ダッシュボード

PXChat Evals

enja

ヘルプ

Eval ハーネスガイド

ケース作成、ラン実行、レビュー、比較のためのチーム向けドキュメントです。

Eval ハーネスガイド

このハーネスは、eval ケースの作成、再現可能な実験の実行、失敗レビュー、改善の時系列比較を行うためのチーム用ワークスペースです。

CLI エントリポイント、マイグレーション、seed、ローカル DB ファイルのフォルダ単位の地図は evals/README.md を参照してください。

ブラウザ UI は apps/evals にあり、通常は http://localhost:3000/evals で起動します。独立したチャットフロントエンドは apps/chat にあり、ローカルの /api/chat プロキシは PXCHAT_EVALS_BASE_URL で指定した evals ランタイムへ転送します。PXCHAT_AGENT_SETUP_ID を指定すると、そのフロントエンドインスタンスで使う登録済みエージェント設定を固定できます。本番環境では、この固定を認証するため chat と evals の両プロセスに同じ PXCHAT_PROXY_SECRET を設定します。ブラウザから渡された設定/モデル上書きは削除され、認証されていない evals API の上書きも拒否されます。信頼済みローカルインスタンスでのみ PXCHAT_ALLOW_RUNTIME_OVERRIDES=1 を明示できます。

目的

  • この eval UI で新しい eval ケースを直接作成する。
  • スモーク、回帰、重要ケース、シナリオラン用に、ケースを再利用可能なプリセットへ整理する。
  • 環境が実際に準備できているときだけランを開始する。
  • 手動確認が必要なケースだけをレビューする。
  • 新しいランを前回ランまたは固定した基準ランと比較する。

用語集

  • Case
    • 1つの eval 項目です。通常は1つの質問またはプロンプト、期待値、その周辺メタデータを含みます。
  • Scenario
    • 関連する複数ケースで構成される複数ターンの会話です。シナリオキーが各ターンを順序付きでまとめます。
  • Source
    • スプレッドシート行、QA成果物、インポート識別子など、ケースの外部由来です。追跡用であり、ラン可否は決めません。
  • workflowStatus
    • チームが直接管理するハーネス上の状態です。
    • draft は作成中を意味します。
    • active は実行可能を意味します。
    • disabled は参照用として保持し、ランから除外することを意味します。
  • sourceStatus
    • 元のインポートワークフローまたはスプレッドシートから保持された状態です。QA 文脈として表示されますが、ハーネスがケースを実行するかどうかは決めません。
  • Preset
    • 保存済みのランパックです。ケースリストまたはフィルターセットと、デフォルトのラン設定を保存します。
  • Baseline
    • チームが比較の基準点として使う固定ランです。

主な画面

eval エリアには共通シェルがあります。上部ナビゲーションには 概要、ケース、ラン作成、プリセット、ラン、設定、ヘルプ があり、設定済みチャットフロントエンドへ戻るリンクと概要のプリセット開始へ戻るリンクもあります。設定 メニューには 基準、エージェント、シグナル、データソース、モデル をまとめています。

  • /evals
    • 概要ダッシュボード。
    • 準備状況、最新ラン概要、スイートカバレッジ、保存済みプリセットランのクイック開始を表示します。
  • /evals/runs
    • ラン一覧。
    • 検索、スイート、状態にはクイックフィルターを使います。モード、言語、採点、日付範囲、件数上限は詳細フィルターで開きます。
  • /evals/suites/[suiteSlug]/cases
    • ケース表示とシナリオ作成。
    • ケースの閲覧、絞り込み、複製、作成に使います。
  • /evals/suites/[suiteSlug]/cases/new
    • 新規ケースフォーム。
    • ファイルをインポートせずにテストを追加したいときに使います。
  • /evals/suites/[suiteSlug]/runs/new
    • ラン作成。
    • フィルターまたは明示ケース、準備状況の検証、エージェント/モデルバリアント、実行設定からカスタムランを組み立てて開始します。
  • /evals/presets
    • プリセット管理。
    • スイートのプリセットの表示、作成、更新、削除、および定期スケジュールの紐付けに使います。
  • /evals/criteria
    • 判定基準管理。
    • 5つの採点軸、定義、例、基準セットの作成/複製、そして新規ラン用デフォルトの選択に使います。
  • /evals/agents
    • エージェント設定管理。
    • バージョン付きのエージェント設定、トップレベル Pi エージェントのプロンプトとフラットなツールレジストリの調整、設定ごとのシグナル選択、インスタンスのシグナル表の展開、evals ランタイム /api/chat が使うデフォルト設定の選択に使います。
  • /evals/signals
    • バックエンドインスタンス単位のシグナル管理。
    • この eval バックエンドのエージェント設定で利用可能な許可済みシグナルの作成、説明編集、無効化に使います。
  • /evals/data-sources
    • Mirage データソース管理。
    • アクティブな /sources ツリーの閲覧とプレビュー、アップロード先フォルダーの選択、LLM wiki ZIP の新しい不変リビジョンとしてのアトミックなインポートに使います。
  • /internals/models
    • モデルプロファイルとデフォルトモデル設定。
    • eval シェルの 設定 メニューでは モデル としてリンクされています。
  • /evals/runs/[runId]
    • ライブラン画面。
    • キュー済み/実行中の状態、例外レビューキュー、比較、詳細診断を表示します。
  • /evals/help
    • このガイドを eval シェル内で表示します。

