creating-online-evaluations

创建在线评估

在线评估会自动对每个匹配的 $ai_generation 或包含它的整条轨迹进行评分，直到评估被禁用。好的评估源自你在生产流量中发现的真实故障模式，而不是猜测，也不是“幻觉”或“有帮助性”这类通用指标。这项技能从识别出这些故障模式后开始，将它们转化为范围明确、持续运行的评估。

每种故障模式对应一个评估，数据支持多少种就创建多少个。 应创建多少个评估，取决于你从实际轨迹中发现的情况——有时是一个，通常是三到四个。不要默认答案只有一个，也不要把无关的故障模式合并到一个评估器中。例外情况是，一组模式属于同一项检查的不同结果，例如回复未能满足用户请求的各种原因：为每种模式设置一个类别的分类评估就适合这种情况（2.1）。

先提出方案，再创建。 向用户提供一份简短的候选评估列表，让他们选择想要的评估（阶段 1.1）。创建用户未要求的评估会增加他们的费用和噪声。

首先，明确要评估什么。 找出并排列值得捕捉的故障模式，是一项独立工作。如果用户没有说明想要评估什么，就询问他们。如果用户仍然没有明确说明，也没有提及具体的故障模式，请运行 exploring-ai-failures，以明确使用场景、找出失败的轨迹，并生成按优先级排序的故障模式列表。

关于_编写和迭代_评估器的具体操作（Hog 源码与 LLM 裁判提示词、试运行、调试线上评估），请参阅 exploring-llm-evaluations。

工具

工具	用途
posthog:llma-evaluation-config-get	检查未固定裁判使用的当前提供商密钥
posthog:llma-provider-key-list	查找可用的（ok 状态）提供商密钥以进行固定
posthog:llma-evaluation-judge-models	列出有效的提供商与模型组合
posthog:llma-evaluation-directory-list	列出可用于整理评估的目录
posthog:llma-evaluation-directory-create	用户要求新建目录时创建目录
posthog:llma-evaluation-test-hog	创建前，用近期生成内容试运行 Hog 源代码
posthog:llma-evaluation-create	创建评估（始终先设置 enabled: false）
posthog:llma-evaluation-run	针对一次生成内容运行草稿评估
posthog:llma-evaluation-update	迭代配置，然后将 enabled 切换为 true
posthog:llma-evaluation-backfill-estimate	统计对过去的数据进行回填评估时的评估数量
posthog:llma-evaluation-backfill-create	评估过去的数据，仅在用户确认估算结果后进行
posthog:llma-evaluation-backfill-get	跟踪回填的进度和覆盖范围
posthog:llma-evaluation-backfill-list	查找某项评估的回填任务，包括正在运行的任务
posthog:llma-evaluation-backfill-cancel	用户要求时停止正在运行的回填
posthog:execute-sql	验证条件是否匹配预期的事件和数据量
posthog:generate-app-url	构建包含区域和项目信息、可直接跳转至评估页面的链接

完整的创建负载（所有字段、配置架构以及确切的 conditions 结构）请参阅 references/evaluation-payload.md。

阶段 1 — 决定要提议什么，然后让用户选择

从实际观察到的故障入手，而不是预先选定指标。如果你还没有相关故障， 先运行 exploring-ai-failures，界定用例、查找失败轨迹，并生成按优先级排序的故障 模式列表，然后再回来。

1.1 — 将故障模式转化为候选集

让数据决定候选数量。 一个故障模式对应一个评估，因此，包含四种不同模式的排序列表 就是由四个评估组成的候选集。不要把它们合并成一个试图捕获所有问题的评估器；如果轨迹 明确显示还有其他值得关注的问题，也不要只选最靠前的模式。保留候选项的条件：

• 影响大。 出现频繁或造成明显损害。通常少数几种模式就涵盖了大多数故障。
• 可检查。 能归纳为一个明确标准——“回复必须围绕用户的话题”，“工具调用必须包含 order_id”。如果无法用一句话说清楚，就还没准备好提议。
• 彼此不同。 两个会在同一批生成结果上失败的候选项，实际上算一个评估。

按影响程度排序，提议排名大致靠前的五项；用一句话说明你把较弱的候选项暂时搁置了，而不是悄悄删掉它们。

1.2 — 用通俗语言提议候选集

