如何將 Hugging Face 帳號權杖與自訂推論端點接入 HuggingChat

想要在 HuggingChat 介面中運行私有開源大模型或客製化微調模型，必須先釐清其架構運作邏輯。許多開發者在造訪官方公開版 HuggingChat（hf.co/chat）時，習慣在個人設定或助手介面尋找輸入自訂 API 端點網址與 Token 的欄位。然而，公開版 HuggingChat 是官方維運的多租戶展示平台，流量直接串接官方路由架構，基於安全隔離與算力調度，公開網頁並不支援任意掛載外部專屬端點。

要真正享有 HuggingChat 互動體驗並運行私有模型，標準且符合生產規範的做法是部署一套獨立的 Chat UI——這正是支撐 HuggingChat 的官方開源 SvelteKit 專案。Chat UI 原生相容 OpenAI API 規範，開發者僅需設定環境變數 OPENAI_BASE_URL 與 OPENAI_API_KEY，即可將前端直連至由 Text Generation Inference（TGI）或 vLLM 驅動的 Hugging Face 專屬推論端點（Inference Endpoints）。整個流程無論是在 Hugging Face Space 一鍵啟動，或於本地環境以 Docker 部署，皆十分便捷。

系統架構與工作流程

完整的私有串接鏈路包含三個核心元件：

Hugging Face Inference Endpoints（推論端點）：託管私有儲存庫模型或開源大模型（如 Llama 3.3、Mistral、Qwen 或專屬 LoRA 權重），由 TGI 或 vLLM 提供生產級加速推論，並開放標準 OpenAI 相容的 /v1/chat/completions 端點。
User Access Token（使用者存取權杖）：提供對私有端點發出請求時的身份驗證。
Chat UI（私有 HuggingChat 實例）：作為前端對話介面，直接調用專屬端點，呈現與公開版完全一致的交談、多模態與工具調用體驗。

+-------------------------------------------------------------+
|                     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
+-------------------------------------------------------------+
|                  私有模型儲存庫 / 微調權重                  |
+-------------------------------------------------------------+

步驟一：建立專屬推論端點（Inference Endpoint）

首先在 Hugging Face 託管算力中建立專屬模型服務：

登入 Hugging Face 並開啟 Inference Endpoints 管理主控台。
點擊 Create New Endpoint。
Model Repository：輸入要部署的模型儲存庫路徑（例如私有庫 your-org/private-llama-3-8b-instruct 或公共 Hub 模型）。
Cloud Provider & Region：選擇雲端供應商（AWS 或 Azure）以及延遲較低的所在區域。
Instance Type：依模型參數量配置對應硬體（如 8B 模型配置單張 NVIDIA A10G，70B 模型配置多張 A100/H100）。
Framework & Engine：在推論引擎中選擇 Text Generation Inference (TGI) 或 vLLM。這兩款容器預設均提供相容 OpenAI 規範的路由介面。
點擊 Create Endpoint。

等待服務狀態由 Building 轉換為 Running。在主控台面板中記錄專屬存取 URL：

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

步驟二：生成具備授權的存取權杖（Access Token）

呼叫受保護的專屬推論端點需要合法的認證金鑰：

前往個人帳號的 Settings > Access Tokens（hf.co/settings/tokens）。
點擊 Create new token。
選擇權杖類型：
- Fine-grained token（細粒度權杖，推薦）：在 Inference 權限清單中勾選「Make calls to your Inference Endpoints」。
- Read token：針對個人帳號旗下的推論端點，具備 Read 權限的權杖亦可正常呼叫。
複製生成的字串（格式為 hf_...），並安全保存於密碼庫或部署環境設定中。

步驟三：設定並啟動 Chat UI（HuggingChat）

Chat UI 透過在 Base URL 後方自動串接 /v1 來探索可用模型與轉發對話內容。

方案 A：一鍵部署至 Hugging Face Space（推薦）

若希望為內部團隊提供無需維運實體主機的私有對話服務，可直接複製官方 Space 範本：

