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

FreeToken 安装指南PyPI、源码与 Nightly Wheels 三种方式全解析FreeToken 是一套面向边缘设备的 MoE 模型推理引擎目标是在消费级硬件上以交互速度运行大规模模型。本文基于仓库 docs/install.md 整理完整的安装流程覆盖环境要求、PyPI 二进制安装、源码编译、Nightly 滚动构建与安装验证并结合仓库中的pyproject.toml、setup.py、内核工具链检查与install.sh脚本说明每条命令背后的依赖约束与编译原理。读完本文你将能根据自身环境选择最合适的安装方式并独立完成 FreeToken 服务的启动与接口验证。环境要求RequirementsFreeToken 对运行环境有明确且严格的要求安装前请先核对项目要求说明操作系统Linux x86_64官方支持的运行时平台GPUNVIDIA GPU推理依赖 CUDA 加速驱动driver r580CUDA 13驱动版本决定可用的 CUDA 运行时能力Python 3.10与 pyproject.toml 中requires-python 3.10一致包管理器uv推荐普通pipvenv亦可但 uv 解析更快、索引管理更可控值得注意的一点是版本约束的上限即下限设计哲学pyproject.toml中所有核心依赖都采用floorlast-verified, ceilingnext-major的区间写法例如torch2.11,2.12、triton3.6.0、transformers5.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 索引上的陈旧公共依赖如packaging24.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 中定义的一个组合 extrafi [flashinfer-python[cu13]0.6,0.7] sgl [sglang-kernel0.4.5] accel [freetoken[fi,sgl]]即accel同时引入两套原生融合内核包flashinfer-python[cu13]提供 FlashInfer 注意力内核cu13 表示匹配 CUDA 13 构建sglang-kernel0.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编译扩展名源文件用途freetoken.kernel._pinned_tensorpinned_tensor.cpp链接 CUDA runtime APIcudart的固定内存张量支持freetoken.kernel._cpu_moecpu_moe_ext.cppCPU 计算 MoE 执行器--moe-backend cpu路径使用 AVX512BF16/AVX512F 微内核加运行时__builtin_cpu_supports分派单二进制保持可移植freetoken.kernel._ple_storeple_store_ext.cpp磁盘行存储--ple-backend disk目前仅 Linux 构建sys.platform linux条件编译这些扩展需要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_MISMATCH1 to override.FREETOKEN_ALLOW_CUDA_MISMATCH1是官方提供的逃生舱环境变量设置后跳过该检查该文件位于 python/freetoken/kernel/_toolchain.py供setup.py与 kernel-cache 构建后端按路径独立加载不依赖 freetoken 包本身。方法三Nightly wheels滚动构建FreeToken 每天都会将main分支构建为一对 wheel发布到滚动的nightlyrelease 上freetoken运行时 wheelCPython 3.12、Linux x86_64 构建freetoken-kernel-cachewheel包含 FreeToken 自有 CUDA 内核的预编译版本。两者必须配套安装。参考命令URL 从 nightly release 页面获取uv pip install \ freetoken[accel] runtime wheel URL \ kernel-cache wheel URL为什么必须钉住 wheel URL 而不是 tagNightly 构建的文件名携带gsha构建戳build stamp每天都变nightlytag 随之移动。文档给出了三条关键警告Pin a wheel URL, never the tagtag 是滚动的直接引用 tag 无法固定到你测试过的那个构建本地 tag 副本会过期git fetch不会更新已存在的本地 taggit 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_JIT1 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 环境配置 → 自检。常用环境变量如下环境变量默认值作用FREETOKEN_WHEEL钉住的 release asset运行时 wheel 的本地路径或 URLFREETOKEN_KERNEL_CACHE_WHEEL自动探测kernel-cache wheel 路径或 URL若未设置且运行时 wheel 为本地文件自动探测同目录兄弟 wheelFREETOKEN_HOME~/.freetoken安装根目录venv 位于$FREETOKEN_HOME/venvFREETOKEN_PY_VERSION3.12venv 使用的 Python 版本必须与 wheel 标签匹配FREETOKEN_BIN_DIR~/.local/binft符号链接目录FREETOKEN_ENV_DIR~/.config/environment.dDesktop 环境配置目录脚本还支持--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:mainft --version打印freetoken version 版本版本号单一来源是 python/freetoken/version.py 中的__version__。第二条命令启动推理服务。从 python/freetoken/server/args.py 可以看到默认监听端口是server_port: int 1919ft 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、checkpointHF 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.mdft各子命令与完整参数参考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 一键安装。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考