ghcr.io/huggingface/chat-ui-db:sha-60350a6

Chat UI

这是一个面向大语言模型（LLM）的聊天界面，基于 SvelteKit 构建，也是 hf.co/chat 上 HuggingChat 应用的底层服务。

• 快速入门
• 数据库选项
• 启动
• 可选 Docker 镜像
• 额外参数
• ML 内部开发人员
• 构建

Chat UI 仅通过 OPENAI_BASE_URL 和 /models 端点支持兼容 OpenAI 规范的 API。面向特定服务商的集成（旧版 MODELS 环境变量、GGUF 自动发现、嵌入能力、网页搜索辅助功能等）已被移除，但所有遵循 OpenAI 协议的服务（如 llama.cpp server、Ollama、OpenRouter 等）均可直接默认使用。

[!NOTE] 旧版本仍可在 legacy 分支中获取。

---

快速入门

Chat UI 仅对接兼容 OpenAI 规范的 API。最快的启动方式是使用 Hugging Face 推理提供商路由器，搭配你个人的 Hugging Face 访问令牌。

步骤 1 – 创建 .env.local 文件

在 .env.local 中写入以下配置：

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

OPENAI_API_KEY 可以使用你计划对接的任意兼容 OpenAI 端点的密钥。根据你的实际部署组合选择对应值，填入 .env.local 即可。

步骤 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 版本的部署实例。

[!NOTE] 如果你仅做快速本地开发，可以跳过本节。当未设置 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 命令。

---

可选 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="让社区中最优质的 AI 聊天模型面向所有用户开放可用。"
PUBLIC_APP_DATA_SHARING=

• PUBLIC_APP_NAME：应用全局各处使用的标题名称
• PUBLIC_APP_ASSETS：用于指定在 static/$PUBLIC_APP_ASSETS 路径下查找 Logo 和图标资源，当前可选值为 chatui 和 huggingchat
• PUBLIC_APP_DATA_SHARING：将其设置为 1 后，会在用户设置页新增一个开关，允许用户选择是否与模型开发者共享使用数据

模型配置

模型会自动从 ${OPENAI_BASE_URL}/models 端点获取，你也可以通过 MODELS 环境变量（JSON5 格式）自定义覆盖模型元数据。旧版面向特定服务商的集成以及 GGUF 自动发现功能已被移除。鉴权优先使用 OPENAI_API_KEY，HF_TOKEN 为旧版兼容别名仍可使用。

LLM 路由器（可选）

Chat UI 支持通过本地启发式规则实现服务端智能路由，无需额外部署独立的路由服务或模型选择模型。UI 会暴露一个名为 "Omni" 的虚拟模型别名（可自定义配置），用户选择该别名后，系统会为每一条消息自动选择最优的路由/模型：图像输入会走多模态路由、支持 MCP 工具调用的请求会走智能代理路由、其余请求全部走默认路由。

• 通过 LLM_ROUTER_ROUTES_PATH 指定路由策略 JSON 文件路径。当前分支未附带示例文件，你需要自行创建一个 JSON 数组文件（例如在项目中提交 config/routes.chat.json）并将环境变量指向该文件。每个路由条目必须包含 name、description、primary_model 字段，可选配置 fallback_models 字段。路由器会自动识别 default、multimodal、agentic 这三个预留路由名称。
• 默认路由名称可通过 LLM_ROUTER_DEFAULT_ROUTE 自定义（默认值为 default）。如果选中路由下的所有模型调用全部失败，请求会自动 fallback 到 LLM_ROUTER_FALLBACK_MODEL 指定的模型。
• Omni 别名相关配置：PUBLIC_LLM_ROUTER_ALIAS_ID（默认值 omni）、PUBLIC_LLM_ROUTER_DISPLAY_NAME（默认值 Omni），还可配置可选的 PUBLIC_LLM_ROUTER_LOGO_URL 自定义 Logo。

在 UI 中选中 Omni 后，Chat UI 会执行以下逻辑：

• 基于请求特征（是否附带图片、是否启用 MCP 服务器、默认场景）在本地选择对应路由
• 立即返回 RouterMetadata 信息（包含实际使用的路由和模型名称），供前端界面展示
• 通过你配置的 OPENAI_BASE_URL 从选中的模型流式返回响应内容。如果出现错误，系统会按顺序尝试路由配置中设置的 fallback 模型，最后兜底到 LLM_ROUTER_FALLBACK_MODEL。

工具与多模态快捷配置

