Langfuse Python SDK — Trace LLM Apps

简介

Langfuse Python SDK 用 decorators 或底层事件把你的 LLM 应用接入可观测性：记录 traces、延迟、token 成本、prompt/response，上线后也能快速定位回归。

• 适合谁： 需要把 prompt、工具与多供应商调用统一纳入追踪的 Python LLM 应用
• 可搭配： Python；支持 decorators 或底层事件；可配任意 LLM/provider（见 README）
• 准备时间： 5–20 分钟

实战建议

• README 提示：SDK 在 2026 年 3 月发布 v4 重写版本，升级前先看迁移指南。
• 先从一个关键入口（chat/tool router）开始埋点，再扩到工具调用与后台任务。
• 只记录你能长期保留的内容：把 secrets/PII 在入库前做脱敏或过滤。

主要内容

避免“过度埋点”的做法：

1. 先选一条黄金路径（用户问题 → 工具调用 → 最终回答）。
2. 只在边界处埋点：请求进入、模型调用、工具调用、响应返回。
3. 先记录 输入/输出 + 耗时，基础稳定后再逐步加用户标签、数据集等元信息。
4. 做一个最小回归看板：最慢 traces、最高错误率、最大 prompt 体积。

最快收益通常来自定位哪一步最“吃 token”（检索、工具结果、prompt 模板），然后只优化那一步。

FAQ

必须绑定某个模型/供应商吗？ 答：不需要。README 表示可配任意 LLM/框架；更重要的是把 trace context 做一致。

要不要记录完整 prompt？ 答：看合规。建议对敏感字段做脱敏 + 抽样；保留能复现问题的最小上下文即可。

升级最容易踩什么坑？ 答：大版本重写可能改事件结构；上线前按 v4 迁移指南做对照验证。