AI Agent——可观测性链路集成&评测体系搭建（Langfuse）

文章目录

• • 一、前言
  • 相关资料
  • Langfuse核心特点解析
  • Langfuse实战
  • • [Langfuse tracing](#Langfuse tracing)
    • [Langfuse prompt](#Langfuse prompt)
    • [Langfuse datasets](#Langfuse datasets)
    • Langfuse评测
  • 总结：Langfuse的适配场景与落地建议

一、前言

继上篇：AI Agent------后时代的LangChain&LangGraph

在项目落地最新的LangChain1.0版本后，我研究了LangSmith这LangChain官方推介的日志管理和任务追踪（Trace），发现其部署及其简单，仅需3行代码，无侵入式即可部署。

但缺点是需要对接云端license认证，不适合我们这种内网项目 。

于是，通用的langfuse项目进入了我的视野。

相关资料

• 官方官网：https://langfuse.com（可切换云服务与自托管指南，提供核心功能演示）

• GitHub仓库：https://github.com/langfuse/langfuse（开源核心代码，含部署脚本与更新日志）

• 官方文档：https://docs.langfuse.com（含快速入门、API参考、自托管部署教程等）

• Python SDK文档：https://docs.langfuse.com/python（适配LangChain/LangGraph的集成指南）

• JavaScript/TS SDK文档：https://docs.langfuse.com/js（前端与Node.js环境集成说明）

• 自托管部署指南：https://docs.langfuse.com/self-hosting（Docker Compose/K8s/Terraform部署方案）

• LangChain集成示例：https://docs.langfuse.com/integrations/langchain（含回调配置与链路追踪实操）

• 实战示例库：https://github.com/langfuse/langfuse-examples（多场景集成案例，含多智能体监控）

Langfuse核心特点解析

作为开源LLM工程化平台，Langfuse以"全生命周期管理"为核心，相较于LangSmith等工具，其特点更贴合内网项目的隐私需求与定制化场景，具体如下表所示：

特点类别	详细说明
部署灵活：自托管与云服务双适配	支持自托管**（Docker Compose/K8s/Terraform）与云托管两种模式**，自托管可部署至内网集群，数据本地存储无云端依赖 。docker-compose链接：https://langfuse.com/self-hosting/deployment/docker-compose
功能全面：覆盖LLM应用全生命周期	涵盖"开发-测试-生产-优化"全流程，核心含可观测性、提示工程、评估体系、性能监控；
集成高效：无缝对接主流框架与模型	高适配LangChain/LangGraph，注入CallbackHandler即可无侵入式集成，
自带评测集体系	可将生产环境的调用问题一键集成到数据集，配合提示词从而实现评测体系，并实时更新评测集

Langfuse实战

Langfuse tracing

详细可直接看官网：https://langfuse.com/docs/observability/get-started

该链接贴了具体的操作视频；这里选重点介绍：

链路追踪是基础能力，但利用好链路追踪，就可以对测试、生产环境，每个Agent内部的上下文扭转、跟模型的交互等都做到一目了然，是非常重要的能力。

Langfuse prompt

提示词管理，Langfuse支持提示词按版本管理 。然后联动数据集形成评测体系。比如如图，我构建了第一版的提示词，可以看到，支持 提示词新增版本、复制提示词等能力。

Langfuse datasets

数据集支持手动创建和通过tracing里的真实请求进行创建。

Langfuse评测

如何匹配prompt和datasets？通过变量的方式，具体如下：

1. 在提示词里指定变量，比如指定{{user_prompt}}、{{data}}，两个变量（用花括号指定）
2. 在datasets的每条数据格式为: {"user_prompt": "这是用户输入", "data"："这是额外的上下文"}
3. 在评测的时候，就可以通过prompt+datasets的变量匹配，实现messages组合。
4. 这里注意：变量可以不用完全填写，数据集只要具备一个变量以上即可完成评测
5. 评测LLM，Langfuse内嵌了一些评测LLM，也可以自定义，具体如下：
   

总结：Langfuse的适配场景与落地建议

Langfuse的核心价值在于"开源可控+全流程支撑"，尤其适合对数据隐私有严格要求的内网项目、需要定制化观测逻辑的复杂Agent应用，以及追求性价比的中小团队。若你的项目是基于LangChain1.0/LangGraph构建的多步骤、多智能体系统，且需规避云端依赖，Langfuse将是LangSmith的最优替代方案。

落地建议方面，初期可通过Docker Compose快速搭建测试环境，验证链路追踪与评估功能的适配性；生产环境建议结合K8s部署，搭配内网数据库（如PostgreSQL）存储追踪数据，并对接内网告警系统实现异常实时感知。对于定制化需求，可基于开源代码扩展中间件，实现与内网业务系统的深度联动。

Langfuse部署后，整个链路清晰可见，无论是项目迭代还是后续的任务追踪，都是非常好的开源项目。