omni-ai-eval

Omni AI 评估

Omni 提供一套一流的评估系统（AI Hub → 提示词集和评估运行）。此技能通过 Omni CLI 驱动该系统：定义可复用的提示词集，针对模型或分支启动经评审的评估运行，并从 Omni 内置的准确性评审器读取每条提示词的判定结果。

优先使用这套原生系统，而不是自行构建测试框架。评审器会根据完整的 Agent 对话，对每个答案进行语义评分——不需要黄金查询 JSON，而且评估的是整个 Agent 工作流（主题选择、查询、结果和最终书面答案），而不仅是生成的查询结构。

提示：发现问题后，使用 omni-ai-optimizer 提高分数；在进行 A/B 测试前，使用 omni-model-builder 在分支上应用上下文变更；编写提示词时，使用 omni-model-explorer 探索主题和字段。

前提条件

# Verify the Omni CLI is installed — if not, ask the user to install it.
# See: https://github.com/exploreomni/cli#readme
command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."

# Verify the CLI has the eval commands. If this errors with "unknown command",
# the binary is stale — ask the user to update it (the ai-eval group is generated
# from the bundled API spec).
omni ai-eval --help >/dev/null 2>&1 || echo "ERROR: 'omni ai-eval' missing — update the Omni CLI."

# Show available profiles and select the right one — running against the wrong
# instance silently evaluates the wrong model.
omni config show
# If multiple profiles exist, ask the user which to use:
omni config use <profile-name>

# Confirm the active profile is authenticated and inspect your permissions:
omni whoami whoami

身份验证：配置文件通过 API 密钥或 OAuth 进行身份验证。如果 whoami（或任何调用）返回 401，请交由用户处理——让用户运行 ! omni config login <profile>（OAuth 2.1 浏览器流程；会在浏览器中阻塞约 2 分钟）。不要在无头/CI 会话中自行运行 config login（没有浏览器会导致超时）；在本地交互式计算机上则可以运行。有关配置文件设置（omni config init --auth oauth），以及如何使用 --schema 查看命令和请求体结构，请参阅omni-api-conventions规则。

你还需要要评估的共享模型的模型 ID。评估要求对此模型至少拥有Querier权限，并且至少有一个针对 AI 优化的主题。有关概念和提示词集最佳实践，请参阅评估指南。

工作原理

概念	说明
提示词集	可复用的命名列表，包含最多 25 条自然语言提示词，范围限定为一个模型。每条提示词都可以带有可选的 expectation——评审器据此对照评分的参考答案。数据保存在服务端；可针对每个主题、每个版本或回归测试创建一个提示词集。
评估运行	针对模型分支（或 main）执行提示词集。每条提示词都会作为完整的异步 Agent 式 AI 任务运行（与生产环境 Blobby 使用相同引擎），随后由准确性评审器对结果评分。
准确性评审器	固定的评审模型，会读取被评估 AI 的完整对话，并为每条提示词返回通过/失败判定，以及置信度和理由。它针对影响较大的分析错误（幻觉、日期/时间筛选、行数限制处理、心算、期间对比错误、主题错误）。它不会评价措辞或格式。

所有命令都支持 -o json（或 --compact）以强制输出结构化数据，便于解析；也支持 --profile <name> / --branch-id 形式的全局标志。运行 omni ai-eval <command> --help 查看完整标志列表。运行任何命令时加上 --schema，即可打印其参数、标志、请求体架构（含填好的示例）和响应结构，无需猜测。

步骤 1 — 创建提示词集

omni ai-eval prompt-sets-create --compact --body '{
  "model_id": "your-model-id",
  "name": "Orders regression",
  "slug": "orders-regression",
  "description": "Core revenue + orders coverage",
  "prompts": [
    { "prompt_text": "Show me revenue by month" },
    { "prompt_text": "What are the top 5 products by revenue?",
      "expectation": "The top product by revenue should be Aniseed Syrup." },
    { "prompt_text": "How many orders were placed last week?" }
  ]
}'

响应中包含新建的 prompt_set.id（UUID）——请记下此 ID，以供运行时使用。

字段	必填	说明
model_id	是	此提示词集绑定到的共享模型 UUID
name	是	≤ 255 个字符
slug	是	在每个 model_id 下唯一；必须匹配 ^[a-z][a-z0-9-]*$
description	否	≤ 1024 个字符
prompts[]	否	≤ 25；每项需要 prompt_text（≤ 8000 个字符），可选 expectation（≤ 16000 个字符）

