FreeToken 支持模型完全指南模型家族、图片输入与 MoE 专家调度策略FreeToken 是一个面向个人硬件消费级 GPU、主机内存与 PCIe 互连的边缘原生 MoEMixture-of-Experts推理引擎其核心目标是把数据中心级别的模型服务搬到桌面上。本文以官方文档 docs/models.md 为骨架完整梳理 FreeToken 当前支持的全部模型家族与已验证的 HF 检查点、各家族图片输入视觉编码器的接入方式与 token 预算语义以及决定 MoE 专家驻留与调度方式的五种策略fused/offload/cpu/hybrid/auto。读完本文你将能依据自己的显存、内存与 PCIe 带宽为任意受支持检查点选择正确的启动参数并理解 FTW 快速加载格式、图片输入与 MoE offload 背后源码级的实现原理。支持的模型与 HF 检查点FreeToken 直接加载 Hugging Face 的 safetensors 检查点ft serve --model path-or-hf-id无需预先转换。下表列出的是**已知良好known-good**的检查点——预编译内核针对它们做过调优同一架构的其它检查点通常也可以工作但不在官方验证范围内。模型HF 检查点DeepSeek-V4deepseek-ai/DeepSeek-V4-Flash-0731GLM-5.3-FlashRedHatAI/GLM-5.3-Flash-NVFP4GLM-5.2nvidia/GLM-5.2-NVFP4GLM-4.7nvidia/GLM-4.7-NVFP4Qwen3.8-Flash-NextQwen/Qwen3.8-Flash-Next-FP8、RadixArk/Qwen3.8-Flash-Next-NVFP4、nvidia/Qwen3.8-Flash-Next-NVFP4Qwen3.6 / Qwen3.5 MoEQwen/Qwen3.6-35B-A3B及-FP8、nvidia/Qwen3.6-35B-A3B-NVFP4、Qwen/Qwen3.5-35B-A3B及-FP8Qwen3.8 / Qwen3.6 denseQwen/Qwen3.8-27B及-FP8、RadixArk/Qwen3.8-27B-NVFP4、Qwen/Qwen3.6-27B及-FP8、nvidia/Qwen3.6-27B-NVFP4Qwen3-MoEQwen/Qwen3-30B-A3BQwen3-VLQwen/Qwen3-VL-8B-Instruct、Qwen/Qwen3-VL-30B-A3B-Instructgpt-ossopenai/gpt-oss-120b、openai/gpt-oss-20bGemma-4google/gemma-4-26B-A4B-it、nvidia/Gemma-4-26B-A4B-NVFP4、google/gemma-4-12B-it、nvidia/Gemma-4-31B-IT-NVFP4等MiniMax-M2.5nvidia/MiniMax-M2.5-NVFP4MiniMax-M3nvidia/MiniMax-M3-NVFP4Muse-Glimmermeta-models/Muse-Glimmer-30B、RedHatAI/Muse-Glimmer-30B-NVFP4从仓库源码看每个家族都在模型注册表 python/freetoken/models/register.py 中登记为一张ModelSpecDeepseekV4ForCausalLM对应 deepseek_v4GlmMoeDsaForCausalLM对应 GLM-5.2glm_moe_dsaGlm5NextForConditionalGeneration对应 GLM-5.3-Flashglm5_nextQwen4ExpForConditionalGeneration对应 Qwen3.8-Flash-Nextqwen4_expdense 与 MoE 的 Qwen3.5/3.6/3.8 统一落在 qwen3_5_moe 包内Qwen3-VL 在 qwen3_vlGemma-4 的gemma4/gemma4_unified两个变体都在 gemma4gpt-oss 在 gpt_oss。注册表通过architectures字段自动识别检查点因此ft serve只需要--model一个必填参数。不同量化的落地方式上表中同一模型往往有 FP8、NVFP4、BF16 等多个 HF 发布FreeToken 按量化配置quantization_config自动选择内核路径例如 NVFP4 专家可由--quant-backend moe.nvfp4指定marlin/b12x/triton之一--nvfp4-backend是已废弃的旧拼写等价于--quant-backend moe.nvfp4...详见 docs/cli.md。量化方案的解析逻辑集中在 layers/quantizationModelSpec中的packed_modules_mapping如把qkv_proj拆回 HF 的q_proj/k_proj/v_proj叶子保证量化配置查表时能找到与 HF 检查点一致的名字。图片输入Image input以下家族默认接受图片输入传--text-model-only可跳过视觉编码器只做纯文本服务。相关 flags 的完整说明见 CLI 参考每个家族用自己的单位解释这些 flagtoken 预算的换算方式不同见下表。家族图片 token 计算--image-min-tokens/--image-max-tokens语义--mm-processor-kwargs示例Qwen3.6两种变体、表内全部权重格式、Qwen3.8-Flash-Next、Qwen3-VL缩放后图片每 32x32 像素 1 个 token动态分辨率以像素面积形式传给size.shortest_edge/longest_edge检查点默认 64 到 16384 token{size: {longest_edge: 1048576}}Gemma-4 26B-A4B、31Bgemma4ViT tower--mm-encoder-weights host下流式加载从 70 / 140 / 280 / 560 / 1120 软 token 预算中取一档每张图在宽高比允许范围内缩放到对应预算最大值会选取落在区间内的最大档位低于 70 启动时直接拒绝最小值无效{max_soft_tokens: 1120}Gemma-4 12Bgemma4_unified线性 patch embedder两种驻留方式下都常驻同上预算每个软 token 对应一个 48x48 超级 patch与 tower 版本一致同上GLM-5.3-Flashglm5_nextViT tower--mm-encoder-weights host下流式加载缩放后图片每 28x28 像素 1 个 token动态分辨率画布零填充到 28 的倍数直接透传为处理器的min_image_tokens/max_image_tokens检查点默认 16 到 8000 token{max_image_tokens: 2048}Muse-Glimmer-30Bwindowed ViT tower--mm-encoder-weights host下流式加载缩放后图片每 28x28 像素 1 个 token宽高比控制在 token 上限内检查点默认 4096 token最大值即上限max_image_tokens最小值无效{max_image_tokens: 1024}MiniMax-M3minimax_m3CLIP 风格 ViT tower--mm-encoder-weights host下流式加载缩放后图片每 28x28 像素 1 个 token动态分辨率以像素面积形式传给size.shortest_edge/longest_edge检查点默认 4 到 576 token{size: {longest_edge: 1048576}}视觉编码器在源码中的登记与接入编码器塔以EncoderSpec登记在ModelSpec.encoders上kind 为vision/audio即--mm-disable可关闭的种类并在register.py中挂接对应的多模态处理器Qwen 系共用QwenVLMMProcessormm/processors/qwen_vl.pyGemma-4 用Gemma4MMProcessor/Gemma4UnifiedMMProcessormm/processors/gemma4.pyGLM-5.3-Flash 用Glm5NextMMProcessormm/processors/glm5_next.pyMiniMax-M3 与 Muse-Glimmer 各有独立处理器。这些处理器把上表的 token 预算语义翻译成各家的图像缩放与 patch 划分逻辑。--mm-encoder-weights host默认表示编码器塔的块权重从 pinned host bank 每次两块地流式送入 GPU计算与拷贝重叠GPU 只保留两块而非整座塔gpu则让权重常驻显存。没有块堆栈的编码器无论哪种方式都常驻。GET /v1/stats会以model.input_modalities[text]或[text, image]上报服务器实际接受的输入模态客户端无需解析检查点配置即可决定是否开放附件入口docs/cli.md。MoE 策略专家驻留与调度MoE 模型的专家权重很大不可能全部常驻消费级显存。FreeToken 通过ft serve --moe-strategy {auto,fused,offload,cpu,hybrid}控制专家住哪里、miss 时怎么办--moe-backend是已废弃的旧拼写在 engine/config.py 的EngineConfig.__post_init__中会把它折叠进moe_strategyfused— 所有专家常驻 GPU需要足够的显存永远不会被自动选中。offload— 专家存放在主机 RAMpinned host banksGPU 上维护一个专家槽位的 LRU 缓存缓存 miss 时通过 PCIe 流式取回。cpu— miss 的专家不取回 GPU而是直接在 CPU 上用主机内存计算。hybrid— 每个 step 一部分 miss 走 PCIe 取回其余在 CPU 计算两者重叠执行。需要在每台机器上跑一次ft bench bw校准拆分比例。auto— dense 模型恒定为fusedMoE 模型解析为offload当存在ft bench bw的缓存 profile 且推荐 hybrid 时升级为hybrid。策略集合在 python/freetoken/moe/init.py 中定义为MOE_STRATEGIES (fused, offload, cpu, hybrid)offload/cpu/hybrid同属 offload 家族OFFLOAD_MOE_STRATEGIES。源码视角offload 家族如何工作专家 bank 与 LRU 槽位缓存offload_cache.py 中的OffloadMoeCache以cache_policylru在 GPU 上维护专家槽位并记录每个 (layer, expert) 的最近活跃 stepexpert_recency供 hybrid 的逐层抓取上限挑选最活跃的 miss 先取。缓存大小由--moe-cache-size槽位数/--moe-cache-rate专家总数占比/--moe-cache-auto按空闲显存自动推导三者互斥指定offload 家族默认开启 auto由 engine/cache_budget.py 的resolve_moe_cache_auto统一求解专家槽位与 KV page 的显存划分。最小缓存约束engine.py 中的_require_offload_cache_size强制缓存至少每层每专家一个槽位太小会直接报错——这是避免 offload 空转的关键保护。CPU 层拆分--moe-cpu-layers与--moe-strategy offload组合时可以把指定 MoE 层的 decode 放到 CPU 执行_resolve_cpu_layers--moe-strategy cpu则所有层都在 CPU。该参数仅接受 CPU 执行器能服务的专家格式bf16、nvfp4、mxfp4fp8 专家无法使用docs/cli.md。hybrid 的自动决策auto升级到 hybrid 依赖 moe/bench_profile.py 的load_backend_recommendation它读取ft bench bw写入的 profile按 GPU UUID 存放于~/.cache/freetoken/benchbw/gpu-uuid.json按专家格式 GPU 键控硬件不匹配时直接忽略。只有当 CPU 带宽超过 PCIe 带宽达到--threshold默认 2.0倍才推荐 hybrid统一内存设备GB10/DGX Spark、Jetson没有 host/device 边界会直接跳过该升级逻辑并默认fused因为此时 offload 家族只会引入无意义的搬运。用 ft bench bw 校准本机ft bench bw用真实的 cpu/offload MoE 内核测量主机内存与 PCIe 的带宽并把 profile 交给--moe-strategy auto与--moe-hybrid-max-fetch -1读取ft bench bw # 每块 GPU 跑一次即可 ft bench bw --dtype nvfp4,bf16 # 只测你实际服务的格式 ft bench bw --gpu 1 # 指定 GPUUUID 或 nvidia-smi 索引同 ft serve注意事项NotesFTW 转换是可选的ft checkpoint 把 HF 检查点预先转换为 FreeToken 的 FTW 快速加载格式ft serve --model会自动探测 FTW 目录也接受原始 HF 目录或 HF repo id。旧版 FTW 兼容性量化重构之前构建的 FTW 可能加载失败受影响检查点与修复工具见 FTW 修复指南。修复脚本 scripts/ftw_hotfix.py 按字节范围只下载缺失的张量从不下载整个检查点且能在中断后安全续跑每步原子替换 index。图片能力缺失的 FTW在某个家族支持图片输入之前转换的 FTW 不含视觉编码器ft serve会拒绝加载它除非以--text-model-only或--mm-disable vision启动解决办法是用ft checkpoint重新转换或通过 scripts/ftw_hotfix.py 就地补齐编码器。加载侧对缺视觉编码器的判定在 models/weight.py 的ftw_lacks_vision中实现。DeepSeek-V4 的目录结构要求检查点必须保留inference/config.json子目录——权威的模型参数从那里读取对应 register.py 中DeepseekV4ForCausalLM的特殊checkpoint_roots映射。Qwen3.8-Flash-Next 的 PLE 表该模型把 47.7 GiB 的 PLE n-gram 表钉在主机 RAMple_backendpinned见 engine/config.py启动时需要预留足够的主机内存。快速上手示例# 用 Qwen3.6-35B-A3BMoE自动选择 offload/hybrid启动服务 ft serve --model Qwen/Qwen3.6-35B-A3B # 在无显存压力的机器上让专家全部常驻 GPU ft serve --model Qwen/Qwen3.6-35B-A3B --moe-strategy fused # 先用 benchbw 校准本机再让 auto 决定是否升级 hybrid ft bench bw --dtype nvfp4,bf16 ft serve --model nvidia/Qwen3.6-35B-A3B-NVFP4 # 多模态模型只做文本服务省下视觉编码器的显存给 KV/专家池 ft serve --model Qwen/Qwen3-VL-8B-Instruct --text-model-only # 限制单张图片的 token 预算并调整 GLM-5.3-Flash 的视觉处理器 ft serve --model RedHatAI/GLM-5.3-Flash-NVFP4 --image-max-tokens 2048至此你可以依据模型家族dense 还是 MoE、是否多模态、可用显存与主机内存、以及ft bench bw校准出的 CPU/PCIe 带宽比为受支持检查点组合出正确的启动参数遇到旧 FTW 加载失败时也知道该用ft checkpoint重转还是用scripts/ftw_hotfix.py就地修复。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
