hf-cloud-python-env-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python Environment Setup for SageMaker

面向SageMaker的Python环境搭建

Most SageMaker deployment failures that look like AWS problems are actually Python environment problems: wrong Python version, broken dependency resolution, stale SDK that doesn't know about a current API. This skill makes env setup boring and correct.

大多数看似AWS问题的SageMaker部署故障，实际上都是Python环境问题：Python版本错误、依赖解析失败、SDK版本过时而不支持当前API。本技能让环境搭建变得规范且不出错。

Core rules

核心规则

Never use the system Python. Always work inside an isolated environment.
Pin the Python version, not the package versions. Use 3.10, 3.11, or 3.12. Avoid 3.13+ — ML libraries lag on wheel availability and dependency resolution breaks in confusing ways.
Install the latest of each package. Don't defensively pin
```
boto3
```
or
```
awscli
```
. Newer ones have current API surfaces and security fixes. Only pin if the user explicitly requires a specific version.
Check installed versions correctly. Use
```
importlib.metadata.version("package-name")
```
, never
```
module.__version__
```
. The latter is inconsistent across packages.
The bundled scripts use
boto3
directly. The SageMaker Python SDK is a valid alternative — see "boto3 vs the SageMaker SDK" below.

绝对不要使用系统Python。始终在隔离环境中工作。
固定Python版本，而非包版本。使用3.10、3.11或3.12版本。避免使用3.13及以上版本——机器学习库的wheel包适配滞后，依赖解析会出现难以排查的问题。
安装每个包的最新版本。不要刻意固定
```
boto3
```
或
```
awscli
```
的版本。新版本包含当前API接口和安全修复。仅当用户明确要求特定版本时才进行固定。
正确检查已安装版本。使用
```
importlib.metadata.version("package-name")
```
，绝对不要使用
```
module.__version__
```
。后者在不同包中的表现不一致。
捆绑脚本直接使用
boto3
。SageMaker Python SDK是可行的替代方案——详见下方“boto3 vs SageMaker SDK”部分。

boto3 vs the SageMaker SDK

boto3 vs SageMaker SDK

The bundled deploy scripts (

deploy.py

deploy_async.py

teardown.py

) use

boto3

directly and read image URIs from AWS's published Deep Learning Containers catalog. That fits this workflow's explicit-stages design — each skill produces a concrete value (region, role ARN, image URI) that the next one consumes — and

boto3

is the stable underlying API client.

The SageMaker Python SDK (v3) is fine to use when the user prefers it or their project already does. Since PR #5960 (June 2026),

ModelBuilder

auto-routes HuggingFace models to the current containers (text-generation → HuggingFace vLLM, multimodal → vLLM-Omni, embeddings → TEI). Don't avoid the SDK over stale-image or wrong-container concerns — that routing is fixed.

Two specific SDK cases that still need care:

Generative rerankers: the SDK routes the
```
text-ranking
```
task to TEI unconditionally, which is wrong for causal-LM rerankers like Qwen3-Reranker — those need vLLM (see
```
hf-cloud-serving-image-selection
```
). Pass the container explicitly for these models.
SSO assumed-role credentials: v3 has had credential-resolution regressions in
```
ModelTrainer
```
/
```
FrameworkProcessor
```
under SSO profiles. If SDK calls fail with credential errors while
```
aws sts get-caller-identity
```
succeeds in the same shell, suspect this rather than your AWS config.

If you use the SDK, install it into the isolated env like everything else (

.venv/bin/python -m pip install sagemaker

). The bundled scripts don't require it.

捆绑的部署脚本（

deploy.py

、

deploy_async.py

、

teardown.py

）直接使用

boto3

，并从AWS发布的深度学习容器目录读取镜像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等因果语言模型重排器来说是错误的——这些模型需要vLLM（详见
```
hf-cloud-serving-image-selection
```
）。针对这类模型需显式指定容器。
SSO假定角色凭证：在SSO配置文件下，v3版本的
```
ModelTrainer
```
/
```
FrameworkProcessor
```
存在凭证解析回归问题。如果在同一Shell中
```
aws sts get-caller-identity
```
执行成功，但SDK调用却因凭证错误失败，应怀疑是该问题而非AWS配置问题。

如果使用SDK，请将其安装到隔离环境中，与其他包一致（

.venv/bin/python -m pip install sagemaker

）。捆绑脚本不需要依赖该SDK。

How to set up

搭建步骤

The fastest path is the bundled script — it's Python, so it runs the same on Windows, macOS, and Linux:

bash

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

This script detects

uv

and uses it if available (faster), falls back to the stdlib

venv

module, creates

.venv/

