Langfuse 是什么：定位与架构全景

Langfuse 的核心抽象只有一个：Trace。可观测是「看 Trace」，评估是「给 Trace 打 Score」，Prompt 管理是「让生成 Trace 的那段提示词可版本化」。三大能力不是三个独立产品，而是围绕同一份数据的三种视角——这正是它和「日志工具 + 评估工具 + 配置中心」拼盘方案的本质区别。

它到底解决什么问题

把一个 demo 级 LLM 应用推向生产时，你会连续撞上三堵墙：链路是黑盒，效果没法量化，成本不透明。Langfuse 的设计就是逐个拆掉这三堵墙。

架构全景：从 SDK 到 Web UI

Langfuse 是典型的「客户端 SDK + 服务端摄入 + 双存储 + Web UI」架构。关键是要记住：SDK 到服务端是异步、批量、单向的上报，你的应用主链路不等待 Langfuse 的网络往返。

1. Instrumentation 层（SDK）：Python SDK（@observe 装饰器 / langfuse.openai 直替 / LangChain CallbackHandler）、JS/TS SDK。它们在你应用进程里把调用记录成 trace/span/generation，缓存进本地队列。
2. Ingestion API：SDK 后台线程把队列里的事件 批量、异步 POST 到 /api/public/ingestion，失败自动重试，应用退出时 flush。
3. 队列与 Worker：服务端把摄入事件入队（自托管用 Redis），由 Worker 异步消费、解析、计算 token 与 cost。
4. 存储双写：分析型大表（traces / observations / scores）落 ClickHouse（列式，扛聚合查询）；项目、用户、API key、prompt 等元数据落 Postgres。对象（如大 payload）走 S3 兼容存储。
5. Web UI：Dashboard（用量/成本/延迟指标）、Tracing（链路下钻）、Prompts（版本与 label）、Evaluations（datasets 与 scores）从存储读取并展示。

一条请求如何变成一条 Trace（数据流）

  [你的应用进程]
        │  ① 调用被 SDK 拦截 / 装饰
        ▼
  ┌──────────────────────────┐
  │ Langfuse SDK              │
  │  trace → span → generation│  ② 记录输入/输出/耗时/模型
  │  写入本地内存队列          │
  └──────────────┬───────────┘
                 │ ③ 后台线程：批量 + 异步 + 重试（不阻塞主链路）
                 ▼  POST /api/public/ingestion
  ┌──────────────────────────┐
  │ Langfuse Server           │
  │  Ingestion API → 队列      │  ④ 入队
  │  Worker 消费               │  ⑤ 解析 + 按模型定价算 token/cost
  └───────┬───────────┬──────┘
          │           │
          ▼           ▼
     ClickHouse     Postgres        ⑥ 双写：分析大表 / 元数据
     (traces,        (projects,
      observations,   prompts,
      scores)         users, keys)
          │           │
          └─────┬─────┘
                ▼
        ┌───────────────┐
        │   Web UI       │  ⑦ Dashboard / Tracing / Prompts / Evals
        └───────────────┘

30 秒感受：一条 Trace 是怎么产生的

下面是能直接跑通的最小示例。把它当作「架构图里 ①②③ 步」的代码版——你会在第 4 章 quickstart-sdk 里展开细节，这里先建立体感。

# 安装 Python SDK（v3，基于 OpenTelemetry）；带 openai 集成
pip install "langfuse>=3.0.0" openai

# 三个环境变量来自 Langfuse 项目设置页（云版 cloud.langfuse.com 或自托管实例）
export LANGFUSE_PUBLIC_KEY="pk-lf-xxxxxxxx"
export LANGFUSE_SECRET_KEY="sk-lf-xxxxxxxx"
export LANGFUSE_HOST="https://cloud.langfuse.com"   # 自托管换成你的地址
export OPENAI_API_KEY="sk-..."

# 方式 A：用 @observe 装饰器，把整段函数变成一个 trace，内嵌一个 generation
from langfuse import observe, get_client
# 关键：从 langfuse.openai 导入，而不是直接 import openai
# 这个 drop-in 替换会自动把每次 chat.completions 记成 generation（含 token/cost）
from langfuse.openai import openai


@observe()  # 装饰器把这个函数包成一个 trace 的根节点
def answer_question(question: str) -> str:
    completion = openai.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": "你是一个简洁的助手。"},
            {"role": "user", "content": question},
        ],
        # name 会成为这条 generation 在 UI 里的显示名，便于检索
        name="answer-llm-call",
    )
    return completion.choices[0].message.content


if __name__ == "__main__":
    print(answer_question("用一句话解释什么是可观测性"))

    # SDK 默认异步批量上报；脚本/短任务退出前必须 flush，否则事件可能没发出去
    langfuse = get_client()
    langfuse.flush()  # 阻塞直到本地队列清空（长驻服务里通常无需手动调用）
    # 运行后到 Web UI 的 Tracing 页，就能看到一条名为 answer_question 的 trace

Langfuse vs LangSmith vs Phoenix：怎么选

三者都做 LLM 可观测，但定位不同。一句话区分：Langfuse 是开源 + 可自托管 + 框架中立的全平台；LangSmith 是 LangChain 官方的托管闭源方案，和 LangChain/LangGraph 生态贴得最紧；Phoenix（Arize）是开源、强调本地探索与 OpenTelemetry 原生的可观测/评估工具。

你无法改进你看不见、量不准、算不清成本的系统。Langfuse 做的就是先让 LLM 应用变得「可见、可量、可算」。

— 本 Wiki 编者按

下一章进入动手环节：搞清楚 云版 vs Docker 自托管 各自的取舍，并把一个可用的 Langfuse 实例跑起来——这是后续所有 SDK 接入和实验的前提。