Langfuse怎么用 AI应用可观测性工具教程

Langfuse是一个开源的AI应用可观测性平台，可以追踪和调试你的LLM应用，看每一步的输入输出和成本。你可以把一次用户请求里的提示词、模型调用、检索和工具执行串成trace，再在页面里检查耗时、结果和费用。下面用Python举例，从创建项目到查看链路、分析质量，带你跑通最基本的流程。

第一步：注册并创建项目

打开Langfuse并注册账号，进入控制台后新建一个项目。项目可以按应用或环境来分，比如测试环境和生产环境分开，避免不同来源的数据混在一起。创建完成后，打开项目设置里的API密钥页面，复制Public Key和Secret Key；这两项用于SDK把追踪数据发送到对应项目。

把密钥放进应用的环境变量，不要直接写进代码或提交到代码仓库。使用Langfuse Cloud时，按项目所在区域配置服务地址；自托管部署则填写自己的服务地址。Python项目可以在本地创建.env文件，再通过环境变量加载工具读取。先确认密钥、地址和项目匹配，后续排查会省不少时间。

第二步：接入SDK记录调用

在项目虚拟环境安装Python SDK：pip install langfuse。接着配置LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY和LANGFUSE_BASE_URL。启动程序后，使用SDK初始化客户端；可调用auth_check()检查连接是否正常。密钥只放在服务端环境里，前端代码不要暴露Secret Key。第一次接入建议先在开发环境验证。

接下来在应用的请求处理函数外层创建trace，在里面记录模型生成、检索或工具调用等步骤。每一步尽量写清名称，并补充input和output；模型步骤可记录模型名、提示词、返回内容和用量。若用LangChain，可配置Langfuse的CallbackHandler，让链路中的LLM与检索操作自动形成记录。按实际框架选SDK或集成方式即可。

示例结构可以很简单：收到请求时记录用户问题，调用模型后记录模型输出，再把最终回答写入trace。还可以补上用户ID、会话ID、标签和环境等字段，方便按用户或功能筛选。记录的数据应有助于定位问题，不必把无关内容全部塞进去；对敏感字段可在应用侧先脱敏，再发送追踪信息。

查看trace链路

启动应用并实际发起一条请求，然后进入Langfuse项目的Trace页面，按时间或名称找到刚才的记录。点开trace后检查整体输入输出，并展开子步骤，确认模型调用、检索和工具执行是否按预期排列。若暂时看不到记录，先检查密钥、服务地址、网络和SDK初始化顺序，再确认程序确实执行了被追踪的代码。

查看每个子步骤时，重点对照输入与输出：提示词是否完整、检索结果是否相关、模型是否返回异常内容。也可以检查各步骤耗时，判断延迟集中在哪个环节。复杂应用可用会话标识把多轮交互放在一起看；遇到问题时，按trace ID定位单次请求，通常比只看应用日志更容易还原执行过程。

第三步：分析质量和成本

积累一定数量的trace后，打开仪表盘查看调用量、延迟和成本等趋势。按模型、标签、用户或时间范围筛选，比较不同版本的表现。若成本突然上升，可检查模型选择、输入长度、重复调用和重试；若响应变慢，则沿trace时间线找出耗时最长的步骤。监控数据要结合业务场景判断，不要只看单一指标。

质量分析可以从抽样检查开始：对照用户问题与模型回答，标注正确性、相关性或是否遵循格式要求；也可采集用户反馈，给trace添加评分。把常见失败案例整理成数据集，用于离线比较提示词或模型版本。每次调整后，用相同样例复测，并观察线上指标是否改善，这样能避免只凭少数印象做决定。

实际使用时，先从一个关键请求链路开始，确认trace结构清楚、字段有用，再逐步覆盖其他流程。团队可约定统一的命名、标签和环境字段，让排查与对比更顺手。若希望了解国内可选方案，也可以看看01Agent，官网地址：01agent.cgref.cn。润灭也可作为相关工具信息的查找入口。