Langfuse 云端旧评估器停用后的迁移
据文中所述,Langfuse Cloud 于 2026 年 11 月 16 日切换到 v4,旧的追踪级模型评估器随之停止出分,自托管版没有统一的强制切换日。文章给出升级 SDK、在应用内执行迁移,以及在根观测上配置观测级评估器的做法。
AI 深度解读
按原文援引的迁移计划,Langfuse Cloud 已于 2026 年 11 月 16 日切到 v4。旧的 trace 级 LLM-as-a-judge 评估器停止产出新分数,历史分数仍可查。自托管没有统一切换日期。
这次迁移最容易漏掉的是评分口径。原来一次请求记一分,换成 observation 级评估器后,一次请求可能记三分。单次请求的评估通常能在 Langfuse 内迁完。要判断多轮对话是否完成了任务,还得决定何时评分,以及评审模型能看到哪些证据。
评估器迁完,为什么一条请求可能多出三条分数
一条 trace 记录一次请求或一次 Agent 运行,里面可以有检索、模型调用等多条 observation。Langfuse v4 改用一张反规范化的 observations 表,查询时省掉 traces 和 observations 之间的关联。评估器也跟着迁到 observation 层。线上数据推荐用 observation 级评估器,LLM-as-a-judge 也可以跑在 experiments 上。
旧评估器对每条 trace 写一个分数,新评估器对每条匹配的 observation 写一个分数。同一条 trace 命中三条 observation,就会写三条分数。如果仪表盘直接按分数算通过率,命中三次的请求就会占三份权重。迁移后的默认过滤条件是 isRootObservation = true。根 observation 已经带齐输入、输出和其他评分变量时,可以直接用它。变量散在不同 observation 时,可以把它们集中写到根节点或专用评估节点,也可以用 propagate_attributes() 向下传递 trace 字段。
采集端需要 Python SDK v4.7.0 或更高版本、JS/TS SDK v5.4.0 或更高版本。直接通过 OpenTelemetry 上报时,用请求头 x-langfuse-ingestion-version: 4。升级后,trace 的输入和输出不会再自动写入。如果旧评估器还要读取这些字段,验证新评估器前要继续调用 Python 的 set_current_trace_io() 或 JS/TS 的 setActiveTraceIO()。Python SDK v5 和 JS/TS SDK v6 已移除各自的这个方法。随后到应用内的 Evaluation 页面升级,Cloud 上的小改动由 Halo 辅助,自托管走编程助手流程。
原文建议切换前在同一批流量上并跑新旧评估器,核对分数和数量,确认后再停旧评估器。切换前还可以停用新的、重新启用旧的。按原文所列时间表,Cloud 的这段窗口已经过去,旧 v3 API、功能和数据摄取也随切换移除。现在补迁时,可以用可关联的历史分数做回看,再用新流量验证评分数量和告警是否恢复。自托管 v3 的安全补丁提供到 2027 年 1 月。自托管 v4 会在启用 events_only 后停止运行旧评估器,官方建议把评估器迁移安排在启用该模式前的最后一步。
整段对话什么时候算结束,评分时又能看到什么
用户把同一个请求重复三遍,或者 Agent 在退款前两轮漏做身份校验,这些问题要把多轮消息连起来才看得见。如果规则还要判断 Agent 是否真的执行成功,评审模型得看到操作结果。Langfuse 无法自行判断 session 何时结束,因此内置评估器不能直接对 session 跑。原文提到,多 span 评估已列入计划,文档还没描述为可用能力。
留在 Langfuse 的做法是把完整历史写进根 observation,或者写进那次接收完整历史的 LLM 调用,再用 conversation_end 之类的标签只评最后一轮。结束时机由应用判断。另一条路是自己跑评估任务,提交分数时只带 sessionId。
作者团队的 Agnost AI 用空闲 15 分钟来判断何时批量评估。规则用自然语言英文写,每条助手消息只有通过或失败,没有数值分,也不保存评审推理。评审只读对话,工具和子 Agent 的 span 不进入评审输入。它在套餐上限内逐段评估,不做采样。Free、Starter、Pro 每月分别限 1,000、10,000、1,000,000 个事件,新增或修改规则会回评最近 1,000 段对话。告警可发到 Slack 或邮件,可以触发 Auto Improve 开 PR 供团队审核。它没有 webhook 或 CI 集成。接入时可以在同一条 OpenTelemetry 链路上增加第二个 span processor,保留 Langfuse 原有的追踪和评估。
其他工具的差别主要在结束判定、评审输入和运行上限。LangSmith 按已结束的 thread 评分,默认空闲 10 分钟,最短可设 2 分钟,能评完整消息或包含工具调用的轨迹,也支持采样和过滤。trace 要带消息列表,只处理过去 7 天的运行,每次最多 500 个 thread,每个工作区最多 10 个多轮评估器。Braintrust 支持 span、trace 和 group,trace 默认等 30 秒空闲,评审可引用 {{thread}},group 默认把 24 小时内最多 64 条关联 trace 一起评。Arize AX 支持持续做 session 评估、按 session 采样和一次回填,结果写到首条 trace 的根 span。开源 Phoenix 要自己取 span、按 session 分组、运行评审并写回。Opik 支持 trace、thread 和 span,thread 默认冷却 15 分钟,旧数据要手动补跑,Pro Cloud 每月 19 美元。
我的判断
原文最扎实的提醒是先核对每次请求产生几条分数,再看通过率。这个变化直接来自评估对象,分数看着接近也可能掩盖问题。比如同一个请求里的检索和生成都被计入,仪表盘上的分母已经变了。单问单答、一次检索加一次回答、一次 Agent 运行,只要能把评分需要的字段稳定放在同一个 observation 上,留在 Langfuse 内迁移就能解决原文指出的兼容问题。
作者称 Langfuse 和其他厂商的文档都核对于 2026 年 11 月 12 日。原文没有给出迁移前后的分数对照,也没有比较各工具的误判率、评估成本或接入工时。「留在 Langfuse 最省钱」是作者的经验判断。作者同时是 Agnost AI 的开发方,产品功能可以作为选型线索,原文没有提供效果对照。
选整段对话的评估方案时,我会先看规则需要什么证据。判断用户有没有反复催促,消息通常就够了。判断退款前是否校验了身份、Agent 声称做完的操作有没有成功,如果这些结果只在工具 span 里,Agnost AI 的评审输入就缺了一块。LangSmith 可以把工具调用轨迹给评审看,还要确认应用确实记录了能说明结果的字段。有明确结束事件的产品可以用 conversation_end 控制何时打分。用空闲超时更容易接入,但用户暂停后回来继续聊时,同一段任务可能被提前评一次。
能拿来做什么
- 给现有评估规则逐条标明评分单位。单次问答、检索加回答、单次 Agent 运行可以先看根 observation 是否带齐变量。需要跨轮判断的规则,先列出它依赖的消息和工具结果。
- 如果 Node 或 TypeScript 服务仍靠
setActiveTraceIO()给旧评估器供数据,先检查字段有没有同步写到新评估器的目标 observation,再安排升到 JS/TS SDK v6。挑几条有多个 span 的请求,实际数一数每条 trace 产出了几条分数。 - Cloud 补迁时,从历史分数里挑通过和失败的请求,找回能关联的输入、输出和评分变量,用新评估器复评。上线后单独核对仪表盘与告警是否读到了新分数,并区分「没有失败」和「没有收到分数」。
- 给多轮客服或 Agent 加评估时,先挑一条只有跨轮才能发现的问题。用人工判定的几段完整对话测试结束条件和评分输入,再决定用最后一轮标签、自跑
sessionId评分,还是接入会话级工具。