Knowledge RAG uses {@link MilvusHybridKnowledgeStore} (MilvusClientV2) exclusively. - * Legacy {@code MilvusServiceClient} bean is no longer created for the knowledge path.
+ *知识库 RAG 唯一实现：{@link MilvusHybridKnowledgeStore}（{@code MilvusClientV2}）。
+ *由检索适配器从 {@code KnowledgeSearchHit} / 向量结果映射而来。 - * 后处理会基于它做归一化、规则 boost、chunk 级去重并生成 {@link EvidenceBlock}。
+ *后处理：{@code RetrievalScoreNormalizer} → qualityScore；按 {@link #originalRank} 保序； + * evidenceKey 去重 / 截断；不再用关键词 boost 改序。
*/ @Data @Builder public class RetrievedEvidenceCandidate { - /** 向量库记录 id。 */ private String id; - /** - * 文档级 id（metadata.docId 等）。 - * 用于每文档 chunk 上限；不等于 evidenceKey。 - */ private String docId; - /** 文档内切片序号；可能为空（老数据）。 */ private Integer chunkIndex; - /** - * 片段级去重/投影主键。 - * 通常为 docId#chunk-N，fallback 为 vector:{id}。 - */ private String evidenceKey; - /** - * 来源标识（_source / source / filePath / docId 等）。 - * 可与同文档其他 chunk 重复；不再作为唯一去重键。 - */ private String source; private String title; private String breadcrumb; - /** chunk 正文原文（后处理前未截断或仅底层原样）。 */ private String content; - /** 固定为 L1（向量层）；预留多路召回标记。 */ private String retrievalLayer; - /** 所属 attempt 名，如 FILTERED_VECTOR。 */ private String retrievalAttempt; /** - * 兼容 L2 距离分（越小越相似），后处理会 normalize 成 baseScore。 + * 引擎主分：dense=L2；hybrid=融合分。量纲由 {@link #scoreLabel} 解释。 */ private Double score; - /** 底层原始分。 */ private Double rawScore; - /** rawScore 语义标签：l2_distance / similarity。 */ + /** + * {@code dense} | {@code hybrid}（及可被 canonicalize 的历史别名）。 + */ private String scoreLabel; - /** 向量召回顺序（从 1 起），规则 rerank 前的名次。 */ + /** + * 检索返回名次（从 1 起）——后处理排序权威。 + */ private Integer originalRank; /** - * 扁平化 metadata（string map）。 - * 可能含 docId、chunkIndex、category、kb_scope 等。 + * hybrid 命中可选的 dense L2，仅供质量闸门；不参与排序。 */ + private Double denseDistance; + private MapLifecycle: {@link #bind} on Agent {@code beforeModel} (step row created). Binding stays + * until the next {@code beforeModel} for the same run, covering tool execution that happens + * after {@code afterModel} emits tool_calls. {@link #clear} on run finish is optional cleanup.
+ */ +@Component +public final class AgentStepAuditTracker { + + private final ConcurrentHashMapLLM-facing content policy for {@link AgentReasoningAudit}:
+ *For {@code lookup_knowledge}, enriches RAG-specific columns from internal LookupResult + * JSON when present. {@code relevance_level} stores RAG PRECISE/REFERENCE (not evidence_status). + * {@code evidence_status} remains in {@code retrieval_details} for all tools.
+ */ @Component public final class JpaToolInvocationAuditSink implements ToolInvocationAuditSink { + /** Max chars stored for free-text query / sql / topic style fields. */ + private static final int MAX_TEXT_PREVIEW = 160; + private static final int MAX_REQUEST_KEYS = 12; + private static final Set{@code rawResultJson} is optional internal executor output (e.g. full {@code LookupResult} + * before Agent projection). It is used only to enrich durable RAG fields and must not be + * echoed wholesale into agent-facing views.
+ * + *{@code stepId} links to {@code agent_step.id} when the in-flight Agent step is known. + * {@code requestJson} is the tool request envelope body used only to derive bounded + * {@code input_params} (e.g. query preview) — never dump secrets wholesale.
+ */ public record ToolInvocationAuditEvent( String sessionId, String runId, @@ -15,7 +26,11 @@ public record ToolInvocationAuditEvent( String errorCode, int durationMs, int requestBytes, - int agentResultBytes) { + int agentResultBytes, + String rawResultJson, + String agentResultJson, + Long stepId, + String requestJson) { public ToolInvocationAuditEvent { requireText(sessionId, "sessionId"); @@ -35,6 +50,38 @@ public record ToolInvocationAuditEvent( } } + /** Backward-compatible constructor without raw/agent JSON / step / request body. */ + public ToolInvocationAuditEvent(String sessionId, + String runId, + String toolCallId, + String toolName, + InvocationStatus status, + EvidenceStatus evidenceStatus, + String errorCode, + int durationMs, + int requestBytes, + int agentResultBytes) { + this(sessionId, runId, toolCallId, toolName, status, evidenceStatus, errorCode, + durationMs, requestBytes, agentResultBytes, null, null, null, null); + } + + /** Backward-compatible constructor with raw/agent JSON only. */ + public ToolInvocationAuditEvent(String sessionId, + String runId, + String toolCallId, + String toolName, + InvocationStatus status, + EvidenceStatus evidenceStatus, + String errorCode, + int durationMs, + int requestBytes, + int agentResultBytes, + String rawResultJson, + String agentResultJson) { + this(sessionId, runId, toolCallId, toolName, status, evidenceStatus, errorCode, + durationMs, requestBytes, agentResultBytes, rawResultJson, agentResultJson, null, null); + } + private static void requireText(String value, String name) { if (value == null || value.isBlank()) { throw new IllegalArgumentException(name + " must not be blank"); diff --git a/src/main/java/com/superbiz/agent/harness/audit/TraceAuditEvents.java b/src/main/java/com/superbiz/agent/harness/audit/TraceAuditEvents.java index bba18b9..542f664 100644 --- a/src/main/java/com/superbiz/agent/harness/audit/TraceAuditEvents.java +++ b/src/main/java/com/superbiz/agent/harness/audit/TraceAuditEvents.java @@ -129,9 +129,14 @@ public final class TraceAuditEvents { details.put("evidence_status", tool.evidenceStatus().name()); details.put("request_bytes", tool.requestBytes()); details.put("agent_result_bytes", tool.agentResultBytes()); + details.put("has_raw_result", tool.rawResultJson() != null && !tool.rawResultJson().isBlank()); + if (tool.stepId() != null) { + details.put("step_id", tool.stepId()); + } if (tool.errorCode() != null) { details.put("error_code", tool.errorCode()); } + // Do not embed raw LookupResult / agent JSON here — durable RAG fields go to tool_invocation. return new DiagnosisTraceAuditEvent( tool.sessionId(), tool.runId(), TracePhase.TOOL, TraceEventType.TOOL_INVOCATION, tool.status() == com.superbiz.agent.harness.contract.InvocationStatus.READY diff --git a/src/main/java/com/superbiz/agent/harness/tool/boundary/ToolBoundary.java b/src/main/java/com/superbiz/agent/harness/tool/boundary/ToolBoundary.java index fea3451..c35e33c 100644 --- a/src/main/java/com/superbiz/agent/harness/tool/boundary/ToolBoundary.java +++ b/src/main/java/com/superbiz/agent/harness/tool/boundary/ToolBoundary.java @@ -3,9 +3,9 @@ package com.superbiz.agent.harness.tool.boundary; import com.fasterxml.jackson.core.JsonProcessingException; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; +import com.superbiz.agent.harness.audit.AgentStepAuditTracker; import com.superbiz.agent.harness.audit.ToolInvocationAuditEvent; import com.superbiz.agent.harness.audit.ToolInvocationAuditSink; -import com.superbiz.agent.harness.contract.EvidenceStatus; import com.superbiz.agent.harness.core.BudgetExceededException; import com.superbiz.agent.harness.core.DiagnosisHarnessCore; import com.superbiz.agent.harness.core.RunAbortedException; @@ -19,10 +19,10 @@ import com.superbiz.agent.harness.tool.store.ToolCallKeyFactory; import org.slf4j.Logger; import org.slf4j.LoggerFactory; +import java.nio.charset.StandardCharsets; import java.time.Clock; import java.time.Duration; import java.time.Instant; -import java.nio.charset.StandardCharsets; import java.util.Objects; public final class ToolBoundary { @@ -35,13 +35,14 @@ public final class ToolBoundary { private final ObjectMapper objectMapper; private final Clock clock; private final ToolInvocationAuditSink auditSink; + private final AgentStepAuditTracker stepTracker; public ToolBoundary(DiagnosisHarnessCore core, ToolCallKeyFactory keyFactory, CanonicalInvocationStore store, ObjectMapper objectMapper, Clock clock) { - this(core, keyFactory, store, objectMapper, clock, ToolInvocationAuditSink.noop()); + this(core, keyFactory, store, objectMapper, clock, ToolInvocationAuditSink.noop(), null); } public ToolBoundary(DiagnosisHarnessCore core, @@ -50,12 +51,23 @@ public final class ToolBoundary { ObjectMapper objectMapper, Clock clock, ToolInvocationAuditSink auditSink) { + this(core, keyFactory, store, objectMapper, clock, auditSink, null); + } + + public ToolBoundary(DiagnosisHarnessCore core, + ToolCallKeyFactory keyFactory, + CanonicalInvocationStore store, + ObjectMapper objectMapper, + Clock clock, + ToolInvocationAuditSink auditSink, + AgentStepAuditTracker stepTracker) { this.core = Objects.requireNonNull(core, "core must not be null"); this.keyFactory = Objects.requireNonNull(keyFactory, "keyFactory must not be null"); this.store = Objects.requireNonNull(store, "store must not be null"); this.objectMapper = Objects.requireNonNull(objectMapper, "objectMapper must not be null"); this.clock = Objects.requireNonNull(clock, "clock must not be null"); this.auditSink = Objects.requireNonNull(auditSink, "auditSink must not be null"); + this.stepTracker = stepTracker; } public ToolBoundaryResult execute(RunContext context, @@ -63,15 +75,15 @@ public final class ToolBoundary { ToolExecutor executor, ToolResultProjector projector) { Instant startedAt = clock.instant(); - ToolBoundaryResult result = executeCanonical(context, request, executor, projector); - auditSafely(context, request, result, startedAt); - return result; + ExecutionOutcome outcome = executeCanonical(context, request, executor, projector); + auditSafely(context, request, outcome.result(), outcome.rawResponse(), startedAt); + return outcome.result(); } - private ToolBoundaryResult executeCanonical(RunContext context, - ToolCallRequestEnvelope request, - ToolExecutor executor, - ToolResultProjector projector) { + private ExecutionOutcome executeCanonical(RunContext context, + ToolCallRequestEnvelope request, + ToolExecutor executor, + ToolResultProjector projector) { String toolCallId = request == null ? null : request.toolCallId(); String key; try { @@ -79,23 +91,23 @@ public final class ToolBoundary { core.beforeToolCall(context, request.toolName()); long requestBytes = store.limits().utf8Bytes(request.requestJson()); if (requestBytes > store.limits().maxRecordBytes()) { - return errorAndNoRecord(toolCallId, ToolBoundaryErrorCode.RESULT_TOO_LARGE); + return ExecutionOutcome.of(errorAndNoRecord(toolCallId, ToolBoundaryErrorCode.RESULT_TOO_LARGE)); } core.reserveRunBytes(context, requestBytes); store.begin(key, CanonicalToolInvocation.projecting( request.toolCallId(), request.runId(), request.toolName(), request.requestJson(), clock.instant())); } catch (DuplicateInvocationException e) { - return ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.DUPLICATE_TOOL_CALL); + return ExecutionOutcome.of(ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.DUPLICATE_TOOL_CALL)); } catch (RunAbortedException | BudgetExceededException e) { - return ToolBoundaryResult.error(toolCallId, + return ExecutionOutcome.of(ToolBoundaryResult.error(toolCallId, e instanceof BudgetExceededException ? ToolBoundaryErrorCode.BUDGET_EXHAUSTED - : ToolBoundaryErrorCode.RUN_INACTIVE); + : ToolBoundaryErrorCode.RUN_INACTIVE)); } catch (IllegalArgumentException e) { - return ToolBoundaryResult.error(toolCallId, classifyPreflightError(e)); + return ExecutionOutcome.of(ToolBoundaryResult.error(toolCallId, classifyPreflightError(e))); } catch (CanonicalStoreException e) { - return ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.STORE_ERROR); + return ExecutionOutcome.of(ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.STORE_ERROR)); } String rawResponse; @@ -107,7 +119,7 @@ public final class ToolBoundary { } } catch (Exception e) { markErrorSafely(key, null, ToolBoundaryErrorCode.TOOL_EXECUTION_ERROR); - return ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.TOOL_EXECUTION_ERROR); + return ExecutionOutcome.of(ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.TOOL_EXECUTION_ERROR)); } try { @@ -115,13 +127,16 @@ public final class ToolBoundary { core.reserveRunBytes(context, store.limits().utf8Bytes(rawResponse)); } catch (ResultTooLargeException e) { markErrorSafely(key, null, ToolBoundaryErrorCode.RESULT_TOO_LARGE); - return ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.RESULT_TOO_LARGE); + return new ExecutionOutcome( + ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.RESULT_TOO_LARGE), rawResponse); } catch (BudgetExceededException e) { markErrorSafely(key, null, ToolBoundaryErrorCode.BUDGET_EXHAUSTED); - return ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.BUDGET_EXHAUSTED); + return new ExecutionOutcome( + ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.BUDGET_EXHAUSTED), rawResponse); } catch (RunAbortedException e) { markErrorSafely(key, null, ToolBoundaryErrorCode.RUN_INACTIVE); - return ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.RUN_INACTIVE); + return new ExecutionOutcome( + ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.RUN_INACTIVE), rawResponse); } ProjectedToolResult projected; @@ -133,29 +148,35 @@ public final class ToolBoundary { } } catch (Exception e) { markErrorSafely(key, rawResponse, ToolBoundaryErrorCode.PROJECTION_ERROR); - return ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.PROJECTION_ERROR); + return new ExecutionOutcome( + ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.PROJECTION_ERROR), rawResponse); } try { store.limits().validateAgentResult(projected.agentResult()); core.reserveRunBytes(context, store.limits().utf8Bytes(projected.agentResult())); store.markReady(key, rawResponse, projected.agentResult(), projected.evidenceStatus(), clock.instant()); - return ToolBoundaryResult.ready(toolCallId, projected.agentResult(), projected.evidenceStatus()); + return new ExecutionOutcome( + ToolBoundaryResult.ready(toolCallId, projected.agentResult(), projected.evidenceStatus()), + rawResponse); } catch (ResultTooLargeException e) { markErrorSafely(key, rawResponse, ToolBoundaryErrorCode.RESULT_TOO_LARGE); - return ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.RESULT_TOO_LARGE); + return new ExecutionOutcome( + ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.RESULT_TOO_LARGE), rawResponse); } catch (BudgetExceededException e) { markErrorSafely(key, rawResponse, ToolBoundaryErrorCode.BUDGET_EXHAUSTED); - return ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.BUDGET_EXHAUSTED); + return new ExecutionOutcome( + ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.BUDGET_EXHAUSTED), rawResponse); } catch (RunAbortedException e) { markErrorSafely(key, rawResponse, ToolBoundaryErrorCode.RUN_INACTIVE); - return ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.RUN_INACTIVE); + return new ExecutionOutcome( + ToolBoundaryResult.error(toolCallId, ToolBoundaryErrorCode.RUN_INACTIVE), rawResponse); } catch (CanonicalStoreException e) { ToolBoundaryErrorCode code = e instanceof ResultTooLargeException ? ToolBoundaryErrorCode.RESULT_TOO_LARGE : ToolBoundaryErrorCode.PROJECTION_ERROR; markErrorSafely(key, rawResponse, code); - return ToolBoundaryResult.error(toolCallId, code); + return new ExecutionOutcome(ToolBoundaryResult.error(toolCallId, code), rawResponse); } } @@ -222,6 +243,7 @@ public final class ToolBoundary { private void auditSafely(RunContext context, ToolCallRequestEnvelope request, ToolBoundaryResult result, + String rawResponse, Instant startedAt) { if (context == null || request == null || result == null || !context.runId().equals(request.runId()) @@ -230,11 +252,16 @@ public final class ToolBoundary { return; } try { + Long stepId = stepTracker == null ? null : stepTracker.currentStepId(context.runId()); auditSink.record(new ToolInvocationAuditEvent( context.sessionId(), context.runId(), request.toolCallId(), request.toolName(), result.status(), result.evidenceStatus(), result.errorCode(), saturatingInt(Math.max(0L, Duration.between(startedAt, clock.instant()).toMillis())), - utf8Bytes(request.requestJson()), utf8Bytes(result.agentResult()))); + utf8Bytes(request.requestJson()), utf8Bytes(result.agentResult()), + rawResponse, + result.agentResult(), + stepId, + request.requestJson())); } catch (RuntimeException exception) { log.warn("Failed to persist Tool durable audit: tool={}, status={}", request.toolName(), result.status()); @@ -249,6 +276,12 @@ public final class ToolBoundary { return value >= Integer.MAX_VALUE ? Integer.MAX_VALUE : (int) value; } + private record ExecutionOutcome(ToolBoundaryResult result, String rawResponse) { + static ExecutionOutcome of(ToolBoundaryResult result) { + return new ExecutionOutcome(result, null); + } + } + private static final class InvalidToolCallIdException extends IllegalArgumentException { private InvalidToolCallIdException(Throwable cause) { super("Invalid tool call ID", cause); diff --git a/src/main/java/com/superbiz/agent/service/DiagnosisTraceService.java b/src/main/java/com/superbiz/agent/service/DiagnosisTraceService.java index 104e73b..98e2821 100644 --- a/src/main/java/com/superbiz/agent/service/DiagnosisTraceService.java +++ b/src/main/java/com/superbiz/agent/service/DiagnosisTraceService.java @@ -184,6 +184,7 @@ public class DiagnosisTraceService { .runId(run.getRunId()) .sessionId(run.getSessionId()) .query(run.getQuery()) + .conclusion(run.getConclusion()) .status(run.getStatus()) .agentFlow(run.getAgentFlow()) .intent(run.getIntent() == null ? null : run.getIntent().name()) @@ -239,6 +240,8 @@ public class DiagnosisTraceService { .agentName(audit.getAgentName()) .reasoningAvailable(audit.getReasoningAvailable()) .reasoningContent(audit.getReasoningContent()) + .assistantText(audit.getAssistantText()) + .contentSource(audit.getContentSource()) .contentBytes(audit.getContentBytes()) .createdAt(audit.getCreatedAt()) .build(); diff --git a/src/main/java/com/superbiz/agent/service/KnowledgeDocumentRetriever.java b/src/main/java/com/superbiz/agent/service/KnowledgeDocumentRetriever.java index b701ef6..2a072f8 100644 --- a/src/main/java/com/superbiz/agent/service/KnowledgeDocumentRetriever.java +++ b/src/main/java/com/superbiz/agent/service/KnowledgeDocumentRetriever.java @@ -86,6 +86,7 @@ public class KnowledgeDocumentRetriever { .rawScore(hit.rawScore()) .scoreLabel(hit.scoreLabel()) .originalRank(hit.originalRank()) + .denseDistance(hit.denseDistance()) .metadata(hit.metadata() == null ? java.util.Map.of() : hit.metadata()) .hitReasons(List.of("semantic_rank:" + hit.originalRank(), "attempt:" + attemptName)) .build()); diff --git a/src/main/java/com/superbiz/agent/service/KnowledgeEvidencePostProcessor.java b/src/main/java/com/superbiz/agent/service/KnowledgeEvidencePostProcessor.java index 436faed..d7984ee 100644 --- a/src/main/java/com/superbiz/agent/service/KnowledgeEvidencePostProcessor.java +++ b/src/main/java/com/superbiz/agent/service/KnowledgeEvidencePostProcessor.java @@ -6,6 +6,7 @@ import com.superbiz.agent.dto.KnowledgeQuery; import com.superbiz.agent.dto.RerankTrace; import com.superbiz.agent.dto.RetrievedEvidenceCandidate; import com.superbiz.agent.service.retrieval.EvidenceIdentity; +import com.superbiz.agent.service.retrieval.RetrievalScoreNormalizer; import org.springframework.beans.factory.annotation.Value; import org.springframework.stereotype.Service; @@ -20,28 +21,25 @@ import java.util.Map; import java.util.Set; /** - * 检索后处理：分数归一化、规则 rerank、chunk 级证据组装、相关等级判定。 + * 检索后处理：统一 qualityScore、保检索序、chunk 级装配、相关等级判定。 * *L0 domain/keyword 命中仅写入解释性 {@code hitReasons}，不改变分数与主序。
*/ @Service public class KnowledgeEvidencePostProcessor { private static final String LEVEL_PRECISE = "PRECISE"; - private static final String LEVEL_HIGHLY_RELEVANT = "HIGHLY_RELEVANT"; private static final String LEVEL_REFERENCE = "REFERENCE"; private static final String HINT_PRECISE = "知识库中不存在比上述结果更精准的文档"; - private static final String HINT_HIGHLY_RELEVANT = "当前结果已高度相关，继续检索不太可能找到更精准的文档"; private static final String HINT_REFERENCE = "当前结果为相关参考，如需更精准信息请明确缺少的具体维度"; @Value("${retrieval.normalization.max-l2-distance:2.0}") @@ -53,22 +51,21 @@ public class KnowledgeEvidencePostProcessor { @Value("${retrieval.normalization.reference-threshold:0.5}") private double referenceThreshold = 0.5; - /** 同一 docId 最多保留的 chunk 数。 */ @Value("${rag.max-chunks-per-document:2}") private int maxChunksPerDocument = 2; - /** - * 后处理后最多返回的 evidence 条数。 - * 0 或负数表示不在此层截断（仍可能被 projector 预算截断）。 - */ @Value("${rag.return-n:5}") private int returnN = 5; public EvidencePostprocessResult process(KnowledgeQuery query, List写入单一后端 {@link MilvusHybridKnowledgeStore}（dense + BM25 search_text）。 - * 不再使用 legacy {@code MilvusServiceClient} insert/delete。
+ *唯一后端 {@link MilvusHybridKnowledgeStore}（Milvus SDK v2）：
+ *不再使用 legacy {@code MilvusServiceClient} insert/delete， + * 也不走 Spring AI {@code VectorStore#add}（starter 无 hybrid schema/BM25 Function）。
*/ @Service public class VectorIndexService { @@ -118,12 +124,13 @@ public class VectorIndexService { for (int i = 0; i < chunks.size(); i++) { DocumentChunk chunk = chunks.get(i); try { + // dense embedding 与 BM25 search_text 同源（title/path 增强） List在正文前拼接 title / breadcrumb，提高「按标题或路径关键词」的 BM25 命中率， + * 同时让 dense 向量也编码结构信息。无标题路径时退回纯 content。
*/ static String buildSearchText(DocumentChunk chunk) { String content = trimToEmpty(chunk.getContent()); diff --git a/src/main/java/com/superbiz/agent/service/VectorSearchService.java b/src/main/java/com/superbiz/agent/service/VectorSearchService.java index 3aa7105..4b6deee 100644 --- a/src/main/java/com/superbiz/agent/service/VectorSearchService.java +++ b/src/main/java/com/superbiz/agent/service/VectorSearchService.java @@ -1,6 +1,7 @@ package com.superbiz.agent.service; import com.superbiz.agent.service.milvus.MilvusHybridKnowledgeStore; +import com.superbiz.agent.service.retrieval.RetrievalScoreLabels; import lombok.Getter; import lombok.Setter; import org.slf4j.Logger; @@ -13,11 +14,18 @@ import java.util.List; import java.util.Locale; /** - * Knowledge vector retrieval facade. + * 知识库向量检索门面（lookup_knowledge / RAG 召回入口）。 * - *Single backend: {@link MilvusHybridKnowledgeStore} (Milvus Java SDK v2). - * Legacy {@code MilvusServiceClient} search and Spring AI VectorStore routing for - * {@code lookup_knowledge} have been removed.
+ *唯一后端：{@link MilvusHybridKnowledgeStore}（Milvus Java SDK v2）。
+ * + *{@code retrieval.search.mode}（同库查询算法，非两套写入）：
+ *命中 {@link SearchResult#scoreLabel} 仅为 {@link RetrievalScoreLabels#DENSE} / + * {@link RetrievalScoreLabels#HYBRID}。质量分由后处理 {@code RetrievalScoreNormalizer} 统一计算。
*/ @Service public class VectorSearchService { @@ -31,7 +39,7 @@ public class VectorSearchService { private VectorEmbeddingService embeddingService; /** - * dense | hybrid + * 检索模式：{@code hybrid}（主路径）| {@code dense}（召回对照）。 */ @Value("${retrieval.search.mode:dense}") private String searchMode = "dense"; @@ -53,18 +61,34 @@ public class VectorSearchService { return knowledgeStore.searchDense(query, queryVector, topK, category); } + /** + * 单条召回结果。列表顺序即检索权威序（adapter 赋 originalRank=1..n）。 + * + *Supports dense ANN and dense+BM25 hybrid search via {@code hybridSearch} + {@link RRFRanker}. - * Legacy {@code MilvusServiceClient} search is not used.
+ *+ * id VarChar PK + * content VarChar —— 原文，返回给上层 + * search_text VarChar+analyzer —— BM25 输入文本（可含 title/path 增强） + * sparse_vector SparseFloatVector —— 由 BM25 Function 从 search_text 自动生成，写入时不必填 + * vector FloatVector —— dense 向量（应用侧 embedding） + * metadata JSON —— docId / source / category / kb_scope 等 + *+ * + *
配置入口：{@code milvus.collection}、{@code retrieval.search.mode}、{@code retrieval.hybrid.rrf-k}。
*/ @Service public class MilvusHybridKnowledgeStore { @@ -52,11 +78,20 @@ public class MilvusHybridKnowledgeStore { private static final Logger log = LoggerFactory.getLogger(MilvusHybridKnowledgeStore.class); private static final Gson GSON = new Gson(); + /** 主键（稳定 UUID，由 source + chunkIndex 派生，便于幂等重写）。 */ public static final String FIELD_ID = "id"; + /** 返回给 LLM / 上层的原文 chunk。 */ public static final String FIELD_CONTENT = "content"; + /** + * BM25 输入字段。写入明文；Milvus 侧 analyzer + BM25 Function 生成 {@link #FIELD_SPARSE}。 + * 通常比 content 多带 title/path 等检索增强词。 + */ public static final String FIELD_SEARCH_TEXT = "search_text"; + /** 稀疏向量字段；由 BM25 Function 自动产出，insert 时不要手动填。 */ public static final String FIELD_SPARSE = "sparse_vector"; + /** Dense 向量字段（应用侧 EmbeddingModel 生成）。 */ public static final String FIELD_DENSE = "vector"; + /** 业务元数据 JSON（过滤、证据身份、展示用）。 */ public static final String FIELD_METADATA = "metadata"; private final MilvusProperties milvusProperties; @@ -64,12 +99,14 @@ public class MilvusHybridKnowledgeStore { @Value("${milvus.collection:biz}") private String collectionName = "biz"; + /** + * RRF 平滑参数 k：score(d) = Σ 1/(k + rank_i(d))。 + * k 越大，各路排名差异被压得越平；默认 60 与常见 RRF 设定一致。 + */ @Value("${retrieval.hybrid.rrf-k:60}") private int rrfK = 60; - @Value("${retrieval.normalization.max-l2-distance:2.0}") - private double maxL2Distance = 2.0; - + /** 非空时追加 {@code metadata.kb_scope} 过滤，实现多知识域隔离。 */ @Value("${retrieval.kb-scope:}") private String kbScope = ""; @@ -79,6 +116,10 @@ public class MilvusHybridKnowledgeStore { this.milvusProperties = milvusProperties; } + /** + * 懒连接：首次调用时建连、确保 collection schema 存在并 load。 + * 线程安全；后续检索/写入复用同一 {@link MilvusClientV2}。 + */ public synchronized MilvusClientV2 client() { if (client == null) { client = connect(); @@ -92,6 +133,21 @@ public class MilvusHybridKnowledgeStore { return collectionName; } + /** + * 写入单个 chunk（dense + BM25 所需明文）。 + * + *只插入 {@code content / search_text / vector / metadata}； + * {@code sparse_vector} 由 collection 上的 BM25 Function 在服务端从 {@code search_text} 生成。
+ * + *id 由 {@code source|docId + chunkIndex} 的 nameUUID 派生，同一 chunk 重复写入会得到相同 id + *（配合先 delete 再 insert 的上层逻辑实现覆盖）。
+ * + * @param content 原文（返回字段） + * @param searchText BM25 / 可与 dense embedding 同源的检索文本 + * @param denseVector 应用侧 embedding + * @param metadata 须尽量带 {@code _source} 或 {@code docId}，供 id 与过滤使用 + * @param chunkIndex 分片序号 + */ public void upsertChunk(String content, String searchText, List{@code scoreLabel=hybrid}；{@code score}/{@code rawScore} 保留引擎融合分， + * 不用 dense L2 覆盖主分或改 label。可选并行 dense 探测仅填充 + * {@link VectorSearchService.SearchResult#setDenseDistance}，供后处理绝对质量闸门 + * （如 L0 filter low-quality → unfiltered retry），排序仍以 RRF 返回序为准。
*/ public List关键点：
+ *已存在的 collection 不会改 schema；schema 变更需走 {@link #dropAndRecreateCollection()}。
+ */ private void ensureCollection(MilvusClientV2 milvusClient) { Boolean exists = milvusClient.hasCollection(HasCollectionReq.builder() .collectionName(collectionName) @@ -376,6 +457,7 @@ public class MilvusHybridKnowledgeStore { .dataType(DataType.VarChar) .maxLength(MilvusConstants.CONTENT_MAX_LENGTH) .build()); + // BM25 语料字段：必须 enableAnalyzer，Function 才能从文本生成 sparse schema.addField(AddFieldReq.builder() .fieldName(FIELD_SEARCH_TEXT) .dataType(DataType.VarChar) @@ -395,6 +477,7 @@ public class MilvusHybridKnowledgeStore { .fieldName(FIELD_METADATA) .dataType(DataType.JSON) .build()); + // 写入 search_text 时，Milvus 自动维护 sparse_vector（应用层 insert 不填 sparse） schema.addFunction(CreateCollectionReq.Function.builder() .functionType(FunctionType.BM25) .name("bm25_fn") @@ -446,6 +529,7 @@ public class MilvusHybridKnowledgeStore { } } + /** 过滤表达式字符串转义，防止引号打断 expr。 */ private static String escapeFilter(String value) { return value.replace("\\", "\\\\").replace("\"", "\\\""); } diff --git a/src/main/java/com/superbiz/agent/service/retrieval/KnowledgeSearchHit.java b/src/main/java/com/superbiz/agent/service/retrieval/KnowledgeSearchHit.java index e841eea..d71bcc6 100644 --- a/src/main/java/com/superbiz/agent/service/retrieval/KnowledgeSearchHit.java +++ b/src/main/java/com/superbiz/agent/service/retrieval/KnowledgeSearchHit.java @@ -19,6 +19,8 @@ public record KnowledgeSearchHit( String source, String title, String breadcrumb, - int originalRank + int originalRank, + /** Optional dense L2 for hybrid quality gates; null on dense-only hits. */ + Double denseDistance ) { } diff --git a/src/main/java/com/superbiz/agent/service/retrieval/KnowledgeSearchMode.java b/src/main/java/com/superbiz/agent/service/retrieval/KnowledgeSearchMode.java index 0808e6f..bd0a65e 100644 --- a/src/main/java/com/superbiz/agent/service/retrieval/KnowledgeSearchMode.java +++ b/src/main/java/com/superbiz/agent/service/retrieval/KnowledgeSearchMode.java @@ -1,10 +1,20 @@ package com.superbiz.agent.service.retrieval; /** - * Retrieval mode for {@link KnowledgeSearchPort}. - * Delivery 1 only requires {@link #DENSE}; hybrid arrives in a later change. + * {@link KnowledgeSearchPort} 检索模式。 + * + *当前实际生效模式由全局配置 {@code retrieval.search.mode} 决定 + *（见 {@link com.superbiz.agent.service.VectorSearchService}）； + * 请求里的 mode 预留作将来 per-call 覆盖，adapter 暂未按请求切换。
*/ public enum KnowledgeSearchMode { + /** 仅 dense 向量检索。 */ DENSE, + /** dense + BM25 hybrid（Milvus {@code hybridSearch} + RRF）。 */ HYBRID } diff --git a/src/main/java/com/superbiz/agent/service/retrieval/KnowledgeSearchPort.java b/src/main/java/com/superbiz/agent/service/retrieval/KnowledgeSearchPort.java index f94c9ed..b878891 100644 --- a/src/main/java/com/superbiz/agent/service/retrieval/KnowledgeSearchPort.java +++ b/src/main/java/com/superbiz/agent/service/retrieval/KnowledgeSearchPort.java @@ -3,8 +3,11 @@ package com.superbiz.agent.service.retrieval; import java.util.List; /** - * Application boundary for knowledge semantic search. - * Implementations may wrap VectorStore, hybrid engines, etc. without leaking SDK details upward. + * 知识语义检索的应用边界端口。 + * + *实现可对接 dense / hybrid 等引擎，但不得向上层泄漏 SDK 类型。 + * 当前实现：{@link VectorKnowledgeSearchAdapter} → {@code VectorSearchService} + * → {@code MilvusHybridKnowledgeStore}（Milvus SDK v2 dense 或 dense+BM25 RRF）。
*/ public interface KnowledgeSearchPort { diff --git a/src/main/java/com/superbiz/agent/service/retrieval/RetrievalScoreLabels.java b/src/main/java/com/superbiz/agent/service/retrieval/RetrievalScoreLabels.java new file mode 100644 index 0000000..ee9bf7e --- /dev/null +++ b/src/main/java/com/superbiz/agent/service/retrieval/RetrievalScoreLabels.java @@ -0,0 +1,45 @@ +package com.superbiz.agent.service.retrieval; + +/** + * 检索结果一级 {@code scoreLabel} 约定。 + * + *只区分两种检索形态（与 {@code retrieval.search.mode} 对齐）， + * 不再使用 {@code bm25_only_*} 等作为正式一级 label。
+ */ +public final class RetrievalScoreLabels { + + /** dense-only ANN：{@code score} 为 L2 距离（越小越好）。 */ + public static final String DENSE = "dense"; + + /** hybrid（dense+BM25+RRF）：{@code score}/raw 为融合侧信号；质量分主要看 rank。 */ + public static final String HYBRID = "hybrid"; + + private RetrievalScoreLabels() { + } + + /** + * 将历史/别名 label 归一到 {@link #DENSE} 或 {@link #HYBRID}。 + * 未知或空 → dense（保守，按 L2 解释失败时 quality 偏低）。 + */ + public static String canonicalize(String scoreLabel) { + if (scoreLabel == null || scoreLabel.isBlank()) { + return DENSE; + } + String label = scoreLabel.trim().toLowerCase(); + return switch (label) { + case DENSE, "l2_distance", "l2" -> DENSE; + case HYBRID, "rrf_fused", "rrf", "bm25_only_no_dense", "bm25_only" -> HYBRID; + default -> label.contains("hybrid") || label.contains("rrf") || label.contains("bm25") + ? HYBRID + : DENSE; + }; + } + + public static boolean isHybrid(String scoreLabel) { + return HYBRID.equals(canonicalize(scoreLabel)); + } + + public static boolean isDense(String scoreLabel) { + return DENSE.equals(canonicalize(scoreLabel)); + } +} diff --git a/src/main/java/com/superbiz/agent/service/retrieval/RetrievalScoreNormalizer.java b/src/main/java/com/superbiz/agent/service/retrieval/RetrievalScoreNormalizer.java new file mode 100644 index 0000000..0e68d4a --- /dev/null +++ b/src/main/java/com/superbiz/agent/service/retrieval/RetrievalScoreNormalizer.java @@ -0,0 +1,71 @@ +package com.superbiz.agent.service.retrieval; + +/** + * 检索分 → 统一 {@code qualityScore ∈ [0,1]}（越大越好）的唯一转换点。 + * + *后处理排序仍按 {@code originalRank}；本类只负责质量闸门 / relevance 用分。
+ * + *Delegates to {@link VectorSearchService}, which is backed solely by - * Milvus V2 dense / dense+BM25 hybrid store. Mode selection lives in - * {@code retrieval.search.mode}.
+ *委托 {@link VectorSearchService}（背后仅 {@code MilvusHybridKnowledgeStore}）： + * dense 或 dense+BM25 hybrid 由配置 {@code retrieval.search.mode} 选择。 + * 本类负责 metadata 解析、docId/chunk 身份与 evidenceKey，不碰 SDK。
*/ @Component public class VectorKnowledgeSearchAdapter implements KnowledgeSearchPort { @@ -76,7 +76,8 @@ public class VectorKnowledgeSearchAdapter implements KnowledgeSearchPort { source, EvidenceIdentity.metadataValue(metadata, "title"), EvidenceIdentity.metadataValue(metadata, "breadcrumb"), - originalRank + originalRank, + result.getDenseDistance() ); } diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml index 6db6800..7a4d177 100644 --- a/src/main/resources/application.yml +++ b/src/main/resources/application.yml @@ -167,17 +167,21 @@ rag: enabled: false content-preview-limit: 300 -# 检索配置（单一 Milvus V2 后端；已移除 sdk/spring/auto 路由） +# 检索配置 +# 知识主路径：Milvus Java SDK v2（MilvusHybridKnowledgeStore），非 Spring AI VectorStore starter。 +# 原因：starter（含 2.0.0）仅 dense similarity，无 hybridSearch / BM25 Function / RRFRanker。 +# 已移除 legacy sdk/spring/auto 多后端路由。 retrieval: - kb-scope: "" # empty means search all documents in hybrid collection + kb-scope: "" # 非空则过滤 metadata.kb_scope；空=不过滤 search: - mode: hybrid # dense | hybrid (dense + BM25 RRF) + # hybrid=线上主路径；dense=同库对照/评测/排障（非第二套线上策略）。见 mvp/architecture/rag-knowledge-retrieval-architecture.md §6.0 + mode: hybrid # dense=单路L2对照 | hybrid=dense+服务端BM25+RRF hybrid: - rrf-k: 60 + rrf-k: 60 # RRF 平滑参数 k，score=Σ 1/(k+rank) normalization: - max-l2-distance: 2.0 # L2 距离上界（BGE-M3 单位向量 = 2.0） - highly-relevant-threshold: 0.75 # similarity >= 0.75 → HIGHLY_RELEVANT - reference-threshold: 0.5 # similarity >= 0.5 → REFERENCE + max-l2-distance: 2.0 # dense quality：L2 上界（单位向量 ≈ 2.0） + highly-relevant-threshold: 0.75 # qualityScore >= 0.75 → PRECISE（hybrid 为序数分，见架构 §6） + reference-threshold: 0.5 # qualityScore >= 0.5 → REFERENCE；低于则低质/可 unfiltered retry # Prometheus 配置 prometheus: @@ -213,6 +217,8 @@ logging: # Agent-facing MySQL Tool uses independent logical datasources only. # Production entries are supplied by a dedicated profile and Secret injection. +# When data-sources is empty (default), query_mysql is NOT registered on the Diagnosis Agent +# (avoids a permanently broken tool that the model can still call). harness: chat: worker-core-pool-size: 2 diff --git a/src/main/resources/db/migration/V016__add_conclusion_to_diagnosis_run.sql b/src/main/resources/db/migration/V016__add_conclusion_to_diagnosis_run.sql new file mode 100644 index 0000000..55db01a --- /dev/null +++ b/src/main/resources/db/migration/V016__add_conclusion_to_diagnosis_run.sql @@ -0,0 +1,3 @@ +-- V016: expose a first-class conclusion field next to query for run-level readout. +ALTER TABLE diagnosis_run + ADD COLUMN conclusion TEXT NULL COMMENT 'Extracted final conclusion text (from report or fallback message)' AFTER query; diff --git a/src/main/resources/db/migration/V017__add_content_source_to_agent_reasoning_audit.sql b/src/main/resources/db/migration/V017__add_content_source_to_agent_reasoning_audit.sql new file mode 100644 index 0000000..9965e97 --- /dev/null +++ b/src/main/resources/db/migration/V017__add_content_source_to_agent_reasoning_audit.sql @@ -0,0 +1,9 @@ +-- V017: store provider reasoning and assistant text separately on agent model steps. +-- Tool result payloads remain out of this table (see tool_invocation). +ALTER TABLE agent_reasoning_audit + ADD COLUMN assistant_text LONGTEXT NULL + COMMENT 'Assistant visible text / tool-call plan for this model step (no tool results)' + AFTER reasoning_content, + ADD COLUMN content_source VARCHAR(64) NULL + COMMENT 'PROVIDER_REASONING+ASSISTANT_TEXT | PROVIDER_REASONING | ASSISTANT_TEXT | TOOL_CALL_PLAN | NONE' + AFTER assistant_text; diff --git a/src/test/java/com/superbiz/agent/config/HarnessChatConfigurationTest.java b/src/test/java/com/superbiz/agent/config/HarnessChatConfigurationTest.java index 2b04253..34b9e89 100644 --- a/src/test/java/com/superbiz/agent/config/HarnessChatConfigurationTest.java +++ b/src/test/java/com/superbiz/agent/config/HarnessChatConfigurationTest.java @@ -91,6 +91,8 @@ class HarnessChatConfigurationTest { .withBean(LookupResultAssembler.class, () -> mock(LookupResultAssembler.class)) .withBean(ToolInvocationAuditSink.class, ToolInvocationAuditSink::noop) .withBean(DiagnosisTraceRecorder.class, DiagnosisTraceRecorder::noop) + .withBean(com.superbiz.agent.harness.audit.AgentStepAuditTracker.class, + com.superbiz.agent.harness.audit.AgentStepAuditTracker::new) .withBean(AgentStepRepository.class, () -> mock(AgentStepRepository.class)) .withBean(AgentReasoningAuditRepository.class, () -> mock(AgentReasoningAuditRepository.class)) diff --git a/src/test/java/com/superbiz/agent/eval/RagLookupSnapshotGeneratorTest.java b/src/test/java/com/superbiz/agent/eval/RagLookupSnapshotGeneratorTest.java index 73825a6..011a47a 100644 --- a/src/test/java/com/superbiz/agent/eval/RagLookupSnapshotGeneratorTest.java +++ b/src/test/java/com/superbiz/agent/eval/RagLookupSnapshotGeneratorTest.java @@ -10,18 +10,29 @@ import org.junit.jupiter.api.Test; import org.junit.jupiter.api.condition.EnabledIfSystemProperty; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; +import org.springframework.test.context.DynamicPropertyRegistry; +import org.springframework.test.context.DynamicPropertySource; import java.nio.file.Files; import java.nio.file.Path; import java.time.Instant; +import java.util.Locale; import static org.junit.jupiter.api.Assertions.assertTrue; /** - * Generates RAG retrieval fixtures from the real LookupKnowledgeTool bean. + * Generates RAG retrieval fixtures from the real {@link LookupKnowledgeTool} bean. * - *This class is disabled by default because it writes repository files and - * depends on the configured runtime retrieval stack.
+ *Disabled by default: writes repository files and needs the live retrieval stack + * (embedding + Milvus hybrid collection + optional MySQL/L0).
+ * + *System properties (via Maven {@code -D}):
+ *