为 SageMaker/AWS 工作搭建隔离 Python…

当要执行 SageMaker 部署、训练任务或任何 AWS 自动化 Python 代码时，用隔离环境并固定 Python 版本、安装最新 SDK。

适用场景

解决思路

1. 永远不要使用系统 Python，始终在隔离环境中工作。
2. 固定 Python 版本而非包版本：使用 3.10、3.11 或 3.12，避免 3.13+（ML 库 wheel 滞后、依赖解析易出错）。
3. 安装每个包的最新版本，不要防御性地固定 boto3 或 awscli；仅当用户明确要求特定版本时才固定。
4. 用 importlib.metadata.version("package-name") 检查已安装版本，绝不用 module.__version__（各包不一致）。
5. 优先运行捆绑脚本：python3 scripts/setup_env.py（macOS/Linux）或 python scripts/setup_env.py（Windows），它会检测 uv 并优先使用，否则回退到 stdlib venv，创建 .venv/ 并默认用 Python 3.12（可用 python3 setup_env.py .venv 3.11 覆盖），拒绝不支持的版本，从捆绑 requirements.txt 安装且幂等，并打印对应平台的解释器路径。
6. 手动等价做法（优先 uv）：uv venv --python 3.12 .venv 然后 uv pip install --python .venv/bin/python --upgrade boto3 awscli（Windows 用 .venv\Scripts\python.exe）。
7. 手动回退（stdlib venv）：python3.12 -m venv .venv 然后 .venv/bin/python -m pip install --upgrade pip boto3 awscli。
8. 设置后显式调用环境的 Python 而非激活 venv：.venv/bin/python deploy.py（macOS/Linux）或 .venv\Scripts\python.exe deploy.py（Windows），在脚本、交互式 shell 和 agent 工具调用中一致。
9. 验证安装：运行 .venv/bin/python scripts/check_versions.py，它用 importlib.metadata.version() 打印 boto3、botocore、awscli 版本，也可传入任意包名如 check_versions.py transformers huggingface_hub。
10. 部署特定额外依赖（如 huggingface_hub 用于模型检查、transformers 用于 tokenizer 验证）加到项目专属 requirements 文件，用环境的 Python 安装，除非有理由否则不固定版本。
11. 捆绑部署脚本（deploy.py、deploy_async.py、teardown.py）直接使用 boto3 并从 AWS 发布的 Deep Learning Containers 目录读取镜像 URI；若用户偏好或项目已用 SageMaker Python SDK (v3) 也可使用，安装到隔离环境：.venv/bin/python -m pip install sagemaker。
12. 使用 SageMaker SDK 时注意两个特例：生成式重排序器（如 Qwen3-Reranker）的 text-ranking 任务会被 SDK # 无条件路由到 TEI，需显式传入 vLLM 容器；SSO 假定角色凭据在 ModelTrainer/FrameworkProcessor 下可能有凭据解析回归，若 SDK 调用报凭据错误但同一 shell 中 aws sts get-caller-identity 成功，应怀疑此问题。
13. 遇到神秘的 pip install 解析错误时，几乎总是 Python 3.13+ 缺少 wheel 或污染的系统 Python；删除 .venv 并重新运行 python3 setup_env.py .venv 3.12 重建。
14. 若 pip install 成功但脚本报 module not found，说明安装到了不同的解释器；始终显式调用：.venv/bin/python -m pip install ... 和 .venv/bin/python deploy.py。
15. PowerShell 中内联 python -c "..." 单行命令因引号规则失败时，不要调试引号，把代码写入小 .py 文件再运行。
16. boto3 调用报 unknown parameter 时，用 .venv/bin/python -m pip install --upgrade boto3 升级，不要降级脚本去匹配旧版本。
17. 若安装了 sagemaker SDK 但捆绑脚本失败，注意捆绑脚本不使用 SDK，只需 requirements.txt 中的 boto3/awscli；同时安装 sagemaker 无害但不能替代 requirements 安装。

适用边界 · 注意事项

• 当不使用 SageMaker 或任何 AWS 自动化、不需要 boto3/awscli 的纯本地 Python 项目时，不必强制此流程。
• 当用户明确要求固定特定包版本时，不要坚持安装最新版本。
• 当项目已使用 SageMaker Python SDK 且用户偏好时，不必改用捆绑的 boto3 脚本。