エージェントランタイムとツール

evals ランタイムは、公開チャットとヘッドレス eval の両方で1つのトップレベル Pi エージェントを使います。エージェント設定には1つのシステムプロンプトと1つのフラットな tools レジストリがあり、独立した AI SDK メインエージェント層やネストされた Pi ツール設定はありません。

各ツールは個別に有効化できます。

  • ragSearch は、Postgres に保存された埋め込み済みナレッジベースを検索します。
  • pricingTable2024 は、2024/2025年度の電力料金表を検索します。
  • signal は、このバックエンドインスタンスのレジストリに登録された許可済みフロントエンドシグナルを送ります。各設定では、ツールと送信を許可する個別シグナルの両方を有効にする必要があります。
  • read、grep、find、ls、bash は、読み取り専用の Mirage /sources ファイルシステムを調査します。専用のファイルツールを優先し、シェルパイプラインが有用な場合だけ bash を有効にしてください。

各 eval SQLite バックエンドのシグナルレジストリは空の状態で始まり、マイグレーションは製品固有のシグナルを初期登録しません。/evals/agents の展開可能な表、または /evals/signals で管理します。シグナルを追加すると設定で選択できるようになりますが、どの設定でも自動的には有効になりません。signal ツールと設定ごとの選択シグナル一覧はデフォルトで無効または空です。システムプロンプトとツールスキーマには、その設定で選択されたアクティブなシグナルだけが入ります。

/sources は、このバックエンドの PXCHAT_DATA_SOURCES_DIR が所有するアクティブなリビジョンであり、リポジトリのチェックアウトではありません。チャットリクエストは Pi セッション中のリビジョンを固定し、eval ランはすべてのケースとシナリオターンで1つのリビジョンを固定します。ZIP アップロードが変更するのは Mirage だけで、ragSearch は別の Postgres ストアです。ユースケースごとに異なる PXCHAT_DATA_SOURCES_DIR、EVAL_DB_PATH、そして RAG を有効にする場合は DATABASE_URL を使ってください。

インポートは UTF-8 テキストファイルだけを受け付け、安全でないパス、シンボリックリンク、バイナリ、名前/種類の衝突、空のアーカイブ、過大または異常に圧縮されたアーカイブを拒否します。不変リビジョンでは未変更ファイルをハードリンクします。バックエンドはデフォルトで3つの非アクティブリビジョンを保持し、セッションが固定中かもしれないリビジョンを削除する代わりに追加インポートを拒否します。より長い運用管理履歴が必要な場合は PXCHAT_DATA_SOURCES_MAX_INACTIVE_REVISIONS（0〜100）を設定してください。

Data Sources API のすべてのリクエストに PXCHAT_DATA_SOURCES_ADMIN_TOKEN が必要で、UI が入力されたトークンを保持するのは sessionStorage だけです。ローカル開発では PXCHAT_DATA_SOURCES_ALLOW_UNAUTHENTICATED_DEV=1 で明示的に無効化できますが、本番環境では無視されます。書き込みもデフォルトで無効なので、信頼済み管理者向けにのみ PXCHAT_SOURCES_WRITE_ENABLED=1 を有効にしてください。eval/admin アプリのその他の画面には組み込み認証がないため、別途保護してください。

すべてのツールを無効にした設定も有効です。Pi は選択したモデルを使う通常の会話アシスタントとして応答を続けます。ツールが0個でも UI がコーディングエージェント風に切り替わったり、設定警告が出たりすることはありません。公開チャットでは、検証済み最終回答テキストに加えて、明示的に有効化された一時的な data-signal だけを配信します。非公開の推論、中間ターン、生のツールイベント、内部 /sources パス、出典フッターは表示しません。ヘッドレス eval の成果物には、検証と診断のために引用情報と送信済みシグナルを保持します。

