Langfuse：开源的 LLM 应用观测与调试平台

综合介绍

Langfuse 是一个开源的 LLM（大语言模型）工程平台。它帮助开发者追踪、调试和优化 LLM 应用，提供观测调用、管理提示词、运行实验和评估结果的工具。平台由 Langfuse 团队开发，支持 LangChain、OpenAI 等框架，采用 MIT 许可证，社区活跃。它可以快速自托管到本地或云端，适合团队协作开发可靠的 AI 应用。Langfuse 提供云服务（有免费套餐）和自托管选项，部署简单，经过生产环境验证。

对 Agents 和 RAG 运行过程可视化观测，和 LangSmith 类似。

功能列表

• 应用观测: 追踪 LLM 应用的每次调用，记录输入输出、延迟和成本。
• 提示管理: 集中存储提示词，支持版本控制和团队协作调整。
• 数据集管理: 创建测试数据集，运行实验对比模型或提示效果。
• 评估工具: 支持用户反馈、手动标注和自动化评估，检查输出质量。
• 调试支持: 查看详细日志和用户会话，快速定位问题。
• 实验 playground: 测试提示词和模型配置，加速开发迭代。
• 多框架支持: 兼容 LangChain、OpenAI SDK、LiteLLM 等。
• API 集成: 提供全面 API，定制 LLMOps 工作流。

使用帮助

安装与部署

云服务

1. 注册账号: 访问 Langfuse 云端，点击“Sign Up”注册。
2. 创建项目: 登录后，点击“New Project”，输入项目名称。
3. 获取密钥: 在项目设置中生成 PUBLIC_KEY 和 SECRET_KEY。
4. 开始使用: 无需安装，直接通过 SDK 连接云服务。

本地部署（Docker Compose）

1. 准备环境: 确保已安装 Docker 和 Docker Compose，可从 Docker 官网 下载。
2. 克隆代码: 在终端运行 git clone https://github.com/langfuse/langfuse.git，然后进入目录 cd langfuse。
3. 启动服务: 输入 docker compose up，等待启动完成，默认地址为 http://localhost:3000。
4. 验证: 浏览器访问 http://localhost:3000，看到登录页面即成功。
5. 配置密钥: 注册后在 UI 中生成密钥，用于 SDK。

Kubernetes 部署（生产推荐）

1. 准备集群: 使用 Minikube（本地测试）或云服务（如 AWS）创建 Kubernetes 集群。
2. 添加 Helm: 运行 helm repo add langfuse https://langfuse.github.io/langfuse-k8s 和 helm repo update。
3. 配置: 创建 values.yaml，填入数据库和密钥信息（参考 官方文档）。
4. 部署: 输入 helm install langfuse langfuse/langfuse -f values.yaml，等待完成。
5. 访问: 根据 Ingress 配置访问服务地址。

虚拟机部署

• 在单台虚拟机上运行 docker compose up，适合小型生产环境，具体步骤同本地部署。

主要功能操作

应用观测

1. 安装 SDK: Python 项目运行 pip install langfuse，JS/TS 项目运行 npm install langfuse。
2. 初始化: 在代码中配置密钥和主机：

   from langfuse import Langfuse
   langfuse = Langfuse(public_key="pk-lf-xxx", secret_key="sk-lf-xxx", host="http://localhost:3000")

3. 记录调用: 使用装饰器或手动追踪：

   from langfuse.decorators import observe
   @observe()
   def chat(input):
   return openai.chat.completions.create(model="gpt-3.5-turbo", messages=[{"role": "user", "content": input}])
   chat("你好")
   

4. 查看: 在 UI 的 “Traces” 页面，检查调用详情。

提示管理

1. 新建提示: 在 UI 的 “Prompts” 页面，点击 “New Prompt”，输入名称和内容，例如：

   System: 你是一个助手，直接回答问题。
   User: {{question}}
   

2. 使用提示: 代码中调用 langfuse.get_prompt("prompt-name")。
3. 版本管理: 修改提示后自动保存版本，可回滚。

数据集与实验

1. 创建数据集: 在 UI 的 “Datasets” 页面，点击 “Create Dataset”，命名如 “qa-test”。
2. 添加数据: 输入或上传 CSV，例如：

   Input: "1+1等于几？" Expected: "2"
   

3. 运行实验: 在代码中测试：

   dataset = langfuse.get_dataset("qa-test")
   for item in dataset.items:
   result = chat(item.input)
   item.link(langfuse.trace({"output": result}), "test-1")
   

4. 分析: 在 UI 查看实验结果。

Playground

1. 进入: 在 UI 点击 “Playground”，输入提示词和模型参数。
2. 测试: 点击运行，查看输出，调整参数后保存。
3. 跳转: 从 “Traces” 的错误结果直接进入 Playground 修改。

特色功能操作

调试日志

• 在 “Traces” 页面，点击某次调用，查看输入输出和上下文。
• 在 “Sessions” 查看用户会话，分析多轮对话。

评估输出

• 手动: 在 “Scores” 页面为输出评分（0-1）。
• 自动: 通过 API 添加评估：

  langfuse.score(trace_id="xxx", name="accuracy", value=0.95)
  

API 使用

• 使用 OpenAPI 规范或 SDK（如 Python/JS）调用，例如创建追踪：

  curl -X POST "http://localhost:3000/api/traces" -H "Authorization: Bearer sk-lf-xxx" -d '{"id": "trace-1", "name": "test"}'
  

应用场景

1. RAG流程可视化追踪
   • 从关键词召回、向量召回、召回融合、重排、回答整体流程的可视化追踪
2. 开发智能客服
   • 团队用 Langfuse 追踪对话，优化回答质量，提升客户体验。
3. 模型性能对比
   • 开发者创建数据集，测试多个 LLM 在问答任务上的表现。
4. 企业内部部署
   • 公司自托管 Langfuse，保护敏感数据，调试内部 AI 应用。

QA

1. 支持哪些语言和框架？
   • 支持 Python 和 JS/TS，兼容 LangChain、OpenAI、LlamaIndex 等。
2. 自托管的最低配置是什么？
   • 小型项目用 2 核 CPU 和 4GB 内存，大型建议 8 核 16GB。
3. 如何禁用遥测？
   • 在环境变量中设置 TELEMETRY_ENABLED=false。