SSE on Zell Blog

Spring AI 流式输出实战：SSE 实现 RAG 智能问答

Tue, 28 Apr 2026 00:00:00 +0000

概述

本文介绍如何在 Spring AI 中实现 SSE（Server-Sent Events）流式输出，结合 RAG 知识库问答功能，实现类似 ChatGPT 的流式对话体验。

SSE 简介

SSE 是一种服务端推送技术，允许服务器通过 HTTP 连接向客户端连续发送事件。与 WebSocket 的全双工通信不同，SSE 是单通道的，适合服务器向客户端推送数据场景。

┌─────────┐              ┌─────────┐              ┌─────────┐
│  客户端  │              │  服务器  │              │ 知识库  │
└────┬────┘              └────┬────┘              └────┬────┘
     │                         │                        │
     │──── GET /stream ───────▶│                        │
     │                         │                        │
     │◀─── event: chunk 1 ────│                        │
     │◀─── event: chunk 2 ────│                        │
     │◀─── event: chunk 3 ────│─────── RAG ──────────▶│
     │                         │◀────── 检索结果 ───────│
     │◀─── event: chunk N ────│                        │
     │                         │                        │
     │──── GET /sessions ──────▶│                        │

项目架构

┌─────────────────────────────────────────────────────────────────┐
│                        前端（浏览器）                            │
│    EventSource 接收 SSE → 实时显示 AI 回答                       │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                     RagChatController                            │
│  @PostMapping(value = "/messages/stream",                        │
│          produces = MediaType.TEXT_EVENT_STREAM_VALUE)           │
│    返回 Flux<ServerSentEvent<String>>                            │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    RagChatSessionService                         │
│  prepareStreamMessage()  → 保存用户消息，创建 AI 消息占位        │
│  getStreamAnswer()       → 调用 queryService 获取流式回答        │
│  completeStreamMessage() → 流式完成后更新消息内容                 │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                  KnowledgeBaseQueryService                       │
│  answerQuestionStream() → 调用 Spring AI ChatClient 流式生成     │
│  normalizeStreamOutput() → 探测窗口归一化处理                    │
└───────────────────────────────┬─────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    KnowledgeBaseVectorService                    │
│  similaritySearch() → 向量数据库相似度检索                       │
└─────────────────────────────────────────────────────────────────┘

核心实现

1. 流式接口设计

RagChatController 提供流式消息接口：

@Slf4j
@RestController
@RequiredArgsConstructor
@RequestMapping("/api/rag-chat")
@Tag(name = "RAG 问答", description = "基于知识库的智能问答会话")
public class RagChatController {

    private final RagChatSessionService sessionService;

    /**
     * 发送消息（流式SSE）
     *
     * 流式响应设计：
     * 1. 先同步保存用户消息和创建 AI 消息占位
     * 2. 返回流式响应
     * 3. 流式完成后通过回调更新消息
     */
    @PostMapping(value = "/sessions/{sessionId}/messages/stream",
            produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<ServerSentEvent<String>> sendMessageStream(
            @PathVariable Long sessionId,
            @Valid @RequestBody RagChatDTO.SendMessageRequest request) {
        log.info("收到 RAG 聊天流式请求: sessionId={}, question={}",
                sessionId, request.question());

        // 1. 准备消息（保存用户消息，创建 AI 消息占位）
        Long messageId = sessionService.prepareStreamMessage(sessionId, request.question());

        // 2. 获取流式响应
        StringBuilder fullContent = new StringBuilder();

        return sessionService.getStreamAnswer(sessionId, request.question())
                // 累积完整内容
                .doOnNext(fullContent::append)
                // 转换为 ServerSentEvent 格式
                .map(chunk -> ServerSentEvent.<String>builder()
                        .data(chunk.replace("\n", "\\n").replace("\r", "\\r"))
                        .build()
                )
                // 流式完成后的回调
                .doOnComplete(() -> {
                    sessionService.completeStreamMessage(messageId, fullContent.toString());
                    log.info("RAG 聊天流式完成: sessionId={}, messageId={}", sessionId, messageId);
                })
                // 错误处理
                .doOnError(e -> {
                    String content = !fullContent.isEmpty()
                            ? fullContent.toString()
                            : "【错误】回答生成失败：" + e.getMessage();
                    sessionService.completeStreamMessage(messageId, content);
                    log.error("RAG 聊天流式错误: sessionId={}", sessionId, e);
                });
    }
}

2. 会话服务

RagChatSessionService 管理会话状态和消息：

@Service
@Slf4j
@RequiredArgsConstructor
public class RagChatSessionService {

