ghcr.io/huggingface/chat-ui-db:sha-b16ec46

Chat UI

LLM 的聊天界面。这是一个 SvelteKit 应用，为 hf.co/chat 上的 HuggingChat 应用提供支持。

• 快速入门
• 数据库选项
• 启动
• 可选 Docker 镜像
• 额外参数
• 构建

Chat UI 仅通过 OPENAI_BASE_URL 和 /models 端点支持与 OpenAI 兼容的 API。已移除特定提供商的集成（旧版 MODELS 环境变量、GGUF 发现、嵌入、网络搜索助手等），但任何支持 OpenAI 协议的服务（llama.cpp server、Ollama、OpenRouter 等）默认均可使用。

旧版本仍可在 legacy 分支获取。

快速入门

Chat UI 仅支持与 OpenAI 兼容的 API。最快的运行方式是使用 Hugging Face Inference Providers 路由器以及您的个人 Hugging Face 访问令牌。

步骤 1 – 创建 .env.local：

OPENAI_BASE_URL=https://router.huggingface.co/v1
OPENAI_API_KEY=hf_************************

OPENAI_API_KEY 可来自您计划调用的任何与 OpenAI 兼容的端点。选择与您的设置匹配的组合，并将值放入 .env.local：

.env

步骤 2 – 安装并启动开发服务器：

git clone https://github.com/huggingface/chat-ui
cd chat-ui
npm install
npm run dev -- --open

现在您已在本地运行 Chat UI。打开浏览器并开始聊天。

数据库选项

聊天历史、用户、设置、文件和统计信息均存储在 MongoDB 中。您可以将 Chat UI 指向任何 MongoDB 6/7 部署。

对于快速本地开发，您可以跳过此部分。当未设置 MONGODB_URL 时，Chat UI 会回退到嵌入式 MongoDB，数据持久化到 ./db。

MongoDB Atlas（托管）

• 在 mongodb.com 创建免费集群。
• 将您的 IP（或开发环境使用 0.0.0.0/0）添加到网络访问列表。
• 创建数据库用户并复制连接字符串。
• 将该字符串粘贴到 .env.local 中的 MONGODB_URL。保留默认的 MONGODB_DB_NAME=chat-ui，或根据环境进行更改。

Atlas 可将 MongoDB 部署在您的笔记本电脑之外，非常适合团队或云部署。

本地 MongoDB（容器）

如果您希望在容器中运行 MongoDB：

docker run -d -p 27017:27017 --name mongo-chatui mongo:latest

然后在 .env.local 中设置 MONGODB_URL=mongodb://localhost:27017。

启动

配置环境变量后，使用以下命令启动 Chat UI：

npm install
npm run dev

开发服务器默认监听 http://localhost:5173。生产构建使用 npm run build / npm run preview。

数据库选项

聊天历史、用户、设置、文件和统计数据均存储在MongoDB中。您可以将Chat UI指向任何MongoDB 6/7部署。

[!TIP] 对于快速本地开发，您可以跳过此部分。当未设置MONGODB_URL时，Chat UI会回退到嵌入式MongoDB，数据持久化到./db目录。

MongoDB Atlas（托管版）

1. 在mongodb.com创建免费集群。
2. 将您的IP（或开发环境使用0.0.0.0/0）添加到网络访问列表。
3. 创建数据库用户并复制连接字符串。
4. 将该字符串粘贴到.env.local中的MONGODB_URL。保留默认的MONGODB_DB_NAME=chat-ui，或根据环境修改。

Atlas可将MongoDB部署在您的本地设备之外，非常适合团队或云部署场景。

本地MongoDB（容器版）

如果您希望在容器中运行MongoDB：

docker run -d -p 27017:27017 --name mongo-chatui mongo:latest

然后在.env.local中设置MONGODB_URL=mongodb://localhost:27017。

LLM 路由器（可选）

Chat UI 可使用本地启发式算法执行服务器端智能路由——无需调用单独的路由服务或选择模型。UI 公开一个名为“Omni”的虚拟模型别名（可配置），选择该别名后，系统会为每条消息选择最佳路由/模型：图像输入将路由至 multimodal 路由，启用 MCP 工具的请求将路由至 agentic 路由，其他所有请求则路由至 default 路由。

