quark-torch-llm-ptq

Quark Torch PTQ

用途

将 PyTorch / Hugging Face 大模型从模型识别推进到确认 AMD Quark PTQ。通过一个独立完整的工作流，完成信息收集、规划、清单生成、执行和输出验证。

此技能仅处理量化后的模型。不接受 .onnx 模型输入，不会训练或微调模型，也不会修改 Quark 软件包或源文件。

先决条件

• Python 3.11 至 3.13、与加速器匹配的 PyTorch 2.2 或更高版本、amd-quark[cli] 和 datasets。
• 所需的 ROCm 版本和 GPU 架构取决于 PyTorch 构建版本和所选量化方案。记录实际运行环境、GPU 架构（在 AMD 上从 gcnArchName 获取 gfx...）、主机内核和驱动程序，并验证其是否支持已确认的计划。
• 不需要容器镜像。如果在容器中运行，请在可获取时记录其镜像名称或摘要，并验证 GPU 设备访问权限。
• 检查并保留 HIP_VISIBLE_DEVICES、CUDA_VISIBLE_DEVICES、HSA_OVERRIDE_GFX_VERSION、PYTORCH_ROCM_ARCH 和 PYTORCH_HIP_ALLOC_CONF。在已确认的计划中，注明对设备可见性、架构或内存分配的任何必要更改。

输入

• 模型来源：Hugging Face 仓库 ID 或本地模型目录。
• 输出目录。
• 量化意图：所需精度／方案、目标硬件、准确度优先级，以及可选的校准设置。
• 可选环境信息：Python、PyTorch、加速器、可用内存、已安装的 amd-quark 和 Transformers 版本。

不要要求用户预先准备工作流产物。按照此技能的本地参考文件，在用户的工作目录中创建所有产物：

• references/model-intake.md
• references/quant-plan.md
• references/environment.md
• references/troubleshooting.md

输出

在执行前或执行期间生成以下三个产物：

1. model_analysis.json，并根据 references/contracts/model_analysis.schema.json 验证。
2. quant_plan.json，并根据 references/contracts/quant_plan.schema.json 验证。
3. run_manifest.yaml，并根据 references/contracts/run_manifest.schema.json 验证。

量化后的模型及其配置／分词器文件将写入已确认的输出目录。在清单中记录实际文件和最终状态。

交互流程

始终按顺序完成以下四个步骤。展示具体事实、产物和命令。每个检查点都必须停下并等待用户。

步骤 1 — 模型信息收集

1. 确认模型来源是本地还是远程。对于本地来源，将其解析为绝对路径，并验证目录和 config.json 均存在。对于远程来源，保留仓库 ID。
2. 按照 references/model-intake.md 操作。仅读取配置；信息收集期间不要加载模型权重。
3. 确定 model_type、架构／加载提示、隐藏层信息、多模态或 MoE 信号、默认排除项、兼容性风险，以及可量化线性层数量的合理估算。
4. 编写符合架构的 model_analysis.json 并展示其摘要。

检查点 1 — 确认模型分析

请用户确认或更正模型分析。

在用户确认之前，不要规划量化。

步骤 2 — 量化计划

1. 遵循 references/quant-plan.md，并结合已确认的分析结果和用户的优先事项。
2. 选择并说明全局方案、可选的 KV-cache 方案、按模式覆盖的设置、排除项、算法和校准数据。
3. 将方案、算法和模型模板支持视为与版本相关。需要核实选项时，使用当前安装的 Quark API 或 quark-cli torch-llm-ptq --help；不要依赖历史列表中的项目数量。
4. 显示决策表，编写符合架构的 quant_plan.json，并在获得批准前将 requires_confirmation: true 设为 true。

检查点 2 — 确认量化计划

请用户确认或调整完整计划。

确认后，将 requires_confirmation 更新为 false。如果用户更改了某项决策，请在继续前重写并重新验证计划。

步骤 3 — 清单与执行确认

使用由 amd-quark[cli] 安装的公开 quark-cli torch-llm-ptq 命令。不要直接导入其实现模块，也不要查找、复制、生成或修改其他 PTQ 运行器。

构建一个参数数组安全的等效命令：