    private final KnowledgeRepository knowledgeRepository;
    private final RagChatSessionRepository sessionRepository;
    private final RagChatMapper chatMapper;
    private final RagChatMessageRepository chatMessageRepository;
    private final KnowledgeBaseMapper knowledgeBaseMapper;
    private final KnowledgeBaseQueryService queryService;

    /**
     * 准备流式消息（保存用户消息，创建 AI 消息占位）
     *
     * @return AI 消息的 ID（用于后续更新）
     */
    @Transactional
    public Long prepareStreamMessage(Long sessionId, @NotBlank(message = "问题不能为空") String question) {
        RagChatSessionEntity session = sessionRepository.findByIdWithKnowledgeBases(sessionId)
                .orElseThrow(() -> new BusinessException(ErrorCode.NOT_FOUND, "会话不存在"));

        Integer nextOrder = session.getMessageCount();

        // 保存用户消息
        RagChatMessageEntity userMessage = new RagChatMessageEntity();
        userMessage.setSession(session);
        userMessage.setType(RagChatMessageEntity.MessageType.USER);
        userMessage.setContent(question);
        userMessage.setMessageOrder(nextOrder);
        userMessage.setCompleted(true);
        chatMessageRepository.save(userMessage);

        // 保存系统占位消息
        RagChatMessageEntity assistantMessage = new RagChatMessageEntity();
        assistantMessage.setSession(session);
        assistantMessage.setType(RagChatMessageEntity.MessageType.ASSISTANT);
        assistantMessage.setContent("");
        assistantMessage.setMessageOrder(++nextOrder);
        assistantMessage.setCompleted(false);
        chatMessageRepository.save(assistantMessage);

        // 更新会话消息数量
        session.setMessageCount(nextOrder + 1);
        sessionRepository.save(session);

        log.info("准备流式消息: sessionId={}, messageId={}", sessionId, assistantMessage.getId());
        return assistantMessage.getId();
    }

    /**
     * 获取流式回答
     */
    public Flux<String> getStreamAnswer(Long sessionId, String question) {
        RagChatSessionEntity session = sessionRepository.findByIdWithKnowledgeBases(sessionId)
                .orElseThrow(() -> new BusinessException(ErrorCode.NOT_FOUND, "会话不存在"));

        List<Long> kbIds = session.getKnowledgeBaseIds();
        return queryService.answerQuestionStream(kbIds, question);
    }

