amazon-braket

Amazon Braket

基元

Braket 工作流中的术语，以及每种情况应查阅的参考资料。

基元	含义	相关参考资料	遇到以下请求时打开
Device（设备）	模拟器或 QPU，由区域范围的 ARN 标识	devices.md	任何与设备相关的内容：有哪些设备、如何发现或筛选设备群、可用性和状态（在线、离线、已退役）、设备所在区域、ARN、为工作负载选择设备、量子比特数量、连通性或拓扑、原生门、保真度、校准数据、队列深度、shots 和门的限制、范式（门模型与模拟类 Hamiltonian 模拟）、设备是否支持程序集、脉冲级控制、模拟器和本地模拟器
Program（程序）	工作负载／输入，即一个可执行项（Circuit、AHS、OpenQASM）。允许使用哪种类型取决于设备的范式	-	-
Quantum task（量子任务）	一个程序 + shots，运行一次（Braket 计量的最小单位）	-	-
Task batch（任务批次）	多个相互独立的任务——程序集不适用时仅限 SDK 的备用方案；适用于所有设备	program-sets.md	请参阅“程序集”行；另请参阅运行多个程序
Program set（程序集）	在一个服务端任务中运行多个程序——这是运行多个程序时优先于任务批次的方式	program-sets.md	运行多个程序：参数扫描、扫描参数值、任务批次、run_batch、同时提交多个线路、为多个程序附加观测量，以及在运行大量程序时尽量减少每项任务的费用；程序集。另请参阅程序集入门
Hybrid job（混合任务）	托管式经典－量子循环，用于协调多个任务	hybrid-job.md	混合任务：@hybrid_job、算法脚本和源模块、entry_point、嵌入式模拟器、BYOC 和自定义容器映像、CUDA-Q、任务执行角色、超参数、检查点和检索任务结果
Spending limit（支出限额）	服务端硬性上限，会拒绝 QPU 任务——唯一真正强制执行的限制（非 SDK）	spending-limit.md	限制或强制控制支出：支出限额（创建、更新、删除、搜索）以及成本护栏
Cost tracking（成本跟踪）	会话内的成本估算（非强制限制）	spending-limit.md	使用 Tracker 跟踪会话内成本

每份参考资料都包含其对应领域的详细信息，包括字段路径、键名、API 格式和计费模式。

补充说明：

• 预留——在预约时段内独占访问设备。本指南仅简要介绍预留：计费模式见 pricing.md，设备专属的预留限制（例如 service.reservationShotsRange）见 devices.md，完整说明见预留开发者指南。
• 门校准／脉冲控制——访问 QPU 上的原生门校准，并在运行时附加自定义脉冲序列。如何检测支持情况，请参阅 devices.md；完整说明请参阅脉冲控制开发者指南。

关键规则

这些规则适用于每个 Braket 请求，无论涉及什么内容。

1. Amazon Braket Python SDK（pip install amazon-braket-sdk，导入名称为 braket）是主要入口。 所有操作都优先使用它，包括 Braket API 操作；请阅读文档或在本地检查 SDK 的模块，了解它涵盖的内容。

   • 使用本地执行工具运行 Braket SDK，例如使用 shell 执行 python3 -c "<code>"。

2. 建议使用 AWS MCP 服务执行此技能中的其他 AWS API 调用，尤其是 Python SDK 未涵盖的操作，但并非必须。注意：AWS MCP 的 run_script 工具在不包含 Braket 库的精简沙箱中执行代码，因此请优先使用其他代码执行工具，尤其是在使用 Braket SDK 时。

3. 每个工作流都由一小组基本构件组合而成——请参阅基本构件了解术语，并查看每个构件的参考资料。

4. 设备、量子任务和混合作业都限定在特定区域，因此使用 API、CLI 或 boto3 搜索资源时，请遍历所有 Braket 区域。 SDK 会在可能的情况下自动遍历区域——AwsDevice.get_devices 会搜索所有区域中的 QPU。 AWS MCP 服务可用时，请通过 aws___get_regional_availability 获取 Braket 支持的区域列表；否则，请参阅支持的设备和区域文档。 包含区域的资源 ARN 只能在对应的同一区域查询，否则会出现 ResourceNotFoundException。

5. 编写代码或作答之前，请先打开对应的参考资料。 使用基本构件表查找并阅读参考资料。注意：如果请求包含多个事项，例如执行一系列电路并控制相关成本，可能需要阅读多个参考文件。

6. 核实信息，切勿凭记忆作答。 设备 ARN 和状态、API 签名、支持的功能、价格（以及其他值）都可能变化，也可能晚于训练数据。