绝不创建用户尚未选择的评估。 列出候选项，并询问用户想设置哪些评估。

假设他们还没有和你一起查看过轨迹，也不了解评估术语。每项控制在一两行——每个评估都写成长篇大论，会让他们无法比较——但要清楚说明它监测什么，以及失败时会发现什么问题。这里不要提供 Hog 代码片段、属性筛选条件或 hog/llm_judge 的内部细节。给每项编号，方便他们回复“1 和 3”：

发现了 3 种值得关注的故障模式。你想设置哪些？

1. 回复偏离主题 — 检查答案是否回应了用户实际提出的问题。 捕获那些自信地回答了另一个问题的支持回复。每天约出现 40 次。

2. 订单查询缺少订单 ID — 检查每次 lookup_order 调用是否都包含 order_id。 捕获导致 Agent 编造订单状态的静默工具故障。每天约出现 15 次。

3. 拒绝回答本可解答的问题 — 检查回复是否不必要地表示“我无法帮你处理这个问题”。 捕获那些将用户拒之门外、但文档其实已涵盖的情况。每次检查都会产生一次大模型调用。

每个评估都要说明：检查什么、会揭示什么问题，以及已知的大致发生频率（第 2.5 阶段会进行正式验证）。标出需要 LLM 评判器的评估，因为它们每次运行都会产生成本——这是唯一值得提前说明的机制。排名顺序中隐含优先级即可，不要使用评分表。

如果用户似乎拿不定主意，就推荐一个起点（通常是排名最靠前的一两项）；将“全部都要”或“继续吧”视为接受整个候选集。如果调整提示词可能解决某种模式，就在评估旁边同时提出修复建议，而不是用修复建议取代评估——通过率上升可以确认修复已经生效。

1.3 — 没有发现故障时，提议情绪评估

如果已经查看了轨迹，但没有发现值得评估的故障模式，不要凭空捏造故障，也不要空手而归。说明你检查了什么，然后将 sentiment 评估作为基础选项提出：

过去 7 天没有发现明显的故障模式。可以先从以下评估开始：

1. 用户挫败感 — 将每条用户消息标记为正面、中性或负面。 显示哪些对话进展不顺，而真实故障通常就藏在这些对话中。无需支付评判器费用。

它不需要服务提供商密钥，成本也低；当流量足以发现模式时，它还能提供信号，方便之后继续分析。

没有生成结果，就不能进行任何类型的评估。 情绪评估只会为匹配的 $ai_generation 事件打分，因此，如果项目中没有这类事件，你能创建的所有评估——包括情绪评估——都会一直闲置，永远不会触发。不要提议创建评估。请引导用户使用 instrument-llm-analytics，先采集生成结果以实现 AI 可观测性；等有流量可供分析后，再回来使用此技能。

阶段 2 — 构建每个已接受的评估

对于用户选中的每个评估，各运行一次 2.1 至 2.5，使每个评估都成为经过验证的草稿。在整套评估全部验证完成之前，保持每个评估处于禁用状态——最后的 2.6 是针对已完成整套评估的一次性操作，不是每轮循环的最后一步。在评估 3 仍在编写时启用评估 1，会导致只有部分内容上线，这会带来噪声，也会让用户承担（对评审器而言）他们尚未同意的费用。

2.1 — 选择评估类型

使用……	适用情况
hog	结构性／基于规则的检查（JSON 解析、长度、正则表达式、工具调用形式）。成本低、结果确定、无需提供方密钥。
llm_judge	主观／模糊的检查（语气、事实准确性、切题程度）。每次运行都会产生一次大模型调用的费用；需要提供方和模型。只有启用时才需要可用的提供方密钥，创建草稿时不需要。
sentiment	你需要为用户消息添加情感标签，而非判断通过／失败（除非有非常明确的要求；通常与此技能无关）。

优先使用 hog，如果没有确定性的方法来检查目标，再升级到 llm_judge。

然后选择每次运行返回的内容。hog 和 llm_judge 支持以下三种输出类型：

output_type	失败模式……
boolean	单个是／否标准。默认值。如果检查检测到问题，设置 true_is_failure: true。
numeric	程度问题（1–5 的质量评分）或测量值（长度、延迟、成本）。
categorical	单项检查，其结果归入具名类别，例如多个相关失败模式中实际发生的某一种。

