本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # Amazon Braket 故障診斷使用本節中的疑難排解資訊和解決方案，以協助解決 Amazon Braket 的問題。 **Topics** + [AccessDeniedException](#braket-troubleshooting-access-denied) + [呼叫 CreateQuantumTask 操作時發生錯誤 (ValidationException)](#braket-troubleshooting-create-fail) + [SDK 功能無法運作](#braket-troubleshooting-sdk) + [由於 ServiceQuotaExceededException，混合任務失敗](#braket-jobs-quota-troubleshoot) + [元件在筆記本執行個體中停止運作](#braket-troubleshooting-notebook-issue) + [故障診斷 Python 3.12 升級](braket-troubleshooting-python312.md) + [故障診斷 OpenQASM](braket-troubleshooting-openqasm.md) ## AccessDeniedException 如果您在啟用或停用 Braket 時收到 **AccessDeniedException**，您可能會嘗試在受限角色無法存取的區域中啟用或停用 Braket。在這種情況下，請聯絡您的內部 AWS 管理員，以了解下列哪些條件適用： + 如果有防止存取區域的角色限制。 + 如果您嘗試使用的角色允許使用 Braket。如果您的角色在使用 Braket 時無法存取指定區域，則您將無法在該特定區域中使用裝置。 ## 呼叫 CreateQuantumTask 操作時發生錯誤 (ValidationException) 如果您收到類似的錯誤：`An error occurred (ValidationException) when calling the CreateQuantumTask operation: Caller doesn't have access to amazon-braket-…`請檢查您指的是現有的 s3\$1folder。Braket 不會為您自動建立新的 Amazon S3 儲存貯體和字首。如果您API直接存取並收到類似的錯誤：`Failed to create quantum task: Caller doesn't have access to s3://MY_BUCKET`請檢查您是否未包含在 Amazon S3 儲存貯體路徑`s3://`中。 ## SDK 功能無法運作您的 Python 版本必須為 3.10 或更新版本。對於 Amazon Braket 混合任務，我們建議使用 Python 3.12。確認您的 SDK 和結構描述是up-to-date。若要從筆記本或您的 python 編輯器更新 SDK，請執行下列命令： ``` pip install amazon-braket-sdk --upgrade --upgrade-strategy eager ``` 若要更新結構描述，請執行下列命令： ``` pip install amazon-braket-schemas --upgrade ``` 如果您是從自己的用戶端存取 Amazon Braket，請確認您的[AWS 區域](https://docs.aws.amazon.com/braket/latest/developerguide/braket-devices.html#braket-regions)已設定為 Amazon Braket 支援的區域。 ## 由於 ServiceQuotaExceededException，混合任務失敗如果您超過目標模擬器裝置的並行量子任務限制，則針對 Amazon Braket 模擬器執行量子任務的混合任務可能無法建立。如需服務限制的詳細資訊，請參閱[配額](braket-quotas.md)主題。如果您在帳戶中的多個混合任務中對模擬器裝置執行並行任務，您可能會遇到此錯誤。若要查看針對特定模擬器裝置的並行量子任務數量，請使用 `search-quantum-tasks` API，如下列程式碼範例所示。 ``` DEVICE_ARN=arn:aws:braket:::device/quantum-simulator/amazon/sv1 task_list="" for status_value in "CREATED" "QUEUED" "RUNNING" "CANCELLING"; do tasks=$(aws braket search-quantum-tasks --filters name=status,operator=EQUAL,values=${status_value} name=deviceArn,operator=EQUAL,values=$DEVICE_ARN --max-results 100 --query 'quantumTasks[*].quantumTaskArn' --output text) task_list="$task_list $tasks" done; echo "$task_list" | tr -s ' \t' '[\n*]' | sort | uniq ``` 您也可以使用 Amazon CloudWatch 指標來檢視針對裝置建立的量子任務：**Raket ** > **By Device**。 **若要避免執行這些錯誤：** 1. 請求增加模擬器裝置的並行量子任務數量的服務配額。這僅適用於SV1裝置。 1. 處理程式碼中的`ServiceQuotaExceeded`例外狀況，然後重試。 ## 元件在筆記本執行個體中停止運作如果筆記本的某些元件停止運作，請嘗試下列動作： 1. 將您建立或修改的任何筆記本下載至本機磁碟機。 1. 停止您的筆記本執行個體。 1. 刪除您的筆記本執行個體。 1. 使用不同的名稱建立新的筆記本執行個體。 1. 將筆記本上傳至新的執行個體。 # 故障診斷 Python 3.12 升級 **生效日期：**2026 年 1 月 21 日 ## 概觀自 2026 年 1 月 21 日起，Amazon Braket 會將所有[筆記本執行個體](https://github.com/amazon-braket/amazon-braket-examples)和[受管容器映像](https://github.com/amazon-braket/amazon-braket-containers/tree/main) (Base、CUDA-Q、TensorFlow 和 PyTorch) 的 Python 執行期從 3.10 升級到 3.12。本指南提供常見相容性問題的解決方案。 **Topics** + [概觀](#braket-troubleshooting-python312-overview) + [常見錯誤訊息](#braket-troubleshooting-python312-errors) + [Braket 受管筆記本](#braket-troubleshooting-python312-notebooks) + [混合式任務裝飾器](#braket-troubleshooting-python312-hybrid-job) + [Bring-Your-Own-Container (BYOC)](#braket-troubleshooting-python312-byoc) + [Braket 筆記本執行個體升級](#braket-troubleshooting-python312-notebook-upgrade) ## 常見錯誤訊息 ### SDK Python 版本不相符錯誤 **錯誤：** ``` RuntimeError: Python version must match between local environment and container. Client is running Python 3.10 locally, but container uses Python 3.12. ``` **原因：**Raket SDK 偵測到您的筆記本正在執行 Python 3.10，但混合任務容器正在執行 Python 3.12。 **解決方案：**[將您的筆記本升級至 Python 3.12](#braket-troubleshooting-python312-notebook-upgrade) 或將 [PIN 升級至 Python 3.10 容器](#braket-troubleshooting-python312-option2)。 ### Cloudpickle 序列化錯誤 **錯誤：** ``` TypeError: code() argument 13 must be str, not int ``` **原因：**如果略過 SDK 驗證，由於 Python 3.12 中的 CodeType 建構函數變更，Cloudpickle 無法序列化 Python 3.10 和 3.12 之間的程式碼。 **解決方案：**確保您的筆記本和容器使用相同的 Python 版本。 ## Braket 受管筆記本如果您在 Python 3.10 上執行 Braket 筆記本執行個體並提交混合任務，您將會遇到版本不符錯誤，因為任務容器現在預設使用 Python 3.12。您有兩種選擇： 1. 【建議】使用 Python 3.12 建立新的筆記本執行個體 - 請參閱 [Braket 筆記本執行個體升級](#braket-troubleshooting-python312-notebook-upgrade) 1. 釘選至 Python 3.10 容器 - 請參閱[混合式任務裝飾器](#braket-troubleshooting-python312-hybrid-job) ## 混合式任務裝飾器若要使用`@hybrid_job`裝飾項目，您環境的 Python 版本必須符合容器的 Python 版本。 ### 選項 1：使用 Python 3.12 容器（建議）如果您已將環境升級至 Python 3.12，則會使用最新的標籤（預設行為）。 ### 選項 2：使用 Python 3.10 容器如果您必須保留在 Python 3.10 上，請在`@hybrid_job`裝飾項目中明確指定 `image_uri` 參數。 **Python 3.10 容器標籤：** | 映像名稱 | Tag | | --- | --- | | Base | 1.0-cpu-py310-ubuntu22.04 | | CUDA-Q | 0.12.0-cpu-py310-0.12.0 | | PyTorch | 2.2.0-gpu-py310-cu121-ubuntu20.04 | | TensorFlow | 2.14.1-gpu-py310-cu118-ubuntu20.04 | 下列範例適用於 us-west-2 區域。 **完整映像 URIs：** ``` Base: 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-base-jobs:1.0-cpu-py310-ubuntu22.04 CUDA-Q: 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-cudaq-jobs:0.12.0-cpu-py310-0.12.0 PyTorch: 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-pytorch-jobs:2.2.0-gpu-py310-cu121-ubuntu20.04 TensorFlow: 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-tensorflow-jobs:2.14.1-gpu-py310-cu118-ubuntu20.04 ``` **範例**： ``` from braket.jobs.hybrid_job import hybrid_job from braket.devices import Devices device_arn = Devices.Amazon.SV1 @hybrid_job( device=device_arn, image_uri="292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-base-jobs:1.0-cpu-py310-ubuntu22.04" ) def my_job(): pass ``` **注意** Python 3.10 容器將保持可用，但不會收到更新。請參閱[定義演算法指令碼的環境](https://docs.aws.amazon.com/braket/latest/developerguide/braket-jobs-script-environment.html)。 ## Bring-Your-Own-Container (BYOC) 如果您的 Dockerfile 使用具有最新標籤的 Braket 受管映像，在 2026 年 1 月 21 日之後重建將提取 Python 3.12 支援的影像。若要保留 Python 3.10 支援的 Braket 受管映像，請更新您的 Dockerfile： **之前（升級後取得 Python 3.12)：** ``` FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-base-jobs:latest FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-cudaq-jobs:latest FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-tensorflow-jobs:latest FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-pytorch-jobs:latest ``` **之後（保留在 Python 3.10 上）：** ``` FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-base-jobs:1.0-cpu-py310-ubuntu22.04 FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-cudaq-jobs:0.12.0-cpu-py310-0.12.0 FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-pytorch-jobs:2.2.0-gpu-py310-cu121-ubuntu20.04 FROM 292282985366.dkr.ecr.us-west-2.amazonaws.com/amazon-braket-tensorflow-jobs:2.14.1-gpu-py310-cu118-ubuntu20.04 ``` ## Braket 筆記本執行個體升級請依照下列步驟升級至 Python 3.12： **重要** 刪除筆記本執行個體之前，請確定您已下載要保留的所有筆記本和檔案。刪除後無法復原此資料。 1. 將您建立或修改的任何筆記本下載至本機磁碟機。 1. 停止您的筆記本執行個體。 1. 刪除您的筆記本執行個體。 1. 使用不同的名稱建立新的筆記本執行個體。 1. 將您的筆記本上傳至新的執行個體。 # 故障診斷 OpenQASM 本節提供使用 OpenQASM 3.0 遇到錯誤時可能有用的疑難排解指標。 **Topics** + [包含陳述式錯誤](#braket-troubleshooting-openqasm-include-statement-error) + [非連續qubits錯誤](#braket-troubleshooting-openqasm-non-contiguous-qubits-error) + [混合實體qubits與虛擬qubits錯誤](#braket-troubleshooting-openqasm-mixing-physical-and-virtual-qubits-error) + [在相同的程式錯誤qubits中請求結果類型和測量](#braket-troubleshooting-openqasm-result-types-measuring-qubits-error) + [超過傳統和qubit註冊限制的錯誤](#braket-troubleshooting-openqasm-register-limits-error) + [前面沒有逐字 pragma 錯誤的方塊](#braket-troubleshooting-openqasm-box-not-preceded-by-pragma-error) + [逐字方塊缺少原生閘道錯誤](#braket-troubleshooting-openqasm-verbatim-box-missing-native-gates-error) + [逐字方塊缺少實體qubits錯誤](#braket-troubleshooting-openqasm-verbatim-box-missing-physical-qubits-error) + [逐字 pragma 缺少 "braket" 錯誤](#braket-troubleshooting-openqasm-pragma-naming-error) + [單一 qubits無法編製索引錯誤](#braket-troubleshooting-openqasm-qubit-index-error) + [兩個qubit閘道qubits中的實體未連線錯誤](#braket-troubleshooting-openqasm-disconnected-physical-qubits-error) + [本機模擬器支援警告](#braket-troubleshooting-openqasm-local-simulator-support-warning) ## 包含陳述式錯誤 Braket 目前沒有要包含在 OpenQASM 程式中的標準閘道程式庫檔案。例如，下列範例會引發剖析器錯誤。 ``` OPENQASM 3; include "standardlib.inc"; ``` 此程式碼會產生錯誤訊息： `No terminal matches '"' in the current parser context, at line 2 col 17.` ## 非連續qubits錯誤 qubits 在裝置功能`true`中`requiresContiguousQubitIndices`設定為的裝置上使用不連續的會導致錯誤。在模擬器和上執行量子任務時IonQ，下列程式會觸發錯誤。 ``` OPENQASM 3; qubit[4] q; h q[0]; cnot q[0], q[2]; cnot q[0], q[3]; ``` 此程式碼會產生錯誤訊息： `Device requires contiguous qubits. Qubit register q has unused qubits q[1], q[4].` ## 混合實體qubits與虛擬qubits錯誤不允許在相同程式qubits中混合實體qubits與虛擬，並導致錯誤。下列程式碼會產生錯誤。 ``` OPENQASM 3; qubit[2] q; cnot q[0], $1; ``` 此程式碼會產生錯誤訊息： `[line 4] mixes physical qubits and qubits registers.` ## 在相同的程式錯誤qubits中請求結果類型和測量請求在相同程式中qubits明確測量的結果類型和會導致錯誤。下列程式碼會產生錯誤。 ``` OPENQASM 3; qubit[2] q; h q[0]; cnot q[0], q[1]; measure q; #pragma braket result expectation x(q[0]) @ z(q[1]) ``` 此程式碼會產生錯誤訊息： `Qubits should not be explicitly measured when result types are requested.` ## 超過傳統和qubit註冊限制的錯誤只允許一個傳統註冊和一個qubit註冊。下列程式碼會產生錯誤。 ``` OPENQASM 3; qubit[2] q0; qubit[2] q1; ``` 此程式碼會產生錯誤訊息： `[line 4] cannot declare a qubit register. Only 1 qubit register is supported.` ## 前面沒有逐字 pragma 錯誤的方塊所有方塊前面都必須加上逐字法。下列程式碼會產生錯誤。 ``` box{ rx(0.5) $0; } ``` 此程式碼會產生錯誤訊息： `In verbatim boxes, native gates are required. x is not a device native gate.` ## 逐字方塊缺少原生閘道錯誤逐字方塊應具有原生閘道和實體 qubits。下列程式碼會產生原生閘道錯誤。 ``` #pragma braket verbatim box{ x $0; } ``` 此程式碼會產生錯誤訊息： `In verbatim boxes, native gates are required. x is not a device native gate.` ## 逐字方塊缺少實體qubits錯誤逐字方塊必須具有實體 qubits。下列程式碼會產生缺少的實體qubits錯誤。 ``` qubit[2] q; #pragma braket verbatim box{ rx(0.1) q[0]; } ``` 此程式碼會產生錯誤訊息： `Physical qubits are required in verbatim box.` ## 逐字 pragma 缺少 "braket" 錯誤您必須在逐字法中包含「括號」。下列程式碼會產生錯誤。 ``` #pragma braket verbatim // Correct #pragma verbatim // wrong ``` 此程式碼會產生錯誤訊息： `You must include “braket” in the verbatim pragma` ## 單一 qubits無法編製索引錯誤單一 qubits無法編製索引。下列程式碼會產生錯誤。 ``` OPENQASM 3; qubit q; h q[0]; ``` 此程式碼會產生錯誤： `[line 4] single qubit cannot be indexed.` 不過，單一qubit陣列的索引如下所示： ``` OPENQASM 3; qubit[1] q; h q[0]; // This is valid ``` ## 兩個qubit閘道qubits中的實體未連線錯誤若要使用實體 qubits，請先檢查 qubits 以確認裝置使用實體，`device.properties.action[DeviceActionType.OPENQASM].supportPhysicalQubits`然後檢查 `device.properties.paradigm.connectivity.connectivityGraph`或來驗證連線圖形`device.properties.paradigm.connectivity.fullyConnected`。 ``` OPENQASM 3; cnot $0, $14; ``` 此程式碼會產生錯誤訊息： `[line 3] has disconnected qubits 0 and 14` ## 本機模擬器支援警告 `LocalSimulator` 支援 OpenQASM 中的進階功能，這些功能可能無法在 QPUs 或隨需模擬器上使用。如果您的程式包含特有的語言功能`LocalSimulator`，如下列範例所示，您將會收到警告。 ``` qasm_string = """ qubit[2] q; h q[0]; ctrl @ x q[0], q[1]; """ qasm_program = Program(source=qasm_string) ``` 此程式碼會產生警告：`此程式只使用 LocalSimulator 中支援的 OpenQASM 語言功能。QPUs 或隨需模擬器可能不支援其中一些功能。如需支援的 OpenQASM 功能的詳細資訊，請探索[本機模擬器上 OpenQASM 的進階功能支援](braket-openqasm-supported-features.md#braket-openqasm-supported-features-advanced-feature-local-simulator)頁面。