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_key	LANGFUSE_SECRET_KEY	密钥	-
public_key	LANGFUSE_PUBLIC_KEY	公钥	-
host	LANGFUSE_HOST	API 地址	https://xxx.xxx.xxx
debug	LANGFUSE_DEBUG	是否启用调试日志	False
sample_rate	LANGFUSE_SAMPLE_RATE	采样率	1.0
release	LANGFUSE_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

下一步

• 查看装饰器使用指南了解推荐的使用方式
• 查看Low Level SDK 使用指南了解更多高级用法
• 查看最佳实践与示例获取实际应用案例