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 が必要です。それ以外は種類によって異なります。

種類	生成するもの	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 に渡してください。

ステップ 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. 予算を確認する — vision-quota-get を呼び出して、組織の credit_limit（クレジット。1 クレジット = $0.01。上限なしの場合は null）に対する remaining と exhausted、および現在の期間の period_start／period_end を確認します。

プロダクト UI と同じように、同じ期間についてクレジット同士を比較してください。remaining は観測回数ではなくクレジット単位のため、estimated_observations_per_month と比較すると、モデルごとの観測単価分だけコストを少なく見積もることになります。 remaining は現在の期間の残りに使えるクレジット数です。月間予測の全額と比較するのではなく、残りの期間に合わせて按分してください。

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 を選ぶことで、コストを抑えられます。
• estimated_credits_per_month も伝えてください。これは、このスキャナーを作成した期間が終了した後、1 期間全体でかかるコストです。期間の途中では 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 を使って作成するか、1 度だけ提案します。ユーザーが断った場合、再度提案しないでください。新規作成したばかりのスキャナーにはグラフ化するデータがないため、提案されることはありません。
• 通知とダイジェスト。 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 の切り替え、プロンプトの微調整、query の範囲縮小では、再見積もりは不要です。credit_limit が設定されたスキャナーの model を変更してもクレジット数は変わらないため、同じ上限で対象となる観察数は変わります。新しい件数をユーザーに伝え、以前の件数を維持したい場合は credit_limit の変更を提案してください。設定を編集すると scanner_version が更新されます。過去の観察結果には、古い設定のスナップショットが保持されます。

注意点

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