基于SpringBoot与多模型API的AI角色扮演系统实战开发

前言

本文记录了我完成的一个AI应用项目全过程。客户希望构建一个类似“豆包智能体”的角色扮演对话系统，要求使用Java技术栈，支持通义千问和DeepSeek等多种大模型API切换，并实现纯文本形式的角色对话功能。

项目聚焦于后端API开发，不包含前端界面，通过Postman等工具进行接口测试验证。文章将从需求分析、架构设计、核心功能实现到问题解决进行全面梳理，旨在为从事AI应用开发的开发者提供实践参考。

项目技术栈

SpringBoot 3.2.0

MySQL 8.0

通义千问API

DeepSeek API

WebSocket

一、项目背景与需求分析

1.1 项目来源

该项目来源于一次外包合作。客户提供了初步的需求文档（目前已过期），核心目标是打造一个具备角色设定能力的AI对话系统，功能上对标当前主流的AI智能体平台。

1.2 核心需求

客户明确提出以下关键要求：

核心功能清单如下：

• 角色管理：预设“苏格拉底”与“魔法学徒”两个角色
• 会话管理：支持创建独立会话并选择对应AI模型
• 消息交互：提供REST API和WebSocket两种通信模式
• 多种对话风格：支持沉浸式、学术式、苏格拉底问答式等不同语境
• 模型动态切换：可在运行时根据需要更换底层大模型

1.3 客户提供的资源

客户在项目初期提供了必要的基础资料：

# 通义千问API Key
# DeepSeek API Key

此外还包括：

• 预设角色数据（苏格拉底、魔法学徒）
• 数据库表结构设计要求
• 角色人设定义文件（YAML格式）

二、系统架构设计

2.1 技术选型

结合项目需求与长期维护考虑，最终确定以下技术方案：

2.2 项目结构

整体采用标准分层架构，目录组织清晰：

ai-roleplay/
├── src/main/java/com/example/airoleplay/
│   ├── controller/          
│   │   ├── CharacterController.java      # 角色管理接口
│   │   ├── SessionController.java        # 会话管理接口
│   │   └── HealthController.java         # 健康检查接口
│   ├── service/             
│   │   ├── CharacterService.java         # 角色业务逻辑
│   │   ├── SessionService.java           # 会话业务逻辑
│   │   ├── LlmService.java               # LLM服务接口
│   │   ├── TongyiLlmService.java         # 通义千问实现
│   │   ├── DeepSeekLlmService.java       # DeepSeek实现
│   │   └── LlmServiceFactory.java        # 工厂模式选择模型
│   ├── entity/              
│   │   ├── CharacterEntity.java          # 角色实体
│   │   ├── SessionEntity.java            # 会话实体
│   │   └── MessageEntity.java            # 消息实体
│   ├── repository/           
│   │   ├── CharacterRepository.java     # 角色数据访问
│   │   ├── SessionRepository.java       # 会话数据访问
│   │   └── MessageRepository.java       # 消息数据访问
│   ├── config/                
│   │   └── WebSocketConfig.java          # WebSocket配置
│   ├── dto/                   
│   │   ├── request/                      # 请求DTO
│   │   └── response/                     # 响应DTO
│   └── util/                  
│       └── PromptUtil.java               # 提示词工具类

2.3 系统架构图

系统采用模块化设计，各组件协同工作，形成完整的服务闭环。

三、核心功能实现

3.1 数据库设计

核心表结构

主要包括三个核心数据表：

• character：存储角色基本信息及人设描述
• session：记录用户会话状态及所选模型
• message：保存每轮对话的消息内容

关键设计点

• 使用JSON字段存储角色YAML人设信息，便于扩展
• 会话表中包含model_type字段，标识当前使用的AI模型
• 消息表按会话ID分区，提高查询效率

预设数据

初始化包含两个角色：

• 苏格拉底：擅长哲学思辨与引导式提问
• 魔法学徒：具有奇幻世界观下的互动设定

3.2 多模型适配器模式

设计思路

