package com.custom.webui.service; import com.custom.webui.dto.resp.OcrResultDTO; import com.custom.webui.dto.resp.RagChunk; import java.nio.file.Path; import java.util.List; /** * RAG 微服务代理。 * *

本接口存在的原因:前端永远不直连 Python 服务。 * 所有 RAG 流量都经过 SpringBoot,好处是: *

*/ public interface RagProxyService { /** * 提交文档做向量化入库。 * * @param filePath 服务器上文件的绝对路径 * @param collectionName 目标集合名,为空则由 Python 侧按内容生成 * @param userId 用于在向量元数据中记录归属 * @return 入库结果:集合名 + 分块数 */ IngestResult ingest(Path filePath, String collectionName, Long userId); /** * 在多个集合中做相似度检索。 * * @param query 用户问题 * @param collectionNames 目标集合,空列表表示没有知识库可查 * @param topK 每集合返回片段数 * @return 命中片段,按相关度排序;服务不可用时返回空列表(降级为纯对话) */ List search(String query, List collectionNames, int topK); /** * 把检索片段拼装成注入 prompt 的上下文文本。 * * @return 形如「参考资料 1(来自 xxx.pdf):...」的文本,无命中返回 null */ String buildRagContext(List chunks); /** 删除向量集合 */ boolean deleteCollection(String collectionName); /** 健康检查:RAG 服务是否可用 */ boolean isHealthy(); /** * 图片文字识别(OCR)。 * *

用于对话时上传图片:把图里的文字提取出来,作为上下文喂给大模型。 * * @param imagePath 服务器磁盘上的图片路径 * @return 识别结果;OCR 服务不可用时抛 BusinessException(这是用户显式发起的操作, * 静默失败会让人以为图片内容已被理解) */ OcrResultDTO recognizeImage(Path imagePath); /** 入库结果 */ record IngestResult(String collectionName, int chunkCount, String message) { } }