深入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请求会依次穿过HTTP API 层server/——协议解析、流式响应消息/分词层message/、tokenizer/——文本转 token调度层scheduler/——prefill/decode 编排、KV 预算引擎层engine/——CUDA 流、CUDA Graph、KV Pool内核层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/modelsAnthropic 兼容/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-A3Bdtype、注意力后端、MoE 后端、缓存大小全部从 checkpoint 和 GPU 自动解析日志出现API server is ready to serve on 127.0.0.1:1919即就绪。三、调度层Prefill 与 Decode 的编排艺术调度器 python/freetoken/scheduler/scheduler.py 是整个引擎的总指挥它管理组件文件职责PrefillManagerscheduler/prefill.py分块预填充chunked prefillDecodeManagerscheduler/decode.py批量 decode 请求合并CacheManagerscheduler/cache.py统一缓存分配ShadowRadix 分层TableManagerscheduler/table.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% 以上的权重是专家ExpertFFN而消费级显卡显存根本装不下——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.pyCPU 侧走 AVX-512 GEMVkernel/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 MoEcsrc/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 模型这不再是论文里的概念。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
深入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请求会依次穿过HTTP API 层server/——协议解析、流式响应消息/分词层message/、tokenizer/——文本转 token调度层scheduler/——prefill/decode 编排、KV 预算引擎层engine/——CUDA 流、CUDA Graph、KV Pool内核层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/modelsAnthropic 兼容/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-A3Bdtype、注意力后端、MoE 后端、缓存大小全部从 checkpoint 和 GPU 自动解析日志出现API server is ready to serve on 127.0.0.1:1919即就绪。三、调度层Prefill 与 Decode 的编排艺术调度器 python/freetoken/scheduler/scheduler.py 是整个引擎的总指挥它管理组件文件职责PrefillManagerscheduler/prefill.py分块预填充chunked prefillDecodeManagerscheduler/decode.py批量 decode 请求合并CacheManagerscheduler/cache.py统一缓存分配ShadowRadix 分层TableManagerscheduler/table.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% 以上的权重是专家ExpertFFN而消费级显卡显存根本装不下——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.pyCPU 侧走 AVX-512 GEMVkernel/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 MoEcsrc/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 模型这不再是论文里的概念。创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
