Chatbot UI 教程：构建你的专属大语言模型对话界面

一、引言

随着 ChatGPT 和大语言模型（LLM）技术的发展，越来越多的开发者希望构建属于自己的聊天界面，结合自己的 API 或私有大模型，构建企业级、可定制的聊天应用。为了满足这种需求，开源社区中涌现出多个聊天界面框架，其中 Chatbot UI 是最受欢迎、最易用、功能最完善的项目之一。

本教程将系统介绍 Chatbot UI 的背景、理论基础、安装部署、功能特点、使用方式以及进阶自定义改造技巧，帮助你从零构建自己的 AI 对话界面。

二、什么是 Chatbot UI？

Chatbot UI 是一个开源的 Web 聊天界面项目，最初由 Mckay Wrigley 发布，旨在提供类似 ChatGPT 的前端交互体验，帮助开发者快速搭建自己的对话界面。

项目地址：https://github.com/mckaywrigley/chatbot-ui

2.1 核心特点

• ChatGPT 风格：界面风格和交互体验与 OpenAI 的 ChatGPT 极为相似。
• 支持自定义 API：可以接入你自己的后端，如本地大模型、OpenAI API、FastAPI、LangChain 等。
• 响应式设计：适配桌面和移动端。
• 多会话支持：支持多轮会话、多聊天窗口。
• 多主题切换：支持暗黑和明亮主题。
• 完全前后端分离：前端可以独立部署，适用于多种后端场景。

2.2 适用场景

• 企业内训 Chatbot
• 本地大模型界面（如 LLaMA、ChatGLM）
• SaaS 应用对话系统前端
• 个性化 AI 助手开发

三、架构与技术栈分析

Chatbot UI 是一个典型的现代 Web 应用，使用了以下技术栈：

• 前端框架：React + Next.js
• UI 框架：Tailwind CSS + Headless UI
• 状态管理：Zustand
• Markdown 渲染：Shiki（高亮代码块）、React Markdown
• 本地存储：IndexedDB（用于保存会话数据）

它本质上是一个纯前端项目，通过调用用户指定的后端 API 来完成问答交互，因此高度灵活，适合各种自定义部署需求。

四、安装与部署

4.1 克隆项目

git clone https://github.com/mckaywrigley/chatbot-ui.git
cd chatbot-ui

4.2 安装依赖

确保你已经安装了 Node.js（建议版本 >= 18）和 pnpm：

npm install -g pnpm
pnpm install

4.3 启动开发环境

pnpm dev

默认会在 http://localhost:3000 打开聊天界面。

五、配置 API Key

首次使用会提示你输入 OpenAI API Key，系统会将 key 存储在本地浏览器缓存中。

如果你使用的是自己的后端 API，可以进入 utils 目录，修改 chat.ts 文件，替换默认的调用逻辑：

const response = await fetch('/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ messages, key, prompt })
})

将其改为你自定义的后端 API 地址即可。

六、主要功能模块详解

6.1 多轮对话支持

Chatbot UI 使用 IndexedDB 保存所有对话记录，即便刷新页面也不会丢失数据。支持：

• 多个聊天窗口（支持重命名）
• 对话历史查看
• 对话复制 / 删除 / 继续

6.2 Markdown 与代码块支持

你可以在输出内容中使用 markdown，包括：

• 标题、列表、引用等
• Latex 数学公式
• 代码高亮（使用 Shiki）

示例：

以下是一个 Python 示例：
```python
def hello():
    print("Hello, world!")

### 6.3 Prompt 管理

内置提示词（Prompt）系统，可预定义常用角色设定、写作风格、任务目标等，提升聊天效果。

### 6.4 主题切换

点击左下角设置按钮可以切换亮/暗主题，满足不同视觉需求。

---

## 七、与本地大模型结合

很多用户希望使用本地大模型（如 ChatGLM、LLaMA、Qwen）提供后端服务，可结合如下方式使用：

### 7.1 启动本地服务（示例：FastAPI）

```python
# server.py
from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware
from transformers import AutoModelForCausalLM, AutoTokenizer

app = FastAPI()
app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])

@app.post("/chat")
async def chat(request: Request):
    data = await request.json()
    messages = data['messages']
    reply = "你是本地模型，接收到消息：" + messages[-1]['content']
    return {"message": reply}

启动本地 API：

uvicorn server:app --host 0.0.0.0 --port 8000

7.2 修改前端调用逻辑

修改 utils/chat.ts，将 API 地址改为本地地址：

fetch("http://localhost:8000/chat", ...)

八、高级定制与功能拓展

8.1 修改 Logo 与页面标题

在 app/layout.tsx 和 public/favicon.ico 中更换图标、修改标题信息。

8.2 增加角色设定功能

可在会话开始时加入系统提示（system prompt）来设定角色：

{"role": "system", "content": "你是一个诗人"}

可以在前端配置提示词模板，点击即可注入该设定。

8.3 添加文件上传功能

可以结合 React 组件和自定义 API 添加上传按钮，将文件内容发送给后端处理。

8.4 接入向量数据库，实现知识问答

Chatbot UI 仅是前端，如果结合 LangChain + FAISS 或 LlamaIndex + Chroma 实现检索增强（RAG）即可实现知识库问答：

1. 后端接收用户问题
2. 检索相关文档段落
3. 拼接上下文后发送给模型
4. 返回响应渲染

九、生产环境部署

9.1 构建静态文件

pnpm build
pnpm export

生成的静态文件位于 .next/out 目录。

9.2 部署方式

• Vercel：一键部署，支持自动构建
• Netlify / Cloudflare Pages：静态资源部署平台
• Nginx + Docker：企业内网部署

示例 Dockerfile

FROM node:18
WORKDIR /app
COPY . .
RUN npm install -g pnpm && pnpm install && pnpm build && pnpm export
RUN cp -r .next/out /dist

FROM nginx:alpine
COPY --from=0 /dist /usr/share/nginx/html

十、对比 Gradio 和 Streamlit

Chatbot UI 更适合需要高度定制和生产环境使用的场景，而 Gradio/Streamlit 更适合快速原型和教学展示。

十一、总结与建议

Chatbot UI 是一个极具潜力的开源项目，特别适合以下用户：

• 想搭建 ChatGPT 类应用的开发者
• 需要对前端 UI 深度定制的团队
• 企业内部私有模型的界面需求
• 高性能、轻量级聊天框架的需求者

建议搭配 FastAPI、LangChain、向量数据库等后端工具使用，实现更强大的 AI 应用。

十二、参考链接

• 官方仓库：https://github.com/mckaywrigley/chatbot-ui
• 中文改进版：https://github.com/zhayujie/chatgpt-web
• LangChain 项目：https://github.com/hwchase17/langchain
• 向量库 Chroma：https://www.trychroma.com/