quark-install

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Quark Install

Quark 安装

Purpose

目的

Install or verify

amd-quark

without relying on another skill, a Quark checkout, or pre-generated workflow artifacts. Detect the actual hardware, ensure PyTorch matches it, choose the smallest safe Quark install, obtain approval, execute it, and verify the requested capabilities.

安装或验证

amd-quark

，而不依赖其他 skill、Quark 源码检出（checkout）或预先生成的 workflow 产物。检测实际硬件，确保 PyTorch 与其匹配，选择最小且安全的 Quark 安装方式，获取批准、执行安装并验证所请求的能力。

Prerequisites

前置条件

GPU support depends on the selected PyTorch build and Quark wheel. Record the actual runtime, host kernel and driver, and GPU architecture (
```
gfx...
```
from
```
gcnArchName
```
on AMD); verify compatibility with that environment instead of assuming a fixed ROCm version or GPU target.
No container image is required. If running in a container, record its image name or digest when available and verify GPU device access.
Inspect and preserve
```
QUARK_ACCELERATOR
```
,
```
PYTORCH_ROCM_ARCH
```
,
```
QUARK_BUILD_DISABLE_JIT_FALLBACK
```
,
```
HSA_OVERRIDE_GFX_VERSION
```
,
```
HIP_VISIBLE_DEVICES
```
, and
```
CUDA_VISIBLE_DEVICES
```
. Include any required changes in the confirmed install plan. Report
```
PIP_EXTRA_INDEX_URL
```
only as set or unset because its value may contain credentials.

GPU 支持取决于所选的 PyTorch 构建版本和 Quark wheel。记录实际运行时、主机内核和驱动，以及 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
```
的值可能包含凭据，因此仅报告其为已设置或未设置。

Inputs

输入

Python interpreter or environment to modify. Default to the active interpreter, but make its resolved path explicit.
Requested Quark source: existing environment, PyPI, an AMD native-wheel index, a local wheel, or a local source directory. Default to the universal PyPI wheel.
Optional version constraint.
Compute intent: GPU by default; CPU only after explicit user confirmation.
Required capabilities: basic Quark import, Quark PyTorch kernels, ONNX custom operators, or
```
quark-cli
```
.

Do not require pre-existing environment or install-result artifacts. A user-provided wheel or source directory is an input, not a skill dependency.

要修改的 Python 解释器或环境。默认为当前活动的解释器，但必须明确给出其解析后的路径。
要求的 Quark 来源：现有环境、PyPI、AMD 原生 wheel 索引、本地 wheel 或本地源码目录。默认使用通用 PyPI wheel。
可选的版本约束。
计算模式：默认使用 GPU；仅在用户明确确认后使用 CPU。
所需能力：基础 Quark 导入、Quark PyTorch kernel、ONNX 自定义算子或
```
quark-cli
```
。

不应要求预先存在的环境或安装结果产物。用户提供的 wheel 或源码目录属于输入，而不是 skill 依赖项。

Outputs

输出

Always write

quark_install_result.json

in the user's working directory at a terminal outcome and validate it against

references/contracts/quark_install_result.schema.json

Preserve the compatibility fields

status

quark_version

install_source

extras_installed

verification

, and

failure_reason

. Also record the resolved interpreter, imported Quark module path, PyTorch version/backend, GPU availability, whether CPU mode was explicitly confirmed, exact executed commands, and

pip check

result.

Use
```
status: "ok"
```
only when installation and every requested verification pass.
Use
```
status: "skipped"
```
when a suitable existing install is verified or the user declines changes.
Use
```
status: "failed"
```
with the exact failing command and error for install or verification failure.
Set unrequested optional checks to
```
null
```
; do not report
```
llm_ptq_deps: true
```
merely because
```
quark-cli --help
```
works.

始终在用户工作目录中写入

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
```
。

Installation Rules

安装规则

