package com.custom.webui.service.impl; import com.custom.webui.config.props.RagProperties; import com.custom.webui.dto.resp.OcrResultDTO; import com.custom.webui.dto.resp.RagChunk; import com.custom.webui.exception.BusinessException; import com.custom.webui.service.RagProxyService; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ObjectNode; import lombok.extern.slf4j.Slf4j; import org.springframework.beans.factory.annotation.Qualifier; import org.springframework.core.io.FileSystemResource; import org.springframework.http.HttpEntity; import org.springframework.http.HttpHeaders; import org.springframework.http.MediaType; import org.springframework.http.ResponseEntity; import org.springframework.stereotype.Service; import org.springframework.util.LinkedMultiValueMap; import org.springframework.util.MultiValueMap; import org.springframework.http.client.SimpleClientHttpRequestFactory; import org.springframework.web.client.RestTemplate; import java.nio.file.Files; import java.nio.file.Path; import java.util.ArrayList; import java.util.Collections; import java.util.List; /** * RAG 微服务代理实现:通过 HTTP 调用 Python FastAPI 服务。 * *

接口对应关系: *

 * POST /api/rag/ingest  (multipart) -> Python POST /api/rag/ingest
 * POST /api/rag/search  (json)      -> Python POST /api/rag/search
 * DELETE /api/rag/collection        -> Python DELETE /api/rag/collection/{name}
 * 
* *

降级策略:检索失败返回空列表而非抛异常。 * 理由:知识库是「增强」能力,它挂掉不应该让用户连话都聊不了。 * 而入库失败必须抛出 —— 用户明确点了「向量化」,静默失败会让人以为成功了。 */ @Slf4j @Service public class RagProxyServiceImpl implements RagProxyService { private final RagProperties ragProperties; private final RestTemplate restTemplate; private final ObjectMapper objectMapper; public RagProxyServiceImpl(RagProperties ragProperties, @Qualifier("ragRestTemplate") RestTemplate restTemplate, ObjectMapper objectMapper) { this.ragProperties = ragProperties; this.restTemplate = restTemplate; this.objectMapper = objectMapper; log.info("RAG 代理初始化 enabled={} baseUrl={}", ragProperties.isEnabled(), ragProperties.getBaseUrl()); } @Override public IngestResult ingest(Path filePath, String collectionName, Long userId) { if (!ragProperties.isEnabled()) { throw BusinessException.badRequest("RAG 功能未启用"); } if (filePath == null || !Files.exists(filePath)) { throw BusinessException.badRequest("待入库文件不存在: " + filePath); } // 用 multipart/form-data 传文件本体 + 集合名 + 用户 id MultiValueMap body = new LinkedMultiValueMap<>(); body.add("file", new FileSystemResource(filePath)); body.add("collection_name", collectionName); body.add("user_id", String.valueOf(userId)); HttpHeaders headers = new HttpHeaders(); headers.setContentType(MediaType.MULTIPART_FORM_DATA); String url = baseUrl() + "/api/rag/ingest"; try { ResponseEntity response = restTemplate.postForEntity( url, new HttpEntity<>(body, headers), String.class); JsonNode root = objectMapper.readTree(response.getBody()); JsonNode data = unwrapData(root); String returnedCollection = text(data, "collection_name", collectionName); int chunkCount = data.path("chunk_count").asInt(0); log.info("RAG 入库完成 collection={} chunks={}", returnedCollection, chunkCount); return new IngestResult(returnedCollection, chunkCount, "入库成功,共 " + chunkCount + " 个片段"); } catch (BusinessException e) { throw e; } catch (Exception e) { log.error("调用 RAG 入库接口失败 url={}", url, e); throw BusinessException.serverError( "调用 RAG 服务失败(" + url + ")。请确认 Python 服务已启动:" + "uvicorn main:app --host 0.0.0.0 --port 8000。原因: " + rootMessage(e)); } } @Override public List search(String query, List collectionNames, int topK) { if (!ragProperties.isEnabled() || collectionNames == null || collectionNames.isEmpty()) { return Collections.emptyList(); } if (query == null || query.isBlank()) { return Collections.emptyList(); } ObjectNode payload = objectMapper.createObjectNode(); payload.put("query", query); payload.put("top_k", topK > 0 ? topK : ragProperties.getDefaultTopK()); var array = payload.putArray("collection_names"); collectionNames.forEach(array::add); String url = baseUrl() + "/api/rag/search"; try { HttpHeaders headers = new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); ResponseEntity response = restTemplate.postForEntity( url, new HttpEntity<>(objectMapper.writeValueAsString(payload), headers), String.class); JsonNode root = objectMapper.readTree(response.getBody()); JsonNode data = unwrapData(root); JsonNode chunksNode = data.path("chunks"); List chunks = new ArrayList<>(); if (chunksNode.isArray()) { for (JsonNode node : chunksNode) { RagChunk chunk = new RagChunk(); chunk.setText(text(node, "text", "")); chunk.setFilename(text(node, "filename", "未知文档")); // 章节路径由 Python 分块时标注并存入向量元数据,这里必须一并取出, // 否则引用信息会退化成只有文件名,无法定位到文档的哪一节 chunk.setSection(text(node, "section", null)); chunk.setCollectionName(text(node, "collection_name", null)); chunk.setChunkIndex(node.path("chunk_index").isMissingNode() ? null : node.path("chunk_index").asInt()); if (node.hasNonNull("score")) { chunk.setScore(node.get("score").asDouble()); } // 过滤掉空片段,避免把无意义的空白拼进 prompt if (!chunk.getText().isBlank()) { chunks.add(chunk); } } } log.debug("RAG 检索完成 query={} collections={} 命中 {} 条", abbreviate(query, 50), collectionNames, chunks.size()); return chunks; } catch (Exception e) { // 降级:检索失败不阻断对话 log.warn("调用 RAG 检索接口失败,本次降级为纯对话 url={} err={}", url, rootMessage(e)); return Collections.emptyList(); } } @Override public String buildRagContext(List chunks) { if (chunks == null || chunks.isEmpty()) { return null; } StringBuilder sb = new StringBuilder(); int index = 1; int maxChars = ragProperties.getMaxContextChars(); for (RagChunk chunk : chunks) { // 用与前端完全一致的序号做前缀,让模型能引用 [1][2], // 用户在前端看到的「引用来源」列表也是同一套编号,两边可以对齐。 // 来源信息里带上章节(如果有),模型据此可以写出更精确的引用。 String source = chunk.getFilename() == null ? "未知文档" : chunk.getFilename(); if (chunk.getSection() != null && !chunk.getSection().isBlank()) { source = source + " · " + chunk.getSection(); } String header = "[" + index + "] 来源:" + source + "\n"; String body = chunk.getText(); // 总量控制:超出上限就停止追加,防止撑爆模型上下文窗口 if (sb.length() + header.length() + body.length() > maxChars) { int remaining = maxChars - sb.length() - header.length(); if (remaining > 200) { sb.append(header).append(body, 0, remaining).append("...\n\n"); index++; } log.debug("RAG 上下文达到字符上限 {},已截断", maxChars); break; } sb.append(header).append(body).append("\n\n"); index++; } return sb.isEmpty() ? null : sb.toString().trim(); } @Override public boolean deleteCollection(String collectionName) { if (!ragProperties.isEnabled() || collectionName == null || collectionName.isBlank()) { return false; } String url = baseUrl() + "/api/rag/collection/" + collectionName; try { restTemplate.delete(url); log.info("已删除向量集合 {}", collectionName); return true; } catch (Exception e) { log.warn("删除向量集合失败 collection={} err={}", collectionName, rootMessage(e)); return false; } } @Override public OcrResultDTO recognizeImage(Path imagePath) { if (!ragProperties.isEnabled()) { throw BusinessException.badRequest("RAG 功能未启用,无法使用图片识别"); } if (imagePath == null || !Files.exists(imagePath)) { throw BusinessException.badRequest("图片文件不存在: " + imagePath); } MultiValueMap body = new LinkedMultiValueMap<>(); body.add("file", new FileSystemResource(imagePath)); HttpHeaders headers = new HttpHeaders(); headers.setContentType(MediaType.MULTIPART_FORM_DATA); String url = baseUrl() + "/api/ocr/recognize"; try { // OCR 超时单独设置:RagRestTemplate 的读超时是按「向量检索」调的, // 首次 OCR 要加载 onnx 模型,可能明显更久 RestTemplate client = ocrRestTemplate(); ResponseEntity response = client.postForEntity( url, new HttpEntity<>(body, headers), String.class); JsonNode root = objectMapper.readTree(response.getBody()); JsonNode data = unwrapData(root); OcrResultDTO dto = new OcrResultDTO(); dto.setFilename(text(data, "filename", imagePath.getFileName().toString())); dto.setText(text(data, "text", "")); dto.setEngine(text(data, "engine", null)); dto.setImageWidth(data.path("image_width").isMissingNode() ? null : data.path("image_width").asInt()); dto.setImageHeight(data.path("image_height").isMissingNode() ? null : data.path("image_height").asInt()); dto.setCharCount(data.path("char_count").asInt(dto.getText() == null ? 0 : dto.getText().length())); dto.setElapsedMs(data.path("elapsed_ms").isMissingNode() ? null : data.path("elapsed_ms").asLong()); JsonNode blocks = data.path("blocks"); if (blocks.isArray()) { for (JsonNode node : blocks) { OcrResultDTO.Block b = new OcrResultDTO.Block(); b.setText(text(node, "text", "")); if (node.hasNonNull("confidence")) { b.setConfidence(node.get("confidence").asDouble()); } JsonNode box = node.path("box"); if (box.isArray()) { List coords = new ArrayList<>(box.size()); box.forEach(v -> coords.add(v.asDouble())); b.setBox(coords); } dto.getBlocks().add(b); } } log.info("OCR 完成 file={} engine={} 字符={} 耗时={}ms", dto.getFilename(), dto.getEngine(), dto.getCharCount(), dto.getElapsedMs()); return dto; } catch (Exception e) { log.error("调用 OCR 接口失败 url={}", url, e); throw BusinessException.serverError( "图片识别失败(" + url + ")。请确认 RAG 服务已启动且 OCR 引擎可用:" + "macOS 执行 bash rag-service/tools/build_vision_ocr.sh," + "或 pip install rapidocr-onnxruntime。原因: " + rootMessage(e)); } } /** OCR 专用客户端:读超时按 OCR 配置,避免被检索的短超时误杀 */ private RestTemplate ocrRestTemplate() { SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory(); factory.setConnectTimeout(5000); factory.setReadTimeout(ragProperties.getOcrTimeoutMillis()); return new RestTemplate(factory); } @Override public boolean isHealthy() { if (!ragProperties.isEnabled()) { return false; } try { ResponseEntity response = restTemplate.getForEntity(baseUrl() + "/health", String.class); return response.getStatusCode().is2xxSuccessful(); } catch (Exception e) { return false; } } // ==================== 内部辅助 ==================== /** 去掉末尾斜杠,避免拼出 //api/rag/... */ private String baseUrl() { String url = ragProperties.getBaseUrl(); return url != null && url.endsWith("/") ? url.substring(0, url.length() - 1) : url; } /** * 兼容两种响应格式:{@code {code,msg,data}} 与直接的对象。 * Python 侧返回统一结构时取 data,否则把根节点当作数据。 */ private JsonNode unwrapData(JsonNode root) { if (root != null && root.has("data") && !root.get("data").isNull()) { return root.get("data"); } return root == null ? objectMapper.createObjectNode() : root; } private String text(JsonNode node, String field, String defaultValue) { JsonNode value = node.get(field); return value == null || value.isNull() ? defaultValue : value.asText(); } /** 取异常链最底层的信息,RestTemplate 的异常包装很深,直接 getMessage 可读性差 */ private String rootMessage(Throwable t) { Throwable cursor = t; while (cursor.getCause() != null && cursor.getCause() != cursor) { cursor = cursor.getCause(); } String msg = cursor.getMessage(); return msg == null ? cursor.getClass().getSimpleName() : abbreviate(msg, 300); } private String abbreviate(String s, int max) { if (s == null) { return ""; } return s.length() <= max ? s : s.substring(0, max) + "..."; } }