# FreeToken 探索结论 + 最终方案（Qwen3.8-27B 破限版）

> 记录日期：2026-08-26 ｜ GPU 机 192.168.31.25（RTX 5060 Ti 16GB / 32GB RAM）
> 相关：`破限版27B部署实测-20260826.md`（llama.cpp 96K 方案主记录）

## 一、FreeToken 探索（最终结论：放弃）

### 安装完成（耗时约 1.5h，网络是主要瓶颈）

- **环境**：`~/Downloads/freetoken-venv`（Python 3.12 venv），`ft` 0.1.2
- **依赖安装经验**：
  - PyPI 直连慢 → 阿里镜像（`-i https://mirrors.aliyun.com/pypi/simple/`）快
  - **torch cu130 不在 PyPI 主站**，需从 `download.pytorch.org/whl/cu130/` 手动下载 wheel 后 `pip install <file>`（注意 wheel 文件名必须规范，否则 pip 报 "Invalid wheel filename"）
  - **sglang-kernel 383MB 是纯 PyPI 包**（x86_64 版 365MB），阿里镜像同步有问题 → 从 PyPI JSON API 拿确切 URL 手动下载后离线安装
  - 踩坑：pip 后台安装时 `/tmp` 下的启动脚本会被清理，必须用 `~/Downloads/` 下脚本 + `setsid nohup` 模式

### 模型下载（23.35GB 破限 NVFP4）

- 仓库：`lyf/Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive-NVFP4`（HauhauCS 破限）
- 路径：`~/Downloads/freetoken-models/Qwen3.6-35B-A3B-Uncensored-HauhauCS-Aggressive-NVFP4/`
- **网络经验**：
  - GPU 机直连 hf-mirror 不稳定（时而 26MB/s 时而 150KB/s）
  - 本机（192.168.31.76）是 **WiFi 上网**（有线网卡 DOWN），本机→GPU 机只有 ~2.5MB/s，传 23GB 不可行
  - **最优：GPU 机 aria2 16 线程直连 hf-mirror**（恢复高速时 100MB/s+，几分钟完成）

### ❌ 核心结论：破限版 NVFP4 与 FreeToken 不兼容

**症状**：
1. `ft serve --moe-backend offload` → CUDA OOM（加载时把全部 23GB 权重物化到 GPU）
2. `ft checkpoint`（转 FTW）→ `Missing MoE expert source layers: {'gate_up': [...0-39], 'down': [...]}`

**根因**（源码级对比 FreeToken `qwen3_5_moe/weight.py` + `loader.py`）：

| | lyf 破限版（HauhauCS） | FreeToken 预期 |
|---|---|---|
| 权重前缀 | `language_model.model.layers.N...` | `model.language_model.layers.N...` |
| 专家权重 | `experts.E.down_proj.weight_packed` | `experts.E.down_proj.weight/.weight_scale` |
| 量化格式 | `nvfp4-pack-quantized`（compressed-tensors） | modelopt NVFP4 |

→ FreeToken 的专家识别正则全部失配，offload 模式无法识别专家层，把 23GB 全当 dense 塞 GPU → OOM。

