Chat UI

这是一个面向大型语言模型的聊天界面。它基于 SvelteKit 构建，并为 HuggingChat (hf.co/chat) 提供支持。

0. 快速入门
1. 数据库选项
2. 启动
3. 可选的 Docker 镜像
4. 额外参数
5. 构建

[!NOTE]
Chat UI 仅通过 OPENAI_BASE_URL 和 /models 端点支持 OpenAI 兼容的 API。已移除特定于提供商的集成（旧版 MODELS 环境变量、GGUF 发现、嵌入、网络搜索辅助工具等），但任何遵循 OpenAI 协议的服務（如 llama.cpp 服务器、Ollama、OpenRouter 等）都将默认正常工作。

[!NOTE]
旧版本仍可在 legacy 分支 找到。

快速入门

Chat UI 仅与 OpenAI 兼容的 API 通信。启动它的最快方式是使用 Hugging Face 推理提供商路由器以及您的个人 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 部署。

[!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。

启动

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

npm install
npm run dev

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

可选的 Docker 镜像

chat-ui-db 镜像将 MongoDB 捆绑在容器内：

docker run \
  -p 3000:3000 \
  -e OPENAI_BASE_URL=https://router.huggingface.co/v1 \
  -e OPENAI_API_KEY=hf_*** \
  -v chat-ui-data:/data \
  ghcr.io/huggingface/chat-ui-db:latest

所有 .env.local 中接受的环境变量都可以通过 -e 参数提供。

额外参数

主题

您可以使用一些环境变量来定制 chat-ui 的外观和体验。默认值为：

PUBLIC_APP_NAME=ChatUI
PUBLIC_APP_ASSETS=chatui
PUBLIC_APP_DESCRIPTION="Making the community's best AI chat models available to everyone."
PUBLIC_APP_DATA_SHARING=

• PUBLIC_APP_NAME：用作整个应用程序标题的名称。
• PUBLIC_APP_ASSETS：用于在 static/$PUBLIC_APP_ASSETS 目录下查找 Logo 和 Favicon。当前可选值为 chatui 和 huggingchat。
• PUBLIC_APP_DATA_SHARING：设置为 1 可在用户设置中添加一个开关，允许您的用户选择是否与模型创建者共享数据。

模型

模型通过 ${OPENAI_BASE_URL}/models 接口自动发现。您还可以通过 MODELS 环境变量 (JSON5 格式) 选择性覆盖它们的元数据。已移除旧版特定于提供商的集成和 GGUF 发现。授权首选使用 OPENAI_API_KEY。HF_TOKEN 仍然作为旧版别名保留。

LLM 路由器 (可选)

Chat 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。

当您在界面中选择 Omni 时，Chat UI 将：

• 根据请求特征（是否附加图片、是否启用 MCP 服务器，或默认情况）本地选择一个路由。
• 立即发送 RouterMetadata (路由和实际使用的模型)，以便界面显示。
• 通过您配置的 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 数组：名称、URL、可选的请求头
MCP_SERVERS=[
  {"name": "Web Search (Exa)", "url": "https://mcp.exa.ai/mcp"},
  {"name": "Hugging Face MCP Login", "url": "https://hf.co/mcp?login"}
]

# 当官方 HF MCP 登录端点的服务器条目未设置 Authorization 请求头时，
# 转发已登录用户的 Hugging Face 令牌。
MCP_FORWARD_HF_USER_TOKEN=true

启用路由器工具路径 (Omni)：

• 设置 LLM_ROUTER_ENABLE_TOOLS=true，并使用 LLM_ROUTER_TOOLS_MODEL=<模型 ID 或名称> 选择一个支持工具的模型。
• 目标模型必须支持 OpenAI 工具/函数调用。Chat UI 会在宣传此功能的模型上显示“工具”徽章；您也可以在设置中针对每个模型强制启用它（见下文）。

在界面中使用工具：

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

按模型覆盖设置：

• 在“设置”->“模型”中，您可以针对每个模型切换“工具调用 (函数)”和“多模态输入”。即使提供商元数据未宣传该功能，这些覆盖设置也会生效。

构建

要为您的应用创建生产版本：

npm run build

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

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