FreeToken 安装指南：PyPI、源码与 Nightly Wheels 三种方式全解析

FreeToken 是一套面向边缘设备的 MoE 模型推理引擎，目标是在消费级硬件上以交互速度运行大规模模型。本文基于仓库 docs/install.md 整理完整的安装流程，覆盖环境要求、PyPI 二进制安装、源码编译、Nightly 滚动构建与安装验证，并结合仓库中的pyproject.toml、setup.py、内核工具链检查与install.sh脚本，说明每条命令背后的依赖约束与编译原理。读完本文，你将能根据自身环境选择最合适的安装方式，并独立完成 FreeToken 服务的启动与接口验证。

环境要求（Requirements）

FreeToken 对运行环境有明确且严格的要求，安装前请先核对：

值得注意的一点是版本约束的"上限即下限"设计哲学：pyproject.toml中所有核心依赖都采用floor=last-verified, ceiling=next-major的区间写法（例如torch>=2.11,<2.12、triton==3.6.0、transformers>=5.16,<5.17），注释中明确指出"这些区间就是契约（these ranges are the contract; there is no lockfile）"。这意味着项目不依赖 lockfile 锁版本，而是靠精确的版本区间保证依赖可解析且不静默升级破坏兼容性。

另外，由于 torch 2.11.0 的 PyPI wheel 本身就是 cu130 构建，pyproject.toml 中通过[tool.uv.sources]为 torch 单独指定了pytorch-cu130索引（explicit = true将该索引作用域限定在 torch 一个包上），避免 pytorch 索引上的陈旧公共依赖（如packaging<=24.1）在 uv 的 first-index 策略下遮蔽 PyPI 的同名包。若使用 uv 安装，这些索引配置会自动生效。

方法一：从 PyPI 安装（推荐）

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

两条命令各司其职：第一条创建隔离虚拟环境（默认.venv目录）并激活；第二条从 PyPI 安装 FreeToken 运行时及accel附加依赖。

accel 附加依赖是什么

accel是 pyproject.toml 中定义的一个组合 extra：

fi = ["flashinfer-python[cu13]>=0.6,<0.7"] sgl = ["sglang-kernel==0.4.5"] accel = ["freetoken[fi,sgl]"]

即accel同时引入两套原生融合内核包：

• flashinfer-python[cu13]：提供 FlashInfer 注意力内核，cu13 表示匹配 CUDA 13 构建；
• sglang-kernel==0.4.5：提供 SGLang 的融合内核，版本被精确锁定（注释说明它链接了仅 torch 2.11 才有的 libtorch 符号，因此必须锁死）。

安装accel后，运行时优先走这两套原生快速路径。如果不安装它们，引擎会回退到freetoken.kernel.triton下的纯 Triton 内核与 Triton 注意力后端——功能可用但非全速。pyproject.toml中的注释明确写道："Installfreetoken[accel]for the full native fast path."

JIT 编译的前提：nvcc 在 PATH 上

从 PyPI 安装的包不含预编译的 CUDA 内核二进制。文档明确说明：

CUDA kernels are JIT-compiled on first use, need a CUDA 13 toolkit withnvccon PATH.

因此采用此方法时，机器上必须装有 CUDA 13 toolkit 且nvcc位于 PATH，否则首次使用内核时会因缺少编译器而失败。这与方法三（Nightly wheels）形成对比——后者自带预编译内核，对 CUDA toolkit 的依赖更弱。

方法二：从源码安装

git clone https://github.com/FlashML-org/FreeToken.git && cd FreeToken uv venv && source .venv/bin/activate uv pip install -e ".[accel]"

源码安装以可编辑模式（-e）安装当前 checkout，适合开发调试与跟进最新提交。这里的.指向仓库根目录，[accel]与 PyPI 方式使用同一套 extra 定义。

源码安装会编译什么

从源码安装时，setup.py 会构建三个 C++ 扩展（均由 torch 的BuildExtension编译）：

编译这些扩展需要CUDA_HOME环境变量——setup.py 中_cuda_runtime_paths()在CUDA_HOME is None时直接抛出RuntimeError("CUDA_HOME is required ...")。因此源码安装前请确保 CUDA toolkit 已安装且CUDA_HOME已导出。

构建前的工具链一致性校验

源码安装过程中，setup.py 会通过_check_toolchain()加载 python/freetoken/kernel/_toolchain.py 并调用其中的check_nvcc_matches_torch()，该校验逻辑是：

• 读取 torch 自带的 CUDA 主版本（torch.version.cuda）；
• 读取nvcc --version的 release 主版本；
• 若两者主版本不一致，直接拒绝编译——因为 nvcc 编译出的二进制会链接libcudart.so.<nvcc major>，而运行时只有 torch wheel 自带的 CUDA runtime 保证可加载。

报错信息形如：

nvcc 12.4 would build kernels linking libcudart.so.12, but torch 2.11.0 ships CUDA 13.0 (libcudart.so.13). Install a CUDA 13.x toolkit, or set FREETOKEN_ALLOW_CUDA_MISMATCH=1 to override.

FREETOKEN_ALLOW_CUDA_MISMATCH=1是官方提供的逃生舱环境变量，设置后跳过该检查（该文件位于 python/freetoken/kernel/_toolchain.py，供setup.py与 kernel-cache 构建后端按路径独立加载，不依赖 freetoken 包本身）。

方法三：Nightly wheels（滚动构建）

FreeToken 每天都会将main分支构建为一对 wheel，发布到滚动的nightlyrelease 上：

