Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

fix(observability): distinguish retrieval diagnostic spans (#4128)

lyingbug8cb53fdbc58e
diff --git a/internal/application/service/knowledgebase_search.go b/internal/application/service/knowledgebase_search.go
index 2c2020905..e615197e4 100644
--- a/internal/application/service/knowledgebase_search.go
+++ b/internal/application/service/knowledgebase_search.go
@@ -135,7 +135,8 @@ func (s *knowledgeBaseService) HybridSearch(ctx context.Context,
return nil, err
}
- recordImageRecallDecision(ctx, "candidate_cut", nil, summarizeImageCandidateCut(chunks, params.MatchCount))
+ recordImageRecallDecision(ctx, "fusion.candidate_selection", "",
+ summarizeImageCandidateCut(chunks, params.MatchCount))
// Truncate to the primary-match cap. MatchCount is guaranteed positive by
// the normalization at the top of this function; the slice bound below
diff --git a/internal/application/service/knowledgebase_search_fanout.go b/internal/application/service/knowledgebase_search_fanout.go
index fe0c0afc8..72936f225 100644
--- a/internal/application/service/knowledgebase_search_fanout.go
+++ b/internal/application/service/knowledgebase_search_fanout.go
@@ -151,7 +151,7 @@ func retrieveGroup(ctx context.Context, g *storeGroup) ([]*types.RetrieveResult,
if rr != nil {
out := summarizeImagePool(rr, g)
out["retriever"], out["kb_ids"] = rr.RetrieverType, g.KBIDs
- recordImageRecallDecision(ctx, "filter", nil, out)
+ recordImageRecallDecision(ctx, "filter_decision", rr.RetrieverType, out)
}
}
filterImageHits(res, g)
diff --git a/internal/application/service/knowledgebase_search_image_obs.go b/internal/application/service/knowledgebase_search_image_obs.go
index 62a3f789c..345ee3a00 100644
--- a/internal/application/service/knowledgebase_search_image_obs.go
+++ b/internal/application/service/knowledgebase_search_image_obs.go
@@ -45,7 +45,7 @@ func retrieveObservedImagePool(ctx context.Context, g *storeGroup, params []type
out["kb_ids"], out["image_kb_ids"] = g.KBIDs, imageKBs
out["result_complete"] = err == nil && rr.Error == nil
out["unreturned_images"] = "unknown: engine threshold, top_k, or no eligible indexed images"
- recordImageRecallDecision(ctx, "engine_pool", nil, out)
+ recordImageRecallDecision(ctx, "result_pool."+phase, rr.RetrieverType, out)
}
return res, err
}
@@ -131,10 +131,22 @@ func summarizeImageCandidateCut(hits []*types.IndexWithScore, limit int) map[str
}
}
-func recordImageRecallDecision(ctx context.Context, stage string, input, output map[string]interface{}) {
- logger.GetLogger(ctx).WithFields(logger.Fields(output)).Info("image recall " + stage)
+// Diagnostic snapshots describe existing results, not another retrieval call.
+// Counts cover the entire pool; detailed samples focus on image-vector hits.
+func recordImageRecallDecision(
+ ctx context.Context, stage string, retriever types.RetrieverType, output map[string]interface{},
+) {
+ name := "diagnostics.retrieval."
+ if retriever != "" {
+ name += string(retriever) + "."
+ }
+ name += stage
+ logger.GetLogger(ctx).WithFields(logger.Fields(output)).Info(name)
_, span := langfuse.GetManager().StartSpan(ctx, langfuse.SpanOptions{
- Name: "retrieval.image_" + stage, Input: input,
+ Name: name,
+ Metadata: map[string]interface{}{
+ "observation_kind": "diagnostic", "stage": stage, "sample_scope": "image_vectors",
+ },
})
span.Finish(output, nil, nil)
}
diff --git a/internal/reranking/observability.go b/internal/reranking/observability.go
index 10b0d6b7e..8d43c11cd 100644
--- a/internal/reranking/observability.go
+++ b/internal/reranking/observability.go
@@ -15,8 +15,14 @@ func recordSelection(ctx context.Context, input []*types.SearchResult, res *Resu
scoredAsImage map[int]bool,
) {
out := summarizeSelection(input, res, opts, scoredAsImage)
- logger.GetLogger(ctx).WithFields(logger.Fields(out)).Info("rerank selection")
- _, span := langfuse.GetManager().StartSpan(ctx, langfuse.SpanOptions{Name: "rerank.selection"})
+ const name = "diagnostics.rerank.selection"
+ logger.GetLogger(ctx).WithFields(logger.Fields(out)).Info(name)
+ _, span := langfuse.GetManager().StartSpan(ctx, langfuse.SpanOptions{
+ Name: name,
+ Metadata: map[string]interface{}{
+ "observation_kind": "diagnostic", "sample_scope": "image_vectors",
+ },
+ })
span.Finish(out, nil, nil)
}
diff --git a/website-docs/03-features/16-observability.md b/website-docs/03-features/16-observability.md
index 5396f4a39..e17f7999a 100644
--- a/website-docs/03-features/16-observability.md
+++ b/website-docs/03-features/16-observability.md
@@ -136,6 +136,23 @@ flowchart LR
G --> H["Generation: embedding / vlm / chat"]
```
+#### 检索调用与诊断记录
+
+`embedding.embed`、`retrieve`、`rerank` 分别记录 query 向量计算、实际检索阶段和重排模型调用的耗时。以 `diagnostics.` 开头的节点只记录已有结果的统计和筛选判定,不会额外发起检索或模型请求,也不应当作独立调用统计。
+
+| 诊断节点 | 含义 |
+| --- | --- |
+| `diagnostics.retrieval.vector.result_pool.initial` | 向量检索首次返回的结果池 |
+| `diagnostics.retrieval.keywords.result_pool.initial` | 关键词检索首次返回的结果池 |
+| `diagnostics.retrieval.<vector/keywords>.result_pool.refill` | 补充检索返回的结果池,仅在实际发生补充检索时出现 |
+| `diagnostics.retrieval.<vector/keywords>.filter_decision` | 应用过滤前的结果池及保留/淘汰判定 |
+| `diagnostics.retrieval.fusion.candidate_selection` | 融合后按候选数量上限截断的判定 |
+| `diagnostics.rerank.selection` | 重排后的保留/淘汰判定 |
+
+这些结果池包含文本、摘要、图片描述、OCR 和原图向量等符合查询范围的记录,并非只检索图片。总数统计覆盖全部候选,`image_samples` 只抽样展示原图向量命中;metadata 中用 `observation_kind=diagnostic` 和 `sample_scope=image_vectors` 标明用途。没有补充检索时,`result_pool.initial` 和 `filter_decision` 的样本可能相同,表示同一批数据在两个阶段被观察。
+
+命名调整只影响新产生的追踪;历史记录保留原来的 `retrieval.image_*` 和 `rerank.selection` 名称。按节点名称过滤的仪表盘或查询需同步调整。
+
#### 每轮用量、调用用途与缓存
每次模型调用继续生成独立 Generation;消息的 usage 保存本轮聚合 Token 用量,Agent 完成事件通过 turn_usage 返回,重开历史消息仍可读取。prompt_tokens、completion_tokens、total_tokens 为总计;cached_tokens 是 cache_read_tokens 的兼容别名,cache_read/write/miss 是输入 Token 的细分,不能再加到 prompt_tokens 上。