Java全栈开发者的一天 — AI功能交付纪实

// 文档实体类 — 对应 documents 表 package com.smartqa.model; import lombok.Data; import java.time.LocalDateTime; @Data public class Document { private Long id; private String title; private String content; private String category; private float[] embedding; // 1536维向量 private String filePath; private String status; private LocalDateTime createdAt; } // ──────────────────────────── // ChatHistory.java — 问答历史 // ──────────────────────────── @Data public class ChatHistory { private Long id; private String userId; private String question; private String answer; private String sources; // JSONB → 存为String，前端JSON.parse private Integer tokensUsed; private Integer responseMs; private LocalDateTime createdAt; }

<!-- pgvector语义搜索：按余弦距离排序找Top-K相关文档 --> <select id="searchByVector" resultType="Document"> SELECT id, title, content, category, 1 - (embedding <=> #{queryVector,jdbcType=OTHER}::vector) AS relevance FROM documents WHERE status = 'ready' AND embedding IS NOT NULL ORDER BY embedding <=> #{queryVector,jdbcType=OTHER}::vector LIMIT #{topK} </select> <!-- 插入文档（含向量） --> <insert id="insertWithEmbedding" parameterType="Document"> INSERT INTO documents (title, content, category, embedding, file_path, status) VALUES (#{title}, #{content}, #{category}, #{embedding,jdbcType=OTHER}::vector, #{filePath}, #{status}) </insert>

// 项目分层架构说明 // ──────────────── // controller/ → 接口层（接收请求） // dto/ → 数据传输对象（校验） // service/ → 业务逻辑层（RAG核心） // mapper/ → 数据访问层（MyBatis） // model/ → 实体类 // config/ → 基础设施（异步/CORS/连接池） // // 请求流程: // Client → ChatController → ChatRequest (@Valid校验) → RagService → DocumentMapper (读写DB) → ChatResponse → Client

<!-- Spring Boot 3.x + JDK 21 --> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.2.5</version> </parent> <dependencies> <!-- Web + REST --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- 参数校验 @Valid --> <dependency> <artifactId>spring-boot-starter-validation</artifactId> </dependency> <!-- MyBatis --> <dependency> <groupId>org.mybatis.spring.boot</groupId> <artifactId>mybatis-spring-boot-starter</artifactId> <version>3.0.3</version> </dependency> <!-- PostgreSQL + pgvector驱动 --> <dependency> <groupId>org.postgresql</groupId> <artifactId>postgresql</artifactId> </dependency> <!-- WebClient（调LLM API） --> <dependency> <artifactId>spring-boot-starter-webflux</artifactId> </dependency> <!-- Redis --> <dependency> <artifactId>spring-boot-starter-data-redis</artifactId> </dependency> </dependencies>

server: port: 8080 spring: datasource: url: jdbc:postgresql://localhost:5432/smartqa username: ${DB_USER:postgres} password: ${DB_PASS:postgres} driver-class-name: org.postgresql.Driver data: redis: host: ${REDIS_HOST:localhost} port: 6379 mybatis: mapper-locations: classpath:mapper/*.xml configuration: map-underscore-to-camel-case: true # 自定义配置 llm: api-key: ${OPENAI_API_KEY:} base-url: https://api.openai.com/v1 embedding-model: text-embedding-3-small chat-model: gpt-4o-mini

package com.smartqa.controller; import com.smartqa.dto.ChatRequest; import com.smartqa.dto.ChatResponse; import com.smartqa.service.RagService; import jakarta.validation.Valid; import org.springframework.web.bind.annotation.*; @RestController @RequestMapping("/api/chat") public class ChatController { private final RagService ragService; @PostMapping("/ask") public ChatResponse ask(@Valid @RequestBody ChatRequest req) { // 同步问答：等LLM完整生成后返回 return ragService.ragChat(req.getQuestion(), 5); } @GetMapping("/stream") public SseEmitter chatStream(@RequestParam String question) { // SSE流式：逐token推送 SseEmitter emitter = new SseEmitter(120_000L); // 2分钟超时 ragService.ragChatStream(question, emitter); return emitter; } } // ──────────────────────────── // ChatRequest.java — DTO + 校验 // ──────────────────────────── @Data public class ChatRequest { @NotBlank(message = "问题不能为空") @Size(max = 500, message = "问题不能超过500字") private String question; @Size(max = 100) private String userId = "anonymous"; }

// Embedding服务：调用OpenAI API把文本转成1536维向量 package com.smartqa.service; import org.springframework.beans.factory.annotation.Value; import org.springframework.http.MediaType; import org.springframework.stereotype.Service; import org.springframework.web.reactive.function.client.WebClient; @Service public class EmbeddingService { private final WebClient webClient; @Value("${llm.embedding-model}") private String embeddingModel; public float[] getEmbedding(String text) { // 调用 OpenAI Embedding API Map<String, Object> request = Map.of( "model", embeddingModel, "input", text ); EmbeddingResponse resp = webClient.post() .uri("/embeddings") .contentType(MediaType.APPLICATION_JSON) .bodyValue(request) .retrieve() .bodyToMono(EmbeddingResponse.class) .block(); // 同步阻塞等待结果 return resp.getData().get(0).getEmbedding(); } }

// RAG核心服务 — 检索增强生成 package com.smartqa.service; @Service public class RagService { private final EmbeddingService embeddingService; private final LlmService llmService; private final DocumentMapper documentMapper; /** * RAG问答主流程: * 1. 问题向量化 * 2. pgvector搜索相关文档 * 3. 构造prompt * 4. 调LLM生成答案 */ public ChatResponse ragChat(String question, int topK) { long start = System.currentTimeMillis(); // Step 1: 问题向量化 float[] queryVec = embeddingService.getEmbedding(question); String vecStr = vectorToString(queryVec); // [0.01, -0.03, ...] // Step 2: pgvector语义搜索（Top-K相关文档） List<Document> docs = documentMapper.searchByVector(vecStr, topK); if (docs.isEmpty()) { return ChatResponse.notFound("文档库中没有找到相关内容"); } // Step 3: 构造Prompt（把文档内容拼进prompt） String context = docs.stream() .map(d -> "【文档" + d.getId() + "】" + d.getContent()) .collect(Collectors.joining("\n\n")); String prompt = """ 你是公司内部客服助手。请基于以下文档回答问题。 如果文档中没有相关信息，请说"未找到相关资料"。 参考文档： %s 问题：%s """.formatted(context, question); // Step 4: 调LLM生成答案 String answer = llmService.generate(prompt); return ChatResponse.builder() .answer(answer) .sources(docs.stream().map(Document::toSource).toList()) .responseMs((int)(System.currentTimeMillis() - start)) .build(); } /** SSE流式版本 — 逐token推送 */ @Async("ragExecutor") public void ragChatStream(String question, SseEmitter emitter) { try { // 同样的RAG流程，但LLM生成时用流式API float[] queryVec = embeddingService.getEmbedding(question); List<Document> docs = documentMapper.searchByVector( vectorToString(queryVec), 5); String prompt = buildPrompt(docs, question); // 逐chunk推送 llmService.generateStream(prompt, chunk -> { emitter.send(SseEmitter.event() .data(Map.of("token", chunk))); }); // 推送引用来源 emitter.send(SseEmitter.event() .data(Map.of("sources", toSourceList(docs)))); emitter.send(SseEmitter.event().data(Map.of("done", true))); emitter.complete(); } catch (Exception e) { emitter.completeWithError(e); } } }

// LLM服务：调用OpenAI Chat Completions API @Service public class LlmService { private final WebClient webClient; @Value("${llm.chat-model}") private String chatModel; /** 同步生成 */ public String generate(String prompt) { Map<String, Object> request = Map.of( "model", chatModel, "messages", List.of( Map.of("role", "system", "content", "你是客服助手"), Map.of("role", "user", "content", prompt) ), "temperature", 0.3 ); return webClient.post() .uri("/chat/completions") .bodyValue(request) .retrieve() .bodyToMono(ChatCompletionResponse.class) .block() .getChoices().get(0) .getMessage().getContent(); } /** 流式生成 — 逐chunk回调 */ public void generateStream(String prompt, Consumer<String> onChunk) { Map<String, Object> request = Map.of( "model", chatModel, "messages", List.of( Map.of("role", "user", "content", prompt) ), "stream", true // 关键：开启流式 ); webClient.post() .uri("/chat/completions") .bodyValue(request) .retrieve() .bodyToFlux(String.class) // Flux<String> = 响应式流 .doOnNext(onChunk) // 每个chunk回调 .blockLast(); // 阻塞直到完成 } }

// 异步线程池配置 — 控制并发数，避免OOM @Configuration @EnableAsync public class AsyncConfig { /** RAG专用线程池 — 处理文档embedding */ @Bean("ragExecutor") public ThreadPoolTaskExecutor ragExecutor() { ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor(); executor.setCorePoolSize(4); // 核心线程：CPU核数 executor.setMaxPoolSize(8); // 最大线程 executor.setQueueCapacity(100); // 等待队列 executor.setThreadNamePrefix("rag-"); executor.setRejectedExecutionHandler( new ThreadPoolExecutor.CallerRunsPolicy()); // 队列满时由调用线程执行 executor.initialize(); return executor; } }

// 文档服务：异步处理文档导入 @Service public class DocumentService { private final DocumentMapper documentMapper; private final EmbeddingService embeddingService; /** 上传接口：保存文件后立即返回，异步处理embedding */ public Map<String, Object> uploadDocument(MultipartFile file, String category) { // 1. 保存文件到磁盘 String filePath = saveFile(file); // 2. 插入DB，状态为pending Document doc = new Document(); doc.setTitle(file.getOriginalFilename()); doc.setContent(""); // 还没提取 doc.setCategory(category); doc.setFilePath(filePath); doc.setStatus("pending"); documentMapper.insert(doc); // 3. 异步处理（不阻塞当前请求） processDocumentAsync(doc.getId()); // 4. 立即返回 — 用户不用等 return Map.of( "docId", doc.getId(), "status", "pending", "message", "文档已上传，正在处理中" ); } /** 异步处理：文本提取 → embedding → 入库 */ @Async("ragExecutor") public void processDocumentAsync(Long docId) { Document doc = documentMapper.findById(docId); try { // 更新状态：处理中 documentMapper.updateStatus(docId, "processing"); // Step 1: 文本提取（PDF/Word → 纯文本） String content = extractText(doc.getFilePath()); // Step 2: 生成embedding向量 float[] embedding = embeddingService.getEmbedding(content); // Step 3: 写入数据库（更新content + embedding） documentMapper.updateContentAndEmbedding( docId, content, vectorToString(embedding)); documentMapper.updateStatus(docId, "ready"); } catch (Exception e) { documentMapper.updateStatus(docId, "failed"); log.error("文档处理失败 docId={}", docId, e); } } }

<template> <div class="chat-container"> <div class="messages" ref="msgList"> <div v-for="msg in messages" :key="msg.id" :class="['msg', msg.role]"> <div class="bubble">{{ msg.content }}</div> <!-- 引用来源折叠 --> <details v-if="msg.sources?.length"> <summary>📚 引用来源 ({{ msg.sources.length }})</summary> <div v-for="s in msg.sources" :key="s.doc_id"> 📄 {{ s.title }} ({{ (s.relevance*100).toFixed(0) }}%) </div> </details> </div> </div> <div class="input-area"> <input v-model="input" @keyup.enter="send" placeholder="输入你的问题..." /> <button @click="send" :disabled="loading">发送</button> </div> </div> </template> <script setup> import { ref, nextTick } from 'vue' const messages = ref([]) const input = ref('') const loading = ref(false) async function send() { const question = input.value.trim() if (!question) return // 添加用户消息 messages.value.push({ id: Date.now(), role: 'user', content: question }) input.value = '' loading.value = true // 用SSE流式接收（EventSource） const evtSrc = new EventSource( `/api/chat/stream?question=${question}` ) const aiMsg = { id: Date.now()+1, role: 'ai', content: '', sources: [] } messages.value.push(aiMsg) evtSrc.onmessage = (e) => { const data = JSON.parse(e.data) if (data.token) { // 打字机效果：逐字追加 aiMsg.content += data.token } if (data.sources) { aiMsg.sources = data.sources } if (data.done) { evtSrc.close() loading.value = false } } } </script> <style scoped> /* 聊天气泡样式省略... */ </style>

# Dockerfile — Spring Boot后端镜像 # 多阶段构建：先Maven打包，再瘦身运行 # Stage 1: 构建 FROM maven:3.9-eclipse-temurin-21 AS builder WORKDIR /build # 先复制pom.xml，利用Docker缓存层 COPY pom.xml . RUN mvn dependency:go-offline # 复制源码并打包 COPY src/ ./src/ RUN mvn package -DskipTests # Stage 2: 运行（JRE精简镜像） FROM eclipse-temurin:21-jre-alpine WORKDIR /app COPY --from=builder /build/target/*.jar app.jar # 暴露端口 EXPOSE 8080 # JVM参数 + 启动命令 CMD ["java", \ "-XX:+UseG1GC", \ "-XX:MaxRAMPercentage=75.0", \ "-jar", "app.jar"]