テキスト生成推論（Text Generation Inference、TGI）とは？

Text Generation Inference は、トークンストリーミング、継続的バッチ処理、テンソル並列シャディング機能を備えた大規模言語モデルをホストするための Hugging Face サーバーです。

Nvidia GPU 上で Docker を使用して TGI を実行するにはどうすればよいですか？

公式 TGI コンテナを GPU アクセス付きで実行し、ホストポートをコンテナポートにマッピングして、モデル ID を渡すことで、サーバーがモデルをダウンロードして提供します。

TGI を用いて、ゲート付きまたはプライベートな Hugging Face モデルを提供するにはどうすればよいですか？

HF_TOKEN 環境変数を、モデルの読み取り権限を付与された Hugging Face アクセストークルに設定し、サーバーがゲート付きまたはプライベートなモデルファイルをダウンロードできるようにしてください。

TGI の設定のうち、GPU メモリとリクエスト制限を制御するのはどれですか？

主要な制限には、最大総トークン数、最大入力トークン数、バッチトークン予算、およびオプションの CUDA メモリ割合が含まれ、これらは合わせてメモリ使用量とキューイング動作を制限します。

TGI は複数の GPU で NCCL または共有メモリエラーが発生する原因はなにか？

マルチ GPU シャーディングは集合通信を使用し、共有メモリに依存するため、コンテナの共有メモリが不足すると NCCL の失敗や深刻なパフォーマンス低下を引き起こす可能性があります。

OpenAI 互換のチャットクライアントで TGI をどのように使用できるでしょうか？

Messages API エンドポイントを使用し、OpenAI 互換のクライアントのベース URL をサーバーの v1 パスに設定してから、標準的なチャットメッセージを送信してください。

TGI サーバーからPrometheus指標をスクレイピングできるのはどこですか？

サーバー上の Prometheus メトリクスエンドポイントをスクレイプし、リクエスト遅延、トークン数、キュー深さ、バッチタイミングのメトリクスを取得します。

TGI はどの量子化手法に対応していますか。

TGI は GPTQ、AWQ、bitsandbytes、EETQ、Marlin、EXL2、fp8、圧縮テンソルをサポートしており、一部の手法では事前量子化された重みが必要であるのに対し、他の手法は読み込み時に量子化を行います。

TGI（Text Generation Inference）のインストール、設定、トラブルシューティング

TGI をインストールし、迅速にデプロイ、さらに高速にデバッグ。

Text Generation Inference (TGI) は、非常に特有の雰囲気を持っています。推論の分野で最も新しい子供ではありませんが、すでに本番環境でのトラブルを学び、その教訓をデフォルト設定に焼き付けているのが TGI です。

あなたの目標が「HTTP 背後に LLM を配置し、稼働し続けること」であるならば、TGI は実用的なツールです。

モデルをどこで実行するかを検討している場合は、2026 年の LLM ホスティング比較を参照して、ローカル、セルフホスティング、クラウドのセットアップをまとめ、TGI を文脈に位置付けてください。

まず現実確認です。2026 年現在、TGI はメンテナンスモードにあり、アップストリームリポジトリは読み取り専用アーカイブされています。これは、運用の観点から見れば悪いニュースのように見えますが、実際の变化（ churn ）はモデル、プロンプト、製品要件にあるため、安定したエンジンはむしろ機能と言えます。

laptop with server

本ガイドでは、導入初日と 30 日後に重要な 4 つのことに焦点を当てます：インストールパス、実際に動作するクイックスタート、実際の動作を変える設定、時間を節約するトラブルシューティングの心構えです。

2026 年でも TGI が依然として重要な理由

推論サーバーを互換性のあるものと扱うのは簡単ですが、一般的なローカルスタックのツール別調査については、Ollama vs vLLM vs LM Studio: 2026 年にローカルで LLM を実行する最善の方法は？から始めてください。

実際には、重要な質問は 3 つだけです。

第一に、負荷下での動作はどうなるか。TGI は連続バッチングとトークンストリーミングを核として構築されているため、スループットを優先しながらも、ユーザーにレスポンス性の錯覚を与え続けることができます。

第二に、既存のツールが使用する方言に対応できるか。TGI は独自の「カスタム API」と、OpenAI Chat Completions スキーマとの互換性を持つ Messages API をサポートしています。つまり、OpenAI 形状のエンドポイントを期待するツールは、最小限の変更で TGI 向けに設定できることが多いです。

