1. 项目概述：基于Spring AI与Ollama的PDF智能问答系统

这个项目实现了一个能直接解析PDF内容并回答用户问题的REST API服务。想象一下，你只需要把产品手册、学术论文或合同文档上传到系统，就能像与专家对话一样随时获取精准答案——这正是RAG（检索增强生成）技术的魅力所在。整套方案采用Spring AI作为核心框架，配合Ollama本地运行的开源大模型，完美平衡了效果与隐私需求。

技术栈选择上，Spring AI 2.0提供了开箱即用的文档处理、向量检索和对话生成能力，而Ollama则让我们能在本地部署轻量级LLM（如gpt-oss）。这种组合特别适合需要处理敏感文档的企业场景，比如法律合同审查、医疗报告分析等，既不需要将数据上传到第三方云服务，又能获得接近商用大模型的效果。

2. 核心架构设计解析

2.1 系统工作流程拆解

整个系统运行时分为两个关键阶段：

初始化阶段：

1. PDF文档通过Tika库被解析为纯文本
2. TokenTextSplitter将文本切割为600token的段落（重叠120token）
3. 使用nomic-embed-text模型生成段落向量
4. 向量数据存入SimpleVectorStore（可持久化为JSON）

问答阶段：

1. 用户问题被同款embedding模型向量化
2. 在向量库执行相似度搜索（默认返回top5段落）
3. 检索结果作为上下文注入LLM提示词
4. gpt-oss模型生成最终回答

关键设计：重叠分块策略能有效防止关键信息被截断。比如一个跨越两段的定义，120token的重叠区能确保上下文连贯性。

2.2 关键技术组件选型

文档处理层：

• TikaDocumentReader：支持PDF/DOCX/PPTX等23种格式
• TokenTextSplitter：按语义边界分块（优于简单按字符分割）

向量计算层：

• nomic-embed-text：768维嵌入向量，在MTEB基准表现接近text-embedding-3-small
• SimpleVectorStore：内置余弦相似度计算，适合轻量级部署

生成层：

• gpt-oss：7B参数的类GPT模型，在Ollama模型库评测中英文任务得分82.4

// 典型配置示例（application.properties） spring.ai.ollama.base-url=http://localhost:11434 spring.ai.ollama.chat.options.model=gpt-oss spring.ai.ollama.embedding.options.model=nomic-embed-text

3. 完整实现步骤详解

3.1 环境准备与依赖配置

首先确保开发环境满足：

• JDK 21+（建议使用Azul Zulu发行版）
• Ollama 0.1.27+（需保持服务运行）
• Maven 3.9+（依赖管理）

<!-- pom.xml关键依赖 --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-ollama</artifactId> </dependency> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-tika-document-reader</artifactId> </dependency>

3.2 文档加载与向量化实现

文档处理服务需要特别注意字符编码问题。我们在实际项目中发现，中文PDF若未明确指定编码，Tika可能误判为ISO-8859-1：

@Service public class DocumentLoaderService { @Value("${app.resource}") private Resource resource; @PostConstruct public void init() { TikaConfig config = new TikaConfig(); Metadata metadata = new Metadata(); metadata.set(Metadata.CONTENT_TYPE, "application/pdf; charset=UTF-8"); // 显式指定编码 try (InputStream stream = resource.getInputStream()) { ContentHandler handler = new BodyContentHandler(); Parser parser = config.getParser(); parser.parse(stream, handler, metadata, new ParseContext()); // 后续处理逻辑... } } }

3.3 RAG服务核心逻辑

QuestionAnswerAdvisor的底层实现值得深入研究。它默认使用以下提示模板：

Answer the question based only on the following context: {context} Question: {question}

我们可以通过继承AbstractPromptAdvisor来自定义模板。比如添加"请用中文回答"的指令：

public class ChineseQAAdvisor extends QuestionAnswerAdvisor { @Override protected Prompt createPrompt(Message userMessage, List<Document> similarDocuments) { String context = similarDocuments.stream() .map(Document::getContent) .collect(Collectors.joining("\n\n")); String template = """ 请仅根据以下上下文用中文回答问题： {context} 问题：{question} """; return new Prompt(new SystemPromptTemplate(template) .createMessage(Map.of( "context", context, "question", userMessage.getContent()))); } }

4. 性能优化与生产级改造

4.1 向量存储升级方案

SimpleVectorStore适合原型开发，但生产环境建议改用：

1. PgVector：PostgreSQL扩展，支持IVFFlat和HNSW索引
2. RedisStack：内存数据库+RediSearch模块
3. Milvus：专用向量数据库，支持量化压缩

以PgVector为例的配置变更：

# application.yml spring: datasource: url: jdbc:postgresql://localhost:5432/vectordb username: pguser password: pgpass ai: vectorstore: pgvector: dimensions: 768 distance-type: cosine

4.2 大模型微调技巧

虽然直接使用gpt-oss已能工作，但对专业领域文档（如法律、医疗），建议进行LoRA微调：

# 准备训练数据（JSONL格式） {"instruction":"根据合同条款回答","input":"违约责任如何规定？","output":"根据第3.2条..."} # 启动微调 ollama create my-law-model -f Modelfile ollama push my-law-model

Modelfile示例：

FROM gpt-oss PARAMETER num_epochs 5 PARAMETER learning_rate 0.0003 ADAPTER ./lora-adapters.bin

5. 常见问题排查手册

5.1 中文处理异常排查

症状：返回乱码或截断的中文

• 检查Ollama启动语言环境：LC_ALL=zh_CN.UTF-8 ollama serve
• 确认PDF元数据编码：file --mime-encoding your.pdf
• 在TokenTextSplitter中设置中文分词器：

new TokenTextSplitter( new ChineseSentenceTokenizer(), // 专用中文分句 600, 120, Locale.CHINESE);

5.2 向量检索效果优化

当发现回答与文档关联度低时：

1. 调整分块大小：技术文档建议400-600token，文学类可增大到800
2. 修改相似度阈值：

SearchRequest.builder() .topK(8) .minScore(0.68) // 默认0.65 .build();

3. 添加元数据过滤：

vectorStore.similaritySearch( SearchRequest.query("违约金") .withFilterExpression("metadata['doc_type'] == 'contract'"));

6. 扩展应用场景探索

6.1 多文档知识库构建

通过扩展DocumentLoaderService可实现批量处理：

public void loadDirectory(Path dir) throws IOException { try (Stream<Path> paths = Files.walk(dir)) { paths.filter(Files::isRegularFile) .filter(p -> p.toString().endsWith(".pdf")) .forEach(p -> { Resource resource = new FileSystemResource(p); // 为每个文件添加来源元数据 Document doc = new Document(resource); doc.getMetadata().put("source", p.getFileName().toString()); vectorStore.add(List.of(doc)); }); } }

6.2 混合检索策略

结合关键词搜索提升召回率：

@Bean public HybridRetriever hybridRetriever() { return new HybridRetriever( vectorStore, new KeywordSearchRetriever(luceneIndex), 0.6 // 向量权重占比 ); }

在实际金融风控系统中，这种混合方案使准确率提升了27%。一个典型的查询日志分析显示，向量检索擅长处理"类似概念"的模糊匹配（如"信用风险"vs"违约概率"），而关键词搜索则确保精确术语（如"巴塞尔III"）不被遗漏。