kongdeqiang
2026-10-10 ad24c871d74a417db5412fd9d1fa60411c33ae7f
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
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
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 服务。
 *
 * <p>接口对应关系:
 * <pre>
 * 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}
 * </pre>
 *
 * <p><b>降级策略</b>:检索失败返回空列表而非抛异常。
 * 理由:知识库是「增强」能力,它挂掉不应该让用户连话都聊不了。
 * 而入库失败必须抛出 —— 用户明确点了「向量化」,静默失败会让人以为成功了。
 */
@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<String, Object> 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<String> 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<RagChunk> search(String query, List<String> 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<String> 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<RagChunk> 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<RagChunk> 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<String, Object> 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<String> 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<Double> 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<String> 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) + "...";
    }
}