一、AI 对话应用的整体架构
一个完整的 AI 对话应用,不只是一个输入框加上大模型 API。它实际上是一个包含用户交互、会话管理、模型调用、上下文组织和安全控制的应用系统。
1.1 核心组成
典型 AI 对话应用可以拆分为以下模块:
| 模块 | 核心职责 |
|---|---|
| 前端交互层 | 消息展示、输入框、会话列表、流式渲染 |
| 后端 API 层 | 接收请求、身份认证、参数校验、业务编排 |
| 会话管理层 | 创建会话、保存消息、维护上下文 |
| 模型适配层 | 对接不同大模型服务,统一请求与响应 |
| 模型服务层 | 调用 GPT、Claude、Gemini、Qwen、DeepSeek 等模型 |
| 数据存储层 | 保存用户、会话、消息和配置 |
| 安全治理层 | 权限校验、内容安全、限流、审计 |
| 可观测性层 | 记录请求、Token、延迟、错误和成本 |
1.2 系统架构
flowchart TB
A["用户"] --> B["前端应用"]
B --> C["后端 API Gateway"]
C --> D["身份认证与权限校验"]
D --> E["对话业务服务"]
E --> F["会话管理"]
E --> G["上下文构建"]
E --> H["模型适配层"]
H --> I["大模型 API"]
F --> J["数据库"]
E --> K["缓存"]
H --> L["日志与监控"]
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#EAF3EC,stroke:#83A995,color:#315D49
style C fill:#EAF3EC,stroke:#83A995,color:#315D49
style D fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style E fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style F fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style G fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style H fill:#EAF3EC,stroke:#83A995,color:#315D49
style I fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style J fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style K fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style L fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
1.3 一次对话请求的完整链路
用户发送一条消息后,系统需要完成多个步骤:
- 前端收集用户输入。
- 后端验证身份和请求参数。
- 获取当前会话及历史消息。
- 构建模型所需的上下文。
- 调用大模型 API。
- 接收模型响应。
- 将响应持久化。
- 将结果返回前端。
- 前端更新对话界面。
sequenceDiagram
autonumber
participant U as 用户
participant F as 前端
participant B as 后端
participant D as 数据库
participant M as 大模型
U->>F: 输入问题
F->>B: 发送对话请求
B->>B: 身份认证与参数校验
B->>D: 查询会话与历史消息
D-->>B: 返回历史消息
B->>B: 构建上下文
B->>M: 发送模型请求
M-->>B: 返回模型响应
B->>D: 保存用户消息与模型回复
B-->>F: 返回响应
F-->>U: 展示回答
实际生产系统通常会采用流式响应,因此模型生成和前端展示不一定等到全部内容生成完毕后才开始。
二、技术选型与项目结构
从零构建应用,首先需要确定技术栈。
2.1 推荐技术栈
| 技术层 | 可选方案 | 主要职责 |
|---|---|---|
| 前端 | React、Vue、Next.js | 对话界面与交互 |
| 后端 | Node.js、Python、Java、Go | API 与业务逻辑 |
| 模型 SDK | 官方 SDK、HTTP Client | 调用模型服务 |
| 数据库 | PostgreSQL、MySQL | 持久化用户和消息 |
| 缓存 | Redis | 会话缓存、限流、临时状态 |
| 实时通信 | SSE、WebSocket | 流式响应 |
| 部署 | Docker、Kubernetes | 应用运行与扩缩容 |
| 监控 | OpenTelemetry、Prometheus | 指标、链路与日志 |
对于第一个版本,建议使用:
- React:构建对话界面。
- Node.js:实现后端 API。
- PostgreSQL:保存用户、会话和消息。
- Redis:后续用于缓存和限流。
- 大模型 API:提供模型推理能力。
不需要一开始就引入微服务、消息队列和复杂的 Agent 框架。先构建清晰的单体应用,再根据业务规模拆分。
2.2 项目目录结构
一个较为清晰的项目可以组织为:
ai-chat-app/
├── frontend/
│ ├── src/
│ │ ├── components/
│ │ │ ├── ChatWindow.tsx
│ │ │ ├── MessageList.tsx
│ │ │ ├── MessageItem.tsx
│ │ │ ├── ChatInput.tsx
│ │ │ └── ConversationList.tsx
│ │ ├── hooks/
│ │ │ └── useChat.ts
│ │ ├── services/
│ │ │ └── chatApi.ts
│ │ ├── types/
│ │ │ └── chat.ts
│ │ └── App.tsx
│ └── package.json
│
├── backend/
│ ├── src/
│ │ ├── routes/
│ │ │ └── chat.ts
│ │ ├── services/
│ │ │ ├── chatService.ts
│ │ │ ├── modelService.ts
│ │ │ └── contextService.ts
│ │ ├── adapters/
│ │ │ └── openaiAdapter.ts
│ │ ├── repositories/
│ │ │ ├── conversationRepository.ts
│ │ │ └── messageRepository.ts
│ │ ├── middleware/
│ │ │ ├── auth.ts
│ │ │ └── rateLimit.ts
│ │ ├── config/
│ │ │ └── model.ts
│ │ └── app.ts
│ └── package.json
│
├── database/
│ └── migrations/
│
├── .env
└── README.md
这里有几个重要的设计原则:
- Routes 负责 HTTP 请求,不直接承载复杂业务逻辑。
- Services 负责对话编排和模型调用。
- Adapters 负责隔离不同模型供应商的协议差异。
- Repositories 负责数据库访问。
- Middleware 负责认证、限流等横切逻辑。
这种分层可以避免业务代码与模型供应商、数据库实现高度耦合。
三、设计对话数据模型
AI 对话应用首先需要解决一个基础问题:如何保存用户、会话和消息?
不能简单地把整个对话保存为一个字符串。随着对话增长,需要支持分页查询、历史恢复、消息状态、模型追踪和数据分析。
3.1 核心数据实体
建议至少设计三个核心实体:
User:用户
| 字段 | 类型 | 说明 |
|---|---|---|
| id | UUID | 用户唯一标识 |
| username | VARCHAR | 用户名 |
| VARCHAR | 邮箱 | |
| created_at | TIMESTAMP | 创建时间 |
Conversation:会话
| 字段 | 类型 | 说明 |
|---|---|---|
| id | UUID | 会话唯一标识 |
| user_id | UUID | 所属用户 |
| title | VARCHAR | 会话标题 |
| model | VARCHAR | 当前使用的模型 |
| system_prompt | TEXT | 会话级系统指令,可选 |
| created_at | TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | 更新时间 |
Message:消息
| 字段 | 类型 | 说明 |
|---|---|---|
| id | UUID | 消息唯一标识 |
| conversation_id | UUID | 所属会话 |
| role | VARCHAR | 消息角色 |
| content | TEXT / JSONB | 消息内容 |
| status | VARCHAR | 消息状态 |
| input_tokens | INTEGER | 输入 Token 数 |
| output_tokens | INTEGER | 输出 Token 数 |
| model | VARCHAR | 实际使用的模型 |
| created_at | TIMESTAMP | 创建时间 |
3.2 数据库关系
erDiagram
USER ||--o{ CONVERSATION : owns
CONVERSATION ||--o{ MESSAGE : contains
USER {
uuid id PK
string username
string email
timestamp created_at
}
CONVERSATION {
uuid id PK
uuid user_id FK
string title
string model
timestamp created_at
timestamp updated_at
}
MESSAGE {
uuid id PK
uuid conversation_id FK
string role
jsonb content
string status
integer input_tokens
integer output_tokens
timestamp created_at
}
3.3 为什么 Message 的 Content 可以使用 JSONB?
如果应用只支持纯文本,使用 TEXT 就可以满足需求。
但如果后续支持多模态消息,消息内容可能包含:
- 文本。
- 图片引用。
- 音频内容。
- 文件引用。
- 工具调用。
- 工具执行结果。
因此可以采用结构化 JSON 存储消息内容。
例如:
{
"type": "text",
"text": "请解释一下 Transformer 的工作原理"
}
包含图片的消息可以抽象为:
{
"parts": [
{
"type": "text",
"text": "请分析这张图片"
},
{
"type": "image",
"url": "https://example.com/image.png"
}
]
}
需要注意,数据库中的消息结构不一定等同于模型供应商的请求结构。应用内部应该定义自己的消息模型,再由模型适配层转换成供应商协议。
3.4 角色设计
最基本的对话角色包括:
| Role | 含义 |
|---|---|
| system | 系统级指令 |
| user | 用户消息 |
| assistant | 模型回复 |
| tool | 工具执行结果 |
不同模型 API 对角色和消息结构的支持可能不同,不能假设所有服务商都完全遵循同一种协议。
对于工具调用,还需要保存工具调用 ID、工具名称、参数、执行状态和结果,保证一次工具调用的完整生命周期可以被追踪。
四、接入大模型 API
模型 API 是 AI 对话应用的核心能力来源。
应用自身负责用户交互和业务逻辑,大模型负责根据输入上下文执行推理并生成响应。
4.1 配置模型服务
首先需要准备:
- API Base URL。
- API Key。
- Model ID。
- 请求超时时间。
- 最大输出 Token 数。
- Temperature 等采样参数。
配置文件可以通过环境变量管理:
MODEL_API_KEY=your_api_key
MODEL_BASE_URL=https://api.example.com/v1
MODEL_NAME=your-model-name
生产环境不要将真实 API Key 提交到 Git,也不要写入前端代码。
4.2 后端调用模型
以下使用 JavaScript 和 OpenAI SDK 风格接口演示。实际使用时需要安装对应 SDK,并根据所选服务商的协议调整配置和参数。
npm install openai
模型服务封装:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.MODEL_API_KEY,
baseURL: process.env.MODEL_BASE_URL,
});
export async function generateAnswer(
messages: Array<{
role: "system" | "user" | "assistant";
content: string;
}>
) {
const response = await client.chat.completions.create({
model: process.env.MODEL_NAME!,
messages,
temperature: 0.7,
max_tokens: 2048,
});
return {
content: response.choices[0]?.message?.content ?? "",
usage: response.usage,
model: response.model,
};
}
这里使用的是 Chat Completions 风格接口示例,并不意味着所有模型供应商都支持完全相同的字段和参数。
4.3 为什么要封装 Model Adapter?
如果业务代码直接调用某个模型供应商的 SDK,后续切换模型时会出现大量修改。
例如:
ChatService
├── 直接调用 OpenAI SDK
├── 直接处理 OpenAI 响应
└── 直接依赖 OpenAI 流式事件
这种设计会让业务层与具体供应商绑定。
更合理的方式是定义统一接口:
export interface ModelAdapter {
generate(
messages: ChatMessage[],
options?: ModelOptions
): Promise<ModelResponse>;
stream(
messages: ChatMessage[],
options?: ModelOptions
): AsyncIterable<ModelStreamEvent>;
}
然后分别实现不同供应商的适配器:
ModelAdapter
├── OpenAIAdapter
├── AnthropicAdapter
├── GeminiAdapter
├── QwenAdapter
└── DeepSeekAdapter
业务层只依赖统一接口,不直接依赖某家供应商的 SDK。
需要特别注意:统一接口不应该抹平所有能力差异。某个模型不支持的参数、工具调用或多模态能力,应当显式声明、拒绝或降级,而不是静默忽略。
五、实现核心对话 API
模型接入完成后,需要为前端提供稳定的业务接口。
5.1 API 设计
建议先实现以下接口:
| HTTP 方法 | API | 功能 |
|---|---|---|
| POST | /api/conversations | 创建会话 |
| GET | /api/conversations | 查询会话列表 |
| GET | /api/conversations/:id | 获取会话详情 |
| PATCH | /api/conversations/:id | 修改会话信息 |
| DELETE | /api/conversations/:id | 删除会话 |
| GET | /api/conversations/:id/messages | 获取消息历史 |
| POST | /api/chat | 发送消息 |
| POST | /api/chat/stream | 流式发送消息 |
这些接口是应用内部的业务 API,不需要直接暴露模型供应商的 API。
5.2 对话请求结构
前端可以发送:
{
"conversation_id": "conv_123",
"message": "什么是 Transformer?",
"model": "your-model-name"
}
后端需要验证:
- 当前用户是否已登录。
- 当前会话是否属于当前用户。
- 消息内容是否为空。
- 消息长度是否超过限制。
- 模型是否在允许使用的范围内。
- 当前用户是否还有可用额度。
不能直接信任前端提交的 user_id、模型名称或权限信息。用户身份应从经过验证的认证凭证中获取。
5.3 对话服务实现
对话服务负责串联会话、消息和模型:
export async function chat(
userId: string,
conversationId: string,
userContent: string
) {
const conversation =
await conversationRepository.findById(conversationId);
if (!conversation || conversation.userId !== userId) {
throw new Error("Conversation not found");
}
const history =
await messageRepository.findRecentMessages(conversationId);
const userMessage =
await messageRepository.create({
conversationId,
role: "user",
content: userContent,
status: "completed",
});
const context = await contextService.build({
conversation,
history,
userContent,
});
const result = await modelService.generate({
model: conversation.model,
messages: context,
});
const assistantMessage =
await messageRepository.create({
conversationId,
role: "assistant",
content: result.content,
status: "completed",
inputTokens: result.usage?.prompt_tokens,
outputTokens: result.usage?.completion_tokens,
});
return {
userMessage,
assistantMessage,
usage: result.usage,
};
}
这是用于说明职责边界的简化示例。生产实现还需要处理模型调用失败、超时、并发消息、事务一致性、请求幂等和消息状态恢复。
尤其要注意:用户消息已经保存,但模型调用失败时,不能让会话处于无法解释的状态。可以将消息状态设计为:
- pending:等待处理。
- streaming:正在生成。
- completed:生成完成。
- failed:生成失败。
- cancelled:用户主动取消。
六、实现前端对话界面
前端是用户与 AI 交互的主要入口。
一个基础对话页面通常包括四个区域:
- 左侧会话列表。
- 顶部会话标题和模型信息。
- 中间消息展示区。
- 底部消息输入区。
6.1 页面组件设计
ChatPage
├── Sidebar
│ ├── NewConversationButton
│ └── ConversationList
│ └── ConversationItem
│
├── ChatMain
│ ├── ChatHeader
│ ├── MessageList
│ │ └── MessageItem
│ └── ChatInput
│ ├── TextArea
│ ├── AttachmentButton
│ └── SendButton
│
└── ModelSelector
组件之间应尽量通过明确的数据结构和回调通信,避免将所有对话状态都放在单个页面组件中。
6.2 消息数据结构
前端可以定义:
export interface ChatMessage {
id: string;
conversationId: string;
role: "user" | "assistant" | "tool";
content: string;
status: "pending" | "streaming" | "completed" | "failed";
createdAt: string;
}
消息列表需要支持:
- 用户消息和 AI 消息使用不同样式。
- Markdown 渲染。
- 代码高亮。
- 复制消息。
- 消息重新生成。
- 消息反馈。
- 加载和错误状态。
- 长消息滚动与性能优化。
对于 Markdown 渲染,必须对不可信内容进行安全处理,避免将模型输出直接作为未经净化的 HTML 注入页面。
6.3 对话状态管理
对话应用不仅需要保存消息数组,还需要管理请求状态。
典型状态包括:
interface ChatState {
conversationId: string | null;
messages: ChatMessage[];
input: string;
isLoading: boolean;
isStreaming: boolean;
error: string | null;
}
其中:
- isLoading:请求正在准备或等待响应。
- isStreaming:模型正在持续输出内容。
- error:当前请求发生的错误。
这两个状态不应简单合并为一个布尔值。应用可能需要区分等待首个 Token、正在接收内容、结束和失败等阶段。
七、实现 Streaming 流式响应
如果每次都等到模型生成完整回答后再返回,用户需要等待较长时间。
Streaming 可以让模型生成的内容逐步传输到前端,明显改善交互体验。
7.1 流式响应的基本原理
以 SSE 为例:
- 后端向模型服务发起流式请求。
- 模型服务持续产生事件或内容片段。
- 后端读取上游数据。
- 后端将内容转换成应用内部事件。
- 前端持续接收事件并更新消息内容。
flowchart TB
A["用户发送消息"] --> B["后端建立模型流式请求"]
B --> C["模型生成 Token"]
C --> D["模型返回流式数据"]
D --> E["后端解析数据块"]
E --> F["转换为应用事件"]
F --> G["SSE 推送前端"]
G --> H["前端追加消息内容"]
H --> I{"是否结束"}
I -->|"否"| C
I -->|"是"| J["结束响应并保存消息"]
style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
style B fill:#EAF3EC,stroke:#83A995,color:#315D49
style C fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style D fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style E fill:#EAF3EC,stroke:#83A995,color:#315D49
style F fill:#EAF3EC,stroke:#83A995,color:#315D49
style G fill:#EAF3EC,stroke:#83A995,color:#315D49
style H fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
style I fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
style J fill:#DCEFE5,stroke:#4F8B70,color:#24563F
7.2 后端流式接口
下面以 Node.js 的 Web API ReadableStream 和 SSE 为例,演示应用层如何向浏览器发送事件。modelService.stream() 是前面统一模型适配层的抽象方法。
export async function streamChat(
userId: string,
conversationId: string,
content: string
) {
await conversationService.assertOwnedBy(
conversationId,
userId
);
const context = await contextService.buildForNewMessage(
conversationId,
content
);
return new ReadableStream({
async start(controller) {
const encoder = new TextEncoder();
const send = (event: string, data: unknown) => {
controller.enqueue(
encoder.encode(
`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
)
);
};
try {
send("start", {
conversationId,
});
for await (const chunk of modelService.stream({
messages: context,
})) {
if (chunk.type === "text_delta") {
send("delta", {
content: chunk.text,
});
}
}
send("done", {
conversationId,
});
} catch (error) {
send("error", {
message: "Model generation failed",
});
} finally {
controller.close();
}
},
});
}
这里省略了消息持久化、取消信号、连接断开检测和资源清理。生产实现需要将这些逻辑纳入完整的请求生命周期。
7.3 前端接收 SSE
浏览器可以使用 fetch 读取流式响应:
async function sendStreamMessage(
conversationId: string,
message: string,
onDelta: (text: string) => void
) {
const response = await fetch("/api/chat/stream", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
conversationId,
message,
}),
});
if (!response.ok || !response.body) {
throw new Error("Stream request failed");
}
const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (true) {
const { value, done } = await reader.read();
if (done) break;
buffer += decoder.decode(value, {
stream: true,
});
const events = buffer.split("\n\n");
buffer = events.pop() ?? "";
for (const event of events) {
const dataLine = event
.split("\n")
.find((line) => line.startsWith("data: "));
if (!dataLine) continue;
const data = JSON.parse(
dataLine.slice(6)
);
if (data.content) {
onDelta(data.content);
}
}
}
}