exploring-llm-evaluations

探索 AI 可观测性评估

对于已存储的离线实验比较、评分器历史记录或外部计算结果上传，请使用 analyzing-offline-evaluations。离线实验使用固定的评分器配置，其结果 API 与下方的在线评估 API 相互独立。

PostHog 评估会为 $ai_generation 事件评分。每项评估分为以下三种类型之一：

• hog — 确定性的 Hog 代码，返回布尔值、数值分数或类别（也可以返回 N/A）。 最适合客观的规则检查：格式验证（JSON 可解析、符合架构）、长度限制、关键词是否存在、正则表达式模式、结构断言、延迟阈值、成本限制。成本低、速度快、结果可复现——每次运行都无需调用大模型。如果评估标准可用代码表达，优先使用此类型。
• llm_judge — 大模型根据你编写的提示词为生成内容评分。最适合主观或模糊的检查：语气、帮助程度、幻觉检测、偏离主题、是否遵循指令。每次运行都需要调用大模型，并且需要在组织级别批准 AI 数据处理。
• sentiment — 对每个匹配生成中的用户消息进行情感分类。返回情感标签和分数，而非通过／未通过判定。

所有类型的结果都会以 $ai_evaluation 事件的形式存入 ClickHouse。布尔评估（llm_judge 和 hog）会设置 $ai_evaluation_result；情感评估则会设置 $ai_sentiment_* 属性。 hog 和 llm_judge 也都支持 output_type: "numeric"。 数值运行会将原始分数存储在 $ai_evaluation_numeric_result 中，并可选择设置 $ai_evaluation_numeric_result_min 和 $ai_evaluation_numeric_result_max。 它们绝不会设置 $ai_evaluation_result。 使用 output_config.passing_rule 来解读分数：gte 表示大于或等于阈值，lte 表示小于或等于阈值。 更改规则会重新解读历史分数。已保存的报告会保留生成时使用的规则和指标。 如果没有通过规则，请检查分数均值和分布；通过率和报告将不可用。

启用项目的分类评估后，两种运行时也都支持 output_type: "categorical"。 读取 output_config.options 以获取已配置的 {key, label} 对，并读取 selection_mode 以确定是 single 还是 multiple。 结果会以列表形式将键存储在 $ai_evaluation_categorical_result 中；单选要求恰好有一个键，多选则允许 []。 在单选模式下，Hog 也可以返回单个键字符串。 使用 output_config.passing_rule.categories 为结果评级：只有当非空结果中的每个返回键都是通过类别时，该结果才通过。 非空规则会使 [] 判定为未通过；空规则只会使 [] 判定为通过，且仅允许用于多选模式。 如果没有规则，请检查类别频率，而非通过率；新报告将不可用。 编辑规则会重新分类历史结果，而已保存的报告会保留其规则快照。

此技能涵盖完整生命周期：列出／检查／管理评估配置、对指定生成运行评估、查询单个结果，以及配置定期汇总近期运行结果的评估报告。

工具

工具	用途
posthog:llma-evaluation-list	列出/搜索评估配置（按名称、启用标志筛选）
posthog:llma-evaluation-get	按 UUID 获取单个评估配置
posthog:llma-evaluation-create	创建新的 llm_judge、hog 或 sentiment 评估
posthog:llma-evaluation-update	更新现有评估（名称、提示词、启用状态等）
posthog:llma-evaluation-delete	软删除评估
posthog:llma-evaluation-run	针对特定的 $ai_generation 事件运行评估
posthog:llma-evaluation-test-hog	对近期生成内容试运行 Hog 源（不保存）
posthog:llma-evaluation-report-list	列出关联到某项评估的报告配置
posthog:llma-evaluation-report-create	为某项评估安排 AI 报告（通过邮件或 Slack）
posthog:llma-evaluation-report-run-list	过往报告运行记录，包括已发送的报告内容
posthog:execute-sql	对 $ai_evaluation 事件执行临时 HogQL
posthog:query-llm-trace	深入查看评估所评分的底层生成内容

所有 llma-evaluation-* 工具都定义在 products/ai_observability/mcp/tools.yaml 中。

事件架构

每次评估运行都会发出一个 $ai_evaluation 事件。关键属性如下：