为了实现多个大模型的灵活切换，采用适配器+工厂模式的设计思想，统一对外暴露相同的LLM调用接口。

LLM服务接口定义

定义统一的LlmService接口，包含generateResponse方法，所有具体模型实现该接口。

工厂类实现模型选择

通过LlmServiceFactory根据传入的模型类型返回对应的实现类实例，实现运行时动态绑定。

设计优势

• 解耦模型调用与业务逻辑
• 易于后续扩展新模型（如加入文心一言、星火等）
• 提升代码可维护性与可测试性

3.3 通义千问API集成

核心实现代码

使用WebClient发起异步HTTP请求，封装Authorization头与请求体格式，处理流式响应数据。

踩坑记录

• 初始未正确设置Accept头导致返回格式异常
• 签名算法需严格按照官方文档实现，注意参数排序
• 流式响应需启用exchange()而非retrieve()以获取完整控制权

3.4 DeepSeek API集成

核心实现代码

同样基于WebClient实现，但其API更简洁，无需复杂签名，直接携带Bearer Token即可调用。

API对比

3.5 角色扮演Prompt工程

Prompt构建策略

采用“角色设定 + 行为规范 + 输出约束”三层结构构建提示词模板：

• 第一层：明确身份与背景（你是谁）
• 第二层：规定对话风格与行为边界（你怎么说）
• 第三层：限制输出格式与禁止内容（你不能做什么）

实际效果示例

以苏格拉底为例，当用户提出观点时，系统会自动以反问形式引导思考，而非直接给出答案，有效模拟其教学风格。

3.6 WebSocket实时通信

WebSocket处理器实现

通过@ServerEndpoint注解定义端点，管理会话连接池，接收客户端消息后转发至对应LLM服务并推送流式结果。

连接方式

客户端通过ws://host:port/ws/chat/{sessionId}建立连接，服务端基于Session ID维护上下文。

技术要点

• 使用ConcurrentHashMap存储活跃会话
• 确保每个会话线程安全
• 及时关闭异常断开的连接，防止内存泄漏

四、完整测试流程

4.1 环境准备

配置本地application-dev.yml，填入各模型API Key，启动MySQL容器，确保服务正常运行。

4.2 REST API测试（使用Postman）

测试1：获取角色列表
GET /api/characters
验证能否正确返回预设角色信息。

测试2：创建会话（通义千问）
POST /api/sessions
Body: {"characterId": 1, "model": "qwen"}
验证是否生成有效会话ID并持久化。

测试3：发送消息
POST /api/messages
包含会话ID与用户输入，验证AI能否返回符合角色设定的回答。

测试4：获取历史消息
GET /api/messages?sessionId=xxx
验证消息记录是否完整保存。

4.3 WebSocket测试

使用WebSocket客户端工具连接指定端点，发送消息后观察是否能接收到逐字流式返回的结果，验证实时性与稳定性。

五、开发中遇到的问题与解决

5.1 问题1：AI回复中自报家门

现象：模型在回答开头总是自称“我是通义千问”等标识语。
解决方案：在Prompt中增加明确指令：“请完全代入角色，禁止提及自己是AI或模型名称”，成功抑制此类输出。

5.2 问题2：WebClient依赖缺失

现象：编译通过但运行时报错找不到WebClient类。
原因：未引入spring-boot-starter-webflux依赖。
解决：在pom.xml中添加对应依赖后恢复正常。

5.3 问题3：UUID生成策略问题

现象：JPA保存实体时UUID为空。
原因：未正确配置@GeneratedValue(strategy = GenerationType.UUID)或缺少默认值设置。
解决：改为在Java层面使用UUID.randomUUID().toString()手动赋值，确保唯一性。

六、项目亮点总结

6.1 技术亮点

• 采用适配器+工厂模式实现多模型无缝切换
• 结合REST与WebSocket双协议支持多样化交互场景
• Prompt工程精细化设计，显著提升角色一致性
• 全响应式编程模型，提升高并发下系统吞吐能力

6.2 技术收获

