FreeToken 部署 Qwen3.6-35B-A3B-NVFP4 操作计划（16G+32G）

本文是一份给 AI Agent 执行的部署操作计划。硬件：RTX5060Ti 16GB VRAM + 整机 32GB 物理内存，WSL2 Ubuntu 环境。目标：本地代码开发 + Claude Code / OpenClaw Agent 接入，提供 OpenAI 兼容 API 服务。

模型来源：https://huggingface.co/nvidia/Qwen3.6-35B-A3B-NVFP4（国内镜像 hf-mirror.com）

⚠️ 2026-09-11 实战订正说明：本计划已于同配置机器（RTX5060Ti 16G + 32G 内存 + WSL2 Ubuntu-24.04）完整执行成功，部署实录见《FreeToken 部署 Qwen3.6-35B-A3B-NVFP4 实战总结》。执行中发现本文多处与实际情况不符，已按实战订正，主要修订点：

仓库地址 404：github.com/freetoken/freetoken 不存在，真实仓库为 github.com/FlashML-org/FreeToken（镜像：https://ghproxy.net/https://github.com/FlashML-org/FreeToken.git）

CLI 与参数名：入口是 python -m freetoken（另有 ft），参数是 --attention-backend 而非 --attn

模型格式：ModelScope 的 unsloth 混合量化版（FP8+NVFP4）不被 FreeToken 支持（报 no quant method for moe.fp8_tensor），须改用 NVIDIA 官方 modelopt 版（nvidia/Qwen3.6-35B-A3B-NVFP4，22GB，3 分片）

CUDA 工具链：RTX 5060 Ti（Blackwell SM120）需 CUDA 13 的 nvcc（系统 12.x 不支持 compute_120，报 Unsupported gpu architecture），并需 pip install ninja

显存参数：--moe-cache-size auto 在本机 OOM，须显式 256，并建议 --moe-strategy offload、--num-tokens 4096、--moe-cpu-layers auto

WSL 版本：进程莫名消失 / “显存没用满却 OOM” 时，先升级 WSL ≥ 2.7.13（修复会话回收与 WDDM 显存记账 bug），.wslconfig 建议加 vmIdleTimeout=0

0. 执行目标总览（Agent 先读）

配置 WSL .wslconfig，重启 WSL 生效
从 HuggingFace（国内镜像 hf-mirror.com）下载 NVIDIA 官方 Qwen3.6-35B-A3B-NVFP4 模型
安装 FreeToken 源码与依赖（含 CUDA 13 工具链）
用指定参数启动 python -m freetoken 服务
curl 测试 OpenAI 兼容 API，确认能正常生成代码
全程输出结构化日志，记录 token 速度与是否出现 swap / OOM

1. 环境前置要求

硬件约束（不可变更）

GPU：RTX5060Ti，16GB 显存
RAM：整机 32GB 物理内存（可用内存仅约 22~26GB，系统/浏览器/WSL 会占用 6~10GB）
⚠️ 只能单请求，禁止并发；上下文上限锁定 4096 token（--num-tokens 4096），不要开启 262K 超长上下文
运行环境：WSL2 Ubuntu（不使用原生 Windows，原生 Windows 下 FreeToken 兼容性差）
PCIe：优先 PCIe 4.0 x16；x8 会降低专家权重预取速度

WSL2 系统调优（必须提前配置，防止内存爆掉）

在 Windows 用户目录新建 %UserProfile%\.wslconfig：

[wsl2]
memory=24GB
processors=8
swap=4GB
localhostForwarding=true
vmIdleTimeout=0

说明：限制 WSL 最多占用 24G 内存、swap 仅 4G，防止 WSL 吃掉全部 32G 主机内存。vmIdleTimeout=0 禁止发行版空闲自动关闭（默认 60 秒后会自动关闭导致服务掉线）。修改后执行 wsl --shutdown 重启 WSL 生效。

⚠️ WSL 版本要求：≥ 2.7.13（wsl --version 查看）。旧版本存在两个已知问题：① 由 wsl.exe 启动的后台进程（含 setsid nohup）会在 wsl.exe 断开后被会话回收；② WDDM 显存记账异常导致“显存没用满却 CUDA OOM”。升级 WSL：wsl --update。

系统软件依赖

Ubuntu 22.04 / 24.04
Python 3.10 ~ 3.12
CUDA Toolkit 13.0（RTX 50 系列 Blackwell 需要；系统 12.x 不支持 compute_120）
Git、git-lfs、ninja（pip install ninja）

2. 模型下载

模型名称：Qwen3.6-35B-A3B-NVFP4（总参 35B，激活 3B，NVFP4 量化）。

⚠️ 必须用 NVIDIA 官方 modelopt 版（nvidia/Qwen3.6-35B-A3B-NVFP4，约 22GB，3 个分片）。不要用 ModelScope 的 unsloth/Qwen3.6-35B-A3B-NVFP4（26.5GB，compressed-tensors 混合布局 FP8+NVFP4）——FreeToken 不支持 per-tensor FP8 专家，启动即报 NotImplementedError: no quant method for moe.fp8_tensor。

