> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokios.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Tokios exposes private local models through https://api.tokios.com using an outbound-only connector tunnel.
> Use 'connector' for the local tokios-connector process.
> Use 'deployment' for the public model name in the API model field.
> Use 'upstream model id' for the model served by Ollama, llama.cpp, vLLM, LM Studio, or another local backend.
> API keys use the prefix sk-tok-. Connector tokens use the prefix ct-tok-.

# FreeToken：在消费级 NVIDIA GPU 上进行 MoE 推理

> FreeToken 支持 35B-753B 参数 MoE 模型在 8GB NVIDIA GPU 上运行。UC Berkeley 的边缘原生引擎采用动态 CPU-GPU 协同调度，解码速度比 Ollama 快 3-4x 倍。

FreeToken 是 UC Berkeley 推出的开源推理引擎，可在消费级 NVIDIA GPU 上实际运行前沿规模的 Mixture-of-Experts（MoE）模型。传统服务栈要求将整个模型放入 VRAM，而 FreeToken 采用**动态 CPU-GPU 协同调度**，按需从系统内存流式加载专家权重——让你运行 35B 参数模型，在 8GB GPU 上达到 \~39 tokens/s。

> [!NOTE]
>
> 最后验证：2026-10-20

## FreeToken 解决的问题

MoE 模型如 DeepSeek-V4-Flash（284B 总参数，8B 活跃参数）或 Qwen3.6-35B（30.5B 总参数，3.3B 活跃参数）的 token 生成速度取决于**活跃参数**——但它们需要**全部参数**的内存。35B MoE 在 4-bit 量化下需要 \~18 GB 内存，无法放入 8GB GPU。

传统卸载方式（llama.cpp、Ollama）将权重静态移至系统 RAM，可行但很慢——PCIe 带宽成为瓶颈。FreeToken 采用了不同的方法：

* **动态协同调度** — 引擎预测你下一步需要哪些专家，并提前将它们从 CPU 流式传输到 GPU，将传输与计算重叠
* **双缓冲** — 当一组专家在 GPU 上运行时，下一组从 CPU 传输中，隐藏延迟
* **带宽自适应执行** — FreeToken 测量你的 PCIe 带宽并调整调度策略以匹配

结果：在相同硬件上，解码速度比静态卸载快 3-4x。

## 支持的模型

FreeToken 目前支持三个 MoE 模型系列：

| 模型 | 总参数量 | 活跃参数量 | 4-bit 下内存占用 | 状态 |
| - | - | - | - | - |
| **Qwen3.6-35B-A3B** | 30.5B | 3.3B | \~18 GB | 稳定 |
| **DeepSeek-V4-Flash** | 284B | 8B (in) / 16B (out) | \~170 GB | 稳定 |
| **GLM-5.2** | 753B | \~40B | \~452 GB | 实验性 |

35B 模型在 24GB GPU 上可放入单张显卡（4-bit 量化）。284B 和 753B 模型需要系统 RAM 卸载——FreeToken 的动态调度使其在配备 64-128 GB 系统 RAM 的游戏台式机上变得可行。

## 硬件要求

**最低要求：**

* NVIDIA RTX 30/40/50 系列 GPU（8GB+ VRAM）
* 32 GB 系统 RAM（64 GB+ 推荐用于 284B+ 模型）
* PCIe 3.0 x16 或更高（推荐 PCIe 4.0/5.0）
* CUDA 12.x

**不支持：**

