creating-replay-vision-scanners

Replay Vision スキャナーの作成

スキャナーは、セッションの録画を対象とする常時稼働の LLM プローブです。作成して有効にすると、5 分ごとに対象を確認する Temporal スケジュールで実行され、条件に一致する新しい録画それぞれにプロンプトを適用し、その結果をオブザベーション（クエリ可能な $recording_observed イベント）として記録します。各オブザベーションでは、現在の請求期間における組織の予算からクレジット（1 クレジット = $0.01）が消費され、オブザベーションの料金はスキャナーの model によって異なります。そのため、消費額はクレジットで見積もり、ユーザーから指定されたオブザベーション数は、そのモデルの料金に基づいてクレジットに換算してください。

このスケジュールがあるため、作成時には慎重な確認が必要です。条件が緩く、サンプリング率が 100％のスキャナーは自動的に課金を開始し、最初の数回の実行で期間全体の予算を使い果たす可能性があります。作成時にはクォータがチェックされません。保護が適用されるのはオブザベーションの実行時だけであり、その時点ではすでに予算がなくなっている可能性があります。

まず、スキャナーは本当に適切ですか？

スキャナーは、今後の録画を継続的に監視するものです。ユーザーが特定のセッションを前にして、そのセッションについて質問している場合、スキャナーは必要ありません。その場合は vision-scanners-inline-scan を使います。これは session_ids と prompt を受け取り、何も保存せず、スケジュールも設定しません。

対象のセッションがすでに決まっている場合は、インラインスキャンを使ってください。「この 5 件の録画では何が問題だったのか」「昨日のチェックアウトセッションでクーポンのバグが発生したものはあったか」など、スキャナーを作成して後から削除することで答えようとしていた質問には、すべてインラインスキャンを使います。セッションごとのクレジット消費は同じで、同じ質問が繰り返された場合は回答を再利用するため、再度質問しても低コストです。

スキャナーを作成するのは、ユーザーがまだ発生していない録画を自動的にスキャンしたい場合だけです。スキャナーを作成して結果を一度だけ確認し、その後削除しようとしているなら、そこでやめてインラインスキャンを実行してください。一時的なスキャナーを作成すると、条件に一致する今後のすべての録画に対して、スケジュールされたスキャンが実行され続けます。

基本原則：作成前に規模を見積もる

有効なスキャナーを、確認せずに作成してはいけません。月あたりのクレジット消費量を見積もり、残りのクレジット予算を確認してください。予測される消費量が残りの予算に対して無視できない割合を占める場合は、作成前に数値をユーザーに示し、確認を得てください。これがこのスキルの中核です。それ以外は補足事項です。

手順

ステップ 1：スキャナーに何をさせるべきですか？

質問、種類、またはプロンプトがまだ曖昧な場合は、まず [[designing-replay-vision-scanners]] を実行してください。希望を、回答形式が固定された、証明ルールが定められ、判定不能と答えることも許可された、明確な質問に変換します。それらが決まったら、ここに戻ってください。

scanner_type を選び、scanner_config を記述します。どの種類にも prompt が必要です。その他の設定は種類によって異なります。

Type	生成するもの	scanner_config の形式
monitor	プロンプトに基づく自由形式の観察（例：「怒りによる連打を検出する」）	{"prompt": "..."}；任意で "allow_inconclusive": true（デフォルトでは無効のため、モデルは「はい」または「いいえ」で答える必要があります）
classifier	固定されたラベルセットからタグを割り当てます	{"prompt": "...", "tags": ["tag-a", "tag-b"]} — tags には 1 件以上の項目が必要です；任意で "multi_label": false（デフォルトは true）、"allow_freeform_tags": true（デフォルトでは無効）
scorer	評価基準に基づく数値スコア	{"prompt": "...", "scale": {"min": 1, "max": 5, "label": "frustration"}} — min は max より小さい値にします；label は任意です
summarizer	自由形式の要約	{"prompt": "..."}；任意で "length": "short" | "medium" | "long"（デフォルトは "medium"）。埋め込みは常に有効です

