Back to Details

amazon-braket

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Amazon Braket

Amazon Braket

Primitives

核心原语

The vocabulary of a Braket workflow, and which reference to open for each.
PrimitiveWhat it isRelated ReferencesOpen it when the request involves
DeviceA simulator or QPU, identified by a region-scoped ARNdevices.mdanything about a device: what exists, discovering or filtering the fleet, availability and status (online, offline, retired), which region a device lives in, ARNs, choosing a device for a workload, qubit count, connectivity or topology, native gates, fidelities, calibration data, queue depth, shot and gate limits, paradigm (gate-model vs analog Hamiltonian simulation), whether a device supports program sets, pulse-level control, simulators and local emulators
ProgramThe workload/input — one executable (Circuit, AHS, OpenQASM). Which type is legal depends on the device's paradigm--
Quantum taskOne program + shots, run once (the atomic unit Braket meters)--
Task batchMany independent tasks — SDK-only fallback for when a program set does not fit; works on all devicesprogram-sets.mdsee the Program set row; also running multiple programs
Program setMany programs in one service-side task — preferred way to run multiple programs instead of task batchprogram-sets.mdrunning more than one program: parameter sweeps, scanning parameter values, task batches, 
run_batch
, several circuits submitted together, attaching observables across programs, and minimizing per-task fees when many programs run, program sets. Also getting started with program sets
Hybrid jobManaged classical-quantum loop that orchestrates many taskshybrid-job.mdhybrid jobs: 
@hybrid_job
, algorithm scripts and source modules, 
entry_point
, embedded simulators, BYOC and custom container images, CUDA-Q, job execution roles, hyperparameters, checkpoints, and retrieving job results
Spending limitService-side hard cap that rejects QPU tasks — the only true enforcement (not SDK)spending-limit.mdcapping or enforcing spend: spending limits (create, update, delete, search), and cost guardrails
Cost trackingIn-session cost estimate (not enforcement)spending-limit.mdin-session cost tracking with 
Tracker
Each reference carries the domain detail for its own area — field paths, key names, API shapes, and billing models.
Additional notes:
  • Reservation — exclusive device access for a booked window. This skill covers reservations at pointer depth only: the billing model is in pricing.md, reservation-specific device limits such as 
    service.reservationShotsRange
    are in devices.md, and the full model is in the reservations developer guide.
  • Gate calibrations / pulse control — access native gate calibrations on QPUs and attach custom pulse sequences at run time. See devices.md for detecting support, and the pulse control developer guide for the full model.
Braket工作流的核心术语，以及每个术语对应的参考文档。
核心原语定义相关参考文档适用场景
设备（Device）模拟器或QPU，由区域范围的ARN标识devices.md任何与设备相关的问题：现有设备类型、设备集群发现与筛选、可用性和状态（在线、离线、已退役）、设备所在区域、ARN、为工作负载选择设备、量子比特数量、连接性或拓扑结构、原生门、保真度、校准数据、队列深度、射击次数和门限制、范式（门模型vs模拟哈密顿量模拟）、设备是否支持程序集、脉冲级控制、模拟器和本地仿真器
程序（Program）工作负载/输入——一个可执行文件（Circuit、AHS、OpenQASM）。合法的程序类型取决于设备的范式--
量子任务（Quantum task）一个程序+射击次数，运行一次（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结构和计费模型。
补充说明：
  • 预留（Reservation）——在预订时段内独占设备访问权限。本技能仅提供预留的基础信息：计费模型见pricing.md，预留特定的设备限制如
    service.reservationShotsRange
    见devices.md，完整模型见预留开发者指南。
  • 门校准/脉冲控制（Gate calibrations / pulse control）——访问QPU上的原生门校准，并在运行时附加自定义脉冲序列。检测支持情况见devices.md，完整模型见脉冲控制开发者指南。

Critical Rules

重要规则

These rules apply to every Braket request, whatever it involves.
  1. The Amazon Braket Python SDK (
    pip install amazon-braket-sdk
    , imported as 
    braket
    ) is the primary entry point.     Prefer it for every operation including Braket API operations, and understand what it covers by reading the docs or inspecting the SDK's modules locally.
    • Use local execution tools for running the Braket SDK, such as 
      shell
      with 
      python3 -c "<code>"
      .
  2. The AWS MCP server is recommended for executing any other AWS API calls in this skill, especially operations not present in the Python SDK, although not required. Note: the AWS MCP's 
    run_script
    tool executes code in a minimal sandbox without Braket libraries, so prefer using other tools for code execution, especially when using the Braket SDK.
  3. A small set of primitives composes every workflow — see Primitives for the vocabulary and the reference for each.
  4. Devices, quantum tasks, and hybrid jobs are region-scoped, so fan out across every Braket region whenever you use the API, CLI, or boto3 to search for resources. The SDK handles fanout for you where it can — 
    AwsDevice.get_devices
    searches QPUs in all regions. Get the list of regions Braket supports from 
    aws___get_regional_availability
    when the AWS MCP server is available, or from the supported devices and regions documentation. Resource ARNs containing a region may only be queried from that same region, otherwise you will see a 
    ResourceNotFoundException
    .
  5. Open the matching reference before you write code or answer. Use the Primitives table to find and read references. Note: A request that asks for several things, e.g. executing a series of circuits and controlling the cost thereof, may require reading multiple reference files.
  6. Verify, never recall. Device ARNs and statuses, API signatures, supported features, and prices (and other values) all change and may post-date training data.
  7. Confirm an SDK signature before you write code that calls it. Read it from the SDK reference docs. If no available tool can reach them, get it from the installed SDK with 
    shell
    :
