Langfuse：监控本地 LLM（追踪记录、提示词、 评估)

#为什么要监测本地 LLM

Langfuse 是一个面向 LLM 应用的可观测性平台，其主代码库采用 MIT 许可证。您可以自托管，让对话追踪数据留在您自己的环境中。它会针对每次请求记录实际发送给模型的提示词、回答、每个步骤的耗时，以及在已设定价格的情况下记录成本。它帮助您查明回答不佳的原因：检索到的片段偏离主题、实际提示词与您以为的不同，或模型失败。只要有第二个人依赖结果，或处理链包含多个步骤，它就有用；如果只是您独自进行探索性使用，一个日志文件就足够。需要准备一套由多个容器组成的服务栈（Web 服务器、工作进程、PostgreSQL、ClickHouse、Redis、对象存储）；生产环境则应使用 Kubernetes，而不是 Docker Compose。

当回答不尽如人意时，可能有三种原因，而在没有监测手段的情况下，只有一种能直接看出来：实际发送给模型的最终提示词并不是您以为的那份，文档检索得到的片段与问题无关，或者模型本身没能完成任务。如果没有记录，就只能随意修改提示词，直到结果有所改善，却始终不知道为什么。

这套理由在本地和在线环境中同样成立，只有一点不同：账单不再是提醒您出现问题的信号。当一串智能体在您自己的显卡上陷入循环时，没人会收到账单；反映问题的是延迟和发热。可观测性用各项指标取代这一价格信号：token 数量、耗时、失败率和质量。

#Langfuse记录的内容

该项目将自身定位为一个开源的智能体评估与可观测性平台：在同一个开放平台上追踪、评估和改进 LLM 应用。其 Python SDK（版本 4）和 JS/TS SDK（版本 5）基于 OpenTelemetry，其他语言也可以通过该协议发送追踪数据。主仓库在 GitHub 上已超过 35,000 个星标。其 README 表示，Langfuse 自 2026 年 1 月起成为 ClickHouse 的一部分，而存储追踪数据的数据库也是 ClickHouse。

追踪记录

用户请求的完整流程：每一步按顺序列出，包含其耗时。这是基本单位。

观察记录

在一条追踪记录中：模型调用的完整提示和响应、文档检索步骤、工具调用过程。

会话与用户

按对话和用户对追踪记录进行分组，以跟踪完整流程，而不是单次孤立的调用。

评分

附在一条调用追踪上的评分：用户点赞、自动评估结果或人工标注。

Prompts

提示模板，版本化，由应用在运行时动态获取，而非硬编码在代码中。

成本

Langfuse 根据模型定义计算成本，该定义为每种使用类型指定价格。它为 OpenAI、Anthropic 和 Google 的模型提供此类定义。对于本地模型，只有您自行添加价格后，系统才有价格可用：如果没有模型定义，就不要在界面中查找成本；也可以设定一个虚拟价格，用来反映电费和折旧。

#自行部署

Langfuse 可通过 Docker Compose 实现自托管。README 称五分钟即可启动；部署文档则预计 Web 容器显示“Ready”前需要两到三分钟。整套架构不止一个容器：它包含两个应用容器（提供界面和 API 的 Web 服务器，以及异步处理事件的 worker）和四个存储组件：PostgreSQL 用于事务数据，ClickHouse 用于追踪记录、观测记录和评分，Redis 或 Valkey 用于队列和缓存，以及用于保存所有传入事件的 S3 兼容对象存储。这比一个简单的仪表板更重，原因在于它需要满足这样的要求：摄入大量事件，同时不丢失任何追踪记录，即使数据库暂时不可用也如此。

在将它与模型一起安装之前，需要了解两个限制。首先，文档说明 Docker Compose 用于试用：这种配置既不提供高可用性，也不支持扩容或备份；对于生产环境，文档建议使用 Kubernetes 配合 Helm。其次，对于虚拟机，文档建议至少配备 4 个核心、16 GiB 内存和 100 GiB 存储空间。在已经运行模型服务的机器上，这些资源需求的量级很重要：如果可观测性技术栈占用了原本供模型使用的一部分内存，就会在最不合适的时候抢占资源。最后，请修改 docker-compose.yml 文件中标记为 CHANGEME 的密钥：没有默认账户，首个用户需通过 http://localhost:3000 上的 Sign up 按钮创建。

git clone --depth=1 https://github.com/langfuse/langfuse.git
cd langfuse
# Éditer docker-compose.yml : remplacer chaque secret marqué CHANGEME
docker compose up
# Après 2 à 3 minutes, le conteneur web affiche « Ready » : ouvrir http://localhost:3000

#连接至 Ollama 或 vLLM

Langfuse不是推理服务器，也不会插入请求流量的传输路径：追踪数据由您的应用发送给它。该项目根据您调用模型的方式，介绍了三种具体的集成途径，并提供了一个专门介绍Ollama的页面，其中的示例使用OpenAI SDK：Ollama在http://localhost:11434/v1提供兼容OpenAI的API，而Langfuse提供了可直接替换该SDK的版本，只需修改import语句即可。项目也有专门介绍vLLM的页面。

1. 01
   通过 SDK，在您的代码中

   为调用模型的函数添加装饰器。这是最明确且最准确的方式，因为您可以选择哪些内容被记录下来。
