Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
fix(observability): distinguish retrieval diagnostic spans (#4128)
lyingbug8cb53fdbc58e
diff --git a/internal/application/service/knowledgebase_search.go b/internal/application/service/knowledgebase_search.goindex 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 belowdiff --git a/internal/application/service/knowledgebase_search_fanout.go b/internal/application/service/knowledgebase_search_fanout.goindex 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.goindex 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 []typeout["kb_ids"], out["image_kb_ids"] = g.KBIDs, imageKBsout["result_complete"] = err == nil && rr.Error == nilout["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.goindex 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 *ResuscoredAsImage 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.mdindex 5396f4a39..e17f7999a 100644--- a/website-docs/03-features/16-observability.md+++ b/website-docs/03-features/16-observability.md@@ -136,6 +136,23 @@ flowchart LRG --> 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 上。