ghcr.io/huggingface/chat-ui:sha-3441842

Chat UI

这是一款面向大语言模型的聊天界面，基于 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 的部署实例。

对于快速本地开发场景，可跳过本节配置。当 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 时，会在用户设置中添加数据共享开关，允许用户自主选择是否向模型创作者共享交互数据

模型配置

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

LLM 路由（可选）

Chat 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）。若选中路由下的所有模型均调用失败，请求会自动降级使用 LLM_ROUTER_FALLBACK_MODEL 指定的模型。
• Omni 别名可自定义：通过 PUBLIC_LLM_ROUTER_ALIAS_ID 设置别名 ID（默认值 omni），PUBLIC_LLM_ROUTER_DISPLAY_NAME 设置界面显示名称（默认值 Omni），还可配置可选的 PUBLIC_LLM_ROUTER_LOGO_URL 自定义图标。

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

• 基于请求特征（是否附带图片、是否启用 MCP 服务器等）在本地自动选择对应路由，无特征匹配时走默认路由
• 立即返回路由元数据（包含选中的路由与实际使用的模型信息）供界面展示
• 通过你配置的 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 数组：包含 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」标识；你也可以在设置中为每个模型手动强制启用该功能（详见下文）。

在 UI 中使用工具

• 从右上角菜单或聊天输入框的 + 菜单中打开「MCP Servers」页面，即可添加服务器、切换启用状态、运行健康检查。服务器卡片会列出所有可用工具。
• 当模型调用工具时，消息区域会展示紧凑的「tool」区块，包含调用参数、运行中的进度条，以及最终结果（或错误信息）。工具结果会同时返回给模型，供后续推理使用。

单模型独立覆盖配置

• 进入「设置」→「模型」页面，你可以为每个模型单独切换「工具调用（函数）」和「多模态输入」的开关。这些覆盖配置优先级高于提供商元数据声明的能力，即便提供商未标注该模型支持对应功能也可生效。

ML Intern

ML Intern 是一项实验性功能，可在 Hugging Face Hub 上规划并执行机器学习相关工作：复现论文、微调评估模型、构建数据集、将演示部署为 Space。它会读取论文、模型和数据集资源，自动编写脚本，并在你为每个对话设定的计算预算范围内，以 Hugging Face Job 和沙箱的形式运行这些脚本。

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

• ML Intern 入门：完成账号与账单配置，编写首个任务，并管控消费额度。
• 在本地 Chat UI 中运行 ML Intern：配置并在自有 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 配置的、兼容 OpenAI 规范的 API，且要求服务提供 /models 端点。面向特定提供商的旧版集成（传统 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 版本的部署实例。

[!TIP] 快速本地开发场景下可跳过本部分配置。当未设置 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="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 与收藏夹图标，当前可选值为 chatui 和 huggingchat。
• PUBLIC_APP_DATA_SHARING 可设置为 1，此时会在用户设置中新增一个开关，允许用户自主选择是否与模型创建者共享数据。

模型

系统会从 ${OPENAI_BASE_URL}/models 地址自动发现可用模型，你也可以通过 MODELS 环境变量（JSON5 格式）覆盖模型的元数据。旧版的特定提供商专属集成与 GGUF 自动发现功能已被移除。授权优先使用 OPENAI_API_KEY，HF_TOKEN 仅作为旧版别名保留兼容。

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 服务器、默认场景）在本地匹配对应路由。
• 立即返回路由元数据（包含实际使用的路由与模型信息），供 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 函数调用机制将工具执行结果反馈给大模型。你可以通过环境变量预配置可信 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= 指定支持工具调用的目标模型。
• 该目标模型必须兼容 OpenAI 工具/函数调用规范。Chat UI 会在自行声明支持该能力的模型旁显示“工具”标签；你也可以在设置中手动为任意模型强制开启该功能（详见下文）。

在 UI 中使用工具：

• 点击右上角菜单或聊天输入框旁的 + 菜单，打开“MCP Servers”面板，即可添加服务器、开关启用状态并执行健康检查。服务器卡片会列出该服务器提供的所有可用工具。
• 当模型调用工具时，对话消息区将展示紧凑的“工具”区块，包含调用参数、运行时进度条，以及最终结果（或错误信息）。工具执行结果会自动传回模型，用于后续生成回复。

单模型独立配置：

• 在「设置 → 模型」页面，你可以为每个模型单独切换「工具调用（函数）」和「多模态输入」的开关状态。这些手动配置的优先级高于模型提供商元数据的能力声明。

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] 如需部署该应用，你可能需要为目标环境安装对应的 https://kit.svelte.dev/docs/adapters。