FastLLM

English · 快速开始 · 模型部署指南 · Benchmark · 常用参数 · 版本日志

FastLLM 是一个面向本地运行和服务部署的高性能大模型推理引擎。核心运行时使用 C++ 实现，不依赖 PyTorch，支持稠密模型与 MoE 模型，并提供 CUDA、ROCm、CPU、NUMA、磁盘混合推理以及多卡张量并行能力。

项目同时提供命令行对话、终端部署向导、WebUI、性能测试工具，以及兼容 OpenAI Chat Completions、OpenAI Responses 和 Anthropic Messages 的 API 服务。

核心能力

• 新模型快速适配：当前主线覆盖 Qwen4-Exp / Qwen3.8-Flash-Next、Qwen3.5/3.6/3.8、DeepSeek-V4、Kimi-K3、GLM-5.3-Flash、Dots3-Note 等模型。
• 大规模 MoE 混合部署：可将普通层和专家层分别放在 CUDA、CPU、NUMA 或磁盘上，也可按比例组合多种设备，适合显存有限但主机内存或 SSD 容量充足的机器。
• 多卡与高吞吐服务：支持张量并行、奇数卡数量、动态批处理、流式输出、Paged KV Cache、前缀缓存、分块 Prefill 和 CUDA Graph。
• 投机解码：为匹配的模型提供 MTP、内置或外部 DSpark，以及 DFlash2 等投机解码路径。
• 多种精度与格式：支持 Hugging Face Safetensors、FastLLM 导出格式、AWQ 和部分 GGUF；可按模型与硬件使用 FP16、BF16、FP8、NVFP4、MXFP4、INT4、K-Quant 等路径。
• 完整服务接口：支持思考内容分离、工具调用、流式响应、缓存命中统计、服务端采样参数和启动进度事件。
• 可扩展后端：内置 CPU/CUDA/ROCm 算子，并提供 Triton 可选算子、自定义 Python 模型图和其他加速器后端的源码接入能力。

不同模型、量化格式和硬件后端支持的算子并不完全相同。正式部署前请用目标模型和目标硬件验证精度、显存占用及吞吐。

当前模型能力

下面列出当前开发主线重点，不再把早期模型作为首页介绍内容。

Qwen4-Exp / Qwen3.8-Flash-Next 当前不加载视觉权重；Qwen3.8-Flash-Next 可通过 --mtp 按需加载 MTP 权重并启用推测解码。早期模型的兼容信息仍可在支持模型列表中查询；最新适配和限制以版本日志为准。

快速开始

安装

建议在独立的 Python 虚拟环境中安装。预编译包适用于以下常见环境：

Windows 首次安装所需的依赖包：

python -m pip install https://www.modelscope.cn/models/huangyuyang/fastllmdepend-windows/resolve/master/ftllmdepend-0.0.0.2-py3-none-win_amd64.whl
python -m pip install -U ftllm

如果 Conda 环境出现动态库冲突，可尝试使用 venv 创建干净环境。安装或加载失败时先查看 FAQ。

验证安装

下面使用体积较小的 Qwen3-0.6B 做安装冒烟测试；它只是便于快速下载的测试模型，不代表当前模型主线。

ftllm run Qwen/Qwen3-0.6B

最常用的部署入口是 API Server：

# API Server，默认监听 0.0.0.0:8080
ftllm server Qwen/Qwen3-0.6B

# 命令行对话
ftllm run Qwen/Qwen3-0.6B

# WebUI，连接上面的 API Server，默认监听 127.0.0.1:1616
ftllm webui --api_base http://127.0.0.1:8080/v1

# 浏览器部署启动器；无参数时启动并自动打开本地管理页面
ftllm
ftllm launch  # 等价写法

# 终端部署向导
ftllm tui

# 性能测试
ftllm bench Qwen/Qwen3-0.6B \
  --device cuda --input_tokens 512 --output_tokens 128 --batch 4