第三に、推測なしに可視化できるか。TGI は Prometheus メトリクスを公開し、OpenTelemetry を介した分散トレースをサポートしています。これは、「遅いと思う」ことと、「プリフィルが飽和し、キュー時間が伸び、バッチトークン予算が高すぎる」という状態の間に差を生みます。

インストールパスと必須条件

TGI は Docker を通じて、またはソースからのローカルインストールを通じてアプローチできます。Docker ルートは、多くの人が「TGI をインストールする」と言う際に意味するパスであり、ルーター、モデルサーバー、カーネルを 1 つのイメージにパッケージ化し、単一のコマンドで実行できるようにしています。

内部では、TGI は明確なコンポーネントを持つシステムです：HTTP を受け付け、バッチングを行うルーター、1 つ以上のモデルサーバープロセスを調整するランチャー、モデルをロードし推論を行うモデルサーバーです。この分離は、設定フラグの「なぜ」や一般的な失敗モードの多くを説明します。

実用的な必須条件は常に浮上します：コンテナからの GPU アクセスと、モデル重みの健全なキャッシュ戦略です。Nvidia への GPU アクセスは、通常 Nvidia Container Toolkit のインストールを意味し、キャッシュはホストボリュームをコンテナにマッピングすることで、モデル重みが毎回再ダウンロードされないようにします。

ソースからのローカルインストール

ソースインストールは存在しますが、開発者やカーネルビルダー向けに意見が反映されています。Rust、Python 3.9+、ビルドツールを必要とし、コンテナを実行するよりも最初のステップが遅いことが一般的です。内部を変更する必要がある場合、パッチをテストする場合、非常に特定の環境に統合する場合に有用です。

Docker によるクイックスタート

公式のクイックスタートは短く、それがまさにポイントです。モデル ID を選び、キャッシュボリュームをマウントし、ポートを公開し、コンテナを実行します。

Nvidia GPU クイックスタート

これは、最初の起動によく機能する最小のパターンです。

model=HuggingFaceH4/zephyr-7b-beta
volume=$PWD/data

docker run --gpus all --shm-size 1g -p 8080:80 -v $volume:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id $model

この 1 つのコマンドは、頻繁な FAQ の質問「Docker を使って Nvidia GPU で TGI を実行する方法は？」に暗黙的に答え、「–gpus all」、ポートマッピング、モデル ID という 3 つの譲れない要素を示しています。

微妙だが重要な点はポートマッピングです。コンテナは通常 HTTP でポート 80 でサービスするように構成されているため、ホストの 8080 をコンテナの 80 にマッピングします。Docker 外で TGI を実行する場合、ランチャーのデフォルトポートは通常 3000 であるため、ポートの混乱は最初の日の一般的なバグです。

カスタム API を使用した最初のリクエスト

TGI はシンプルな JSON「generate」スタイルの API を公開しています。ストリーミングリクエストは以下のようになります。

curl 127.0.0.1:8080/generate_stream \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"What is Deep Learning?","parameters":{"max_new_tokens":40}}'

単一のレスポンスを好む場合は、ストリーミングしないエンドポイントを使用します。

curl 127.0.0.1:8080/generate \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{"inputs":"Explain continuous batching in one paragraph.","parameters":{"max_new_tokens":120}}'

Messages API を使用した最初のリクエスト

エコシステムが OpenAI スタイルのチャットリクエストを期待する場合は、Messages API を使用します。これはもう一つの FAQ の質問「TGI を OpenAI 互換のチャットクライアントで使用する方法は？」に直接関連しています。

curl 127.0.0.1:8080/v1/chat/completions \
  -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Give a one sentence definition of tensor parallelism."}
    ],
    "stream": false,
    "max_tokens": 60
  }'

ゲート付きまたはプライベートモデルの提供

「ゲート付きまたはプライベートな Hugging Face モデルを TGI で提供する方法是？」と尋ねたことがある場合、答えは設計上退屈です：HF_TOKEN を介してハブトークンを提供します。

model=meta-llama/Meta-Llama-3.1-8B-Instruct
volume=$PWD/data
token=hf_your_read_token_here

docker run --gpus all --shm-size 1g -e HF_TOKEN=$token -p 8080:80 -v $volume:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id $model

ここでの失敗モードも退屈です：権限不足、無効なトークンスコープ、ライセンスの同意が必要なモデルをプルしようとする。

AMD ROCm クイックスタート

TGI には ROCm イメージと異なるデバイス設定もあります。AMD GPU を使用している場合、起動の形状が変わります。