• 深入掌握了WebClient在流式场景下的高级用法
• 积累了多模型API集成的实战经验
• 提升了对WebSocket长连接管理的理解
• 强化了Prompt工程对输出质量的影响认知

七、项目交付

7.1 交付内容

• 完整的SpringBoot后端源码
• 数据库初始化脚本
• Postman测试集合导出文件
• API接口文档（Swagger）

7.2 后续优化方向

• 增加缓存机制减少重复计算
• 引入Rate Limiting防止API滥用
• 支持更多大模型接入（如GLM、Baichuan等）
• 增强日志追踪与监控能力

八、相关资源

（已去除所有引流性质内容）

结语

本次项目成功实现了基于Java生态的AI角色扮演系统，验证了SpringBoot在现代AI应用开发中的可行性与强大能力。整个过程不仅锻炼了技术整合能力，也加深了对大模型服务调用细节的理解。希望这份详实的开发记录能为后来者提供有价值的借鉴。

2.3 系统架构图

三、核心功能实现

3.1 数据库设计

作为整个系统的基础，数据库设计严格依据客户需求文档进行，确保了数据结构的完整性与可扩展性。

核心表结构

关键设计点

UUID主键：采用UUID作为主键，提升分布式部署下的扩展能力。

id VARCHAR(36) PRIMARY KEY DEFAULT (UUID())

对话模式枚举：通过mode字段支持三种交互方式：

mode ENUM('immersive', 'academic', 'socratic') DEFAULT 'immersive'

sessions

• mode

  ：沉浸式 — AI完全代入设定角色进行互动

• immersive

  ：学术式 — 以严谨的学术风格展开讨论

• academic

  ：苏格拉底式 — 通过连续提问引导用户自主思考

socratic

模型选择字段：model_name用于记录当前会话所使用的AI模型。

model_name VARCHAR(50) DEFAULT 'tongyi'

model_name

预设数据初始化：在数据库初始脚本中预先插入两个角色实例，便于快速体验：

INSERT INTO characters (id, name, locale, tags, brief, popularity) VALUES
('char-socrates', '苏格拉底', 'zh-CN', '["哲学家", "古希腊", "智者"]',
'古希腊哲学家，以问答法著称', 100),
('char-wizard', '魔法学徒', 'zh-CN', '["魔法", "学生", "冒险"]',
'霍格沃茨的年轻魔法学徒', 85);
    

3.2 多模型适配器模式

该模块是项目的核心技术亮点。为实现多种大语言模型之间的灵活切换与统一调用，采用了策略模式 + 工厂模式相结合的设计方案。

设计思路

LLM服务接口定义：所有模型服务均需实现统一接口，保证调用一致性。

public interface LlmService {
    String generateResponse(String text);
    String generateResponse(String text, Session session);
    void streamChat(String text, String sessionId, WebSocketSession webSocketSession);
}
    

工厂类实现动态模型选取：通过Spring依赖注入管理不同模型服务实例，并根据配置或参数返回对应实现。

@Component
@RequiredArgsConstructor
public class LlmServiceFactory {
    private final TongyiLlmService tongyiLlmService;
    private final DeepSeekLlmService deepSeekLlmService;
}
    

public LlmService getService(String modelName) {
    return switch (modelName.toLowerCase()) {
        case "deepseek" -> deepSeekLlmService;
        case "tongyi" -> tongyiLlmService;
        default -> tongyiLlmService;
    };
}

设计优势说明

该实现方式具备多个关键优势，能够有效提升系统的可维护性与扩展能力：

• 遵循开闭原则：当需要接入新的模型时，仅需新增对应的服务实现类并实现统一接口，无需对已有逻辑进行任何修改，保证了代码的稳定性。
• 支持运行时动态切换：系统可根据会话级别的配置信息，在不重启应用的前提下灵活选择使用的语言模型服务。
• 高度解耦：各模型的具体实现相互独立，彼此之间无直接依赖，降低了模块间的耦合度，提升了代码的可读性和可维护性。
• 便于单元测试：由于服务通过接口注入，可以在测试中轻松使用mock对象替换真实服务，从而实现高效、精准的自动化测试。

LlmService