    /**
     * 完成流式消息（更新消息内容）
     */
    public void completeStreamMessage(Long messageId, String answer) {
        RagChatMessageEntity message = chatMessageRepository.findById(messageId)
                .orElseThrow(() -> new BusinessException(ErrorCode.NOT_FOUND, "消息不存在"));
        message.setCompleted(true);
        message.setContent(answer);
        chatMessageRepository.save(message);
        log.info("完成流式消息: messageId={}, contentLength={}", messageId, answer.length());
    }
}

3. 流式输出归一化处理

KnowledgeBaseQueryService 中的流式处理逻辑：

/**
 * 流式输出归一化处理
 *
 * 设计目标：
 * - 探测前 120 字符，快速识别"无信息"模板
 * - 命中无信息：立即输出固定模板并结束，防止长篇拒答
 * - 非无信息：尽快释放缓冲并实时透传
 */
private Flux<String> normalizeStreamOutput(Flux<String> rawFlux) {
    return Flux.create(sink -> {
        StringBuilder probeBuffer = new StringBuilder();
        AtomicBoolean passthrough = new AtomicBoolean(false);
        AtomicBoolean completed = new AtomicBoolean(false);
        final Disposable[] disposableRef = new Disposable[1];

        disposableRef[0] = rawFlux.subscribe(
                chunk -> {
                    // 已完成或已取消，跳过
                    if (completed.get() || sink.isCancelled()) {
                        return;
                    }

                    // 已进入透传模式，直接发送
                    if (passthrough.get()) {
                        sink.next(chunk);
                        return;
                    }

                    // 累积探测文本
                    probeBuffer.append(chunk);
                    String probeText = probeBuffer.toString();

                    // 检测"无信息"模板
                    if (isNoResultLike(probeText)) {
                        completed.set(true);
                        sink.next(NO_RESULT_RESPONSE);
                        sink.complete();
                        if (disposableRef[0] != null) {
                            disposableRef[0].dispose();
                        }
                        return;
                    }

                    // 探测窗口（120字符）后开始透传
                    if (probeBuffer.length() >= STREAM_PROBE_CHARS) {
                        passthrough.set(true);
                        sink.next(probeText);
                        probeBuffer.setLength(0);
                    }
                },
                sink::error,
                () -> {
                    // 流式完成
                    if (completed.get() || sink.isCancelled()) {
                        return;
                    }
                    if (!passthrough.get()) {
                        sink.next(normalizeAnswer(probeBuffer.toString()));
                    }
                    sink.complete();
                }
        );

        // 取消时清理资源
        sink.onCancel(() -> {
            if (disposableRef[0] != null) {
                disposableRef[0].dispose();
            }
        });
    });
}

private boolean isNoResultLike(String text) {
    return text.contains("没有找到相关信息")
            || text.contains("未检索到相关信息")
            || text.contains("信息不足")
            || text.contains("超出知识库范围")
            || text.contains("无法根据提供内容回答");
}

4. 消息实体

@Entity
@Table(name = "rag_chat_messages", indexes = {
    @Index(name = "idx_rag_message_session", columnList = "session_id"),
    @Index(name = "idx_rag_message_order", columnList = "session_id, messageOrder")
})
@Getter
@Setter
@NoArgsConstructor
public class RagChatMessageEntity {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "session_id", nullable = false)
    private RagChatSessionEntity session;

    @Enumerated(EnumType.STRING)
    @Column(nullable = false, length = 20)
    private MessageType type;

    @Column(columnDefinition = "TEXT", nullable = false)
    private String content;

    @Column(nullable = false)
    private Integer messageOrder;

    @Column(nullable = false, updatable = false)
    private LocalDateTime createdAt;

    private LocalDateTime updatedAt;

    private Boolean completed = true;

    public enum MessageType {
        USER,      // 用户消息
        ASSISTANT  // AI 回答
    }

    @PrePersist
    protected void onCreate() {
        createdAt = LocalDateTime.now();
        updatedAt = LocalDateTime.now();
    }

    @PreUpdate
    protected void onUpdate() {
        updatedAt = LocalDateTime.now();
    }
}

5. DTO 定义

public class RagChatDTO {

    // ========== 请求 DTO ==========

    /**
     * 创建会话请求
     */
    public record CreateSessionRequest(
            @NotEmpty(message = "至少选择一个知识库")
            List<Long> knowledgeBaseIds,
            String title  // 可选，为空则自动生成
    ) {
    }

    /**
     * 发送消息请求
     */
    public record SendMessageRequest(
            @NotBlank(message = "问题不能为空")
            String question
    ) {
    }

