Java on Zell Blog

Spring AI结构化输出实战

Mon, 20 Apr 2026 00:00:00 +0000

什么是结构化输出？

在使用大语言模型（LLM）时，模型默认输出的是自由文本。但在企业级应用中，我们往往需要将 AI 的响应解析成结构化的 Java 对象，以便后续业务处理。例如：

简历分析：提取评分、优点、改进建议
订单处理：解析订单号、金额、商品列表
内容审核：返回审核结果、类别、置信度

Spring AI 提供了 BeanOutputConverter 来实现这一功能，而我们需要解决的问题是：LLM 输出不稳定时的重试机制。

项目集成

Maven 依赖

<properties>
    <spring-ai.version>2.0.0-M4</spring-ai.version>
</properties>

<dependencies>
    <!-- Spring AI OpenAI Starter -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
    </dependency>

    <!-- Micrometer（可选，用于指标监控） -->
    <dependency>
        <groupId>io.micrometer</groupId>
        <artifactId>micrometer-core</artifactId>
    </dependency>
</dependencies>

配置类

@Data
@Component
@ConfigurationProperties(prefix = "app.ai")
public class StructuredOutputProperties {

    // 最大重试次数（默认2次）
    private int structuredMaxAttempts = 2;

    // 重试时是否包含上次错误信息
    private boolean structuredIncludeLastError = true;

    // 重试时是否使用修复提示词
    private boolean structuredRetryUseRepairPrompt = true;

    // 重试时是否追加严格的 JSON 格式说明
    private boolean structuredRetryAppendStrictJsonInstruction = true;

    // 错误消息最大长度
    private int structuredErrorMessageMaxLength = 200;

    // 是否启用指标监控
    private boolean structuredMetricsEnabled = true;
}

配置文件

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      base-url: https://api.openai.com

app:
  ai:
    structured-max-attempts: 2
    structured-include-last-error: true
    structured-retry-use-repair-prompt: true
    structured-retry-append-strict-json-instruction: true
    structured-error-message-max-length: 200
    structured-metrics-enabled: true

核心实现：StructuredOutputInvoker

设计思路

用户调用 invoke()
    │
    ├── 第一次尝试
    │       │
    │       └── 成功 → 返回结果
    │       │
    │       └── 失败 → 构建重试提示词（含错误信息）
    │
    ├── 第二次尝试
    │       │
    │       └── 成功 → 返回结果
    │       │
    │       └── 失败 → 记录指标，抛出业务异常
    │
    └── 达到最大重试 → 抛出异常

完整代码

@Component
public class StructuredOutputInvoker {

    private static final String STRICT_JSON_INSTRUCTION = """
    请仅返回可被 JSON 解析器直接解析的 JSON 对象，并严格满足字段结构要求：
    1) 不要输出 Markdown 代码块（如 ```json）。
    2) 不要输出任何解释文字、前后缀、注释。
    3) 所有字符串内引号必须正确转义。
    """;

    private static final String METRIC_INVOCATIONS = "app.ai.structured_output.invocations";
    private static final String METRIC_ATTEMPTS = "app.ai.structured_output.attempts";
    private static final String METRIC_LATENCY = "app.ai.structured_output.latency";

    private final int maxAttempts;
    private final boolean includeLastErrorInRetryPrompt;
    private final boolean retryUseRepairPrompt;
    private final boolean retryAppendStrictJsonInstruction;
    private final int errorMessageMaxLength;
    private final boolean metricsEnabled;
    private final MeterRegistry meterRegistry;

    public StructuredOutputInvoker(
        StructuredOutputProperties properties,
        @Autowired(required = false) MeterRegistry meterRegistry
    ) {
        this.maxAttempts = Math.max(1, properties.getStructuredMaxAttempts());
        this.includeLastErrorInRetryPrompt = properties.isStructuredIncludeLastError();
        this.retryUseRepairPrompt = properties.isStructuredRetryUseRepairPrompt();
        this.retryAppendStrictJsonInstruction = properties.isStructuredRetryAppendStrictJsonInstruction();
        this.errorMessageMaxLength = Math.max(20, properties.getStructuredErrorMessageMaxLength());
        this.metricsEnabled = properties.isStructuredMetricsEnabled();
        this.meterRegistry = meterRegistry;
    }

    public <T> T invoke(
        ChatClient chatClient,
        String systemPromptWithFormat,
        String userPrompt,
        BeanOutputConverter<T> outputConverter,
        ErrorCode errorCode,
        String errorPrefix,
        String logContext,
        Logger log
    ) {
        long startNanos = System.nanoTime();
        String contextTag = normalizeContextTag(logContext);
        Exception lastError = null;

        for (int attempt = 1; attempt <= maxAttempts; attempt++) {
            // 构建提示词：首次尝试用原始提示词，重试时追加错误信息
            String attemptSystemPrompt = attempt == 1
                ? systemPromptWithFormat
                : buildRetrySystemPrompt(systemPromptWithFormat, lastError);

            try {
                T result = chatClient.prompt()
                    .system(attemptSystemPrompt)
                    .user(userPrompt)
                    .call()
                    .entity(outputConverter);

                recordAttempt(contextTag, STATUS_SUCCESS);
                recordInvocation(contextTag, STATUS_SUCCESS, startNanos);
                return result;
            } catch (Exception e) {
                lastError = e;
                recordAttempt(contextTag, STATUS_FAILURE);
                if (attempt < maxAttempts) {
                    log.warn("{}结构化解析失败，准备重试: attempt={}/{}, error={}",
                        logContext, attempt, maxAttempts, e.getMessage());
                } else {
                    log.error("{}结构化解析失败，已达最大重试次数: attempts={}, error={}",
                        logContext, maxAttempts, e.getMessage());
                }
            }
        }

        recordInvocation(contextTag, STATUS_FAILURE, startNanos);
        throw new BusinessException(
            errorCode,
            errorPrefix + (lastError != null ? lastError.getMessage() : "unknown")
        );
    }

