返回专栏
· 21 分钟阅读

从零构建一个 AI 对话应用:从前端交互到后端模型服务的完整实践


一、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 一次对话请求的完整链路

用户发送一条消息后,系统需要完成多个步骤:

  1. 前端收集用户输入。
  2. 后端验证身份和请求参数。
  3. 获取当前会话及历史消息。
  4. 构建模型所需的上下文。
  5. 调用大模型 API。
  6. 接收模型响应。
  7. 将响应持久化。
  8. 将结果返回前端。
  9. 前端更新对话界面。
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 用户名
email 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 交互的主要入口。

一个基础对话页面通常包括四个区域:

  1. 左侧会话列表。
  2. 顶部会话标题和模型信息。
  3. 中间消息展示区。
  4. 底部消息输入区。

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);
      }
    }
  }
}