查找或更新现有提示词集，而不是重新创建：

omni ai-eval prompt-sets-list --model-ids your-model-id --compact   # discover sets + ids
omni ai-eval prompt-sets-get <promptSetId> --compact                # full set with prompts

prompt-sets-update 会替换整个 prompts 列表：未提供的提示词会被删除；没有 id 的条目会被创建；id 匹配的条目会原地更新。若要添加一条提示词，请发送完整的目标列表（现有提示词需保留其 id）。

omni ai-eval prompt-sets-update <promptSetId> --compact --body '{
  "prompts": [
    { "id": "<existing-prompt-id>", "prompt_text": "Show me revenue by month" },
    { "prompt_text": "Revenue by month, last 12 months only" }
  ]
}'

编写优质提示词和设定预期

• 反映真实用户的问题 — 从 AI 使用分析仪表板中获取问题，而不是编造模仿字段名称的说法。
• 广而不深 — 一个涵盖多个主题的提示词，比十个集中在一个主题的提示词能提供更多信号。
• 每当答案出错时添加回归提示词，以便下次捕获同样的问题。
• 仅在提示词有值得固定的已知答案时设置 expectation：一个值或排名（“排名第一的产品应为 Aniseed Syrup”）、一个方向（“收入应同比增长”）或必需的细分结果。评判器会将实质性偏差（数字错误、方向错误、缺少必需结果）视为失败，但会忽略措辞或格式差异。未设置预期时，评判器会根据答案本身判断其是否正确。预期仅向评判器显示，受评估的 AI 不会看到。

第 2 步 — 运行评估

# Against main:
omni ai-eval runs-create --compact --body '{
  "prompt_set_id": "<promptSetId>",
  "description": "Baseline on main"
}'

# Against a branch (measures a model-context change before promotion):
omni ai-eval runs-create --compact --body '{
  "prompt_set_id": "<promptSetId>",
  "description": "After adding ai_context to order_items",
  "run_config": { "branch_id": "<branchId>" }
}'

响应会返回 run.id 和 job_count（每个提示词对应一个 Agentic 作业）。省略 run_config.branch_id，即可针对实时共享模型运行。

并发上限：同时最多只能有 2 个评估运行处于进行中。429 表示已达到每用户活跃运行上限 — 等待正在进行的运行结束，或取消其中一个。503 表示该组织已暂停评估。启动前请检查 runs-list。

轮询直至完成

omni ai-eval runs-get <runId> --compact

采用递增间隔轮询（例如 5s、10s、20s），直到运行的 status 进入终态 — COMPLETE 或 CANCELLED。通过每个结果的 agentic_job.state 跟踪进度（QUEUED → EXECUTING → COMPLETE/FAILED）。不要频繁请求端点。

第 3 步 — 查看结果

runs-get 会返回 results[]，每个提示词对应一行：

{
  "run": {
    "status": "COMPLETE",
    "branch_id": null,
    "results": [
      {
        "prompt": "What are the top 5 products by revenue?",
        "score": 1,
        "error_reason": null,
        "cost": 0.0021,
        "scoring_cost": 0.0004,
        "timing_ms": 4321,
        "agentic_job": { "state": "COMPLETE", "conversation_id": "conv-uuid", "id": "job-uuid" }
      }
    ]
  }
}

字段	含义
score	该提示词的评判结果 — 通过 = 1，失败 = 0
error_reason	底层 Agentic 作业失败时设置
cost / scoring_cost	回答和评判所需的大模型费用（美元）
timing_ms	总 AI 耗时，单位为 ms — 所有大模型处理和工具调用的耗时（与 UI 中的“AI 时间”列一致），不是墙钟时长
agentic_job.conversation_id	回答对应的对话 — 查看该对话以了解评判器的完整判定、置信度和理由

总体准确率 = 通过率（所有结果中 score 的平均值）。报告该数据时，同时列出每个提示词的细分结果；对于任何失败，请提供 conversation_id，以便用户查看评判器判定失败的原因 — 其中的理由包含可采取行动的关键信息。

