Hugging Faceアカウントトークンとカスタム推論エンドポイントをHuggingChatに接続する方法

プライベートなオープンソースモデルや社内ファインチューニングモデルをHuggingChatのインターフェースで運用するには、まずプラットフォームの構造を正しく把握する必要があります。多くの開発者は公開されているHuggingChat（hf.co/chat）の設定画面を開き、エンドポイントURLやAPIトークンを直接入力できる項目を探しがちです。しかし、公開版HuggingChatは公式ルーター基盤上で稼働するマルチテナント型のデモプラットフォームであり、セキュリティおよびインフラ分離の観点から、外部のプライベート推論エンドポイントを共有Web画面に直接登録する機能は提供されていません。

HuggingChatのUIを用いてプライベートモデルを安全に動かす正規の方法は、HuggingChatの基盤ソフトウェアであるオープンソースの Chat UI を自身のリソース上にデプロイすることです。Chat UIはOpenAI互換のAPI仕様にネイティブ対応しており、環境変数 OPENAI_BASE_URL と OPENAI_API_KEY を設定するだけで、Text Generation Inference（TGI）やvLLMでホストされたHugging Faceの専用推論エンドポイント（Inference Endpoints）へ直接チャットをルーティングできます。この構成は、プライベートなHugging Face Space上またはローカルDocker環境で数分で構築可能です。

全体構成とアーキテクチャ

プライベート連携は以下の3つの要素で構成されます。

1. Hugging Face Inference Endpoints: 独自モデルや非公開リポジトリのモデル（Llama 3.3、Mistral、Qwen、社内LoRAなど）をTGIやvLLMの高効率推論エンジンで運用し、標準的なOpenAI互換ルート（/v1/chat/completions）を公開するマネージド基盤。
2. User Access Token（アカウントアクセストークン）: プライベートエンドポイント呼び出し時の認証を行うAPIキー。
3. Chat UI（専用HuggingChatインスタンス）: エンドポイントからモデルを取得してチャット画面を提供するフロントエンドWebアプリ。

+-------------------------------------------------------------+
|                     専用 Chat UI インスタンス               |
|             (Hugging Face Space / ローカル Docker)          |
+-------------------------------------------------------------+
                               |
               OPENAI_BASE_URL | OPENAI_API_KEY (hf_xxx)
                               v
+-------------------------------------------------------------+
|             Hugging Face Inference Endpoint                 |
|   https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1   |
|                 (TGI / vLLM コンテナ稼働)                   |
+-------------------------------------------------------------+
                               |
                               v
+-------------------------------------------------------------+
|                 非公開リポジトリ / 調整済みモデル重み       |
+-------------------------------------------------------------+

ステップ1：専用推論エンドポイント（Inference Endpoint）の作成

Hugging Faceの専用GPUリソースにモデルをデプロイします。

1. Inference Endpoints 管理コンソール にアクセスします。
2. Create New Endpoint をクリックします。
3. Model Repository: 対象のプライベートモデルリポジトリ（例: your-org/private-llama-3-8b-instruct）またはHub上のオープンモデルを指定します。
4. Cloud Provider & Region: クラウド事業者（AWSまたはAzure）とレイテンシの低いリージョンを選択します。
5. Instance Type: モデルの規模に適したハードウェアを選択します（8BモデルならNVIDIA A10G 1基、70BモデルならA100/H100複数基）。
6. Framework & Engine: 推論エンジンとして Text Generation Inference (TGI) または vLLM を選択します。どちらもOpenAI互換のスキーマを標準で備えています。
7. Create Endpoint をクリックします。

ステータスが Building から Running に変化するまで待ちます。コンソール上に表示される専用URLを確認して控えます。

https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud

ステップ2：アクセストークン（Access Token）の取得

保護されたエンドポイントへのリクエストには認証トークンが必要です。

1. アカウントの Settings > Access Tokens（hf.co/settings/tokens）を開きます。
2. Create new token をクリックします。
3. トークンの種別を選択します。
   • Fine-grained token（推奨）: Inference 権限グループ内の「Make calls to your Inference Endpoints」にチェックを入れます。
   • Read token: 個人アカウント所有のエンドポイントであれば、Read権限のトークンでも呼び出し可能です。
