omni-ai-eval

Omni AI Eval

Omni には、主要機能として評価システム（AI Hub → Prompt sets と Eval runs）が搭載されています。このスキルでは Omni CLI を通じて、再利用可能な プロンプトセットを定義し、モデルまたはブランチに対する判定付きの 評価実行を開始して、Omni に組み込まれた 精度判定器からプロンプトごとの判定結果を読み取ります。

独自のハーネスを構築するより、このネイティブシステムを優先してください。判定器は、エージェントとの会話全体に照らして各回答を意味的に採点します。正解となるクエリの JSON は不要で、生成されたクエリの構造だけでなく、エージェント型ワークフロー全体（トピックの選択、クエリ、結果、最終的な文章の回答）を評価します。

ヒント: 失敗を見つけた後にスコアを改善するには 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 key または OAuth を使用します。whoami（または任意の呼び出し）が 401 を返す場合は、ユーザーに引き継いでください。ユーザーに ! omni config login <profile> の実行を依頼します（OAuth 2.1 のブラウザーフロー。ブラウザー上で約 2 分間処理がブロックされます）。ヘッドレス／CI セッションでは、自分で config login を実行しないでください（ブラウザーがないためタイムアウトします）。ローカルの対話型マシンでは実行してもかまいません。プロファイルの設定（omni config init --auth oauth）や、--schema を使ってコマンドとリクエスト本文の形式を確認する方法については、omni-api-conventions ルールを参照してください。

評価する共有モデルの model ID も必要です。評価には、そのモデルに対する少なくとも Querier のアクセス権と、AI 向けに最適化されたトピックが少なくとも 1 つ必要です。概念とプロンプトセットのベストプラクティスについては、評価ガイドを参照してください。

仕組み

概念	内容
プロンプトセット	自然言語のプロンプトを最大 25 件まで登録できる、再利用可能な名前付きリストです。1 つのモデルが対象です。各プロンプトには、判定器が採点する参照回答として、任意の expectation を設定できます。サーバー側に保存されます。トピックごと、リリースごと、またはリグレッションの確認用に作成してください。
評価実行	プロンプトセットをモデルのブランチ（または main）に対して実行します。各プロンプトは、エージェント型 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）が含まれます。評価実行のために保存してください。

フィールド	必須	備考
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 を持つ項目はその場で更新されます。プロンプトを 1 件追加するには、希望するリスト全体を送信してください（既存のプロンプトには 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 利用分析ダッシュボードから質問を選びます。
• 深さより幅を重視する — 1 つのトピックに関する 10 個のプロンプトより、多くのトピックを扱う 1 つのプロンプトのほうが、多くの情報を得られます。
• 回答が誤っていた場合は、回帰テスト用のプロンプトを追加する — 次回も同じ失敗を検出できるようにします。
• 固定する価値のある既知の答えがある場合に限り、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（プロンプトごとに 1 つのエージェントジョブ）が返されます。共有の本番モデルに対して実行するには、run_config.branch_id を省略します。

同時実行数の上限：一度に実行できる評価は最大 2 件です。429 はユーザーごとのアクティブな実行数の上限に達したことを意味します。実行中の評価が完了するまで待つか、いずれかをキャンセルしてください。503 は組織で評価が一時停止されていることを意味します。実行を開始する前に runs-list を確認してください。

完了をポーリングする

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

バックオフ（例：5 秒、10 秒、20 秒）を適用して、実行の status が終端状態の COMPLETE または CANCELLED になるまでポーリングします。各結果の agentic_job.state（QUEUED → EXECUTING → COMPLETE／FAILED）で進捗を追跡します。エンドポイントに過剰なリクエストを送らないでください。

ステップ 3 — 結果を確認する

runs-get は、プロンプトごとに 1 行の 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	基になるエージェントジョブが失敗した場合に設定されます
cost / scoring_cost	回答の LLM コスト（USD）と、その評価にかかった LLM コスト（USD）
timing_ms	合計 AI 時間（ミリ秒） — すべての LLM 処理とツール呼び出しにかかった時間です（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)

ユーザーを UI に誘導するのではなく、CLI からその会話の記録を読み取ります。

omni ai conversation-detail <conversationId> --compact

• アシスタントのテキストは 30 日間保持されます。30 日を過ぎた会話でも 200 が返されますが、ユーザーの発言のみが含まれます。引用が必要になる可能性のある根拠は、後で読み返すのではなく、実行直後に要約しておきます。
• 評価の会話は omni ai conversations-list には表示されません。そのため、ID は runs-get からのみ取得できます。また、ユーザーに紐づくトークンで読み取れるのは、そのユーザーが作成した実行のみです（組織 API キーでは別のユーザーの実行も読み取れます）。

A/B 比較：ブランチと main

モデルの変更によって改善するかどうかを測定するための基本的なワークフローです。同じプロンプトセットを 2 回実行します。1 回は main で、もう 1 回はブランチで実行し、その結果を比較します。

1. 変更を含むブランチを作成するか、特定します（omni-model-builder を使用して、ブランチ上で ai_context、フィールド、結合、ai_settings などを適用します）。
2. runs-create を run_config なしで実行 → main でベースライン実行します。
3. runs-create を run_config.branch_id 付きで実行 → ブランチで実行します。
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 が設定された結果は、エージェント型ジョブ自体が失敗したことを意味します（採点対象となる回答が生成されませんでした）。これは、判定の 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 — プロンプト作成時にトピックやフィールドを見つけます