Leonx AI

LiteLLM与langfuse集成

Table of Contents

为什么需要将LiteLLM与Langfuse集成？ #

上一篇 介绍了LiteLLM (如何使用AI 网关(LiteLLM): 统一管理AI大语言模型接入) 但是在企业级AI应用部署中，仅有一个统一的API网关是不够的。随着AI应用规模的扩大，我们还需要全面的可观测性和监控能力，以便：

  1. 追踪模型性能 - 了解不同模型在各种场景下的响应时间、成功率和质量
  2. 分析使用模式 - 识别高频查询、用户行为模式和潜在的优化机会
  3. 成本管理 - 精确追踪每个团队、项目或功能的AI使用成本
  4. 质量保证 - 监控模型输出质量，及时发现异常或退化情况

这就是为什么将LiteLLM与Langfuse集成变得如此重要。

Langfuse简介 #

Langfuse是一个专为LLM应用设计的开源可观测性平台，提供了全面的追踪、评估和监控功能。它能够：

  • 记录所有LLM交互的详细信息
  • 提供直观的仪表板，展示性能指标和使用统计
  • 支持自定义标签和分组，便于多维度分析
  • 实现成本追踪和分配
  • 提供评分和反馈机制，帮助改进模型输出质量

集成优势 #

将LiteLLM与Langfuse结合使用，可以获得以下优势：

  1. 统一管理与全面监控 - LiteLLM提供统一的API接入层，而Langfuse提供深入的可观测性
  2. 无缝数据流 - 所有通过LiteLLM的请求自动被记录到Langfuse，无需额外代码
  3. 细粒度分析 - 可以按模型、团队、项目或任何自定义维度分析性能和成本
  4. 闭环优化 - 基于Langfuse的数据洞察，可以优化LiteLLM的路由策略和模型选择

实施步骤 #

1. 安装 Langfuse #

  1. 克隆 Langfuse 仓库
git clone https://github.com/langfuse/langfuse.git
cd langfuse
  1. 配置环境变量 在 docker-compose.yml 文件中配置必要的环境变量：
  • POSTGRES_PASSWORD: PostgreSQL 数据库密码
  • NEXTAUTH_SECRET: NextAuth 密钥
  • NEXTAUTH_URL: 应用访问地址（默认为 http://localhost:3000）
  1. 启动服务
docker compose up -d

  1. 等待服务就绪 等待约 2-3 分钟，直到看到 langfuse-web-1 容器日志显示 “Ready”。

  2. 访问界面 打开浏览器访问 http://localhost:3000 即可进入 Langfuse 管理界面。

2. 配置 LiteLLM 集成 #

如果还没有安装 LiteLLM，请参考：如何使用AI 网关(LiteLLM): 统一管理AI大语言模型接入

2.1 配置 LiteLLM 配置文件 #

编辑 config.yaml：

# https://docs.litellm.ai/docs/proxy/logging#langfuse
litellm_settings:
  success_callback: ["langfuse"]

2.2 配置环境变量 #

编辑 .env 文件：

# Langfuse 配置
LANGFUSE_PUBLIC_KEY="pk-lf-xxxxxxxx-0000-xxxx-xxxx-xxxxxxxxxxxx"
LANGFUSE_SECRET_KEY="sk-lf-xxxxxxxx-6767-xxxx-xxxx-xxxxxxxxxxxx"
# Optional, defaults to https://cloud.langfuse.com
LANGFUSE_HOST="http://localhost:3000"

2.3 重启 LiteLLM 服务 #

# 重启 LiteLLM 服务使配置生效
cd litellm
docker-compose restart

3. 使用示例 #

LiteLLM 支持通过 HTTP Header 和请求体两种方式传递追踪信息。

3.1 通过 HTTP Header 传递 #

curl http://localhost:4000/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H 'langfuse_trace_user_id: user-grayson' \
  -H 'langfuse_trace_session_id: oa-test-id-hello-word' \
  -H 'langfuse_trace_environment: local' \
  -d '{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "system",
      "content": "你是一个助手. 叫 李四1"
    },
    {
      "role": "user",
      "content": "how are you? what your name?"
    }
  ]
}'

3.2 通过请求体传递 #

curl http://localhost:4000/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -d '{
  "model": "gpt-4o-mini",
  "metadata": {
    "session_id": "oa-test-id-hello-word",
    "user_id": "user-grayson",
    "trace_environment": "staging",
    "trace_metadata": {"subdomain": "demo-full", "custom": "hello"}
  },
  "messages": [
    {
      "role": "system",
      "content": "你是一个助手. 叫 李四三"
    },
    {
      "role": "user",
      "content": "how are you? what your name?"
    }
  ]
}'

4. 效果展示 #

Langfuse 追踪界面 Langfuse 会话详情 Langfuse 性能分析

参考文档 #