一个脚本跑通DeepSeek-V4.1-Flash-Quark-PTPC-FP8:inference最小推理实现新手入门教程
一个脚本跑通DeepSeek-V4.1-Flash-Quark-PTPC-FP8:inference最小推理实现新手入门教程
DeepSeek-V4.1-Flash-Quark-PTPC-FP8 是 AMD 官方用 AMD Quark 量化为 PTPC-FP8 的 DeepSeek-V4.1-Flash 视觉语言模型。本教程手把手带你使用 inference/ 目录下的最小推理实现,完成从环境安装、权重转换到一键运行图文推理的全部步骤——只需跑通一个脚本,即可看到模型输出。下图就是 examples 中图文示例用到的玉米实拍图:
这个项目是什么?
简单来说,它是开源的最小可运行推理参考实现(readable reference implementation),面向新手与研究者,而非生产级服务引擎:
| 特性 | 说明 |
|---|---|
| 量化格式 | PTPC-FP8(experts、shared_experts、self_attn、engram.embed 被量化,视觉塔保持原精度) |
| 目标硬件 | AMD MI355 / MI350(gfx950),ROCm 7.2.0 |
| 模型规模 | 40 层 + 3 层 MTP,384 个路由专家(激活 6 个),65K 上下文 |
| 输入输出 | 文本 + 图片 → 文本 |
| 精度验证 | GSM8K(8-shot)得分 92.95,与原版模型 100% 持平 |
模型代码完整覆盖视觉编码器、滑动窗口+压缩稀疏注意力(两级 indexer)、engram n-gram 查找、MoE、Hyper-Connections 与 DSpark 前向路径。想深入了解架构细节,可阅读仓库根目录的技术报告 DeepSeek_V41_Tech_Report.pdf。
目录结构:先看一眼文件在哪
inference/
├── run.sh # 一键推理脚本(本文主角)
├── convert.py # 权重转换:HF 权重 → 张量并行分片
├── generate.py # 推理入口(批量生成 / 交互聊天)
├── model.py # 完整模型架构(Transformer 前向)
├── kernel.py # fp8/fp4 算子、稀疏注意力等内核
├── vision.py # 视觉编码器 ViT + Aligner
├── engram.py # engram n-gram 哈希查找
├── image_processor.py# 图文输入预处理
├── config.json # 模型超参数(40层/384专家/65K上下文)
├── requirements.txt # 依赖清单
└── examples/ # TXT 与 JSON 示例输入
第一步:环境安装(1 分钟)
推理实现基于标准 PyTorch + 张量并行,依赖非常轻:
python -m pip install -r inference/requirements.txt
核心依赖:torch>=2.10.0、transformers、safetensors、tilelang==0.1.8 等,详见 inference/requirements.txt。
💡 官方验证环境为 Linux + ROCm 7.2.0 + PyTorch 2.12.0;只要 GPU 显存能装下模型分片(默认 8 卡张量并行),NVIDIA/AMD 机器均可尝试。
第二步:权重转换(关键一步)
运行时每个张量并行 rank 需要一个独立的分片文件,因此先用 inference/convert.py 把 Hugging Face 格式权重"切好":
export HF_CKPT_PATH=/path/to/DeepSeek-V4.1-Flash-Quark-PTPC-FP8
export SAVE_PATH=/path/to/DeepSeek-V4.1-Flash-TP8
export MP=8
python inference/convert.py \
--hf-ckpt-path "${HF_CKPT_PATH}" \
--save-path "${SAVE_PATH}" \
--model-parallel "${MP}" \
--expert-dtype fp4 \
--tokenizer-path "${HF_CKPT_PATH}"
参数说明:
--model-parallel:分片数(默认 8,即 TP8),必须能整除专家总数 384;--expert-dtype:专家权重输出格式,fp4(默认)或fp8;- 专家数量会从权重名自动推断,无需手动指定;
- tokenizer 文件(
tokenizer.json、tokenizer_config.json)会被自动复制到输出目录。
转换完成后,SAVE_PATH 下会出现 model0-mp8.safetensors ~ model7-mp8.safetensors 共 8 个分片。
第三步:一个脚本跑通推理 🚀
转换完成后,inference/run.sh 一条命令即可运行(它会校验分片齐全,再自动 torchrun 拉起 8 个进程):
cd inference
INPUT_FILE=examples/example.txt ./run.sh /path/to/DeepSeek-V4.1-Flash-TP8
# 或跑 Harmony JSON 格式的图文示例:
INPUT_FILE=examples/example_harmony.json ./run.sh /path/to/DeepSeek-V4.1-Flash-TP8
examples/example.txt 内置了 4 条示例:中文问答、列出素数、公司介绍,以及一条双图视觉问答(用 <image>路径</image> 标签内嵌图片)。两个示例文件表达的是同一条"两张图交错"的 prompt,编码后的 token 序列完全一致。
运行成功后,终端会打印每条 Prompt 及模型 Completion,类似:
Prompt: 中国的首都是哪里?
Completion: 北京……
常用参数速查
| 方式 | 说明 |
|---|---|
MP=4 ./run.sh ... |
改为 4 卡张量并行(需先以 --model-parallel 4 重新转换) |
CONFIG=xxx ./run.sh ... |
指定其他 config.json |
--max-new-tokens |
限制生成长度(generate.py 默认 200) |
--temperature |
采样温度,越高越发散,越低越稳定 |
| `--thinking-mode chat | thinking` |
第四步:进阶玩法
🗨 交互聊天模式:加 --interactive 后进入 REPL,支持多轮上下文,/exit 退出、/clear 清空会话:
torchrun --nproc-per-node 8 generate.py \
--ckpt-path /path/to/DeepSeek-V4.1-Flash-TP8 \
--config config.json \
--interactive \
--temperature 0.6
🖥 多机推理:在 generate.py 前追加标准 torchrun 参数 --nnodes、--node-rank、--master-addr、--master-port 即可横向扩展。
🧪 自检(不需要大显存):model.py 内置自测——构建一个小模型跑 prefill + 22 步 decode,验证 fp8/MoE-fp4 算子链路是否可用:
python inference/model.py
常见问题 FAQ ❓
Q1:run.sh 报 "is missing N of the 8 shards"?
分片缺失。确认 convert.py 的 --model-parallel 与 MP 环境变量一致,且转换完整跑完。
Q2:convert.py 报专家数不能整除?
专家总数 384 必须被 MP 整除,可选 1/2/3/4/6/8/12/16/24/32/48/96/128/192/384,推荐 8。
Q3:这和 vLLM 部署有什么区别?
inference/ 是可逐行阅读的参考实现;生产服务建议用 vLLM(ROCm 镜像),命令见 README.md 的 Deployment 章节。
Q4:视觉输入为什么必须逐条生成? 图片片段必须在一次 prefill 中处理,所以含图 prompt 会逐条推理,纯文本 prompt 则可批量。
Q5:想复现精度评测? 仓库 evaluation/ 提供 lm-eval + vLLM 的 GSM8K 复现说明与补丁。
写在最后
恭喜,你已经用一个脚本跑通了 DeepSeek-V4.1-Flash-Quark-PTPC-FP8 的最小推理!接下来推荐两条路线:
- 打开 inference/model.py 通读架构实现,对照 inference/config.json 里的超参数理解每个模块;
- 阅读 inference/README.md 完整文档,迁移到自己的图文任务上。
Happy LLM hacking 🎉