• 多模态场景：当 LLM_ROUTER_ENABLE_MULTIMODAL=true 且用户上传了图片，路由器会跳过策略配置文件，直接使用 LLM_ROUTER_MULTIMODAL_MODEL 指定的模型处理请求，对应路由名称为 multimodal。
• 工具调用场景：当 LLM_ROUTER_ENABLE_TOOLS=true 且用户至少启用了一个 MCP 服务器，路由器会跳过策略配置文件，直接使用 LLM_ROUTER_TOOLS_MODEL 处理请求。如果该模型未配置或配置错误，会自动 fallback 到启发式规则路由，对应路由名称为 agentic。

MCP Tools（可选）

Chat UI 可通过 OpenAI 函数调用机制，调用由 Model Context Protocol（MCP）服务器暴露的工具，并将工具执行结果返回给大模型。你可以通过环境变量预配置可信的 MCP 服务器，也可开放权限让用户自行添加服务器，还可配置 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= 指定具备工具调用能力的目标模型。 LLM_ROUTER_ENABLE_TOOLS=true LLM_ROUTER_TOOLS_MODEL= 所选目标模型必须兼容 OpenAI 工具/函数调用规范。Chat UI 会在符合能力要求的模型旁展示「tools」标识；你也可以在设置中为任意模型手动强制开启该功能（详见下文）。

在界面中使用工具

• 从右上角菜单或聊天输入框旁的「+」菜单中打开「MCP Servers」面板，即可添加新服务器、开关指定服务器、运行健康检查。每个服务器卡片会展示该节点提供的全部可用工具。
• 当模型触发工具调用时，消息区域会展示紧凑的「tool」模块，包含调用参数、运行中的进度条以及最终返回结果（或错误信息），该结果会自动传回模型用于后续推理生成。

单模型独立配置覆盖

进入「Settings → Model」页面，你可以为每个模型单独切换「Tool calling (functions)」和「Multimodal input」开关。这些配置优先级高于服务商元数据，即使服务商未对外声明该模型支持对应能力，覆盖配置也会生效。

ML Intern

ML Intern 是一项实验性功能，可在 Hugging Face Hub 上自主规划并执行机器学习相关工作：复现学术论文、微调并评估模型、构建数据集、将演示应用部署为 Spaces。它支持读取论文、模型和数据集资源，自动生成脚本，并在你为每个对话单独设置的算力配额范围内，将脚本作为 Hugging Face Job 或沙箱任务运行。

你可以访问 https://huggingface.co/chat/?mode=ml-intern 在 HuggingChat 中直接体验该功能。

• ML Intern 快速上手：完成账户与账单配置，提交首个任务，并管控算力消耗上限。
• 本地部署带 ML Intern 能力的 Chat UI：在自建 Chat UI 中配置启用 ML Intern，选择适配模型，了解对应代码逻辑。

构建

生成应用生产版本：

npm run build

执行以下命令即可预览生产构建产物：

npm run preview

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

---

项目仓库 README（补充）

Chat UI

这是一款面向大语言模型的聊天界面，基于 SvelteKit 开发，是 https://huggingface.co/chat 的底层实现。

目录索引： 0. 快速开始

1. 数据库配置选项
2. 启动服务
3. 可选 Docker 镜像
4. 额外配置参数
5. ML Intern
6. 构建

[!NOTE] Chat UI 目前仅支持通过 OPENAI_BASE_URL 和 /models 端点接入兼容 OpenAI 协议的 API。原有的服务商专属集成（包括旧版 MODELS 环境变量、GGUF 自动发现、嵌入能力、网页搜索助手等）已被移除，所有兼容 OpenAI 协议的服务（llama.cpp server、Ollama、OpenRouter 等）均可直接接入使用。

[!NOTE] 历史旧版本代码仍可在 https://github.com/huggingface/chat-ui/tree/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 版本的部署实例。

[!NOTE] 快速本地开发场景可跳过本部分配置。当未设置 MONGODB_URL 时，Chat UI 会自动降级使用内置嵌入式 MongoDB，所有数据持久化存储在 ./db 目录下。

MongoDB Atlas（托管服务）

1. 前往 https://www.mongodb.com/pricing 创建免费集群实例。
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="让社区中最优质的AI聊天模型面向所有人开放使用。"
PUBLIC_APP_DATA_SHARING=

