quark-install

Quark 安装

目的

无需依赖其他技能、Quark 检出目录或预生成的工作流产物，即可安装或验证 amd-quark。检测实际硬件，确保 PyTorch 与硬件匹配，选择最精简且安全的 Quark 安装方式，获取批准、执行安装，并验证所需功能。

先决条件

• GPU 支持取决于所选 PyTorch 构建版本和 Quark 轮子。记录实际运行时、主机内核和驱动程序，以及 GPU 架构（AMD 上从 gcnArchName 获取 gfx...）；根据该环境验证兼容性，不要假设使用固定的 ROCm 版本或 GPU 目标。
• 无需容器镜像。如果在容器中运行，请在可用时记录其镜像名称或摘要，并验证 GPU 设备访问权限。
• 检查并保留 QUARK_ACCELERATOR、PYTORCH_ROCM_ARCH、QUARK_BUILD_DISABLE_JIT_FALLBACK、HSA_OVERRIDE_GFX_VERSION、HIP_VISIBLE_DEVICES 和 CUDA_VISIBLE_DEVICES。将所需的任何更改纳入已确认的安装计划。对于 PIP_EXTRA_INDEX_URL，仅报告其已设置或未设置，因为其值可能包含凭据。

输入

• 要修改的 Python 解释器或环境。默认使用当前活动的解释器，但必须明确其解析后的路径。
• 请求的 Quark 来源：现有环境、PyPI、AMD 原生轮子索引、本地轮子或本地源代码目录。默认使用通用 PyPI 轮子。
• 可选的版本约束。
• 计算意图：默认使用 GPU；只有在用户明确确认后才使用 CPU。
• 所需功能：基本 Quark 导入、Quark PyTorch 内核、ONNX 自定义算子或 quark-cli。

不要要求预先存在环境或安装结果产物。用户提供的轮子或源代码目录属于输入，不是技能依赖项。

输出

在终端结果确定时，始终在用户的工作目录中写入 quark_install_result.json，并根据 references/contracts/quark_install_result.schema.json 验证它。

保留兼容性字段 status、quark_version、install_source、extras_installed、verification 和 failure_reason。同时记录解析后的解释器、导入的 Quark 模块路径、PyTorch 版本和后端、GPU 是否可用、是否明确确认了 CPU 模式、实际执行的命令，以及 pip check 结果。

• 仅当安装成功且所有请求的验证均通过时，才使用 status: "ok"。
• 当现有安装经验证满足要求，或用户拒绝更改时，使用 status: "skipped"。
• 安装或验证失败时，使用 status: "failed"，并提供准确的失败命令和错误。
• 未请求的可选检查设为 null；不要仅因 quark-cli --help 可用就报告 llm_ptq_deps: true。

安装规则

• Quark 需要 Python 3.11、3.12 或 3.13，以及 PyTorch 2.2 或更高版本。

• amd-quark 运行时 wheel 不会安装 PyTorch。安装 Quark 前，请先解决并验证 PyTorch。

• 默认使用 GPU。仅有 CUDA/ROCm 构建标签并不足够：GPU 就绪需要满足 torch.cuda.is_available()、设备数量大于 0，并且能在 cuda 上成功执行张量运算（PyTorch 对 CUDA 和 ROCm 都使用此设备名称）。

• 如果缺少 PyTorch、仅支持 CPU、后端不匹配，或无法访问 GPU，请停止并询问是否安装/修复匹配的 GPU 构建，或明确继续使用 CPU 模式。绝不能默默安装或接受 CPU 模式。

• 仅从与检测到的 CUDA/ROCm 支持相匹配的官方索引安装 GPU 版 PyTorch。先查询可用版本，选择满足 torch>=2.2 且兼容 Python 的稳定版本，展示确切命令并获得批准：

  "<PYTHON>" -m pip index versions torch --index-url "https://download.pytorch.org/whl/<GPU_INDEX>"
  "<PYTHON>" -m pip install "torch==<VERSION>" --index-url "https://download.pytorch.org/whl/<GPU_INDEX>"
  

• 在明确确认使用 CPU 模式后，请使用官方 CPU 索引，而不是不指定索引的 PyPI 安装：

  "<PYTHON>" -m pip install "torch==<VERSION>" --index-url "https://download.pytorch.org/whl/cpu"
  

• 通用 PyPI wheel 是安全的默认选择。它支持不同的 PyTorch 后端，但首次使用时会编译 Quark 内核/自定义算子，因此可能需要 C++ 编译器以及 nvcc 或 hipcc：

  "<PYTHON>" -m pip install "amd-quark"
  