開啟 Chat UI 官方 Space 範本。
將 Space 權限設為 Private，防止未經授權的公開存取。
在 Space 的 Settings > Variables and Secrets 新增下列環境變數：
- OPENAI_BASE_URL：https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1
- OPENAI_API_KEY：hf_************************（填入步驟二取得的存取權杖）
（選用）若需在 Space 重啟後保留對話歷史紀錄，可設定 MONGODB_URL；若僅供個人測試，Chat UI 會自動採用內嵌資料庫。
重啟 Space，Chat UI 將自動探測端點架構並在介面中就緒，團隊即可立即展開交談。

方案 B：本機或企業伺服器自建（Node.js / Docker）

若需部署於企業內部網路、工作站或專有伺服器：

複製 Chat UI 開源儲存庫：

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

建立 .env.local 設定檔：

# 專屬推論端點設定
OPENAI_BASE_URL=https://<endpoint-id>.<region>.<cloud>.endpoints.huggingface.cloud/v1
OPENAI_API_KEY=hf_your_token_here

# 資料庫設定（本地開發若未指定 MONGODB_URL，預設採用 ./db 內嵌式資料庫）
# MONGODB_URL=mongodb://localhost:27017

若特定端點未支援 /v1/models 自動列舉，或需自訂前端顯示名稱與推論參數，可在 .env.local 中明確配置 MODELS JSON5 變數：

MODELS=`[
  {
    "id": "tgi",
    "name": "企業私有專屬模型",
    "multimodal": false,
    "supportsTools": false,
    "parameters": {
      "temperature": 0.7,
      "max_tokens": 4096
    }
  }
]`

安裝依賴套件並啟動開發伺服器：
```
npm install
npm run dev -- --open
```

瀏覽器將自動開啟 http://localhost:5173，完整呈現連線至專屬權重的 HuggingChat 對話介面。

連線驗證與測試

在正式透過瀏覽器進行交談前，建議先以終端機指令驗證端點運作狀態與金鑰正確性：

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 建立助手僅能自訂提示詞（Prompt）與掛載檢索知識庫（RAG），底層模型仍受限於官方提供的公用開源模型清單。若需完全隔離資料或使用專屬微調模型，自建 Chat UI 實例為必要途徑。
冷啟動延遲（Scale-to-Zero）：若推論端點設定為無請求時自動縮容至 0 副本以節省成本，休眠後的首次對話可能因 GPU 容器啟動時間而發生請求逾時。建議在生產環境中設定至少 1 個常駐副本。
串流輸出（Streaming）：Chat UI 依賴 Server-Sent Events（SSE）呈現逐字輸出。TGI 與 vLLM 原生支援此特性，若前端架設反向代理（如 Nginx），請確保停用代理快取緩衝（proxy_buffering off;），以保障流暢的對話響應。

如何將 Hugging Face 帳號權杖與自訂推論端點接入 HuggingChat

讓你的 AI 用上 365 Wiki

365Wiki Skill

系統架構與工作流程

步驟一：建立專屬推論端點（Inference Endpoint）

步驟二：生成具備授權的存取權杖（Access Token）

步驟三：設定並啟動 Chat UI（HuggingChat）

方案 A：一鍵部署至 Hugging Face Space（推薦）

方案 B：本機或企業伺服器自建（Node.js / Docker）

連線驗證與測試

關鍵評估與實務建議

參考資料

如何將 Hugging Face 帳號權杖與自訂推論端點接入 HuggingChat

系統架構與工作流程

步驟一：建立專屬推論端點（Inference Endpoint）

步驟二：生成具備授權的存取權杖（Access Token）

步驟三：設定並啟動 Chat UI（HuggingChat）

方案 A：一鍵部署至 Hugging Face Space（推薦）

方案 B：本機或企業伺服器自建（Node.js / Docker）

連線驗證與測試

關鍵評估與實務建議

參考資料

涉及產品