opik-online-eval

在线评估 — 让评审器正式运行

完成定义：项目上存在一条在线评估规则，已启用，且至少为一条新轨迹打过分——通过读取一条新轨迹的反馈分数确认，而不是以创建调用返回为准。该规则针对一种故障模式打分，采样率符合项目流量承受能力，设有费用上限，且变量映射到轨迹实际包含的字段。如果流量尚未到达，完成状态为“规则已上线，尚未验证——监控此筛选条件”。如果无法创建规则，停在第一个确实存在的阻碍，并且只返回一个后续步骤。

操作原则：**每条规则针对一种故障模式，先采样再扩大规模，设置费用上限，在真实轨迹上验证——不更改任何应用代码。**此技能只会写入 Opik。

输入

入口可以是 /opik-online-eval <what to score>（“幻觉”“退款期限答案”“拒绝”）、在 /opik-evaluate 验证评审器后立即运行 /opik-online-eval（让该评审器正式运行），或 /opik-online-eval <project>。推断其余内容；以下均视为可选覆盖项：

• 项目（默认：已配置） · 范围（默认：trace；单次模型调用用 span，完整对话用 thread） · 采样率（默认：每天约 1k 条轨迹以下为 1.0，否则为 0.1–0.2） · 筛选条件（默认：无；常见设置：environment 或标签筛选条件） · 评审器模型 · 费用上限（默认：设置一个） · 变量映射（默认：input → input、output → output）。

只有遇到确实存在且无法推断的阻碍时才询问（见 阻碍）。

激活 — 唯一属于此流程的工作

1. 确定项目、评审器和范围

确认 Opik 可访问（~/.opik.config 或 OPIK_API_KEY；否则 → 阻碍）。从轨迹或按名称解析项目 ID。确定评审器：

• 如果 /opik-evaluate 已验证过评审器 → 原样复用其提示词和输出架构。
• 如果是命名指标（幻觉、答案相关性、审核）→ 针对该单一故障模式编写最简二元评审器（../opik-evaluate/references/write-judge-prompt.md）。
• 如果是机械检查（JSON 是否有效、是否包含免责声明、延迟预算）→ 使用 Python 指标规则，而不是评审器。

范围：默认使用 trace；如果检查针对单次 LLM／工具调用，则使用 span；如果检查需要完整对话，则使用 thread（线程规则会等到线程变为非活动状态后才运行——默认等待 15 min）。

2. 映射变量前先查看轨迹

读取最近的三条生产环境轨迹，并记录 input 和 output 的实际结构。实验运行会以不同的输入结构落在同一项目中（其元数据包含 test_suite_experiment_id），因此跳过这些运行——按应用入口筛选是可靠的方式：client.search_traces(project_name=…, max_results=3, filter_string='name = "<entrypoint>"')。（OQL 对 metadata.* 键不支持 is_empty。）变量是普通字段路径，嵌套键使用点号表示法（output.answer、input.messages）——绝不使用 {{ }} 模板。路径错误是规则悄无声息地不打分的最常见原因。

3. 检查现有运行规则

import opik
client = opik.Opik()
existing = client.rest_client.automation_rule_evaluators.find_evaluators(project_id="<project_id>")

如果已有同名规则或针对相同故障模式的规则 → 不要创建第二条；报告 exists（可提出调整采样率／启用规则）。连接托管 MCP 后，list('online_rule', project_id=…) 和 list('score_name', project_id=…) 会显示相同的信息，包括每条规则的类型、启用状态和采样率。

4. 创建规则

没有高级 SDK 封装；请使用 REST 客户端。LLM-as-judge，追踪范围：

from opik.rest_api.types import (
    AutomationRuleEvaluatorWrite_LlmAsJudge, LlmAsJudgeCodeWrite,
    LlmAsJudgeModelParametersWrite, LlmAsJudgeMessageWrite, LlmAsJudgeOutputSchemaWrite,
)

rule = AutomationRuleEvaluatorWrite_LlmAsJudge(
    action="evaluator",                     # required literal; the model rejects the payload without it
    name="refund_window_correct",           # becomes the feedback-score name on every scored trace — use underscores, not hyphens: OQL parses `feedback_scores.a-b` as an operator
    project_ids=["<project_id>"],
    sampling_rate=0.2,                      # fraction of SDK-logged traces scored
    enabled=True,
    filters=[],                             # e.g. [{"field": "tags", "operator": "contains", "value": "production"}]
    code=LlmAsJudgeCodeWrite(
        model=LlmAsJudgeModelParametersWrite(name="<judge model>", temperature=0.0),
        messages=[LlmAsJudgeMessageWrite(role="USER", content="<the validated judge prompt using {{input}} and {{output}}>")],
        variables={"input": "input", "output": "output"},          # field paths from step 2
        schema_=[LlmAsJudgeOutputSchemaWrite(name="refund_window_correct", type="BOOLEAN",
                                             description="True if the response states 5-7 business days")],
        max_cost_usd=5.0,                   # per-rule spend cap — set it
    ),
)
created = client.rest_client.automation_rule_evaluators.create_automation_rule_evaluator(request=rule)

