学习笔记 · Obsidian
Run v1：查询、统计、线程预览与删除
v1 run 组提供了查询、聚合、统计、自然语言生成 filter、Thread 预览、旧共享契约与破坏性删除。它与 v2 Run API 并存，不能只根据路径名相似就混用请求/响应 schema。
能力表
| 能力 | 方法与路径 | 要点 |
|---|---|---|
| 查询 | POST /api/v1/runs/query | BodyParamsForRunsQuerySchema → runs + cursors |
| 语法验证 | POST /api/v1/runs/query/validate | valid + errors；OpenAPI 未声明认证 |
| 自然语言转 filter | POST /api/v1/runs/generate-query | query → filter + feedback URLs |
| 读单 Run | GET /api/v1/runs/{run_id} | 可带 session/start time 及排除大字段开关 |
| 分组 / 分组统计 | POST /api/v1/runs/group / group/stats | session + group_by |
| 全局统计 | POST /api/v1/runs/stats | 必填 session 数组 |
| Thread 预览 | GET /api/v1/runs/threads/{thread_id} | 必填 session_id，可选 select/variables |
| 共享状态 / 共享 / 取消 | GET / PUT / DELETE /api/v1/runs/{run_id}/share | v1 共享契约 |
| 删除条件集 | POST /api/v1/runs/delete | trace IDs 或 metadata，可波及 examples |
| ABAC Trace 删除 | POST /api/v1/runs/delete/traces | 必填 session + trace IDs |
查询模型与翻页
/runs/query 支持 ID、trace/parent、run type、sessions、reference examples、时间、error、root、filter/trace_filter/tree_filter、实验搜索和字段 select。默认 limit=100，响应是 runs、分页 cursors、可选 search cursors 与 parsed query。
特别边界：传 trace 时 limit 和 cursor pagination 不生效，会在单次响应返回整个 Trace 的 Runs。大 Trace 上调用前应评估响应体和网关上限，必要时改用 v2 投影和时间窗。
validate-runs-query 只验证语法，不代替 tenant/session 授权。当前 OpenAPI 对此 operation 没有 security requirement，如自托管暴露公网，应由 ingress 限流、限 body 并避免错误信息泄露解析器细节。
自然语言生成的 filter 不可直接执行
generate-query 输入自然语言 query，返回 filter 和多个用于产品反馈的 URL（如用户选择/打开 Run、结果大小、filter 是否有效）。生成 filter 应视为不可信输出：先 validate，展示给用户审查，再由服务端强制 workspace/session 与最大时间窗；反馈 URL 同样按 capability URL 保护，不记日志或转发给第三方分析。
聚合与成本指标
RunGroupRequest 必填 session_id 和 group_by，可按 name/run_type/tag/metadata 及 metadata path 分组，并有时间、filter、offset/limit。stats 可返回 count、latency/first-token P50/P99、token 和 cost 总量/分位、error/streaming rate、feedback stats 及细分。
监控报表必须固定时区、时间窗、filter 和分组定义，同时记录无数据、部分数据与延迟到达；null 指标不能当 0。费用是根据模型价格映射估算，应保存价格版本与数据窗口，不作为财务对账的唯一来源。
共享与读取最小化
读单 Run 可用 exclude_s3_stored_attributes、exclude_serialized、include_messages 控制负载。默认不要拉取 serialized/messages 到列表或日志。v1 share 先读状态，再显式 PUT；撤销后不应假定旧链接在所有下游缓存立即消失。
删除是高风险作业
/runs/delete 可传 session_id、trace_ids、metadata、start_time，还有 delete_examples 开关；ABAC 版强制 session_id + trace_ids。执行前应：
- 用同一作用域先 query/count 生成待删 Trace ID 快照；
- 双人审批 tenant/session、数量、时间范围和
delete_examples； - 分批、限速、以 trace ID 精确删除，记录不含载荷的审计清单；
- 删后重查 Run、Feedback、数据集关联和公开 share state。
文档没有承诺级联、恢复或幂等语义，不应仅因 HTTP 200 就宣称数据已完全清理。