チャットフロントエンドは data-signal を会話履歴の外で処理します。Web ではハンドラー登録または pxchat:signal カスタムイベントを利用できます。組み込みモバイルホストには同じ { type: "pxchat.signal", signal } エンベロープを、iOS の window.webkit.messageHandlers.pxchatSignal.postMessage(...) または Android の window.PXChatSignalBridge.postMessage(...) で渡します。ホスト側はシグナル名を許可リストで検証し、signal.id で重複排除してください。payload は信頼できないエージェント出力として扱います。登録済みシグナルの製品動作が承認されるまでは、組み込み Web リアクションマップは空です。

ヘッドレス eval ランも同じランタイムと設定を使いますが、ケースごとの成果物には診断と採点に必要な内部トレース、ツール呼び出し、ツール結果のテレメトリを保持します。このテレメトリは eval のレビュー画面で利用でき、エンドユーザーのチャット履歴には送信されません。

ケースモデル

各ケースには2つの状態概念があります。

  • workflowStatus
    • draft: 作成中で、実行対象ではありません。
    • active: 実行可能な選択に含まれます。
    • disabled: ライブラリには保持されますが、ランからは除外されます。
  • sourceStatus
    • インポートまたはスプレッドシートワークフローから保持されます。
    • メタデータと絞り込みには役立ちますが、ケースを実行すべきかどうかの判断には使いません。

その他の重要フィールド:

  • caseType: golden、scenario_turn、または exploratory
  • sourceCaseId: 外部/スプレッドシート識別子
  • scenarioKey + scenarioTurn: 複数ターンの継続性テストに使用
  • isReleaseCritical: リリース信頼度で重く見るべきケースを示す
  • tags: 観点、ポリシー区分、回帰パック、その他のラン選択子として再利用できるラベル
  • expectedSignals: 任意の完全一致シグナル検証です。null は検証しない、[] はシグナルなしを期待、名前リストは各名前を1回ずつ期待します。欠落、想定外、重複のいずれも、回答判定が合格でもケースを不合格にします。

ランのマニフェストにはアクティブなシグナル定義をスナップショットします。ケースフォームでは既存ケースを変更せず、必要なケースだけ完全一致検証を有効にできます。JSON インポートは nullable な expectedSignals、Excel は任意の Expected_Signals を使います。フィールドを省略すると従来どおりシグナルを採点しません。

この Eval UI でケースを作成する

  1. ケースライブラリを開きます。
  2. 新規ケース をクリックします。
  3. 次を入力します。
    • caseKey
    • caseType
    • workflowStatus
    • プロンプトと期待値のフィールド
  4. 調整中は draft として保存します。
  5. 実行準備ができたら active に移します。

ヒント:

  • 既存ケースの 複製 を使うと、バリアントをすばやく作成できます。
  • シナリオテストでは scenarioKey と scenarioTurn を定義します。
  • シナリオターンのケースでは、次のターンを追加 で現在のケースから次ターンを分岐できます。

シナリオ作成

ケースライブラリにはシナリオグループ用フォームがあります。

次の定義に使います。

  • scenarioKey
  • 表示名
  • 共有ターゲット
  • 共有タグ

その後、その scenarioKey を参照するシナリオターンケースを追加します。

プリセット

プリセットは再利用可能な保存済みラン選択です。

保存できる内容:

  • 明示的なケース ID
  • フィルターに基づく選択
  • デフォルトモード
  • デフォルト言語
  • デフォルトサンプル数
  • 任意の判定基準セット

概要ダッシュボードでできること:

  • スイートと保存済みプリセットを選ぶ
  • 保存済みのモード、言語、サンプル数、バリアント、選択方式を確認する
  • 準備状況の検証後にプリセットを直接実行する
  • カスタムランが必要なときはラン作成へ移動する

専用のプリセット画面でできること:

  • すべてのプリセットを一覧で見る
  • プリセットのデフォルトと選択ロジックを編集する
  • プリセットをフィルター型と明示ケース型の間で切り替える
  • このサーバー上でプリセットの定期ランをスケジュールする

新しいスイートには、トップレベル Pi 用のスタータープリセットとして、RAG only、Sources only、RAG + Sources の3つが含まれます。

判定基準

基準画面では、自動判定モデルが使うルーブリックを管理します。

デフォルト基準セットは eval DB のブートストラップで自動作成され、次の5軸を含みます。

  • accuracy
  • relevance
  • consistency
  • safety
  • style

