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-Experts（MoE）推理引擎，专为在消费级 GPU、家用台式机上运行大规模开源 MoE 模型（如 Qwen3.6-35B-A3B、DeepSeek-V4 系列等）而设计。读完本文，你将掌握四条核心技能：用ft serve一键启动 OpenAI/Anthropic 兼容的本地推理服务、用curl验证与调用 API、用ft shell在终端里直接聊天，以及用ft launch把主流编码 Agent（Claude Code、Codex、OpenCode 等）无缝接到本地服务器上。

1. 前置条件：安装并验证 FreeToken

Quickstart 默认 FreeToken 已经安装完成。完整的安装方式（PyPI、源码、nightly wheels 三种途径）见 安装指南。简单来说，推荐的安装方式是：

uv venv && source .venv/bin/activate uv pip install "freetoken[accel]"

安装完成后，用下面的命令验证环境就绪：

ft --version

注意：ft --version是 torch-free 的（不加载深度学习框架），可快速确认 CLI 本身可用；nightly 构建的版本号会带有+g<sha>构建标记。所有子命令均支持--help查看参数。

从源码看，ft是 FreeToken 的唯一 CLI 入口，命令分发逻辑集中在 python/freetoken/cli.py：serve、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 查看正在服务的模型

先查询服务器当前暴露了哪些模型 id：

curl 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/models
• Anthropic 兼容协议：/v1/messages、/v1/messages/count_tokens

因此，任何以 OpenAI 或 Anthropic 为目标的客户端库，只需把 base URL 指向本服务器即可直接使用，无需修改业务代码。这也是后续ft launch能一键接入各类编码 Agent 的协议基础。

4. 深入理解“全自动解析”背后的可调参数

虽然默认配置开箱即用，但了解自动解析的逻辑有助于在资源受限时手动干预。下表总结了 quickstart 提及的“自动解析项”对应的可调参数（完整清单见 CLI 参考）：

4.1 服务器与运行时参数

4.2 KV cache 与显存参数

4.3 MoE offload 参数（关键调优点）

FreeToken 的核心卖点是 CPU/GPU 协同执行 MoE，相关策略详见 docs/models.md。常用参数：

4.4 API 行为参数

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 shell

ft 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. 接入编码 Agent：ft launch

这是 quickstart 的压轴功能——让本地推理服务直接成为编码 Agent 的推理后端：

ft launch claude # claude / codex / dsh / hermes / openclaw / opencode

ft launch会依次完成三件事（对应 python/freetoken/launch.py 的实现逻辑）：

1. 发现服务模型：通过/v1/models自动发现正在服务的模型 id，并读取/v1/stats获取上下文窗口与输入模态（text / image）；
2. 写入 Agent 的 provider 配置：为该 Agent 生成指向本服务器的 provider/模型配置（例如 Codex 的~/.codex/config.tomlprofile、Claude Code 的环境变量、OpenCode 的 provider 配置、Hermes 的config.yaml、dsh 的 settings 文件等）；
3. 安装并启动 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的常用选项：

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 转换为 FTW（FreeToken 自包含快速加载格式），转换后的目录直接交给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