Langfuse 介绍与选型指南

目标：全面介绍开源 LLM 工程平台 Langfuse 的定位、架构、功能与自托管能力，并与 LangSmith、Arize Phoenix 做量化选型对比，帮助团队在「LLM 应用可观测与评估平台」这一品类中做出正确选型。本文为认知篇，全部事实均联网溯源官方渠道，未做本地实测；部署与实测内容见本专栏部署篇。

一、环境信息

本文为 A1 认知篇，按规范仅做联网溯源，不包含本地实测。所有事实的来源与查询日期如下：

💡 说明：Langfuse 迭代极快（三天连发 4 个版本），阅读本文时若已发布更高版本，请以官方 Releases 页为准；本文涉及的架构与功能描述以 v4.68.0 时点的官方资料为准。

二、软件概述

2.1 Langfuse 是什么

Langfuse 是一个开源的 LLM 工程平台（open source LLM engineering platform），核心能力是为一层：追踪（Tracing）——把 LLM 应用每次调用的输入、输出、工具执行、Agent 每一步、成本、延迟等全部记录成结构化的 Trace/Observation 树；二层：评估（Evaluation）——LLM-as-judge 评估器、代码评估器与人工评分；三层：Prompt 管理——版本化 Prompt 仓与 Prompt 实验对比；四层：监控分析——成本/质量/延迟仪表盘、阈值告警。它对标商业产品 LangSmith，但以「可自托管、开源核心」为最大差异化卖点。

基本盘信息（来源：langfuse.com/press，查询日期 2026-10-23）：

• 开发方：Langfuse 公司，2023 年成立，Y Combinator W23 批次，团队分布于柏林（产品与工程）与旧金山（商业化）；
• 2026 年 1 月被 ClickHouse 收购（官方公告 langfuse.com/blog/joining-clickhouse），收购后承诺保持开源与自托管能力，产品路线图不变；
• GitHub 星数 36k（shields.io 徽章实取，2026-10-23）；
• 开源许可：open core 模式——ee/、web/src/ee/、worker/src/ee/ 目录之外全部 MIT 许可（根 LICENSE 明文），ee/ 目录（SSO 高级选项、UI 白标定制、组织创建白名单等）为商业 Enterprise License（ee/LICENSE 明文）；
• 版本节奏：2026-10-20 至 10-22 三天连续发布 v4.65.0、v4.66.0、v4.67.0、v4.68.0，社区与商业投入极其活跃（GitHub Releases 实查）。

2.2 与 Langfuse Cloud 的关系

Langfuse 提供两条使用路径：官方云服务 Langfuse Cloud（SaaS，有免费额度）与完全自托管（self-hosted）。本文聚焦自托管。官方云已宣布 2026-11-16 起 v4-only（来源：changelog），自托管用户可按自己的节奏规划 v3→v4 升级，这是自托管在版本控制上的直接优势。

三、核心架构

3.1 版本演进：v2 → v3 → v4

（来源：仓库 main 分支 docker-compose.yml 与全文检索、langfuse.com/changelog/2026-08-17-langfuse-v4，查询日期 2026-10-23）

💡 技术拓展：为什么 LLM 可观测平台普遍选择「PostgreSQL + ClickHouse」双存储？——业务实体（用户、组织、项目、API Key、Prompt、数据集）是典型 OLTP 关系数据，放 PostgreSQL；而 Trace/Observation/Score 是海量追加型时序类数据，单项目可达数十亿行，宽表 + 列存 + 高压缩比的 OLAP 引擎（ClickHouse）才是成本与查询延迟的正确解。同理品类的 Phoenix 走 PostgreSQL/SQLite 路线，Langfuse 自 v3 起押注 ClickHouse，并在 2026 年被 ClickHouse 公司收购后进一步深化该路线。

3.2 v4 自托管六服务拓扑（官方 Compose 实录）

官方 docker-compose.yml（main 分支，2026-10-23 检索）定义了 6 个服务，自托管最小拓扑如下：

数据流：SDK/OTLP → langfuse-web（鉴权、入队）→ Redis 队列 → langfuse-worker（批量处理）→ 原始事件落 MinIO、结构化宽表写 ClickHouse、业务元数据写 PostgreSQL → 查询时 Web 按数据归属分别查三存储。

官方 Compose 安全基线（照抄自官方文件注释）：除 langfuse-web（3000）与 MinIO（9090）外，所有组件仅绑定 127.0.0.1，外部无法直接触达数据库与队列；所有默认口令均标注 CHANGEME 要求替换。

3.3 接入协议