    /**
     * 更新标题请求
     */
    public record UpdateTitleRequest(
            @NotNull(message = "请选择会话")
            Long sessionId,
            @NotBlank(message = "标题不能为空")
            String title
    ) {
    }

    /**
     * 更新知识库请求
     */
    public record UpdateKnowledgeBasesRequest(
            @NotNull(message = "请选择会话")
            Long sessionId,
            @NotEmpty(message = "至少选择一个知识库")
            List<Long> knowledgeBaseIds
    ) {
    }

    // ========== 响应 DTO ==========

    /**
     * 会话基础信息
     */
    public record SessionDTO(
            Long id,
            String title,
            List<Long> knowledgeBaseIds,
            LocalDateTime createdAt
    ) {
    }

    /**
     * 会话列表项
     */
    public record SessionListItemDTO(
            Long id,
            String title,
            Integer messageCount,
            List<String> knowledgeBaseNames,
            LocalDateTime updatedAt,
            Boolean isPinned
    ) {
    }

    /**
     * 会话详情（含消息）
     */
    public record SessionDetailDTO(
            Long id,
            String title,
            List<KnowledgeBaseListItemDTO> knowledgeBases,
            List<MessageDTO> messages,
            LocalDateTime createdAt,
            LocalDateTime updatedAt
    ) {
    }

    /**
     * 消息 DTO
     */
    public record MessageDTO(
            Long id,
            String type,  // "user" | "assistant"
            String content,
            LocalDateTime createdAt
    ) {
    }
}

前端对接

EventSource 接收 SSE

// 创建 EventSource（注意：GET 请求，参数在 URL 中）
const sessionId = 123;
const eventSource = new EventSource(`/api/rag-chat/sessions/${sessionId}/messages/stream?question=${encodeURIComponent(question)}`);

// 监听消息事件
eventSource.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log('Received:', data);
    // data 就是 AI 返回的文本片段
    appendToChat(data);
};

// 监听错误
eventSource.onerror = (error) => {
    console.error('SSE Error:', error);
    eventSource.close();
};

// 关闭连接
function closeChat() {
    eventSource.close();
}

Fetch API 接收 SSE（推荐）

async function sendMessage(sessionId, question) {
    const response = await fetch(`/api/rag-chat/sessions/${sessionId}/messages/stream`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({ question }),
    });

    const reader = response.body.getReader();
    const decoder = new TextDecoder();

    while (true) {
        const { done, value } = await reader.read();
        if (done) break;

        const chunk = decoder.decode(value);
        // 解析 SSE 格式: data: {"data":"xxx"}\n\n
        const lines = chunk.split('\n');
        for (const line of lines) {
            if (line.startsWith('data: ')) {
                const data = JSON.parse(line.slice(6));
                console.log('Received:', data.data);
                appendToChat(data.data);
            }
        }
    }
}

SSE 数据格式

Spring AI 返回的 SSE 格式：

data: {"data":"今天"}

data: {"data":"天"}

data: {"data":"气"}

data: {"data":"不"}

data: {"data":"错"}

会话管理 API

创建会话

POST /api/rag-chat/sessions
Content-Type: application/json

{
    "knowledgeBaseIds": [1, 2, 3],
    "title": "我的智能问答"
}

获取会话列表

`1`	`GET /api/rag-chat/sessions`

获取会话详情

`1`	`GET /api/rag-chat/sessions/{sessionId}`

删除会话

`1`	`DELETE /api/rag-chat/sessions/{sessionId}`

更新会话标题

PUT /api/rag-chat/sessions/title
Content-Type: application/json

{
    "sessionId": 123,
    "title": "新标题"
}

切换置顶状态

`1`	`PUT /api/rag-chat/sessions/{sessionId}/pin`

更换会话知识库

PUT /api/rag-chat/sessions/knowledge-bases
Content-Type: application/json

{
    "sessionId": 123,
    "knowledgeBaseIds": [4, 5]
}

流式响应完整流程

