feat: add rag evidence postprocess blocks

2026-07-05 03:03:18 +08:00
parent 4a94c14feb
commit 5197712719
12 changed files with 497 additions and 1 deletions
@@ -0,0 +1,28 @@
+package com.superbiz.agent.dto;
+
+import lombok.Builder;
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * Structured evidence returned by knowledge retrieval.
+ */
+@Data
+@Builder
+public class EvidenceBlock {
+
+    private String source;
+
+    private String title;
+
+    private String breadcrumb;
+
+    private String retrievalLayer;
+
+    private String content;
+
+    private Double score;
+
+    private List<String> hitReasons;
+}
@@ -27,6 +27,21 @@ public class LookupResult {
     */
    private SupplementResult supplement;

+    /**
+     * Structured evidence blocks after retrieval post-processing.
+     */
+    private List<EvidenceBlock> evidenceBlocks;
+
+    /**
+     * Candidate count before evidence deduplication.
+     */
+    private Integer evidenceCandidateCount;
+
+    /**
+     * Evidence block count after post-processing.
+     */
+    private Integer evidenceBlockCount;
+
    /**
     * 归一化质量等级：PRECISE / HIGHLY_RELEVANT / REFERENCE
     */
@@ -3,6 +3,7 @@ package com.superbiz.agent.service;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.superbiz.agent.domain.entity.ToolInvocation;
+import com.superbiz.agent.dto.EvidenceBlock;
 import com.superbiz.agent.dto.LookupResult;
 import com.superbiz.agent.repository.ToolInvocationRepository;
 import com.superbiz.agent.dto.KnowledgeEntry;
@@ -128,6 +129,15 @@ public class ToolInvocationRecorder {
        if (record.l1Scores() != null && !record.l1Scores().isEmpty()) {
            details.put("l1_scores", record.l1Scores());
        }
+        if (record.evidenceCandidateCount() != null) {
+            details.put("evidence_candidate_count", record.evidenceCandidateCount());
+        }
+        if (record.evidenceBlockCount() != null) {
+            details.put("evidence_block_count", record.evidenceBlockCount());
+        }
+        if (record.evidenceBlocks() != null && !record.evidenceBlocks().isEmpty()) {
+            details.put("evidence_blocks", record.evidenceBlocks());
+        }
        if (record.relevanceLevel() != null) {
            details.put("relevance_level", record.relevanceLevel());
        }
@@ -209,7 +219,10 @@ public class ToolInvocationRecorder {
            List<String> l0Entities,
            Double l1TopScore,
            Double l1TopSimilarity,
-            List<Double> l1Scores
+            List<Double> l1Scores,
+            Integer evidenceCandidateCount,
+            Integer evidenceBlockCount,
+            List<Map<String, Object>> evidenceBlocks
    ) {
        public static LookupKnowledgeRecord from(String query,
                                                 KnowledgeIndexService.L0Hint l0Hint,
@@ -290,7 +303,33 @@ public class ToolInvocationRecorder {
                    .l1TopScore(hasL1 ? (double) l1Results.get(0).getScore() : null)
                    .l1TopSimilarity(hasL1 ? l1TopSimilarity : null)
                    .l1Scores(l1Scores)
+                    .evidenceCandidateCount(result != null ? result.getEvidenceCandidateCount() : null)
+                    .evidenceBlockCount(result != null ? result.getEvidenceBlockCount() : null)
+                    .evidenceBlocks(result != null ? summarizeEvidenceBlocks(result.getEvidenceBlocks()) : List.of())
                    .build();
        }
+
+        private static List<Map<String, Object>> summarizeEvidenceBlocks(List<EvidenceBlock> blocks) {
+            if (blocks == null || blocks.isEmpty()) {
+                return List.of();
+            }
+            List<Map<String, Object>> summaries = new ArrayList<>();
+            for (int i = 0; i < Math.min(5, blocks.size()); i++) {
+                EvidenceBlock block = blocks.get(i);
+                Map<String, Object> summary = new LinkedHashMap<>();
+                summary.put("source", block.getSource());
+                summary.put("title", block.getTitle());
+                summary.put("breadcrumb", block.getBreadcrumb());
+                summary.put("retrieval_layer", block.getRetrievalLayer());
+                summary.put("score", block.getScore());
+                summary.put("hit_reasons", block.getHitReasons());
+                String content = block.getContent();
+                if (content != null) {
+                    summary.put("content_preview", content.length() <= 180 ? content : content.substring(0, 180) + "...");
+                }
+                summaries.add(summary);
+            }
+            return summaries;
+        }
    }
 }
@@ -13,8 +13,11 @@ import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.stereotype.Component;

+import java.util.ArrayList;
+import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Locale;
+import java.util.Map;
 import java.util.stream.Collectors;

 /**
@@ -397,12 +400,154 @@ public class LookupKnowledgeTool {
        }
        builder.supplement(supplement);

+        EvidencePostprocessResult evidence = buildEvidenceBlocks(l0Matches, l1Results);
+        builder.evidenceBlocks(evidence.blocks());
+        builder.evidenceCandidateCount(evidence.candidateCount());
+        builder.evidenceBlockCount(evidence.blocks().size());
+
        boolean found = (primary != null) || (supplement != null);
        builder.found(found);

        return builder.build();
    }

+    private EvidencePostprocessResult buildEvidenceBlocks(
+            List<KnowledgeEntry> l0Matches,
+            List<VectorSearchService.SearchResult> l1Results) {
+        Map<String, EvidenceBlock> deduped = new LinkedHashMap<>();
+        int candidateCount = 0;
+
+        if (l0Matches != null) {
+            for (int i = 0; i < l0Matches.size(); i++) {
+                KnowledgeEntry entry = l0Matches.get(i);
+                candidateCount++;
+                EvidenceBlock block = EvidenceBlock.builder()
+                        .source(entry.getFilePath())
+                        .title(entry.getTitle())
+                        .breadcrumb(null)
+                        .retrievalLayer("L0")
+                        .content(buildMetadataOnlySummary(entry))
+                        .score(null)
+                        .hitReasons(buildL0HitReasons(entry, i + 1))
+                        .build();
+                mergeEvidence(deduped, sourceKey(block, "l0-" + i), block);
+            }
+        }
+
+        if (l1Results != null) {
+            for (int i = 0; i < l1Results.size(); i++) {
+                VectorSearchService.SearchResult result = l1Results.get(i);
+                candidateCount++;
+                Map<String, String> metadata = parseMetadata(result.getMetadata());
+                String source = firstNonBlank(
+                        metadata.get("_source"),
+                        metadata.get("docId"),
+                        result.getMetadata(),
+                        result.getId()
+                );
+                EvidenceBlock block = EvidenceBlock.builder()
+                        .source(source)
+                        .title(metadata.get("title"))
+                        .breadcrumb(metadata.get("breadcrumb"))
+                        .retrievalLayer("L1")
+                        .content(truncate(result.getContent(), 800))
+                        .score((double) result.getScore())
+                        .hitReasons(List.of("semantic_rank:" + (i + 1)))
+                        .build();
+                mergeEvidence(deduped, sourceKey(block, "l1-" + i), block);
+            }
+        }
+
+        return new EvidencePostprocessResult(candidateCount, new ArrayList<>(deduped.values()));
+    }
+
+    private void mergeEvidence(Map<String, EvidenceBlock> deduped, String key, EvidenceBlock incoming) {
+        EvidenceBlock existing = deduped.get(key);
+        if (existing == null) {
+            deduped.put(key, incoming);
+            return;
+        }
+
+        List<String> mergedReasons = new ArrayList<>();
+        if (existing.getHitReasons() != null) {
+            mergedReasons.addAll(existing.getHitReasons());
+        }
+        if (incoming.getHitReasons() != null) {
+            for (String reason : incoming.getHitReasons()) {
+                if (!mergedReasons.contains(reason)) {
+                    mergedReasons.add(reason);
+                }
+            }
+        }
+
+        String mergedLayer = existing.getRetrievalLayer();
+        if (incoming.getRetrievalLayer() != null && !incoming.getRetrievalLayer().equals(mergedLayer)) {
+            mergedLayer = "L0+L1";
+        }
+
+        existing.setRetrievalLayer(mergedLayer);
+        existing.setHitReasons(mergedReasons);
+        if (existing.getScore() == null && incoming.getScore() != null) {
+            existing.setScore(incoming.getScore());
+        }
+        if ((existing.getBreadcrumb() == null || existing.getBreadcrumb().isBlank())
+                && incoming.getBreadcrumb() != null) {
+            existing.setBreadcrumb(incoming.getBreadcrumb());
+        }
+    }
+
+    private List<String> buildL0HitReasons(KnowledgeEntry entry, int rank) {
+        List<String> reasons = new ArrayList<>();
+        reasons.add("l0_rank:" + rank);
+        if (entry.getKeywords() != null && !entry.getKeywords().isEmpty()) {
+            reasons.add("l0_keywords:" + String.join(",", entry.getKeywords()));
+        }
+        if (entry.getCategory() != null && !entry.getCategory().isBlank()) {
+            reasons.add("domain:" + entry.getCategory());
+        }
+        return reasons;
+    }
+
+    private String sourceKey(EvidenceBlock block, String fallback) {
+        return firstNonBlank(block.getSource(), block.getTitle(), block.getBreadcrumb(), fallback);
+    }
+
+    private Map<String, String> parseMetadata(String metadata) {
+        if (metadata == null || metadata.isBlank()) {
+            return Map.of();
+        }
+        try {
+            Map<?, ?> raw = objectMapper.readValue(metadata, Map.class);
+            Map<String, String> result = new LinkedHashMap<>();
+            for (Map.Entry<?, ?> entry : raw.entrySet()) {
+                if (entry.getKey() != null && entry.getValue() != null) {
+                    result.put(String.valueOf(entry.getKey()), String.valueOf(entry.getValue()));
+                }
+            }
+            return result;
+        } catch (Exception e) {
+            return Map.of();
+        }
+    }
+
+    private String firstNonBlank(String... values) {
+        for (String value : values) {
+            if (value != null && !value.isBlank()) {
+                return value;
+            }
+        }
+        return null;
+    }
+
+    private String truncate(String text, int maxLength) {
+        if (text == null || text.length() <= maxLength) {
+            return text;
+        }
+        return text.substring(0, maxLength) + "...";
+    }
+
+    private record EvidencePostprocessResult(int candidateCount, List<EvidenceBlock> blocks) {}
+
    private int countMdHeadings(String content) {
        if (content == null) return 0;
        return (int) content.lines()