Langfuse：2.5万星开源LLM工程平台，让你的AI应用不再黑箱

你是不是也遇到过这些问题？

你花了一周时间终于把大模型接到了业务系统里，上线第一天客户就反馈："这个回答怎么胡说八道？"你打开日志一看，密密麻麻的请求记录，根本分不清哪条调用了哪个模型、传了什么参数、中间经过了哪些步骤。更头疼的是，团队里三个人各自维护一套Prompt（提示词，即你喂给大模型的指令），谁也说不清线上跑的到底是哪个版本。评估模型回答好不好？全靠手动翻记录，效率低到让你怀疑人生。

如果你有以上任何一种感受，那你今天要认识的这个项目，会变成你的救命稻草。

Langfuse 是什么？

Langfuse 是一个开源的 LLM（大语言模型）工程平台，帮助团队追踪、监控、评估和调试 AI 应用的每一步操作。简单说，它给你的 AI 应用装了一个"行车记录仪"——谁调过了什么模型、传了什么参数、花了多少钱、返回了什么结果，全部一目了然。更关键的是，它完全开源免费，你可以部署在自己的服务器上，数据不外泄。

这个项目由 Y Combinator W23 孵化，目前 GitHub 上已获得 25,600+ 星标，是 LLM 可观察性（Observability，即对系统内部运行状态的可视化监控能力）领域最受欢迎的开源方案之一。

核心功能详解

1. Tracing（链路追踪）

一句话解释： 把你 AI 应用的每次调用都完整记录下来，像查快递一样追踪整个处理流程。

不管你的应用是简单的一问一答，还是复杂的 RAG（检索增强生成，即先从知识库找资料再让模型回答）流水线、多 Agent（智能体）协作，Langfuse 都能把每个步骤——从用户输入、检索文档、调用模型到最终输出——串联成一条完整的调用链。你可以在界面上看到每个步骤的输入、输出、耗时和 Token（模型处理文本的最小单位）用量，快速定位性能瓶颈或异常回答的元凶。

2. Prompt Management（提示词管理）

一句话解释： 团队所有人共享一套提示词版本库，改了什么一目了然，线上切换零延迟。

你在开发中一定遇到过这类混乱：张三改了提示词觉得效果不错，推上线才发现李四上周也改了一版但没同步，结果线上线下版本对不上。Langfuse 提供了集中的提示词管理面板，所有提示词有完整的版本历史，谁改了什么一目了然。更厉害的是，它内置了缓存机制——应用第一次从 Langfuse 拉取提示词后就会缓存到本地，后续调用不会增加任何网络延迟。

3. Evaluations（评估）

一句话解释： 自动打分你的 AI 输出质量，不用再靠人肉翻记录判断好不好。

Langfuse 支持四种评估方式：

• LLM-as-judge：用另一个大模型给输出打分（比如让 GPT-4 评估回答的相关性、准确性）
• 用户反馈：在应用里放个👍👎按钮，收集真实用户评价
• 手动标注：团队内部对历史回答做标注，建立金标准数据集
• 自定义评估流水线：写代码定义你自己的评估逻辑，灵活度最高

4. Datasets（数据集）

一句话解释： 给你的 AI 应用建一个"考试题库"，每次改代码前先跑一遍测试，确保不会越改越差。

开发 AI 应用最怕的就是改了提示词或换了模型，效果反而变差了，但你又说不清到底差在哪。Langfuse 的数据集功能让你把典型的输入-输出对保存下来作为测试基准，每次改动后自动跑一遍对比结果，真正做到持续改进而非"凭感觉优化"。

5. LLM Playground（模型试验场）

一句话解释： 在浏览器里直接测试不同提示词和模型配置的效果，不用反复改代码。

你可以直接在 Langfuse 界面上调整提示词、换模型、改温度等参数，实时看到输出变化。调到满意了再一键应用到线上，省去了在代码里来来回回调试的麻烦。

6. 综合 API 和 SDK

一句话解释： 不管你用什么语言、接什么框架，基本都有现成的对接方式。

Langfuse 提供了 OpenAPI 规范、Postman 集合，以及 Python、JavaScript、TypeScript 三种语言的类型化 SDK，覆盖了主流开发者的技术栈。

安装步骤（手把手教程）

Langfuse 最简单的部署方式是用 Docker Compose（一个帮你一键启动多个服务的容器编排工具），下面按操作系统分别说明。

前置条件

你需要先安装 Docker（一个把应用装进容器的工具，保证在任何系统上运行效果一致）和 Docker Compose（管理多个 Docker 容器的工具）。

Mac 用户： 下载 Docker Desktop（包含 Docker 和 Docker Compose）：https://www.docker.com/products/docker-desktop/ 下载后拖到"应用程序"文件夹，双击打开即可。Mac 版自带 Docker Compose，无需额外安装。

Windows 用户： 同样下载 Docker Desktop for Windows：https://www.docker.com/products/docker-desktop/ 安装时勾选 "Use WSL 2 instead of Hyper-V"（推荐使用 WSL2 后端，性能更好）。安装完成后重启电脑。

