Skip to main content

Python SDK 概述

兼容说明
  • 如果您使用 Dify 开发 AI 应用，请参考《使用 Dify 进行数据上报》文档进行配置。
  • 如果您使用 Python 开发自己的 AI 应用，可以继续阅读本文。
  • Lighthouse 完全兼容 Langfuse SDK，您可以使用 Langfuse Python SDK 来采集 LLM 应用的可观测性数据。

Langfuse Python SDK 提供了两种使用方式：

  • 装饰器 API：推荐使用，提供简单直观的使用方式
  • Low Level SDK：提供更灵活、更细节的控制，适用于特殊场景

安装

前置条件

确保您的环境满足以下要求：

  • Python 3.7 或更高版本
  • 已创建 Lighthouse LLM 应用
  • 已获取应用的密钥和公钥
pip install langfuse

基础概念

Trace（追踪）

Trace 表示 LLM 功能的一次完整执行过程，是所有观测数据的顶层容器。

一个 Trace 通常对应一次用户请求或一个完整的 LLM 任务执行。

Observation（观测）

每个 Trace 可以包含多个 Observation 来记录执行的各个步骤：

  • Event（事件）：记录离散的事件点
  • Span（跨度）：记录一段时间区间内的执行过程
  • Generation（生成）：特殊的 Span 类型，专门用于记录 AI 模型的生成过程
示例结构
TRACE (用户问题处理)
├── SPAN: 检索相关文档
│   ├── GENERATION: 生成检索查询
│   │   ├── input: 用户原始问题
│   │   └── output: 优化后的检索关键词
│   ├── SPAN: 向量数据库搜索
│   │   ├── metadata: {db_type: "milvus", top_k: 3}
│   │   └── output: 相关文档列表
│   └── EVENT: 文档处理完成
│       └── metadata: {doc_count: 3}
│
└── GENERATION: 生成回答
    ├── input: 用户问题 + 检索到的上下文
    ├── output: AI 生成的回答
    └── metadata: {model: "gpt-4", tokens: 1250}

配置方式

环境变量配置

配置建议

推荐使用环境变量方式进行配置，这样可以更好地管理敏感信息。

import os

os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..."  # 密钥
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..."  # 公钥
os.environ["LANGFUSE_HOST"] = "https://xxx.xxx.xxx"  # API地址

代码配置

注意事项

使用代码配置时，请确保在执行任何装饰函数之前完成配置。建议在应用程序入口处进行配置。

from langfuse.decorators import langfuse_context

langfuse_context.configure(
    secret_key="sk-lf-...",
    public_key="pk-lf-...",
    host="https://xxx.xxx.xxx"
)

主要配置参数

参数名称环境变量说明默认值
secret_keyLANGFUSE_SECRET_KEY密钥-
public_keyLANGFUSE_PUBLIC_KEY公钥-
hostLANGFUSE_HOSTAPI 地址https://xxx.xxx.xxx
debugLANGFUSE_DEBUG是否启用调试日志False
sample_rateLANGFUSE_SAMPLE_RATE采样率1.0
releaseLANGFUSE_RELEASE应用版本号-

选择合适的 API

装饰器 API（推荐）

适用场景
  • 快速集成到现有代码
  • 自动处理上下文关系
  • 与主流框架（OpenAI、LangChain、LlamaIndex）集成
from langfuse.decorators import observe

@observe()
def process_query(query: str):
    # 处理逻辑
    pass

Low Level SDK

适用场景
  • 需要精细控制追踪过程
  • 特殊的集成需求
  • 分布式系统中的手动上下文传递
from langfuse import Langfuse

langfuse = Langfuse()
trace = langfuse.trace(name="custom-trace")

框架支持

支持的框架

Lighthouse 通过 Langfuse SDK 支持以下主流框架：

  • OpenAI
  • LangChain
  • LlamaIndex
  • Anthropic
  • Mistral
  • Amazon Bedrock

下一步