Back to Details

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

核心规则

  1. Never use the system Python. Always work inside an isolated environment.
  2. 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.
  3. 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.
  4. Check installed versions correctly. Use 
    importlib.metadata.version("package-name")
    , never 
    module.__version__
    . The latter is inconsistent across packages.
  5. The bundled scripts use 
    boto3
    directly.     The SageMaker Python SDK is a valid alternative — see "boto3 vs the SageMaker SDK" below.
  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 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
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
并无害处，但不能替代依赖安装步骤。