• **数值型：**设置 min 和 max，超出范围的分数将被跳过，而非评分。对于通过率和报告，添加 passing_rule（阈值的 gte 或 lte）。step 仅供参考：即使设置了 step: 1，评审器仍可返回 3.7 这样的分数，且分数会按原样存储。
• **类别型：**将 options 定义为稳定的小写键，并配上显示标签。仅有一个结果适用时，使用 single 选择；多个问题可能同时出现时，使用 multiple。对于通过率和报告，将计为通过的键设为 passing_rule.categories。在 single 模式下，通常应设置一个表示“没有问题”的键。在 multiple 模式下，不要定义表示“没有问题”的键，并将 categories: [] 设为空数组，这样只有空结果才能通过。任何列出的键都会使空结果不通过。
• 如果没有通过规则，数值型和类别型结果仍会记录，但不会生成通过率或报告。

当 llm_judge 返回 numeric 或 categorical 时，PostHog 会告知评审器输出格式。提示词只需说明每个分数或类别的含义。完整配置字段见： references/evaluation-payload.md。

2.2 — 选择目标

目标	行为
generation	每次匹配 $ai_generation 时运行一次，在数据写入后立即运行。这是默认值。
trace	在首次匹配的 generation 之后，等待可配置的时间以便 trace 完成，然后针对整个 trace 运行一次。
session	在 session 稳定后，针对整个 $ai_session_id session 运行一次。

对于 trace 目标，请发送 "target": "trace"，并附上用于控制何时评估 trace 的稳定配置，该配置由 strategy 区分：

• { "strategy": "fixed_window", "window_seconds": 1800 } — 在首次匹配的 generation 之后固定等待一段时间再评估。范围为 10 秒至 2 小时，默认值为 30 分钟。没有 strategy 键的 target_config 表示使用此策略。
• { "strategy": "inactivity", "quiet_period_seconds": 300, "max_age_seconds": 7200 } — 当 trace 在静默时段内没有新活动时进行评估（范围为 10 秒至 30 分钟，默认值为 5 分钟）。max_age_seconds 会限制从首次匹配的 generation 开始的总等待时间（范围为 1 分钟至 2 小时，默认值为 2 小时，且必须大于或等于静默时段）。

session 目标使用相同的稳定配置，但取值范围适用于 session，且默认使用 inactivity 而非 fixed_window：

• { "strategy": "inactivity", "quiet_period_seconds": 3600, "max_age_seconds": 86400 } — 当 session 在静默时段内没有新活动时进行评估（范围为 10 秒至 24 小时，默认值为 1 小时）。max_age_seconds 会限制从首次匹配的 generation 开始的总等待时间（范围为 1 分钟至 7 天，默认值为 24 小时，且必须大于或等于静默时段）。
• { "strategy": "fixed_window", "window_seconds": 1800 } — 在首次匹配的 generation 之后固定等待一段时间再评估（范围为 10 秒至 7 天）。

只有携带 $ai_session_id 的事件才会触发 session 评估。数据生产方要么在每个 generation 上设置它，要么完全不设置，因此不设置它的 SDK 永远不会触发 session 评估。$ai_session_id 不等于 $session_id：后者是 PostHog 的产品分析 session，与此无关。

session 评估也可能返回跳过，而不是评分。此时发出的 $ai_evaluation 事件会携带 $ai_evaluation_skipped: true 和 $ai_evaluation_skip_reason；如果该评估不允许 N/A，其 $ai_evaluation_result 则为 false。因此，分析通过率时必须排除跳过的运行，而不能将其计为失败。当 session 包含超过 2500 个事件（通常是多个对话共用同一个 session id）、在评估窗口内未找到任何内容，或对于 LLM 评审器而言，转录内容过长而无法完整发送时，session 会被跳过。

只要已完成的运行仍处于 Temporal 的保留窗口内，每项评估对同一个 session 最多运行一次。评估完成很久后恢复活动的 session 可能会再次被评估，因此应选择足够长的静默时段，确保 session 确实已经结束。较长的静默时段只会增加延迟。

条件仍与触发运行的 generation 匹配；评估器本身会接收完整的 trace 或 session。情感评估仅支持 generation 目标。

新的 Hog 源代码应使用所有目标共享的全局变量：

