ghcr.io/huggingface/chat-ui-db:sha-5ea8995

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 等）默认均可使用。

OPENAI_BASE_URL、/models、MODELS

旧版本仍可在 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 会回退到持久化到 ./db 的嵌入式 MongoDB。

MONGODB_URL、./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。

Chat UI 可以调用由模型上下文协议（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= 选择支持工具的目标。

LLM_ROUTER_ENABLE_TOOLS=true
  LLM_ROUTER_TOOLS_MODEL=

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

在 UI 中使用工具

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

每个模型的覆盖设置

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

构建

要创建应用的生产版本：

npm run build

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

npm run preview

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

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

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

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

# 服务器 JSON 数组：name、url、可选 headers
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 服务器”，以添加服务器、启用服务器并运行健康检查。服务器卡片会列出可用工具。
• 当模型调用工具时，消息会显示一个包含参数的简洁“工具”块、运行时的进度条以及结果（或错误）。结果也会反馈给模型以进行后续处理。

模型级覆盖设置：

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

构建

要创建应用的生产版本：

npm run build

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

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