hf-cloud-serving-image-selection

サービングイメージの選択

サービングコンテナは、「書面上は正しく見えた」SageMaker デプロイを最も頻繁に失敗させる要因です。間違ったコンテナ、古いタグ、誤った AMI は、いずれも同じ原因の分かりにくいエラー Failed to pass health check を引き起こします。

原則その 1：HuggingFace のイメージを必ず選ぶ

HuggingFace がキュレーションしたファミリー（huggingface-vllm、huggingface-vllm-omni、huggingface-sglang、tei、huggingface-pytorch-inference）と汎用ファミリー（vllm、vllm-omni、sglang、djl-inference）のどちらでもモデルをサービングできる場合、HuggingFace のイメージは推奨ではなく必須です。汎用イメージを使用できる正当な理由は、次の 3 つだけです。

1. 互換性がないことを確認済み — モデルが、利用可能な HuggingFace のタグでサポートされていないアーキテクチャ／モダリティ／機能を必要とすることを、推測ではなくカタログで確認している。
2. 対象リージョンに HuggingFace のタグが存在しないうえに、ミラーリングも選択肢にない。
3. 以下の「既知の不具合があるイメージ」に HuggingFace のイメージが記載されている。

汎用リポジトリのバージョン番号のほうが新しいことは理由になりません。AWS の vllm リポジトリでは、huggingface-vllm より高い vLLM バージョンが公開されることがよくありますが、古くても互換性のある huggingface-vllm タグが優先されます。「最新の vLLM」は誰も要件として挙げていません。必要なのはモデルとの互換性です。汎用イメージに切り替える場合は、該当する 3 つの理由のどれに当てはまるかをデプロイログに記録してください。

イメージ URI の取得元

第一の情報源：AWS 公式の Deep Learning Containers カタログ。

URL：https://aws.github.io/deep-learning-containers/reference/available_images/

このページは AWS が管理しており、すべてのイメージファミリーについて、URI の例、タグ、CUDA バージョン、Python バージョン、プラットフォーム（SageMaker 対応か EC2/ECS/EKS 対応か）が掲載されています。デプロイに使う URI を選ぶときは、このページから直接取得してください。URL の例をコピーし、<region> をユーザーのリージョンに置き換えてから、deploy.py --image-uri に渡します。

URL の例では、ほとんどのリージョンでアカウント ID に 763104351884 が使われています。一部のリージョンでは異なるアカウント ID が使われます（例：eu-south-1 では 692866216735）。不明な場合は、リージョンの提供状況ページを確認してください。

例外：現在はありません。 このワークフローで使用するすべてのイメージファミリーが、AWS カタログページに掲載されています（TEI は 2026 年後半に追加されました）。掲載されていない新しいファミリーに遭遇した場合は、mirror_image.py でミラーリングし、生成された URI をそのまま渡してください。

クイック選択

モデル	コンテナファミリー	URI の取得方法
HuggingFace のテキスト生成 LLM（Llama、Qwen、Mistral など）	HuggingFace vLLM	AWS カタログ → "HuggingFace vLLM Inference"（ECR リポジトリ huggingface-vllm）
上記と同じ、マルチモーダル	HuggingFace vLLM-Omni	AWS カタログ → "HuggingFace vLLM-Omni Inference"（ECR リポジトリ huggingface-vllm-omni）
HuggingFace の埋め込みモデル	TEI	AWS カタログ → "HuggingFace Text Embeddings Inference"
エンコーダー／クロスエンコーダーの再ランキングモデル（BERT 系の *ForSequenceClassification）	TEI	埋め込みモデルと同じ
生成型再ランキングモデル（因果 LM。例：Qwen3-Reranker）	HuggingFace vLLM	テキスト生成 LLM と同じ — TEI ではありません。「再ランキングモデル：TEI か vLLM か？」を参照
テキストから画像への生成／拡散モデル（Stable Diffusion、FLUX）	DJL Inference	AWS カタログ → "DJL Inference" — HF Inference Toolkit ではありません。「既知の問題があるイメージ」を参照
HuggingFace の分類器、NER、QA、要約モデル	HF Inference Toolkit（CPU）	AWS カタログ → "HuggingFace PyTorch Inference"。GPU タグは現在動作しません — 「既知の問題があるイメージ」を参照
ユーザーが SGLang を明示的に希望する場合	HuggingFace SGLang	AWS カタログ → "HuggingFace SGLang Inference"
互換性のある huggingface-vllm タグがない場合（互換性がないことを確認済み、またはリージョンの制約 — 「ルール 0」を参照）	vLLM（AWS）	AWS カタログの「vLLM」セクション — フォールバック専用。バージョンの新しさを理由に選ばないでください
ユーザーが DJL-LMI を明示的に希望する場合	DJL Inference	AWS カタログ → "DJL Inference"
Amazon Nova	SageMaker JumpStart	JumpStart を使用してください。エンドポイントを直接作成しないでください
カスタム推論コード	BYOC	ユーザーが URI を指定