属性	含义
$ai_evaluation_id	评估配置的 UUID
$ai_evaluation_name	易于理解的名称
$ai_target_event_id	被评分的 $ai_generation 事件的 UUID
$ai_trace_id	父级追踪 ID（用于跳转到追踪 UI）
$ai_evaluation_result_type	结果类型：boolean、numeric、categorical 或 sentiment
$ai_evaluation_numeric_result	原始数值分数。使用通过规则将其映射为通过或失败
$ai_evaluation_categorical_result	类别键列表。使用通过规则将其映射为通过或失败
$ai_evaluation_result	原始布尔结果。使用评估的输出配置将其映射为通过或失败
$ai_evaluation_reasoning	自由文本说明（由 LLM 评审器或 Hog 代码设置）
$ai_evaluation_applicable	当评估器判定生成结果为 N/A 时为 false
$ai_evaluation_skipped	当运行无法评估、因此未对结果评分时为 true
$ai_sentiment_label	用于情感评估：positive、neutral 或 negative
$ai_sentiment_score	获胜情感标签的置信度分数

首先检查 $ai_evaluation_skipped：跳过的运行不计入通过率，且与 N/A 不同。 否则，$ai_evaluation_applicable = false 表示 N/A，无论结果值为何。 对于不支持 N/A 的评估，此属性可能为 null——将 null 视为“适用”。 对于布尔评估，output_config.true_is_failure: false 会将 true 映射为通过，将 false 映射为失败。 对于检测器类型的评估，如果 true 表示评估器发现问题，请将其设为 true。

失败谓词

事件存储的是原始结果，而非通过或失败。PostHog 读取事件时，会应用评估当前的 output_type 和 output_config。根据 llma-evaluation-get 返回的配置构造 <fail predicate>，并在下方查询筛选失败项时使用：

评估	<fail predicate>
boolean，true_is_failure 为 false 或未设置	properties.$ai_evaluation_result = 'false'
boolean，true_is_failure: true（检测器）	properties.$ai_evaluation_result = 'true'
numeric，passing_rule 为 gte，阈值为 T	toFloat(properties.$ai_evaluation_numeric_result) < T
numeric，passing_rule 为 lte，阈值为 T	toFloat(properties.$ai_evaluation_numeric_result) > T
categorical，passing_rule.categories 为 [a,b]	NOT (notEmpty(<cats>) AND hasAll(['a', 'b'], <cats>))
categorical，passing_rule.categories 为 []	notEmpty(<cats>)
numeric 或 categorical，没有通过规则	None。直接读取分数或类别，不存在通过或失败

<cats> 为 JSONExtract(ifNull(properties.$ai_evaluation_categorical_result, '[]'), 'Array(String)')。 始终添加 (isNull(properties.$ai_evaluation_skipped) OR properties.$ai_evaluation_skipped != 'true')，因为跳过的运行仍可能存储 result = false。将这些属性与字符串 'true' 和 'false' 比较：未定义 Boolean 属性的项目会将其读取为字符串，因此与不带引号的 true 或 false 比较会失败。

工作流：调查评估失败的原因

llm_judge 和 hog 评估的操作方式相同——两者的差异只会在你最终修复评估器时体现（编辑提示词还是编辑 Hog 源码）。情感评估应根据情感标签和分数进行检查，而非使用通过/失败筛选条件。 下方查询使用上表中的评估 <fail predicate>。

步骤 1 — 查找评估

posthog:llma-evaluation-list
{ "search": "hallucination", "enabled": true }

查看返回的 id、name、evaluation_type，以及以下其中一项：

• llm_judge 的 evaluation_config.prompt
• hog 评估器的 evaluation_config.source

Hog 源码是判断 Hog 评估器为何通过或失败的依据——在假设问题出在生成结果之前，先阅读它。

步骤 2 — 汇总通过、失败和不适用的情况

posthog:execute-sql
SELECT
    countIf(properties.$ai_evaluation_applicable = 'false') AS na_count,
    countIf((isNull(properties.$ai_evaluation_applicable) OR properties.$ai_evaluation_applicable != 'false') AND NOT (<fail predicate>)) AS pass_count,
    countIf((isNull(properties.$ai_evaluation_applicable) OR properties.$ai_evaluation_applicable != 'false') AND (<fail predicate>)) AS fail_count