• 原生摄取 API：POST /api/public/ingestion（trace-create、observation-create、score-create 等批量事件，OpenAPI 定义见仓库 fern/apis/server/definition/）；
• OpenTelemetry 原生：/api/public/otel 提供 OTLP/HTTP 摄取（仓库 fern OpenAPI 定义含 opentelemetry.yml），任何 OTel SDK/Collector 可直接上报；
• SDK：Python 与 TypeScript/JS 官方 SDK（langfuse-python / langfuse-js，pip/npm 安装），主流框架（LangChain、LlamaIndex、OpenAI SDK、Vercel AI SDK、LiteLLM 等）有官方集成文档（来源：langfuse.com/docs/integrations，2026-10-23）；
• v4 新增 AI Gateway（Rust 实现）：集中代理各 LLM Provider 请求并自动记账（来源：.env.prod.example 的 LANGFUSE_AI_GATEWAY_* 配置组与 Release Notes）。

四、功能特性

以下均来自官方资料（changelog/文档站/仓库），查询日期 2026-10-23：

可观测

• 全链路追踪：Trace → Observation（span/event/generation）树，模型、Token、成本、延迟自动核算，会话（Session）与用户维度聚合；
• 全文检索（v4）：跨 observation 输入/输出/元数据的词组搜索（官方注明 v3 遗留表可通过 LANGFUSE_DISABLE_LEGACY_TRACING_IO_SEARCH 控制行为）；
• 过滤搜索栏（v4）：类型化过滤、元数据、评分组合成可分享查询；
• Pulse（v4）：Observations 表上方绘制次数/成本/延迟曲线，点击尖峰直达具体操作；
• Monitors（v4）：成本/质量/延迟阈值监控，经 Slack、Webhook、GitHub Actions 通知；
• Halo（v4）：对 traces/observations/sessions/指标以自然语言提问。

评估

• LLM-as-judge 评估器 + 人工评分队列（annotation queues）；
• 代码评估器（v4）：在真实 observations 与实验上运行确定性的 Python/TypeScript 检查；
• 数据集与实验（Datasets & Experiments）：用固定数据集回归测试不同 Prompt/模型/版本。

Prompt 工程

• 版本化 Prompt 管理（创建/标注/回滚），缓存与 Prompt 实验，SDK 拉取与 Playground 调试。

平台与治理

• 组织/项目两级隔离，项目级 API Key（pk-/sk-），基于角色的访问控制；
• 审计日志（audit_logs 表，PostgreSQL 落库，支持 X-Forwarded-For 解析真实客户端 IP，对应 LANGFUSE_TRUSTED_PROXY_COUNT）；
• 数据保留策略（项目级配置 + Worker 后台清理队列，含批量删除 runner 与 ClickHouse 已删位图清理器等一组可调参数）；
• Observations API v2 / Metrics API v2（v4）：游标分页、按字段组选择；
• MCP Server（v4 活跃开发中，Release Notes 连续多个版本包含 MCP 工具更新）；
• 企业版（EE，商业许可）：SSO 高级选项、UI 白标（logo/文档/支持链接）、组织创建白名单等（ee/ 目录与 .env.prod.example 的 EE 配置组）。

五、快速开始（最小可用示例）

自托管的最小可用路径即官方 Docker Compose（来源：langfuse.com/docs/deployment/docker-compose 与仓库 main 分支 docker-compose.yml，查询日期 2026-10-23）。三步概览：

# 1. 获取官方 Compose 文件（含 6 服务定义，镜像仓库 docker.langfuse.com）
curl -L https://raw.githubusercontent.com/langfuse/langfuse/main/docker-compose.yml -o docker-compose.yml

# 2. 修改文件内所有 # CHANGEME 标注的默认口令（SALT/ENCRYPTION_KEY/NEXTAUTH_SECRET/
#    CLICKHOUSE_PASSWORD/MINIO_ROOT_PASSWORD/REDIS_AUTH/POSTGRES_PASSWORD）

# 3. 启动全栈，Web 控制台监听 3000 端口，浏览器注册首个账号即可使用
docker compose up -d

💡 说明：以上为官方文档路径的概览转述，命令输出与逐项验证不在本文范围内。本团队已按此路径完成全栈实测（含环境变量逐项验证与常见排障），完整过程与实测回显见本专栏《Langfuse Docker Compose 部署指南》（部署篇）；配置参数逐项详解见《Langfuse 4.68.0 配置参数详解》，运维命令见《Langfuse 4.68.0 常用 CLI 命令与工具详解》。

