Day 19 / 共 20 天 · 第 4 周 Agent/Workflow/生态

可观测与评估（从"能跑"到"能上线"）

RAG/Agent 是"黑盒"——检索了啥、LLM 想了啥、花了多少钱、答得好不好都看不见。今天两套工具：可观测（追踪内部）+ 评估（打分衡量质量）。

📍 你在整条链的位置（RAG/Agent 全学完，收尾工程化）
RAG + Agent + 记忆→ 可观测 + 评估（工程化）→ 收官 D20
L01

黑盒问题

🤔 "答错了，但不知道错在哪" RAG 答错了——是检索没找到对的？还是找到了但 LLM 没用好？花了多少钱（token）？Agent 调了哪些工具、想了什么？不观测就是抓瞎。而且怎么客观衡量"这个系统好不好"？改了参数是变好还是变差？
💡 可观测（看内部）+ 评估（打分） 可观测让你看到每一步发生了什么；评估给系统质量打分。它们是 RAG 从 demo 走向生产的必经之路。
L02

callbacks 回调

callbacks/：CallbackManager + handler（LlamaDebugHandler、TokenCountingHandler）。CBEventType 定义事件类型（RETRIEVE/LLM/EMBEDDING/QUERY）。

读法：回想前几天代码里到处的 callback_manager.event(CBEventType.RETRIEVE, ...)（Day 11/12）——那就是埋点。CallbackManager 在每个关键步骤发事件，handler 接收后可打印/计时/统计。LlamaDebugHandler 打印每步详情（调试神器）。
L03

instrumentation：新一代追踪

instrumentation/（较新，逐步取代 callbacks）：基于 dispatcher 的事件系统——回想 Day 11 dispatcher.event(RetrievalStartEvent(...))、@dispatcher.span。

💡 span（时间区间）+ event（结构化事件） span 记"这次检索耗时 200ms"，event 记结构化信息。注册 handler 就能收到框架各处的事件（检索开始/结束、LLM 调用、Agent 每步），实现完整链路追踪。接近现代 APM 模型（回想 Envoy/Istio 的追踪）。
L04

token 计数：盯着钱

callbacks/token_counting.py 的 TokenCountingHandler：统计嵌入 token、LLM 提示 token、LLM 生成 token。

📝 一次 query 的 token 账单 嵌入问题（~30 token）+ 检索内容塞进提示（~3000 token）+ 生成答案（~200 token）
→ 发现"提示 token 太高"？说明 top_k 太大或切块太大 → 调小省钱。
token = 钱，生产必须盯 LLM 和嵌入都按 token 收费。TokenCountingHandler 帮你算清每部分用量，直接关系成本。回想 wasm-go/Higress 的 tokenusage——AI 应用都要盯 token。
L05

第三方追踪平台

通过 instrumentation/callbacks，接入第三方可观测平台：Arize Phoenix、LangSmith、Langfuse、OpenTelemetry。set_global_handler("arize_phoenix") 一行开启。

可视化链路追踪 这些平台提供 UI——一次 query 的每步（检索了哪些 Node、分数、LLM 完整提示和输出、耗时）都能可视化。调试复杂 RAG/Agent 比看日志高效得多。Phoenix 还能做评估。生产 RAG 的标配——线上出问题能快速定位。
L06

evaluation：用 LLM 当裁判打分

evaluation/：FaithfulnessEvaluator、RelevancyEvaluator、CorrectnessEvaluator、RetrieverEvaluator，多用 LLM-as-judge。

🤔 RAG 答案好不好难量化（不像分类有标准答案） 怎么客观打分？
💡 让一个强 LLM 当"裁判"给答案打分 • Faithfulness（忠实度）：答案是不是真的基于检索资料（没瞎编）？
• Relevancy（相关性）：答案和检索内容跟问题相关吗？
• Correctness（正确性）：对比参考答案，答对了吗？
让裁判 LLM 读"问题+资料+答案"，打分 + 给理由。这样能批量、客观衡量质量——改了参数跑一批评估，看分数升降。
L07

检索 vs 生成评估：分段定位

💡 RAG 评估分两段 • 检索评估（RetrieverEvaluator）：检索出的 Node 里有没有正确答案所在的（hit rate、MRR）。
• 生成评估（Faithfulness/Relevancy/Correctness）：基于检索内容，答案生成得好不好。
分段才能定位问题（呼应 Day 20 调优清单） 答错了，是"没检索到对的"（检索问题）还是"检索到了但没答好"（生成问题）？分段评估告诉你：
检索分低 → 改切块/嵌入/检索策略（W1-2、D11/14）；
生成分低 → 改提示词/合成模式/LLM（D13-15）。让 RAG 调优有的放矢——先测哪段弱、再针对优化。
RAG 流水线 · 两段独立评估 问题 检索 Retriever 生成 合成器 + LLM 答案 检索出的 Nodes 检索评估 RetrieverEvaluator hit rate · MRR 生成评估（LLM-judge） Faithfulness · Relevancy · Correctness 检索分低 → 改切块 / 嵌入 / 检索策略（D11/14） 生成分低 → 改提示词 / 合成模式 / LLM（D13-15）
检索段与生成段各自打分，答错时按分段结果定位是"没检索到"还是"没答好"，再针对性调优
L08

今日小结 + 动手

🧠 今天你应该能回答

  • 为什么 RAG/Agent 需要可观测和评估？
  • callbacks/instrumentation 怎么追踪内部？token 为什么要盯？
  • evaluation 怎么用 LLM-as-judge 打分？三个维度？
  • 检索评估 vs 生成评估——为什么要分段？

✋ 动手

cd /Users/bitmart/work/codes/github/llama_index/llama-index-core/llama_index/core
ls callbacks/ instrumentation/ evaluation/
grep -n "class TokenCountingHandler" callbacks/token_counting.py | head
grep -rn "class FaithfulnessEvaluator\|class RetrieverEvaluator" evaluation/*.py 2>/dev/null | head
明天预告 · Day 20（收官）：部署 + 收官串讲——core vs integrations、RAG 全链路回顾、设计智慧、RAG 调优清单、和你学过的其他框架对比，画上圆满句号。
← Day 18 Day 20 · 收官串讲 →