• Quark Torch 导入目前需要 Transformers，即使基础 amd-quark wheel 可能未声明此依赖。当用户要求验证内核且缺少 Transformers 时，请预览并确认安装与发布版本/模型兼容的版本；除非已知有更严格的要求，否则当前上限使用 "transformers<5.16"。将缺少 Transformers 模块视为依赖故障，而非编译器故障。

• 原生 wheel 的可用性因发布版本而异。绝不要根据硬编码矩阵或单独使用 --extra-index-url 选择。只能使用已观察到的候选项，其文件名/本地版本必须与当前 PyTorch 主次版本、CUDA/ROCm 主次版本（或 CPU）、CPython 标签、操作系统和架构完全匹配；使用 === 固定其完整版本：

  "<PYTHON>" -m pip install "amd-quark===<FULL_VERSION_WITH_VARIANT>" --index-url "<AMD_INDEX_URL>" --extra-index-url "https://pypi.org/simple"
  

• 对用户提供的原生 wheel 执行相同的 ABI 检查。py3-none-any wheel 是通用 wheel。对于可信的本地输入：

  "<PYTHON>" -m pip install "<ABSOLUTE_WHEEL_PATH>"
  "<PYTHON>" -m pip install --no-build-isolation "<ABSOLUTE_SOURCE_DIR>"
  

• 仅当目录中包含 pyproject.toml 或 setup.py、PyTorch 已通过验证，且用户明确信任并要求执行该源代码时，才使用源码形式。

• 仅在用户要求时添加 [cli]。添加前，请检查已安装的 onnxruntime* 发行包和试运行计划，因为当前 CLI 额外依赖可能会添加 CPU 版 onnxruntime；不要默默将其与 onnxruntime-gpu 组合使用，也不要通过 --no-deps 绕过依赖。

• ONNX Runtime 变体的选择不属于此技能的范围。当用户要求使用 ONNX 自定义算子时，请验证并报告已有运行时，但不要默默选择或替换其 CPU/GPU 发行包。

• 始终使用同一个绝对路径 "<PYTHON>" -m pip；绝不要使用未限定的 pip 或 sudo pip。

交互流程

按顺序完成以下步骤。

步骤 1 — 检查环境

将 <PYTHON> 解析为将要修改的确切解释器。路径包含空格时，请加引号。运行只读检查：

"<PYTHON>" -c "import platform, sys; print('executable:', sys.executable); print('prefix:', sys.prefix); print('python:', platform.python_version()); print('os:', platform.platform()); print('machine:', platform.machine())"
"<PYTHON>" -m pip --version
"<PYTHON>" -m pip show amd-quark torch
"<PYTHON>" -c "import torch; ok=torch.cuda.is_available(); n=torch.cuda.device_count(); print('torch:', torch.__version__); print('cuda:', torch.version.cuda); print('hip:', torch.version.hip); print('gpu_available:', ok); print('device_count:', n); print('device:', torch.cuda.get_device_name(0) if ok and n else None)"
nvidia-smi --query-gpu=name,driver_version --format=csv,noheader
rocm-smi --showproductname
hipcc --version

仅运行主机上可用的硬件命令；命令不存在属于证据，不代表获准安装实用程序。接收信息时不要导入可选的 Quark 内核/自定义算子，因为通用 wheel 可能会编译它们。

检查点 1 — 确认计算模式

如果 Python 版本不受支持、PyTorch 低于 2.2、硬件情况不明确、PyTorch 仅支持 CPU、构建系列与检测到的硬件冲突，或 GPU 构建无法访问设备，请在规划 Quark 前停止。

询问：“我发现了 <EVIDENCE>。要安装/修复匹配的 GPU 版 PyTorch，还是你明确希望使用 CPU 模式？”

未经明确答复，不得继续使用 CPU 模式。如果选择 GPU 模式，请展示并批准官方索引的 PyTorch 确切安装命令，然后验证实际的 GPU 张量运算，再继续。

步骤 2 — 选择安装方式

1. 如果已安装合适的 Quark 版本，且未要求升级或重新安装，则跳过安装并继续验证。
2. 优先使用明确指定且已验证的本地 wheel/源码。
3. 仅在完成精确候选项和 ABI 验证后使用原生 wheel；否则使用通用 PyPI wheel。
4. 将请求的版本约束添加到软件包规格中，例如 "amd-quark==<VERSION>" 或 "amd-quark[cli]==<VERSION>"。
5. 使用 "<PYTHON>" -m pip install --dry-run "<PACKAGE_SPEC>" 预览所有必需的软件包变更，包括用于内核的 Transformers。如果不支持 dry-run，应报告此限制，而不要修改环境。
6. 以已安装发行版的元数据为准。不要声称源码树版本或依赖限制适用于其他已发布版本。

