接入 Langfuse 前，先把 LLM 失败复核链路想清楚

# 在接入 Langfuse 之前，先把 LLM 失败复核链路想清楚

AI Agent 出错时，最危险的往往不是这一次输出错了，而是下一次运行又在没有证据的情况下继续说“已经完成”。

如果没有人复核 trace、eval、prompt 变更和恢复动作，系统很容易把同一个错误重复一遍，只是语气更自信。Langfuse 的价值就在这里：它是一个开源 LLM engineering platform，覆盖 LLM observability、metrics、evals、prompt management、playground、datasets 等场景。

但真正适合开发者的第一个问题不是“要不要装 Langfuse”，而是：

> 我在信任下一次 LLM 运行之前，应该先检查哪些证据？

下面是一套更适合首次接入前使用的检查框架。

先说清楚一个定位：这不是提示词库，也不是“复制一段 prompt 就万事大吉”。Doramagic 的 Langfuse 包是一个能力资产，里面包含宿主指令、Prompt Preview、Human Manual、Pitfall Log、Boundary & Risk Card、eval 检查、smoke check、Test Log 和反馈路径。它的目标是让 AI 宿主基于证据工作，而不是让 Langfuse 看起来更“神奇”。

## 1. 先建立失败复核闭环

一个 LLM 应用的失败复核闭环，至少需要四类信息：

1. trace：这次运行到底发生了什么；
2. eval 或 score：这次结果是否达到最低验收线；
3. prompt 变更记录：这次修改到底改了什么行为；
4. recovery rule：下一次运行前必须先满足什么条件。

如果缺少这四件事，可观测性就容易变成“事后看仪表盘”。真正有用的做法，是要求 AI Agent 在声称完成之前说明：它有什么证据、证据来自哪里、哪些地方还没有验证。

## 2. 把 Prompt 变更当成生产变更看

Prompt 看起来只是文本，但它可能改变路由、工具选择、输出格式、评分逻辑和异常处理方式。

接入 Langfuse 时，Prompt 管理不应该只是“保存几个版本”。更实用的检查问题是：

- 改了什么？
- 影响哪个任务、数据集或调用路径？
- 修改后 score 或 eval 有没有变化？
- 这个变化是在单个样例上有效，还是在可重复集合上有效？
- 如果效果变差，能不能回滚？

这对 AI 编码场景尤其重要。因为一个 Agent 可能在同一轮里同时改代码、改提示词、改测试。如果没有 trace 和 eval 分离，团队很难判断到底是代码质量提升，还是评估标准变宽了。

## 3. 不要跳过边界卡

Doramagic 的 Langfuse 能力包里有一个很重要的边界：它不是“已经在你的环境中安装、配置、生产验证通过”的证明。

真实接入前，至少要检查：

- 是否在临时环境、临时目录或容器里验证；
- 是否避免使用生产密钥、私人数据、主力配置目录；
- prompt 或配置变更是否可以回滚；
- 运行结果是否有真实 trace 或 eval 证据；
- 失败日志是否被记录下来，而不是被重试过程吞掉。

这一步很关键。仪表盘不是边界，trace 不是保证，score 也不天然等于发布批准。团队需要定义 score 如何使用、什么情况必须停下来、什么情况可以继续。

## 4. 注意真实集成坑，而不是把风险说成结论

Doramagic 的 Langfuse 包记录了一些 source-linked pitfall，需要在首次试用前复核。例如：scoring 行为、UI 中 unnamed trace、Semantic Kernel / Openlit 集成、self-hosted Kubernetes worker shutdown、BullMQ idle queue timeout 等相关问题。

这些信息不能被夸大成“Langfuse 一定有问题”。更准确的使用方式是：它们是试用前的检查点。

可以用一个简单的 GO / HOLD / NO-GO 规则：

- GO：最小 trace 能捕获，eval 或 smoke check 可见，回滚路径明确；
- HOLD：trace 存在，但 scoring、命名、worker 行为或集成兼容性不清楚；
- NO-GO：Agent 没有运行证据却声称成功，或者基础验证前就要求生产密钥和真实数据。

## 5. 第一步不要让 Agent 直接上生产

如果你把 Langfuse 相关能力包加载进 AI coding host，第一条指令不应该是“帮我部署到生产环境”。

更安全的第一条指令应该是：

```text
基于这个包，识别 Langfuse 失败复核工作流的第一个安全验证步骤。
除非我明确允许，不要调用外部工具。
没有 trace 或 eval 证据之前，不要声称 Langfuse 已安装或已工作。
```

这个任务的目标不是马上完成接入，而是得到一个边界清楚的下一步：验证什么、证据从哪里来、失败信号是什么。

## 6. 适合什么场景

这套思路适合正在构建或运行 LLM 应用的团队，尤其是需要让 AI Agent 从证据出发，而不是凭解释声称完成的场景。

它可以帮助团队把 trace、eval、prompt 变更和恢复动作接到同一个复核链路中。但它不能替代 Langfuse 官方文档，也不能证明生产环境已经安全。

更准确的理解是：

> Langfuse 可以提供可观测性表面；你的流程仍然需要边界、验收规则和回滚习惯。

参考资料：Doramagic 整理的独立 Langfuse 项目说明书：  
https://doramagic.ai/en/projects/langfuse/manual/

上游项目：  
https://github.com/langfuse/langfuse

声明：本文基于 Doramagic 对 Langfuse 的独立能力包整理，不代表 Langfuse 官方立场，也不表示上游项目对该能力包背书。