在 Langfuse 上配 LLM-as-Judge，五个真坑我替你踩过了

上个月给我自己的 Teaching Agent 装 Langfuse 的 LLM-as-Judge 自动评测。从配置到上生产，看着 Langfuse 后台哗哗出分挺爽，但中间踩的坑比我想象多得多。这篇不是官方文档的搬运，是我自己一遍遍试出来的东西——特别是 Prompt 怎么写、开关什么时候开、Token 怎么不爆，这三件事文档里没怎么说人话。

下面 6 步是完整的操作流程，关键的地方我会把我当时怎么处理的、为什么这么处理都写出来。

1. 先把"裁判"装上脑子：LLM Connection

Langfuse 的在线评测核心是 LLM-as-Judge——也就是用一个大模型当裁判，来看你 Agent 的输出并打分。裁判自己也是个 LLM，所以你得先把 LLM 服务接进来。

点击左下角 Settings → LLM Connections：

页面顶部那行小字其实很重要：Connect your LLM services to enable evaluations and playground features. Your provider will charge based on usage.——意思就是这笔钱是算到 LLM 提供商头上的，不是 Langfuse 收的。

点 + Add LLM Connection，表单里要填的字段是这四个：

• Provider：LLM 提供商标识，你自己取个名字，比如 hy3-preview、venus-deepseek
• Adapter：协议适配器，选 openai 不是说只能用 OpenAI 的模型——是说"我的接口长得像 OpenAI 那样"，国内绝大多数模型（混元、DeepSeek、通义、智谱）都兼容
• Base URL：模型服务地址，可以是你自己部署的代理，也可以是官方 API
• API Key：认证密钥，填完会加密存

填完别急着建 Evaluator，先去 Playground 验证一下。Playground 是个很多人忽略但其实最关键的环节：选个下拉框里刚加的连接，发一句 hello 你是什么模型？——能看到正常回复，再继续。

我栽过最冤的一次就是：API Key 填错一位，Playground 直接 401，我没看就关了，导致后面 Evaluator 跑出来全是 0 分，回头查 Log 才发现是连接根本没通。

2. 真正难的从来不是配置，是 Evaluator 的 Prompt

这一步是整个流程里真正花时间的地方。Evaluator 的本质就是一段 Prompt 模板 + 评分配置，但 Prompt 怎么写，文档里没讲人话。

点 Evaluation → Evaluators → Set up evaluator 进入创建页：

这个页面我要重点拆三块——这三块是 Prompt 写得"能不能用"的关键。

2.1 Prompt 三块拆解：角色、变量、推理链

一个能用的 LLM-as-Judge Prompt 要写三块东西，缺一块都不稳。

第一块：角色定义要足够窄。 我第一版 Prompt 这么写的：

你是一个 AI 评审专家，请评估 Agent 的回答质量。

跑出来 50 条 trace，分数全是 0.7、0.8，分不出好坏。后来我改成：

你是一个负责"意图识别结果评估"的评审专家。请判断 Teaching Agent 输出的 intent 类别是否与用户输入的语义最匹配。评估范围仅限意图分类这一环节， 不要评价回答内容本身的质量。

效果立刻不一样——分数从 0.6 一直到 1.0 都出现了。角色越具体，裁判越知道自己要评什么。"AI 评审专家"是个什么都能评的空帽子，"意图识别评估专家"才是真正的岗位。

第二块：{{input}} 和 {{output}} 是自动注入的。 Prompt 模板里这两个变量是 Langfuse 自动替换的——{{input}} 会塞入当前 Trace 的用户输入，{{output}} 会塞入 Agent 输出。你只要在 Prompt 里写上变量名就行，不用自己处理数据流。页面下方"Available variables"那一列会列出当前可用的所有变量，根据你的 Agent 结构还可能有 {{metadata}}、{{tool_calls}} 之类的。

第三块：一定要让裁判"先说理由，再打分"。 页面最下面有块容易被忽略的 Score Reasoning Prompt。我第一版只填了主体 Prompt，没填这块，结果发现裁判给分极其不稳定——同一条 trace 跑两次分数能差 0.3。后来填上：

用一句话简要说明评分理由，包括：识别的意图是什么，是否正确， 判断依据是什么（关键词匹配 / 语义匹配 / 上下文推断）。

这是 Chain-of-Thought（思维链）的应用：让裁判在给分之前先"写一遍解题过程"。稳定性立刻上来了，而且你能直接通过 Log 看到裁判的推理过程——调试评分质量时这是最重要的入口，比看分数本身有用。

2.2 分数区间的语义必须写死

Score Output Prompt 我现在用的是这套定义：

返回 0 到 1 的数值分数。 - 1.0：意图识别完全正确 - 0.5：可接受的次优选项（识别方向对，但选了相邻类别） - 0.3 及以下：明显错误

不定义区间语义的 Prompt 一定不要上线。我之前用过一版没定义的，裁判自己一套解释，今天 0.8 是"好"，下周跑出来 0.8 它觉得是"还行"——评分标准漂移到你都没法做趋势对比。