3.3 通义千问 API 集成方案

通义千问基于阿里云提供的 DashScope 大模型服务平台进行集成。该平台通过标准化接口提供多种AI能力，其中文本生成服务是本项目重点使用的功能。

核心调用逻辑

private String callTongyiApi(String text) throws Exception {
    Map<String, Object> request = new HashMap<>();
    request.put("model", "qwen-turbo");

    Map<String, Object> input = new HashMap<>();
    input.put("messages", List.of(Map.of("role", "user", "content", text)));
    request.put("input", input);

    WebClient client = WebClient.builder()
        .defaultHeader("Authorization", "Bearer " + apiKey)
        .defaultHeader("Content-Type", "application/json")
        .build();

    String response = client.post()
        .uri("https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation")
        .bodyValue(request)
        .retrieve()
        .bodyToMono(String.class)
        .block();

    JsonNode node = objectMapper.readTree(response);
    return node.path("output").path("choices").get(0)
               .path("message").path("content").asText();
}

常见问题及解决方案

坑点一：响应格式存在新旧两个版本

在实际对接过程中发现，通义千问返回的数据结构有两种形式：

• 旧版格式：

output.text

• 新版格式：

output.choices[0].message.content

因此，解析响应时必须兼容处理两种结构，避免因格式变更导致解析失败。

坑点二：错误标识字段非常规

与大多数API不同，通义千问在请求失败时不通过常见的 HTTP 状态码或顶层 error 字段判断，而是通过检查特定字段：

code

而非通常使用的：

error

对应的错误处理代码应如下编写：

// 错误检测逻辑
if (node.has("code")) {
    throw new RuntimeException("API调用失败: " + node.path("message").asText());
}

3.4 DeepSeek API 集成实现

DeepSeek 提供了与 OpenAI 接口高度兼容的标准 RESTful API，这使得其集成过程更为简便，也是选型中的重要考量因素之一。

主要调用代码

