本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

故障診斷 Python 3.12 升級

生效日期：2026 年 1 月 21 日

概觀

自 2026 年 1 月 21 日起，Amazon Braket 會將所有筆記本執行個體和受管容器映像 (Base、CUDA-Q、TensorFlow 和 PyTorch) 的 Python 執行期從 3.10 升級到 3.12。本指南提供常見相容性問題的解決方案。

常見錯誤訊息

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 或將 PIN 升級至 Python 3.10 容器。

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。

您有兩種選擇：

混合式任務裝飾器

若要使用@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 容器標籤：

下列範例適用於 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

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：