FROM events
WHERE event = '$ai_evaluation'
    AND properties.$ai_evaluation_id = '<evaluation_uuid>'
    AND (isNull(properties.$ai_evaluation_skipped) OR properties.$ai_evaluation_skipped != 'true')
    AND timestamp >= now() - INTERVAL 7 DAY

如果评估已有报告配置，llma-evaluation-report-list 和 llma-evaluation-report-run-list 会提供之前周期的 AI 生成报告，这是了解情况变化的快捷方式。

步骤 3 — 查看失败的运行

问题模式会体现在推理文本中。提取近期失败项并阅读：

posthog:execute-sql
SELECT
    properties.$ai_target_event_id AS generation_id,
    properties.$ai_trace_id AS trace_id,
    properties.$ai_evaluation_reasoning AS reasoning,
    timestamp
FROM events
WHERE event = '$ai_evaluation'
    AND properties.$ai_evaluation_id = '<evaluation_uuid>'
    AND (<fail predicate>)
    AND (isNull(properties.$ai_evaluation_applicable) OR properties.$ai_evaluation_applicable != 'false')
    AND (isNull(properties.$ai_evaluation_skipped) OR properties.$ai_evaluation_skipped != 'true')
    AND timestamp >= now() - INTERVAL 7 DAY
ORDER BY timestamp DESC
LIMIT 25

N/A 防护条件（IS NULL OR != false）很重要——它与后端对运行进行分类时使用的逻辑一致。

步骤 4 — 深入查看失败运行示例

从步骤 3 中选取最具代表性的行，并提取其底层跟踪记录：

posthog:query-llm-trace
{ "traceId": "<trace_id>", "dateRange": {"date_from": "-30d"} }

（如果只有生成 ID，请先通过 execute-sql 查询，找到父跟踪 ID。）

工作流：针对特定生成结果运行评估

当用户粘贴跟踪记录/生成结果 URL，并询问“评估 X 会如何评价这个结果？”时使用此流程。

posthog:llma-evaluation-run
{
  "evaluationId": "<eval_uuid>",
  "target_event_id": "<generation_event_uuid>",
  "timestamp": "2026-04-01T19:39:20Z",
  "event": "$ai_generation"
}

timestamp 是高效查询目标事件所必需的。如果有 distinct_id，请一并传入——这样可以进一步加快查询。

工作流：构建并测试新的评估器

Hog 评估器（确定性，基于代码）

如果评估标准是基于规则的，优先使用它——成本更低、速度更快，而且结果可复现。使用 llma-evaluation-test-hog 进行原型测试（不保存）：

posthog:llma-evaluation-test-hog
{
  "source": "return event.properties.$ai_output_choices[1].content contains 'sorry';",
  "sample_count": 5,
  "allows_na": false
}

处理程序会针对抽样单元返回原始布尔值、数值或类别结果。对于数值或类别预览，请传入已保存的 output_type 和 output_config；如果允许 null，还要包含 allows_na: true。不断迭代源代码，直到行为符合预期，然后通过 llma-evaluation-create 将其正式启用：

posthog:llma-evaluation-create
{
  "name": "Output is valid JSON",
  "description": "Fails when the assistant message can't be parsed as JSON",
  "evaluation_type": "hog",
  "evaluation_config": {
    "source": "let raw := event.properties.$ai_output_choices[1].content; try { jsonParseStr(raw); return true; } catch { return false; }"
  },
  "output_type": "boolean",
  "enabled": true
}

Hog 评估器可以完全访问事件及其属性——常见模式包括架构验证、长度／令牌限制、正则表达式匹配，以及工具调用格式检查。由于它们具有确定性，因此重复运行的结果可复现，也很容易进行差异比较。

LLM 评审评估器（主观，基于提示词）

如果评估标准较为模糊，而代码规则会显得僵化（例如语气、事实准确性、有用性、切题程度），请使用此评估器。LLM 评审没有与 llma-evaluation-test-hog 等效的测试工具——典型流程是使用 enabled: false 创建评估器，通过 llma-evaluation-run 手动评估一些有代表性的生成结果，检查结果，使用 llma-evaluation-update 优化提示词，然后在满意时将 enabled: true：