全局变量	含义
evaluation_events	对于生成目标，是一次生成事件；对于轨迹或会话目标，则是捕获到的每个事件。
target	目标的 type、id、total_cost_usd 和 total_latency_seconds。
item.input_text / item.output_text	尽力生成的可读文本；用于长度、关键词和正则表达式检查。
item.input / item.output	原始序列化值；当评估器需要解析捕获的 JSON 本身时使用。

对于会话目标，target.id 是会话 ID，target.total_cost_usd / target.total_latency_seconds 是该会话所有轨迹的总和。total_latency_seconds 是 AI 工作耗时，而非会话墙钟时间；两者可能相差几个数量级。会话墙钟时间可根据 evaluation_events 的时间戳推算。

生成评估仍会公开顶层的 input、output、properties 和 event。轨迹评估仍会公开原有的 events 和 trace 全局变量。为兼容已保存的评估器，保留了这些全局变量。会话评估不包含这些变量：会话 Hog 源代码只能接收 target 和 evaluation_events。不要在需要跨目标运行的新源代码中使用特定于目标的全局变量。文本投影能够识别常见的提供方载荷，但并非权威来源；需要精确结构时，请使用 item.input / item.output。

2.3 — 配置 LLM 评判器

创建 llm_judge 评估时，只需提供有效的 provider 和 model，即可将其保存为草稿。启用评估需要可用的提供方密钥，但保存时不需要；因此，没有 ok 状态的密钥意味着应保持评估禁用，而不是停止创建。provider_key_id 用于控制评估是否固定使用某个特定密钥：

• 将 provider_key_id 设为同一提供方下处于 ok 状态的密钥 UUID，即可固定使用该密钥。
• 将 provider_key_id 设为 null，即可使用团队的活动提供方密钥。这始终是有效的已保存值。要启用评估，活动密钥必须处于 ok 状态，且其提供方必须与 model_configuration.provider 相同。

Hog 和情感评估可跳过此步骤。

posthog:llma-evaluation-config-get        // check active_provider_key for an unpinned judge
posthog:llma-provider-key-list            // find an ok-state key to pin
posthog:llma-evaluation-judge-models      // {} → every provider and its models; { "provider": "openai" } narrows it

使用 llma-evaluation-judge-models 确认提供方和模型。 不带参数调用即可一次查看完整目录。 对于 PostHog 不提供资金支持的模型，结果会为空；除非传入团队某个密钥的 key_id。响应中的 providers 列表会标明哪些提供方属于此类。 列出的模型并非免费模型。运行任何 llm_judge 都需要使用团队自己的提供方密钥，因此在存在可用密钥之前，启用操作会失败。 建议固定所选密钥，以免之后团队级活动密钥发生更改，导致评估运行方式改变。 将 provider_key_id 保留为 null，即可使用团队的活动密钥；启用前，请使用 llma-evaluation-config-get 确认活动密钥可用且其提供方匹配。

没有可用密钥不会阻止创建。使用有效的 provider 和 model 创建禁用状态的草稿，供用户审核。不要试运行或启用，并请用户在 UI 中添加或验证密钥，以便之后启用。

2.4 — 创建时禁用

创建时设置 enabled: false，这样在验证范围之前不会触发。最简 hog 示例：

评估可以创建在顶层，也可以创建在一个目录中。如果用户指定了目录，请调用 posthog:llma-evaluation-directory-list，并将其 UUID 作为 directory_id 传入。仅当用户要求创建目录时才创建。 顶层评估请省略 directory_id 或传入 null。目录不能嵌套。

posthog:llma-evaluation-create
{
  "name": "Output is not empty",
  "description": "Fails when a generation has no readable output",
  "evaluation_type": "hog",
  "evaluation_config": { "source": "let count := 0\nfor (let i, item in evaluation_events) {\n    if (item.event == '$ai_generation') {\n        count := count + 1\n        if (length(trim(item.output_text)) == 0) { return false }\n    }\n}\nreturn count > 0" },
  "output_type": "boolean",
  "output_config": { "allows_na": false },
  "target": "generation",
  "target_config": {},
  "conditions": [
    { "id": "default", "rollout_percentage": 100, "properties": [{ "key": "$ai_model", "type": "event", "operator": "icontains", "value": "gpt" }] }
  ],
  "enabled": false
}