Eval run "Baseline on main" — 9/12 passed (75.0%)
  ✗ "Revenue by quarter"        — judge: summed a row-limited result as a total
  ✗ "Top products this year"    — judge: date filter used calendar instead of fiscal year
  ✗ "Churn rate by segment"     — agentic job FAILED (error_reason)
  (omni ai conversation-detail <conversation_id> for the full rationale)

请通过 CLI 阅读该对话记录，而不是让用户前往 UI：

omni ai conversation-detail <conversationId> --compact

• 助手文本会保留 30 天，较早的对话仍会返回 200 — 但只包含用户轮次。需要引用的理由应在运行结束后尽快总结，不要等到之后再重新阅读。
• 评估对话不会出现在 omni ai conversations-list 中，因此只能从 runs-get 获取 ID；用户范围的令牌只能读取其创建的运行（组织 API 密钥则可读取其他用户的运行）。

A/B 对比：分支与 main

衡量模型变更是否有帮助的核心工作流。使用同一组提示词运行两次——一次在 main 上，一次在分支上——然后进行比较。

1. 创建或确定包含变更的分支（使用 omni-model-builder 在分支上应用 ai_context、字段、联接、ai_settings 等）。
2. 不带 run_config 执行 runs-create → 在 main 上运行基线。
3. 使用 run_config.branch_id 执行 runs-create → 运行分支版本。
4. 轮询两次运行，直到状态为 COMPLETE，然后按提示词对比判定结果。

A/B: main vs branch/new-context  (prompt set: orders-regression)
                    main      branch     Δ
Accuracy:           75.0%     91.7%     +16.7%
Prompt credits:     0.024     0.026     +0.002

Regressions (passed on main, failed on branch):
  - rev-by-quarter
Improvements (failed on main, passed on branch):
  - top-products-this-year
  - churn-rate-by-segment

务必检查是否有回归，而不只是整体提升。 即使总体通过率更高，也可能掩盖某条新近失效的提示词——有助于大多数提示词的 ai_context 变更也可能与其中一条冲突。请指出任何在 main 上通过、但在分支上失败的提示词。

确保比较可审计的注意事项：

• 两次运行必须使用同一组提示词，以便评估相同的提示词（AI Hub 比较视图也会强制执行这一点）。
• 记录所用的完整 branch_id，并确认分支运行的 run.branch_id 与之匹配——否则不要声称已测试该分支。
• 每次运行都会保存提示词预期的快照，因此之后编辑提示词的 expectation 不会改变早前运行的评分方式。

管理提示词集和运行

omni ai-eval runs-list --prompt-set-id <promptSetId> --compact   # runs for a set, newest first
omni ai-eval runs-cancel <runId>                                 # cancel an in-flight run (also archives it)
omni ai-eval runs-archive <runId>                                # archive a finished run
omni ai-eval runs-unarchive <runId>                              # restore an archived run

omni ai-eval prompt-sets-archive <promptSetId>                   # archive a set (cancels its in-flight jobs)
omni ai-eval prompt-sets-unarchive <promptSetId>                 # restore an archived set

归档属于软删除——提示词集和运行会予以保留，并且可以恢复。取消运行会将其标记为 CANCELLED 并归档；使用 runs-unarchive 可让它再次显示在默认列表中。使用 *-list 命令时添加 --archived true，即可查看已归档项目。

注意事项

• 配置文件和实例都要正确——评估会使用当前配置文件所对应实例上的模型。创建提示词集或运行前，请确认配置文件。
• 评审结果为二元且固定——通过表示答案避免了高影响分析错误，并不意味着它是唯一或最佳答案。无法按运行配置评审模型。
• 作业失败 ≠ 评审失败——设置了 error_reason 的结果表示 Agent 作业本身失败（未生成可供评分的答案）；请将其与评审 score 为 0 区分开来。
• 保存快照——为确保运行可复现，请将模型状态与结果一并保存：omni models yaml-get <modelId> --compact 和 omni models validate <modelId>。分支运行已将变更固定在分支上。

文档参考

• 评估（概念 + 评审） · AI 评估 API · 创建 AI 作业 API · 针对 AI 优化模型

相关技能

• omni-ai-optimizer — 根据评估结果提升 AI 准确性（ai_context、sample_queries、字段元数据）
• omni-model-builder — 在 A/B 测试前于分支上应用上下文变更
• omni-model-explorer — 编写提示词时发现主题和字段