posthog:llma-evaluation-create
{
  "name": "Response stays on-topic",
  "description": "LLM judge — fails if the assistant changes topic from the user's question",
  "evaluation_type": "llm_judge",
  "evaluation_config": {
    "prompt": "You are evaluating whether the assistant's reply stays on-topic relative to the user's most recent question. Return true if it does, false if the assistant changed the subject. Return N/A if the user did not actually ask a question."
  },
  "output_type": "boolean",
  "output_config": { "allows_na": true },
  "model_configuration": {
    "provider": "openai",
    "model": "gpt-5-mini"
  },
  "enabled": false
}

接着，对一个已知良好和一个已知不良的生成结果进行试运行：

posthog:llma-evaluation-run
{
  "evaluationId": "<new_eval_uuid>",
  "target_event_id": "<generation_uuid>",
  "timestamp": "2026-04-01T19:39:20Z"
}

LLM 评审需要获得组织的 AI 数据处理审批。Hog 评估器则不需要。

工作流：管理评估生命周期

操作	工具
添加 Hog 评估器	使用 evaluation_type: "hog" 和 evaluation_config.source 调用 llma-evaluation-create
添加 LLM 评审评估器	使用 evaluation_type: "llm_judge"、evaluation_config.prompt 和 model_configuration 调用 llma-evaluation-create
调整源代码或提示词	使用 llma-evaluation-update（Hog 修改 evaluation_config.source，LLM 评审修改 evaluation_config.prompt）
切换 N/A 处理方式	使用 output_config.allows_na 调用 llma-evaluation-update
设置失败极性	使用 output_config.true_is_failure 调用 llma-evaluation-update
暂时停用	使用 enabled: false 调用 llma-evaluation-update
移除	llma-evaluation-delete（通过 PATCH {deleted: true} 软删除）

llm_judge 评估需要获得组织级别的 AI 数据处理审批 （is_ai_data_processing_approved）。Hog 评估不需要此门槛 ——它们以普通代码的形式在摄取流水线上运行。

何时使用 Hog，何时使用 LLM judge

默认优先选择 Hog。只有在无法用代码表达评估标准时，才切换到 LLM judge。

使用 Hog 的情况……	使用 LLM judge 的情况……
检查结构（JSON 能否解析、是否匹配架构）	检查含义（是否切题、有帮助、真实）
需要确定、可复现的结果	可以接受少量判断差异
评估标准的计算成本低	评估标准需要阅读和理解文本
无法获得 AI 数据处理批准	已获得批准，且评估标准确实模糊
需要强制执行硬性限制（长度、成本等）	需要评估某个质量维度
希望在亚毫秒级完成评估	可以接受数百毫秒的耗时和 LLM 成本

常见做法是分层使用：先用 Hog 评估器廉价地拦截明显的格式／长度违规，再通过 conditions 让 LLM judge 评估器只处理通过 Hog 筛选的生成结果。

调查模式

无论评估器是 hog 还是 llm_judge，诊断方式都相同——查看生成的 $ai_evaluation 事件，而不是评估器本身。修复方式有所不同（修改 Hog 源码或修改提示词），但诊断过程完全一致。

“为什么评估 X 突然有更多失败？”

1. llma-evaluation-list — 确认评估仍处于启用状态且配置未变（将 evaluation_config.source 或 evaluation_config.prompt 与预期版本比较）

2. 阅读近期失败运行及其推理过程（见上文第 3 步），并按主要失败模式对它们分组

3. 按天统计失败次数，以确认回归发生的时间范围：

   SELECT toDate(timestamp) AS day, count() AS fails
   FROM events
   WHERE event = '$ai_evaluation'
       AND properties.$ai_evaluation_id = '<uuid>'
       AND (<fail predicate>)
       AND (isNull(properties.$ai_evaluation_applicable) OR properties.$ai_evaluation_applicable != 'false')
       AND (isNull(properties.$ai_evaluation_skipped) OR properties.$ai_evaluation_skipped != 'true')
       AND timestamp >= now() - INTERVAL 30 DAY
   GROUP BY day
   ORDER BY day
   

4. 通过 query-llm-trace 深入查看每种模式下一个有代表性的追踪记录

“通过和失败是否由相同的根本内容导致？”

