huggingface/chat-ui

📣 huggingface/chat-ui 是什么？

一个轻量级、开源的前端，用于与任何兼容 OpenAI 的语言模型端点聊天。它基于 SvelteKit 构建，并驱动着公开的 HuggingChat 服务（hf.co/chat）。该 UI 处理用户账户、聊天历史、模型选择、主题以及可选工具调用（MCP）或多模态输入，而将所有推理委托给支持 OpenAI /v1 协议的外部 API（例如：Hugging Face Inference Router、llama.cpp 服务器、Ollama、OpenRouter 等）。

🎯 核心功能

功能	工作原理	重要性
模型无关的后端	通过 `OPENAI_BASE_URL` 和 `OPENAI_API_KEY` 连接到任何暴露 OpenAI `/v1` API 的服务。	无需代码更改即可在托管 HF 模型、本地 `llama.cpp`、Ollama 或任何商业提供商之间切换。
聊天持久化	将用户、对话、设置和文件上传存储在 MongoDB 中。默认情况下，它会回退到写入 `./db` 的嵌入式 MongoDB。	跨会话保留历史记录，并且本地开发开箱即用。
Omni 路由器（可选）	内置的启发式算法，为每个请求选择一个路由（默认、多模态或工具支持），然后为该路由选择一个具体模型。可通过 JSON 策略文件和环境变量进行配置。	提供单个“Omni”模型条目，自动为图像、函数调用或纯文本选择最佳后端。
MCP 工具集成	支持 Model Context Protocol 服务器；UI 可以调用外部工具（搜索、数据库查询等），并使用 OpenAI 函数调用将结果反馈给模型。	无需编写自定义后端代码，即可实现更丰富、更具代理性的对话。
主题与品牌化	简单的环境变量（`PUBLIC_APP_NAME`、`PUBLIC_APP_ASSETS` 等）可让您重命名应用、更换 Logo 或切换数据共享选择。	轻松将 UI 嵌入到产品或社区站点中。
Docker 就绪	官方 `ghcr.io/huggingface/chat-ui-db` 镜像捆绑了 UI 和嵌入式 MongoDB，并公开了相同的环境变量接口。	一条命令即可部署到任何容器主机或云服务。
ML Intern 模式	实验性的“助手”，可以在对话中生成并运行 Hugging Face Hub 作业（论文复现、微调、数据集创建），并尊重每个用户的计算预算。	将聊天 UI 转变为低代码的 ML 工作流编排器。

🛠️ 快速开始

创建 .env.local，至少包含：

OPENAI_BASE_URL=https://router.huggingface.co/v1   # 或任何兼容 OpenAI 的 URL
OPENAI_API_KEY=hf_XXXXXXXXXXXXXXXXXXXXXXXXX      # 您的令牌或本地服务器的虚拟密钥

克隆并安装

git clone https://github.com/huggingface/chat-ui
cd chat-ui
npm install
npm run dev -- --open   # 启动 http://localhost:5173

（可选）添加 MongoDB – 将 MONGODB_URL 设置为远程 Atlas 集群或运行本地容器：
```
docker run -d -p 27017:27017 --name mongo-chatui mongo:latest
```
如果省略 MONGODB_URL，将自动使用嵌入式数据库。

部署 – 对于生产环境，运行 npm run build && npm run preview 或使用提供的 Docker 镜像：

docker run -p 3000:3000 \
  -e OPENAI_BASE_URL=… -e OPENAI_API_KEY=… \
  -v chat-ui-data:/data \
  ghcr.io/huggingface/chat-ui-db:latest

📚 典型用例

自托管 ChatGPT 风格的 UI：用于私有模型（例如公司内部 LLM），无需从头构建前端。
研究模型演示平台：连接 llama.cpp 服务器或 Ollama 模型，让用户通过精美的 Web UI 进行交互。
工具增强代理：通过 MCP 公开搜索或代码执行服务，并让模型自动调用它们。
多模态实验：通过 Omni 路由器将图像输入路由到具有视觉能力的模型。
ML Intern 游乐场：让非技术用户直接从聊天中触发微调作业或数据集构建。

⚠️ 局限性与注意事项

仅支持 OpenAI 风格的 API – 使用不同协议（例如原生 Hugging Face pipeline 端点）的提供商不受支持。
没有超越 /models 的内置模型发现机制 – 您必须在后端公开 /models 列表，或手动配置 MODELS 环境变量。
自定义路由需要路由器策略文件 – 默认分支不附带示例 JSON；如果您想超越内置启发式算法，则需要创建一个。
MCP 支持依赖于模型的函数调用能力 – 如果所选模型不支持工具，UI 将隐藏该功能。
生产部署仍需要 SvelteKit 适配器（例如：Vercel、Netlify、Cloudflare） – 自述文件中提到了这一点，但没有提供现成的配置。

📦 总结

huggingface/chat-ui 是一个可直接运行的、基于 SvelteKit 的 Web 聊天前端，可与任何兼容 OpenAI 的 LLM 端点配合使用。它通过 MongoDB 提供持久化历史记录、可选智能路由（Omni）、通过 MCP 进行工具集成、主题以及用于轻松部署的 Docker 镜像。非常适合任何希望在无需编写 UI 代码的情况下获得精美聊天界面，同时还能接入本地或云端 LLM、多模态模型或代理工具调用的人。

huggingface/chat-ui