对于 llm_judge，将 evaluation_config 替换为 { "prompt": "…" }，并添加 "model_configuration": { "provider": "openai", "model": "gpt-5-mini", "provider_key_id": null }。 若要固定使用某个密钥运行，请将 provider_key_id 设为 llma-provider-key-list 中状态为 ok 的密钥 UUID； null 则使用团队当前启用的密钥。两种设置都会保存为草稿。字段完整说明： references/evaluation-payload.md。

2.5 — 启用前验证范围

conditions 是在线评估容易出错的地方：范围太宽，就会评估（并产生费用）大量事件；范围太窄，则永远不会触发。请确认筛选条件与预期事件匹配，并大致估算每天的事件数量：

posthog:execute-sql
SELECT count() AS matched, count() / 7 AS per_day
FROM events
WHERE event = '$ai_generation'
    AND properties.$ai_model ILIKE '%gpt%'      -- mirror each condition property
    AND timestamp >= now() - INTERVAL 7 DAY

对于 generation 目标，count() 就是运行量。对于 trace 目标，请统计非空 $ai_trace_id 的不同值，因为同一 trace 中匹配的 generation 只会安排一次运行。

如果数量较大，请将 rollout_percentage 设为低于 100 的值进行抽样。使用 llma-evaluation-test-hog（hog）检查评估器，或使用 llma-evaluation-run 对单个 generation 进行检查（llm_judge；对于没有可用密钥的 judge，请按 2.3 跳过单次运行检查）。对于数值型或类别型 Hog 评估，请向 llma-evaluation-test-hog 传入相同的 output_type 和 output_config，以确保预览会验证已保存评估能够接受的分数或类别键。 这两个工具目前都使用 generation 样本；对于 trace 目标，它们可以检查共享的来源或提示词行为，但不会复现完整且已稳定的 trace。提高 rollout 之前，请先检查首批实时 trace 结果。

注意： 有些组织会在 100k+ 个事件中重复使用同一个 $ai_trace_id。按 trace-ID 前缀限定范围可能匹配到远超预期的事件 — 启用前请使用上面的 SQL 验证数量。

2.6 — 启用已验证的评估集，然后闭环跟进

只有当所有获认可的评估都已成为范围验证过的草稿后，才启用它们 — 每个评估单独调用一次：

posthog:llma-evaluation-update
{ "evaluationId": "<uuid>", "enabled": true }

现在，每个评估都会在有新匹配 generation 时运行；若目标是 trace，则每个匹配的 trace 运行一次。这并非一次性工作：用户应知晓，他们需要持续关注结果，并在结果不符合预期时进行迭代。若要将结果接入 Slack 信息流，请参阅 feature-usage-feed。

对整个评估集一次性完成闭环 — 简短列出当前已上线的评估，并为每个评估附上链接，而不是逐个评估汇报过程。说明任何被你保留为禁用状态的候选项（没有可用的 provider 密钥、数量过大而暂不适合启用），以及解除阻碍所需的条件。

2.7 — 提议评估历史数据

启用评估后，只会对从现在起的流量进行评分。如果用户希望查看已有数据的结果，可以提议对最近一段时间（最多过去 30 天）的数据进行回填。posthog:llma-evaluation-backfill-create 不接受已禁用的评估，因此请先启用评估（参见 2.6）。

1. 使用用户指定的时间范围、conditions 和 rerun_existing 调用 posthog:llma-evaluation-backfill-estimate。告知用户 total_units、返回的时间范围（时间范围会被限制，因此可能与请求的范围不同），以及每个单元的成本：运行一次评估（计为一个 AI 可观测性事件），再加上 llm_judge 的一次模型调用。already_evaluated_units 已有结果，除非 rerun_existing 为 true，否则不会纳入。
2. 只有在用户同意后，才调用 posthog:llma-evaluation-backfill-create。传入估算结果返回的 window_start 和 window_end，而不是你请求的值，并使用相同的 conditions 和 rerun_existing，确保运行范围与用户批准的一致。
3. 使用 posthog:llma-evaluation-backfill-get 跟踪进度。跳过的单元此前已由评估本身进行评估，因此这些单元已覆盖，并非遗漏。任务完成后，如果 remaining_count 大于零，说明有些单元没有结果；可提议对相同范围再次回填。只提议一次。如果第二次运行后仍有单元未完成，则说明评估在这些单元上持续失败，应告知用户，不要再提议第三次回填。
4. 如果 posthog:llma-evaluation-backfill-create 表示无法确认任务已启动，请先调用 posthog:llma-evaluation-backfill-list 再尝试，因为回填可能正在运行。
5. 如需停止回填，请调用 posthog:llma-evaluation-backfill-cancel。已经启动的评估仍会完成。