4. 生成された文字列（hf_...）をコピーし、安全な場所に保管します。

ステップ3：Chat UI（HuggingChat）の設定と起動

Chat UIはベースURLの末尾に /v1 を付与することで、自動的にモデル検出とリクエストの転送を行います。

選択肢A：Hugging Face Spacesでのワンクリックデプロイ（推奨）

インフラ管理の手間をかけずチーム内で利用したい場合、公式Spaceテンプレートの利用が最適です。

1. Chat UI 公式Spaceテンプレート を開きます。
2. 公開範囲（Visibility）を Private に設定し、社外からのアクセスを遮断します。
3. Spaceの Settings > Variables and Secrets に以下の環境変数を登録します。
   • OPENAI_BASE_URL: https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1
   • OPENAI_API_KEY: hf_************************（ステップ2で取得したトークン）
4. （任意）会話履歴をSpace再起動後も永続化したい場合は MONGODB_URL を指定します。個人利用であれば設定不要で、組み込みデータベースが自動利用されます。
5. Spaceを再起動すると、Chat UIがエンドポイントを認識し、HuggingChatと同じ操作画面で会話が開始できます。

選択肢B：ローカル環境またはオンプレミス自作（Node.js / Docker）

ローカルマシンや社内Kubernetes環境で運用する場合の手順です。

1. Chat UIのリポジトリをクローンします。

   git clone https://github.com/huggingface/chat-ui.git
   cd chat-ui
   

2. .env.local 設定ファイルを作成します。

   # 推論エンドポイント設定
   OPENAI_BASE_URL=https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1
   OPENAI_API_KEY=hf_your_token_here
   
   # データベース設定（未指定の場合はローカルの ./db ディレクトリに自動永続化）
   # MONGODB_URL=mongodb://localhost:27017
   

3. エンドポイント側で /v1/models の自動探索に対応していない場合や、モデル名・パラメータを固定したい場合は、.env.local 内の MODELS JSON5配列で定義します。

   MODELS=`[
     {
       "id": "tgi",
       "name": "社内専用カスタムモデル",
       "multimodal": false,
       "supportsTools": false,
       "parameters": {
         "temperature": 0.7,
         "max_tokens": 4096
       }
     }
   ]`
   

4. 依存パッケージをインストールして起動します。

   npm install
   npm run dev -- --open
   

ブラウザで http://localhost:5173 が自動で開き、プライベートモデルに接続された専用HuggingChatが利用可能になります。

接続確認テスト

ブラウザ経由でテストする前に、ターミナルから curl で直接疎通を確認しておくとトラブルシューティングが容易になります。

curl -X POST "https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1/chat/completions" \
  -H "Authorization: Bearer hf_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tgi",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello! Confirm endpoint readiness."}
    ],
    "max_tokens": 50
  }'

モデルからの生成テキストを含む正常なJSONが返却されれば、認証トークンと推論コンテナの準備は完了です。

運用上の注意点とトレードオフ

• 公開版アシスタント（Assistants）との機能差: 公開版 hf.co/chat 上で作成できるアシスタントは、システムプロンプトの指定やRAGドキュメントのアップロードに対応していますが、ベースモデルは公開カタログからしか選べません。社外秘モデルや独自重みを用いるにはChat UIのセルフホストが必須です。
• コールドスタート対策（Scale-to-Zero）: コスト削減のためにアイドル時0レプリカに自動停止する設定にしている場合、復帰時にGPUコンテナの起動待ちが発生し、UI側で初回タイムアウトが起きることがあります。本番利用では最小レプリカ数を1以上にしておくことを推奨します。
• ストリーミング通信（Streaming）: Chat UIはServer-Sent Events（SSE）を用いて逐次テキストを表示します。TGIやvLLMは標準対応していますが、リバースプロキシ（Nginx等）を経由させる際はバッファリング設定を無効化（proxy_buffering off;）してください。

参考資料

• Chat UI · Hugging Face
• Configuration Overview · Hugging Face
• Running Locally · Hugging Face
• Inference Endpoints · Hugging Face