    /**
     * 构建重试提示词
     * 在原始提示词基础上追加：
     * 1. 严格的 JSON 格式说明
     * 2. 上次失败的原因
     */
    private String buildRetrySystemPrompt(String systemPromptWithFormat, Exception lastError) {
        if (!retryUseRepairPrompt) {
            return systemPromptWithFormat;
        }

        StringBuilder prompt = new StringBuilder(systemPromptWithFormat)
            .append("\n\n");

        if (retryAppendStrictJsonInstruction) {
            prompt.append(STRICT_JSON_INSTRUCTION).append('\n');
        }
        prompt.append("上次输出解析失败，请仅返回合法 JSON。");

        if (includeLastErrorInRetryPrompt && lastError != null && lastError.getMessage() != null) {
            prompt.append("\n上次失败原因：")
                .append(sanitizeErrorMessage(lastError.getMessage()));
        }
        return prompt.toString();
    }

    private String sanitizeErrorMessage(String message) {
        // 错误信息转成单行，并限制长度
        String oneLine = message.replace('\n', ' ').replace('\r', ' ').trim();
        if (oneLine.length() > errorMessageMaxLength) {
            return oneLine.substring(0, errorMessageMaxLength) + "...";
        }
        return oneLine;
    }
}

使用示例

定义业务 DTO

// 简历分析响应
public record ResumeAnalysisResponse(
    int overallScore,           // 总分
    ScoreDetail scoreDetail,    // 各维度评分
    String summary,             // 摘要
    List<String> strengths,     // 优点列表
    List<Suggestion> suggestions // 改进建议
) {
    public record ScoreDetail(
        int contentScore,        // 内容完整性
        int structureScore,      // 结构清晰度
        int skillMatchScore,     // 技能匹配度
        int expressionScore,     // 表达专业性
        int projectScore         // 项目经验
    ) {}

    public record Suggestion(
        String category,         // 类别
        String priority,         // 优先级
        String issue,            // 问题描述
        String recommendation    // 建议
    ) {}
}

Service 中调用

@Service
@Slf4j
public class ResumeGradingService {

    private final ChatClient client;
    private final PromptTemplate sysPromptTemplate;
    private final PromptTemplate userPromptTemplate;
    private final BeanOutputConverter<ResumeAnalysisResponseDTO> outputConverter;
    private final StructuredOutputInvoker structuredOutputInvoker;

    public ResumeGradingService(
            ChatClient.Builder chatClientBuilder,
            ResourceLoader resourceLoader,
            ResumerAnalysisProperties properties,
            StructuredOutputInvoker structuredOutputInvoker
    ) throws IOException {
        this.client = chatClientBuilder.build();
        this.sysPromptTemplate = new PromptTemplate(
            resourceLoader.getResource(properties.getSystemPromptPath())
                .getContentAsString(StandardCharsets.UTF_8));
        this.userPromptTemplate = new PromptTemplate(
            resourceLoader.getResource(properties.getUserPromptPath())
                .getContentAsString(StandardCharsets.UTF_8));
        this.outputConverter = new BeanOutputConverter<>(ResumeAnalysisResponseDTO.class);
        this.structuredOutputInvoker = structuredOutputInvoker;
    }

    public ResumeAnalysisResponse analyzeResume(String content) {
        log.info("开始分析简历，文本长度: {} 字符", content.length());

        // 使用内部 DTO 接收 AI 响应
        ResumeAnalysisResponseDTO dto = structuredOutputInvoker.invoke(
            client,
            buildSystemPrompt(),          // 系统提示词（含 JSON 格式要求）
            buildUserPrompt(content),     // 用户提示词
            outputConverter,              // 输出转换器
            ErrorCode.AI_INVOKE_FAILED,   // 错误码
            "简历分析失败：",              // 错误前缀
            "resume-grading",             // 日志上下文
            log
        );

        // 转换为业务响应对象
        return toResponse(dto);
    }

    private String buildSystemPrompt() {
        return sysPromptTemplate.render() + "\n\n" + outputConverter.getFormat();
    }

    private String buildUserPrompt(String content) {
        return userPromptTemplate.render(Map.of("content", content));
    }
}

系统提示词示例

你是一个专业的简历评估专家。请分析以下简历，给出评分和改进建议。
请以 JSON 格式返回，字段必须严格遵循以下格式：
{
  "overallScore": 85,           // 总分，0-100
  "scoreDetail": {              // 各维度评分
    "contentScore": 20,         // 内容完整性，0-25
    "structureScore": 18,       // 结构清晰度，0-20
    "skillMatchScore": 22,      // 技能匹配度，0-25
    "expressionScore": 12,      // 表达专业性，0-15
    "projectScore": 13          // 项目经验，0-15
  },
  "summary": "这是一份结构清晰的简历...",
  "strengths": ["技术栈丰富", "项目经验详实"],
  "suggestions": [
    {
      "category": "内容",
      "priority": "中",
      "issue": "缺少量化的工作成果",
      "recommendation": "建议添加具体的数据指标"
    }
  ]
}

重试策略详解

首次尝试 vs 重试尝试

项目	首次尝试	重试尝试
系统提示词	原始提示词	原始提示词 + 修复提示词
JSON 格式说明	包含在原始提示词中	可选择追加
错误信息	无	可选择追加上次错误

重试提示词构建流程

1. 判断是否启用重试修复（retryUseRepairPrompt）
   └── 否：直接返回原始提示词

2. 追加严格 JSON 格式说明（可选）
   └── STRICT_JSON_INSTRUCTION:
       "请仅返回可被 JSON 解析器直接解析的 JSON 对象..."

3. 追加修复指令
   └── "上次输出解析失败，请仅返回合法 JSON。"