scanner_type は 作成後に変更できません。変更するには削除して作り直す必要があるため、最初に種類が正しいことを確認し、scanner_config の形式も正しく設定してください（形式が誤っていると、デフォルト値が黙って適用されるのではなく、作成エラーになります。不明なキーも拒否されます）。

ユーザーの意図から種類とプロンプトが明らかな場合は、そのまま進めてください。ユーザーに細かく質問する必要はありません。 ユーザーが目標だけを持っている場合（「オンボーディングでユーザーがつまずく箇所を見つける」など）、vision-scanners-draft が種類、設定、クエリ、モデル、サンプリングを下書きとして作成し、ユーザーが確認できるようにします。何も保存されません。 どのくらい利用するかをユーザーに尋ね、2 つの選択肢を提示してください。無料（free_only: true。組織の月間無料クレジットのみを使用し、請求額が増えることはありません）、またはユーザーが指定する月間クレジット予算です。予算を決めつけてはいけません。下書きの free_only と credit_limit を vision-scanners-create に渡してください。 classifier の場合、vision-scanners-suggest-tags がプロジェクトのデータに基づいたラベルを提案します。

ステップ 2：どのセッションを対象にしますか？

query は、スキャナーが監視する録画を選択する RecordingsQuery 形式です。date_from と date_to は無視されます（時間はスケジュールで制御されます）。そのため、設定する必要はありません。イベント、URL、ユーザープロパティ、継続時間などでクエリを絞り込み、実際に重要なセッションを対象にしてください。クエリを絞り込むことが、コストに最も大きく影響します。

1 つの実験の露出対象者をターゲットにする場合は、専用のジョブとして実行します。手動でクエリを組み立てるのではなく、実験の露出条件からクエリを生成する scanning-experiments-with-replay-vision スキルを使用してください。

さらに絞り込むための方法が 2 つあります。次の順に適用されます。

• sampling_mode（デフォルトは comprehensive）は、マッチしたセッションに対する品質の事前フィルターです。focused はサーフェシングスコアの高いセッションのみを保持し、balanced は品質の低いセッションを除外し、comprehensive はすべてを保持します。対象範囲を無作為に狭めるのではなく、見る価値のあるセッションに予算を使うために活用してください。
• sampling_rate（0～1、デフォルトは 1.0）は、その後に適用されるランダムなダウンサンプリングです。対象範囲と予算のバランスを取るには、値を下げてください。0 を指定するとスキャンが一時停止されます。0.0001 未満の 0 以外の値は拒否されます。

どのモデルを使いますか？

model はスキャナーが行うすべての観察の料金を決めるため、品質だけでなくコストにも影響します。gemini-3.5-flash-lite（2 クレジット）、gemini-3-flash-preview（5 クレジット、デフォルト）、gemini-3.8-flash （15 クレジット）から選べます。まずはデフォルトを使用し、安価なモデルではスキャナーが探しているものを明らかに見逃す場合に限り、gemini-3.8-flash を選択してください。

ステップ 3：規模を見積もる — 直感的なチェック（省略しないでください）

作成する前に、両方のチェックを実行し、あわせて判断してください。

1. 支出を見積もる — 提案する query、sampling_rate、sampling_mode、model を指定して vision-scanners-estimate を呼び出します。matched_sessions_in_window、測定対象の window_days、estimated_observations_per_month、credits_per_observation、estimated_credits_per_month、および other_enabled_scanners_monthly_credits（組織で有効になっているほかのスキャナーにすでに見込まれている支出）が返されます。既存のスキャナーを編集する場合は、そのスキャナー自身の見積もりが二重に計上されないよう、scanner_id を渡してください。
2. 予算を確認する — 組織の credit_limit（クレジット。1 クレジット = $0.01。上限なしの場合は null）に対する remaining と exhausted、および現在の期間の period_start／period_end を取得するため、vision-quota-get を呼び出します。