每个评估一次只能运行一个回填任务。

使用 conditions 确定范围

conditions 是一个条件集列表——条件集之间为 OR 关系，同一条件集的 properties 内部为 AND 关系。每个条件集的格式为 { id, rollout_percentage, properties[] }。conditions 中没有时间范围；采样仅由 rollout_percentage（0–100）控制。属性筛选器使用标准 PostHog 格式（key、type、operator、value）。对于 trace 目标，这些筛选器仍会选择触发后续整条 trace 评估的 generation。

"conditions": [
  { "id": "openai",    "rollout_percentage": 100, "properties": [{"key": "$ai_provider", "type": "event", "operator": "exact", "value": "openai"}] },
  { "id": "anthropic", "rollout_percentage": 25,  "properties": [{"key": "$ai_provider", "type": "event", "operator": "exact", "value": "anthropic"}] }
]

构造 UI 链接

使用 posthog:generate-app-url 构造链接——绝不要手动填写主机或 /project/<id>/ 前缀。url 必须是规范的目录模板；通过 params 传入具体 ID，绝不要将其直接写入路径。

• 评估列表： generate-app-url {url: "/ai-evals/evaluations"}
• 单项评估： generate-app-url {url: "/ai-evals/evaluations/{id}", params: {id: "<evaluation_id>"}}

这些链接会解析到正确的区域主机和项目路径前缀（例如 https://us.posthog.com/project/<id>/ai-evals/evaluations/<evaluation_id>）。创建后展示链接，方便用户在 UI 中查看和切换评估。

提示

• 评估应源于真实故障，而非通用指标。 从此产品流量中发现的故障入手（通过 exploring-ai-failures），而不是想着“我们来衡量幻觉率”。没有追溯到真实不良输出的指标只是噪声。
• 一种故障模式对应一个评估，评估数量则应与数据相符。 不同的故障模式需要不同的评估；不要让一个评估试图捕捉所有问题，也不要默认只创建一个评估，而实际跟踪记录显示有多种值得关注的模式。例外情况是，相关模式可以由同一项检查区分开来：它们适合放在一个分类评估中。
• 先提出方案，再创建用户选定的评估。 用通俗语言展示候选方案，每个方案写一两行，然后等待用户选择。每项评估都写很长的说明，用户只会浏览，不会细读。
• 即使没有发现问题，也要给出方案。 如果已阅读跟踪记录，但没有发现值得评估的故障模式，就提出 sentiment 评估，而不是空手而归。例外情况是完全没有 $ai_generation 事件——没有事件可供评估触发，因此应引导用户使用 instrument-llm-analytics。
• 尽可能同时建议相应的更改。 例如，如果明确修改提示词就能解决问题，请设置评估，同时建议用户修改提示词：这样他们很快就能看到评估通过率从低变高。
• 优先使用 hog。 无需提供商密钥、无需 AI 审批且结果确定。只有在确实无法用代码编写评估标准时，才使用 llm_judge。
• 始终先创建为禁用状态，确认作用范围，再启用。 如果评估在错误的事件上触发，比不创建评估更糟——这会产生噪声，也会带来成本（对于 llm_judge）。
• 评审草稿只需要提供商和模型。 启用评审需要可用的提供商密钥，但保存草稿不需要，因此没有 ok 密钥时应保持禁用，而不是停止操作。provider_key_id 可以为 null，以使用团队当前启用的密钥。
• bytecode 由服务端为 hog 评估写入——绝不要传入它；只发送 evaluation_config.source。
• 对于集群范围的评估，使用 exploring-llm-clusters 确定集群，然后将其事件筛选条件转换为 conditions。

相关技能

• exploring-ai-failures——查找并确定值得评估的故障模式优先级——请先执行此操作
• exploring-llm-evaluations——调试和管理现有评估
• exploring-llm-clusters——确定集群，以限定针对集群的评估条件