quark-cli torch-llm-ptq \
  --model_dir "<MODEL_OR_ABSOLUTE_LOCAL_PATH>" \
  --output_dir "<ABSOLUTE_OUTPUT_PATH>" \
  --quant_scheme "<SCHEME>" \
  --num_calib_data "<N>" \
  --seq_len "<LENGTH>" \
  --device cuda \
  --no_trust_remote_code

仅添加已确认的选项：

• 当计划将其更改为非 CLI 默认值时，添加 --dataset <NAME> 和 --batch_size <N>。
• 对于已确认的 KV-cache 量化，添加 --kv_cache_dtype <SCHEME>。
• 对每项覆盖设置添加一个 --layer_quant_scheme <PATTERN> <SCHEME>。
• 必要时添加 --quant_algo <comma-separated-list>。
• 仅在覆盖模板默认值时添加 --exclude_layers <patterns...>。
• 仅当已了解其限制时，添加 --multi_device。
• 除非用户明确同意执行远程模型代码，否则添加 --no_trust_remote_code。省略此标志时，CLI 会信任远程代码。
• 当请求的范围严格限定于模型输出时，添加 --skip_evaluation。
• 使用非 CLI 默认支持的数据集进行评估时，添加 --evaluation_dataset <NAME>。

将本地模型和输出目录解析为绝对路径，然后为所有由用户控制的路径和值添加引号。在 ROCm 上，--device cuda 仍是 PyTorch 对设备的写法；如需指定 GPU，请使用 HIP_VISIBLE_DEVICES。从提供 amd-quark 的同一 Python 环境中解析 quark-cli。

编写 run_manifest.yaml，其中包含：

• workflow: quark-torch-ptq
• 输入和输出路径；
• 所有四项检查点的原因；
• 生成 model_analysis.json 的分析步骤；
• 生成 quant_plan.json 的计划步骤；
• 生成 run_manifest.yaml 的生成步骤；
• 包含确切命令和预期输出目录的运行步骤。

使用 references/environment.md 确认环境后，再显示命令。缺少软件包或 PyTorch 构建与加速器不匹配的问题应在此处暴露，而不是等到执行关卡之后。

显示完整命令、目标位置、预估资源需求、远程代码选项和预期输出。

检查点 3 — 批准执行

询问：“要运行这条确切的命令吗？”

这是执行关卡。未获得明确批准（例如“是”、“运行吧”或“执行”）时，不要创建输出目录、下载模型权重、更改环境或运行 PTQ。先前对计划的确认不等于批准执行。

步骤 4 — 执行并验证

仅在检查点 3 获得批准后：

1. 如有需要，创建输出目录。
2. 运行已确认的确切 quark-cli 命令。
3. 监控输出。若失败，请停止；收集命令、退出状态、完整错误、版本和资源状态，然后参考 references/troubleshooting.md。切勿盲目重试。
4. 成功后，检查输出目录，并报告实际的模型分片、配置文件和分词器文件、大小、格式以及所请求的指标。
5. 使用观测到的状态和输出更新 run_manifest.yaml，但不要更改记录的命令。

检查点 4 — 接受已验证的结果

展示已验证的结果，并请用户接受，或提出范围明确的后续请求。

不要仅凭退出状态就声称成功。如果缺少预期文件，请报告部分成功或失败，并保留诊断信息。

恢复

• 缺少或无效的产物：根据相应的本地参考重新生成，并依据本地架构进行验证；不要为了绕过验证错误而编造字段。
• 输入信息不确定：将 analysis_status 标记为 partial，记录一项风险，并询问缺失的信息。不要仅为填充元数据而加载权重。
• 不支持的模型类型或方案：报告已安装的 Quark 证据，并询问是否更改计划。不要修改已安装的 CLI。
• 内存不足或设备故障：保留失败的清单，并提出最小幅度的计划调整，例如减少校准样本、缩短序列长度或使用多设备执行。返回检查点 2。
• 依赖项或兼容性故障：显示已安装和所需的确切版本。获得确认后再更改软件包，然后返回检查点 3，并记录一条新命令。
• 用户更改意图：返回最早受影响的检查点，并保留仍然有效的产物。绝不要绕过执行确认。