working-with-autoresearch

使用 autoresearch

Autoresearch 会为每个模型持续回答一个问题：某个人群中的哪些人会在指定时间范围内完成某个目标？ 例如：“哪些活跃用户会在接下来的 7 天内打开报告？”

1. 用户指定一个目标（事件或 PostHog 操作）、一个人群和一个以天为单位的时间范围。
2. 训练 Agent 在 PostHog 沙盒中运行。它编写特征 SQL 和模型，在留出集上评估每次实验，并保留能提高留出集 AUC 的实验，丢弃其余实验。
3. 服务端从保留的实验中选出冠军模型。Agent 提出方案；后端做出决定。
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）启动一次研究运行，因此手动启动的运行会重置计时。 如果 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
使用预测结果	输出的人物属性，或使用 posthog:execute-sql 查询 autoresearch_prediction	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 会启动一个耗时较长的 Agent 运行（通常需要几十分钟）。这会消耗实际的沙盒和 LLM 运行时间，因此启动前请先征得用户同意，并且在已有运行进行时，绝不要再启动第二个运行。403 表示调用来自沙盒内部（请用户在模型页面点击 Start training），或者用户没有 PostHog Desktop 访问权限（该页面也会拒绝访问）。请阅读错误消息来区分这两种情况。
5. 等待。 以较宽松的频率轮询 posthog:autoresearch-training-runs-list。首次运行进行期间，模型处于 bootstrapping 状态，尚无冠军模型是正常的。
6. 评分。 冠军模型晋升后，下一次每日扫描会为人群评分。posthog:autoresearch-score-create 会立即为今天评分；调用一次，然后轮询 posthog:autoresearch-runs-list。同一天再次手动评分可能会产生重复预测。

暂停、恢复和删除只能在 UI 中的模型菜单操作。 暂停会停止评分和新的训练运行。已在进行中的训练运行会继续，并且仍可能晋升冠军模型。

模型状态

状态	含义
draft	已定义，从未训练。
bootstrapping	首次训练运行正在进行。尚无冠军模型。
running	已有冠军模型，并按计划周期评分。仍可能进行重新训练。
converged	视同 running：冠军模型仍会评分，也仍会经过验证。
paused	不会评分，也不会开始新的训练，直到有人在 UI 中恢复。已在进行中的运行会完成。

训练运行的 iteration_count 和 best_holdout_score 仅会在运行完成时写入。 健康的运行可能会显示 0 次迭代，即使其试验已经记录，因此不要仅凭计数器就判断运行卡住了。

如何解读结果

• 留出集 AUC 是模型在留出的训练数据上的得分。它说明模型对过去的人群进行排序的效果。应将其视为承诺。
• 实际 AUC 是预测时限过后，模型根据真实结果计算出的得分。应将其视为证明。只要实际 AUC 存在，它就优先于留出集 AUC。
• UI 将 AUC 达到 0.8 标为 Strong，达到 0.7 标为 Fair，低于 0.7 标为 Weak，并说明该标签仅来自测试，还是已由真实结果验证。请使用相同的词语，以保持 Agent 与 UI 的说法一致。
• 前 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），模板则使用各自的前缀，因此同一目标的两个模型不会互相覆盖。
• 研究模型决定了大部分训练成本。 一次训练运行使用模型的 agent_model 和 agent_reasoning_effort。设为 Null 时使用默认值：Claude Opus 5.5、中等推理力度，其每次运行的成本约为 Claude Sonnet 5.5 的两倍。posthog:autoresearch-retrieve 中的 effective_agent_model 会显示下一次运行使用的模型，posthog:autoresearch-partial-update 可对其进行修改。未知模型或模型不支持的推理力度会返回 400，并列出有效选项。posthog:autoresearch-training-runs-list 会显示每次运行所用的模型。
• 训练模型需要花费资金，计算得分需要执行查询。 对于规模特别大的人群，系统会分批滚动计算得分（每次运行约 45,000 人），因此并非所有人每天都会获得新得分。验证结果会告诉你，完成一次全面重新评分需要运行多少次。

使用自己的 Agent

PostHog 之外的 Agent（例如笔记本电脑上的 Agent）可以为现有流水线训练模型。 它会通过 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:execute-sql 提取训练数据，因为 posthog:autoresearch-materialize-features 只会将数据写入 PostHog 沙盒。 请先阅读 posthog:autoresearch-training-runs-history，以复用同一目标的早期运行所学到的内容。 迭代工具的描述定义了有效特征 SQL 的规范：开始第一次迭代前，请完整阅读。