with Python 3.12 (override:

python3 setup_env.py .venv 3.11

), refuses unsupported Python versions, installs from the bundled

requirements.txt

, and is idempotent. It also prints the correct interpreter path for the host OS (see below).

Manual equivalent:

bash

undefined

最快的方式是使用捆绑脚本——它是Python编写的，因此在Windows、macOS和Linux上运行方式一致：

bash

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

安装依赖，且支持幂等执行。它还会打印适用于主机操作系统的正确解释器路径（详见下文）。

手动等效操作：

bash

undefined

Preferred: uv

首选方案：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

回退方案：标准库venv

python3.12 -m venv .venv .venv/bin/python -m pip install --upgrade pip boto3 awscli


After setup, **invoke the env's Python explicitly** rather than activating the venv. The interpreter path differs by platform:

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

This works the same in scripts, interactive shells, and agent tool calls. The rest of this skill writes

.venv/bin/python

for brevity — on Windows substitute

.venv\Scripts\python.exe

python3.12 -m venv .venv .venv/bin/python -m pip install --upgrade pip boto3 awscli


搭建完成后，**显式调用环境中的Python**，而非激活虚拟环境。解释器路径因平台而异：

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

这种方式在脚本、交互式Shell和Agent工具调用中的效果一致。为简洁起见，本技能后续均使用

.venv/bin/python

——在Windows上请替换为

.venv\Scripts\python.exe

。

Verifying

验证环境

bash

.venv/bin/python scripts/check_versions.py

Prints versions of

boto3

botocore

awscli

. Uses

importlib.metadata.version()

so it works on every package, including ones without

__version__

. Pass arbitrary names:

... check_versions.py transformers huggingface_hub

bash

.venv/bin/python scripts/check_versions.py

该脚本会打印

boto3

、

botocore

、

awscli

的版本。它使用

importlib.metadata.version()

，因此适用于所有包，包括没有

__version__

属性的包。可传入任意包名：

... check_versions.py transformers huggingface_hub

。

Deployment-specific extras

部署专属扩展依赖

Default

requirements.txt

covers SageMaker orchestration. Some deployments need extras (

huggingface_hub

for model inspection,

transformers

for tokenizer validation). Add these to a deployment-specific requirements file in the project, install with the env's Python, don't pin unless there's a reason.

默认的

requirements.txt

已涵盖SageMaker编排所需依赖。部分部署需要额外依赖（如用于模型检查的

huggingface_hub

、用于分词器验证的

transformers

）。将这些依赖添加到项目中部署专属的requirements文件，使用环境中的Python进行安装，除非有特殊原因否则不要固定版本。

Common pitfalls

常见陷阱

Mysterious
pip install
resolution errors Almost always Python 3.13+ trying to install packages without wheels yet, or installing into a polluted system Python. Recreate at 3.12: delete

.venv

and re-run

python3 setup_env.py .venv 3.12

(the script recreates the env when the version doesn't match, so you can also just re-run it).

pip install
succeeded but the script says "module not found" You installed into a different interpreter than the one running the script. Always invoke Python explicitly:

.venv/bin/python -m pip install ...

and

.venv/bin/python deploy.py

Inline
python -c "..."
one-liners fail in PowerShell PowerShell's quoting rules mangle nested/escaped quotes in inline Python. Don't debug the quoting — write the snippet to a small

.py

file and run that. (All bundled helpers are files for exactly this reason.)

boto3 call fails with "unknown parameter" Your boto3 is older than the API surface. Upgrade with

.venv/bin/python -m pip install --upgrade boto3

. Don't downgrade the script to match an old version.

sagemaker
(the SDK) installed but the bundled scripts fail The bundled scripts don't use the SDK — they only need

boto3

awscli

from

requirements.txt

. Installing

sagemaker

alongside is harmless, but it doesn't replace the requirements install.

pip install
出现莫名的解析错误几乎都是因为使用Python 3.13及以上版本安装尚未提供wheel包的依赖，或者安装到了被污染的系统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

。

PowerShell中
python -c "..."
单行命令执行失败 PowerShell的引号规则会破坏内嵌/转义引号。不要调试引号问题——将代码片段写入一个小型

.py

文件后运行即可。（所有捆绑辅助工具均为文件，正是出于这个原因。）

boto3调用提示“未知参数” 你的boto3版本早于API接口版本。使用

.venv/bin/python -m pip install --upgrade boto3

进行升级。不要为适配旧版本而降级脚本。

已安装
sagemaker
（SDK），但捆绑脚本执行失败捆绑脚本不依赖该SDK——它们只需要

requirements.txt

中的

boto3

awscli

。同时安装

sagemaker

并无害处，但不能替代依赖安装步骤。