国内下载（HF 镜像 + 关闭 Xet 协议，否则 401）：

export HF_ENDPOINT=https://hf-mirror.com
export HF_HUB_DISABLE_XET=1
python -c "from huggingface_hub import snapshot_download; snapshot_download('nvidia/Qwen3.6-35B-A3B-NVFP4', local_dir='/home/$USER/models/Qwen3.6-35B-A3B-NVFP4-nvidia')"

⚠️ 必须完整下载所有模型分片文件，不要缺文件；下载完成后校验文件数量与总大小。模型本地路径：/home/$USER/models/Qwen3.6-35B-A3B-NVFP4-nvidia

3. FreeToken 安装

# 1. 安装 git-lfs
sudo apt update && sudo apt install git-lfs
git lfs install

# 2. 拉取 FreeToken 源码（注意：教程原仓库 freetoken/freetoken 为 404，真实仓库如下）
git clone https://ghproxy.net/https://github.com/FlashML-org/FreeToken.git
cd FreeToken

# 3. 安装依赖（建议在 venv 中；PEP 668 限制的系统 Python 需先建虚拟环境）
python3 -m venv ~/freetoken-venv && source ~/freetoken-venv/bin/activate
pip install -e '.[accel]' ninja

# 4. 安装 CUDA 13 工具链（Blackwell 编译必需，见订正说明第 4 条）
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb && sudo apt-get update
sudo apt-get install -y cuda-nvcc-13-0 cuda-cudart-dev-13-0 cuda-cccl-13-0
export CUDA_HOME=/usr/local/cuda-13.0
export PATH=/usr/local/cuda-13.0/bin:$PATH

验证安装成功：python -m freetoken --help 能正常输出参数列表（注：验证命令不是 freetoken --version；CLI 入口是 python -m freetoken，另有 ft 命令）。

4. 模型启动命令（核心，直接执行）

前提：模型文件全部下载完毕，位于 /home/$USER/models/Qwen3.6-35B-A3B-NVFP4-nvidia：

python -m freetoken \
  --model-path /home/$USER/models/Qwen3.6-35B-A3B-NVFP4-nvidia \
  --moe-strategy offload \
  --moe-cache-size 256 \
  --num-tokens 4096 \
  --kv-reserve-tokens 8192 \
  --max-prefill-length 8192 \
  --max-running-requests 1 \
  --moe-cpu-layers auto \
  --attention-backend triton \
  --host 127.0.0.1 --port 8000

参数说明（Agent 阅读，已按实战订正）

参数	值	说明
`--moe-strategy`	`offload`	专家权重驻留系统内存（16.9GB），GPU 只放 dense 权重 + 小缓存，本机唯一可稳定运行的策略
`--moe-cache-size`	`256`	GPU 专家 LRU 缓存槽数。不要用 `auto` 或 2048——本机实测均 CUDA OOM；256 槽可稳定启动
`--num-tokens`	`4096`	KV 实际容量（token）。本机显存约束下的稳定值，上下文上限 4096
`--kv-reserve-tokens`	`8192`	KV 预留上限，保持 8192 即可，禁止再调大（32G 内存扛不住更大上下文）
`--max-prefill-length`	`8192`	prompt 预填充上限 8k
`--max-running-requests`	`1`	仅单并发请求，硬件不足，禁止改为 >1
`--moe-cpu-layers`	`auto`	自动按 pin 预算锁 18 层专家到 CPU decode，其余 GPU 拉取（实测稳定）
`--attention-backend`	`triton`	使用 Triton 注意力内核，N 卡加速（参数名不是 `--attn`）
`--host` / `--port`	`127.0.0.1:8000`	本地 API 服务，OpenAI 兼容接口

服务托管建议：用 systemd 托管服务（/etc/systemd/system/freetoken.service + WSL 配置 [boot] systemd=true），服务不再依赖终端会话，配合 Restart=on-failure 自动拉起，避免终端关闭导致服务掉线。

5. API 接入信息（对接 Claude Code / OpenClaw）

API base url：http://127.0.0.1:8000/v1
model name：Qwen3.6-35B-A3B-NVFP4-nvidia（默认取模型目录尾名）
api key：任意字符串（本地无鉴权，例如 sk-local）

测试 API（新开 WSL 终端执行）：

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-local" \
  -d '{
    "model": "Qwen3.6-35B-A3B-NVFP4-nvidia",
    "messages": [{"role":"user","content":"写一个Python快速排序代码"}]
  }'

返回正常代码输出即代表部署成功。

6. 监控与故障排查规则

✅ 正常现象

首次加载模型很慢：权重从硬盘载入系统内存，冷加载耗时约 2~~3 分钟（内核缓存命中后约 34 秒）；第一轮对话后专家缓存预热，速度稳定在 **22~~24 token/s**（实测）
偶尔 token 掉到 12 左右：专家缓存未命中，属于正常现象
GPU 显存占用看起来很低（<2GB）：这是 offload 架构的正常现象——专家主体在系统内存、按需搬入，物理显存占用不代表性能问题