**FreeToken 官方支持**的是 [nvidia/Qwen3.6-35B-A3B-NVFP4](https://huggingface.co/nvidia/Qwen3.6-35B-A3B-NVFP4)（modelopt 格式，~30GB，**非破限**）。
破限版 bf16（如 [RobinsonLabs](https://huggingface.co/RobinsonLabs/Qwen3.6-35B-A3B-abliterated)）兼容但 70GB，超 32G 内存。

## 二、最终选定方案（✅ 已部署）

**C. llama.cpp + Qwen3.8-27B 破限版（Bucoid MTP）**

- **配置**：96K 上下文 + KV Q4_0 + 全 GPU + Flash Attention，实测 **26-27 tok/s**
- **服务**：端口 8081，`~/Downloads/start-llamacpp-qwen38-heretic.sh`（自动释放 llmster 显存）
- **验证**：`model loaded`，显存 15.5G，API 正常（破限生效）
- **停止**：`~/Downloads/stop-llamacpp-qwen38-heretic.sh`

### 为什么 FreeToken 不适合当前需求

- 核心价值（MoE 专家卸载到内存）需要 **FreeToken 兼容格式的 MoE 模型**
- 破限版 Qwen3.6-35B-A3B NVFP4 与 FreeToken 不兼容（见上）
- 官方兼容版非破限，且需重新下载 30GB
- llama.cpp 已能 96K + 26 tok/s 跑破限 27B，满足需求

## 三、FreeToken 残留（可清理，约 29G）

- `~/Downloads/freetoken-venv`（6.9G）
- `~/Downloads/freetoken-models/`（22G）
- 本机 `/home/zyw/Downloads/hf-dl/freetoken/`（23.35G，本机副本）
- 本机 `range_server.js` + 端口 8898（若未关）

保留还是清理，按需决定；venv 保留可在 FreeToken 更新兼容格式后复用。

---

## ✅ 更新（2026-08-26 深夜）：FreeToken 成功部署官方版！

### 关键突破：换官方 nvidia modelopt 版后完全跑通

之前失败是**模型格式问题**（lyf 破限版 compressed-tensors pack 与 FreeToken 不兼容）。
换 **nvidia 官方 modelopt 版**后一次成功：

### 模型

- 仓库：[nvidia/Qwen3.6-35B-A3B-NVFP4](https://huggingface.co/nvidia/Qwen3.6-35B-A3B-NVFP4)
- 路径：`~/Downloads/freetoken-models/nvidia-Qwen3.6-35B-A3B-NVFP4/`
- 大小：3 分片共 **22GB**（10G+10G+3.4G），quant_method=**modelopt** / MIXED_PRECISION
- 下载：GPU 机 aria2 16 线程直连 hf-mirror（高峰期 ~20MB/s，约 15 分钟）

### 服务运行（✅ 已部署）

```bash
# 启动（offload 模式：专家驻留内存 + GPU 只放缓存）
/home/zyw/Downloads/freetoken-venv/bin/ft serve \
  --model /home/zyw/Downloads/freetoken-models/nvidia-Qwen3.6-35B-A3B-NVFP4 \
  --host 0.0.0.0 --port 8081 --moe-backend offload --memory-ratio 0.9
# 封装脚本：~/Downloads/start_ft_nvidia.sh
```

### 实测结果（RTX 5060 Ti 16GB / 32GB RAM）

| 指标 | 数值 |
|---|---|
| **速度** | **33.4 tok/s**（200 tokens / 5.98s，流式） |
| 显存 | 14.9G / 16G（专家缓存 5701 slots + KV 0.16G） |
| 内存 | 20G used（专家池驻留内存，available 11G）✅ 32G 够 |
| 首次请求 | ~6 分钟（专家冷启动 + serial bank build） |
| 后续请求 | **4-6 秒**（专家缓存热了） |
| 架构 | Qwen3.6-35B-A3B MoE（每 token 只激活 3B） |

### 与 llama.cpp 方案对比

| | FreeToken + 官方 35B MoE | llama.cpp + 破限 27B |
|---|---|---|
| 速度 | **33.4 tok/s** | 26-27 tok/s |
| 上下文 | 8271 tokens（KV 很小） | **96K**（KV Q4_0） |
| 破限 | ❌ 官方版非破限 | ✅ 破限 |
| 显存 | 14.9G | 15.5G |
| 内存 | 20G | ~3G |

### ⚠️ 取舍提醒

- **要速度** → FreeToken（33 tok/s，但官方版**非破限**，上下文仅 ~8K）
- **要破限 + 长上下文** → llama.cpp 破限 27B（26 tok/s，96K）
- 两个服务不能同时驻留（都占 ~15G 显存）

### 启动脚本

- `~/Downloads/start_ft_nvidia.sh`（FreeToken 8081 端口）
- `~/Downloads/start-llamacpp-qwen38-heretic.sh`（llama.cpp 8081 端口）