---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: private
status: active
tags:
  - study
  - langsmith
  - annotation
  - feedback
  - security
topic: LangSmith Annotation Queues、Assertions、Feedback SDK 与预签名令牌安全
sources:
  - https://docs.langchain.com/langsmith/annotation-queues
  - https://docs.langchain.com/langsmith/annotation-queues-sdk
  - https://docs.langchain.com/langsmith/assertions
  - https://docs.langchain.com/langsmith/set-up-feedback-criteria
  - https://docs.langchain.com/langsmith/annotate-traces-inline
  - https://docs.langchain.com/langsmith/attach-user-feedback
  - https://docs.langchain.com/langsmith/presigned-feedback-tokens
last_verified: 2026-08-11
---
# 人工标注、Assertions 与反馈安全

## 两种 Queue

### Single-run queue

一次呈现一个 run 或完整 thread，并按固定 rubric 收集反馈。Run 与 thread 能力不同：

| 能力 | Run item | Thread item |
|---|---:|---:|
| Rubric feedback | 是 | 是 |
| Reviewer notes | 是 | 否 |
| Assertions | 是 | 否 |
| 导出到 Dataset | 是 | 否 |
| Default dataset | 是 | 否 |
| Automation rule | 是 | 否 |

Thread item 依赖 trace 中正确设置 thread_id/session_id。Automation rule 只能入队 runs，不能自动入队整个 thread。单次手工操作最多加入 100 个 runs/threads，更多必须分批。

### Pairwise annotation queue

PAQ 必须从同一 dataset 中**恰好两个** experiments 创建，系统按顺序配对 runs。Reviewer 对每项 rubric 选择 A 更好、B 更好或 Equal，系统在两个 runs 上写二元 feedback。它不支持 thread、default dataset 或 assertions。

向既有 PAQ 追加比较会保留历史并增加新 pairs。配对依赖两边 example/run 对齐，使用前要核对缺失、重复和顺序，不能仅凭 UI 已成对就假设业务样本一致。

## Reviewer 协作语义

- Reservation 在指定时间内锁定 item，其他人可看但不能写；超时释放。Requeue 只改变当前用户队列顺序并释放其 reservation。
- “每项 reviewer 数量”达到阈值后完成；reviewer 看不到其他 reviewer 的 feedback，但 comments 对所有人可见。
- Assigned reviewers 模式要求所有指定成员提交，状态为 Needs Review → Needs Others’ Review → Completed。非指定成员可写，但不计完成。
- 给已有 completed queue 新增 assigned reviewer 不会让历史项重新变 pending；删除 reviewer 会重算其未审项目。
- 删除 queue item 会对所有用户生效，不受 reservation 保护，属于需要权限与审计的操作。

要衡量人工标签质量，应把 reviewer ID、rubric 版本、时间、冲突率与裁决结果一起保存。仅以“Completed”判断标签可信度不够。

## 三层 Feedback 架构

1. **Feedback config**：组织级 schema，定义 key 与 continuous/categorical/freeform 类型。
2. **Queue rubric item**：把 config 挂到具体 queue，增加说明、取值解释和 required 属性。
3. **Feedback**：reviewer 对具体 run 提交的 score/value/comment。

Continuous 可设置 min/max 和可选锚点，要求 min 小于 max；Categorical 至少两个唯一 label/value，不能设置 min/max；Freeform 不设范围或 categories。

create feedback config 对完全相同配置是幂等的；同 key 但不同 schema 返回 400。删除是 soft delete，同 key 未来可重建。update queue 的 rubric_items 会**整表替换**，遗漏项会被移除，所以必须先 read、合并、校验再 update。

Feedback key 一旦进入报表和 evaluator 就是数据契约。改分值方向、category value 或量纲会破坏历史可比性，应新建版本化 key 或做明确迁移。

## Rubric 与 Assertions 的分工

Rubric 是跨全部 queue items 的固定评分维度；Assertion 是 reviewer 针对某个 run 写的一句自由文本验收条件。