bash
PAGER=cat python -c "import braket; help(braket)"       # subpackages: ahs, circuits, pulse, program_sets, ...
python -c "import braket.ahs; print(dir(braket.ahs))"   # names: DrivingField, AtomArrangement, ...
python -c "import inspect; from braket.ahs import DrivingField; \
print(inspect.signature(DrivingField.from_lists)); print(inspect.getdoc(DrivingField.from_lists))"
这些规则适用于所有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获取：
bash
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))"

Guardrail — where this skill's own files live (MCP vs local install)

注意事项——本技能文件的存储位置（MCP vs 本地安装）

This skill can be loaded two ways, and they resolve the skill's own bundled files from different places. Determine how the skill was loaded before reading a reference:
  • Loaded through the AWS MCP 
    retrieve_skill
    tool:     The skill is not installed on the local filesystem. You MUST fetch each reference via 
    retrieve_skill
    with the 
    file
    parameter (e.g. 
    file="references/devices.md"
    ). Do NOT 
    file_read
    these paths locally — they do not exist on disk.
  • Installed locally (e.g. 
    ~/.kiro/skills/amazon-braket/
    , 
    .kiro/skills/amazon-braket/
    , or 
    ~/.claude/skills/amazon-braket/
    ): Read files from the local skill directory using relative paths.
references/
is a sibling of this 
SKILL.md
— resolve reference paths against that directory, not your working directory, and do not search the filesystem for them. If a skill tool returns this overview instead of the file you asked for, it did not fetch it: read it from that directory instead, and do not write code from memory because a reference read failed. This distinction applies only to the skill's own packaged files. User data and session artifacts are always read from and written to the user's working directory — do not 
cd
before running a script that writes a relative artifact path.
本技能有两种加载方式，分别从不同位置解析自带的捆绑文件。阅读参考文档前，请确定技能的加载方式：
  • 通过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
命令。

Common mistakes

常见错误

SymptomCauseFix
Treats "task", "batch", "job" as interchangeablePrimitive confusionTask = one run; batch = many parallel tasks; job = managed loop
Missing required parameter: filters
on 
SearchQuantumTasks
, 
SearchJobs
, or 
SearchDevices
filters
is required on all three — only 
SearchSpendingLimits
lets you omit it		Pass 
filters=[]
(
--filters '[]'
) for an unfiltered search. A populated filter needs 
name
and 
values
, plus 
operator
on tasks and jobs; 
SearchDevices
has no 
operator
member
Missing required parameter: clientToken
when using AWS MCP 
run_script
tool
CreateQuantumTask
, 
CreateJob
, 
CancelQuantumTask
, 
CreateSpendingLimit
, 
UpdateSpendingLimit
require a 
clientToken
for idempotency. The SDK, CLI, and boto3 generate one automatically; the 
run_script
tool requires explicit passing		Pass 
clientToken=str(uuid.uuid4())
on APIs taking 
clientToken
when calling through 
run_script
. Otherwise, prefer the SDK for these operations when possible.
Builds program IR as JAQCDJAQCD is deprecated on Amazon BraketUse OpenQASM — see OpenQASM on Braket
Denies a feature or SDK construct existsTraining data outdatedRule 2 — verify against the docs or 
GetDevice
before saying it does not exist
Invents a class, method, or parameterWriting API names from memoryConfirm the signature first (rule 4). If uncertain, say so rather than inventing
症状原因解决方法
将"task"、"batch"、"job"视为可互换术语核心原语混淆Task = 单次运行；batch = 多个并行任务；job = 托管循环
SearchQuantumTasks
、
SearchJobs
或
SearchDevices
出现
Missing required parameter: filters
错误		这三个接口都需要
filters
参数——只有
SearchSpendingLimits
允许省略		无过滤搜索时传递
filters=[]
（
--filters '[]'
）。带过滤条件时需要
name
和
values
，任务和作业还需要
operator
；
SearchDevices
没有
operator
字段
使用AWS MCP 
run_script
工具时出现
Missing required parameter: clientToken
错误
CreateQuantumTask
、
CreateJob
、
CancelQuantumTask
、
CreateSpendingLimit
、
UpdateSpendingLimit
需要
clientToken
保证幂等性。SDK、CLI和boto3会自动生成；
run_script
工具需要显式传递		通过
run_script
调用这些API时，传递
clientToken=str(uuid.uuid4())
。否则，尽可能优先使用SDK执行这些操作。
将程序IR构建为JAQCD格式JAQCD在Amazon Braket上已被弃用使用OpenQASM——参见Braket上的OpenQASM
否认某个功能或SDK结构存在训练数据过时遵循规则2——在说不存在之前，先通过文档或
GetDevice
验证
虚构类、方法或参数凭记忆编写API名称先确认签名（规则4）。如果不确定，请说明，不要虚构