製品 UI と同じように、同じ期間におけるクレジット同士を比較してください。remaining の単位はクレジットであり、観測数ではありません。そのため、remaining と estimated_observations_per_month を比較すると、モデルごとの観測単価の分だけコストを過小評価することになります。 remaining は現在の期間の残り日数に使える分なので、1 か月分の見積もりをそのまま比較するのではなく、その期間に合わせて月間予測を按分してください。

fleet_monthly    = estimated_credits_per_month + other_enabled_scanners_monthly_credits
period_days      = period_end - period_start        (in days)
days_left        = period_end - now                 (in days, floored at 0)
rest_of_period   = fleet_monthly * days_left / period_days

次に、rest_of_period と remaining を照らし合わせて判断します。

• remaining に余裕を持って収まる場合は、そのまま進めます。
• remaining の大部分を占める、または超える場合は、具体的な数値をユーザーに伝えて、いったん止めてください（例：「このスキャナーは月に約 X クレジット、約 $Y を使う見込みです。今期の残り N 日間では約 R クレジットとなり、残っている Z クレジットに対してこの額になります。」）。そのうえで、作成前に確認してください。query を絞り込む、sampling_mode を focused に切り替える、sampling_rate を下げる、またはより安価な model を選ぶことで、支出を抑えられます。
• そのスキャナーが 1 期間全体で使用するコストの目安でもあるため、estimated_credits_per_month も伝えてください。この期間の途中では remaining に収まっても、次の期間の予算を超えることがあります。
• 組織の予算がすでに exhausted の場合は、その旨を伝えてください。有効化した新しいスキャナーは、予算がリセットされるまで何も生成しません。スケジュールされた観測は通知なしにスキップされ、オンデマンドスキャンは完全に拒否されます。
• 見積もりが remaining の大部分を占めるものの、ユーザーがそれでもスキャナーを希望する場合は、スキャナーごとの上限を提案してください。作成時に credit_limit を設定すると、このスキャナーが請求期間ごとに使用できるクレジット数をその値に制限できます。次の観測に必要なクレジットを残額でまかなえなくなるとスキャンを停止し、期間がリセットされると再開します。上限によってスキップされたセッションが、後からスキャンされることはありません。
• ユーザーが上限を観測数で指定した場合（「観測を 200 回したら停止」など）、観測数を指定するフィールドはありません。該当するスキャナーの model に対する観測数に credits_per_observation を掛けた値を credit_limit に設定してください（見積もりとスキャナーのレスポンスの両方にこの値が含まれます）。設定したクレジット数もユーザーに伝えてください。上限はクレジット単位のままなので、後でモデルを変更すると、クレジット数は維持され、対象となる観測数が変わります。

ここでの確認は会話上の手順であり、API の機能ではありません。トレードオフを伝え、ユーザーに選択してもらってください。予測される使用量が予算に比べて明らかに少ない場合は、確認を求める必要はありません。

ステップ 4：作成する

vision-scanners-create を呼び出します。最小限の例：

{
  "name": "Rage click monitor",
  "scanner_type": "monitor",
  "scanner_config": { "prompt": "Flag sessions where the user repeatedly clicks the same element in frustration." },
  "query": { "kind": "RecordingsQuery", "events": [{ "id": "$rageclick", "type": "events" }] },
  "sampling_rate": 1.0,
  "sampling_mode": "comprehensive",
  "model": "gemini-3-flash-preview",
  "enabled": true
}

name はチーム内で一意である必要があります。ユーザーが一時停止した状態で作成したい場合は enabled: false を設定してください（スケジュールも実行されず、クォータも消費しません）。後から有効にできます。