步骤 3 — 确认变更

显示：

• 已解析的解释器和环境；
• 检测到的硬件、PyTorch 构建版本、GPU 运行时结果，以及已确认的 GPU/CPU 模式；
• 所选 Quark 来源；如果使用原生 wheel，还要显示所有匹配的 ABI 维度；
• dry-run 依赖变更和确切命令；
• 验证是否可能触发 C++/CUDA/HIP 编译。

询问：“是否要运行这些确切命令？”

CPU 模式的接受和命令执行都需要明确批准。未经批准，不要安装、升级、卸载、调用系统软件包管理器或编译可选组件。

步骤 4 — 安装并验证

获得批准后，仅运行已确认的命令。必要时先安装或修复 PyTorch，并在安装 Quark 前验证所选计算模式。遇到第一个失败时停止，并保留完整输出。对于 wheel 安装，应从任何 Quark 源码检出目录之外的中立目录运行导入验证，并确认导入的模块路径位于所选环境下；对于源码/可编辑安装，应确认模块解析到已确认的源码目录。

运行基本检查：

"<PYTHON>" -m pip check
"<PYTHON>" -c "from importlib.metadata import version; import quark, torch; print('amd-quark:', version('amd-quark')); print('quark:', quark.__version__); print('quark_file:', quark.__file__); print('torch:', torch.__version__); print('cuda:', torch.version.cuda); print('hip:', torch.version.hip)"

对于 GPU 模式，必须执行实际操作：

"<PYTHON>" -c "import torch; assert torch.version.cuda or torch.version.hip, 'CPU-only PyTorch build'; assert torch.cuda.is_available(), 'GPU runtime unavailable'; assert torch.cuda.device_count() > 0, 'No visible GPU'; x=torch.ones(1024, device='cuda'); y=(x*x).sum(); torch.cuda.synchronize(); print(torch.cuda.get_device_name(0), y.item())"

对于请求的 Quark 内核，断言扩展已加载。通用 wheel 使用第一条命令；对于原生 wheel，禁用 JIT 回退，以证明打包的扩展有效：

"<PYTHON>" -c "import quark.torch.kernel; from quark.torch.kernel.hw_emulation import extensions; assert extensions.kernel_ext is not None; print('Quark kernel OK')"
"<PYTHON>" -c "import os; os.environ['QUARK_BUILD_DISABLE_JIT_FALLBACK']='1'; import quark.torch.kernel; from quark.torch.kernel.hw_emulation import extensions; assert extensions.kernel_ext is not None; print('Native Quark kernel OK')"

仅运行其他请求的检查：

"<PYTHON>" -m quark.experimental.cli.main -h
"<PYTHON>" -c "import onnxruntime as ort; from quark.onnx.operators.custom_ops import get_library_path; p=get_library_path('CPU'); so=ort.SessionOptions(); so.register_custom_ops_library(p); print('Quark ONNX custom ops OK:', p)"

不要同时运行两条内核命令。分别报告基础安装、GPU 运行时和可选功能。编写并验证 quark_install_result.json；不要仅凭安装退出代码或构建标签就宣称成功。

恢复

• 仅 CPU 或 GPU 不可用： 保持 GPU 为默认选项，提供硬件、构建和运行时证据，并询问用户是要修复 GPU PyTorch，还是明确接受使用 CPU。不要静默回退。
• 没有完全匹配的原生 wheel： 列出每个不匹配的 ABI 维度，提出使用通用 wheel，并再次请求批准。
• 编译器失败： 通用 wheel 的内核／自定义算子检查可能需要 C++ 编译器以及 nvcc 或 hipcc。报告缺失的工具，并在更改系统前获得批准。
• 缺少 Transformers： 如果未安装 Transformers，Quark Torch 可能会在扩展加载后导入失败。显示确切的 ModuleNotFoundError，预览兼容的 Transformers 安装方案，并在重试前请求批准。
• CLI／ONNX Runtime 冲突： 列出所有已安装或计划安装的 onnxruntime* 分发包。优先使用独立环境，或明确修订计划；绝不要用 --no-deps 隐瞒冲突。
• 依赖或导入失败： 保留 pip check 的结果、确切的失败命令、版本和完整错误信息。优先使用全新环境，而不是强制降级。
• 环境错误或源代码遮蔽： 对比 sys.executable、pip --version、分发包版本和 quark.__file__；从中立目录使用单一绝对解释器路径重新运行 wheel 验证。
• 网络／索引失败： 保留确切的 URL 和错误信息。未经确认，不要切换索引或反复重试。
• 不支持的 Python： 提议创建全新的 Python 3.13 环境，并在获得批准后从步骤 1 重新开始。