cudaq-guide

CUDA-Q 指南

目的

指导用户完成 CUDA-Q 安装、基础内核、GPU 仿真目标、QPU 访问、内置应用、多 GPU 执行，以及 Python @cudaq.kernel 编写。对于 Qiskit 到 CUDA-Q 的移植问题，请改用 cudaq-importing 技能。

前置条件

• 使用 Python CUDA-Q 工作流需要 Python 3.10+。
• 在 Linux 上使用 GPU 加速目标需要 CUDA Toolkit 和 NVIDIA GPU。
• qpp-cpu 支持纯 CPU 仿真；macOS 仅支持 CPU。
• C++ 工作流需要 Linux 或 WSL，以及 C++20。
• QPU 工作流需要特定提供商的凭据和账户。

说明

• 使用 /cudaq-guide [argument] 调用。
• 如果未提供参数，请显示入门菜单并询问用户想了解哪个主题。
• 使用下方的路由表选择相关参考文件。
• 如果答案取决于特定 CUDA-Q 版本或后端行为，请查阅本地 CUDA-Q 文档文件。
• 不要使用此技能回答 Qiskit 移植问题；请改用 cudaq-importing。

按参数路由

参数	操作	参考
install	指导完成 Python 或 C++ 安装和验证。	references/onboarding.md
test-program	构建并运行 Bell 态内核。	references/onboarding.md
gpu-sim	选择 GPU、多 GPU、张量网络或 CPU 目标。	references/onboarding.md
qpu	指导选择提供商并安全配置 QPU。	references/onboarding.md
applications	概述 CUDA-Q 应用领域和笔记本。	references/onboarding.md
parallelize	选择 mgpu、mqpu、异步分派或分布式 observe。	references/onboarding.md
author	编写 CUDA-Q Python 内核、选择执行 API，并调试编译器问题。	references/authoring.md
(none)	显示下方菜单并询问要探索哪个主题。	本文件

菜单

CUDA-Q Getting Started

CUDA-Q is NVIDIA's unified quantum-classical programming model for CPUs, GPUs, and QPUs.
Supports Python and C++. Docs: https://nvidia.github.io/cuda-quantum/latest/

Choose a topic:
  /cudaq-guide install         Install CUDA-Q
  /cudaq-guide test-program    Write and run a Bell-state kernel
  /cudaq-guide gpu-sim         Accelerate simulation on NVIDIA GPUs
  /cudaq-guide qpu             Connect to real QPU hardware
  /cudaq-guide applications    Explore what you can build
  /cudaq-guide parallelize     Run across GPUs or QPUs
  /cudaq-guide author          Author @cudaq.kernel Python code

参考文件

• references/onboarding.md：安装、测试 程序、GPU 目标、QPU 提供商、应用领域、并行化 模式、示例和平台故障排查。
• references/authoring.md：执行 API、 内核语言限制、静默失败陷阱、常见编码 模式、资源指标、调试和验证。

限制

• 本指南针对 CUDA-Q Python/C++ 工作流；编写部分主要介绍 CUDA-Q 0.14 和 0.15 中使用的装饰器模式 Python API。
• GPU 和多 GPU 支持取决于本地 CUDA-Q、CUDA Toolkit、驱动程序、MPI 和硬件是否可用。
• QPU 访问和目标选项因提供商而异，也可能发生变化；提供操作步骤前，请对照本地文档进行核实。

故障排查

• **pip install cudaq 后出现导入错误：**检查 Python 3.10+ 和受支持的 OS。
• **未检测到 GPU：**检查 CUDA Toolkit 和 nvidia-smi；改用 qpp-cpu。
• **内核编译错误：**阅读 references/authoring.md 并检查受限的内核语言子集。
• **版本特定行为不一致：**将 cudaq.__version__ 与最新文档进行比较，然后在调试非最新发行版的已安装版本时，查阅相关文档或源代码变更。
• **QPU 提交失败：**确认提供商凭据已设为环境变量，或通过机密管理器提供，绝不要硬编码。
• **文档查询失败：**对临时性 MCP 或仓库查询失败重试一次，然后改用本地文档或 CUDA-Q 官方文档。