互換性のある場合、HuggingFace が厳選した DLC を必ず使用してください（「ルール 0」を参照）。 huggingface-vllm は AWS vLLM DLC を直接ベースにしており、SM_VLLM_* 環境変数の仕様は同一で、cu130 AMI のルールも共通です。また、最新の transformers、最新の huggingface_hub と hf_xet（古いイメージで発生する XET-CDN の 403 ダウンロードエラーを回避）、および HF のパフォーマンス向けデフォルト設定が追加されています。SageMaker SDK v3 が自動的にルーティングするイメージでもあります。AWS の vllm イメージは互換性のための最終手段にすぎません。通常、huggingface-vllm より高い vLLM バージョンが表示されますが、それを選ぶ理由にはなりません。

TGI は使用しないでください。 Text Generation Inference はアーカイブされています。アーカイブ後にリリースされたモデル（特に Qwen3）は、TGI の ping ヘルスチェックに失敗します。代わりに vLLM を使用してください。（SageMaker SDK v3 も同じ方針です。PR #5960 以降（2026 年 6 月）、ModelBuilder は text-generation を HuggingFace vLLM DLC に、マルチモーダルタスクを HuggingFace vLLM-Omni に自動ルーティングします。）

各ファミリーの選定理由については、references/model-to-image.md を参照してください。

Reranker：TEI と vLLM のどちらを選ぶべきですか？

「Reranker」には大きく異なる 2 種類のアーキテクチャがあり、選択を誤ると、TEI がモデルを拒否するまでにエンドポイント作成のサイクルを丸ごと（約 20 分）無駄にします。

• Encoder cross-encoders（BAAI/bge-reranker-*、mixedbread、ほとんどの sentence-transformers reranker）— 分類ヘッドを持つ BERT 系モデルです。config.json の TEI がサポートするエンコーダータイプに architectures: [..ForSequenceClassification] が設定されています。→ TEI
• Generative rerankers（Qwen/Qwen3-Reranker-*、および同様の causal-LM judge）— yes/no トークンの logprob を使って関連性をスコアリングするデコーダー LLM です。config.json に architectures: [..ForCausalLM] が設定されています。→ テキスト生成 LLM とまったく同じ方法でデプロイする HuggingFace vLLM。TEI はアーキテクチャを読み込んだ後、classifier モデルタイプを拒否します（TEI の Qwen3 サポートは embeddings のみ です）。呼び出しパターン（raw completions API、max_tokens=1、logprobs によるスコアリング）は hf-cloud-sagemaker-production-defaults に記載されています。

リソースを作成する前に事前確認してください — 1 回の HTTP GET で判定できます。

curl -s https://huggingface.co/<model-id>/raw/main/config.json
# "architectures": ["Qwen3ForCausalLM"]              → vLLM
# "architectures": ["XLMRobertaForSequenceClassification"] → TEI

TEI では、(アーキテクチャ、タスク) の組み合わせも確認してください。アーキテクチャが TEI のサポート対象リストに載っていても、embeddings に対応しているだけで、分類／reranking に対応しているとは限りません。

注意：SageMaker SDK v3（PR #5960）は、text-ranking タスクを無条件に TEI へルーティングします。cross-encoder には適切ですが、generative reranker には適しません。SDK のルーティングを、TEI が特定の reranker を提供できる証拠と見なさないでください。

ワークフロー

どのファミリーでも、AWS カタログページから URI を確認してください。

