hf-cloud-python-env-setup

SageMaker 的 Python 环境设置

大多数看似 AWS 问题的 SageMaker 部署失败，实际上都是 Python 环境问题：Python 版本错误、依赖解析失败，或 SDK 过时而不支持当前 API。本技能让环境设置变得简单可靠。

核心规则

1. 绝不使用系统 Python。 始终在隔离环境中工作。
2. 固定 Python 版本，而不是软件包版本。 使用 3.10、3.11 或 3.12。避免使用 3.13 及以上版本——机器学习库的 wheel 支持滞后，依赖解析也会以难以理解的方式出错。
3. 安装各软件包的最新版本。 不要为了防患未然而固定 boto3 或 awscli 的版本。较新版本包含当前 API 和安全修复。只有用户明确要求特定版本时才固定版本。
4. 正确检查已安装的版本。 使用 importlib.metadata.version("package-name")，绝不要使用 module.__version__。后者在不同软件包中的实现并不一致。
5. 随附脚本直接使用 boto3。 SageMaker Python SDK 也是可行的替代方案——见下文“boto3 与 SageMaker SDK”。

boto3 与 SageMaker SDK

随附的部署脚本（deploy.py、deploy_async.py、teardown.py）直接使用 boto3，并从 AWS 发布的 Deep Learning Containers 目录读取镜像 URI。这符合此工作流的显式阶段设计——每项技能都会生成一个具体值（区域、角色 ARN、镜像 URI），供下一项技能使用——而 boto3 是稳定的底层 API 客户端。

如果用户更喜欢 SageMaker Python SDK（v3），或其项目已经在使用该 SDK，也完全可以使用。自 PR #5960（2026 年 6 月）起，ModelBuilder 会自动将 HuggingFace 模型路由到当前容器（文本生成 → HuggingFace vLLM，多模态 → vLLM-Omni，嵌入 → TEI）。不要因为镜像过时或容器错误的顾虑而避开该 SDK——路由问题已修复。

以下两种特定的 SDK 使用场景仍需留意：

• 生成式重排序器：SDK 会无条件地将 text-ranking 任务路由到 TEI，这对于 Qwen3-Reranker 等因果 LM 重排序器来说是错误的——这些模型需要 vLLM（见 hf-cloud-serving-image-selection）。请为这些模型显式指定容器。
• SSO 假定角色凭证：在 SSO 配置文件下，v3 的 ModelTrainer / FrameworkProcessor 曾出现凭证解析回归问题。如果 SDK 调用因凭证错误而失败，但在同一 shell 中执行 aws sts get-caller-identity 却成功，请优先怀疑这一问题，而不是 AWS 配置。

如果使用 SDK，请像安装其他所有内容一样，将它安装到隔离环境中（.venv/bin/python -m pip install sagemaker）。随附脚本不需要它。

设置方法

最快的方法是使用随附脚本——它是 Python 脚本，因此在 Windows、macOS 和 Linux 上的运行方式相同：

python3 scripts/setup_env.py        # macOS / Linux
python  scripts/setup_env.py        # Windows (PowerShell / cmd)

此脚本会检测 uv，如果可用则使用它（速度更快）；否则回退到标准库的 venv 模块。它会使用 Python 3.12 创建 .venv/（覆盖示例：python3 setup_env.py .venv 3.11），拒绝不受支持的 Python 版本，从随附的 requirements.txt 安装依赖，并且支持幂等运行。脚本还会输出适用于主机操作系统的解释器路径（见下文）。

手动执行的等效步骤：

# Preferred: uv
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python --upgrade boto3 awscli   # Windows: .venv\Scripts\python.exe

# Fallback: stdlib venv
python3.12 -m venv .venv
.venv/bin/python -m pip install --upgrade pip boto3 awscli

设置完成后，请显式调用环境中的 Python，而不要激活 venv。解释器路径因平台而异：

.venv/bin/python deploy.py            # macOS / Linux
.venv\Scripts\python.exe deploy.py    # Windows

这在脚本、交互式 shell 和 Agent 工具调用中都适用。本技能后续内容为简洁起见均使用 .venv/bin/python；在 Windows 上请替换为 .venv\Scripts\python.exe。

验证

.venv/bin/python scripts/check_versions.py

此脚本会输出 boto3、botocore 和 awscli 的版本。它使用 importlib.metadata.version()，因此适用于所有软件包，包括没有 __version__ 的软件包。可传入任意软件包名称：... check_versions.py transformers huggingface_hub。

部署特定的额外依赖

默认的 requirements.txt 涵盖 SageMaker 编排。有些部署需要额外依赖（用于检查模型的 huggingface_hub、用于验证分词器的 transformers）。请将这些依赖添加到项目中针对特定部署的 requirements 文件里，并使用环境中的 Python 安装；除非有特殊原因，否则不要固定版本。

常见问题

pip install 出现难以解释的解析错误 几乎总是因为 Python 3.13+ 中的包尚无 wheel，或者安装到了被污染的系统 Python 中。请使用 Python 3.12 重新创建环境：删除 .venv，然后重新运行 python3 setup_env.py .venv 3.12（如果版本不匹配，该脚本会重新创建环境，因此也可以直接重新运行）。

pip install 成功了，但脚本提示“找不到模块” 你安装到的解释器与运行脚本的解释器不同。始终显式调用 Python：.venv/bin/python -m pip install ... 和 .venv/bin/python deploy.py。

内联的 python -c "..." 单行命令在 PowerShell 中失败 PowerShell 的引号规则会破坏内联 Python 中嵌套或转义的引号。不要费力排查引号问题——将代码片段写入一个小型 .py 文件后运行。（出于这个原因，所有捆绑的辅助脚本都是文件。）

boto3 调用失败并提示“未知参数” 你的 boto3 版本较旧，不支持当前 API。请使用 .venv/bin/python -m pip install --upgrade boto3 升级。不要为了适配旧版本而降低脚本的版本要求。

已安装 sagemaker（SDK），但捆绑脚本运行失败 捆绑脚本不使用 SDK——它们只需要 requirements.txt 中的 boto3/awscli。同时安装 sagemaker 没有问题，但它不能替代 requirements 的安装。