MetaX Model Preflight

面向 vLLM-MetaX 的量化 checkpoint 静态预检工具。在模型进入 C500 加载流程前， metax-model-preflight lint 读取 config.json、权重索引和 safetensors header，提前报告 GPTQ/AWQ 权重结构及目标张量并行契约中的确定问题。

它不会在主路径加载权重、导入 vLLM/torch、探测 GPU 或运行推理；默认也不会联网下载模型。一次静态 PASS 只说明已覆盖的 checkpoint 契约成立，不是 C500 部署认证。

安装

要求 Python 3.10 或更高版本。v0.1.0 从固定 tag 安装，不依赖 PyPI：

git clone --branch v0.1.0 --depth 1 \
  https://github.com/xzh25/metax-model-preflight.git
cd metax-model-preflight
python -m pip install .

需要参与开发时再从 main 建立工作分支，并使用 python -m pip install -e ".[dev]"。MetaX runtime、vLLM-MetaX、torch 和 mcoplib 不属于静态 lint 的依赖。

最短使用路径

对准备以 TP2 运行的本地 Qwen2 GPTQ/AWQ checkpoint 执行检查：

metax-model-preflight lint /path/to/model \
  --tensor-parallel-size 2 \
  --target-vllm-version 0.20.0

命令直接输出结论、稳定 rule ID、事实说明和处理建议。自动化场景使用机器可读输出：

metax-model-preflight lint /path/to/model \
  --tensor-parallel-size 2 \
  --target-vllm-version 0.20.0 \
  --format json > lint-report.json

如需先验证命令行为，可生成不含第三方权重的合成 checkpoint：

python examples/create_synthetic_fixture.py /tmp/mxpf-model \
  --profile clean --family gptq
metax-model-preflight lint /tmp/mxpf-model \
  --tensor-parallel-size 2 \
  --target-vllm-version 0.20.0

合成样例用于验证解析与规则边界，不构成真实模型在 C500 上可运行的证据。

解决的问题

量化模型的配置、packed tensor shape、分组参数和目标 TP 切分之间可能存在确定性冲突。直接启动 vLLM-MetaX 时，这类问题需要经过进程初始化、设备占用和模型加载流程后才会暴露。本项目把可由 checkpoint metadata 与已审阅源码契约判定的部分提前到静态阶段：

解析本地模型目录或 Hugging Face 缓存中的固定 revision；
交叉核对配置、index、shard 列表和实际 safetensors header；
检查 GPTQ/AWQ tensor 的精确命名、必需成员、格式参数、dtype 和 packed shape；
根据目标 vLLM 版本检查 Qwen2 七个量化投影的 TP 输入、输出与 head 拓扑约束；
以同一份 finding 数据生成文本或 JSON，并保留规则集版本、来源和摘要。

默认不执行 checkpoint 内的 Python 代码，不物化 tensor payload，也不修改、转换或重新量化模型。远端模型只有已经存在于 Hugging Face 缓存时才会被解析；缺失 snapshot 必须通过 --allow-download 显式允许下载。

v0.1.0 精确支持契约

Route B 的稳定静态规则面限定如下：

维度	v0.1.0 范围
量化 family	GPTQ、AWQ
模型架构	`architectures[0]=Qwen2ForCausalLM`，且 `model_type=qwen2`
目标 vLLM	精确版本 `0.17.0`、`0.18.0`、`0.19.0`、`0.20.0`
版本形式	稳定 `X.Y.Z`，可附带 `+local` build 后缀；按规范化后的精确版本选择契约
量化 tensor 后缀	精确小写 `.qweight`、`.qzeros`、`.scales`；别名和大小写变体不纳入稳定契约
GPTQ 格式	bits 为 `2/4/8`、`desc_act` 为 bool、I32 `qweight/qzeros`、F16/BF16/F32 `scales`
AWQ 格式	bits 为 `4`、`zero_point` 为 bool、I32 `qweight/qzeros`、F16/BF16/F32 `scales`；`version` 不参与稳定契约
TP 检查对象	每层七个量化投影；contract ID 为 `qwen2-linear-input-partition-v1`
TP1	所有投影检查 full-input group 与 packed output
TP>1	检查 row/column input、packed output、attention head 以及 KV partition/replication
权重证据	config、index/shard 一致性及 safetensors header；不读取 tensor payload
稳定规则	`MXPF-WEIGHT-001`、`MXPF-WEIGHT-002`、`MXPF-WEIGHT-003`

静态 PASS 还要求 num_hidden_layers 可核验，并且每层 Qwen2 的 q_proj/k_proj/v_proj/o_proj/gate_proj/up_proj/down_proj 七组量化投影完整。缺少整层或完整投影组时保持 UNKNOWN，不会只根据已经出现的 tensor group 推断 checkpoint 完整。这里的“完整”只指七组量化投影；embed_tokens、norm、lm_head 等非量化权重不在当前完整性检查范围内。

无论 TP1 还是 TP>1，稳定 lint 要得到 PASS 都必须取得一个落在上述范围内的精确目标版本。显式 --target-vllm-version 优先；未传入时，工具只通过 Python distribution metadata 观察已经安装的 vLLM 版本，不导入 vLLM。目标版本缺失、格式不稳定或未覆盖时返回 UNKNOWN。

版本未覆盖、架构不适用、格式无法识别、tensor 覆盖不完整或事实无法核验时，工具返回 UNKNOWN，不会从相近版本或相似模型推断兼容。完整规则与来源见 Route B 规则目录。