Assertion 只存在于 UI 的 single-run run item。只要添加至少一条 assertion：

- Dataset example 的 outputs 会切换为 assertions JSON；
- 当前错误 run 的实际输出不会保存为 reference；
- reviewer 仍可编辑 inputs；
- key 中 must_ / must_not_ 只是命名习惯，没有特殊执行语义。

离线 evaluator 从 reference_outputs.assertions 逐项评分，可以混合：

- 主观 claim 用 LLM judge；
- regex、schema、substring 等用 Code；
- 不完全满足时返回 0–1 partial credit。

Assertion 本身也可能含糊或互相冲突。保存前应要求单一、可判定、无实现细节泄漏，必要时让第二 reviewer 审核。不要把自由文本 assertion 当自动执行的安全 policy。

## Inline 与 SDK Feedback

UI 可给 root 或任何 intermediate run 添加 workspace feedback tag 和 comment；SDK 的 create feedback 同样可针对 child run。Python 传 trace_id 时可后台批量写入，适合低延迟路径；仍应监控异步失败，不能以 HTTP 响应快就假设 feedback 已持久化。

Python 与 TypeScript 示例都需要正确的 session/project ID。Feedback 应关联稳定 run ID、trace ID、key 和 schema；重复点击或客户端重试应通过 source/idempotency 策略去重。

普通 inline feedback、queue notes 和手工入队默认不改变 trace retention tier。这个边界与预签名 URL 不同。

## Presigned Feedback URL 是 Bearer 能力令牌

预签名 URL 绑定一个 run 与 feedback key，客户端无需 API key 即可提交。默认有效期 3 小时，可设置相对或绝对过期；Python 支持一次为多个 keys 批量创建，TypeScript 没有文档中的批量入口。

可用 feedback config 限制分数范围或 category。POST 支持 score、value、comment、correction、metadata；GET 不支持 metadata。

重要语义：

- 任何持有 URL 的人都能在有效期内写反馈，应把 URL 当敏感 bearer token。
- Presigned URL 提交反馈会把 base-retention trace 自动升级到 extended retention，且没有 opt-out；这会增加保存时间和费用。
- GET 会产生写操作。邮件安全扫描器、聊天预览、浏览器预取或重复点击都可能误提交，这是基于 HTTP 客户端行为的生产风险。
- 文档没有给出本页内的显式撤销流程，因而设计时不应依赖“泄漏后随时撤回”。

生产控制：

1. 只在后端生成，使用最短有效期和单一 feedback key。
2. 不写日志、analytics、Referer、异常消息或公开 URL；页面禁止第三方脚本读取。
3. 浏览器交互优先 POST，并在业务侧做一次性 UI、防重复、速率限制和异常检测。
4. 用 feedback config 强校验范围，comment/metadata 仍按不可信输入转义和限长。
5. 高价值反馈通过已认证后端代理，记录真实 user/session 与授权，而不是完全依赖匿名 token。
6. 监控 retention 自动升级和异常 feedback 激增。

## 数据与权限边界

Annotation queue 常直接暴露生产 prompt、tool result、用户对话和 metadata。创建 queue 前要：

- 用最小 workspace 角色和 assigned reviewers；
- 对输入输出脱敏，避免 reviewer comment 再次复制敏感值；
- 对跨地区/外包 reviewer 做数据驻留与协议审查；
- 限制 default dataset 的访问，防止标注后数据扩大传播；
- 自定义 output renderer 按受信应用治理，不执行不可信 HTML；
- 将 rubric/config/assigned reviewer 变更写入审计。

## 人工反馈闭环

生产 trace 或离线 experiment → 过滤与抽样 → Single-run/Pairwise Queue → 多 reviewer 标注与裁决 → Dataset/Assertions/Corrections → 离线 evaluator 与发布门 → 新一轮生产观察。

闭环有效的前提是：采样代表真实风险、rubric 版本稳定、reviewer 一致性可测、敏感数据受控，并且人工纠正真正回流到 dataset/evaluator，而不是只停在 UI comment。