返回转载
Agent开发应知应会：Langfuse 的两种使用方式
2026年2月11日
通过 Text-to-SQL Agent 项目实战，讲解 Langfuse 的自动 Callback 集成与手动 Span 追踪两种方式
这篇文章基于作者开发的 Text-to-SQL Agent 项目，分享了如何通过 Langfuse 解决 LLM 应用开发中的"黑盒"问题（如内部调用链路不清晰、Token 消耗不明等）。
什么是 Langfuse？
Langfuse 是一个 LLM 应用的可观测性平台，帮助开发者追踪和调试 Agent 的执行过程。
两种集成方式
1. 自动 Callback 集成（推荐入门）
原理：利用 LangChain/LangGraph 框架内置的回调机制，通过 CallbackHandler 自动捕获 LLM 调用、工具调用及链路执行过程。
优点：
- 零侵入、配置简单
- 自动记录输入输出、Token 用量、延迟等
局限：
- 仅能追踪框架内部的逻辑
- 对于框架外的自定义 Python 代码（如数据库查询）不可见
- 对 Trace 结构的控制力较弱
2. 手动 Span 追踪（适合进阶）
原理：直接使用 Langfuse SDK，通过装饰器或上下文管理器手动创建 Span，以记录业务层面的关键信息。
用途：
- 在细粒度追踪之上添加"业务汇总层"
- 直接记录最终生成的 SQL、验证结果及迭代轮次
- 便于在 Dashboard 中快速查看执行结果
最佳实践
文章建议在实际项目中结合使用这两种方式：
- Callback：自动捕获技术细节
- 手动 Span：附加业务语义信息
从而实现既有深度又有概览的完整可观测性。
详细代码示例请阅读原文