4. 追加上次错误原因（可选）
   └── "上次失败原因：{错误信息}"

指标监控

监控指标

指标名称	类型	标签	说明
`app.ai.structured_output.invocations`	Counter	context, status	调用次数
`app.ai.structured_output.attempts`	Counter	context, status	尝试次数（含重试）
`app.ai.structured_output.latency`	Timer	context, status	调用延迟

上下文标签规范化

private String normalizeContextTag(String raw) {
    String source = (raw == null || raw.isBlank()) ? "unknown" : raw;
    // 转小写，空格替换为下划线
    String normalized = source.toLowerCase(Locale.ROOT).trim().replace(' ', '_');
    // 移除非字母数字下划线字符
    normalized = NON_ALNUM_PATTERN.matcher(normalized).replaceAll("_");
    // 压缩多个下划线为一个
    normalized = MULTI_UNDERSCORE.matcher(normalized).replaceAll("_");
    // 去除首尾下划线
    normalized = normalized.replaceAll("^_+|_+$", "");
    // 截断超长标签
    if (normalized.length() > MAX_CONTEXT_TAG_LENGTH) {
        normalized = normalized.substring(0, MAX_CONTEXT_TAG_LENGTH);
    }
    return normalized;
}

常见问题处理

1. LLM 输出 Markdown 代码块

问题：LLM 习惯性输出 ```json {...} ```，导致解析失败。

解决方案：在系统提示词中明确禁止，并在重试时追加：

private static final String STRICT_JSON_INSTRUCTION = """
请仅返回可被 JSON 解析器直接解析的 JSON 对象：
1) 不要输出 Markdown 代码块（如 ```json）。
2) 不要输出任何解释文字、前后缀、注释。
""";

2. 字符串引号未转义

问题：JSON 中字符串内容包含引号，导致解析失败。

解决方案：同上，严格要求输出格式。

3. 部分字段缺失

问题：LLM 省略了部分可选字段。

解决方案：

DTO 字段使用包装类型（Integer 而非 int）
提供完整的默认提示词模板

与 Spring AI BeanOutputConverter 结合

BeanOutputConverter 是 Spring AI 提供的结构化输出转换器：

// 创建转换器，指定目标类型
BeanOutputConverter<ResumeAnalysisResponseDTO> outputConverter =
    new BeanOutputConverter<>(ResumeAnalysisResponseDTO.class);

// 获取 JSON 格式说明（用于系统提示词）
String format = outputConverter.getFormat();
// 输出示例：
// {
//   "overallScore": int,
//   "scoreDetail": {
//     "contentScore": int,
//     ...
//   },
//   ...
// }

// 调用 AI 并自动转换
ResumeAnalysisResponseDTO dto = chatClient.prompt()
    .system(systemPrompt + "\n\n" + format)
    .user(userPrompt)
    .call()
    .entity(outputConverter);

最佳实践

1. 合理设置重试次数

1
2
3

app:
  ai:
    structured-max-attempts: 2  # 一般2-3次足够

2. 提示词设计要点

明确输出格式，使用 BeanOutputConverter.getFormat()
给出每个字段的具体说明和取值范围
对复杂结构提供示例

3. 错误处理

try {
    return structuredOutputInvoker.invoke(...);
} catch (BusinessException e) {
    // 记录日志，返回友好错误或降级结果
    log.error("AI调用失败", e);
    return getDefaultResponse();
}

4. 指标监控

启用 Micrometer 后，可通过 Prometheus/Grafana 监控：

调用成功率
重试率
平均延迟

总结

StructuredOutputInvoker 封装了：

调用逻辑：使用 BeanOutputConverter 实现结构化输出
重试策略：根据配置自动重试，追加修复提示词
错误处理：规范化错误信息，区分首次和重试场景
指标监控：记录调用次数、重试次数、延迟等指标

通过这一封装，我们可以稳定地从 LLM 获取结构化数据，无需关心底层重试逻辑。

Apache Tika使用指南

Thu, 16 Apr 2026 00:00:00 +0000

什么是 Apache Tika？

Apache Tika 是一个内容分析工具包，用于从各种格式的文档中检测和提取元数据及文本内容。Tika 支持检测和解析超过 1000 种文件类型，包括：

文档格式：PDF、Microsoft Office、OpenDocument、RTF、HTML 等
图片格式：JPEG、PNG、TIFF 等（可提取 EXIF 元数据）
邮件格式：MIME 消息
归档格式：ZIP、TAR、GZIP 等
音频/视频：MP3、MP4、AVI 等的元数据
其他：XML、JSON、CSV 等结构化格式

项目集成

Maven 依赖

<properties>
    <tika.version>3.2.2</tika.version>
</properties>

<dependencies>
    <!-- 核心库 -->
    <dependency>
        <groupId>org.apache.tika</groupId>
        <artifactId>tika-core</artifactId>
        <version>${tika.version}</version>
    </dependency>

    <!-- 解析器包（包含所有主流文档格式的解析器） -->
    <dependency>
        <groupId>org.apache.tika</groupId>
        <artifactId>tika-parsers-standard-package</artifactId>
        <version>${tika.version}</version>
    </dependency>
</dependencies>

注意：tika-parsers-standard-package 会包含所有解析器，如果需要更小的包体积，可以只引入特定解析器。

基础使用

1. 简单文本提取

import org.apache.tika.Tika;
import org.springframework.web.multipart.MultipartFile;

@Service
public class DocumentService {

    private final Tika tika = new Tika();

    public String extractText(MultipartFile file) throws Exception {
        try (InputStream inputStream = file.getInputStream()) {
            return tika.parseToString(inputStream);
        }
    }
}

2. 自动检测文件类型

import org.apache.tika.Tika;
import org.apache.tika.mime.MimeType;
import org.apache.tika.mime.MimeTypeException;