各軸には定義、1から5のスコア基準、例を保存できます。基準セットには、最小合計スコア、最小 safety、最小 accuracy、最小 relevance、言語/形式ゲートなどの合格しきい値も保存されます。

新規ランは、ラン作成で別の基準を選ばない限りデフォルト基準セットを使います。ランマニフェストには選択した基準がスナップショットされるため、後からデフォルトを変更しても過去ランのルーブリックは保持されます。

スケジュール済みプリセットラン

プリセットスケジュールはプリセット画面にあります。

各スケジュールは1つのプリセットに属し、次を保存します。

  • 実行間隔 (daily、weekdays、または weekly)
  • ローカル時刻
  • タイムゾーン
  • 有効または一時停止状態
  • 前回ラン
  • 次回予定ラン

Next.js サービスが動作している間、eval スケジューラーは期限が来たスケジュールを確認し、プリセットを自動的に起動します。

スケジュール済みランも通常のラン一覧とラン詳細画面に表示されるため、手動で起動したランと同じ方法でレビューできます。

準備チェック

ハーネスは自動的に次を確認します。

  • チャットモデル接続
  • 判定モデル接続
  • eval SQLite DB アクセス
  • アプリ Postgres アクセス
  • 埋め込み/プリフライトカバレッジ

ラン開始時の挙動:

  • ブロッキング失敗があるとラン開始を止めます。
  • カバレッジ問題は、あとで厳格化しない限り警告のままです。

SQLite eval DB はデフォルトではローカルマシン状態です。この repo は evals/*.sqlite* を無視します。これには -wal、-shm のサイドカーとリカバリバックアップも含まれるため、新しい clone は独自のラン履歴を持ちます。デモ前には bun run eval:db-check を使い、ローカル DB ファイルのコピーやバックアップ前には bun run eval:db-checkpoint を使ってください。

ランを開始する

保存済みプリセットパックをすばやく実行したい場合は、概要ダッシュボードを使います。

ラン作成画面で次を行います。

  1. 明示ケースを選択するか、フィルター済みパックを定義します。
  2. エージェントバリアントと候補モデルバリアントを選びます。
  3. モード、言語、サンプル数、判定モデル、判定基準を選びます。
  4. 準備状況の概要でブロッキングチェックが問題ないことを確認します。
  5. ランを開始します。

開始後、アプリはすぐライブラン画面へリダイレクトするため、チームはランが実際に始まったことを確認できます。

結果をレビューする

ラン詳細画面は次の構成です。

  • ライブ実行ヘッダー
  • リリースゲートと品質メトリクス
  • 基準ランおよび前回ランとの比較
  • 例外レビューキュー
  • 失敗ケース概要
  • ケース別ドリルダウン
  • 詳細診断

例外キューが主な手動レビュー画面です。

次のケースがここに入ります。

  • 失敗
  • エラー
  • 未採点
  • 判定/ゲート不一致
  • 手動レビュー済み

基準ランと比較

ラン画面で 基準ランに設定 を使い、スイートの参照ランを固定します。

各ランは次と比較できます。

  • 固定された基準ラン
  • 直前のラン

比較で強調されるもの:

  • 合格率の差分
  • スコア差分
  • エラー差分
  • 変化した判定
  • 変化したケース

CLI コマンド

これらは引き続き利用でき、インポートやヘッドレスランに便利です。

bun run eval:migrate
bun run eval:db-check
bun run eval:db-checkpoint
bun run eval:preflight
bun run eval:judge-check
bun run eval:import -- --suite pxchat --file ./evals/seed/your_dataset.xlsx
bun run eval:run -- --suite pxchat --mode isolated --lang ja --samples 1

推奨チームワークフロー

  1. この eval UI でケースを追加または複製します。
  2. プロンプトと期待値が整うまでは新規作業を draft に保ちます。
  3. 安定したケースを active に移します。
  4. チームが頻繁に再実行するパックをプリセットとして保存します。
  5. プリセットを実行します。
  6. 例外キューだけをレビューします。
  7. 新しいランを基準ランと比較します。
  8. 結果が本当に良くなったときだけ新しい基準ランを固定します。

トラブルシューティング

  • 開始前にランがブロックされる:
    • まず準備状況の概要と詳細を読みます。
    • 再試行前にチャットモデル、判定モデル、DB 接続を修正します。
  • カバレッジ警告:
    • ランは開始できますが、検索品質の評価が誤解を招く可能性があります。
  • ケースがランに出てこない:
    • workflowStatus を確認します。実行可能なのは active ケースだけです。
  • インポート済みスプレッドシートの状態が変に見える:
    • その値は sourceStatus として保持されています。ラン可否は制御しません。