ftllm（或 ftllm launch）默认仅监听 127.0.0.1:8000，并在服务就绪后自动打开浏览器；使用 ftllm launch --no-browser 可以关闭自动打开。页面可以从 ModelScope 下载模型、保存启动配置、预览命令，并选择托管 ftllm server 或聊天 ftllm webui。新增启动项选择本地模型后，会根据模型结构、权重规模以及本机 GPU、内存和 NUMA 拓扑自动推荐 TP、MoE 混合推理与 N-gram 存储参数，也可以手动重新分析或清空可选推理参数。界面支持简体中文和英文，会优先使用上次选择的语言，否则跟随浏览器语言；ftllm launch 的终端日志固定使用英文。需要从局域网访问时使用 ftllm launch --host 0.0.0.0；终端和 Launcher 页面随后会列出本机、局域网以及网卡上直接配置的公网访问地址（若有）。公网访问还需要放行主机防火墙及云安全组，经过 NAT 时还需配置端口映射；Launcher 不会自动探测 NAT 的公网地址。非本机监听使用未加密 HTTP，请仅在可信网络中使用。它与终端向导共用配置文件；关闭 Launcher 时，由它托管的下载和模型进程也会停止。使用 ftllm launch --help 查看其他选项。

API Server 就绪后，点击「打开工作室」即可在 Launcher 内容区直接使用聊天、历史会话、Markdown、附件、思考过程和智能体功能。模型管理导航始终保留，可随时切换到启动、下载、日志和硬件页面，返回「工作室」后继续当前会话。Launcher 与独立的 ftllm webui 共用聊天组件和后端，界面配色、尺寸及语言会适配 Launcher。组件自动连接当前模型并使用启动配置中的 API Key，无需另开 WebUI 服务或端口。会话沿用 WebUI 的本地存储，刷新页面后仍然保留；停止或切换模型时会取消正在运行的 WebUI 任务并清理旧组件。

WebUI 不会在自身进程内加载模型，请先启动 OpenAI 兼容 API Server。WebUI 的可选 model 位置参数只用于推导 API 模型名；省略时会从 /v1/models 自动发现。

代码分析和联网搜索默认使用 Pi 智能体运行时。Linux x86-64 用户可按 tools/ftllm_agent_runtime/ 中的说明构建并安装配套 wheel； 该 wheel 已包含 Pi，不需要 Node.js、npm 或 Bun。尚未安装时可通过 --agent-runtime builtin 使用原有单轮链路。

Launcher 会自动使用已安装的 Pi 运行时；「新建 Agent」可选择工作目录。通过 ftllm launch --agent-workspace-root /path/to/projects 指定可选目录的根路径，默认为用户主目录。Launcher 的目录 Agent 默认启用，本机和远程监听均可使用，例如 ftllm launch --host 0.0.0.0 --agent-workspace-root /path/to/projects。使用 --disable-workspace-agent 可关闭目录 Agent，同时禁止目录浏览、新建目录 Agent 及继续执行已保存的目录 Agent 任务；普通对话仍可使用。目录 Agent 可修改文件和执行命令，请仅对可信用户开放。运行时缺失或目录 Agent 被关闭时，界面会显示原因。

对于 run、server 和 export，model 位置参数既可以是 Hugging Face 仓库 ID，也可以是本地 Hugging Face 模型目录、FastLLM 模型文件或配置文件。例如：

ftllm server /data/models/my-model --device cuda

调用 API

启动一个带固定服务名的本地模型：

ftllm server /data/models/my-model \
  --model_name local-model \
  --host 0.0.0.0 --port 8080 \
  --api_key local-key

通过 OpenAI Chat Completions 接口调用：

curl http://127.0.0.1:8080/v1/chat/completions \
  -H "Authorization: Bearer local-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local-model",
    "messages": [{"role": "user", "content": "你好，请介绍一下 FastLLM。"}],
    "stream": false
  }'

服务还提供 OpenAI Responses API 和 Anthropic Messages API。模型支持时，可使用思考内容分离、工具调用和图文输入等能力。

模型部署指南

不同模型在注意力结构、MoE 布局、投机解码和量化格式上差异很大。选择目标模型后，请先阅读对应部署指南，再使用后面的通用配置作为补充。

Benchmark 索引 按模型分别记录测试硬件、完整启动命令、TTFT、Prefill、Decode 和并发吞吐。没有仓库实测的数据会明确标为“待实测”，不会从其他设备或模型外推。

典型部署配置

多卡张量并行

--tp 0,1 显式使用 0、1 号 GPU；--tp 2 表示使用前两张可见 GPU；--tp auto 自动使用检测到的 GPU。