1. https://aws.github.io/deep-learning-containers/reference/available_images/ を開きます
2. 該当するファミリーのセクションを探します（例：HuggingFace LLM では「HuggingFace vLLM Inference」、embeddings では「HuggingFace Text Embeddings Inference」）
3. プラットフォーム列が SageMaker の最新の行を選びます。選ぶのはそのファミリー内で最新の行です。エンジンバージョンがより新しい別ファミリーのセクションに切り替えないでください（「Rule zero」を参照）
4. <region> をユーザーのリージョン（hf-cloud-aws-context-discovery から取得）に置き換えます
5. vLLM の場合は、AMI の要件も確認します（以下の「vLLM AMI requirement」を参照）
6. URI を deploy.py --image-uri（リアルタイム）または deploy_async.py --image-uri（非同期）に渡します

TEI：適切なバリアントを選ぶ

TEI のカタログ行には、GPU（tei リポジトリ）と CPU（tei-cpu リポジトリ）の 2 つの URI が記載されています。インスタンスタイプに応じて選択してください。

• ml.g*、ml.p*、ml.inf* → GPU バリアント
• ml.c*、ml.m*、ml.t* → CPU バリアント

混在させると失敗します。GPU インスタンスで CPU イメージを使うとハードウェアが無駄になり、CPU インスタンスで GPU イメージを使うと起動に失敗します。

TEI アカウント ID に関する注意：カタログページでは例として 683313688378 が示されていますが、TEI はメインの AWS DLC とは異なるアカウント名前空間から公開されており、リージョンごとにアカウント ID が異なります。us-east-1 以外のリージョンで 683313688378.dkr.ecr.<region>.amazonaws.com/tei:... が ECR のプルエラーを返す場合は、Region Availability ページでそのリージョンの正しいアカウント ID を確認してください。

vLLM AMI の要件

CUDA 13 以降（現在のデフォルトは cu130）を含む vLLM DLC イメージでは、ProductionVariant に InferenceAmiVersion=al2-ami-sagemaker-inference-gpu-3-1 を設定する必要があります。これは、同じ cu130 ベースを使用する huggingface-vllm と huggingface-vllm-omni、および AWS の vllm リポジトリにも同様に適用されます。この設定がない場合、コンテナは起動時に終了し、CloudWatch ログも作成されません。この障害は、アカウントレベルの問題、クォータ、ネットワークなど、ほかの多くの問題と見分けがつかず、誤った診断経路に進んでしまうことがよくあります。

参照表：

タグに含まれるもの	指定する InferenceAmiVersion
cu130（またはそれ以降）	al2-ami-sagemaker-inference-gpu-3-1
cu129 以下	（フラグを省略。デフォルトの AMI が使用できます）

目安：選択した vLLM タグに cu130 以降が含まれている場合は、deploy.py に --inference-ami-version al2-ami-sagemaker-inference-gpu-3-1 を渡してください。将来、CUDA のバージョン（cu140 以降）に別の AMI が必要になった場合は、AWS が新しいイメージを公開した時点で表に行を追加してください。

これは vLLM 固有の注意事項です。TEI と HF Inference Toolkit のイメージでは、AMI のオーバーライドは必要ありません。

vLLM DLC の設定（HuggingFace vLLM と AWS vLLM）

どちらのイメージも同じ仕様に従います。SageMaker のモデル定義で環境変数として設定し、SM_VLLM_* を vLLM の CLI フラグに対応させます。huggingface-vllm のエントリーポイントでは、SM_VLLM_MODEL が未設定の場合、モデルを自動検出します。S3 アーティファクトがマウントされている場合は /opt/ml/model から、そうでない場合は HF_MODEL_ID から検出します。本番環境では、SM_VLLM_MODEL に /opt/ml/model を指定してください。実行時に Hub から直接読み込むのは例外的なケースです。

HuggingFace LLM デプロイごとに必須

環境変数	用途	備考
SM_VLLM_MODEL	HF モデル ID（例：Qwen/Qwen3-0.6B）、または S3 から読み込む場合は /opt/ml/model	—
SM_VLLM_HOST	0.0.0.0 を指定する必要があります	そうしないと、vLLM は localhost のみでバインドし、ping に失敗して、ログが出る前にコンテナが終了します。このイメージで原因不明の障害が起きる主な原因です。
SM_VLLM_TRUST_REMOTE_CODE	モデルアーティファクトによるカスタム Python コードの実行を許可するかどうか	デフォルトは false です。 リポジトリのコードなしでは読み込めない特定のアーキテクチャの場合に限り、そのアーティファクトを確認して固定したうえで true に設定してください。有効にすると、モデルが提供するコードをコンテナ内で実行できるようになります。
HUGGING_FACE_HUB_TOKEN	HF トークン	アクセス制限付きモデルで必要です。

