Opik 在线评估规则：如何编写自定义 LLM-as-a-Judge 评分规则监控生产 trace-平芜编程栈

Opik 在线评估规则：如何编写自定义 LLM-as-a-Judge 评分规则监控生产 trace

【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm

生产环境中 LLM 应用产生的 trace 数量庞大，人工逐条查看不现实。Opik 的在线评估（Online Evaluation）规则允许你定义 LLM as a Judge 指标，对日志中记录的 LLM 调用自动打分，用于监控幻觉、回答相关性或任何任务特定的自定义维度。本文介绍如何在一个项目上创建一条自定义 LLM as a Judge 评分规则、让它持续监控生产 trace，并核对评分结果是否落到了 trace 上。

前提是你的应用已通过 SDK 将 trace 上报到 Opik：在线评估规则默认只对生产（SDK 记录的）trace 生效，实验（experiment）、playground 和优化运行（optimization run）产生的 trace 不在规则自动评估范围内。

创建规则要填的六个字段

进入你要监控的项目，打开rules标签页，点击新建规则。规则也可以通过 REST API 创建，本文以 UI 为例。创建时依次确认以下选项：

Name：规则名称。
Sampling rate：对生产 trace 的采样评分比例，100%表示全部评分。注意它只作用于生产（SDK 记录的）trace：实验产生的 trace 忽略该比例、规则匹配时始终会被评分；playground 和优化运行产生的 trace 同样忽略该比例，只有你在那次运行中显式勾选了该规则才会评估。
Model：执行 LLM as a Judge 的模型。如果 trace 中包含图片，必须选择支持视觉（vision）的模型。
Prompt：judge 使用的提示词。可以使用 Opik 内置的 Hallucination、Moderation、Answer Relevance 三个基础模板，也可以写自定义 prompt。prompt 中的变量统一使用{{variable_name}}格式。
Variable mapping：每个 prompt 变量从 trace 的哪个字段读取（使用 Agent as a Judge 方式时不需要填）。
Score definition：judge 输出的分数格式。可以定义多个分数，让同一条规则沿多个维度给 LLM 输出打分。Opik 底层会结合 structured outputs 机制保证 judge 始终返回分数结构。

方式一：Agent as a Judge（探索期推荐）

当你还在确定"到底要量什么"、或希望同一条规则兼容不同形状的 trace 时，用这种方式。做法很简单：在 prompt 里加入{{trace}}，Variable mapping 留空。文档给出的示例 prompt：

Read the trace below and decide whether the assistant answered the user's question. {{trace}}

此时 judge 会自己读取 trace，并配有以下工具：

read—— 读取 trace 或其某个 span
jq—— 抽取特定路径的值
search—— 在 trace 中查找文本
get_trace_spans—— 列出 trace 的 span
get_attachment—— 以图片、音频或文本形式获取附件

Agent as a Judge 为控制成本做了截断设计：Opik 会把放入 prompt 的 trace 截断，并引导 judge 做定向读取，小 trace 一次调用即可回答，大 trace 只读取需要的部分。还可以设置Max cost per evaluation (USD)硬性成本上限，单次评估达到上限后 judge 收尾并返回已有分数；留空则不设限。

两个注意点：

Agent as a Judge 要求所选模型支持 tool calling。模型不支持时，规则会退化为单次调用加截断后的 trace。
如果要写 span 级别的规则，用{{span}}替代；如果不想给 judge 任何工具、直接把 span 以纯 JSON 注入，用{{spans}}。

方式二：Variable mapping（需要固定评分口径时）

当某个指标需要在每条 trace 上评同一个字段、且希望分数随时间保持可比时，把 prompt 变量映射到 trace 的具体字段，judge 只收到该字段内容。文档给出的示例 prompt：

Decide whether the answer below is helpful. Question: {{question}} Answer: {{answer}}

对应的变量映射（文档示例，路径需与你自己应用的 trace 结构一致）：

question→input.messages[0].content
answer→output.messages[0].parts[0].content

这种方式的代价是映射路径必须与你的 trace 形状匹配：按你应用的 trace 写的映射，读不到另一种形状的数据（例如 playground 运行实验时写入的 trace）。如果一条规则要同时覆盖两种形状，应改用 Agent as a Judge。

可选分支：评估包含图片的 trace

当 trace 中含图片且使用视觉模型时，可以在 prompt 编辑器中点击"Images +"按钮添加图片变量，再在 Variable Mapping 中把它映射到 trace 中存放图片数据的字段。例如文档示例中的图片质量评估规则将output_image映射到output.image_data（具体路径以你的 trace 结构为准）。

两点文档明确的行为：

添加图片变量后，Opik 会自动在 prompt 中追加一行，图片被<<<image>>><</image>>>标签包裹；该包裹在 UI 中不可见，但保证评估时图片被正确处理。
支持的数据形式为 image URL 或 base64 编码的图片。

核对评分结果

规则产生的分数会以 feedback scores 的形式存到对应 trace 上，验证路径有两条：

单条 trace：打开 trace 详情，在 traces sidebar 中查看该规则写入的分数。
项目整体：traces 表格会显示项目内所有 trace 的平均 feedback score，配合 Opik dashboard 可以跟踪分数随时间的变化。

对于规则创建之前已存在的历史 trace，新规则默认不会回溯评分。手动补评的操作路径：在项目的Traces（或 Threads）标签页选中要评估的 trace → 点击工具栏中的大脑（brain）图标 → 选择要应用的在线评估规则。评估耗时取决于规则配置的模型，进度可以在规则日志中查看，或刷新 UI 中的 trace 列表。

边界与限制

规则只对匹配范围的 trace 生效；thread 和 span 级别的规则只运行在生产（SDK 记录）数据上，实验、playground 和优化运行的 thread/span 完全不参与在线评估。
thread 规则（针对整段对话而非单条 trace）与本场景不同：它们没有变量映射选项，固定使用{{context}}变量读取整段对话，且线程最后一次活动后需等待冷却期（默认 15 分钟，self-hosted 环境通过OPIK_TRACE_THREAD_TIMEOUT_TO_MARK_AS_INACTIVE环境变量配置）才会触发评估。
内置的 Hallucination、Moderation、Answer Relevance 三个指标适合起步；复杂任务需要自定义 prompt 时，文档建议先在 Opik 的离线评估平台上把指标调稳定，再用于生产规则。

更完整的规则定义、内置模板与历史数据补评说明，见 Online Evaluation rules。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考