ftllm server /data/models/my-model \
  --device cuda --tp 0,1 \
  --max_batch 16 --gpu_mem_ratio 0.9

GPU + NUMA 混合 MoE

ftllm server /data/models/my-moe-model \
  --device cuda --moe_device numa \
  --chunked_prefill_size 8192

内存不足时还可以把少量专家层放到磁盘，例如 --moe_device "{'cuda':1,'numa':8,'disk':1}"。磁盘路径依赖 SSD 随机读取性能，详细配置参见混合推理指南。

长上下文与前缀缓存

--max_context_length（别名 --max-context-length）设置单会话输入与输出合计上限。扩大模型声明窗口时，还需要有效的 --rope_scaling（别名 --rope-scaling），接受 yarn 或 JSON；只缩小窗口时可省略 RoPE 参数。配置在加载时生效，不修改模型的 config.json。

例如，将 Qwen3-0.6B 扩展到 65536 token，并开启前缀缓存。其 YaRN 原始长度为 32768，应显式指定，不能用配置声明的 40960 代替：

ftllm server /data/models/Qwen3-0.6B \
  --device cuda --max_batch 1 --tokens 65536 \
  --max_context_length 65536 \
  --rope_scaling '{"rope_type":"yarn","factor":2,"original_max_position_embeddings":32768}' \
  --chunked_prefill_size 8192 \
  --prefix_cache true

Qwen3.8-27B-FP8 可以使用已知原始长度的 yarn 简写。下面配置双卡、FP4 KV 和 1,000,000 token 的目标窗口，解析得到 original=262144、factor=4：

ftllm server /data/models/Qwen3.8-27B-FP8 \
  --tp 2 --kv_cache_dtype fp4 \
  --max_context_length 1000000 --rope_scaling yarn

--tokens 是所有会话共享的 KV 池容量，未设置时自动预算。显式目标超过 RoPE 覆盖范围或 warmup 校准容量会启动失败；/v1/models 返回实际窗口、模型原声明和用户目标。上述 1M 命令需要足够显存，本机双 24GB 的测试配置无法容纳，完整 1M 输入尚未实测。

当前扩展接入 HF Qwen2、Qwen3、Qwen3.5 布局，以及基于 Qwen3.5 架构的 Qwen3.8；Launcher 高级参数中的「RoPE 扩展」使用相同配置。GGUF、FLM 和自定义 GraphLLM 仅设置长度时保留旧的只缩小行为，暂不支持新的 RoPE 扩展。更多参数、适配范围和验证结果见上下文扩展说明。

投机解码

以下功能只适用于结构和 checkpoint 匹配的模型：

# 以 Qwen3.5 为例使用内置 MTP，每轮最多配置 8 个 draft token
ftllm server /data/models/qwen3.5 --mtp 4

# 给不含 MTP 权重的 Qwen3.5 GGUF 挂载独立 MTP 模块
ftllm server /data/models/qwen3.5.gguf \
  --device cuda --cuda_embedding \
  --draft /data/models/qwen3.5-fp8/mtp.safetensors \
  --draft_tokens 5

# DeepSeek-V4 内置 DSpark
ftllm server /data/models/deepseek-v4 --dspark 7

# Qwen3.8 + 独立 DFlash2 draft checkpoint
ftllm server /data/models/qwen3.8 \
  --tp 2 \
  --draft /data/models/qwen3.8-dflash2 \
  --draft_tokens 7

--draft 会根据 draft checkpoint 自动识别 MTP、DFlash2 或 DSpark。独立 MTP 当前用于 Qwen3.5 GGUF，路径可指向包含 config.json 和 mtp.safetensors 的目录，也可直接指向 mtp.safetensors；省略 --draft_tokens 时默认使用 5。DFlash2 的 --draft_tokens 表示实际 draft token 数，不包含 anchor token。

DFlash2 的完整配置和验证结果见 Qwen3.8 DFlash2 文档。

Qwen4 PLE 磁盘模式

Qwen4-Exp / Qwen3.8-Flash-Next 的 PLE 表较大。主机内存不足时可按需从 checkpoint 读取：

ftllm server /data/models/qwen4-exp \
  --device cuda --moe_device numa \
  --ngram_device disk

磁盘模式会降低常驻内存，但增加随机 I/O，建议使用高速 SSD。更多限制见 Qwen4-Exp 文档。