private String callDeepSeekApi(String text) throws Exception {
    Map<String, Object> request = new HashMap<>();
    request.put("model", "deepseek-chat");
    request.put("messages", List.of(Map.of("role", "user", "content", text)));
    request.put("stream", false);

    WebClient client = WebClient.builder()
        .defaultHeader("Authorization", "Bearer " + apiKey)
        .defaultHeader("Content-Type", "application/json")
        .build();

    String response = client.post()
        .uri("https://api.deepseek.com/chat/completions")
        .bodyValue(request)
        .retrieve()
        .bodyToMono(String.class)
        .block();

得益于其标准协议的支持，开发者可以复用大量已有的工具链和封装库，显著降低开发与调试成本。

API 对比分析

input.messages

messages

output.choices

choices

incremental_output

stream

角色扮演中的 Prompt 工程设计

作为项目的核心技术之一，角色扮演功能的实现依赖于精心设计的动态 Prompt 构建机制。该机制确保 AI 不仅是回答问题，而是真正“化身”为特定角色进行交互。

Prompt 动态构建策略

private String buildRolePlayPrompt(String userText, Session session) {
    StringBuilder prompt = new StringBuilder();

    // 1. 注入角色身份信息
    characterService.getCharacterById(session.getCharacterId())
        .ifPresent(character -> {
            prompt.append("你现在要扮演角色：").append(character.getName()).append("\n");
            prompt.append("角色描述：").append(character.getBrief()).append("\n");
        });

    // 2. 根据当前对话模式调整表达风格
    switch (session.getMode()) {
        case immersive:
            prompt.append("请完全沉浸在这个角色中，用第一人称回答，保持角色的性格特点和说话方式。\n");
            break;
        case academic:
            prompt.append("请以学术讨论的方式，结合角色的知识背景来回答问题。\n");
            break;
        case socratic:
            prompt.append("请用苏格拉底式的问答方法，通过提问来引导思考。\n");
            break;
    }

    prompt.append("\n用户问题：").append(userText);
    return prompt.toString();
}

实际应用效果示例

• 场景1： 苏格拉底 + socratic 模式

  用户：什么是正义？
  AI：让我们先澄清概念。你认为正义是什么呢？是对所有人一视同仁，还是给予每个人应得的？

• 场景2： 魔法学徒 + immersive 模式

  用户：请介绍一下魔法学院的生活
  AI：这听起来像是一场冒险！在霍格沃茨，每天早上我都要赶去上魔药课，格兰芬多的同学们总是...

• 场景3： 苏格拉底 + academic 模式

  用户：什么是真理？
  AI：从哲学角度来看，真理是符合客观实际的认识。在古希腊哲学传统中，我们认为...

基于 WebSocket 的实时通信实现

为支持流式对话体验，系统集成了 WebSocket 技术，使用户能够实时接收 AI 生成的内容，提升交互流畅度。

WebSocket 处理器逻辑

@Override
public void handleTextMessage(WebSocketSession session, TextMessage message) {
    String sessionId = getSessionIdFromUri(session.getUri());
    ChatMessage chatMessage = objectMapper.readValue(message.getPayload(), ChatMessage.class);

    // 获取会话配置以确定使用的语言模型
    Session chatSession = sessionService.getSessionById(sessionId).get();
    LlmService llmService = llmServiceFactory.getService(chatSession.getModelName());

    // 启动独立线程处理大模型请求，防止阻塞主通信线程
    new Thread(() -> llmService.streamChat(chatMessage.getText(), sessionId, session)).start();
}

连接与消息规范

WebSocket 连接地址：
ws://localhost:8080/ws/chat?sessionId=<会话ID>

发送消息格式（JSON）：
{ "text": "你好，请介绍一下你自己" }

接收消息格式（JSON）：
{ "delta": "我是苏格拉底...", "done": false }

关键技术实现要点

• 异步处理： 使用独立线程执行 LLM 调用，避免阻塞 WebSocket 主线程
• 会话验证： 在建立连接时校验 sessionId 的有效性
• 错误处理： 全面捕获异常并记录日志以便追踪问题
• 线程安全： 采用

  synchronized

  确保消息发送过程的线程安全性

完整测试流程

4.1 环境准备

在进入功能测试前，需完成基础环境搭建，包括服务启动、依赖配置、数据库初始化及外部 API 接口连通性验证。

接口响应解析逻辑

.bodyToMono(String.class)
.block();
JsonNode node = objectMapper.readTree(response);
return node.path("choices").get(0)
.path("message").path("content").asText();

一、环境搭建与数据库配置

首先安装 MySQL 8.0 版本，并创建对应的应用数据库。接着执行以下步骤完成初始化：

1. 运行数据库初始化脚本，建立所需的数据表结构

   schema.sql

2. 修改项目中的数据库连接配置文件

   application.properties

   ，确保 URL、用户名和密码正确无误
3. 启动应用服务前，先运行相关初始化程序

   AiRoleplayApplication.java

4. 确认服务成功启动并连接数据库

二、REST API 功能验证（基于 Postman 测试）

测试项1：获取角色列表

GET http://localhost:8080/api/v1/characters

预期返回结果：系统应返回“苏格拉底”与“魔法学徒”两个预设角色信息。

测试项2：创建会话（接入通义千问模型）

POST http://localhost:8080/api/v1/sessions
Content-Type: application/json

{
    "characterId": "char-socrates",
    "mode": "immersive",
    "modelName": "tongyi"
}

关键操作说明：从接口响应中复制生成的 sessionId 字段值

id

测试项3：发送用户消息

POST http://localhost:8080/api/v1/sessions/{sessionId}/messages
Content-Type: application/json

{
    "text": "你好，请介绍一下你自己"
}

实际表现：AI 将以设定的角色——苏格拉底的语气进行回应，体现角色扮演效果。

测试项4：查询历史对话记录

GET http://localhost:8080/api/v1/sessions/{sessionId}/messages

返回内容说明：接口将返回指定会话 ID 下的所有聊天历史数据。

三、WebSocket 实时通信测试

建立 WebSocket 连接：

ws://localhost:8080/ws/chat?sessionId={sessionId}

向服务端发送如下格式的 JSON 消息：

{
"text": "这是通过WebSocket发送的消息"
}

客户端将实时接收来自 AI 的流式响应结果，实现低延迟互动体验。

四、开发过程中遇到的问题及解决方案

问题一：AI 回复包含自我介绍内容

现象描述：在使用通义千问模型时，AI 首次回复出现“我是通义千问…”等脱离角色设定的内容。

根本原因：虽然已在数据库中保存了完整的会话信息

modelName

解决方式：

// 修改前代码
String response = llmServiceFactory.getService(session.getModelName())
.generateResponse(text);

// 修改后代码
String response = llmServiceFactory.getService(session.getModelName())
.generateResponse(text, session); // 显式传入会话对象以构建完整 Prompt

问题二：编译时报 WebClient 类找不到

现象描述：项目构建阶段提示无法识别 WebClient 相关类。

解决方案：在项目的依赖管理文件中添加 Spring WebFlux 支持：

pom.xml

<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webflux</artifactId>
</dependency>

问题三：JPA 实体 ID 生成异常

现象描述：使用 JPA 保存实体时，UUID 类型的主键字段显示为 null。

解决方法：采用 Hibernate 提供的 UUID 生成策略：

@Id
@GeneratedValue(generator = "uuid2")
@GenericGenerator(name = "uuid2", strategy = "org.hibernate.id.UUIDGenerator")
private String id;

五、项目核心亮点总结

5.1 技术层面的优势

• 分层架构 + 策略模式：整体结构清晰，便于后期维护与功能扩展
• 多模型动态支持：借助工厂模式实现在运行时灵活切换不同 AI 模型
• Prompt 工程优化：根据角色设定和对话场景动态组装提示词，增强角色沉浸感
• 双通道通信机制：同时提供 REST API 和 WebSocket 接口，适配同步请求与实时交互场景
• 全链路数据持久化：所有会话记录均存储于数据库，支持历史查询与回溯分析

5.2 技术能力提升

通过本项目实践，深入掌握了以下技能：

• Spring Boot 3.x 的新特性及其最佳编码实践
• 主流大模型 API 的接入方式与参数差异
• WebSocket 在流式响应和实时通信中的具体应用
• 设计模式在复杂业务逻辑中的落地实践
• Prompt 工程的基本原理与调优技巧

六、项目交付情况

6.1 交付成果清单

• 完整的 Maven 构建源码工程
• 数据库结构初始化脚本（schema.sql）
• 详细的测试文档（Word 格式）
• API 接口说明文档
• 运行环境配置指南

客户已使用 Postman 对全部接口进行验证，确认功能完全满足需求，项目顺利通过验收。

6.2 后续可优化方向

若资源允许，建议推进以下改进：

• 引入 JWT 实现用户认证与权限控制
• 实现真正的流式输出（如 SSE 或 WebSocket 分片传输）
• 增强上下文记忆能力，避免每次调用孤立处理
• 集成更多第三方大模型以提升选择灵活性
• 增加敏感词过滤与内容安全审核机制
• 开发对话摘要生成与关键词提取功能

七、参考资料

• 通义千问 API 官方文档
• DeepSeek 大模型接口说明
• Spring Boot 官方技术手册
• WebSocket 协议标准规范

结语

这是我首次独立完成一个 AI 应用的后端系统开发，涵盖需求分析、架构设计、编码实现到最终测试交付的全流程。整个过程不仅加深了我对 Spring Boot 框架的理解，也让我对大模型应用的开发模式有了更真实的体会。

项目核心收获：

• 掌握多模型集成的设计思路与实现方式
• 熟练运用 Prompt 工程提升 AI 表现力
• 积累真实项目开发经验
• 全面提升问题定位与解决能力

希望本文能为正在学习 AI 应用开发的同学提供参考价值。

关键词展示：

SpringBoot

AI角色扮演

通义千问

DeepSeek

WebSocket

大模型应用

Prompt工程

设计模式

创作过程颇为不易，若您认为内容有所帮助，欢迎点赞、收藏并给予支持。