Lesson 02 — 全链路追踪：接入 Langfuse

传统服务：  请求 → 查库 → 返回          （2 步，日志够看）
LLM 服务：  请求 → 改写 → 检索 → rerank → 生成 → 后处理   （5+ 步，每步都可能出问题）
                          │         │          │
                       每步都要看  哪步最慢  烧了多少 token

trace（一次完整请求）
  │  例：用户问 "试用期多久"
  │
  ├── span（一个步骤/操作）
  │     例：condense 改写问题
  │     记录：name / input / output / start_time / end_time
  │
  ├── span：retrieve 检索
  │     └── span：rerank 重排          ← span 可以嵌套（树形！）
  │
  └── generation（一次 LLM 调用 —— 特殊的 span）
        额外记录：model / usage(input/output tokens) / cost
        例：glm-4 生成答案，in=820 tokens, out=210 tokens

单次 generation 成本 = input_tokens × 输入单价 + output_tokens × 输出单价

改写（flash）：in=200 out=30  → 免费（flash）
生成（glm-4）：in=820 out=210 → (820+210)×50/1e6 ≈ 0.0515 元

from langfuse import get_client

lf = get_client()  # 从环境变量读 host/public_key/secret_key；没配则自动 no-op

# ① 开一个 trace（一次问答）
with lf.start_as_current_observation(as_type="span", name="kb_qa.ask") as trace:
    trace.update(input=question, metadata={"thread_id": ..., "mode": ...})

    # ② 子 span：检索（嵌套在 trace 下 → 自动成树）
    with lf.start_as_current_observation(as_type="span", name="retrieve") as span:
        docs = retrieve(query)
        span.update(input=query, output=[d.page_content for d in docs],
                    metadata={"hits": len(docs)})

    # ③ generation：生成（带 model + usage）
    with lf.start_as_current_observation(
        as_type="generation", name="answer", model="glm-4"
    ) as gen:
        answer, usage = generate(...)
        gen.update(input=..., output=answer,
                   usage={"input": usage.in, "output": usage.out, "unit": "TOKENS"})

lf.flush()  # 异步上报，退出前 flush 确保不丢

                 tracing.py 初始化时探测
                         │
            ┌────────────┴────────────┐
       有 Langfuse SDK              无 SDK
            │                          │
   LANGFUSE_HOST 配了？           用 ConsoleTracer
      │         │                  （把 trace 树打印到控制台）
     配了      没配                    │
      │         │                  效果：不依赖任何外部服务
   真实上报   ConsoleTracer          也能看到完整的树形链路
              （本地调试常用）

cd ops-lessons/02_langfuse_tracing
python code.py

cd portfolio-projects/knowledge-base-qa
# 不配任何 Langfuse 环境变量 → 自动降级打印 trace 树
python -m pytest tests/test_tracing.py -q
# 看一次问答的 trace 树（需 ZHIPUAI_API_KEY；无则看降级输出）
python -c "
import sys; sys.stdout.reconfigure(encoding='utf-8')
import asyncio
from kb_qa.tracing import flush
from kb_qa.service import stream_ask
async def go():
    async for ev in stream_ask('云帆科技试用期多久？', 'demo'):
        pass
    flush()
asyncio.run(go())
" 2>&1 | grep -A20 "trace"

cd portfolio-projects/knowledge-base-qa
docker compose -f docker-compose.langfuse.yml up -d   # 起 Langfuse
# 在 .env 配 LANGFUSE_HOST / LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY（面板里建项目获得）
# 然后跑问答，打开 http://localhost:3000 看 trace