本番用モデルアーティファクトはアカウント管理下の S3 バケットにステージングし、その URI を --model-s3-uri に渡して、SM_VLLM_MODEL=/opt/ml/model を使用してください。これにより、実行時にリポジトリのコードをダウンロードまたは実行する必要がなくなります。実行時に Hub へアクセスする必要が明示されている場合に限り、Hub モデル ID を使用してください。そのアーキテクチャで確認済みのカスタムコードが必要でない限り、SM_VLLM_TRUST_REMOTE_CODE=false のままにしてください。

チューニング（任意）

環境変数	用途
SM_VLLM_MAX_MODEL_LEN	最大シーケンス長。ファインチューニング済みモデルではデフォルト値が適切でない場合があるため、設定してください
SM_VLLM_GPU_MEMORY_UTILIZATION	0.0～1.0 の浮動小数点数。約 0.9 が妥当です
SM_VLLM_TENSOR_PARALLEL_SIZE	マルチ GPU インスタンスでの GPU 数
SM_VLLM_DTYPE	auto、bfloat16、float16

vLLM の CLI フラグはすべて使用できます。大文字にし、ハイフンをアンダースコアに置き換えて、先頭に SM_VLLM_ を付けてください。

TEI の設定

vLLM よりシンプルな環境変数の仕様です。

環境変数	用途	必須
HF_MODEL_ID	HF モデル ID（例：BAAI/bge-large-en-v1.5）、または /opt/ml/model	はい
HF_TOKEN	HF 認証トークン	アクセス制限付きモデルでのみ必要
MAX_BATCH_TOKENS	バッチあたりの最大トークン数（デフォルトは 16384）	いいえ
MAX_CLIENT_BATCH_SIZE	クライアントバッチあたりの最大リクエスト数（デフォルトは 32）	いいえ

ホストバインドの設定も、trust-remote-code フラグもありません。TEI がサポートするアーキテクチャ（BERT、CamemBERT、RoBERTa、XLM-RoBERTa、NomicBert、JinaBert、JinaCodeBert、Mistral、Qwen2/3、Gemma2/3、ModernBert）は、イメージに組み込まれています。

CUDA / インスタンスの互換性

重要で、間違えやすい点です。

イメージタグの CUDA	デフォルト AMI	al2-ami-sagemaker-inference-gpu-3-1 の場合
cu124 / cu128	g5、g6、p5 のすべてで動作	（不要）
cu129	g6、p5 では動作。g5 では失敗（ドライバーの不一致 → CannotStartContainerError）	g5 でも動作する見込み（未検証）
cu130+	どの環境でも失敗 — AMI フラグが必須	g5、g6、p5 のすべてで動作（cu130 を g5 で検証済み、2026年6月）

ドライバーはインスタンスファミリーではなくホスト AMI に付属します。そのため、gpu-3-1 AMI（vLLM cu130 イメージではいずれにしても必要）を渡すことで、cu129 以降のイメージでも ml.g5.* が使用可能になります。

VPC / NAT ゲートウェイの問題

VPC 内にあり、NAT ゲートウェイがない SageMaker エンドポイントは、public.ecr.aws からイメージをプルできません。「VPC」や「egress」には触れない、イメージのプルエラーが発生してデプロイに失敗します。

AWS のリージョナル ECR にあるイメージ（カタログ内のすべてのイメージ）の場合、SageMaker は組み込みのルーティングを通じてアクセスするため、NAT は不要です。public.ecr.aws/... 形式ではなく、リージョナル URI の形式（<account>.dkr.ecr.<region>.amazonaws.com/...）を使用してください。

public.ecr.aws へのアクセスが必要なイメージ（比較的まれ）の場合は、scripts/mirror_image.py を使ってアカウント内のプライベート ECR リポジトリにミラーリングします（クロスプラットフォーム対応。Docker と aws CLI が必要です）。AWS CLI が動作するシェルから実行してください。

# macOS / Linux
PRIVATE_URI=$(python3 scripts/mirror_image.py \
    public.ecr.aws/deep-learning-containers/vllm:<tag> \
    vllm-mirror)