* Apple Silicon（请改用 MLX——参见 [MLX 分布式推理](#mlx-distributed-inference)）
* AMD GPU
* Pascal 之前的 NVIDIA GPU（不支持 CUDA compute capability 6.0+）

> [!TIP]
>
> FreeToken 针对 NVIDIA 消费级 GPU 产品线进行了优化。如果你使用的是 Apple Silicon Mac，MLX 框架配合多台 Mac 的分布式推理是在本地运行 800B+ 模型的等效方案。

## 安装

使用 `uv`（推荐）或 `pip` 安装 FreeToken：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Using uv (faster, isolated environment)
uv pip install "freetoken[accel]"

# Using pip
pip install "freetoken[accel]"
```

安装 `[accel]` 额外依赖可安装 CUDA 内核和优化依赖。不安装的话，FreeToken 会回退到较慢的参考实现。

## 快速开始

### 部署 Qwen3.6-35B（24GB GPU）

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Download the model (4-bit quantization)
freetoken download qwen3.6-35b-a3b:q4

# Start the server
freetoken serve qwen3.6-35b-a3b:q4 --port 8000
```

FreeToken 在 `http://127.0.0.1:8000/v1` 暴露 OpenAI 兼容 API。测试：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.6-35b-a3b:q4",
    "messages": [{"role": "user", "content": "Explain MoE routing in one paragraph."}],
    "max_tokens": 256
  }'
```

RTX 4090（24GB）上的预期性能：

* **解码速度：** \~39 tokens/s
* **首 token 时间：** \~1.2s（4K prompt）
* **内存使用：** \~18 GB VRAM + \~2 GB 系统 RAM

### 使用 CPU 卸载部署 DeepSeek-V4-Flash

对于 284B 模型，你需要 64+ GB 系统 RAM 和至少 8GB VRAM 的 GPU：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# Download (this is ~170 GB at 4-bit)
freetoken download deepseek-v4-flash:q4

# Serve with CPU offloading enabled
freetoken serve deepseek-v4-flash:q4 \
  --port 8000 \
  --cpu-offload \
  --offload-ratio 0.8
```

使用 `--offload-ratio 0.8` 告诉 FreeToken 将 20% 的专家保留在 GPU 内存中，其余 80% 从系统 RAM 流式加载。根据你的 VRAM 调整：

| GPU VRAM | 卸载比例 | 预期解码速度 |
| - | - | - |
| 8 GB | 0.9 | \~12 tokens/s |
| 12 GB | 0.85 | \~18 tokens/s |
| 16 GB | 0.75 | \~26 tokens/s |
| 24 GB | 0.6 | \~35 tokens/s |

## 连接到 Tokios

FreeToken 在 `localhost:8000` 运行后，将 Tokios connector 指向它：

```json theme={"theme":{"light":"github-light","dark":"css-variables"}}
{
  "Upstream": {
    "BaseUrl": "http://127.0.0.1:8000/v1"
  }
}
```