GPTQ 的非空 dynamic、modules_in_block_to_quantize、lm_head，以及 AWQ 的非空 modules_to_not_convert 尚未被检查器建模，因此返回 UNKNOWN。checkpoint_format 的已识别拼写只是本工具的审阅边界，不是 upstream vLLM 或 MetaX 发布的穷尽官方枚举。

官方源码关系审计显示，vLLM-MetaX 通过 adapter 插件接入同版本 upstream vLLM，并复用其 from_config、get_config_filenames 和 create_weights 实现，不是包含完整量化实现的独立 fork。因此 0.17.0—0.20.0 表示静态源码契约范围；仓库引用的真实 C500 runtime 证据目前只对应 0.17.0。无论版本是否在静态范围内，lint PASS 都只表示静态契约成立。

`PASS / FAIL / UNKNOWN`

静态规则和 lint 聚合结论严格使用三态：

状态	含义	`lint` 退出码
`PASS`	本次适用的稳定静态契约及其必需前提均有完整证据并成立	`0`
`FAIL`	至少存在一项规则覆盖范围内、可复核的确定性矛盾	`1`
`UNKNOWN`	版本、格式、权限、字段、tensor 或可信来源不足，无法可靠判定	`3`

UNKNOWN 既不是成功，也不是失败；CI 可以选择阻断它，但不应将其改写为 FAIL。命令行参数错误由 argparse 返回 2；可处理的输入或系统错误返回 64，未预期的内部错误返回 70。高级 doctor 为兼容既有证据流使用 PASS=0、FAIL=2、 UNKNOWN=3，调用方不要复用 lint 的退出码映射。

静态 `lint` 与高级 `doctor`

能力	`lint`（主入口）	`doctor`（高级证据流）
checkpoint 静态规则	是	是
MetaX 软件环境	不采集	采集
capability preview	不使用	可选
`mx-smi` 硬件探测	不执行	仅显式 `--probe-hardware`
C500 runtime	不执行	仅显式门禁后执行
输出	stdout 文本或 JSON	带 manifest 的证据目录

不涉及 GPU 的高级证据包：

metax-model-preflight doctor /path/to/model \
  --output-dir /path/to/new-evidence

默认 doctor 仍不调用 mx-smi。C500 最小运行必须同时指定 --probe-hardware --run-runtime，并设置 METAX_PREFLIGHT_ENABLE_GPU=1；该路径只适合已准备好 MetaX 官方运行栈的受控 GPU 环境。runtime 成功只适用于报告记录的精确模型、软件、硬件和参数组合。

已有证据可独立复核 Schema、manifest、摘要和 staleness inputs：

metax-model-preflight check-report /path/to/evidence/report.json

VALID / STALE / UNKNOWN 是报告有效性，不是部署状态。完整语义见状态与最终判定。

导出可分享的支持材料

export-support 从既有 doctor 报告派生适合 Issue 或支持工单的较小副本：

metax-model-preflight export-support /path/to/evidence \
  --output-dir /path/to/new-support-bundle

输出目录必须不存在，原证据不会被修改。派生包只包含：

new-support-bundle/
├── report.json
├── report.txt
└── manifest.json

默认策略删除内部扩展、主机和用户身份、绝对路径、credential-like 值以及 runtime stdout/stderr/traceback，不复制原始日志。它不是通用数据防泄漏系统，公开提交前仍需人工检查三个文件。字段与边界见支持材料导出。

设计边界

本项目提供“加载前静态判定 + 可选高级证据流”，明确不做以下工作：

不替代 vLLM-MetaX、MetaX runtime、mcoplib 或生产压测；
不维护模型下载器、权重缓存、转换器或重新量化工具；
不把 provisional/observed 数据扩展成官方或穷举支持矩阵；
不把一次 runtime 观测外推到其他 revision、TP、软件栈或硬件环境；
不在仓库中保存模型权重、完整 GPU 证据、远端凭据或原始私有日志。

这是由社区维护的非官方工具，不代表 MetaX、vLLM-MetaX、mcoplib 或 kernel 团队的兼容性认证。

仓库目录索引

路径	功能
`src/`	可安装的 Python 包：CLI、模型解析、静态规则、MetaX 事实、runtime 适配与报告
`tests/`	CPU 单元、契约、集成与回归测试；GPU 用例有独立 marker 和显式门禁
`schemas/`	lint report、capability、evidence report 与 regression case 的公开 JSON Schema
`data/`	版本化规则目录和 capability manifest；不存放模型或运行产物
`cases/`	脱敏回归 case、期望 finding、外部证据 digest 与来源索引
`examples/`	可重建的合成 checkpoint、示例报告和最短操作说明
`docs/`	架构、规则、状态语义、CPU/GPU 工作流、维护和支持材料说明
`scripts/`	CPU 检查、显式 GPU 验证及维护者使用的高层入口
`tools/`	窄范围维护工具；`tools/remote/` 提供默认 dry-run 的远端编排
`constraints/`	CPU 开发依赖与 MetaX runtime 包之间的兼容边界
`.github/`	CPU CI、Issue 表单、PR 模板和 CODEOWNERS

根目录中的 pyproject.toml 定义包和工具配置；CONTRIBUTING.md、MAINTAINERS.md、 SECURITY.md 与 CHANGELOG.md 分别定义协作、维护、安全和版本记录； MetaX_Model_Preflight_项目说明书.md 保存项目范围与验收基线。运行生成的 evidence/、artifacts/、日志、虚拟环境和模型权重均不进入 Git。