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

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等）默认均可工作。

旧版本仍可在legacy分支获取。

快速开始

Chat UI仅支持OpenAI兼容的API。最快的运行方式是使用Hugging Face推理提供商路由（router）加上您的个人Hugging Face访问令牌。

步骤1 – 创建.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会回退到持久化到./db的嵌入式MongoDB。

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

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

构建

要创建应用的生产版本：

npm run build

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

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