2.3 Score Type：Boolean 优先，Numeric 不是万能的

截图里我选的是 Numeric（数值型），但我后来发现意图识别这种"分类"场景其实 Boolean 更直接——要么识别对、要么识别错，0.5 反而是"拿不准"的灰色地带。

我这版截图用的是 Numeric 是历史原因——做对比实验时用。如果你刚配，优先用 Boolean，出了问题再升级到 Numeric。

3. 那个开关，决定你钱包还是不是你的

Evaluator 写完之后，还有一个最关键的开关：Run on live incoming observations。

开启后，每有一条新 Trace 进来，裁判立刻自动跑一次。听起来很美好对吧？我第一次配的时候直接打开了，第二天醒来一看账单：日均 3000 条 trace，混元当裁判，一个月下来模型侧成本多了 200 多块（按 0.8 元/千 token 算，裁判每次平均吃 800 token）。

我后来调整的策略是：

• 第一次接评测，先用关闭模式：只对历史 trace 抽样跑 100-200 条
• 人工 review 评分结果，确认分数分布合理、裁判的推理说得通
• 再开启 live 模式，但配合 Filter 把范围缩到只评 GENERATION 类型
• 采样：日活大的 Agent 用 10% 采样就够了，别全评

Run on 这个 Tab 我建议这么选：

• Observations（生产实时）——正式上线用，先小流量
• Traces (Legacy)（历史批量）——回溯分析、改完 Prompt 看效果
• Experiments（实验数据集）——A/B 对比新版本

我日常 90% 的时间用的是 Traces 回溯，因为改完 Prompt 之后要立刻看到历史数据的分数有没有变化，再决定要不要发版。

Filter 那一栏我一般固定写：type any of GENERATION。意思是只对模型生成的那一层 observation 打分，不对 tool call、retrieval 这些中间步骤打分——这能砍掉 60% 以上的成本，因为中间步骤 trace 数量远大于最终生成那一步。

4. 评分跑出来后，比分数本身更有意思的是 Log

配置完成并保存后，回到 Evaluation → Evaluators 就能看到运行状态：

我特别关注的两列是 Cost 和 Logs。Cost 不用说，钱的事永远要看。Logs 才是我打开最频繁的东西——每一条评测的裁判推理都在里面。

回到 Observability → Tracing 页面，你能看到每条 Trace 的右侧多了一列评分：

这些数字怎么用？我自己的四种用法是：

1. 看趋势：每天看平均分有没有突然下降。下降一般意味着 Agent 那边有改动或者上游 prompt 改了。
2. 挖 bad case：筛 0.3 分以下的 trace，看是哪些类型的输入容易栽。
3. 版本对比：改完 Prompt 我会重跑一遍历史 trace，对比前后平均分的变化——这是最直观的改进证据。
4. 顺手挖产品 bug：这是我最意外的发现。

4.1 评分数据里的两个反直觉发现

最后说两个我配完上线后意外挖出来的事，文档里都没教过我。

第一个：6% 的长期 0 分 trace 不是 Agent bug，是产品 bug。 上线第三周我翻 Log，发现有 6% 的 trace 长期 0 分。以为是 Agent 出 bug 了，结果查下来是产品同学上周新加了一个 intent 类别"教研反馈"，但训练数据还没补，所有落到这类的用户输入 Agent 全部识别为"其他"。这件事让我意识到评分数据不只反映 Agent 质量，也反映产品定义的稳定性。一个稳定的 Agent + 一个变动的产品意图库 = 评分长期低分。这时候该改的不是 Prompt，是去催产品同学补数据。

第二个：0.5 分反而是最有意思的信号。 我观察到 0.5 分对应的不是"中等质量"，而是"差不多对、但有偏差"——往往是模型选了一个相邻 intent，或者在多轮对话里跟丢了上下文。这种 trace 看起来"不算错"，但如果一周涨 5%，就是产品该优化的信号。比如我们最近 0.5 分的 trace 大幅涨，追下来发现是用户在多轮里改了主意，Agent 没意识到——这暴露出我们 prompt 里少了"意图重置"的逻辑。

收尾：这东西的 ROI 怎么算

我自己的体感：对线上 Agent 来说，LLM-as-Judge 不是"锦上添花"——是缺它你真的不知道 Agent 在干嘛。Latency 告诉你快不快，Token 告诉你贵不贵，但"答得对不对"这件事，在没有自动评分之前完全是黑盒。

唯一要算清楚的账是成本。按我现在的配置（混元当裁判 + GENERATION 类型过滤 + 10% 采样），日均 3000 trace 一天大概 1.5-2 块 token 钱。比招个实习生 review 便宜 100 倍，比完全不知道 Agent 在干嘛强 1000 倍。

如果你也想配，我建议先拿一周的历史 trace 跑一遍 Numeric 评分——光这一步你就能挖出至少 3 个你之前没意识到的产品/Agent 改进点。