@Service
public class ContentTypeDetectionService {

    private final Tika tika = new Tika();

    public String detectContentType(MultipartFile file) {
        try (InputStream inputStream = file.getInputStream()) {
            // 根据文件内容检测类型
            return tika.detect(inputStream, file.getOriginalFilename());
        } catch (Exception e) {
            // 检测失败时回退到 HTTP Content-Type
            return file.getContentType();
        }
    }
}

进阶使用

使用 Parser API 进行精细控制

在项目实践中，我们使用 AutoDetectParser 和 ParseContext 进行更精细的控制：

import org.apache.tika.parser.AutoDetectParser;
import org.apache.tika.parser.ParseContext;
import org.apache.tika.parser.Parser;
import org.apache.tika.sax.BodyContentHandler;
import org.apache.tika.metadata.Metadata;
import org.apache.tika.exception.TikaException;
import org.apache.tika.extractor.EmbeddedDocumentExtractor;
import org.apache.tika.parser.pdf.PDFParserConfig;
import org.springframework.web.multipart.MultipartFile;

@Service
public class DocumentParseService {

    private static final int MAX_TEXT_LENGTH = 5 * 1024 * 1024; // 5MB

    public String parseContent(MultipartFile file) throws Exception {
        try (InputStream inputStream = file.getInputStream()) {
            return parseContent(inputStream);
        }
    }

    private String parseContent(InputStream inputStream)
            throws TikaException, IOException, SAXException {

        // 1. 创建自动检测解析器
        AutoDetectParser parser = new AutoDetectParser();

        // 2. 创建内容处理器，限制最大文本长度
        BodyContentHandler handler = new BodyContentHandler(MAX_TEXT_LENGTH);

        // 3. 创建元数据对象
        Metadata metadata = new Metadata();

        // 4. 创建解析上下文
        ParseContext context = new ParseContext();

        // 5. 显式指定 Parser 到 Context（增强健壮性）
        context.set(Parser.class, parser);

        // 6. 禁用嵌入文档解析（避免提取图片引用和临时文件路径）
        context.set(EmbeddedDocumentExtractor.class,
                    new NoOpEmbeddedDocumentExtractor());

        // 7. PDF 专用配置：关闭图片提取，按位置排序文本
        PDFParserConfig pdfConfig = new PDFParserConfig();
        pdfConfig.setExtractInlineImages(false);
        pdfConfig.setSortByPosition(true);
        context.set(PDFParserConfig.class, pdfConfig);

        // 8. 执行解析
        parser.parse(inputStream, handler, metadata, context);

        return handler.toString();
    }
}

禁用嵌入资源解析

在解析 PDF 等文档时，Tika 默认会尝试提取嵌入的图片和附件，这可能导致提取到无用的临时文件路径：

import org.apache.tika.extractor.EmbeddedDocumentExtractor;

// 自定义空提取器，不处理嵌入资源
public class NoOpEmbeddedDocumentExtractor implements EmbeddedDocumentExtractor {

    @Override
    public boolean shouldParseEmbedded(Metadata metadata) {
        return false; // 不解析任何嵌入资源
    }

    @Override
    public void parseEmbedded(InputStream inputStream, ContentHandler contentHandler,
                             Metadata metadata, boolean outputHtml) throws IOException {
        // 空实现，不做任何提取
    }
}

提取元数据

获取文档元数据

import org.apache.tika.parser.AutoDetectParser;
import org.apache.tika.metadata.Metadata;
import org.apache.tika.metadata.TikaCoreProperties;

public void extractMetadata(InputStream inputStream) throws Exception {
    AutoDetectParser parser = new AutoDetectParser();
    BodyContentHandler handler = new BodyContentHandler();
    Metadata metadata = new Metadata();

    parser.parse(inputStream, handler, metadata);

    // 获取常用元数据
    System.out.println("标题: " + metadata.get(TikaCoreProperties.TITLE));
    System.out.println("作者: " + metadata.get(TikaCoreProperties.CREATOR));
    System.out.println("创建日期: " + metadata.get(TikaCoreProperties.CREATED));
    System.out.println("修改日期: " + metadata.get(TikaCoreProperties.MODIFIED));
    System.out.println("文件类型: " + metadata.get("Content-Type"));

    // 打印所有元数据
    for (String name : metadata.names()) {
        System.out.println(name + ": " + metadata.get(name));
    }
}

PDF 专用元数据

import org.apache.tika.metadata.PDF;

// PDF 特有元数据
System.out.println("PDF 标题: " + metadata.get(PDF.TITLE));
System.out.println("PDF 作者: " + metadata.get(PDF.AUTHOR));
System.out.println("PDF 创建者: " + metadata.get(PDF.CREATOR));
System.out.println("页数: " + metadata.getInt(PDF.NUMBER_OF_PAGES));

解析特定格式

解析 PDF

import org.apache.tika.parser.pdf.PDFParser;
import org.apache.tika.parser.pdf.PDFParserConfig;

PDFParser parser = new PDFParser();
PDFParserConfig config = new PDFParserConfig();
config.setExtractInlineImages(false);  // 不提取内联图片
config.setSortByPosition(true);       // 按位置排序文本（适合中文）
config.setSuppressDuplicateOverlappingText(true); // 抑制重复文本

ParseContext context = new ParseContext();
context.set(PDFParserConfig.class, config);

解析 Microsoft Office 文档

import org.apache.tika.parser.microsoft.ooxml.OOXMLParser;
import org.apache.tika.parser.microsoft.ParserFactory;
import org.apache.tika.parser.microsoft.OfficeParserConfig;

// Word、Excel、PowerPoint 都使用 OOXMLParser
OOXMLParser parser = new OOXMLParser();
OfficeParserConfig config = new OfficeParserConfig();
config.setConcatenatePhrases(true); // 合并短语

