大模型应用上线后，第一个问题通常是“钱花哪了、错在哪了”。Langfuse 是开源的大模型可观测平台，把每次调用记成一条 trace，能看输入输出、token、成本与延迟。本教程从零起一个自托管实例，用 Python 接入一次真实调用并跑通基本功能。

第一步：起一个自托管实例

需要本机装有 Docker。用官方编排文件启动，会一并拉起 Web 服务、Postgres 与 Redis。

# 拉取官方 docker-compose.yml 并启动
curl -O https://raw.githubusercontent.com/langfuse/langfuse/main/docker-compose.yml
docker compose up -d

# 查看启动日志，等服务变 healthy
docker compose logs -f

启动后浏览器打开 http://localhost:3000 创建账号。如果 3000 端口已被本机其他服务占用，先改 compose 里的端口映射再启动。

第二步：建项目、拿密钥

  • 登录后在首页新建一个 Project
  • 进入项目 Settings → API Keys，复制 Public Key、Secret Key 与 Host 地址
  • Host 本地默认是 http://localhost:3000

第三步：接入第一次调用

安装 SDK 后，用一段最简代码把一次对话记录进 Langfuse。

# pip install langfuse openai
from langfuse import Langfuse
from openai import OpenAI

langfuse = Langfuse(
    public_key="pk-你的公钥",
    secret_key="sk-你的私钥",
    host="http://localhost:3000",
)

client = OpenAI(base_url="你的模型API地址")  # 任意 OpenAI 兼容接口

with langfuse.start_trace(name="first-call") as trace:
    resp = client.chat.completions.create(
        model="你的模型ID",
        messages=[{"role": "user", "content": "你好，介绍一下你自己"}],
    )
    print(resp.choices[0].message.content)

跑完这段，打开 Web 界面的 Traces 页，能看到这条 trace 的输入、输出与耗时。如果用的是 Agent 或多步工具调用，可以在每个函数上包一层 @observe() 装饰器，Langfuse 会把每一步自动拼进同一条 trace。

第四步：拆成本、跑评测

  • 成本：在项目 Settings 里给用到的模型配置单价，之后每次调用会自动估算成本
  • 评测：在 Datasets 里建一个带预期答案的小数据集，定期回放，观察分数随代码改动的变化
  • 生产建议：先开“只记录”模式观察真实流量，再逐步把评测用例补起来
先让每次调用可复盘，再谈优化——这是 Langfuse 这类工具真正省时间的地方。