┌─────────────────────────────────────────────────────────────────────┐
│                         请求阶段                                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  前端  ──── POST /sessions/1/messages/stream ────▶  Controller      │
│                        │                                             │
│                        ▼                                             │
│               prepareStreamMessage()                                 │
│                        │                                             │
│                        ├── 保存用户消息                               │
│                        ├── 创建 AI 消息占位（completed=false）         │
│                        └── 返回 messageId                            │
│                                                                      │
├─────────────────────────────────────────────────────────────────────┤
│                         流式阶段                                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  Controller  ──── getStreamAnswer() ────▶  QueryService             │
│                        │                                             │
│                        ▼                                             │
│              answerQuestionStream()                                  │
│                        │                                             │
│                        ├── RAG 检索（多候选查询）                      │
│                        ├── 构建 Prompt                               │
│                        └── chatClient.stream() → Flux<String>        │
│                                                                      │
│  Flux<String>  ──── normalizeStreamOutput() ────▶ 前端              │
│                        │                                             │
│                        ├── 探测窗口（120字符）                         │
│                        ├── 无结果模板检测                             │
│                        └── 实时透传或终止                             │
│                                                                      │
├─────────────────────────────────────────────────────────────────────┤
│                         完成阶段                                     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  前端  ──── 流式完成 ────▶  doOnComplete()                           │
│                        │                                             │
│                        ▼                                             │
│              completeStreamMessage(messageId, content)              │
│                        │                                             │
│                        └── 更新消息内容，completed=true                │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

提示词配置

系统提示词

你是一个专业的知识库问答助手。请根据提供的上下文信息，准确回答用户的问题。

要求：
1. 只回答与上下文相关的问题
2. 如果上下文中没有相关信息，请明确告知用户
3. 回答要条理清晰，简洁明了
4. 对于涉及专业知识的问题，尽量给出准确的解释

用户提示词

上下文信息：
{{context}}

用户问题：{{question}}

请根据上下文信息回答用户问题。

常见问题

1. 流式中断

检查网络连接和服务器日志，确保 SSE 连接保持活跃。

2. 乱序问题

SSE 保证顺序，但如果前端渲染不及时，可能导致显示顺序混乱。建议使用数组累积后统一渲染。

3. 跨域问题

如果前端与后端在不同域名，需要配置 CORS：

@Configuration
public class WebConfig implements WebFluxConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins("*")
                .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                .allowedHeaders("*");
    }
}

总结

本文介绍了基于 Spring AI 实现 SSE 流式输出的完整方案：

Controller 层：返回 Flux<ServerSentEvent<String>>，使用 .map() 转换为 SSE 格式
Service 层：
- prepareStreamMessage() - 预先保存消息占位
- getStreamAnswer() - 获取流式回答
- completeStreamMessage() - 流式完成后更新消息
QueryService 层：
- normalizeStreamOutput() - 流式归一化处理
- 探测窗口快速识别无结果
- 支持流式透传和异常终止
前端对接：使用 EventSource 或 Fetch API 接收 SSE

SpringAI实战指南_大模型集成_流式输出

Mon, 13 Apr 2026 10:00:00 +0800

前言

Spring AI 是 Spring 官方打造的 AI 应用开发框架，旨在将 AI 能力无缝集成到 Spring 生态系统中。它侧重于提供构建 AI 应用所需的底层原子能力抽象，让 Java 开发者可以像使用其他 Spring 组件一样，轻松地与大语言模型进行交互。

一、Spring AI 核心能力

能力	说明	应用场景
模型通信 (ChatClient)	统一接口与不同 LLM 对话	简历评分、问答生成
提示词 (Prompt)	结构化管理发送给模型的提示词	.st 模板文件管理
RAG (检索增强生成)	通过 VectorStore 实现 RAG 模式	知识库问答
工具调用 (Function Calling)	模型调用 Java 应用中定义的方法	Agent
记忆 (ChatMemory)	管理多轮对话的上下文历史	会话管理