ParseContext context = new ParseContext();
context.set(OfficeParserConfig.class, config);

解析 HTML

import org.apache.tika.parser.html.HtmlParser;
import org.apache.tika.parser.html.HtmlParserConfig;

// 包含 Jsoup 解析器配置
HtmlParser parser = new HtmlParser();
HtmlParserConfig config = new HtmlParserConfig();
config.setJavascript(false);    // 不执行 JavaScript
config.setMaxTextLength(10000); // 最大文本长度

ParseContext context = new ParseContext();
context.set(HtmlParserConfig.class, config);

文本清洗处理

Tika 提取的文本通常需要进一步清洗才能用于后续处理（如 RAG、知识库等）：

@Service
public class TextCleaningService {

    // 图片文件名行：image123.png
    private static final Pattern IMAGE_FILENAME_LINE =
            Pattern.compile("(?m)^image\\d+\\.(png|jpe?g|gif|bmp|webp)\\s*$");

    // HTTP/HTTPS 图片链接
    private static final Pattern IMAGE_URL =
            Pattern.compile("https?://\\S+?\\.(png|jpe?g|gif|bmp|webp)(\\?\\S*)?",
                          Pattern.CASE_INSENSITIVE);

    // 文件协议 URL（Tika PDF 临时文件路径等）
    private static final Pattern FILE_URL =
            Pattern.compile("file:(//)?\\S+", Pattern.CASE_INSENSITIVE);

    // 分隔线
    private static final Pattern SEPARATOR_LINE =
            Pattern.compile("(?m)^\\s*[-_*=]{3,}\\s*$");

    // 控制字符
    private static final Pattern CONTROL_CHARS =
            Pattern.compile("[\\u0000-\\u0008\\u000B\\u000C\\u000E-\\u001F]");

    public String cleanText(String text) {
        if (text == null || text.isBlank()) {
            return "";
        }

        String t = text;

        // 语义去噪
        t = CONTROL_CHARS.matcher(t).replaceAll("");
        t = IMAGE_FILENAME_LINE.matcher(t).replaceAll("");
        t = IMAGE_URL.matcher(t).replaceAll("");
        t = FILE_URL.matcher(t).replaceAll("");
        t = SEPARATOR_LINE.matcher(t).replaceAll("");

        // 格式规范化
        t = t.replace("\r\n", "\n").replace("\r", "\n");
        t = t.replaceAll("(?m)[ \t]+$", "");
        t = t.replaceAll("\\n{3,}", "\n\n");

        return t.strip();
    }
}

最佳实践

1. 使用流式处理大文件

// 使用 TikaInputStream 处理大文件
import org.apache.tika.io.TikaInputStream;

TikaInputStream tis = TikaInputStream.of(file.toPath());
parser.parse(tis, handler, metadata, context);

2. 设置合理的超时

import org.apache.tika.parser.ParseContext;

ParseContext context = new ParseContext();
context.set("parseMax.timeout", "300000"); // 5 分钟超时

3. 处理编码问题

// 对于纯文本文件，指定编码
Metadata metadata = new Metadata();
metadata.set(Metadata.CONTENT_TYPE, "text/plain; charset=UTF-8");

InputStreamReader reader = new InputStreamReader(
    file.getInputStream(), StandardCharsets.UTF_8);

4. 并行解析多个文件

@Async
public CompletableFuture<List<String>> parseDocuments(List<MultipartFile> files) {
    return CompletableFuture.supplyAsync(() ->
        files.parallelStream()
            .map(file -> {
                try {
                    return parseContent(file);
                } catch (Exception e) {
                    return "";
                }
            })
            .collect(Collectors.toList())
    );
}

支持的文件类型一览

类别	格式
文档	PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, ODF, RTF, TXT
网页	HTML, XHTML, XML
邮件	MIME, EML, PST, OST
图片	JPEG, PNG, GIF, TIFF, BMP, WebP
归档	ZIP, TAR, GZIP, BZIP2, 7Z
音频	MP3, WAV, FLAC, OGG
视频	MP4, AVI, MOV, WMV, FLV
设计	PSD, AI, Sketch

性能优化建议

使用 AutoDetectParser 自动检测：智能选择解析器
禁用不需要的解析器：减少启动时间和内存占用
设置 MAX_TEXT_LENGTH：防止无限提取
使用流式处理：避免一次性加载整个文件到内存
禁用嵌入资源提取：如不需要图片和附件

总结

Apache Tika 是 Java 项目中文档解析的首选工具，它提供了：

统一的 API 来处理多种文档格式
自动检测文件类型
丰富的元数据提取能力
可配置的解析行为
良好的扩展性

通过本指南，你应该能够使用 Tika 构建文档解析服务，实现简历解析、知识库构建、文档检索等功能。

MapStruct使用指南

Thu, 16 Apr 2026 00:00:00 +0000

什么是MapStruct？

MapStruct 是一个 Java 注解处理器，用于生成类型安全、高性能的对象映射代码。与传统的反射式映射库（如 BeanUtils、ModelMapper）不同，MapStruct 在编译时生成映射代码，不使用反射，因此具有以下优势：

编译时类型安全：编译期即可发现映射错误
高性能：生成的代码是直接的对象赋值，没有反射开销
易于调试：生成的代码可直接查看和调试
清晰的映射逻辑：通过注解声明式定义映射规则

项目集成

Maven 依赖

<properties>
    <mapstruct.version>1.6.3</mapstruct.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.mapstruct</groupId>
        <artifactId>mapstruct</artifactId>
        <version>${mapstruct.version}</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.13.0</version>
            <configuration>
                <source>21</source>
                <target>21</target>
                <annotationProcessorPaths>
                    <!-- Lombok 必须在 MapStruct 之前 -->
                    <path>
                        <groupId>org.projectlombok</groupId>
                        <artifactId>lombok</artifactId>
                        <version>1.18.36</version>
                    </path>
                    <path>
                        <groupId>org.mapstruct</groupId>
                        <artifactId>mapstruct-processor</artifactId>
                        <version>${mapstruct.version}</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