常用参数

CLI 会持续演进，ftllm <command> --help 是当前安装版本的最终依据。下面列出部署中最常用的参数。

模型、设备与精度

显存、上下文与调度

解码、模板与工具调用

API Server

查看完整参数：

ftllm --help
ftllm server --help
ftllm bench --help
ftllm download --help

模型格式、下载与导出

支持的输入格式

• Hugging Face 原始 Safetensors 权重，包括模型自带的 FP16、BF16 或 FP8 权重。
• 已量化的 AWQ 模型。
• FastLLM 导出的定精度或动态量化模型。
• 部分 GGUF 格式；需要通过 --ori 指定原模型的配置和 tokenizer 目录。

量化格式是否可用取决于模型结构、设备和对应 kernel。首次部署建议保留 --dtype auto；对于已经量化的 checkpoint，不要再次指定在线量化类型。

下载模型

ftllm download <repo-id> --local-dir /data/models/model-name

只下载配置和 tokenizer 文件时可以排除权重：

ftllm download <repo-id> \
  --exclude "*safetensors*" \
  --local-dir /data/models/model-config

导出模型

在线量化会增加每次启动的加载时间。可以预先导出 FastLLM 格式：

ftllm export /data/models/source-model \
  -o /data/models/source-model-int4 \
  --dtype int4 -t 16

MoE 模型可以分别设置普通层和专家层精度：

ftllm export /data/models/source-moe \
  -o /data/models/source-moe-mixed \
  --dtype float16 --moe_dtype int4 -t 16

动态量化配置见动态量化说明。

源码安装

源码构建需要 C++17 编译器、Make 和 CMake；建议 GCC/G++ 9.4+、CMake 3.23+。Linux NUMA 构建通常还需要 libnuma-dev。CUDA 构建请预先安装兼容的 CUDA Toolkit 和 NCCL。

# Ubuntu/Debian 基础依赖
sudo apt-get install -y build-essential cmake libnuma-dev

# NVIDIA CUDA
bash install.sh -DUSE_CUDA=ON \
  -DCMAKE_CUDA_COMPILER="$(command -v nvcc)"

# 指定 CUDA 架构，例如 Ada 使用 89
bash install.sh -DUSE_CUDA=ON -DCUDA_ARCH=89 \
  -DCMAKE_CUDA_COMPILER="$(command -v nvcc)"

# CPU-only
bash install.sh

更多平台说明：

• ROCm 编译与 wheel 打包
• TFACC 平台
• 示例程序、Android 和其他平台
• 编译与运行 FAQ

文档导航

社区与贡献

欢迎通过 GitHub Issues 报告问题，通过 Pull Requests 参与开发。

部署交流 QQ 群：831641348

用户交流群（使用、部署）：

社区开发群（贡献、开发讨论）：

项目采用 Apache License 2.0。

参考代码和文章

FastLLM 的实现参考或使用了以下开源项目与文章中的思路或代码：

• PyTorch：底层算子实现思路。
• Transformers：模型结构与参考实现。
• llama.cpp 和 ik_llama.cpp：GGUF 量化格式与 kernel。
• FlashInfer：Attention、MLA 等算子。
• TurboMind / LMDeploy 的 GEMM 内核：仓内 third_party/turbomind 的 SM70 s884（SM70_MMA_884 / HMMA 8x8x4）核心由其源码移植，并在其上接入 AWQ INT4、块缩放 FP8 与 NVFP4 Linear。
• 1Cat-vLLM 的 SM70 TurboMind 适配：AWQ 接入及 FP8/NVFP4 类型、布局和小批量 tactic 的参考来源；FastLLM 侧另行实现了无 Torch 的原始指针桥接、模型权重格式转换、非对齐 padding、回退和调度。
• KTransformers：MoE 动态线程调度；另见思路介绍。
• Lvllm：NUMA MoE 动态调度。
• FreeToken：CUDA 专家缓存及相关混合推理优化的设计参考，包括 GPU 端路由与 LRU 缓存管理、主机专家权重按需回填，以及 CUDA Graph 兼容的执行流程。具体实现与扩展方式见 CUDA 专家缓存说明。
• vLLM：工具调用解析。
• json11：JSON 构造与解析。

感谢所有开源贡献者。如发现遗漏的代码来源或引用，请通过 Issue 告知。