model=HuggingFaceH4/zephyr-7b-beta
volume=$PWD/data

docker run --device /dev/kfd --device /dev/dri --shm-size 1g -p 8080:80 -v $volume:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5-rocm \
  --model-id $model

CPU のみ実行

CPU 実行は存在しますが、TGI が得意とするプラットフォームではありません。それでも実行する場合、カスタムカーネルを無効にすることで、ハードウェア固有の問題を回避できます。

model=gpt2
volume=$PWD/data

docker run --shm-size 1g -p 8080:80 -v $volume:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id $model \
  --disable-custom-kernels

実際の効果がある設定

TGI には多くのフラグがありますが、ほとんどは記憶する価値がありません。いくつかは理解する価値があり、なぜならこの分野で最も検索される質問「どの TGI 設定が GPU メモリとリクエスト制限を制御するか」に答えるからです。

メモリ予算は最大総トークン数

TGI 設定で最も重要な概念は、サーバーがバッチングを計画し、メモリ爆発を避けるためにトークン予算を必要とすることです。

リクエスト形状を定義する 2 つの上限があります： max_input_tokens と max_total_tokens です。

max_total_tokens は、入力トークンと生成トークンの合計を制限するため、リクエストあたりのメモリ予算のように機能します。高すぎると、各リクエストが高価になり、バッチングが厄介になり、メモリ圧力が高まります。低すぎると、ユーザーは早期に長さ制限に達し、サーバーは本来有効なワークロードを拒否します。

予算を明示的にする設定は以下のようになります。

docker run --gpus all --shm-size 1g -p 8080:80 -v $PWD/data:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id HuggingFaceH4/zephyr-7b-beta \
  --max-input-tokens 2048 \
  --max-total-tokens 3072

重要なバッチング調整

トークン予算を設定した後、バッチング制御が次のレバーになります。

max_batch_prefill_tokens はプリフィル作業を制限し、これは最もメモリ集約的で計算束縛のフェーズであることが多いです。 max_batch_total_tokens は、サーバーが全体にバッチに収めようとするトークン数を設定します。これは実際のスループット制御の 1 つです。

興味深いのは waiting_served_ratio です。これはハードウェア制約ではなく、ポリシー決定をエンコードします。サーバーがデコード作業を一時停止し、待機中のリクエストを新しいプリフィルに含めてデコードグループに参加させるタイミングを制御します。低い値は既存のリクエストを優先し、高い値は新しくキューされたリクエストのテールレイテンシを減らす傾向があり、両方ともトラフィック形状によって「正しい」場合があります。

シャーディング、num shard、NCCL が表示される理由

モデルが 1 つの GPU に収まらない場合、またはテンソル並列化による高いスループットが必要な場合、シャーディングが次のステップです。

メンタルモデルは単純です：--sharded true はシャーディングを有効にし、--num-shard はシャード数を制御します。サーバーはデフォルトですべての見える GPU を使用するか、サブセットを使用できます。

マルチ GPU ホストでの有用なパターンは、GPU をグループに分割し、複数の TGI リプリカを実行することで、各リプリカは独自の GPU サブセットでシャードされます。これは負荷を分散させつつ、シャーディングトポロジーをシンプルに保ちます。

ここでも FAQ の質問「なぜ TGI はマルチ GPU で NCCL または共有メモリエラーで失敗するか」が関連してきます。マルチ GPU セットアップは集団通信に依存し、SHMフォールバックが使用される場合、コンテナは安全な操作のために十分な共有メモリを必要とします。

量子化の選択とトレードオフ

量子化は、「収める」設定の中で最も誤解されており、2 つの異なる目標を混ぜています：メモリ削減と速度です。

TGI は GPTQ や AWQ などのスキーム向けに事前に量子化された重みをサポートし、bitsandbytes や EETQ などの特定のメソッド向けにオンザフライ量子化もサポートします。一部のメソッドはメモリを削減しますが、ネイティブな半精度よりも遅いため、量子化は無料のパフォーマンスアップグレードとして扱うべきではありません。

シンプルなオンザフライ 8 ビット量子化の例は以下のようになります。

docker run --gpus all --shm-size 1g -p 8080:80 -v $PWD/data:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id HuggingFaceH4/zephyr-7b-beta \
  --quantize bitsandbytes

4 ビット変種は以下のようになります。

docker run --gpus all --shm-size 1g -p 8080:80 -v $PWD/data:/data \
  ghcr.io/huggingface/text-generation-inference:3.3.5 \
  --model-id HuggingFaceH4/zephyr-7b-beta \
  --quantize bitsandbytes-nf4

