---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - run-rules
  - evaluation
topic: LangSmith Smith API Run Rules 评估、采样、回填与日志
sources:
  - https://docs.langchain.com/langsmith/smith-api/run/create-rule
  - https://docs.langchain.com/langsmith/smith-api/run/delete-rule
  - https://docs.langchain.com/langsmith/smith-api/run/get-last-applied-rule
  - https://docs.langchain.com/langsmith/smith-api/run/list-rule-logs
  - https://docs.langchain.com/langsmith/smith-api/run/list-rule-logs-v2
  - https://docs.langchain.com/langsmith/smith-api/run/list-rules
  - https://docs.langchain.com/langsmith/smith-api/run/trigger-rule
  - https://docs.langchain.com/langsmith/smith-api/run/trigger-rules
  - https://docs.langchain.com/langsmith/smith-api/run/update-rule
  - https://docs.langchain.com/langsmith/smith-api/run/validate-rule
last_verified: 2026-08-11
---

# 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、已入队数据或已发外部通知。