--- type: study created: 2026-08-11 updated: 2026-08-11 sensitivity: standard status: verified tags: - study - langchain - langsmith - smith-api - annotation - human-review topic: LangSmith Smith API Annotation Queue 审核调度与状态机 sources: - https://docs.langchain.com/langsmith/smith-api/annotation-queues/add-runs-to-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation-queues/add-runs-to-annotation-queue-by-key - https://docs.langchain.com/langsmith/smith-api/annotation-queues/create-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation-queues/create-identity-annotation-queue-run-status - https://docs.langchain.com/langsmith/smith-api/annotation-queues/delete-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation-queues/delete-annotation-queues - https://docs.langchain.com/langsmith/smith-api/annotation-queues/delete-run-from-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation-queues/delete-runs-from-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation-queues/export-annotation-queue-archived-runs - https://docs.langchain.com/langsmith/smith-api/annotation-queues/get-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation-queues/get-annotation-queues - https://docs.langchain.com/langsmith/smith-api/annotation-queues/get-annotation-queues-for-run - https://docs.langchain.com/langsmith/smith-api/annotation-queues/get-run-from-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation-queues/get-runs-from-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation-queues/get-size-from-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation-queues/get-total-archived-from-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation-queues/get-total-size-from-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation-queues/populate-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation-queues/resolve-annotation-queue-run - https://docs.langchain.com/langsmith/smith-api/annotation-queues/update-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation-queues/update-run-in-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation_queues/add-a-reviewer-to-an-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation_queues/add-annotation-queue-items - https://docs.langchain.com/langsmith/smith-api/annotation_queues/create-annotation-queue-item-status - https://docs.langchain.com/langsmith/smith-api/annotation_queues/delete-annotation-queue-items - https://docs.langchain.com/langsmith/smith-api/annotation_queues/get-annotation-queue-item-placement - https://docs.langchain.com/langsmith/smith-api/annotation_queues/get-the-annotation-queue-item-count - https://docs.langchain.com/langsmith/smith-api/annotation_queues/list-annotation-queue-items - https://docs.langchain.com/langsmith/smith-api/annotation_queues/remove-a-reviewer-from-an-annotation-queue - https://docs.langchain.com/langsmith/smith-api/annotation_queues/update-an-annotation-queue-item last_verified: 2026-08-11 --- # Smith API：Annotation Queue 审核调度与状态机 Annotation Queue 是把 trace/run/thread 送入人工评价的工作队列，不只是一个 ID 列表。它包含队列配置、item、reviewer、reservation、每位 reviewer 的 status、位置和归档状态。正确实现必须把“项目是否已完成全部审核”与“当前审核人是否已完成”分开。 ## 两代路由与统一概念 API 文档同时存在连字符路径 `annotation-queues` 和下划线路径 `annotation_queues`： - 连字符组主要是传统 run-centric CRUD、populate、resolve、统计和导出； - 下划线组提供新的通用 item/reviewer/status/placement 接口； - 新 item 类型覆盖 `RUN` 与 `THREAD`，一次最多 100 项； - 旧的按 key 加 run 端点要求 self-hosted LangSmith `>=0.16`。 不要依据路径拼写推断可互换。SDK 封装层应显式映射两组端点，并用契约测试锁定部署版本。 ## 队列配置 创建队列可设置： - 名称、描述、队列类型（single 或 pairwise）； - 每个 item 所需 reviewer 数，默认 1； - 是否启用 reservation，默认启用； - reservation 分钟数，最小 1； - reviewer access mode 与 reviewer 列表； - default dataset、rubric、预置 session IDs、metadata。 所需 reviewer 数决定真正完成条件。配置从 1 改为 2 时，要评估已有 item 的状态如何迁移；不能只改 UI。reservation 是并发租约而不是永久所有权，消费者要能处理超时、续租失败和另一 reviewer 接管。 ## 入队 传统接口支持按 run IDs 入队、按 key 入队、populate 和删除 run；新接口接受通用 items： - `RUN`：需要 `run_id`，或可使用 suggested example 相关信息； - `THREAD`：需要 thread/project 上下文； - 一批最多 100； - reviewer 的 add/remove 是幂等操作。 入队服务应使用业务幂等键，防止网络重试重复产生 item。先验证所有资源属于同一 workspace；对部分失败响应逐项落账，不把 HTTP 2xx 简化成“全部成功”。 ## 状态机 可以把每位 reviewer 的工作理解为： ```text 可见/未领取 -> 已预约 -> 审核中 -> 已提交状态 \-> 租约过期 -> 可重新领取 ``` item 的全局归档发生在所有审核要求满足后。`archived` 并不等于“当前 reviewer 已完成”，反过来也一样。identity status 端点和通用 item status 端点记录的是 reviewer 维度；给 status 传 `null` 会让该 item 对此 reviewer 重新出现，这是明确的重开语义，不应被当成无操作。 resolve/run update 是业务状态改变，调用方要携带当前版本/placement 信息并在 409 或排序变化时重新读取，避免陈旧页面覆盖他人结果。 ## 读取、排序与游标 队列读取覆盖： - 按 ID 获取队列、列出队列、查某 run 所在队列； - 获取单个 run/item； - 按状态、reviewer 等条件分页列 items； - placement 解析 item 所处 section/position； - active、archived、total size 与分桶 count； - archived runs 导出。 新 item 列表支持前向/后向 cursor，单页最大 100。返回的列表对象偏 metadata，详细 trace 内容可能需另行读取。位置在并发插入、删除、归档后会变化，不能当稳定主键；稳定引用必须用 item ID。 ## 删除与部分成功 队列、runs 和 items 都有单/批量删除。批量队列删除最多 100 个，并明确支持 200 全成功或 207 部分成功。批量 run 删除请求可表达： - `delete_all`； - 精确 `run_ids`； - `exclude_run_ids`。 `delete_all + exclude` 是高风险组合。服务端调用前应展示解析后的数量并要求高权限确认；审计中保存过滤条件、排除集合和逐项结果。删除 item 不等于删除原始 trace/run，也不自动撤销已经写出的 feedback。 ## Reviewer 生命周期 添加/移除 reviewer 是幂等的，但移除 reviewer 前要判断： - 已完成审核是否保留； - 其 reservation 是否释放； - 每 item 所需人数是否仍可满足； - 未完成 items 是否需要重新分配。 最小权限应让 reviewer 只能读其被授权队列和必要 trace 数据；队列管理员、审核人和数据集管理员不应默认合并为一个角色。 ## 典型消费循环 1. 以 reviewer identity 列出可处理 item。 2. 领取或确认 reservation，并记录到期时间。 3. 按 item 类型读取 RUN/THREAD 所需最小数据。 4. 写 feedback/rubric 结果。 5. 更新 reviewer status。 6. 再读 item，确认是否达到全局 archived 条件。 7. 游标前进；若页面变动则从服务返回 cursor 恢复。 状态写入和 feedback 写入可能不是同一事务。客户端需要可重复提交的幂等键与补偿扫描，避免“有反馈但状态未完成”或“状态完成但反馈缺失”。 ## 运营指标 至少监控：待审核数、已预约数、超时租约、按 reviewer 吞吐、归档率、重开率、队列等待时长、207 部分失败数和孤儿 feedback。`size`、`total size`、`archived total` 含义不同，仪表盘要标出统计口径。 ## 安全清单 - 人工页面把 trace 内容视为不可信输入，禁止渲染可执行 HTML/链接。 - reviewer 不能因拿到 item ID 越权读取其他 workspace 的 run。 - 导出 archived runs 前做 PII/秘密扫描并限制下载寿命。 - reservation 超时使用服务端时间；不要依赖浏览器本地时钟。 - 自动 populate 要有速率、成本与采样上限，防止一次查询灌满队列。 Evaluator 和实验自动评分见 [[04-Evaluator实验视图优化与Playground配置]]；人工结果回写的 feedback/traces 端点在 Smith API Traces 专题中展开。