Langfuse文档体系：开发者指南与API参考
项目地址: https://gitcode.com/GitHub_Trending/la/langfuse 概述
Langfuse是一个开源的LLM工程平台，为AI应用提供全面的可观测性（Observability）和分析能力。本文深入解析Langfuse的文档体系架构，帮助开发者快速掌握API使用方法和最佳实践。
核心架构解析
技术栈概览
Langfuse采用现代化的技术栈构建：
数据库架构
API体系结构
主要API路由分类
Langfuse的API体系分为多个功能模块：
| API类别 | 主要功能 | 路由路径 |
|---|---|---|
| 追踪管理 | 追踪记录管理 | /api/traces |
| 观测数据 | 观测记录操作 | /api/observations |
| 会话管理 | 用户会话处理 | /api/sessions |
| 模型管理 | AI模型配置 | /api/models |
| 评分配置 | 评分规则管理 | /api/scoreConfigs |
| 公共API | 公开接口服务 | /api/public |
| 媒体管理 | 多媒体资源处理 | /api/media |
| 评论系统 | 用户评论功能 | /api/comments |
核心API端点示例
追踪API
// 创建追踪记录
POST /api/traces
{
"name": "user_query_processing",
"input": {"query": "什么是Langfuse?"},
"metadata": {"user_id": "12345"}
}
// 查询追踪列表
GET /api/traces?projectId=proj_123&limit=10&offset=0
观测数据API
// 记录生成观测
POST /api/observations/generations
{
"traceId": "trace_abc",
"model": "gpt-4",
"input": "解释机器学习",
"output": "机器学习是...",
"usage": {"tokens": 150}
}
// 获取观测详情
GET /api/observations/{observationId}
OpenAPI规范集成
Langfuse使用Fern框架维护API规范，支持自动生成：
- OpenAPI 3.0规范文档
- TypeScript类型定义
- Python Pydantic模型
- Postman集合
规范生成命令
# 生成服务器API规范
npx fern-api generate --api server
# 生成客户端API规范
npx fern-api generate --api client
# 生成组织API规范
npx fern-api generate --api organizations
SDK集成指南
Python SDK使用示例
from langfuse import Langfuse
from langfuse.decorators import observe
# 初始化客户端
langfuse = Langfuse(
public_key="pk-your-key",
secret_key="sk-your-secret",
host="https://cloud.langfuse.com"
)
@observe()
def process_query(user_input: str):
"""处理用户查询的追踪函数"""
trace = langfuse.trace(
name="query_processor",
input={"query": user_input}
)
# 记录生成过程
generation = trace.generation(
name="llm_response",
model="gpt-4",
input=user_input,
output="这是AI生成的响应"
)
return generation.output
# 使用示例
result = process_query("解释深度学习")
JavaScript/TypeScript SDK
import { Langfuse } from "langfuse";
const langfuse = new Langfuse({
publicKey: "pk-your-key",
secretKey: "sk-your-secret",
baseUrl: "https://cloud.langfuse.com"
});
// 创建追踪
const trace = langfuse.trace({
name: "web_chat_interaction",
input: { message: "用户消息" }
});
// 记录生成事件
const generation = trace.generation({
name: "chat_response",
model: "gpt-4",
input: "用户输入",
output: "AI响应内容"
});
数据模型详解
核心数据实体
interface Trace {
id: string;
name: string;
input: any;
output: any;
sessionId?: string;
userId?: string;
metadata: Record<string, any>;
}
interface Observation {
id: string;
traceId: string;
type: 'GENERATION' | 'SPAN' | 'EVENT';
name: string;
input?: any;
output?: any;
model?: string;
usage?: TokenUsage;
}
interface TokenUsage {
promptTokens: number;
completionTokens: number;
totalTokens: number;
}
集成模式最佳实践
1. 异步处理模式
from langfuse import Langfuse
import asyncio
class AsyncLangfuseClient:
def __init__(self):
self.langfuse = Langfuse()
self.queue = asyncio.Queue()
async def process_queue(self):
"""异步处理追踪队列"""
while True:
trace_data = await self.queue.get()
try:
await self._send_trace(trace_data)
except Exception as e:
print(f"追踪发送失败: {e}")
finally:
self.queue.task_done()
async def _send_trace(self, data):
# 实现异步发送逻辑
pass
2. 批处理优化
// 批量发送追踪数据优化
class BatchProcessor {
private batch: any[] = [];
private batchSize = 50;
private flushInterval = 5000; // 5秒
constructor(private langfuse: Langfuse) {
setInterval(() => this.flush(), this.flushInterval);
}
addToBatch(traceData: any) {
this.batch.push(traceData);
if (this.batch.length >= this.batchSize) {
this.flush();
}
}
async flush() {
if (this.batch.length === 0) return;
const batchToSend = [...this.batch];
this.batch = [];
try {
await Promise.all(
batchToSend.map(data => this.langfuse.trace(data))
);
} catch (error) {
console.error('批量发送失败:', error);
}
}
}
监控与调试
健康检查端点
# 检查API健康状态
curl -X GET https://cloud.langfuse.com/api/health
# 检查数据库连接
curl -X GET https://cloud.langfuse.com/api/health/db
# 检查队列状态
curl -X GET https://cloud.langfuse.com/api/health/queue
性能指标监控
from prometheus_client import Counter, Histogram
# 定义监控指标
TRACE_REQUESTS = Counter('langfuse_trace_requests', '追踪请求数量')
TRACE_LATENCY = Histogram('langfuse_trace_latency', '追踪处理延迟')
@observe()
def monitored_function():
start_time = time.time()
TRACE_REQUESTS.inc()
# 业务逻辑
result = do_work()
latency = time.time() - start_time
TRACE_LATENCY.observe(latency)
return result
错误处理与重试机制
健壮的客户端实现
class RobustLangfuseClient {
private maxRetries = 3;
private retryDelay = 1000; // 1秒
async sendWithRetry(
operation: () => Promise<any>,
retries = this.maxRetries
): Promise<any> {
try {
return await operation();
} catch (error) {
if (retries > 0 && this.isRetryableError(error)) {
await this.delay(this.retryDelay);
return this.sendWithRetry(operation, retries - 1);
}
throw error;
}
}
private isRetryableError(error: any): boolean {
// 网络错误、速率限制等可重试错误
return error.code === 'NETWORK_ERROR' ||
error.status === 429 ||
error.status >= 500;
}
private delay(ms: number): Promise<void> {
return new Promise(resolve => setTimeout(resolve, ms));
}
}
安全最佳实践
API密钥管理
import os
from langfuse import Langfuse
from cryptography.fernet import Fernet
class SecureLangfuseClient:
def __init__(self):
self.cipher = Fernet(os.getenv('ENCRYPTION_KEY'))
self.langfuse = self._initialize_client()
def _initialize_client(self):
# 从安全存储解密密钥
encrypted_key = os.getenv('LANGFUSE_SECRET_ENCRYPTED')
decrypted_key = self.cipher.decrypt(encrypted_key.encode())
return Langfuse(
secret_key=decrypted_key.decode(),
public_key=os.getenv('LANGFUSE_PUBLIC_KEY'),
host=os.getenv('LANGFUSE_HOST')
)
def safe_trace(self, trace_data):
# 清理敏感数据
sanitized_data = self._sanitize_data(trace_data)
return self.langfuse.trace(sanitized_data)
def _sanitize_data(self, data):
# 移除敏感信息
if 'input' in data and 'password' in data.input:
data.input.password = '***REDACTED***'
return data
总结
Langfuse提供了完整的LLM应用可观测性解决方案，其API体系设计合理，文档完善。通过本文的指南，开发者可以：
- 快速集成：使用提供的SDK和API规范快速接入现有系统
- 高效监控：实现全面的LLM应用性能监控和调试
- 规模扩展：利用批处理和异步模式支持高并发场景
- 安全保障：遵循安全最佳实践保护敏感数据
Langfuse的开放式架构和丰富的集成选项使其成为LLM应用开发的首选 observability 平台。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
