langfuse-observability

用途

Langfuse 是开源 LLM 可观测性平台，OrchestKit 使用它进行追踪、监控、评估和提示词管理。资料说明，与 LangSmith（已弃用）不同，Langfuse 是自托管的、免费的，并且面向生产级 LLM 应用设计。

适用场景包括：

从头搭建 LLM 可观测性
调试缓慢或错误的 LLM 响应
跟踪 token 用量和成本
在生产中管理提示词
评估 LLM 输出质量
从 LangSmith 迁移到 Langfuse

OrchestKit 集成

状态：已从 LangSmith 迁移（2025 年 12 月）
位置：backend/app/shared/services/langfuse/
MCP Server：orchestkit-langfuse（可选）

快速开始

设置客户端：

# backend/app/shared/services/langfuse/client.py
from langfuse import Langfuse
from app.core.config import settings

langfuse_client = Langfuse(
    public_key=settings.LANGFUSE_PUBLIC_KEY,
    secret_key=settings.LANGFUSE_SECRET_KEY,
    host=settings.LANGFUSE_HOST  # 自托管或云端
)

使用 @observe 进行基础追踪：

from langfuse.decorators import observe, langfuse_context

@observe()  # 自动追踪
async def analyze_content(content: str):
    langfuse_context.update_current_observation(
        metadata={"content_length": len(content)}
    )
    return await llm.generate(content)

会话与用户追踪：

langfuse.trace(
    name="analysis",
    user_id="user_123",
    session_id="session_abc",
    metadata={"content_type": "article", "agent_count": 8},
    tags=["production", "orchestkit"]
)

核心能力

资料列出以下功能及其参考文档：

分布式追踪（Distributed Tracing）：跟踪 LLM 调用及父子 span。参考 references/tracing-setup.md
成本追踪（Cost Tracking）：自动计算 token 与成本。参考 references/cost-tracking.md
提示词管理（Prompt Management）：提示词版本控制。参考 references/prompt-management.md
LLM 评估（LLM Evaluation）：使用 G-Eval 自定义评分。参考 references/evaluation-scores.md
会话追踪（Session Tracking）：对相关 trace 分组。参考 references/session-tracking.md
实验 API（Experiments API）：A/B 测试与基准测试。参考 references/experiments-api.md
多评委评估（Multi-Judge Eval）：集成 LLM 评估。参考 references/multi-judge-evaluation.md

参考文档覆盖主题

追踪设置：使用 @observe 装饰器初始化 Langfuse 客户端；创建嵌套 trace 与 span；用 metadata 跟踪 LLM 生成；LangChain/LangGraph CallbackHandler 集成；工作流集成模式。

成本追踪：根据 token 用量自动计算成本；自定义模型定价配置；监控看板 SQL 查询；按分析/用户追踪成本；每日成本趋势分析。

提示词管理：提示词版本化与标签（production/staging/draft）；使用 Jinja2 语法的模板变量；提示词版本的 A/B 测试；OrchestKit 四级缓存架构（L1-L4）；将提示词关联到生成 span。

LLM 评估：使用数值/分类值进行自定义评分；G-Eval 自动质量评估；评分趋势与对比；按分数阈值过滤 trace。

会话追踪：按 session_id 对 trace 分组；多轮对话追踪；用户与 metadata 分析。

实验 API：在 Langfuse 中创建测试数据集；运行自动化评估；LLM 回归测试；对提示词版本进行基准测试。

多评委评估：使用多个 LLM 评委进行质量评估；跨评委的加权评分；OrchestKit langfuse_evaluators.py 集成。

最佳实践

始终使用 @observe 装饰器进行自动追踪
设置 user_id 和 session_id 以获得更好的分析
添加有意义的 metadata（content_type、analysis_id 等）
对所有生产 trace 评分以进行质量监控
使用提示词管理而非硬编码提示词
每日监控成本以及早发现异常峰值
为回归测试创建数据集
为生产与预发 trace 打标签

LangSmith 迁移说明

资料列出的关键差异：

托管：Langfuse 为自托管、开源；LangSmith 为仅云端、专有
成本：Langfuse 免费；LangSmith 付费
提示词：Langfuse 内置管理；LangSmith 需要外部存储
装饰器：Langfuse 为 @observe；LangSmith 为 @traceable

关键决策

可观测性平台：选择 Langfuse（而非 LangSmith）。理由：开源、自托管、免费、内置提示词管理
追踪方式：选择 @observe 装饰器。理由：自动、低开销埋点
成本追踪：选择自动 token 计数。理由：内置模型定价并支持自定义覆盖
提示词管理：选择 Langfuse 原生能力。理由：版本控制、A/B 测试、标签集中在一处

能力细节

资料按能力词条列出关键词与解决的问题：

distributed-tracing：关键词 trace、tracing、observability、span、nested、parent-child、observe。解决如何跨应用追踪 LLM 调用、如何调试缓慢的 LLM 响应、跟踪多智能体工作流的执行流、创建嵌套 trace span。

cost-tracking：关键词 cost、token usage、pricing、budget、spend、expense。解决如何跟踪 LLM 成本、计算 token 用量与定价、监控 AI 预算与支出、按用户或会话追踪成本。

prompt-management：关键词 prompt version、prompt template、prompt control、prompt registry。解决如何对提示词进行版本控制、在生产中管理提示词、A/B 测试不同提示词版本、将提示词关联到 trace。

llm-evaluation：关键词 score、quality、evaluation、rating、assessment、g-eval。解决如何评估 LLM 输出质量、用自定义指标为响应评分、跟踪质量趋势、按质量比较提示词版本。

session-tracking：关键词 session、user tracking、conversation、group traces。解决如何对相关 trace 分组、跟踪多轮对话、监控每用户表现、按会话组织 trace。

langchain-integration：关键词 langchain、callback、handler、langgraph integration。解决如何将 Langfuse 与 LangChain 集成、使用 CallbackHandler 追踪、自动追踪 LangGraph 工作流、LangChain 可观测性设置。

datasets-evaluation：关键词 dataset、test set、evaluation dataset、benchmark。解决如何在 Langfuse 中创建测试数据集、运行自动化评估、LLM 回归测试、对提示词版本进行基准测试。

ab-testing：关键词 a/b test、experiment、compare prompts、variant testing。解决如何 A/B 测试提示词、比较两个提示词版本、实验性提示词评估、统计提示词测试。

monitoring-dashboard：关键词 dashboard、analytics、metrics、monitoring、queries。解决哪些 trace 最昂贵、按智能体类型的平均成本、质量分数趋势、自定义监控查询。

orchestkit-integration：关键词 orchestkit、migration、setup、workflow integration。解决 OrchestKit 如何使用 Langfuse、从 LangSmith 迁移到 Langfuse、OrchestKit 工作流追踪模式、按分析追踪成本。

multi-judge-evaluation：关键词 multi judge、g-eval、multiple evaluators、ensemble evaluation、weighted scoring。解决如何使用多个 LLM 评委评估质量、设置 G-Eval 标准评估、配置跨评委加权评分、接入 OrchestKit 已有的 langfuse_evaluators.py。

experiments-api：关键词 experiment、dataset、benchmark、regression test、prompt testing。解决如何跨数据集运行实验、系统性地 A/B 测试模型与提示词、跟踪质量回归、比较实验结果。

外部参考

资料列出：Langfuse Docs、Python SDK、Decorators Guide、Prompt Management、Self-Hosting。

限制

资料未提供具体的收费价格数字、部署硬件要求、具体模型支持列表或使用配额等信息，这些内容暂未提供。

技能介绍

用途