❌ 异常判断与处理

异常	判断	处理
硬盘持续大量读写（swap 风暴）	内存不足	立刻停止 freetoken 服务，关闭 Windows 后台程序（浏览器、VSCode 其他窗口等）释放主机内存；不要把上下文调大
CUDA OOM 报错	显存溢出	确认 `--max-running-requests 1`，不要并发；不要增大 KV token；若报错显示“显存没用满却 OOM”（如 `Tried to allocate 540 MiB` 但 free 还有 11GB），是 WSL 旧版本 WDDM 显存记账 bug，先 `wsl --update` 升级到 2.7.13+
服务进程莫名消失（无报错）	WSL 会话回收 / 发行版空闲自动关闭	确认 WSL ≥ 2.7.13、`.wslconfig` 含 `vmIdleTimeout=0`；用 systemd 托管服务
模型加载报错 `no quant method for moe.fp8_tensor`	模型格式不对	用了 unsloth 混合量化版，换 NVIDIA 官方 modelopt 版（见第 2 节）
编译报错 `nvcc fatal: Unsupported gpu architecture 'compute_120'`	nvcc 版本过旧	安装 CUDA 13 工具链（见第 3 节），系统 12.x 不支持 Blackwell

停止服务：systemctl stop freetoken（systemd 托管时）或 Ctrl + C 终止进程。

7. 备选降级方案（部署失败时自动切换）

若 FreeToken 持续 swap、频繁 OOM，放弃 FreeToken，切换 Unsloth Desktop 跑稠密 Qwen3-14B。

模型：Qwen3-14B 稠密
优势：无需大量主机内存，GUI 一键部署，稳定 25~35 tok/s，支持 LoRA 微调
劣势：模型能力弱于 Qwen3.6-35B-A3B MoE

8. Agent 日志输出规范

每一步执行必须输出结构化日志，不要只贴大段原始 log。每完成一个阶段，输出固定格式的阶段报告。

阶段报告模板

## 阶段：【阶段名称】
✅ 状态：成功 / ⚠️警告 / ❌失败
📝 简要描述：一句话总结本阶段
💻 执行命令：xxx
📊 资源信息：
- WSL 内存占用：XX GB
- GPU 显存占用(nvidia-smi)：XX GB /16GB
- Swap 使用量：XX GB
🔍 关键输出摘要：提炼重要信息，过滤无关 INFO 日志
🐞 异常：有/无；如有，记录报错原文 + 已采取处理动作

监控指标采集命令（每阶段必跑）

free -h
nvidia-smi --query-gpu=memory.used,memory.total --format=csv

阶段清单（按顺序逐个输出报告）

WSL 配置阶段：修改 .wslconfig，wsl --shutdown 重启后验证 WSL 内存限制生效
模型下载阶段：下载全部模型文件，统计文件数量、总大小，校验分片完整性
FreeToken 源码 & 依赖安装阶段：安装依赖（含 CUDA 13 工具链），python -m freetoken --help 验证
模型加载 & 服务启动阶段：启动服务，等待模型载入完成；记录冷加载耗时、显存/内存占用
API 测试阶段：执行 curl 测试请求；记录 prefill 耗时、decode token 速度（tok/s），输出模型返回内容摘要

服务运行期间持续监控

服务启动成功后，每 30 秒采样一次：

free -h 查看内存 / swap
nvidia-smi 查看显存
观察 FreeToken 输出的 tok/s 解码速度

一旦检测到 swap 持续上涨 > 2GB 或 CUDA OOM → 立即终止 freetoken 进程，标记任务失败，准备切换 Unsloth 备选方案。

最终交付报告（全部任务跑完后输出）

# FreeToken 部署最终汇总报告
✅ 部署结果：成功 / ❌失败
🖥️ 硬件：RTX5060Ti 16G + 整机 32G 内存
📌 模型：Qwen3.6-35B-A3B-NVFP4
📊 运行指标：
- 冷加载耗时：XX s
- 稳定解码速度：XX ~ XX tok/s
- 峰值显存占用：XX GB
- 峰值内存占用：XX GB
- Swap 最大使用：XX GB
🧪 API 测试结果：【成功/失败，简要回答质量】
⚠️ 发现的问题：列出所有警告/报错
🔄 备选方案建议：是否需要切换 Unsloth Desktop

Agent 行为约束

所有命令在 WSL2 Ubuntu 中执行，禁止直接在 Windows 原生环境跑 FreeToken
不擅自修改启动参数，不调高上下文、不修改 max-running-requests
出现报错优先收集完整日志，不要盲目重试，先判断是内存/显存/文件缺失问题；遇到“假 OOM”或进程消失先查 WSL 版本
如果持续 swap 风暴或 OOM 超过 2 次，停止 FreeToken 部署，直接输出报告并告知准备切换 Unsloth Desktop 方案
日志中不要塞满原始冗长日志，只保留关键报错、指标数值，长原始 log 放在折叠块内