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,好处是:
*
* - 统一鉴权 —— Python 服务不需要重复实现 JWT 校验
* - Python 服务可以只监听内网,不暴露给浏览器
* - 业务侧可以在这里加缓存、限流、降级逻辑
*
*/
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) {
}
}