Security considerations

安全注意事项

Braket workflows touch IAM, S3, and (for hybrid jobs) container execution.
  • Least-privilege IAM. Scope custom policies to the actions, device ARNs, and buckets a workload actually uses, and avoid broad 
    braket:*
    . Actions are listed at the Service Authorization Reference. Prefer a custom policy over 
    AmazonBraketFullAccess
    , which is deliberately broad: S3 on any 
    amazon-braket-*
    bucket or any bucket tagged 
    AmazonBraket=true
    (if the bucket is enabled for Attribute-Based Access Control), plus SageMaker and CloudWatch actions a task-submission workflow never needs. See Managing access to Amazon Braket and Restricting access to devices. 
    • braket:UpdateSpendingLimit
      and 
      braket:DeleteSpendingLimit
      should be restricted to prevent accidental removal of a spending limit and accidental cost overruns.
  • Hybrid-job execution role. Attach only 
    AmazonBraketJobsExecutionPolicy
    . Its 
    iam:PassRole
    condition requires the role be named 
    AmazonBraketJobsExecutionRole*
    under the 
    /service-role/
    path, or 
    create_job
    is denied at 
    PassRole
    .
  • Ephemeral credentials. Call Braket APIs with IAM roles (instance profiles, ECS/EKS task roles, or assumed roles), not long-lived IAM user access keys.
  • Encrypt task output. Enable default encryption (SSE-S3, or SSE-KMS with a customer-managed key for sensitive workloads) on any S3 bucket receiving task results, job source archives, output data, or checkpoints. Add 
    aws:SourceAccount
    /
    aws:SourceArn
    conditions to the bucket policy where a service principal is granted access, and deny non-TLS access with an 
    aws:SecureTransport: false
    condition.
  • Auditing. Enable CloudTrail for Braket management events, with log-file validation, KMS encryption, and delivery to an access-restricted bucket — the trail is the primary evidence if a cost guardrail is removed. Encrypt any CloudWatch Logs group receiving task output or hybrid-job logs, since algorithm parameters and results appear there.
  • Cost guardrail. Recommend a spending limit before the user's first QPU run, when the user asks what a workload costs, or when one request fans out across several devices or a large shot count. Spending limits may already exist in the customer's account. In general, enforce QPU spend caps with spending limits.
  • Secrets. Hyperparameters are stored in job metadata and echoed into the job's CloudWatch log stream at container boot, so never pass a secret as a hyperparameter — fetch it from Secrets Manager or SSM Parameter Store inside the algorithm script. Restrict read access to the job log groups accordingly.
For details, see the Amazon Braket security documentation.
Braket工作流涉及IAM、S3和（针对混合作业）容器执行。
  • 最小权限IAM。 将自定义策略限定为工作负载实际使用的操作、设备ARN和存储桶，避免使用宽泛的
    braket:*
    。操作列表见服务授权参考。优先使用自定义策略而非
    AmazonBraketFullAccess
    ，后者权限过于宽泛：允许访问任何
    amazon-braket-*
    存储桶或标记为
    AmazonBraket=true
    的存储桶（如果存储桶启用了基于属性的访问控制），还包含任务提交工作流永远不需要的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前、用户询问工作负载成本时，或当一个请求涉及多个设备或大量射击次数时，建议设置支出限额。客户账户中可能已存在支出限额。通常，使用支出限额强制限制QPU支出。
  • 机密信息。 超参数存储在作业元数据中，并在容器启动时回显到作业的CloudWatch日志流中，因此切勿将机密信息作为超参数传递——应在算法脚本中从Secrets Manager或SSM Parameter Store获取相应信息。相应地，限制对作业日志组的读取权限。
详细信息请参见Amazon Braket安全文档。

Reference links

参考链接

Authoritative sources — prefer these over recalled details, since device ARNs, quotas, prices, and supported features change.
Official documentation (stable entry points — navigate/search from here)
For anything not covered here, search the documentation rather than guessing page slugs or recalling details: if the AWS MCP server is available, its 
aws___search_documentation
tool can help; otherwise start from the Developer Guide or API Reference above and navigate.
GitHub
权威来源——优先使用这些来源而非记忆的细节，因为设备ARN、配额、价格和支持的功能会变化。
官方文档（稳定入口——从此处导航/搜索）
对于此处未涵盖的内容，请搜索文档而非猜测页面路径或回忆细节：如果AWS MCP服务器可用，其
aws___search_documentation
工具可提供帮助；否则从上述开发者指南或API参考开始导航。
GitHub