working-with-autoresearch

autoresearch の使用

Autoresearch は、モデルごとに「ある期間内に、母集団の誰が特定の目標を達成するか」という問いに答えます。 たとえば、「今後 7 日間にレポートを開くアクティブユーザーは誰か」といった問いです。

1. ユーザーは 目標（イベントまたは PostHog アクション）、母集団、日数で表す 期間 を指定します。
2. トレーニングエージェントが PostHog のサンドボックスで実行されます。特徴量の SQL とモデルを作成し、各実験をホールドアウトセットで評価します。ホールドアウトの AUC が改善したものを保持し、それ以外は破棄します。
3. サーバーは、保持された実験の中から チャンピオン を選びます。エージェントが提案し、バックエンドが決定します。
4. 各実行間隔（デフォルトでは毎日 02:00 UTC）で、チャンピオンが推論対象の母集団をスコアリングします。 スコアリングされた各人物について、確率を含む autoresearch_prediction イベントが記録されます。 モデルの write_person_property が有効な場合、現在の distinct ID に解決される人物には、モデルの出力を表す人物プロパティ（例：predicted_p_adopt_insights_14d）も付与されます。新しいモデルではデフォルトで無効です。スコアに基づいてフラグ、コホート、ワークフロー、インサイトの対象者を指定する前に、autoresearch-partial-update で有効にしてください。無効にすると、そのモデルがスコアリングした人物からこのプロパティが削除されます。この設定の変更には person:write スコープが必要です。
5. 予測日から期間が経過すると、オンライン検証でスコアを実際の結果と照合し、実現 AUC を記録します。
6. トレーニングはスケジュールに沿って継続されます。各スコアリング日にモデルはリサーチ実行（探索）を開始し、より良いモデルが昇格しない実行が発生するか、リサーチ実行が 5 回に達するまで続けます。 その後は、最新のトレーニング実行から research_interval_days（維持。デフォルトは 7 日）ごとにリサーチ実行を 1 回開始します。手動で開始した実行も、実行間隔の起点をリセットします。 research_interval_days が null の場合、モデルは要求があったときにのみトレーニングされます。スコアリングできないチャンピオンに対しては、短時間の復旧実行も行われます。 posthog:autoresearch-retrieve の training_phase と next_research_at で、モデルの状態を確認できます。

PostHog の UI では、対象は モデル です。API とツールでは パイプライン と呼ばれます。人に説明するときは「モデル」を使ってください。

Autoresearch は autoresearch 機能フラグで制御されています。 トレーニングはクラウドサンドボックスで実行されるため、PostHog Desktop へのアクセスも必要です。 autoresearch-* ツールが見つからない場合、そのプロジェクトにはまだアクセス権がない可能性があります。

作業を選ぶ

ユーザーの目的	まず使うもの	参考資料
モデルを作成する	posthog:autoresearch-resolve-template-create またはカスタム定義を使い、その後 posthog:autoresearch-validate-create	defining-a-question.md
モデルの性能を確認する	posthog:autoresearch-retrieve、その後 posthog:autoresearch-online-performance-retrieve	reading-model-quality.md
予測を使う	出力された人物プロパティ、または autoresearch_prediction に対する posthog:execute-sql	using-predictions.md
モデルを修正または調整する	posthog:autoresearch-training-runs-list、posthog:autoresearch-runs-list、posthog:autoresearch-suggestions-create	troubleshooting-and-steering.md
既存のモデルを確認する	posthog:autoresearch-list	このページ

作成、トレーニング、スコアリング

通常の手順は短く済みます。各ツールの説明には前提条件と拒否条件が記載されているため、初めて呼び出す前に info で確認してください。

1. 解決または定義します。 テンプレートでは、よくある質問（アクティビティ、非アクティブ化のリスク、初回利用後の再訪、機能の採用、反復行動）に対応しています。該当するものがない場合は、カスタム定義を使用できます。defining-a-question.md を参照してください。
2. 検証します。 作成時に使用するものと同じ対象、期間、ルックバック期間、母集団を指定して posthog:autoresearch-validate-create を実行します。ベースレート、正例と負例の件数、警告が返されます。can_proceed を false にするものはすべて修正し、ブロッキングではない警告についてはユーザーに伝えてください。
3. 作成します。 posthog:autoresearch-create を実行します。新しいモデルは、トレーニングが始まるまで draft 状態です。
4. トレーニングします。 posthog:autoresearch-train-create を実行すると、時間のかかるエージェント実行が開始されます（数十分かかることもよくあります）。サンドボックスと LLM の実行時間が実際に消費されるため、開始前にユーザーの確認を得てください。また、実行中に2つ目の実行を開始してはいけません。403 が返された場合、呼び出しがサンドボックス内から行われた（モデルのページで Start training をクリックするようユーザーに依頼してください）か、ユーザーに PostHog Desktop へのアクセス権がない（その場合もページで拒否されます）かのどちらかです。エラーメッセージを読んで、どちらかを伝えてください。
5. 待機します。 posthog:autoresearch-training-runs-list をゆっくりしたペースでポーリングします。最初の実行が進行中の間、モデルは bootstrapping 状態であり、チャンピオンがまだいないのは正常です。
6. スコアリングします。 チャンピオンが昇格した後、次の日次スイープで母集団のスコアが計算されます。今日のスコアを今すぐ計算するには posthog:autoresearch-score-create を実行し、その後 posthog:autoresearch-runs-list をポーリングします。1日に同じ日付の手動スコアリングを2回行うと、予測が重複することがあります。