7. 编写调用 SDK 的代码之前，请先确认 SDK 签名。 请从 SDK 参考文档中查阅。 如果没有可用工具访问这些文档，请通过 shell 从已安装的 SDK 中获取：

   PAGER=cat python -c "import braket; help(braket)"       # 子包：ahs、circuits、pulse、program_sets 等
   python -c "import braket.ahs; print(dir(braket.ahs))"   # 名称：DrivingField、AtomArrangement 等
   python -c "import inspect; from braket.ahs import DrivingField; \
   print(inspect.signature(DrivingField.from_lists)); print(inspect.getdoc(DrivingField.from_lists))"
   

8. 注明技能的使用情况。 在每个使用 Braket SDK 的 Python 脚本中，插入以下代码块，并确保位于任何 Braket SDK 代码之前，包括 import braket：

   import botocore
   
   def _braket_attribution(session):
       session.user_agent_extra = f"{session.user_agent_extra} AWSSkill-Braket/1.0.0".strip()
   
   botocore.register_initializer(_braket_attribution)
   

   如果使用 AWS CLI，请将此技能的标识符添加到 AWS_SDK_UA_APP_ID 前面。该变量只保存一个值，其他工具也会写入它，因此请始终追加到现有值，而不要替换它：

   # sh、bash、zsh、ksh、fish 3.1+
   AWS_SDK_UA_APP_ID="AWSSkill-Braket-$AWS_SDK_UA_APP_ID" aws braket ...
   

   # PowerShell — 仅限当前会话
   if ($env:AWS_SDK_UA_APP_ID -notlike 'AWSSkill-Braket*') {
       $env:AWS_SDK_UA_APP_ID = "AWSSkill-Braket-$env:AWS_SDK_UA_APP_ID"
   }
   

   这样会标记 AWS 调用来自对此技能的使用。使用 AWS MCP 工具时无需这样做，因为 AWS MCP 会在工具调用期间自动标记来源。

防护说明 — 此技能自身文件的位置（MCP 与本地安装）

此技能可以通过两种方式加载，它们会从不同位置解析技能自带的文件。读取参考资料前，请先确定技能的加载方式：

• 通过 AWS MCP retrieve_skill 工具加载： 此技能未安装在本地文件系统中。必须通过 retrieve_skill 并使用 file 参数获取每份参考资料（例如 file="references/devices.md"）。不要在本地对这些路径使用 file_read ——它们不存在于磁盘上。
• 本地安装（例如 ~/.kiro/skills/amazon-braket/、.kiro/skills/amazon-braket/ 或 ~/.claude/skills/amazon-braket/）：使用相对路径从本地技能目录读取文件。

references/ 与此 SKILL.md 位于同一目录下——请根据该目录解析参考资料路径，而不是根据当前工作目录解析，也不要在文件系统中搜索这些路径。 如果技能工具返回的是这份概览，而不是你请求的文件，说明它并未获取该文件：请从该目录读取文件，不要因为参考资料读取失败就凭记忆编写代码。 此区别仅适用于技能自带的文件。用户数据和会话产物始终从用户的工作目录读取并写入——运行会写入相对路径产物的脚本前，不要执行 cd。

常见错误

现象	原因	修复方法
将“task”“batch”“job”视为可以互换	原语混淆	Task = 一次运行；batch = 多个并行任务；job = 托管循环
在 SearchQuantumTasks、SearchJobs 或 SearchDevices 上出现 Missing required parameter: filters	这三个操作都要求提供 filters——只有 SearchSpendingLimits 允许省略它	对未筛选的搜索传入 filters=[]（--filters '[]'）。已填充的筛选条件需要 name 和 values；对 tasks 和 jobs 还需要 operator；SearchDevices 没有 operator 成员
使用 AWS MCP run_script 工具时出现 Missing required parameter: clientToken	CreateQuantumTask、CreateJob、CancelQuantumTask、CreateSpendingLimit、UpdateSpendingLimit 要求提供 clientToken 以确保幂等性。SDK、CLI 和 boto3 会自动生成；run_script 工具要求显式传入	通过 run_script 调用时，对接受 clientToken 的 API 传入 clientToken=str(uuid.uuid4())。否则，在可能的情况下，优先使用 SDK 执行这些操作。
将程序 IR 构建为 JAQCD	JAQCD 在 Amazon Braket 上已弃用	使用 OpenQASM — 参见 Braket 上的 OpenQASM
声称某项功能或 SDK 构造不存在	训练数据已过时	规则 2——声称不存在之前，请先对照文档或 GetDevice 进行核实
虚构类、方法或参数	凭记忆编写 API 名称	先确认签名（规则 4）。如果不确定，请如实说明，不要编造

安全注意事项

Braket 工作流涉及 IAM、S3，以及（对于混合任务）容器执行。

