LiteLLM SDK 集成

在本指南中，我们将演示如何使用 LiteLLM SDK 捕获 LLM 调用并将其记录到 Litefuse。

什么是 LiteLLM？ LiteLLM 是一个开源代理与 SDK，提供统一的 API，可通过 OpenAI 兼容的 endpoint 调用并管理数百种不同的 LLM 提供方与模型。

什么是 Litefuse？ Litefuse 是一个开源的 AI Agent 可观测性与评估平台，帮助你 trace、监控并调试你的 LLM 应用。

将 LiteLLM 与 Litefuse 集成有三种方式：

使用 LiteLLM SDK 直接捕获 LLM 调用。
通过 LiteLLM Proxy 发送日志，捕获所有经过代理的 LLM 调用。
使用任意兼容框架（如 OpenAI 或 LangChain SDK）来捕获 LLM 调用。

本集成针对 LiteLLM SDK。如果你想要 LiteLLM Proxy 的集成，请查看 LiteLLM Proxy 集成页面。

特性

自动收集所有 LiteLLM 请求的 trace
支持 Litefuse Cloud
支持自托管 Litefuse 实例
自定义 endpoint 配置
使用 Basic Auth 进行安全鉴权
与其他 OTEL 集成保持一致的属性映射

前置条件

Litefuse 账号：在 Litefuse Cloud 注册或搭建一个自托管实例
API Key：从 Litefuse 项目设置中获取你的 public 和 secret Key

依赖：安装所需依赖：

pip install litellm opentelemetry-api opentelemetry-sdk opentelemetry-exporter-otlp

配置

环境变量

变量	是否必填	描述	示例
`LANGFUSE_PUBLIC_KEY`	是	你的 Litefuse public key	`pk-lf-...`
`LANGFUSE_SECRET_KEY`	是	你的 Litefuse secret key	`sk-lf-...`
`LANGFUSE_OTEL_HOST`	否	OTEL endpoint 主机	`https://otel.my-litefuse.ai`

Endpoint 解析

集成会自动从 LANGFUSE_OTEL_HOST 构造 OTEL endpoint

默认（US）：https://litefuse.cloud/api/public/otel
EU 区域：https://litefuse.cloud/api/public/otel
自托管：{LANGFUSE_OTEL_HOST}/api/public/otel

使用

基础设置

import os
import litellm
 
# Set your Langfuse credentials
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."
 
# Enable Langfuse OTEL integration
litellm.callbacks = ["langfuse_otel"]
 
# Make LLM requests as usual
response = litellm.completion(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello!"}]
)

高级配置

import os
import litellm
 
# Set your Langfuse credentials
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."
 
os.environ["LANGFUSE_OTEL_HOST"] = "https://litefuse.cloud"
# os.environ["LANGFUSE_OTEL_HOST"] = "https://otel.my-litefuse.company.com"  # custom OTEL endpoint
 
# Or use self-hosted instance
# os.environ["LANGFUSE_OTEL_HOST"] = "https://my-litefuse.company.com"
 
litellm.callbacks = ["langfuse_otel"]

手动 OTEL 配置

如果你需要直接控制 OpenTelemetry 配置：

import os
import base64
import litellm
 
# Get keys for your project from the project settings page: https://litefuse.cloud
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..." 
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..." 
os.environ["LANGFUSE_OTEL_HOST"] = "https://litefuse.cloud"
# os.environ["LANGFUSE_OTEL_HOST"] = "https://otel.my-litefuse.company.com" # custom OTEL endpoint
 
LANGFUSE_AUTH = base64.b64encode(
    f"{os.environ.get('LANGFUSE_PUBLIC_KEY')}:{os.environ.get('LANGFUSE_SECRET_KEY')}".encode()
).decode()
 
host = os.environ.get("LANGFUSE_OTEL_HOST")
os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = host + "/api/public/otel"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Basic {LANGFUSE_AUTH}"
 
litellm.callbacks = ["langfuse_otel"]

配合 LiteLLM Proxy

将集成添加到你的代理配置中：

将凭证添加到环境变量

export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_OTEL_HOST="https://litefuse.cloud"
# export LANGFUSE_OTEL_HOST="https://otel.my-litefuse.company.com"  # custom OTEL endpoint

配置 config.yaml

# config.yaml
litellm_settings:
  callbacks: ["langfuse_otel"]

运行代理

litellm --config /path/to/config.yaml

收集的数据

集成会自动收集以下数据：

请求详情：模型、消息、参数（temperature、max_tokens 等）
响应详情：生成内容、token 使用、完成原因
时序信息：请求耗时、首 token 时延
元数据：用户 ID、会话 ID、自定义标签（若提供）
错误信息：异常详情与堆栈跟踪（若发生错误）

元数据支持

原生 Litefuse 集成中提供的所有元数据字段，在使用 OTEL 集成时也都完全支持。

你在 metadata 字典中传入的任何 Key（generation_name、trace_id、session_id、tags 等）都会作为 OpenTelemetry span 属性导出。
属性名前缀为 langfuse.，便于在你的可观测性后端中筛选或搜索。示例：langfuse.generation.name、langfuse.trace.id、langfuse.trace.session_id。

传递元数据 – 示例

response = litellm.completion(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello!"}],
    metadata={
        "generation_name": "welcome-message",
        "trace_id": "trace-123",
        "session_id": "sess-42",
        "tags": ["prod", "beta-user"]
    }
)

生成的 span 将包含类似如下属性：

langfuse.generation.name   = "welcome-message"
langfuse.trace.id          = "trace-123"
langfuse.trace.session_id  = "sess-42"
langfuse.trace.tags        = ["prod", "beta-user"]

使用 Litefuse UI（Traces 标签页）可以搜索、过滤并分析包含 langfuse.* 属性的 span。本集成中的 OTEL exporter 直接将数据发送到 Litefuse 的 OTLP HTTP endpoint；它并不用于 Grafana、Honeycomb、Datadog 或其他通用 OTEL 后端。

鉴权

本集成使用 HTTP Basic Authentication，凭证为你的 Litefuse public 与 secret Key：

Authorization: Basic <base64(public_key:secret_key)>

这部分由集成自动处理 —— 你只需通过环境变量提供 Key。

排错

常见问题

凭证缺失错误
```
ValueError: LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY must be set
```
解决：确保两个环境变量均已设置且 Key 有效。
连接问题
- 检查你的网络连接
- 验证 endpoint URL 正确
- 对于自托管实例，确保可以访问到 /api/public/otel endpoint
鉴权错误
- 验证你的 public 与 secret Key 正确
- 检查 Key 是否属于同一个 Litefuse 项目
- 确保 Key 拥有所需权限

调试模式

启用详细日志查看具体信息：

SDK：

import litellm
litellm._turn_on_debug()

Proxy：

export LITELLM_LOG="DEBUG"

将显示：

Endpoint 解析逻辑
鉴权 header 创建
OTEL trace 提交详情