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 微服务代理。
|
*
|
* <p>本接口存在的原因:<b>前端永远不直连 Python 服务</b>。
|
* 所有 RAG 流量都经过 SpringBoot,好处是:
|
* <ul>
|
* <li>统一鉴权 —— Python 服务不需要重复实现 JWT 校验</li>
|
* <li>Python 服务可以只监听内网,不暴露给浏览器</li>
|
* <li>业务侧可以在这里加缓存、限流、降级逻辑</li>
|
* </ul>
|
*/
|
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<RagChunk> search(String query, List<String> collectionNames, int topK);
|
|
/**
|
* 把检索片段拼装成注入 prompt 的上下文文本。
|
*
|
* @return 形如「参考资料 1(来自 xxx.pdf):...」的文本,无命中返回 null
|
*/
|
String buildRagContext(List<RagChunk> chunks);
|
|
/** 删除向量集合 */
|
boolean deleteCollection(String collectionName);
|
|
/** 健康检查:RAG 服务是否可用 */
|
boolean isHealthy();
|
|
/**
|
* 图片文字识别(OCR)。
|
*
|
* <p>用于对话时上传图片:把图里的文字提取出来,作为上下文喂给大模型。
|
*
|
* @param imagePath 服务器磁盘上的图片路径
|
* @return 识别结果;OCR 服务不可用时抛 BusinessException(这是用户显式发起的操作,
|
* 静默失败会让人以为图片内容已被理解)
|
*/
|
OcrResultDTO recognizeImage(Path imagePath);
|
|
/** 入库结果 */
|
record IngestResult(String collectionName, int chunkCount, String message) {
|
}
|
}
|