ghcr.io/huggingface/chat-ui:sha-7a457d4

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 会回退到嵌入式 MongoDB，数据持久化到 ./db。

MONGODB_URL ./db## MongoDB Atlas（托管版）

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

本地 MongoDB（容器）

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

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

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

MONGODB_URL=mongodb://localhost:27017 env.local## 启动

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

npm install
npm run dev

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

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 标志提供。

.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_NAME- PUBLIC_APP_ASSETS 用于在 static/$PUBLIC_APP_ASSETS 中查找徽标和图标，当前选项为 chatui 和 huggingchat。 PUBLIC_APP_ASSETS static/$PUBLIC_APP_ASSETS chatui huggingchat- PUBLIC_APP_DATA_SHARING 可设置为 1，以在用户设置中添加切换开关，允许用户选择是否与模型创建者共享数据。 PUBLIC_APP_DATA_SHARING## 模型

模型通过 ${OPENAI_BASE_URL}/models 发现，您可以选择通过 MODELS 环境变量（JSON5）覆盖其元数据。旧版特定提供商集成和 GGUF 发现已被移除。授权使用 OPENAI_API_KEY（首选）。HF_TOKEN 仍是旧版别名。

${OPENAI_BASE_URL}/models MODELS OPENAI_API_KEY HF_TOKEN## LLM 路由（可选）

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

multimodal agentic default- 通过 LLM_ROUTER_ROUTES_PATH 提供路由策略 JSON。此分支不附带示例文件，因此您必须将变量指向自己创建的 JSON 数组（例如，在项目中提交 config/routes.chat.json）。每个路由条目需要 name、description、primary_model 和可选的 fallback_models。路由识别 default、multimodal 和 agentic 路由名称。 LLM_ROUTER_ROUTES_PATH config/routes.chat.json name description primary_model fallback_models default multimodal agentic- 默认路由名称可通过 LLM_ROUTER_DEFAULT_ROUTE 配置（默认值：default）。如果所选路由的所有模型均失败，调用会回退到 LLM_ROUTER_FALLBACK_MODEL。 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。 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。 OPENAI_BASE_URL LLM_ROUTER_FALLBACK_MODEL工具和多模态快捷方式：

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

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

每个模型的覆盖设置

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

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"}
]

# 当服务器条目中未设置 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 预览生产构建。

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