说明：在 Opik Cloud 上，如果没有自己的提供商密钥，model.name="opik-free-model" 会使用工作区内置的免费提供商；Python 属性为 schema_（传输名称为 schema）；sampling_rate 仅适用于生产追踪（实验追踪始终会完整评分）；trigger_scope 默认为 production。Span 和线程变体：AutomationRuleEvaluatorWrite_SpanLlmAsJudge、AutomationRuleEvaluatorWrite_TraceThreadLlmAsJudge。Python 指标：AutomationRuleEvaluatorWrite_UserDefinedMetricPython，使用 code={"metric": "<python source defining a BaseMetric>", "arguments": {"output": "output"}}。

如果要在 Python 之外编写脚本，端点为：POST /v1/private/automations/evaluators/，请求体相同。

5. 在真实追踪上验证

import time
for _ in range(12):                                          # ~2 min
    scored = client.search_traces(project_name="<project>", max_results=1,
                                  filter_string='feedback_scores.refund_window_correct is_not_empty')
    if scored: break
    time.sleep(10)

如果评分名称中已包含连字符（现有规则），请将键用双引号括起来，否则 OQL 解析器会把连字符当作运算符：filter_string='feedback_scores."refund-window-correct" is_not_empty'。 追踪获得了评分 → live。没有评分，且项目在此时间范围内没有新追踪 → live_unverified，并附上用于监控的筛选条件。没有评分，但确实有新追踪 → 查看规则日志（get_evaluator_logs_by_id(id)）——变量路径错误或模型故障会显示在那里；修复后重新验证。

6. 汇报

规则名称/ID、范围、采样率、费用上限、评分名称、验证追踪链接，以及一个后续步骤（参见输出）。自然的后续步骤：/opik-diagnose 现在会显示此名称下的低分；针对评分阈值设置提醒；或者，如果此前未验证过评判器，则“用 20 个人工标签验证它（/opik-evaluate），再让任何人依据它采取行动”。

阻碍

遇到最早的阻碍时立即停止，并且只返回一个后续步骤：

• "运行 opik configure，然后重新运行 /opik-online-eval。"
• "应该为哪个项目评分？请传入 /opik-online-eval <what> <project>。"
• "追踪的 output 是 {answer, sources}——评判器应该读取 output.answer 吗？（除非你另有说明，否则我会按此映射。）"——仅在映射确实存在歧义时询问。
• "规则应该捕获哪种故障模式？请说出一种（例如幻觉、退款时间范围错误、不安全内容）。"

输出

**面向用户：**简短的人类可读消息——规则（名称、范围、采样率、上限）、评分名称、可点击的 Opik UI 验证追踪链接（若未验证，则提供监控筛选条件），以及唯一的后续步骤。不是 JSON。

底层（用于组合 / 评估），采用以下结构：

• status：live | live_unverified | exists | blocked
• rule：id、name、type（llm_as_judge | user_defined_metric_python | span/thread 变体）、scope、sampling_rate、filters、max_cost_usd、enabled
• score_name
• variables：使用的字段路径映射
• verification：trace_id、trace_url、value（当状态为 live 时）；watch_filter（未验证时）
• source：sdk | mcp
• next_step：恰好一个

不变量：live 必须包含 verification.trace_id；每个已创建的规则都必须有 max_cost_usd 和 sampling_rate；每条规则只针对一种故障模式；exists 表示未创建任何内容；blocked 必须且只能包含一个 next_step；无论采用哪条路径，代码库都保持不变。

示例

经过验证的评审器上线。 /opik-evaluate 校准了“将退款期限表述为 5–7 个工作日”（TPR 0.95）。/opik-online-eval：项目 support-bot，每天约 5k 条追踪记录 → 采样率 0.1，筛选条件 tags contains "production"，上限 $5，映射 output → output.answer（追踪记录将其嵌套在此处）。已创建；40 秒后，一条追踪记录携带 refund-window-correct = 1。→ live；下一步 = “当 1 小时均值低于 0.8 时发出警报”。

机械检查。“确保每个生产环境回答都是有效的 JSON。”→ Python 指标规则（对 output 使用 IsJson），采样率 1.0（成本低），不使用评审器。→ live。

暂无流量。 在一个仅在工作时间接收追踪记录的项目上创建了规则。→ live_unverified：“监控 feedback_scores.<name> is_not_empty——或发送一个带追踪记录的请求”。

已经存在。 名为 hallucination 的规则已存在、已启用，采样率为 0.5。→ exists；下一步 = “如果关注的是成本，将采样率降至 0.1”。

反模式

在高流量项目上设置 sampling_rate: 1.0 却不说明成本；不设置 max_cost_usd；在变量中使用 {{input}} 形式的模板语法（它们是字段路径）；将整体“质量”评审器用作规则；对机械检查使用评审器；为同一种失败模式创建第二条规则；未取得带评分的追踪记录就根据创建调用宣称成功；将未经验证的评审器直接上线并把它的评分当作事实；编辑应用代码。

参考资料

生产和可观测性细节见与本工具一同安装的 opik 技能——相对于此文件的路径：../opik/references/production.md（在线评估、变量映射、反馈评分、警报）、../opik/references/observability.md（追踪记录／跨度／线程模型）、../opik/references/evaluation-datasets.md（OQL 筛选条件、feedback_scores.<name> 运算符）。评审器设计：../opik-evaluate/references/write-judge-prompt.md、../opik-evaluate/references/validate-evaluator.md。如果宿主环境采用不同的技能目录结构，请找到 opik 技能的 references/ 目录。

如果未安装 opik 技能，请在报告中说明，并使用 https://www.comet.com/docs/opik/，不要凭记忆作答。