FreeToken 快速上手：用 ft serve / ft shell / ft launch 在本地跑起 MoE 大模型服务

FreeToken 快速上手用 ft serve / ft shell / ft launch 在本地跑起 MoE 大模型服务【免费下载链接】FreeTokenFreeToken brings datacenter-scale model serving to your desktop. Run massive models locally, fast and efficiently.项目地址: https://gitcode.com/GitHub_Trending/fr/FreeToken本文是 FreeToken 官方 docs/quickstart.md 的完整实战化展开。FreeToken 是一个面向边缘/桌面硬件的 Mixture-of-ExpertsMoE推理引擎专为在消费级 GPU、家用台式机上运行大规模开源 MoE 模型如 Qwen3.6-35B-A3B、DeepSeek-V4 系列等而设计。读完本文你将掌握四条核心技能用ft serve一键启动 OpenAI/Anthropic 兼容的本地推理服务、用curl验证与调用 API、用ft shell在终端里直接聊天以及用ft launch把主流编码 AgentClaude Code、Codex、OpenCode 等无缝接到本地服务器上。1. 前置条件安装并验证 FreeTokenQuickstart 默认 FreeToken 已经安装完成。完整的安装方式PyPI、源码、nightly wheels 三种途径见 安装指南。简单来说推荐的安装方式是uv venv source .venv/bin/activate uv pip install freetoken[accel]安装完成后用下面的命令验证环境就绪ft --version注意ft --version是 torch-free 的不加载深度学习框架可快速确认 CLI 本身可用nightly 构建的版本号会带有gsha构建标记。所有子命令均支持--help查看参数。从源码看ft是 FreeToken 的唯一 CLI 入口命令分发逻辑集中在 python/freetoken/cli.pyserve、shell、ctl、daemon、launch、checkpoint、bench分别路由到对应的实现模块。本文聚焦 quickstart 提到的三个最常用命令serve、shell、launch。2. 启动第一个推理服务器ft serve启动一个本地 API 服务器只需一条命令ft serve --model ~/models/Qwen3.6-35B-A3B--model参数不仅接受本地目录也接受 Hugging Face 仓库 id例如ft serve --model Qwen/Qwen3.6-35B-A3B # 假设该 repo id 存在且与本地目录等价2.1 全自动配置从 checkpoint 与 GPU 推断一切这是 FreeToken 最核心的设计之一除了--model其余几乎所有运行参数都会自动解析。--model之外的东西——权重 dtype、attention 后端、MoE 后端、缓存大小KV cache 与专家缓存、工具调用解析器、推理reasoning解析器——都从 checkpoint 内容和当前 GPU 硬件自动推导出来见 CLI 参考。这意味着第一次启动通常不需要任何调优参数。2.2 如何判断服务器就绪服务器启动过程中会打印调度器状态等日志当日志出现下面这一行时说明 API 服务已经可以接收请求API server is ready to serve on 127.0.0.1:1919这行日志的实现在 python/freetoken/server/api_server.py默认绑定地址是127.0.0.1默认端口是1919。3. 发送请求验证服务3.1 查看正在服务的模型先查询服务器当前暴露了哪些模型 idcurl http://127.0.0.1:1919/v1/models返回结果中会包含模型 id默认取--model的 basename即Qwen3.6-35B-A3B。随后所有请求都要使用这个 id 作为model字段。3.2 发起一次流式对话补全curl http://127.0.0.1:1919/v1/chat/completions \ -H Content-Type: application/json \ -d { model: Qwen3.6-35B-A3B, messages: [{role: user, content: What is a Mixture-of-Experts model?}], max_tokens: 256, stream: true }该请求完全遵循 OpenAI Chat Completions 协议stream: true开启流式返回。3.3 协议兼容性OpenAI Anthropic 双协议FreeToken 同时提供两套 API见 CLI 参考 中ft serve的说明OpenAI 兼容协议/v1/chat/completions、/v1/responses、/v1/modelsAnthropic 兼容协议/v1/messages、/v1/messages/count_tokens因此任何以 OpenAI 或 Anthropic 为目标的客户端库只需把 base URL 指向本服务器即可直接使用无需修改业务代码。这也是后续ft launch能一键接入各类编码 Agent 的协议基础。4. 深入理解“全自动解析”背后的可调参数虽然默认配置开箱即用但了解自动解析的逻辑有助于在资源受限时手动干预。下表总结了 quickstart 提及的“自动解析项”对应的可调参数完整清单见 CLI 参考4.1 服务器与运行时参数Flag默认值含义--host127.0.0.1绑定地址--port1919绑定端口--gpuGPU 0使用的 GPUnvidia-smi -L输出的 UUID 或索引--max-running-requests4最大并发运行请求数--max-output-tokens32768请求未指定时默认的输出预算--max-seq-len-override来自 checkpoint最大序列长度--max-prefill-length8192chunked prefill 的块大小token 数--cuda-graph-max-bs,--graph等于 max running requests捕获为 CUDA graph 的最大 batch size--decode-log-interval40每 N 个 decode 步打印一次调度器状态行4.2 KV cache 与显存参数Flag默认值含义--memory-ratio0.9引擎可使用的空闲 VRAM 比例权重 MoE 缓存 KV--num-pages/--num-tokensautoKV 容量覆盖值页/ token二者互斥auto 表示按权重和 MoE 缓存之外的剩余显存自动分配--page-size1KV 页大小DSV4 强制 128TRTLLM 后端要求 16/32/64SWA 模型要求 1--cache-typeradixradix前缀复用自动选择 SWA/GDN 感知变体或naive--attention-backend,--attnautotrtllm/fi/fa/triton/dsv4_sparse/dsa支持prefill,decode成对指定4.3 MoE offload 参数关键调优点FreeToken 的核心卖点是 CPU/GPU 协同执行 MoE相关策略详见 docs/models.md。常用参数Flag默认值含义--moe-strategyautofused/offload/cpu/hybridauto 默认 offload若存在ft bench bw生成的带宽画像则自动选 hybrid--moe-cache-size/--moe-cache-rate/--moe-cache-autoautoGPU 专家缓存大小槽位数 / 全部专家的比例 / 按剩余显存自动分配互斥--kv-reserve-tokens8192--moe-cache-auto填充专家前保留的 KV token 下限--moe-cpu-threads物理核心数cpu/hybrid executor 的 CPU 工作线程数--moe-cpu-layers全部在 GPU配合offload哪些 MoE 层在 CPU 上 decode3,7,11、数量、比例或auto--moe-hybrid-max-fetchauto配合hybrid每层每步最多经 PCIe 取回的专家数其余在 CPU 计算--disable-moe-prefill-overlap重叠开启关闭 prefill 的双缓冲拷贝重叠4.4 API 行为参数Flag默认值含义--sampling-defaultsmodel未指定的采样参数从 checkpoint 的generation_config.json填充none为框架默认--tool-call-parserauto工具调用格式解析器按模型家族自动推断--reasoning-parserauto将 chain-of-thought 拆分为reasoning_contentoff关闭--enable-cache-reportoff在响应的 usage 块中报告前缀缓存命中情况5. 选择 GPU索引还是 UUID在一台有多张显卡的机器上例如同时装有 RTX 5090 和 RTX 3060 Ti先列出 GPU$ nvidia-smi -L GPU 0: NVIDIA GeForce RTX 3060 Ti (UUID: GPU-2f3a9b1c-8d7e-4a05-b6c1-0e5f9a3d7b42) GPU 1: NVIDIA GeForce RTX 5090 (UUID: GPU-9e8d7c6b-5a49-4f13-8207-c1b0a4e6d3f5)然后二选一指定目标卡ft serve --model ... --gpu 1 # 按 nvidia-smi 索引 —— 即 RTX 5090 ft serve --model ... --gpu GPU-9e8d7c6b # 按 UUID唯一前缀即可6. 终端里直接聊天ft shellft shell提供两种用法分别对应 attach 模式与一体化模式ft shell # attach 到上面启动的服务器 ft shell --model ~/models/Qwen3.6-35B-A3B # 单进程内部启动引擎并聊天要点attach 模式默认连接http://127.0.0.1:1919可用--server URL覆盖。attach 模式不需要 GPU因此也能驱动另一台机器上的服务器——只要把--server指向远端地址即可。一体化模式--model与ft serve相同适合快速体验进程内完成启动引擎 交互聊天。进入 shell 后输入/help可查看内置命令列表例如/think、/cache、/reset详见 CLI 参考。7. 接入编码 Agentft launch这是 quickstart 的压轴功能——让本地推理服务直接成为编码 Agent 的推理后端ft launch claude # claude / codex / dsh / hermes / openclaw / opencodeft launch会依次完成三件事对应 python/freetoken/launch.py 的实现逻辑发现服务模型通过/v1/models自动发现正在服务的模型 id并读取/v1/stats获取上下文窗口与输入模态text / image写入 Agent 的 provider 配置为该 Agent 生成指向本服务器的 provider/模型配置例如 Codex 的~/.codex/config.tomlprofile、Claude Code 的环境变量、OpenCode 的 provider 配置、Hermes 的config.yaml、dsh 的 settings 文件等安装并启动 Agent若 Agent CLI 未安装会自动安装然后以本服务器为后端启动。几个值得注意的细节均可在 python/freetoken/launch.py 中验证清理云 API 密钥启动子进程时会从环境中清除ANTHROPIC_API_KEY、OPENAI_API_KEY、GEMINI_API_KEY等云厂商密钥防止 Agent 静默回退到付费端点图像能力声明当/v1/stats报告model.input_modalities含image时生成的配置会把模型声明为支持图像Codex、OpenCode、OpenClaw、dsh 只有在声明后才允许其图像工具发送附件--dry-run预览ft launch claude --dry-run只打印将要写入的配置变更和将执行的命令不触碰任何文件适合先审查再落地。ft launch的常用选项Flag含义--server URL指向的服务器默认http://127.0.0.1:1919--dry-run打印计划变更与命令不做任何修改-y,--yes自动批准安装/配置提示--config只安装并配置不启动 Agent--install-only仅安装 Agent CLI无需服务器--force-reinstall强制重新运行 Agent 安装器-- args原样透传给 Agent 的额外参数8. 进阶服务运维与模型转换quickstart 之外与日常使用紧密相关还有两个命令完整参考见 CLI 参考ft ctl通过 HTTP 查询和管理运行中的服务器例如ft ctl health服务器状态、模型、加载进度、ft ctl stats吞吐、延迟、VRAM、池占用率、ft ctl cache缓存池表、ft ctl generate无 chat template 的原始补全冒烟测试、ft ctl requests近期请求环。其中ft ctl cache --moe N --kv N可在不重启的情况下动态调整池大小。ft checkpoint把 Hugging Face safetensors checkpoint 转换为 FTWFreeToken 自包含快速加载格式转换后的目录直接交给ft serve --model使用。旧版本 FTW 文件可用 scripts/ftw_hotfix.py 修复详见 docs/ftw-hotfix.md。ft bench bw每块 GPU 执行一次 CPU vs PCIe 带宽基准使用真实的 cpu/offload MoE kernel结果写入~/.cache/freetoken/benchbw/gpu-uuid.json供ft serve --moe-strategy auto和--moe-hybrid-max-fetch -1在启动时读取以决定 hybrid/offload 策略。9. 总结一条命令打通“本地服务 → 终端聊天 → 编码 Agent”回顾整个 Quickstart 的脉络FreeToken 的设计目标非常清晰把数据中心级的 MoE 服务能力压缩到一条命令里。ft serve --model path-or-hf-id一键启动双协议OpenAI Anthropic兼容的本地推理服务dtype、attention/MoE 后端、缓存尺寸、解析器全部自动解析curl /v1/models/v1/chat/completions即可完成协议级验证ft shell提供免 GPU 的 attach 模式与单进程模式两种聊天体验ft launch agent把 Claude Code、Codex、OpenCode、OpenClaw、Hermes、dsh 等主流编码 Agent 直接指向本地服务器并主动清空云密钥避免付费回退。至此你已经可以在自己的硬件上以分钟级的时间跑起一个可用的本地 MoE 推理服务并接入真实世界的编码与工具调用工作流。更深入的参数调优、受支持模型清单与各 MoE 策略的取舍请继续阅读 CLI 参考 与 支持模型。【免费下载链接】FreeTokenFreeToken brings datacenter-scale model serving to your desktop. Run massive models locally, fast and efficiently.项目地址: https://gitcode.com/GitHub_Trending/fr/FreeToken创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考