一時停止、再開、削除は、UI のモデルメニューからのみ行えます。 一時停止すると、スコアリングと新しいトレーニング実行が停止します。すでに進行中のトレーニング実行は継続し、チャンピオンを昇格させることもあります。

モデルの状態

状態	意味
draft	定義済みですが、トレーニングは一度も実施されていません。
bootstrapping	最初のトレーニング実行が進行中です。チャンピオンはまだいません。
running	チャンピオンが存在し、所定の間隔でスコアリングされます。再トレーニングが行われることもあります。
converged	running と同様に扱われます。チャンピオンは引き続きスコアリングされ、検証されます。
paused	UI で誰かが再開するまで、スコアリングも新しいトレーニングも行われません。すでに進行中の実行は完了します。

トレーニング実行の iteration_count と best_holdout_score は、実行が完了したときにのみ書き込まれます。 正常な実行でも、実験の記録がすでに残っている一方で、イテレーション数が0と表示されることがあります。そのため、カウンターだけを見て実行が停止していると判断しないでください。

結果について伝える方法

• Holdout AUC は、学習データから除外しておいたデータでのスコアです。過去のユーザーをモデルがどれだけ適切に順位付けできたかを示します。期待値として扱ってください。
• Realized AUC は、予測期間の経過後に実際の結果と照らし合わせたスコアです。証拠として扱ってください。実測値がある場合は、必ず Holdout AUC より優先します。
• UI では AUC 0.8 以上を Strong、0.7 以上を Fair、それ未満を Weak と表示し、その評価がテストのみに基づくのか、実際の結果で確認済みなのかも示します。エージェントと UI の表現が一致するよう、同じ言葉を使ってください。
• Lift at 10% は、わかりやすく伝えるための要約です。「上位 10% は、X する可能性が平均の 3.2 倍です」のように表現します。
• スコアは確率ですが、対象の発生率が低い場合は、順位として捉えるのが適切なことがよくあります。ベースレートが数パーセント未満の場合は、そのことを伝えてください。

reading-model-quality.md では、キャリブレーション、尤度セグメント、カバレッジ、数値が一致しない場合の伝え方について説明しています。

留意すべきガードレール

• 質問を変える場合は、新しいモデルが必要です。 モデルの学習に使用したフィールド（ターゲット、予測期間、母集団）は、モデルの作成後は固定されます。既存モデルを編集せず、新しいモデルを作成してください。
• Autoresearch が学習に使うのは、識別済みユーザーのみです。 匿名トラフィックは学習データに含まれないため、イベントの総数から利用可能なデータ量を過大評価することがあります。検証件数を基準にしてください。
• スコアはユーザーにひも付けられています。 ほとんどのスコアが同じ値になるモデルは、シグナルが弱いのではなく、識別子に問題がある可能性があります。troubleshooting-and-steering.md を参照してください。
• 推測せず、出力プロパティ名を確認してください。 posthog:autoresearch-retrieve から output_person_property を取得してください。派生名にはターゲットと予測期間（predicted_p_<target>_<horizon>d）が含まれ、テンプレートには独自のプレフィックスが使われるため、同じターゲットの 2 つのモデルが互いに上書きすることはありません。
• 学習コストの大半は、リサーチモデルによって決まります。 学習の実行では、モデルの agent_model と agent_reasoning_effort が使われます。null の場合はデフォルトの Claude Opus 5.5 が中程度の推論量で使われ、1 回の実行あたりのコストは Claude Sonnet 5.5 の約 2 倍です。posthog:autoresearch-retrieve の effective_agent_model で次回の実行に使われるモデルを確認でき、posthog:autoresearch-partial-update で変更できます。不明なモデル、またはモデルがサポートしていない推論量を指定すると、有効な選択肢とともに 400 が返されます。posthog:autoresearch-training-runs-list では、各実行で使われたモデルを確認できます。
• モデルの学習には費用がかかり、スコアの算出にはクエリが必要です。 非常に大きな母集団のスコアはローリングバッチ（1 回の実行あたり約 45,000 人）で算出されるため、全員のスコアが毎日更新されるとは限りません。検証結果から、全件のスコアを再計算するのに必要な実行回数を確認できます。

独自のエージェントを使う

PostHog の外部で動作するエージェント（たとえばノート PC 上のエージェント）でも、既存のパイプライン用のモデルを学習できます。 posthog:autoresearch-training-runs-create で実行を開始し、posthog:autoresearch-training-runs-iterations-create で各実験を記録し、posthog:autoresearch-training-runs-artifacts-upload-create でバンドルをアップロードして、posthog:autoresearch-training-runs-complete-create で完了します。 posthog:autoresearch-materialize-features が PostHog サンドボックス内にしか書き込まないため、学習データは posthog:execute-sql で取得します。 同じターゲットで以前の実行から得られた知見を再利用できるよう、まず posthog:autoresearch-training-runs-history を確認してください。 有効な特徴量 SQL の仕様はイテレーションツールの説明に記載されています。最初のイテレーションを始める前に、説明をすべて読んでください。