企业官网建设流程全解析

如何用 NInfer 转换与量化你的模型权重：自定义 Recipe 完整教程

【免费下载链接】ninferHigh-performance single-GPU inference for selected model checkpoints and GPUs.项目地址: https://gitcode.com/gh_mirrors/ni/ninfer

NInfer 模型权重转换与量化是这套高性能单卡推理引擎的核心工具链：通过 Pythonrecipe（配方）描述每一组权重的存储格式、量化方法和数据来源，一条命令即可把本地 checkpoint 转换成 NInfer 专属的.ninfer推理制品（artifact）。无论你是想直接用官方配方一键转换，还是想为某些层定制量化精度、引入外部量化好的权重，本教程都会带你从命令参数到自定义 recipe 函数一步步走通。

🎯 转换工具能做什么？

NInfer 的转换器位于 tools/convert/，官方文档见 docs/weight-conversion.md。它做的事情可以概括为三步：

1. 读取逻辑参数：把 checkpoint 中的权重映射为逻辑参数名（如text/layers/0/mlp/down）；
2. 按 recipe 编码：为每个参数选定格式（Q4/Q5/Q6/Q8、FP8、NVFP4 等）、量化方法和数据来源；
3. 写入制品：生成包含模型配置、编码后权重、逻辑绑定和前端资源（分词器、chat template 等）的.ninfer文件。

如果你转换时选择了vision组件，最终得到的制品就能处理上面这类图片输入——这正体现了转换时"组件选择"的意义。

📋 准备环境：3 个要点

• Python 3.11+ PyTorch + NumPy（转换是纯 Python 工具，不依赖 CMake 构建）；
• 默认使用CUDA 加速转换，显存紧张时可加--device cpu；
• 所有命令从仓库根目录执行，--model指向本地 checkpoint 目录（支持索引分片的 Safetensors）。

🚀 一步到位：用官方 recipe 转换

NInfer 内置了 5 个官方配方，源码都在 tools/convert/official_recipes.py。以 Qwen3.6-27B 浮点权重为例：

python3 -m tools.convert \ --model /path/to/Qwen3.6-27B \ --recipe qwen3_6_27b \ --components text,vision,mtp \ --resource chat_template.jinja=tools/chat_templates/qwen3_6.jinja \ --proposal \ --name qwen3.6-27b \ --out models/qwen3_6_27b.ninfer

各官方配方选择的量化策略速览：

💡两个实用参数：

• --components默认只有text，按需加入vision、mtp、dflash等可选组件；
• --proposal会额外写入索引式 proposal head（投机解码用），普通全词表输出头仍然保留。

对于已经量化好的 checkpoint（如 NVFP4 版本），用--source quantized=PATH指向量化源，import_encoded方法会直接搬运已编码的码字和缩放因子，不会先反量化再重新量化，保证精度无损迁移。

✂️ 自定义 recipe：只改你想改的部分

这是本教程的核心。recipe 就是一个普通的 Python 函数，默认入口名为configure，接收三个参数：model（逻辑模型）、recipe（配置对象）、sources（数据源）。

假设你想在官方qwen3_6_27b配方基础上，把第 0 层 MLP 的 down 投影升级为 Q6 精度，只需保存为my_recipe.py：

from tools.convert.official_recipes import qwen3_6_27b def configure(model, recipe, sources): qwen3_6_27b(model, recipe, sources) recipe.assign( "text/layers/0/mlp/down", format="q6_g64_fp16", method="grouped_absmax", )

然后照常运行，把--recipe指向这个文件即可。

recipe.assign是定制的主力 API，几个关键点（实现见 tools/convert/recipe.py）：

• 选择器支持通配符：可传单个名字、名字列表，或 shell 风格模式如text/layers/*/mlp/down；匹配不到任何参数会直接报错；
• 只替换显式给出的选项：后一次 assign 只覆盖你写出的字段，其余保持原样；
• format 与 method 相互独立：改了format不会自动改method，两者要配套；
• rows=(begin, end)可分行定制：比如rows=(0, 128)只给前 128 行换格式，会自动拆成多个物理片段；
• layout="auto"让转换器按格式自动挑选已注册的物理布局。

还有一个更轻量的玩法：--override FILE。它接受一个只做"改动"的 Python 文件，在官方 recipe（和 proposal 设置）之后执行，适合不想复制整个配方的场景。

🧩 进阶三件套：方法、数据源与资源

1. 写自定义量化方法

内置方法覆盖不了时，你可以传一个可调用对象作为method。方法接收PrepareRequest，返回request.job(produce=...)；produce函数里按块读取源数据，用output.write_codes写入码字和缩放因子（字节打包逻辑由框架完成，方法无需重复实现）。例如给分组量化加一个显式裁剪阈值，只需几十行 Python。

2. 引入其他 checkpoint

重复使用--source NAME=PATH可加入命名数据源。recipe 中用model.source(name, sources["alternate"])把某个逻辑参数换成兼容 checkpoint 里的对应张量，架构映射（含 Q/gate 拆分）会自动处理。对于特殊文件格式，还可以自己实现LogicalSource（定义见 tools/convert/sources/logical.py）——它的read_values只需按 C 顺序返回一段平面数值即可。

3. 替换前端资源

--resource ROLE=PATH可替换分词器、chat template 等资源。官方转换使用的维护模板在 tools/chat_templates/ 下，如 qwen3_6.jinja 和 qwen3_8.jinja，默认开启 thinking。

🔍 转换完成后：检查制品

转换会在制品旁生成*.conversion.json报告，记录数据源、方法、格式、组件配置和耗时，方便复现 recipe。用内置的 inspect 工具可离线校验内容（无需跑推理）：

python3 -m tools.artifact.inspect models/my_qwen.ninfer --objects --bindings

它会汇总对象数、张量数、格式与布局分布等信息。注意：转换器的校验不等于 Op 运行时支持——某个组合真正能不能跑，要以 CLI 或 serve 实际启动验证为准。

🛠️ 常见问题速查

数值格式（Q4 组大小、FP8 行缩放、NVFP4 块缩放等）的精确定义见 docs/maintainer/tensor-formats.md，格式注册表实现在 tools/artifact/formats.py。

✅ 小结

• 一条命令 + 官方 recipe = 最快的转换路径；
• 自定义 recipe = 先调用官方配方，再用recipe.assign精准覆盖，支持通配符、分行定制和自定义量化方法；
• --override让"小改动"不需要维护整份配方；
• 转换完记得用 inspect 工具核验，并用 CLI/serve 实际跑一遍确认 Op 支持。

掌握这套配方机制后，你就能为任何受支持的 checkpoint 量身打造最合适的量化方案了。

【免费下载链接】ninferHigh-performance single-GPU inference for selected model checkpoints and GPUs.项目地址: https://gitcode.com/gh_mirrors/ni/ninfer