emits_signals: true も知っておく価値のある設定です。Signals のサイドミッションをプロンプトに追加し、検出結果ごとに 1 つのシグナルを PostHog Signals の受信トレイに送信します。そこでセッションをまたいで検出結果が裏付けられ、レポートになります。ユーザーが観測結果を蓄積するだけでなく、受信トレイに結果を届けたい場合は有効にしてください。

作成後

• レスポンスに含まれるスキャナーの PostHog URL を表示し、ユーザーが UI で確認できるようにします。
• 結果が表示されるまでには数分かかります（録画の動画へのラスタライズと LLM の呼び出しに時間がかかります）。1 つのスキャナーの結果を時系列で確認するには vision-scanners-observations-list を、1 つのセッションに対するすべてのスキャナーの結果を確認するには vision-observations-list（session_id が必要）を使用します。録画を詳しく調べるには、investigating-replay スキルに引き継ぎます。
• 履歴の処理はオプトインです。 新しいスキャナーは、これ以降の録画だけを対象にします。過去の録画も対象にするには、対象期間について vision-scanners-backfills-estimate を実行し、ユーザーに total_sessions と total_credits を伝え、ユーザーの同意を得てから、その total_credits を max_total_credits として指定して vision-scanners-backfills-create を呼び出します。対象期間の費用が増えていて作成が拒否された場合は、見積もりを取り直して、再度ユーザーに確認します。vision-scanners-backfills-get で進捗を確認します。
• データがある場合はダッシュボードを案内します。 vision-scanners-get が dashboard_suggested: true を返した場合（スキャナーに十分な観察結果があり、ダッシュボードがまだない場合）は、vision-scanners-dashboard-create で作成するかどうかを一度だけ提案します。ユーザーが断った場合は、再度提案しません。新しく作成したスキャナーにはグラフ化するデータがないため、提案の対象にはなりません。
• 通知とダイジェスト。 vision-alerts-create（および通知先）を使うと結果が通知され、vision-scanners-scouts-create を使うと、スキャナーの結果をまとめたレポートを定期的に作成するスカウトが追加されます。
• スキャナーの改善方法を説明します。 最初のプロンプトは推測にすぎず、最初のスイープで修正されます。結果について、スキャナーが何を間違えたか、あるいは正しく判断したかを一言添えて、vision-observations-label-create を使って親指を上または下に評価するようユーザーに伝えます。ほとんどのスキャナーは評価されないため、最初の推測のまま実行され続けます。この評価の流れについては、exploring-replay-vision-observations スキルで説明しています。

既存のスキャナーを更新する

vision-scanners-update は部分更新です。変更するフィールドだけを送信してください。対象範囲を広げたり費用を上げたりする場合は、必ずステップ 3 の妥当性確認をもう一度行います。より広い query、より高い sampling_rate、より緩い sampling_mode、またはより高価な model は、対象範囲の広い新規スキャナーと同様に、いずれも月額費用を増やします。enabled の切り替え、プロンプトの調整、またはクエリの絞り込みでは、再見積もりは不要です。credit_limit が設定されたスキャナーの model を変更しても、クレジット数はそのままのため、上限内で処理できる観察結果の数が変わります。新しい件数をユーザーに伝え、以前と同じ件数にしたい場合は credit_limit の変更を提案します。設定を編集すると scanner_version が更新されます。過去の観察結果には、古い設定のスナップショットが保持されます。

注意点

• （スキャナー、セッション）ごとに観察結果は 1 件です。 すでに観察済みのセッションでスキャナーを再実行しても（失敗したものや対象外になったものも含む）、何も起こらず、新しいスキャンは行われません。失敗または対象外となった観察結果を置き換えるには vision-observations-retry を使用します。
• 対象外は失敗ではありません。 観察結果が ineligible（例：too_short、no_recording）になることがあります。これはエラーではなく、処理が終了した状態です。スキャナーが結果を出さなかった理由を調べる際は、error_reason を確認します。
• 現在のバージョンでは、プロバイダーとモデルは Google／Gemini のみです。