Quark requires Python 3.11, 3.12, or 3.13 and PyTorch 2.2 or newer.
The
```
amd-quark
```
runtime wheel does not install PyTorch. Resolve and verify PyTorch before installing Quark.
GPU is the default. A CUDA/ROCm build tag alone is insufficient: GPU readiness requires
```
torch.cuda.is_available()
```
, a positive device count, and a successful tensor operation on
```
cuda
```
(PyTorch uses this device spelling for both CUDA and ROCm).
If PyTorch is missing, CPU-only, backend-mismatched, or unable to access a GPU, stop and ask whether to install/fix the matching GPU build or explicitly continue in CPU mode. Never install or accept CPU mode silently.
Install a GPU PyTorch build only from an official index matching detected CUDA/ROCm support. Query available versions first, choose a Python-compatible stable release satisfying
```
torch>=2.2
```
, show the exact command, and obtain approval:
bash
```
"<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>"
```
After explicit CPU-mode confirmation, use the official CPU index instead of an unqualified PyPI install:
bash
```
"<PYTHON>" -m pip install "torch==<VERSION>" --index-url "https://download.pytorch.org/whl/cpu"
```
The universal PyPI wheel is the safe default. It supports different PyTorch backends but compiles Quark kernels/custom operators on first use and therefore may require a C++ compiler plus
```
nvcc
```
or
```
hipcc
```
:
bash
```
"<PYTHON>" -m pip install "amd-quark"
```
Quark Torch import currently requires Transformers even though the base
```
amd-quark
```
wheel may not declare it. When kernel verification is requested and Transformers is absent, preview and confirm a release/model-compatible install; use
```
"transformers<5.16"
```
as the current upper bound unless a narrower requirement is known. Treat a missing Transformers module as a dependency failure, not a compiler failure.
Native-wheel availability changes by release. Never select one from a hard-coded matrix or a bare
```
--extra-index-url
```
. Use only an observed candidate whose filename/local version exactly matches the active PyTorch major.minor, CUDA/ROCm major.minor (or CPU), CPython tag, OS, and architecture; pin its complete version with
```
===
```
:
bash
```
"<PYTHON>" -m pip install "amd-quark===<FULL_VERSION_WITH_VARIANT>" --index-url "<AMD_INDEX_URL>" --extra-index-url "https://pypi.org/simple"
```

Apply the same ABI checks to a user-provided native wheel. A

py3-none-any

wheel is universal. For trusted local input:

bash

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

Use the source form only when the directory contains
```
pyproject.toml
```
or
```
setup.py
```
, PyTorch is already verified, and the user explicitly trusts and requests executing that source.
Add
```
[cli]
```
only when requested. Before doing so, inspect installed
```
onnxruntime*
```
distributions and the dry-run plan because the current CLI extra may add CPU
```
onnxruntime
```
; do not silently combine it with
```
onnxruntime-gpu
```
or bypass dependencies with
```
--no-deps
```
.
ONNX Runtime variant selection is outside this skill. Verify and report an existing runtime when ONNX custom operators are requested, but do not silently choose or replace its CPU/GPU distribution.
Always use the same absolute
```
"<PYTHON>" -m pip
```
; never use unqualified
```
pip
```
or
```
sudo pip
```
.

Quark 要求 Python 3.11、3.12 或 3.13，以及 PyTorch 2.2 或更高版本。
```
amd-quark
```
runtime wheel 不会安装 PyTorch。安装 Quark 前必须先解析并验证 PyTorch。
默认使用 GPU。仅凭 CUDA/ROCm 构建标签并不足够：GPU 就绪要求
```
torch.cuda.is_available()
```
返回真、设备数量为正，并且在
```
cuda
```
上成功执行张量运算（PyTorch 对 CUDA 和 ROCm 均使用这一设备名称）。
如果 PyTorch 缺失、仅有 CPU 版本、后端不匹配或无法访问 GPU，请停止并询问是要安装或修复匹配的 GPU 构建，还是明确继续使用 CPU 模式。绝不能静默安装或接受 CPU 模式。

仅从与检测到的 CUDA/ROCm 支持相匹配的官方索引安装 GPU PyTorch 构建。先查询可用版本，选择满足

torch>=2.2

且兼容 Python 的稳定版本，展示确切命令并获得批准：

bash

"<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 安装：

bash

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