二、框架对比与选型

2.1 Java AI 框架对比

框架	特点	JDK 基线	适用场景
Spring AI	Spring 官方，原生集成	JDK 17+（建议 JDK 21）	Spring 项目首选
LangChain4j	功能全面，更新快	JDK 8+	老项目，兼容性需求
Solon-AI	轻量化，性能优秀	JDK 8+	Serverless、GraalVM
Agent-Flex	专注于 Agent 编排	JDK 11/17+	Agent 编排需求

2.2 为什么选择 Spring AI

无缝集成：与现有 Spring Boot 技术栈完美融合，学习成本低
高度抽象：统一的、与具体模型无关的 API，轻松切换模型
生态整合：整合向量数据库、ETL 框架等 AI 应用开发工具链
虚拟线程支持：全面拥抱 Java 21 虚拟线程，高并发处理能力强

三、项目依赖配置

3.1 添加依赖

// build.gradle
dependencies {
    // Spring AI 2.0 - OpenAI兼容模式 (阿里云DashScope)
    implementation "org.springframework.ai:spring-ai-starter-model-openai:${spring-ai.version}"
    // Spring AI 2.0 - PostgreSQL Vector Store (pgvector)
    implementation "org.springframework.ai:spring-ai-starter-vector-store-pgvector:${spring-ai.version}"
}

3.2 配置属性

# application.yml
spring:
  ai:
    openai:
      base-url: https://dashscope.aliyuncs.com/compatible-mode
      api-key: ${AI_BAILIAN_API_KEY}
      chat:
        options:
          model: ${AI_MODEL:qwen-plus}
          temperature: 0.2
      # Embedding模型配置
      embedding:
        options:
          model: text-embedding-v3
    # 禁用自动重试机制，让异常立即返回
    retry:
      max-attempts: 1
      on-client-errors: false
    # PostgreSQL Vector Store配置
    vectorstore:
      pgvector:
        index-type: HNSW
        distance-type: COSINE_DISTANCE
        dimensions: 1024
        initialize-schema: true
        remove-existing-vector-store-table: false

3.3 关键配置说明

配置项	说明
`base-url`	阿里云 DashScope 的 OpenAI 兼容端点
`api-key`	通过环境变量注入，严禁硬编码
`temperature`	控制输出随机性（0-1），结构化输出使用 0.2 更稳定
`dimensions`	text-embedding-v3 的向量维度为 1024
`initialize-schema`	开发环境设为 true 自动创建表

四、ChatClient 大模型调用

4.1 服务类设计

@Service
public class ResumeGradingService {

    private final ChatClient chatClient;
    private final PromptTemplate systemPromptTemplate;
    private final PromptTemplate userPromptTemplate;
    private final BeanOutputConverter<ResumeAnalysisResponseDTO> outputConverter;

    public ResumeGradingService(
            ChatClient.Builder chatClientBuilder,
            @Value("classpath:prompts/resume-analysis-system.st") Resource systemPromptResource,
            @Value("classpath:prompts/resume-analysis-user.st") Resource userPromptResource) {
        this.chatClient = chatClientBuilder.build();
        this.systemPromptTemplate = new PromptTemplate(systemPromptResource.getContentAsString(StandardCharsets.UTF_8));
        this.userPromptTemplate = new PromptTemplate(userPromptResource.getContentAsString(StandardCharsets.UTF_8));
        this.outputConverter = new BeanOutputConverter<>(ResumeAnalysisResponseDTO.class);
    }
}

4.2 调用大模型