1. 使用第 3 步中的查询提取两个样本：一次使用 <fail predicate>，一次使用 NOT (<fail predicate>)
2. 如果通过和失败的运行描述了相似内容：
   • 对于 llm_judge：提示词或评分标准可能有歧义——重新措辞 evaluation_config.prompt，然后使用 llma-evaluation-update
   • 对于 hog 评估器：规则可能匹配不足或过度匹配——通过 llma-evaluation-get 查看源码，缩小谓词范围，并在通过 llma-evaluation-update 推送修复前，使用 llma-evaluation-test-hog 重新测试

“Hog 评估器是否在代码更改后发生了回归？”

Hog 评估器具有可复现性——如果源码未变，相同的输入应产生相同的输出。当 Hog 评估器的失败率突然上升时：

1. llma-evaluation-get — 记录当前源码和 updated_at
2. 使用上文第 4 步中的 SQL 查询抽查最新的失败运行
3. 使用 llma-evaluation-test-hog 对这些完全相同的生成结果重新运行源码，并修改 conditions 筛选条件以定位它们
4. 如果测试结果与线上结果一致，变化来自_生成结果_，而非评估器（例如模型升级、上游提示词变更等）——请调查生成方
5. 如果结果不一致，则说明评估器曾被修改；通过活动日志检查源码字段的 Git 历史记录

“此评估器会将哪些类型的生成结果跳过并标记为 N/A？”

posthog:execute-sql
SELECT
    properties.$ai_target_event_id AS generation_id,
    properties.$ai_trace_id AS trace_id,
    properties.$ai_evaluation_reasoning AS reasoning,
    timestamp
FROM events
WHERE event = '$ai_evaluation'
    AND properties.$ai_evaluation_id = '<evaluation_uuid>'
    AND properties.$ai_evaluation_applicable = 'false'
    AND timestamp >= now() - INTERVAL 7 DAY
ORDER BY timestamp DESC
LIMIT 25

阅读这些运行的推理过程，确认 N/A 逻辑是否合理。如果某次运行看起来本应获得评分：

• 对于 llm_judge：提示词中的适用性指令范围过宽——请缩小范围
• 对于 output_config.allows_na: true 的 hog 评估器：源码过于轻易地返回 null（或其他 N/A 信号）——请收紧前置条件

“立即对此次单次生成进行评分”

使用轨迹的生成 ID 和时间戳运行 llma-evaluation-run。适用于抽查，或将评估接入更大的 Agent 循环。

构建 UI 链接

• 评估列表：https://app.posthog.com/ai-evals/evaluations
• 单项评估：https://app.posthog.com/ai-evals/evaluations/<evaluation_id>
• 底层生成/轨迹：参见 exploring-llm-traces 技能中的 URL 约定

始终提供相关链接，方便用户在 UI 中核验。

提示

• 使用 llma-evaluation-report-create 为每项评估配置评估报告： frequency: "scheduled" 配合 rrule，按日或按周定期运行；或者使用 frequency: "every_n" 配合 trigger_threshold，在累积到指定数量的新结果后触发。 报告通过 delivery_targets 发送到电子邮件或 Slack
• llma-evaluation-report-generate 会立即运行已配置的报告，而不是等待下次触发； llma-evaluation-report-run-list 会返回以往的运行记录及其发送的报告内容
• 对于 llma-evaluation-list 不支持的高级筛选（例如按作者或模型 配置筛选），可回退到针对 evaluations Postgres 表或 $ai_evaluation ClickHouse 事件执行 execute-sql
• 向用户展示失败模式时，务必包含 1-2 个示例轨迹链接，方便用户直观核验该模式
• llma-evaluation-* 工具中，读取工具使用 evaluation:read，变更工具使用 evaluation:write，但 llma-evaluation-config-get 和 llma-evaluation-judge-models 除外，它们使用 llm_analytics:read
• Hog 评估器具有可复现性——如果怀疑出现回归，针对失败的生成结果使用可疑源运行 llma-evaluation-test-hog，这是最快判断变更是在评估器还是生成结果的生产端 的方法
• LLM 裁判评估器在重复运行时具有非确定性；即使提示词和模型固定，也要预期存在 1-5% 的噪声。如果要排查失败率的小幅回归，优先使用 Hog，或在 model_configuration 中指定确定性的提供方/种子

相关技能

• creating-online-evaluations — 从头编写新的评估
• exploring-ai-failures — 根据观察到的失败模式确定下一项评估的依据