通用 PyPI wheel 是安全默认值。它支持不同的 PyTorch 后端，但会在首次使用时编译 Quark kernel 或自定义算子，因此可能需要 C++ 编译器以及
```
nvcc
```
或
```
hipcc
```
：
bash
```
"<PYTHON>" -m pip install "amd-quark"
```
目前 Quark Torch 导入需要 Transformers，即使基础
```
amd-quark
```
wheel 可能没有声明该依赖。请求 kernel 验证且 Transformers 缺失时，应预览并确认与发行版及模型兼容的安装；除非已知有更严格的要求，否则使用
```
"transformers<5.16"
```
作为当前上限。缺少 Transformers 模块应视为依赖项失败，而不是编译器失败。
原生 wheel 的可用性会随发行版变化。绝不能从硬编码矩阵或单独的
```
--extra-index-url
```
中选择原生 wheel。只能使用已观察到的候选版本，其文件名或本地版本必须与当前 PyTorch 的 major.minor、CUDA/ROCm 的 major.minor（或 CPU）、CPython tag、操作系统和架构完全匹配；使用
```
===
```
固定其完整版本：
bash
```
"<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。对于可信的本地输入：

bash

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

仅当目录包含
```
pyproject.toml
```
或
```
setup.py
```
、PyTorch 已完成验证，并且用户明确信任并要求执行该源码时，才可使用源码安装形式。
仅在明确请求时添加
```
[cli]
```
。执行前应检查已安装的
```
onnxruntime*
```
分发包并查看 dry-run 计划，因为当前 CLI extra 可能会添加 CPU 版
```
onnxruntime
```
；不得静默将其与
```
onnxruntime-gpu
```
组合，也不得使用
```
--no-deps
```
绕过依赖项。
ONNX Runtime 变体的选择不属于此 skill 的范围。请求 ONNX 自定义算子时，应验证并报告现有 runtime，但不得静默选择或替换其 CPU/GPU 分发包。
始终使用同一个绝对路径形式的
```
"<PYTHON>" -m pip
```
；绝不能使用未限定路径的
```
pip
```
或
```
sudo pip
```
。

Interaction Flow

交互流程

Complete these steps in order.

按顺序完成以下步骤。

Step 1 — Inspect the environment

第 1 步——检查环境

Resolve

<PYTHON>

to the exact interpreter that would be modified. Quote paths containing spaces. Run read-only checks:

bash

"<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

Run only hardware commands available on the host; command-not-found is evidence, not permission to install utilities. Do not import optional Quark kernels/custom operators during intake because a universal wheel may compile them.

将

<PYTHON>

解析为实际要修改的准确解释器。路径包含空格时应加引号。运行只读检查：

bash

"<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 kernel 或自定义算子，因为通用 wheel 可能会触发编译。

Checkpoint 1 — Confirm compute mode

检查点 1——确认计算模式

Stop before Quark planning if Python is unsupported, PyTorch is below 2.2, hardware is ambiguous, PyTorch is CPU-only, the build family conflicts with detected hardware, or a GPU build cannot access a device.

Ask: “I found

<EVIDENCE>

. Shall I install/fix the matching GPU PyTorch build, or do you explicitly want CPU mode?”

Do not continue in CPU mode without an explicit answer. If GPU mode is selected, show and approve the exact official-index PyTorch command, then verify a real GPU tensor operation before continuing.

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

询问：“我发现

<EVIDENCE>

。是否安装或修复匹配的 GPU PyTorch 构建，还是您明确希望使用 CPU 模式？”

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

Step 2 — Select the install

第 2 步——选择安装方式

If a suitable Quark version is already installed and no upgrade or reinstall was requested, skip installation and proceed to verification.
Prefer an explicitly requested and validated local wheel/source.
Use a native wheel only after exact candidate and ABI validation; otherwise use the universal PyPI wheel.
Add a requested version constraint to the package spec, for example
```
"amd-quark==<VERSION>"
```
or
```
"amd-quark[cli]==<VERSION>"
```
.
Preview every required package change, including Transformers for kernel use, with
```
"<PYTHON>" -m pip install --dry-run "<PACKAGE_SPEC>"
```
. If dry-run is unsupported, report that limitation rather than mutating the environment.
Treat the installed distribution metadata as authoritative. Do not claim the source-tree version or dependency limits apply to a different published release.

如果已经安装了合适的 Quark 版本，且未请求升级或重新安装，则跳过安装并继续验证。
优先使用用户明确请求且已验证的本地 wheel 或源码。
仅在候选版本和 ABI 验证完全通过后使用原生 wheel；否则使用通用 PyPI wheel。
将请求的版本约束添加到包规范中，例如
```
"amd-quark==<VERSION>"
```
或
```
"amd-quark[cli]==<VERSION>"
```
。
使用
```
"<PYTHON>" -m pip install --dry-run "<PACKAGE_SPEC>"
```
预览每一项必要的包变更，包括 kernel 使用所需的 Transformers。如果不支持 dry-run，应报告该限制，而不是修改环境。
以已安装的分发包元数据为准。不得声称源码树中的版本或依赖限制适用于其他已发布版本。

Step 3 — Confirm changes

第 3 步——确认更改

Show:

the resolved interpreter and environment;
detected hardware, PyTorch build, GPU runtime result, and confirmed GPU/CPU mode;
selected Quark source and, for a native wheel, every matched ABI dimension;
dry-run dependency changes and exact commands;
whether verification may trigger C++/CUDA/HIP compilation.

Ask: “Shall I run these exact commands?”

CPU-mode acceptance and command execution both require explicit approval. Do not install, upgrade, uninstall, invoke a system package manager, or compile optional components without it.

展示：

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

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

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

Step 4 — Install and verify

第 4 步——安装并验证

After approval, run only the confirmed commands. Install/fix PyTorch first when required and verify the selected compute mode before installing Quark. Stop on the first failure and preserve full output. For a wheel install, run import verification from a neutral directory outside any Quark source checkout and require the imported module path to reside under the selected environment; for a source/editable install, require it to resolve to the confirmed source directory.

Run basic checks:

bash

"<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)"

For GPU mode, require an actual operation:

bash

"<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())"

For requested Quark kernels, assert that the extension loaded. Use the first command for a universal wheel; for a native wheel, disable JIT fallback to prove the packaged extension is valid:

bash

"<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')"

Run only other requested checks:

bash

"<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)"

Do not run both kernel commands. Report base installation, GPU runtime, and optional capabilities separately. Write and validate

quark_install_result.json

; do not claim success from an install exit code or build tag alone.

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

运行基础检查：

bash

"<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 模式，必须执行实际运算：

bash

"<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 kernel，断言扩展已成功加载。通用 wheel 使用第一个命令；原生 wheel 应禁用 JIT fallback，以证明随包提供的扩展有效：

bash

"<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')"

仅运行其他明确请求的检查：

bash

"<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)"

不要同时运行两个 kernel 命令。分别报告基础安装、GPU 运行时和可选能力。写入并验证

quark_install_result.json

；不得仅凭安装退出码或构建标签就宣称成功。

Recovery

恢复处理

CPU-only or unavailable GPU: keep GPU as the default, show hardware/build/runtime evidence, and ask whether to repair GPU PyTorch or explicitly accept CPU. Do not silently fall back.
No exact native wheel: show each mismatched ABI dimension, propose the universal wheel, and request approval again.
Compiler failure: universal-wheel kernel/custom-op checks may require a C++ compiler plus
```
nvcc
```
or
```
hipcc
```
. Report the missing tool and get approval before system changes.
Missing Transformers: Quark Torch import can fail after the extension loads if Transformers is absent. Show the exact
```
ModuleNotFoundError
```
, preview a compatible Transformers install, and request approval before retrying.
CLI/ONNX Runtime conflict: show all installed/planned
```
onnxruntime*
```
distributions. Prefer a separate environment or an explicitly revised plan; never hide the conflict with
```
--no-deps
```
.
Dependency or import failure: preserve
```
pip check
```
, the exact failing command, versions, and full error. Prefer a fresh environment over forced downgrades.
Wrong environment or source shadowing: compare
```
sys.executable
```
,
```
pip --version
```
, distribution version, and
```
quark.__file__
```
; rerun wheel verification from a neutral directory with one absolute interpreter path.
Network/index failure: retain the exact URL and error. Do not switch indexes or retry repeatedly without confirmation.
Unsupported Python: propose a fresh Python 3.13 environment and restart at Step 1 after approval.

仅有 CPU 或 GPU 不可用： 保持 GPU 为默认模式，展示硬件、构建和运行时证据，并询问是修复 GPU PyTorch，还是明确接受 CPU。不得静默回退。
没有完全匹配的原生 wheel： 展示每个不匹配的 ABI 维度，提出使用通用 wheel 的方案，并再次请求批准。
编译器失败： 通用 wheel 的 kernel 或自定义算子检查可能需要 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 步重新开始。