学习笔记 · Obsidian
Run Rules：评估、采样、回填与日志
Run Rule 是对 tracing 项目或数据集的持续自动化：按 filter 和采样率选 Run/Trace，执行 LLM/code evaluator，或将结果送往 Feedback、标注队列、数据集、PagerDuty 和 webhook。它会改变数据、花费模型成本并触发外部副作用，应当作生产作业系统治理。
端点与生命周期
| 阶段 | 方法与路径 |
|---|---|
| 创建 / 列表 | POST /api/v1/runs/rules / GET /api/v1/runs/rules |
| 更新 / 删除 | PATCH / DELETE /api/v1/runs/rules/{rule_id} |
| 预验证 | POST /api/v1/runs/rules/validate |
| 手动触发单条 | POST /api/v1/runs/rules/{rule_id}/trigger |
| 批量触发 | POST /api/v1/runs/rules/trigger |
| 最后一次应用 | GET /api/v1/runs/rules/{rule_id}/last_applied |
| 日志 offset 版 | GET /api/v1/runs/rules/{rule_id}/logs |
| 日志 cursor 版 | GET /api/v1/runs/rules/{rule_id}/logs/v2 |
Rule 契约
创建和更新都必填 display_name 和 sampling_rate。关键维度：
- 作用域：
session_id或dataset_id；列表可按两者、type、name、ID、evaluator/tag 筛选； - 命中逻辑：
filter、trace_filter、tree_filter、sampling_rate、is_enabled； - 评估：结构化 LLM evaluator、Python/TypeScript code evaluator、已有
evaluator_id/version； - 下游：
add_to_annotation_queue_id、add_to_dataset_id、corrections dataset、alerts、webhooks； - 回填/保留：
backfill_from、多个 extend-retention 开关、extend_only； - 成本：
spend_limit.limit_usd与 window，响应返回trace_count和spend_usd； - Thread 规则：
group_by只接受thread_id；可包含对齐标注队列。
sampling_rate 与 filter 是成本和覆盖率的一级控制：新规则应先禁用或极低采样灰度，查日志/费用/队列写入后再放量。backfill_from 会对历史数据运行，不能与实时规则一起盲目全量启用。
先 validate，再保存
POST /rules/validate 接受与创建 Rule 相同的配置加测试 inputs/outputs/reference outputs/attachments/thread ID。它只支持 LLM-as-judge，不允许 code evaluator；执行 Trace 会写入 evaluators 项目，所以 validate 也不是无副作用的本地语法检查。
生产流程：固定测试样本 → validate 输出和评估 Trace → 用审查后的 model/prompt/version 创建禁用 Rule → 低采样启用 → 观察日志、花费、webhook 失败 → 逐步放量。
触发、日志和恢复
批量触发 body 可按 rule_ids 或 dataset_id。触发响应没有返回每项作业状态，HTTP 200 不证明所有 evaluator/webhook 已完成；必须从 rule log 和下游幂等键核对。last_applied 有 backfill 开关，不要把实时和回填进度混在同一水位。
Rule log 包含 rule/run/trace/session IDs、开始结束/应用时间及各 action 结果。旧端点默认 limit=150, offset=0；v2 使用 cursor，并针对 S3 存储 outcome 用 run_outcomes_count 避免过度拉取，新采集器应优先 v2。对 webhook/PagerDuty 使用签名、幂等事件 ID、短超时、异步消费和 dead-letter queue；不把路由键或认证 header 写入 Rule 审计日志。
更新与删除边界
更新 schema 仍要求完整 display_name 和 sampling_rate，不应把 PATCH 等同于任意子集补丁；先 GET 当前版本、生成完整期望状态并做差异审查。删除前先禁用、等待在途作业结束、保存日志/配置快照并确认下游无依赖；文档没有承诺删除会撤销已写 Feedback、已入队数据或已发外部通知。