• PUBLIC_APP_NAME：应用全流程中作为标题显示的名称。
• PUBLIC_APP_ASSETS：用于在 static/$PUBLIC_APP_ASSETS 路径下查找 Logo 和 图标资源，当前可选值为 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。如果当前选中路由下的所有模型调用全部失败，请求会自动 fallback 到 LLM_ROUTER_FALLBACK_MODEL 指定的模型。
• Omni 虚拟别名的可配置项包括：PUBLIC_LLM_ROUTER_ALIAS_ID（默认值为 omni）、PUBLIC_LLM_ROUTER_DISPLAY_NAME（默认值为 Omni），以及可选的 PUBLIC_LLM_ROUTER_LOGO_URL 用于自定义别名的 Logo。

当你在界面中选择 Omni 虚拟模型时，Chat UI 会执行以下逻辑：

• 基于请求特征（是否附带图片、是否启用 MCP 服务器，或默认场景）在本地自动匹配对应路由。
• 立即返回路由元数据（包含实际使用的路由和模型信息），以便界面实时展示该信息。
• 通过你配置的 OPENAI_BASE_URL 地址从选中的模型拉取流式响应。如果调用过程中出现错误，系统会按顺序尝试当前路由下的降级模型，全部失败后再 fallback 到 LLM_ROUTER_FALLBACK_MODEL 指定的全局降级模型。

工具与多模态快速配置规则

• 多模态场景：当 LLM_ROUTER_ENABLE_MULTIMODAL=true，且用户发送了图片时，路由逻辑将直接绕过策略配置文件，自动使用 LLM_ROUTER_MULTIMODAL_MODEL 指定的模型处理请求，对应路由名为 multimodal。
• 工具调用场景：当 LLM_ROUTER_ENABLE_TOOLS=true，且用户至少启用了一个 MCP 服务器时，路由逻辑将直接绕过策略配置文件，自动使用 LLM_ROUTER_TOOLS_MODEL 指定的模型处理请求。如果该模型未配置或配置错误，系统将自动 fallback 到启发式规则路由，对应路由名为 agentic。

MCP 工具（可选）

Chat UI 可以调用 Model Context Protocol（MCP）服务器暴露的工具能力，并通过 OpenAI 函数调用机制将工具执行结果传回大模型。你既可以通过环境变量预配置全局可信的 MCP 服务器，也可以允许用户自行添加私有服务器，还可以配置 Omni 路由器自动自动选择支持工具调用的模型。

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

# MCP 服务器配置 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"}
]

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

启用 Omni 路由的工具调用通路：

• 设置 LLM_ROUTER_ENABLE_TOOLS=true，并通过 LLM_ROUTER_TOOLS_MODEL= 指定一个支持工具调用的目标模型。
• 该目标模型必须兼容 OpenAI 工具/函数调用协议。Chat UI 会在模型列表中为自行声明该能力的模型展示 "tools" 标识；你也可以在设置中强制为任意模型开启该能力，具体方法见下文。

在界面中使用工具的操作流程：

• 你可以从右上角菜单或聊天输入框旁的 + 菜单中打开 "MCP 服务器" 面板，新增自定义服务器、开关服务器启用状态，以及执行健康检查。每个服务器卡片下会列出该服务器暴露的所有可用工具。
• 当模型触发工具调用时，消息流中会展示紧凑的 "tool" 块，包含调用参数、运行过程中的进度条，以及最终返回的结果或错误信息。工具执行结果会自动传回模型，用于生成后续回复。

单模型能力自定义覆盖：

• 在「设置」→「模型」页面中，你可以为每一个模型独立开关「Tool calling (functions)」工具调用和「Multimodal input」多模态输入能力。即使模型提供商返回的元数据中未声明该能力，此处的覆盖配置也会生效。

ML Intern 功能

ML Intern 是一项实验性功能，可在 Hugging Face Hub 上自主规划并运行机器学习相关工作：包括复现学术论文、微调并评估模型、构建数据集，以及将演示应用部署为 Spaces。它支持自动读取论文、模型和数据集资源，编写执行脚本，并在你为每个对话设置的计算预算内，将任务作为 https://huggingface.co/docs/huggingface_hub/guides/jobs 在沙箱环境中运行。

你可以访问 HuggingChat 的 https://huggingface.co/chat/?mode=ml-intern 链接体验该功能。

• ML Intern 快速入门：指导你完成账户与计费配置，创建第一条任务，以及严格控制消费额度。
• 在本地运行集成 ML Intern 的 Chat UI：指导你在自己部署的 Chat UI 中配置并运行 ML Intern，选择适配的模型，以及了解相关代码结构。

构建部署

生成应用的生产环境构建产物，请执行以下命令：

npm run build

构建完成后，你可以通过 npm run preview 预览生产版本的运行效果。

[!NOTE] 部署该应用时，你可能需要为目标环境安装对应的 SvelteKit https://kit.svelte.dev/docs/adapters。