注意：如果使用 Lombok，必须确保 Lombok 在 annotationProcessorPaths 中的顺序早于 MapStruct。

基础使用

定义 Mapper 接口

@Mapper(componentModel = "spring")
public interface ResumeMapper {

    @Mapping(target = "contentScore", source = "contentScore", qualifiedByName = "nullToZero")
    ResumeAnalysisResponse.ScoreDetail toScoreDetail(ResumeAnalysisEntity entity);

    @Named("nullToZero")
    default int nullToZero(Integer value) {
        return value != null ? value : 0;
    }
}

Spring 集成

通过设置 componentModel = "spring"，MapStruct 会将生成的实现类注册为 Spring Bean，可以直接注入使用：

@Service
@RequiredArgsConstructor
public class ResumeService {

    private final ResumeMapper resumeMapper;

    public ResumeAnalysisResponse analyzeResume(ResumeAnalysisEntity entity) {
        // 使用 Mapper 进行转换
        ResumeAnalysisResponse.ScoreDetail scoreDetail =
            resumeMapper.toScoreDetail(entity);
        return new ResumeAnalysisResponse(
            entity.getOverallScore(),
            scoreDetail,
            entity.getSummary(),
            // ... 其他字段
        );
    }
}

常用注解详解

@Mapper

属性	说明
`componentModel`	设置为 “spring” 则生成 Spring Bean；设置为 “cdi” 则生成 CDI Bean
`unmappedTargetPolicy`	配置未映射目标字段的处理策略，如 `IGNORE`（忽略）、`WARN`（警告）、`ERROR`（报错）
`nullValuePropertyMappingStrategy`	null 值的映射策略

@Mapping

@Mapping(
    target = "userName",           // 目标字段
    source = "username",            // 源字段
    qualifiedByName = "toUpperCase" // 使用自定义转换方法
)
UserDTO toUserDTO(User user);

@MappingTarget

用于更新已有对象，而不是创建新对象：

@Mapper(componentModel = "spring")
public interface UserMapper {

    // 将 source 的值更新到 target 中
    @MappingTarget
    void updateUserFromDto(UserDTO dto, @MappingTarget User entity);
}

`1`	`userMapper.updateUserFromDto(dto, existingUser);`

进阶用法

自定义类型转换

@Mapper(componentModel = "spring")
public interface OrderMapper {

    // 使用 expression 进行复杂转换
    @Mapping(target = "orderDate",
             expression = "java(java.time.LocalDateTime.now())")
    OrderDTO toDTO(Order order);

    // 枚举转换
    @Mapping(target = "status", source = "status", dateFormat = "yyyy-MM-dd")
    Order toEntity(OrderDTO dto);
}

集合映射

MapStruct 支持自动集合映射：

@Mapper(componentModel = "spring")
public interface ListMapper {

    // 自动将 List<User> 转换为 List<UserDTO>
    List<UserDTO> userListToDtoList(List<User> users);

    // Map 映射
    Map<String, UserDTO> mapToDtoMap(Map<String, User> map);
}

嵌套 Bean 映射

@Mapper(componentModel = "spring")
public interface StudentMapper {

    // 自动处理嵌套的 Address 对象
    @Mapping(target = "address.city", source = "addr.city")
    @Mapping(target = "address.street", source = "addr.street")
    StudentDTO toDTO(Student student);
}

多个源对象映射

@Mapper(componentModel = "spring")
public interface OrderMapper {

    // 从两个源对象映射到目标对象
    @Mapping(target = "customerName", source = "customer.name")
    @Mapping(target = "productName", source = "product.name")
    OrderDTO toDTO(Customer customer, Product product);
}

项目实战案例

在实际项目中，MapStruct 常用于以下场景：

1. Entity 与 DTO 转换

// 实体类 -> DTO
@Mapper(componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.IGNORE)
public interface ResumeMapper {

    @Mapping(target = "contentScore", source = "contentScore", qualifiedByName = "nullToZero")
    @Mapping(target = "structureScore", source = "structureScore", qualifiedByName = "nullToZero")
    @Mapping(target = "skillMatchScore", source = "skillMatchScore", qualifiedByName = "nullToZero")
    @Mapping(target = "expressionScore", source = "expressionScore", qualifiedByName = "nullToZero")
    @Mapping(target = "projectScore", source = "projectScore", qualifiedByName = "nullToZero")
    ResumeAnalysisResponse.ScoreDetail toScoreDetail(ResumeAnalysisEntity entity);

    @Named("nullToZero")
    default int nullToZero(Integer value) {
        return value != null ? value : 0;
    }
}

2. 请求/响应对象转换

@Mapper(componentModel = "spring")
public interface UserMapper {

    UserResponse toResponse(User user);

    User toEntity(UserCreateRequest request);

    @MappingTarget
    void updateFromRequest(UserUpdateRequest request, @MappingTarget User user);
}

最佳实践

始终指定 unmappedTargetPolicy = ReportingPolicy.IGNORE：避免因字段不匹配导致的编译警告
使用 @Named 注解自定义转换方法：使代码更清晰
避免在 Mapper 中写复杂业务逻辑：Mapper 只做对象映射，业务逻辑应在 Service 层处理
合理拆分 Mapper：按模块或功能划分，不要把所有映射写在一个 Mapper 里
使用 @MapperConfig 共享配置：多个 Mapper 共用同一配置时使用

@MapperConfig(
    componentModel = "spring",
    unmappedTargetPolicy = ReportingPolicy.IGNORE
)
public interface DefaultMapperConfig {
}

性能对比