API 形状と基本的なガードレール

TGI は内部サービスとして、またはより広く公開して実行できます。公開可能な場合、2 つのフラグが重要です： max_concurrent_requests と api_key です。

max_concurrent_requests はバックプレッシャーを提供します。すべてをキューに入れてタイムアウトするのではなく、サーバーが過剰なリクエストを拒否するようにします。

API キーは粗い認証バリアを提供します。完全な認証システムではありませんが、偶然の公開使用を止めます。

CORS は cors_allow_origin を介しても構成でき、ブラウザベースの UI がサーバーに直接呼び出す場合に重要です。

運用と可視化

このセクションは、実際のオペレーターの質問「TGI サーバーから Prometheus メトリクスをスクレイピングできる場所は？」に答えます。

OpenAPI ドキュメントとインタラクティブドキュメント

TGI は /docs ルート下で OpenAPI と Swagger UI を公開し、クライアントを書くことなくリクエストとレスポンスの形状を素早く確認したり、エンドポイントをテストしたりする際に便利です。

Prometheus メトリクス

TGI は /metrics エンドポイントで Prometheus メトリクスをエクスポートします。これらのメトリクスはキューサイズ、リクエストレイテンシ、トークン数、バッチレベルのタイミングをカバーします。結果として、システムがプリフィル、デコード、またはキューイングによって制限されているかを観察できます。

エンドツーエンドの本番監視—PromQL、Grafana ダッシュボード、アラート、およびこれらのスタック向けの Docker や Kubernetes スクレイプレイアウトは、本番環境での LLM 推論監視 (2026): Prometheus & Grafana for vLLM, TGI, llama.cpp でカバーされています。

トレースと構造化ログ

TGI は OpenTelemetry を介した分散トレースをサポートしています。ログも JSON で出力でき、ログパイプラインを容易にします。

トラブルシューティングプレイブック

TGI の失敗は数個のバケットに集まり、各バケットには非常に異なる修正があります。

コンテナは実行されるが GPU が検出されない

最も一般的な原因は、コンテナランタイムが GPU パススルー用に構成されていないことです。Nvidia では、これは通常、Nvidia Container Toolkit サポートの欠如、または期待に一致しないホストドライバースタックで実行されていることに関連します。

モデルダウンロード失敗と権限エラー

サーバーがモデルファイルをダウンロードできない場合、一般的な犯人はゲート付きモデル用の認証トークンの欠如、モデル読み取り権限のないトークン、またはレート制限です。HF_TOKEN を正しく設定することで、ゲート付きモデルのケースを解決します。

負荷下での CUDA メモリ不足または突然の再起動

最も一般的な原因は、過度に許容的なトークン予算です。max_total_tokens が大きく、クライアントが長い生成をリクエストする場合、サーバーは最悪の場合のリクエストのためにメモリを予約します。予算を減らし、並行度を減らし、または制約に合う量子化メソッドを選択します。

マルチ GPU NCCL エラー、ハング、または極端な減速

複数の GPU でシャーディングする場合、共有メモリと NCCL が重要です。コンテナ内の不十分な共有メモリは不安定性を引き起こすことがよくあります。共有メモリ割り当てを増やすか、NCCL_SHM_DISABLE を介して SHM 共有を無効にすることで挙動が変わり、パフォーマンスのトレードオフがあります。

NCCL 問題は、NCCL デバッグログを有効にすることでデバッグしやすくなり、エラーレポートがより明確になるためです。

A100 以外のハードウェアでの奇妙なカーネルエラー

一部のモデルは、最初に特定のハードウェアでテストされたカスタムカーネルを使用します。説明できないカーネル失敗が見られる場合、--disable-custom-kernels は、カスタムカーネルが関係しているかを確認する最も簡単な方法です。

ポートの混乱と「実行されるが到達できない」

クラシックな足銃は、Docker ポートマッピングモデルとローカルデフォルトポートモデルを混同することです。Docker 例では、コンテナは通常 80 でサービスし、ローカル実行はデフォルトで 3000 です。間違ったポートをマッピングすると、curl リクエストは何も当たらず、システムは壊れているように見えますが、実際には到達不能なだけです。

結びの言葉

TGI はインフラストラクチャーのように感じます。それが称賛です。テキスト生成を運用可能に退屈にし、デバッグ可能に測定でき、既存の OpenAI 形状のクライアントスタックに適合するほど柔軟なシステムとして設計されています。