hf-cloud-python-env-setup

SageMaker 用 Python 環境のセットアップ

AWS の問題に見える SageMaker のデプロイ失敗の多くは、実際には Python 環境の問題です。Python のバージョンが正しくない、依存関係の解決に失敗している、現在の API に対応していない古い SDK を使っている、といった原因です。このスキルを使えば、環境のセットアップを確実かつシンプルにできます。

基本ルール

1. システムの Python は絶対に使わないでください。 常に分離された環境内で作業してください。
2. パッケージのバージョンではなく、Python のバージョンを固定してください。 3.10、3.11、3.12 を使用してください。3.13 以降は避けてください。ML ライブラリのホイール対応は遅れがちで、依存関係の解決が分かりにくい形で失敗します。
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）を使っても問題ありません。PR #5960（2026 年 6 月）以降、ModelBuilder は HuggingFace モデルを最新のコンテナに自動で振り分けます（テキスト生成 → HuggingFace vLLM、マルチモーダル → vLLM-Omni、埋め込み → TEI）。古いイメージや誤ったコンテナを使う懸念から、SDK を避ける必要はありません。この振り分けの問題は修正されています。

引き続き注意が必要な、SDK に関する具体的なケースが 2 つあります。

• 生成型リランカー：SDK は text-ranking タスクを無条件に TEI に振り分けますが、これは Qwen3-Reranker のような因果 LM リランカーには適していません。このようなモデルには vLLM が必要です（hf-cloud-serving-image-selection を参照）。これらのモデルでは、コンテナを明示的に指定してください。
• SSO の引き受けロール認証情報：v3 では、SSO プロファイルでの ModelTrainer／FrameworkProcessor において、認証情報の解決に関する問題が発生したことがあります。同じシェルで aws sts get-caller-identity が成功する一方、SDK 呼び出しが認証情報エラーで失敗する場合は、AWS 設定ではなく、この問題を疑ってください。

SDK を使う場合は、ほかのものと同様に分離環境へインストールしてください（.venv/bin/python -m pip install sagemaker）。同梱スクリプトに SDK は必要ありません。

セットアップ方法

最も手早い方法は、同梱スクリプトを使うことです。Python スクリプトなので、Windows、macOS、Linux で同じように実行できます。

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

このスクリプトは uv を検出し、利用可能であれば（より高速な）uv を使用します。利用できない場合は標準ライブラリの venv モジュールにフォールバックします。Python 3.12 で .venv/ を作成し（変更例：python3 setup_env.py .venv 3.11）、サポート対象外の Python バージョンは拒否し、同梱の requirements.txt からインストールします。また、何度実行しても問題ありません。ホスト OS に適したインタープリターのパスも出力します（下記参照）。

手動で同じことを行う場合：

# 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/bin/python deploy.py            # macOS / Linux
.venv\Scripts\python.exe deploy.py    # Windows

この方法は、スクリプト、対話型シェル、エージェントのツール呼び出しで同じように使えます。このスキルでは簡潔にするため、以降 .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 以降でインストールしようとしているか、汚染されたシステム Python にインストールしています。Python 3.12 で環境を再作成してください。.venv を削除して、python3 setup_env.py .venv 3.12 を再実行します（スクリプトはバージョンが一致しない場合に環境を再作成するため、そのまま再実行してもかまいません）。

pip install は成功したのに、スクリプトに「module not found」と表示される スクリプトの実行に使っているものとは別のインタープリターにインストールしています。Python を常に明示的に呼び出してください。.venv/bin/python -m pip install ... および .venv/bin/python deploy.py を使います。

PowerShell ではインラインの python -c "..." ワンライナーが失敗する PowerShell の引用符の規則により、インライン Python の入れ子になった引用符やエスケープされた引用符が正しく処理されません。引用符の問題を調査するのではなく、スニペットを小さな .py ファイルに書き出して実行してください。（同梱のヘルパーがすべてファイルになっているのも、まさにこの理由です。）

boto3 の呼び出しで「unknown parameter」が発生する お使いの boto3 が API の仕様より古いバージョンです。.venv/bin/python -m pip install --upgrade boto3 でアップグレードしてください。古いバージョンに合わせてスクリプトをダウングレードしないでください。

sagemaker（SDK）はインストールされているのに、同梱のスクリプトが失敗する 同梱のスクリプトは SDK を使用せず、requirements.txt の boto3／awscli のみを必要とします。sagemaker を併せてインストールしても問題ありませんが、requirements のインストールの代わりにはなりません。