映射方式	性能	类型安全	调试难度
MapStruct	高	编译期检查	简单
BeanUtils	低（反射）	运行时检查	困难
ModelMapper	低（反射）	运行时检查	困难
手写转换	高	编译期检查	简单

总结

MapStruct 是 Java 项目中进行对象映射的最佳选择，它提供了：

编译时类型安全
高性能的代码生成
清晰的映射规则声明
良好的 Spring 集成

通过本指南，你应该能够快速上手 MapStruct，并在项目中优雅地处理 Entity 与 DTO 之间的转换。

Java_Go开发者ai应用开发agent学习路线

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

前言

AI 时代，Java/后端开发者的机会在哪里？工程化落地。

大模型本身是概率性的"黑盒"，但把它变成稳定、可观测、可扩展的生产级服务，恰恰是 Java/Go 工程师的主场——高并发架构、数据库优化、系统稳定性治理，这些能力可以直接复用。

学习建议：按顺序推进，每个阶段都有对应的详细文章。不要跳过阶段零——思维校准是后面所有技术学习的基础。

一、项目介绍

这是一个基于大语言模型的智能面试辅助平台，旨在帮助求职者提升面试能力。系统提供三大核心功能：

智能简历分析：上传简历后，AI 自动进行多维度评分并给出改进建议
模拟面试系统：基于简历内容生成个性化面试题，支持实时问答和答案评估
RAG 知识库问答：上传技术文档构建私有知识库，支持向量检索增强的智能问答

开源地址：https://github.com/Snailclimb/interview-guide

1.1 系统架构

┌─────────────────────────────────────────────────────────────┐
│                      前端展示层 (React)                      │
├─────────────────────────────────────────────────────────────┤
│                      后端服务层 (Spring Boot)                  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │ Resume Svc  │  │Interview Svc│  │Knowledge Svc│        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
│  ┌─────────────────────────────────────────────────┐        │
│  │         AI 集成层 (Spring AI + 通义千问)         │        │
│  └─────────────────────────────────────────────────┘        │
│  ┌─────────────────────────────────────────────────┐        │
│  │      异步处理层 (Redis Stream)                   │        │
│  └─────────────────────────────────────────────────┘        │
├─────────────────────────────────────────────────────────────┤
│                      数据存储层                              │
│  PostgreSQL+pgvector  │  Redis  │  RustFS/MinIO         │
└─────────────────────────────────────────────────────────────┘

1.2 技术栈概览

后端技术：

技术	版本	说明
Spring Boot	4.0	应用框架
Java	21	开发语言
Spring AI	2.0	AI 集成框架
PostgreSQL + pgvector	14+	关系数据库 + 向量存储
Redis	6+	缓存 + 消息队列
Apache Tika	2.9.2	文档解析
MapStruct	1.6.3	对象映射

二、学习路线总览

阶段总览表

阶段	主题	详细文档	核心产出
零	认知校准	大模型核心概念详解	思维从"确定性"转向"概率性"
一	大模型核心概念	大模型核心概念详解	掌握 Token/上下文窗口/Prompt
二	大模型对接	SpringAi实战指南_大模型集成_流式输出	Spring AI / LangChain4j，流式输出
三	Prompt 工程	大模型核心概念详解	结构化 Prompt，CoT思维链
四	RAG + 知识图谱	RAG知识库实战	文档 ETL，向量检索，GraphRAG
五	Agent 核心机制	AI_Agent核心机制_ReAct_MultiAgent_记忆系统	ReAct，Tool Calling，记忆机制
六	工程化框架	工程化与生产落地	异步处理，限流，成本控制
七	项目实战	本项目 InterviewGuide	智能面试平台完整实现

学习时间规划

按每天 3~6 小时投入估算：

阶段	建议时间	说明
阶段零~二	2~3 周	打基础，不要跳过
阶段三~四	3~4 周	核心能力，需动手实践
阶段五~六	2~3 周	工程化，复用后端经验
阶段七	2~4 周	项目实战，巩固所学

三、阶段零：认知校准

3.1 思维校准

认知转变：

认知	说明
确定性 → 概率性	LLM 是概率预测机器，相同输入可能产生不同输出
工程应对	模型输出进入业务逻辑前，必须经过校验、重试或降级兜底
Java 开发者定位	工程化落地，把模型能力变成稳定的生产级服务

3.2 常见踩坑与解决方案

详细内容见：大模型核心概念详解

坑	表现	解决方案
LLM 响应慢卡死 Tomcat	服务雪崩	SseEmitter/WebFlux + 异步线程池
@Transactional 内调 LLM	连接池耗尽	LLM 调用游离事务外
Agent 死循环导致账单爆炸	成本失控	Token 消耗监控 + 阈值告警
LLM 输出不符合事实	幻觉严重	RAG + 知识图谱双引擎校验
JSON 解析失败率高	格式错误	低温 + Strict Mode + Retry 闭环

四、阶段一：大模型核心概念

详细内容：大模型核心概念详解

4.1 Token 与上下文窗口

Token：模型处理文本的基本单位（英文 3~~4 字符/Token，中文 1~~2 汉字/Token）
上下文窗口：LLM 的"工作记忆"，决定模型可以处理的文本量
Token 预算：可用输入 = window × 0.9 - max_output_tokens - 安全边际

4.2 解码参数

参数	工程建议	场景
Temperature	0~~0.3（结构化）/ 0.4~~0.8（分析）	控制输出稳定性
Top-p	低温 + Top-p(0.9)	控制生成多样性
Max Tokens	硬上限	需防截断风险

4.3 Prompt 工程基础

要素	说明
CoT（思维链）	一步一步思考，展示推理过程，对抗幻觉
Few-Shot	提供 1~3 个示例，让模型理解输入输出模式
任务分解	复杂任务拆成子任务逐一完成，再汇总

4.4 结构化输出

方案	特点
JSON Schema 约束	实现简单、跨供应商
Function Calling	结构化更强，供应商差异大
Structured Outputs (Strict)	受限解码，格式错误率趋近 0