1. freetoken运行时 wheel：CPython 3.12、Linux x86_64 构建；
2. freetoken-kernel-cachewheel：包含 FreeToken 自有 CUDA 内核的预编译版本。

两者必须配套安装。参考命令（URL 从 nightly release 页面获取）：

uv pip install \ "freetoken[accel] @ <runtime wheel URL>" \ "<kernel-cache wheel URL>"

为什么必须钉住 wheel URL 而不是 tag

Nightly 构建的文件名携带+g<sha>构建戳（build stamp），每天都变，nightlytag 随之移动。文档给出了三条关键警告：

• Pin a wheel URL, never the tag：tag 是滚动的，直接引用 tag 无法固定到你测试过的那个构建；
• 本地 tag 副本会过期：git fetch不会更新已存在的本地 tag，git fetch --tags也拒绝覆盖它；
• 强制刷新方式：如需刷新本地nightlytag，使用git fetch --force origin tag nightly。

此外，wheels 旁附带的engine-linux_x86_64.json文件标明了当前 wheel 对，供脚本化安装自动解析。仓库中 scripts/ci/fetch-nightly-pair.sh 正是围绕这一机制编写的获取脚本，可在 CI 或自动化环境中复用它来拉取并安装最新 nightly 对。

kernel-cache wheel 的内容与作用

freetoken-kernel-cache是 freetoken 的伴生 wheel（详见 freetoken-kernel-cache/README.md），内部按内核目录组织：

freetoken_kernel_cache/ jit_cache/ freetoken__store_1024_128_1_false/ freetoken__store_1024_128_1_false.so

运行时，freetoken.kernel.utils.load_jit()与load_aot()会先查找freetoken_kernel_cache.get_jit_cache_dir()，优先加载<jit_cache>/<kernel_name>/<kernel_name>.so，未命中才回退到 nvcc JIT 编译。这意味着安装 kernel-cache wheel 后，常见内核路径直接加载.so，不再需要 nvcc 现场编译——这也是 nightly 方式比 PyPI 方式对 CUDA toolkit 依赖更弱的原因。

注意：即便安装了 kernel-cache，若遇到未被覆盖的内核变体或 cache wheel 与运行时不匹配，仍需要 nvcc 作为 JIT 回退。可用FREETOKEN_DISABLE_JIT=1 ft serve --model <path>强制禁用运行时 JIT——开启后任何 cache miss 都会立即失败而非现场编译，常用于发布验证场景（见 freetoken-kernel-cache/README.md）。

更省事的选择：install.sh 一键安装

仓库根目录的 install.sh 脚本封装了上述机制，适合桌面应用集成与自动化部署。它依次完成：引导 uv → 解析/构建运行时 wheel → 解析 kernel-cache wheel → 校验 NVIDIA 驱动与 nvcc → 在受管 venv 中安装 → 建立ft符号链接与 Desktop 环境配置 → 自检。

常用环境变量如下：

脚本还支持--yes/-y非交互模式（FreeToken Desktop 的应用内安装器即使用此模式），并在安装结束时输出 venv 中ft的绝对路径与立即生效的export FREETOKEN_FT_BIN=...提示。值得一提的是，脚本的安装列表除freetoken[accel]外还包含flashinfer-cubin与flashinfer-jit-cache（来自 flashinfer 官方索引），这两者提供多架构预编译的 FlashInfer 内核，使驱动-only 机器（无 CUDA toolkit）也能完成安装，代价是一次约 2 GiB 的下载。

验证安装

安装完成后，按以下步骤验证整条链路是否打通：

source .venv/bin/activate ft --version ft serve --model ~/path/to/Qwen3.6-35B-A3B

第一条命令输出版本号：ft入口由 pyproject.toml 的[project.scripts]定义（ft = "freetoken.cli:main"），ft --version打印freetoken version <版本>（版本号单一来源是 python/freetoken/version.py 中的__version__）。

第二条命令启动推理服务。从 python/freetoken/server/args.py 可以看到默认监听端口是server_port: int = 1919，ft serve就绪后日志会出现API server is ready to serve on 127.0.0.1:1919。

然后在另一个终端发送一个 Chat Completion 请求：

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":"hi"}]}'

返回正常即说明运行时、模型加载与 OpenAI 兼容 API 全部就绪。ft除serve外还提供shell（终端对话）、ctl（查询管理运行中的服务）、daemon、launch、checkpoint（HF safetensors 转 FTW 格式）与bench（如ft bench bw对比 CPU 与 PCIe 带宽并挑选 MoE 后端）等子命令（见 python/freetoken/cli.py）。

安装完成之后

服务验证通过后，下一步可参考：

• docs/quickstart.md：启动服务、调用 OpenAI/Anthropic API、ft shell终端对话与ft launch接入 coding agent 的完整上手流程；
• docs/cli.md：ft各子命令与完整参数参考（dtype、注意力与 MoE 后端、缓存大小、工具调用与推理解析器等均可通过命令行覆盖）；
• docs/models.md：支持的模型清单与量化格式（MXFP4、NVFP4、FP8、BF16 等）；
• docs/ftw-hotfix.md：旧 FTW 检查点修复指南。

安装方式速查：有 CUDA 13 toolkit 且追求最新功能，选 PyPI 或源码安装（内核首次使用 JIT 编译）；希望开箱即用、不想在运行时编译内核，选 Nightly wheels（预编译 kernel-cache 伴生 wheel）；桌面应用或自动化部署，直接用 install.sh 一键安装。