public ResumeAnalysisResponse analyzeResume(String resumeText) {
    // 1. 加载系统提示词
    String systemPrompt = systemPromptTemplate.render();

    // 2. 加载用户提示词并填充变量
    Map<String, Object> variables = new HashMap<>();
    variables.put("resumeText", resumeText);
    String userPrompt = userPromptTemplate.render(variables);

    // 3. 添加格式指令到系统提示词
    String systemPromptWithFormat = systemPrompt + "\n\n" + outputConverter.getFormat();

    // 4. 调用AI
    ResumeAnalysisResponseDTO dto = chatClient.prompt()
        .system(systemPromptWithFormat)
        .user(userPrompt)
        .call()
        .entity(outputConverter);

    // 5. 转换为业务对象
    return convertToResponse(dto, resumeText);
}

4.3 调用流程图

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ 加载提示词   │────▶│ 填充变量    │────▶│ 调用 ChatClient│
└─────────────┘     └─────────────┘     └─────────────┘
                                               │
                                               ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ 转换业务对象 │◀────│ 解析响应    │◀────│ 获取 AI 响应 │
└─────────────┘     └─────────────┘     └─────────────┘

五、结构化输出

5.1 Java Record 定义

// 中间DTO用于接收AI响应
private record ResumeAnalysisResponseDTO(
    int overallScore,
    ScoreDetailDTO scoreDetail,
    String summary,
    List<String> strengths,
    List<SuggestionDTO> suggestions
) {}

private record ScoreDetailDTO(
    int contentScore,
    int structureScore,
    int skillMatchScore,
    int expressionScore,
    int projectScore
) {}

private record SuggestionDTO(
    String category,
    String priority,
    String issue,
    String recommendation
) {}

5.2 结构化输出重试策略

public <T> T invokeWithRetry(ChatClient chatClient, String systemPrompt,
                              String userPrompt, BeanOutputConverter<T> converter) {
    int maxAttempts = 2;
    Exception lastError = null;

    for (int i = 0; i < maxAttempts; i++) {
        try {
            return chatClient.prompt()
                .system(systemPrompt + "\n\n" + converter.getFormat())
                .user(userPrompt)
                .call()
                .entity(converter);
        } catch (Exception e) {
            lastError = e;
            // 重试时注入上次错误信息
            userPrompt += "\n\n注意：上次输出解析失败，错误原因：" + e.getMessage();
        }
    }
    throw new BusinessException(ErrorCode.AI_RESPONSE_PARSING_FAILED, lastError);
}

5.3 处理流水线

`1`	`生成 → 解析 → 修复（可选）→ 校验`

阶段	说明	失败处理
生成	LLM 输出 JSON	-
解析	Jackson 反序列化	进入修复阶段
修复	将错误信息发回 LLM 要求修正	达最大次数则返回错误
校验	JSR-380 Bean Validation	进入修复阶段

六、流式输出 SSE

6.1 SSE 简介

SSE（Server-Sent Events） 是一种基于 HTTP 的服务器推送技术，允许服务器向客户端单向发送事件流。

6.2 SSE vs WebSocket

维度	SSE	WebSocket
通信方式	单向（服务端→客户端）	全双工
协议	基于 HTTP	独立协议
实现复杂度	低	高
自动重连	支持	需自己实现
二进制数据	需编码	原生支持
适用场景	AI 流式生成、实时通知	聊天室、协作编辑

6.3 SSE 协议格式

data: 第一行内容
data: 第二行内容
data: 第三行内容

id: 事件ID
event: 自定义事件类型
retry: 3000

字段	说明
`data`	具体的业务数据
`event`	自定义事件类型
`id`	事件 ID，断线重连时使用
`retry`	重连间隔（毫秒）

6.4 Spring Boot SSE 实现

@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<ServerSentEvent<String>> streamData() {
    return Flux.interval(Duration.ofMillis(500))
        .map(seq -> ServerSentEvent.<String>builder()
            .id(String.valueOf(seq))
            .event("message")
            .data("消息 " + seq)
            .retry(3000L)
            .build());
}

6.5 Spring AI 流式调用

@GetMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public Flux<ServerSentEvent<String>> streamChat(@RequestParam String question) {
    return chatClient.prompt()
        .system(systemPrompt)
        .user(question)
        .stream()
        .content()
        .map(chunk -> ServerSentEvent.<String>builder()
            .data(chunk.replace("\n", "\\n").replace("\r", "\\r"))
            .build());
}

6.6 SSE 格式转义处理

// 后端转义
.map(chunk -> ServerSentEvent.<String>builder()
    .data(chunk.replace("\n", "\\n").replace("\r", "\\r"))
    .build())

// 前端反向转义
const text = chunk.replace(/\\n/g, '\n').replace(/\\r/g, '\r');

6.7 错误处理与超时控制

return responseFlux
    .timeout(Duration.ofSeconds(30))
    .onErrorResume(TimeoutException.class, e -> {
        log.error("流式输出超时", e);
        return Flux.just("【错误】回答生成超时，请缩短问题或稍后重试。");
    });

6.8 虚拟线程配置

spring:
  threads:
    virtual:
      enabled: true  # 启用虚拟线程

虚拟线程 vs 平台线程：

场景	平台线程	虚拟线程
200 并发 SSE	线程池满，排队	轻松处理
AI 调用等待 3 秒	线程阻塞，占用资源	自动挂起，让出资源
10000 并发请求	拒绝服务	正常处理

七、Function Calling

7.1 Function Calling 原理

Function Calling 允许 LLM 调用我们定义的 Java 方法：

@Bean
public ChatClient chatClient(ChatClient.Builder builder) {
    return builder
        .defaultFunction("getWeather", new GetWeatherFunction())
        .build();
}

public class GetWeatherFunction implements Function<WeatherRequest, WeatherResponse> {
    @Override
    public WeatherResponse apply(WeatherRequest request) {
        // 调用天气 API
        return weatherService.getWeather(request.getCity());
    }
}

7.2 Prompt 模板定义

# System Prompt
你是一个专业的助手。当用户询问天气时，
请调用 getWeather 函数获取实时天气信息。

# User Prompt
{userQuestion}

7.3 处理流程

`1`	`用户输入 → LLM 判断需要调用函数 → 执行函数 → 返回结果 → LLM 生成最终回答`

八、提示词模板管理

8.1 .st 模板文件

# interview-question-system.st
你是一个专业的面试官。请根据候选人的简历内容，
生成针对性的面试问题。

## 要求
1. 问题要基于简历中的具体经历
2. 每个主问题需要生成追问
3. 问题难度要适中，考察真实能力

8.2 变量注入

Map<String, Object> variables = new HashMap<>();
variables.put("resumeText", resumeText);
variables.put("questionCount", 10);
variables.put("followUpCount", 2);

String userPrompt = userPromptTemplate.render(variables);

8.3 安全注入

用户输入注入模板前需清洗特殊符号，防止 Prompt Injection：

public String sanitizeUserInput(String input) {
    // 移除可能破坏 Prompt 结构的符号
    return input.replace("<", "&lt;")
                .replace(">", "&gt;")
                .replace("\"", "&quot;");
}

九、常见问题与解决方案

问题	原因	解决方案
JSON 解析失败	低温导致格式不稳定	升温至 0.3 + Retry 闭环
流式输出中断	网络波动 / 超时	添加超时控制 + 前端重连
响应太慢	上下文太长	减少输入 Token 或分批处理
429 限流	请求频率过高	添加限流器 + 指数退避
线程池耗尽	同步调用阻塞	启用虚拟线程 + 异步处理

十、总结

Spring AI 提供了企业级 AI 应用开发所需的核心能力：

统一抽象：一套代码支持多种 LLM，切换模型只需改配置
结构化输出：BeanOutputConverter 实现 LLM 输出到 Java 对象的自动映射
流式响应：SSE 实现"边生成边展示"的打字机效果
提示词管理：.st 模板文件实现提示词的外置化管理
高并发支持：Java 21 虚拟线程轻松应对高并发场景