官方还提供 Kubernetes Helm Chart 与 AWS Terraform 模板两条进阶自托管路径（来源：langfuse.com/docs/deployment/self-hosting，2026-10-23）；小团队 PoC 也可直接以 v2 时代的单镜像 + Postgres 形态运行，但 v4 已不可用该形态（v4 起数据模型强依赖 ClickHouse 与 Redis）。

六、适用场景与限制

6.1 适用场景

1. LLM 应用研发团队的可观测基建：Agent/RAG/对话产品的每一次调用都需要可回放、可归因，Langfuse 是事实标准级的开源选择；
2. Prompt 工程与回归测试：Prompt 版本化 + 数据集实验，把「改 Prompt」变成可度量工程；
3. 成本治理：按项目/用户/模型聚合成本，Monitors 阈值告警防失控；
4. 质量评估流水线：LLM-as-judge + 代码评估器 + 人工队列三路并行；
5. 私有化交付：客户数据不出域的场景（金融/医疗/政企），MIT 核心许可允许商业部署且功能不受限。

6.2 限制与注意点

1. 资源门槛不低：v4 起最小拓扑就是 6 个服务（Web/Worker/Postgres/ClickHouse/MinIO/Redis），1C1G 小鸡不可行；官方 v2→v3 升级指南明确要求迁移 ClickHouse；
2. EE 功能需商业许可：SSO 高级配置、UI 白标等位于 ee/ 目录，未购许可时不生效；
3. 预构建镜像与部分运行时开关强耦合：如 NEXT_PUBLIC_BASE_PATH（子路径部署）需自行构建镜像，官方预构建镜像不支持（.env.prod.example 明文注释）；
4. 升级节奏快：三天连发 4 版的节奏意味着大版本升级（v3→v4）需要认真规划数据迁移窗口；
5. 平台自身出网行为需关注：默认遥测（TELEMETRY_ENABLED，可关）、对外 LLM 请求的白名单管控（LANGFUSE_LLM_CONNECTION_ALLOWED_HOSTS 等一组出网管控变量，v4 新增 SSRF 防护面）。

七、同类选型对比

选型对象：Langfuse、LangSmith（LangChain 官方商业平台）、Arize Phoenix（开源 OTel 优先）。量化维度如下（来源：各官方仓库与文档站，查询日期 2026-10-23；Langfuse 数据均取自上文溯源项）：

关键差异与选型建议：

• 要自托管、怕锁定 → Langfuse 或 Phoenix：两者都可完全私有化。Langfuse 的产品完成度（追踪+评估+Prompt+监控闭环）更贴近「团队级 LLM 工程平台」；Phoenix 更轻、OTel 生态更纯，适合已重度投入 OpenTelemetry/Collector 栈或单机研究场景；
• 已在 LangChain 生态且接受 SaaS → LangSmith：与 LangChain 全家桶集成最深、开箱即用，但代价是闭源、按席位/用量计费、数据出境，自托管需商业授权；
• 数据敏感、预算有限的私有化 → Langfuse 优势最大：MIT 核心无功能阉割（对比 LangSmith 自托管门槛），比 Phoenix 多出 Prompt 管理、人工评估队列与企业级组织/审计体系；
• 已是 ClickHouse 用户 → Langfuse 顺位再提前：追踪数据直接落在自家技术栈，运维经验与容量规划可复用。

💡 说明：表中 Phoenix 的 star 数、LangSmith 的内部架构属「未做同口径取证」项，均如实标注，不做编造；如需引用请以各官方仓库当日页面为准。

八、参考链接

1. Langfuse 官网：https://langfuse.com
2. Langfuse v4 发布公告（2026-08-17）：https://langfuse.com/changelog/2026-08-17-langfuse-v4
3. Langfuse joins ClickHouse（2026-01）：https://langfuse.com/blog/joining-clickhouse
4. 公司与许可事实页（Press）：https://langfuse.com/press
5. 自托管文档：https://langfuse.com/docs/deployment/self-hosting
6. Docker Compose 部署文档：https://langfuse.com/docs/deployment/docker-compose
7. 官方 Compose 文件（main 分支，2026-10-23 检索）：https://raw.githubusercontent.com/langfuse/langfuse/main/docker-compose.yml
8. 环境变量参考（.env.prod.example，main 分支）：https://raw.githubusercontent.com/langfuse/langfuse/main/.env.prod.example
9. GitHub Releases：https://github.com/langfuse/langfuse/releases
10. 星数徽章取证（36k，2026-10-23）：https://img.shields.io/github/stars/langfuse/langfuse