五、阶段二：大模型对接

详细内容：SpringAi实战指南_大模型集成_流式输出

5.1 框架选型

框架	特点	适用场景
Spring AI	与 Spring 生态无缝集成	企业内部系统
LangChain4j	RAG 和 Agent 场景功能全面	知识库问答

防腐层设计：AI 框架迭代快，业务代码绝不能直接耦合框架 API，需定义自己的领域接口隔离。

5.2 OpenAI 协议兼容性

主流模型均兼容 OpenAI 格式：

模型	Base URL	特点
DeepSeek	api.deepseek.com	成本低，中文优化
通义千问	dashscope.aliyuncs.com	国内合规，稳定
Ollama	localhost:11434	本地部署，数据安全

5.3 流式输出 SSE

详细内容见：Spring AI实战指南 - 流式输出

@GetMapping(value = "/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());
}

六、阶段三：Prompt 工程

详细内容：大模型核心概念详解

6.1 CoT 思维链详解

范式	适用场景
普通 CoT	数学推导、逻辑分析
自治 CoT	模型自我验证推理路径
工具增强 CoT	需要调用工具获取中间结果

6.2 Prompt 工程化管理

要点	说明
外置化存储	Prompt 不应硬编码，使用 .st 文件存储
配置中心热更新	接入 Nacos/Apollo
变量注入安全	用户输入需清洗，防 Prompt Injection

6.3 结构化输出与反思闭环

要点	Java 实现
强类型映射	Java 14+ Record
JSR-380 校验	@NotNull、@Size 等注解
Retry Loop	设定最大重试次数（如 3 次）

七、阶段四：RAG + 知识图谱

详细内容：RAG知识库实战

7.1 RAG 核心概念

┌─────────────────────────────────────────────────────────────┐
│                    RAG 系统                                   │
├──────────────────────────┬──────────────────────────────────┤
│     📥 索引阶段           │      🔍 检索阶段                  │
│   文档 → 分块 → 向量化    │   查询 → 检索 → 生成              │
└──────────────────────────┴──────────────────────────────────┘

7.2 技术选型

组件	选型	理由
向量数据库	PostgreSQL + pgvector	一套数据库，运维简单
索引算法	HNSW	毫秒级检索，百万级够用
Embedding	text-embedding-v3	1024 维，中文优化

7.3 关键知识点

概念	说明
混合检索	向量检索 + BM25 关键词检索
Rerank	Cross-Encoder 精排，提升顶部结果准确性
语义缓存	Redis 向量检索命中缓存，降成本 + 降延迟

八、阶段五：Agent 核心机制

详细内容：AI_Agent核心机制_ReAct_MultiAgent_记忆系统

8.1 Agent 调度范式

范式	说明	适用场景
ReAct	Think → Act → Observe 循环，动态纠错	工具调用、复杂推理
Plan-and-Execute	先全局规划再逐步执行	长任务、多步骤
Reflection	自我纠错闭环	代码生成、内容创作

8.2 Tool Calling

`1`	`用户问题 → LLM 判断需要调用工具 → 返回工具名称+参数 → 执行工具 → 返回结果 → LLM 生成回答`

8.3 记忆系统

类型	说明	存储
短期记忆	Redis 缓存对话历史	Redis
长期记忆	用户偏好、历史知识	Neo4j / 向量库

8.4 MCP 协议

协议	说明
MCP	Model Context Protocol，统一工具调用接口
ACP	Agent Communication Protocol，打通 Agent 与 IDE 集成

九、阶段六：工程化框架

详细内容：工程化与生产落地

9.1 Redis Stream 异步处理

上传请求 → 保存文件 → 发送消息到 Stream → 立即返回
                          ↓
                  Consumer 消费消息
                          ↓
                执行分析/向量化任务
                          ↓
                  更新数据库状态

状态流转：PENDING → PROCESSING → COMPLETED / FAILED

9.2 事务安全

要点	说明
事务反模式	禁止在 @Transactional 方法内调用 LLM
事务极小化	LLM 调用游离在事务外，先校验再落盘

9.3 分布式限流

维度	说明
用户维度	限制单个用户
IP 维度	限制单个 IP
接口维度	限制单个接口

9.4 FinOps 成本控制

要点	工具
Token 计量	Micrometer + Prometheus
成本预警	单日 Token 消耗阈值告警
语义缓存	Redis 缓存，降成本 30~50%

十、阶段七：项目实战

10.1 智能面试平台

基于大语言模型的智能面试辅助平台，提供三大核心功能：

智能简历分析：多维度评分 + 改进建议
模拟面试系统：个性化面试题 + 实时问答
RAG 知识库问答：私有知识库 + 向量检索

10.2 核心技术点

功能	技术方案
简历解析	Apache Tika 多格式解析
AI 分析	Spring AI + 结构化输出
向量检索	PostgreSQL + pgvector
流式输出	SSE + 虚拟线程
异步处理	Redis Stream
限流	Redis + Lua

十一、推荐模型选择

场景	推荐模型	说明
开发调试	DeepSeek / 通义千问	成本低，中文友好
生产环境	GPT / Claude / Gemini	稳定性、能力最均衡
数据安全	本地部署 Ollama + Qwen	内网环境，数据不出域

十二、延伸阅读

文档	内容
大模型核心概念详解	Token、上下文窗口、Prompt工程、结构化输出
SpringAi实战指南_大模型集成_流式输出	ChatClient、流式SSE、Function Calling
RAG知识库实战	向量检索、混合检索、语义缓存
AI_Agent核心机制_ReAct_MultiAgent_记忆系统	ReAct、Multi-Agent、记忆系统、MCP
工程化与生产落地	异步处理、限流、FinOps、安全防护

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 虚拟线程轻松应对高并发场景