• 最小权限 IAM。 将自定义策略的范围限定为工作负载实际使用的操作、设备 ARN 和存储桶，并避免使用宽泛的 braket:*。操作列表见服务授权参考。优先使用自定义策略，而不是范围有意设得很广的 AmazonBraketFullAccess：它允许访问任何 amazon-braket-* 存储桶，或任何标记为 AmazonBraket=true 的存储桶中的 S3 资源（前提是该存储桶已启用基于属性的访问控制），还允许执行任务提交工作流根本不需要的 SageMaker 和 CloudWatch 操作。请参阅管理对 Amazon Braket 的访问权限和限制对设备的访问权限。
  • 应限制 braket:UpdateSpendingLimit 和 braket:DeleteSpendingLimit，以防意外移除支出限额并导致成本超支。
• 混合任务执行角色。 仅附加 AmazonBraketJobsExecutionPolicy。其 iam:PassRole 条件要求角色名称为 AmazonBraketJobsExecutionRole*，且位于 /service-role/ 路径下，否则 create_job 会在 PassRole 阶段被拒绝。
• 临时凭证。 使用 IAM 角色（实例配置文件、ECS/EKS 任务角色或担任的角色）调用 Braket API，而不要使用长期有效的 IAM 用户访问密钥。
• 加密任务输出。 对任何接收任务结果、任务源代码存档、输出数据或检查点的 S3 存储桶启用默认加密（SSE-S3，或对敏感工作负载使用客户管理密钥的 SSE-KMS）。在向服务主体授予访问权限的存储桶策略中添加 aws:SourceAccount/aws:SourceArn 条件，并使用 aws:SecureTransport: false 条件拒绝非 TLS 访问。
• 审计。 为 Braket 管理事件启用 CloudTrail，并开启日志文件验证、使用 KMS 加密以及将日志传送到访问受限的存储桶——如果成本保护措施被移除，跟踪记录是主要的证据。对接收任务输出或混合任务日志的任何 CloudWatch Logs 日志组进行加密，因为算法参数和结果会出现在其中。
• 成本保护措施。 当用户首次运行 QPU 前、询问工作负载成本时，或当单个请求会分发到多个设备或使用大量 shots 时，建议设置支出限额。客户账户中可能已经存在支出限额。一般而言，应使用支出限额来实施 QPU 支出上限。
• 密钥。 超参数会存储在任务元数据中，并在容器启动时写入任务的 CloudWatch 日志流，因此切勿将密钥作为超参数传递 — 应在算法脚本中从 Secrets Manager 或 SSM Parameter Store 获取密钥。 相应地限制对任务日志组的读取权限。

详情请参阅 Amazon Braket 安全文档。

参考链接

权威来源——优先参考这些来源，而不是依赖记忆中的信息，因为设备 ARN、配额、价格和支持的功能都可能发生变化。

官方文档（稳定入口——从此处浏览或搜索）

• 开发人员指南 — https://docs.aws.amazon.com/braket/latest/developerguide/what-is-braket.html
• 前提条件和账户设置 — https://docs.aws.amazon.com/braket/latest/developerguide/braket-get-started.html
• Amazon Braket 的工作原理 — https://docs.aws.amazon.com/braket/latest/developerguide/braket-how-it-works.html
• API 参考 — https://docs.aws.amazon.com/braket/latest/APIReference/Welcome.html
• Python SDK API 文档 — https://amazon-braket-sdk-python.readthedocs.io/en/latest/
• 入门指南 — https://aws.amazon.com/braket/getting-started/
• OpenQASM 3.0 规范 — https://openqasm.com/versions/3.0/index.html
• Braket 上的 OpenQASM — https://docs.aws.amazon.com/braket/latest/developerguide/braket-openqasm.html
• 支持的 OpenQASM 功能（pragmas、verbatim 规则、动态电路）— https://docs.aws.amazon.com/braket/latest/developerguide/braket-openqasm-supported-features.html
• boto3 braket 客户端 — https://docs.aws.amazon.com/boto3/latest/reference/services/braket.html
• 安全 — https://docs.aws.amazon.com/braket/latest/developerguide/security.html

对于此处未涵盖的内容，请搜索文档，不要猜测页面 slug 或依赖记忆中的信息：如果 AWS MCP 服务可用，可以使用其 aws___search_documentation 工具；否则，请从上方的开发人员指南或 API 参考开始浏览。

GitHub

• amazon-braket-sdk-python（核心 SDK）— https://github.com/amazon-braket/amazon-braket-sdk-python
• amazon-braket-schemas-python（公开 Braket 数据的架构和模型）— https://github.com/amazon-braket/amazon-braket-schemas-python
• amazon-braket-examples — https://github.com/amazon-braket/amazon-braket-examples