企业官网建设流程全解析

深入FreeToken架构：从HTTP API到CUDA内核的本地MoE推理引擎全链路剖析

FreeToken 是一款边缘原生的本地 MoE 推理引擎，它把数据中心级的大模型服务能力搬进你的个人电脑：在一台游戏 PC 上，以接近交互的速度运行 290B+ 参数的前沿 MoE 模型（如 DeepSeek-V4-Flash、Qwen3.6-35B-A3B）。它的秘诀是把 GPU、CPU、主机内存和 PCIe 互连当作一个统一的弹性推理平台来调度。

本文带你完整走一遍 FreeToken 的请求链路：HTTP API → 调度器 → KV 缓存 → MoE 专家调度 → CUDA 内核，并告诉你每一层对应源码中的哪个模块。

一、全链路总览：一次推理请求的五层旅程

FreeToken 采用前后端分离的进程架构：API 前端（FastAPI + Uvicorn）通过 ZMQ 消息队列与后端推理 Worker 通信，Worker 内部再由调度器驱动整个引擎。一次/v1/chat/completions请求会依次穿过：

1. HTTP API 层（server/）——协议解析、流式响应
2. 消息/分词层（message/、tokenizer/）——文本转 token
3. 调度层（scheduler/）——prefill/decode 编排、KV 预算
4. 引擎层（engine/）——CUDA 流、CUDA Graph、KV Pool
5. 内核层（kernel/、moe/）——Triton/CUDA 算子、CPU-GPU 混合 MoE

这种分层让控制面可以独立于 GPU 故障存活（见 python/freetoken/server/api_server.py 中前端守护后端 Worker 的看门狗设计）。

二、HTTP API 层：OpenAI 与 Anthropic 双协议

FreeToken 的 API 服务由 FastAPI 驱动，同时注册了三套路由：

• OpenAI 兼容：/v1/chat/completions、/v1/responses、/v1/models
• Anthropic 兼容：/v1/messages、/v1/messages/count_tokens
• 控制面：健康检查、统计、计费路由

见 python/freetoken/server/api_server.py 的register_openai_routes、register_anthropic_routes与register_control_routes。这意味着你现有的 Claude Code、Codex 等编程 Agent只需把 base URL 指过来即可直接工作，配合ft launch claude一条命令完成接入（参考 docs/quickstart.md）。

一条命令即可起服务：

ft serve --model ~/models/Qwen3.6-35B-A3B

dtype、注意力后端、MoE 后端、缓存大小全部从 checkpoint 和 GPU 自动解析，日志出现API server is ready to serve on 127.0.0.1:1919即就绪。

三、调度层：Prefill 与 Decode 的编排艺术

调度器 python/freetoken/scheduler/scheduler.py 是整个引擎的"总指挥"，它管理：

调度器使用独立 CUDA 流做重叠调度（overlap scheduling），让元数据计算与张量运算并行，隐藏 CPU 侧开销。

四、KV 缓存：Radix 树 + 弹性显存

kvcache/模块实现了多种池与缓存结构，按需组合：

• Paged 池家族：MHA 池（mha_pool.py）、DSA 池、QSA 池、滑动窗口池（hybrid_swa_pool.py）、线性注意力状态池
• Radix 前缀树：radix_cache.py 支持前缀复用；混合变体 hybrid_radix_cache.py 为不同注意力组分层管理

两个对 Agent 场景至关重要的特性：

• 语义锚点缓存：工具调用、思维块等上下文编辑命中语义检查点后，可跳过冗余重算
• 运行时显存再分配：专家缓存与 KV 显存之间可免重启、免重载权重地动态调配（见 engine/cache_budget.py）

五、MoE 引擎：CPU-GPU 混合推理的核心魔法 🔥

这是 FreeToken 最精彩的部分。MoE 模型 90% 以上的权重是专家（Expert）FFN，而消费级显卡显存根本装不下——FreeToken 的解法是bandwidth-adaptive CPU–GPU 协同执行：

• 专家银行分层存放：BF16 / FP8 block / NVFP4 / MXFP4 / GGUF Q4_0 五种量化格式各有独立的 bank schema，声明在 moe/offload_cache.py，热专家驻留 GPU，冷专家驻留 pinned 主机内存
• 全局 LRU 专家缓存+全层双缓冲 prefill 流式传输，拷贝与计算重叠
• q*带宽自适应策略：引擎启动时通过ft bench bw实测 CPU 内存带宽与 PCIe 带宽，自动计算最优的专家取回比例（engine/engine.py），CPU 侧走 AVX-512 GEMV（kernel/csrc/cpu_moe/cpu_moe_ext.cpp）

一句话总结：显存放不下的部分交给 CPU 内存，PCIe 搬不动的部分让 GPU 算，两边速度永远对齐硬件实测带宽。

六、CUDA 内核层：Triton 优先，原生 CUDA 兜底

内核层 python/freetoken/kernel/ 采用"可选加速包探测 + 纯 Triton 兜底"策略（kernel/backend.py）：安装了 flashinfer/sgl_kernel 就用融合 CUDA 算子，否则自动回退到kernel/triton/下的纯 Triton 实现——包括 FP8 分块线性、NVFP4 fused MoE、稀疏注意力、GEMMA/GDN 融合算子等上百个 kernel。

原生 CUDA/C++ 部分（kernel/csrc/）则负责更底层的能力：pinned tensor 零拷贝、批量异步拷贝（jit/batch_memcpy.cuh）、GGUF 反量化与 Q4_0 MoE（csrc/gguf/）、以及 pynccl 分布式通信。

七、快速上手清单 ✅

uv pip install "freetoken[accel]" # 1. 安装 ft bench bw # 2. 实测硬件带宽，自动选定 MoE 后端 ft serve --model ~/models/Qwen3.6-35B-A3B # 3. 启动推理服务 ft shell # 4. 终端 TUI 聊天 ft launch claude # 5. 接入编程 Agent

更完整的参数见 docs/cli.md，支持模型清单见 docs/models.md。

八、总结

FreeToken 的架构哲学可以用三层关键词概括：

• API 层：OpenAI/Anthropic 双协议，Agent 即插即用
• 调度层：重叠调度 + Radix 语义缓存 + 弹性显存，为长上下文 Agent 而生
• 执行层：CPU-GPU 带宽自适应 MoE + Triton/CUDA 双内核栈，榨干消费级硬件

对想读懂本地大模型推理引擎的读者，建议按server/ → scheduler/ → engine/ → moe/ → kernel/的顺序阅读源码，配合 tests/ 下的单元测试理解每个模块的边界。在一张 RTX 4090 上跑 290B MoE 模型，这不再是论文里的概念。