kongdeqiang
2026-10-12 7c687dd3c8fba9f7632f5e29d94a708e5f497abd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
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) {
    }
}