在 Tokios dashboard 中注册模型，你会获得一个可从任何位置调用的认证 API 端点。参见[支持的后端](https://docs.tokios.com/zh/setup/supported-backends.md)了解完整的 connector 设置流程。

## 性能调优

### 优化吞吐量

如果你要服务多个并发请求，启用连续批处理：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
freetoken serve qwen3.6-35b-a3b:q4 \
  --port 8000 \
  --batching \
  --max-batch-size 8 \
  --max-wait-ms 10
```

这将最多 8 个请求批处理在一起，将专家加载成本分摊到多个用户。每个请求的延迟略有增加，但总吞吐量提高。

### 优化延迟

对于需要最快首 token 时间的交互场景：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
freetoken serve qwen3.6-35b-a3b:q4 \
  --port 8000 \
  --prefill-priority high \
  --disable-batching
```

这优先处理 prefill（prompt 处理）而非 decode，以降低首 token 时间为代价，换取较低的总吞吐量。

### 监控资源使用

FreeToken 包含内置指标端点：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
curl http://127.0.0.1:8000/metrics
```

返回：

* GPU 内存使用
* 系统 RAM 使用
* PCIe 传输速率（GB/s）
* 解码吞吐量（tokens/s）
* 每个 token 的活跃专家数

用它来调优卸载比例——如果 PCIe 传输速率低且解码速度下降，降低卸载比例以在 GPU 内存中保留更多专家。

## FreeToken 与其他后端对比

| 后端 | MoE 支持 | 35B 在 8GB GPU 上 | 解码速度 | 设置复杂度 |
| - | - | - | - | - |
| **FreeToken** | 原生优化 | 是 | \~39 tok/s（RTX 4090） | 中等（Python 包） |
| **Ollama** | 静态卸载 | 是 | \~12 tok/s（RTX 4090） | 低（一条命令） |
| **llama.cpp** | 静态卸载 | 是 | \~15 tok/s（RTX 4090） | 中等（从源码构建） |
| **vLLM** | 仅 GPU | 否（需 24GB+） | \~45 tok/s（RTX 4090，完全放入） | 高（GPU 服务器设置） |

FreeToken 的优势在于动态调度——当模型无法完全放入 VRAM 时，在相同硬件上比静态卸载快 2.5-3x。如果你的模型**可以**完全放入 VRAM，vLLM 略快，但 FreeToken 仍有竞争力。

## 故障排除

### 启用 CPU 卸载后仍出现 "CUDA out of memory"

你的 `--offload-ratio` 太低。增大它以从 CPU 流式加载更多专家：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
freetoken serve deepseek-v4-flash:q4 --cpu-offload --offload-ratio 0.95
```

### 解码速度低于预期

检查 PCIe 带宽：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
freetoken benchmark --model qwen3.6-35b-a3b:q4 --test pcie
```

如果 PCIe 传输速率低于 10 GB/s，你可能存在瓶颈（较旧的 PCIe 代次，或 GPU 在较慢的插槽中）。FreeToken 的动态调度依赖快速的 CPU-GPU 传输。

### 模型下载缓慢

FreeToken 从 Hugging Face 下载。如果你所在区域访问 HF 较慢，使用镜像：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
export HF_ENDPOINT=https://hf-mirror.com
freetoken download qwen3.6-35b-a3b:q4
```

## MLX 分布式推理

如果你使用 Apple Silicon 并想在本地运行 800B+ 模型，MLX 的分布式推理相当于 FreeToken 的 CPU-GPU 协同调度——但跨越多台 Mac。

MLX 分布式（2026 年发布）使用 RDMA over Thunderbolt 将 Mac Studio 或 Mac Pro 组成集群。4× M5 Ultra 集群达到 36.73 tokens/s，运行 Muse Spark Open（816B 参数）。

设置：

```bash theme={"theme":{"light":"github-light","dark":"css-variables"}}
# On each Mac
pip install mlx-lm

# Start the cluster
mlx_lm.distributed \
  --model muse-spark-open:q4 \
  --nodes 4 \
  --parallelism tensor
```

参见 [Apple ML Research](https://machinelearning.apple.com/research/mlx-distributed-inference) 了解完整技术细节。

## 后续步骤

> **[支持的后端](https://docs.tokios.com/zh/setup/supported-backends.md)**
>
> 将 FreeToken 与其他本地推理后端进行对比。

> **[MoE 概念](https://docs.tokios.com/zh/concepts/moe-routing-and-expert-parallelism.md)**
>
> 了解 Mixture-of-Experts 路由的工作原理以及内存为何随总参数量扩展。

> **[模型适配](https://docs.tokios.com/zh/guides/model-fit.md)**
>
> 计算模型和量化是否适配你的硬件。

> **[连接到 Tokios](https://docs.tokios.com/zh/quickstart.md)**
>
> 将你的本地 FreeToken 服务器转变为认证 API 端点。

## 来源

* [FreeToken GitHub 仓库](https://github.com/FlashML-org/FreeToken) — 安装、支持的模型和技术细节。
* [FreeToken 论文（arXiv）](https://arxiv.org/html/2608.16157v1) — 带宽自适应执行和动态协同调度。
* [InfoQ 报道](https://www.infoq.com/news/2026/08/freetoken-local-inference/) — 实际基准测试和硬件要求。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.