2. 02
   通过框架集成

   已有自动化插桩方案，可通过直接替换 OpenAI SDK、在 LangChain 应用中接入回调处理器，或使用 LlamaIndex 的回调系统来实现：无需修改业务逻辑，即可上报追踪数据。
3. 03
   通过 API 网关

   如果您的调用已经通过兼容 OpenAI 的路由器，那么在这一层接入监测，就能一次覆盖所有应用程序。

在这三种情况下，都要确认记录的是实际发送的提示词，而不只是用户的问题：正是两者之间的差异，解释了文档检索系统大多数错误回答的原因。使用 Ollama 时，下方配置将 LANGFUSE_BASE_URL 指向您的自托管实例（http://localhost:3000），并通过环境变量设置您的公开密钥和秘密密钥。

# pip install langfuse openai
# Variables d'environnement : LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY,
# LANGFUSE_BASE_URL=http://localhost:3000
from langfuse.openai import OpenAI  # remplace : from openai import OpenAI

client = OpenAI(
    base_url='http://localhost:11434/v1',
    api_key='ollama',  # requis mais inutilisé
)
reponse = client.chat.completions.create(
    model='llama3.1',
    messages=[{'role': 'user', 'content': 'Bonjour !'}],
)

• 通过兼容 OpenAI 的网关集中调用模型
• 部署vLLM以服务多个用户
• 从 Python 调用 Ollama
• Ragas：用数据评估本地 RAG
• 来源：SDK、框架及网关的详细集成信息

#管理提示词并进行版本控制

将提示词从代码中分离出来，是团队最先体会到的好处。根据 README，完善的服务端和客户端缓存可以让团队迭代提示词，而不增加应用延迟。模板存储在 Langfuse 中，应用在运行时获取它，每次修改都会创建一个版本。修改措辞不再需要重新部署；更重要的是，追踪记录会显示哪个版本生成了哪条回答：当一次修改后质量下降时，就能知道该排查哪个版本，无需交叉核对单独的部署日志。

#测试集与评估

实际运行的追踪记录用于构建测试集：您标记出值得关注的案例——尤其是失败案例——它们便会组成一个案例集，供新版提示词或另一个模型重新运行测试。这让您能够认真回答“140 亿参数的模型够用吗？”，而不只是讨论这个问题。

评分有多个来源：用户、界面中的人工标注、基于代码的评估器，或按照评分标准评判另一个模型回答的模型——这就是所谓的 LLM-as-a-judge 方法，Langfuse 原生支持该方法。对于最后一种情况，需要创建一个 LLM 连接。文档指出，只要模型遵循 OpenAI API 的接口格式，替换基础 URL 后就能使用：因此，由 Ollama 提供服务的本地模型也可以担任评判者，前提是 Langfuse 容器能够访问它的地址。这种方法有用，但也存在偏差：该领域参考论文（arXiv 2306.05685）的作者描述了位置偏差、冗长偏差和自我偏好偏差，同时测得 GPT-4 类评判者与人类偏好之间的一致率超过 80%。它用于比较两个版本，而不是给出绝对评分。

一款专用于评估RAG的工具，如Ragas，是补充Langfuse而非替代它：Langfuse负责追踪并存储评分，Ragas则计算特定指标——如上下文一致性、回答相关性——这些指标随后可像其他追踪评分一样在Langfuse中展示。

#具体用例

基于 RAG 的支持助手

可以通过调用追踪记录查明回复为何偏离主题：检索到的段落是否相关，还是模型忽略了一个正确的段落？追踪记录可以帮助判定究竟是哪一种情况。

调用工具的智能体

在包含检索、计算、撰写等多个步骤的处理链中，追踪记录会指出哪一步失败，而不是只留下一个没有细节的整体失败，让您自行猜测。

在做出决定前，对比两个模型

先用 80 亿参数的模型，再用 270 亿参数的模型运行同一套测试，可以得到量化的质量指标和耗时，而不是仅凭主观印象。

跟踪更新后的性能退化

当提示词或模型版本的变更导致质量下降时，会在用户抱怨之前反映在聚合评分中。

这些情况的共同点是：都无法通过重新阅读代码来解决。错误响应的根本原因在于传输过的数据——确切的提示、检索到的段落、生成的回复——如果这些数据未在调用时被记录，就不存在于任何其他地方。这正是在上线前而非首次故障后安装可观测性的重要依据。

#费用与功能限制

这并不会使模型表现更优

可观测性负责测量，不会修复任何问题。它会告诉您该从哪里排查。

它会存储你的对话

即使自行托管，提示词内容也会写入磁盘；如果没有数据保留策略（企业版功能），数据就会无限期保存。不过，SDK 提供了数据遮蔽（masking）功能，可在发送追踪数据前移除敏感信息。

需要持续维护的堆栈

备份、更新、迁移：文档本身就说明 Docker Compose 不提供备份功能。对于个人实验来说，这样的维护负担过于繁重。

这种情况通常出现较晚

安装它的合适时机是在投入使用之前，而不是在第一次静默故障之后。

• 来源：Langfuse 官方GitHub仓库
• 来源：Ragas官方仓库，用于RAG评估

#FAQ