# Windows (PowerShell) — capture stdout into a variable
$PRIVATE_URI = python scripts\mirror_image.py `
    public.ecr.aws/deep-learning-containers/vllm:<tag> vllm-mirror

カタログページが表示されない、古い、または誤っている場合

ページが表示されない／取得結果が不正：カタログページは JavaScript を多用しており、一部の取得ツールでは空のシェルが返されます。次の順に代替手段を試してください。

1. カタログの GitHub 上のソースデータ — ページはバージョンごとに1つの YAML ファイルから生成されており、正確なタグ、CUDA、Python のバージョンが記載されています。ファミリーのファイル一覧を取得してから、最新のファイルを取得してください。

   curl -s https://api.github.com/repos/aws/deep-learning-containers/contents/docs/src/data/huggingface-vllm
   curl -s https://raw.githubusercontent.com/aws/deep-learning-containers/main/docs/src/data/huggingface-vllm/0.21.0-gpu-sagemaker.yml
   

   ディレクトリ名は ECR リポジトリ（huggingface-vllm、huggingface-vllm-omni、huggingface-tei、vllm、djl-inference、…）と一致します。
2. ECR に直接問い合わせて、対象リージョンの現在のタグを確認します（DLC レジストリを読み取れる認証情報で動作します。AccessDenied が返された場合は、YAML ファイルを使用してください）。

   aws ecr describe-images --registry-id 763104351884 --repository-name huggingface-vllm \
       --region <region> --query 'sort_by(imageDetails,&imagePushedAt)[-5:].imageTags' --output json
   

3. DLC GitHub リポジトリのリリースノート。

タグがリリースされたばかりで、まだページに掲載されていない場合：まれなケースです。AWS はリリースごとにページを更新します。上記のリリースノートを確認してください。

必要なアーキテクチャが、掲載されているイメージでまだサポートされていない場合：特に TEI では、GHCR の上流イメージ（ghcr.io/huggingface/text-embeddings-inference:<version>）をプライベート ECR にミラーリングし、生成された URI を deploy.py --image-uri に直接渡すことができます。同じ mirror_image.py スクリプトを使用します。

既知の不具合があるイメージ（最終確認：2026年7月）

イメージ	不具合	代わりに使用
huggingface-pytorch-inference GPU タグ — 最近のタグでテスト済みのものすべて（PT 2.3～2.6、cu121/cu124、transformers 4.48～5.5.3）	import torch 時に ImportError: libtorch_cuda.so: undefined symbol: ncclCommResume が発生します。イメージにバンドルされた NCCL が、torch のリンク先より古いことが原因です。これはコンテナ内部のパッケージング不具合で、AMI、モデル、推論コードにかかわらず、g5 と g6 の両方で発生します。MMS Java フロントエンドは /ping に応答し続けるため、Python ワーカーがクラッシュを繰り返して何も提供できない状態でも、エンドポイントは InService に到達することがあります。	DJL Inference（完全な CUDA/NCCL スタックを独自にバンドル）または BYOC。CPU タグには影響しません。

AWS が新しい huggingface-pytorch-inference GPU タグを公開したら再確認してください。不具合が修正されたイメージを確認できた時点で、この行を削除してください。

一般的なフォールバックルール：HF DLC で CUDA/NCCL リンカーエラーが発生した場合は、同系列の別タグを試し続けるのではなく、DJL Inference に切り替えてください。不具合の種類はタグ単位ではなくリポジトリ単位です（上記のケースでは3つの異なるタグを試しましたが、すべて不具合がありました）。

関連する HF Hub の注意点：古い DLC では、バンドルされた huggingface_hub が XET 認証に対応する前のバージョンであるため、HF の XET CDN からモデルをダウンロードする際に 403 Forbidden が発生することがあります。HF_HUB_ENABLE_HF_TRANSFER=0 を設定して標準のダウンロード経路を強制するか、重みをあらかじめ S3 に配置してください。

初回起動時の Hub からのダウンロード時間

HF Hub からのモデルの読み込みは、エンドポイントの起動後にコンテナ内で行われるため、モデルが小さくても InService になるまで5～15 分以上かかることがあります。数 GB のモデルでは、さらに時間がかかります。初回起動に時間がかかっても失敗ではありません。デプロイスクリプトの 30 分間の待機時間が切れる前に、リソースを削除したり、問題を再診断したりしないでください。

本番環境や繰り返しデプロイする場合は、あらかじめ重みを S3 に配置し、deploy.py に --model-s3-uri を渡してください（モデルは /opt/ml/model から読み込まれます）。Hub のレート制限や障害の影響を受けず、より高速で、実行時に HUGGING_FACE_HUB_TOKEN も不要です。