前言¶
在 DSH 工作流里做模型推理部署，量化往往是必经一步：用 PTQ 把 checkpoint 压到 INT4 等档位，再在 vLLM 一类服务上验证吞吐。常见做法是直接跑 llmcompressor 或 AutoAWQ 配方，看困惑度掉多少、压测快多少——但「数字好看」不等于「测量成立」：截断或权重异常的源模型可能输出均匀分布，困惑度与基线逐位相同，会被误签成「零精度损失」。inference-quantization 是维护者 xiciyang 发布的 DSH 工作流类插件，定位是量化之外的「证明层」：无泄漏校准切分、独立精度与性能门禁、有界自动降级、哈希链审计与回滚；默认在容器内用 llmcompressor 做 AWQ + INT4，真机路径需要 GPU、Docker 与已验证的量化镜像。
这是什么¶
一句话：给 checkpoint、精度容忍与性能目标，跑 PTQ 并过双门禁签收，或得到明确失败码。
- 插件名称：
xiciyang/inference-quantization（npm 包@xiciyang/inference-quantization，版本 0.1.0） - 维护者：xiciyang
- 分类：工作流（社区目录 SkillHub 插件页）
- 源码：GitHub — xiciyang/inference-quantization
- 运行时：Node 内建模块，零额外 npm 依赖；引擎要求 Node
>=20.11.0，DSH>=0.2.0 <0.3.0；许可证 MIT
若你只需要量化脚本本身，README 明确说明本插件不合适——它不负责替代 llmcompressor 配方，而是围绕量化做门禁、降级、审计与回滚。
核心功能¶
端到端流程¶
下面介绍一次 quantize 跑通时的大致顺序（与 README 流程图一致）：
- 源模型内容哈希基线 + 结构预检（确认是完整模型，而非仅「能打开的文件」）
- 数据集准备：按内容 sha256 去泄漏，校准集与测试集交集必须为空，无人工放行
- 选方法：默认 AWQ + INT4，容器内经 llmcompressor 做 PTQ；源目录只读挂载
- 精度门禁：同一测试集上比较困惑度退化；阈值须调用方传入或来自
gates.yaml，插件内无默认阈值 - 性能门禁：精度通过后，经 MCP 调用
inference-serving起真实端点测吞吐 - 双门禁判定：数值是否达标，且测量是否成立（见下）
- 通过则写入量化矩阵并标记 verified；失败则沿降级链尝试，或回退
两道与「数字」独立的防线¶
| 防线 | 回答的问题 | 失败码 |
|---|---|---|
| 源模型结构预检 | 内容是不是完整模型（截断、整块为零、层数不符、分片缺失等） | E_SOURCE_MODEL_INVALID |
| 测量成立性门禁 | 这次测量成不成立（均匀输出、无区分力、与输入无关、权重不健康、未评到分等） | E_MEASUREMENT_INVALID |
二者不可降级：换量化档位解决不了，会直接中止。status=verified 需数值达标、决策为 sign、且测量成立同时成立。
精度、性能与其它硬门禁¶
- 去泄漏：
E_CALIB_LEAKAGE_DETECTED；判据是内容 sha256 交集为空，宿主侧独立复核容器结论 - 源模型只读：量化前后对源目录做内容哈希；变更则
E_SOURCE_MODEL_MODIFIED - 阈值：未传
--max-accuracy-drop-pct且gates.yaml未配置 →E_THRESHOLD_NOT_PROVIDED - Serving：依赖
inference-serving（MCP）；找不到报E_SERVING_UNAVAILABLE - 镜像：镜像缺失或未验证 →
E_METHOD_UNAVAILABLE，不会静默「通过」
有界降级¶
链路：awq-w4a16(L1) → int8-w8a8(L2) → fp8-dynamic(L3) → w8a16(L4) → QAT 计划(L5) → 回退。最多 5 级；第 5 级只产出 QAT 计划（E_QAT_REQUIRES_APPROVAL），不执行训练。每次运行写入哈希链审计轨迹。
MCP 与验收已有 checkpoint¶
DSH 侧注册工具包括 inference_quantization_quantize、validate、get_report、list、rollback、qat_plan 等。validate（2026-09-29 起）对已存在的量化产出复用与 quantize 相同的门禁语义，不重新量化、不写量化矩阵；记录落在 <runDir>/validate-existing/<id>.json。
安装与启用¶
官方 README 给出两种加入 DSH 的方式：
dsh plugin --profile <name> add github:xiciyang/inference-quantization
从仓库本地打包安装（README 注明尚未发布到 npm，npm install -g 暂不可用）：
git clone https://github.com/xiciyang/inference-quantization.git
cd inference-quantization && npm pack
dsh plugin --profile <name> add ./xiciyang-inference-quantization-0.1.0.tgz
作为 DSH 插件示例：dsh plugin --profile web add <tgz>，重启后生效。
inference-serving 的查找顺序：options.servingPath → ~/.ai-infra/config/serving-path.txt → 同级 ../inference-serving → node_modules/。
典型用法¶
先做环境自检，再验证量化镜像，最后对模型目录发起量化并查看矩阵与报告：
inference-quantization doctor
inference-quantization image verify --build
inference-quantization quantize /path/to/models/<model> \
--max-accuracy-drop-pct 5 --min-perf-gain-pct 20
inference-quantization list --json
inference-quantization report <runId>
常用子命令还包括：dataset prepare|verify|list、rollback <selector>、qat（仅计划）、audit-verify、contract。退出码：0 成功，1 业务失败，2 用法错误，3 需要确认。
首次运行会在 ~/.ai-infra/config/gates.yaml 生成空模板；max_accuracy_drop_pct / min_perf_gain_pct 为 null 时必须在 CLI 显式传参。DSH 行内 config 可设 root、quantImage、outputRoot、servingPath、maxDegradeSteps 等字段，未知键或类型错误会在加载期失败。
适用场景与注意¶
适合：需要在 DSH / MCP 工作流里把「量化 + 精度证明 + 真机性能证明 + 审计」绑成一条可回滚流水线，且能接受 GPU、Docker 与 inference-serving 前置条件的团队。
不适合：只想本地试 AWQ 配方、不关心泄漏切分、门禁与审计的场景——直接用 llmcompressor 更轻。
安全与权限：插件以当前 DSH 进程权限运行；manifest.yaml 对白名单能力做了分级（如 quantize 涉及 model:read、gpu:write、disk:write 等）。安装前请阅读源码与 MIT 许可证，确认镜像来源与网络策略符合你的环境。社区目录 SkillHub 是独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
inference-quantization 把 PTQ 包进可证明的流程：无泄漏校准、独立精度与性能门禁、测量成立性校验、有界降级与哈希链审计。需要试用或查命令细节时，可看 SkillHub 目录页 与 GitHub 仓库 README。