Linux（Ubuntu/Debian）用户：

# 安装 Docker
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 验证安装
docker --version
docker compose version

部署 Langfuse

三种系统都一样，只需三行命令：

# 1. 克隆项目代码到本地
git clone https://github.com/langfuse/langfuse.git

# 2. 进入项目目录
cd langfuse

# 3. 一键启动（自动拉取镜像、配置数据库、启动所有服务）
docker compose up

第一次运行会下载镜像，可能需要 5-10 分钟（取决于网速）。看到日志输出不再滚动、出现 "ready" 相关提示后，打开浏览器访问：

http://localhost:3000

第一次打开需要注册账号，注册完成后就可以开始使用了。

💡 小贴士：如果你的服务器内存较小（4GB 以下），建议在 docker-compose.yml 中调整各服务的内存限制，确保稳定运行。

关停服务

用完后，在同一个目录下执行：

docker compose down

数据会保留在 Docker 卷中，下次启动不会丢失。

使用方法：从简单到进阶

用法一：Python SDK 追踪函数（最简单）

这是最基础也最推荐的方式，只需两步：

第一步：安装 SDK

pip install langfuse

第二步：写代码

from langfuse import Langfuse
from langfuse.decorators import observe, langfuse_context

# 初始化连接（密钥在 Langfuse 界面的"设置"页面获取）
langfuse = Langfuse(
    public_key="pk-xxx",      # 替换为你的公钥
    secret_key="sk-xxx",      # 替换为你的私钥
    host="http://localhost:3000"  # 自托管地址
)

# 用 @observe 装饰器标记你想追踪的函数
@observe()
def my_function(input_text):
    # 这里放你的业务逻辑
    result = process(input_text)
    return result

# 正常调用函数，Langfuse 自动记录
my_function("你好，请帮我总结一下这篇文章")

就这么简单！加了 @observe() 装饰器后，每次调用这个函数，Langfuse 都会自动记录输入、输出和执行时间。你可以在 Langfuse 界面的"Traces"页面看到所有记录。

用法二：一行代码追踪 OpenAI 调用（最省事）

如果你已经在用 OpenAI 的 Python SDK，只需要改一行 import：

# 原来：
# from openai import OpenAI

# 现在（只改这一行！其他代码完全不用动）：
from langfuse.openai import OpenAI

client = OpenAI(
    public_key="pk-xxx",
    secret_key="sk-xxx",
    host="http://localhost:3000"
)

# 之后的代码跟原来一模一样
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "你好，请介绍一下你自己"}]
)

print(response.choices[0].message.content)

所有对 OpenAI 的调用（包括流式输出、函数调用等）都会被完整追踪，你可以在 Langfuse 界面看到每次调用的 Token 用量、延迟、费用等信息。

用法三：LangChain 集成（适合复杂流水线）

如果你用 LangChain（一个把多个 AI 组件串联起来的框架）搭建了复杂应用，接入 Langfuse 也只需几行代码：

from langfuse.callback import CallbackHandler

# 创建追踪处理器
langfuse_handler = CallbackHandler(
    public_key="pk-xxx",
    secret_key="sk-xxx",
    host="http://localhost:3000"
)

# 在 LangChain 调用时传入 handler 即可
chain.invoke(
    {"input": "帮我分析一下今年的销售数据趋势"},
    config={"callbacks": [langfuse_handler]}
)

这样，LangChain 内部的每一步——检索、重排序、模型调用——都会被完整记录到 Langfuse，你可以在界面上看到一条清晰的调用链。

实际场景举例

跟同类工具对比

市面上做 LLM 可观察性的工具不少，我们挑几个有代表性的来比一比：

选型建议：

• 最在乎数据隐私、想自托管 → 选 Langfuse，没有之一
• 已经在深度使用 LangChain → LangSmith 也可以考虑（同公司产品），但数据不在自己手里
• 只想看 API 调用统计 → Helicone 足够，但功能少得多
• 做内部实验、不涉及生产数据 → Phoenix 本地跑很方便

补充：技术架构与数据库说明

对于有运维经验的读者，了解一下 Langfuse 的技术栈可能有助于评估是否适合自己的环境：

Langfuse 后端使用 TypeScript 开发，数据库采用 PostgreSQL（存储业务数据）+ ClickHouse（存储追踪日志，这是一个专门用于海量数据分析的列式数据库，查询特别快）+ Redis（缓存和任务队列）+ MinIO（对象存储，存附件等大文件）。

Docker Compose 部署会自动把所有这些组件一起启动，你不需要手动配置。如果你的团队已经有现成的 PostgreSQL 或 Redis 服务，也可以在配置文件中指向已有的服务，不必重复部署。

小结

Langfuse 把 LLM 应用开发中最痛的几个环节——看不清调用链、管不住 Prompt、测不准效果——用一个开源平台全解决了。自托管部署三行命令搞定，OpenAI 集成只改一行代码，这对中国开发者来说尤其友好：数据不出境、费用可控、社区活跃。

项目地址： https://github.com/langfuse/langfuse

官方文档： https://langfuse.com/docs

Star 数： 25,600+（持续增长中）