SageMaker 云端 Python 环境配置

问题从哪来

在 SageMaker 上跑 Hugging Face 或自定义推理时，日志里常出现「部署失败」「unknown parameter」「模块未找到」——很多时候根因不在 IAM 或网络，而是 Python 解释器与依赖：用了系统 Python、上了 3.13+ 导致 wheel 缺失、pip 装进了 A 环境却在 B 里跑脚本，或 boto3 过旧跟不上当前 API。

技能怎么做

技能把环境设置收成几条可执行的规则，并附带 setup_env.py 等脚本：

• 隔离环境：不用系统 Python；优先 uv，否则 venv，默认 Python 3.12（可指定 3.10/3.11）。
• 版本策略：固定 Python 大版本，包（如 boto3、awscli）默认装最新，除非用户明确要求 pin。
• 校验方式：用 importlib.metadata.version("package-name") 查版本，避免 module.__version__ 在各包间不一致。
• 部署脚本：deploy.py / deploy_async.py / teardown.py 直接走 boto3，从 AWS 深度学习容器目录读镜像 URI，与「每步产出具体值、下一步消费」的工作流对齐；可选 SageMaker Python SDK v3，但附带脚本不依赖 SDK。

日常用法是显式调用虚拟环境里的解释器（如 .venv/bin/python），而不是只靠 activate，避免「pip 成功但 import 失败」。

边界与注意

• 避免 Python 3.13+；ML 相关 wheel 往往滞后，pip 解析错误多半与此或污染的系统环境有关。
• 若用 SDK：text-ranking 重排序器可能被误路由到 TEI，因果 LM 重排序器需显式指定 vLLM 容器；SSO 假定角色下 SDK 偶发凭据回退，若 CLI sts get-caller-identity 正常而 SDK 报错，优先怀疑 SDK 而非账号配置。
• PowerShell 下避免复杂 python -c 单行；复杂逻辑写成小 .py 再执行。