• 通过 LLM_ROUTER_ROUTES_PATH 提供路由策略 JSON。此分支未附带示例文件，因此你必须将该变量指向自己创建的 JSON 数组（例如，在项目中提交 config/routes.chat.json 之类的文件）。每个路由条目需包含 name、description、primary_model 以及可选的 fallback_models。路由器可识别的路由名称包括 default、multimodal 和 agentic。
• 默认路由名称可通过 LLM_ROUTER_DEFAULT_ROUTE 配置（默认值：default）。如果所选路由的所有模型均失败，调用将回退至 LLM_ROUTER_FALLBACK_MODEL。
• Omni 别名配置：PUBLIC_LLM_ROUTER_ALIAS_ID（默认值 omni）、PUBLIC_LLM_ROUTER_DISPLAY_NAME（默认值 Omni）以及可选的 PUBLIC_LLM_ROUTER_LOGO_URL。

在 UI 中选择 Omni 后，Chat UI 将：

• 根据请求信号（附加图像、启用 MCP 服务器或默认情况）在本地选择路由。
• 立即发送 RouterMetadata（使用的路由和实际模型），以便 UI 显示相关信息。
• 通过你配置的 OPENAI_BASE_URL 从所选模型流式传输内容。发生错误时，系统会按顺序尝试路由回退模型，然后尝试 LLM_ROUTER_FALLBACK_MODEL。

工具和多模态快捷方式：

• 多模态：如果 LLM_ROUTER_ENABLE_MULTIMODAL=true 且用户发送图像，路由器将绕过策略文件并使用 LLM_ROUTER_MULTIMODAL_MODEL 中指定的模型。路由名称：multimodal。
• 工具：如果 LLM_ROUTER_ENABLE_TOOLS=true 且用户至少启用了一个 MCP 服务器，路由器将绕过策略文件并使用 LLM_ROUTER_TOOLS_MODEL。如果该模型缺失或配置错误，将回退至启发式路由。路由名称：agentic。

MCP 工具（可选）

Chat UI 可调用模型上下文协议（Model Context Protocol，MCP）服务器公开的工具，并使用 OpenAI 函数调用将结果反馈给模型。你可以通过环境变量预配置受信任的服务器，允许用户添加自己的服务器，还可选择让 Omni 路由器自动选择支持工具的模型。

配置服务器（所有用户的基础列表）：

# 服务器 JSON 数组：名称、URL、可选标头
MCP_SERVERS=[
{"name": "Web Search (Exa)", "url": "https://mcp.exa.ai/mcp"},
{"name": "Hugging Face MCP Login", "url": "https://hf.co/mcp?login"}
]

# 当该服务器条目不包含 Authorization 标头时，将已登录用户的 Hugging Face 令牌转发到官方 HF MCP 登录端点
MCP_FORWARD_HF_USER_TOKEN=true

启用路由器工具路径（Omni）：

• 设置 LLM_ROUTER_ENABLE_TOOLS=true 并通过 LLM_ROUTER_TOOLS_MODEL= 选择支持工具的目标模型。
• 目标模型必须支持 OpenAI 工具/函数调用。Chat UI 会在宣传此功能的模型上显示“工具”徽章；你也可以在设置中为每个模型强制启用该功能（见下文）。

在 UI 中使用工具：

• 从右上角菜单或聊天输入框的 + 菜单中打开“MCP Servers”，以添加服务器、启用服务器并运行健康检查（Health Check）。服务器卡片会列出可用工具。
• 当模型调用工具时，消息会显示包含参数的紧凑“工具”块、运行时的进度条以及结果（或错误）。结果也会反馈给模型以进行后续处理。

模型级覆盖：

• 在“设置 → 模型”中，你可以为每个模型切换“工具调用（函数）”和“多模态输入”。即使提供程序元数据未宣传这些功能，这些覆盖设置仍然生效。

构建

要创建应用的生产版本：

npm run build

你可以使用 npm run preview 预览生产构建。

要部署应用，你可能需要为目标环境安装一个适配器。