如何将 Hugging Face 账号令牌与自定义推理端点接入 HuggingChat

想要在 HuggingChat 界面中运行私有开源大模型或企业微调模型，必须先理解其底层架构机制。不少开发者在访问官方公开版 HuggingChat（hf.co/chat）时，试图在用户设置或助手面板中寻找直接输入自定义 API 端点和令牌的输入框。然而，公开版 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。在端点控制面板中记录生成的独立专属访问地址：

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）

连通性测试与验证

核心选型与注意事项

参考资料

涉及产品