---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - feedback
  - security
topic: LangSmith Smith API Feedback 数据模型、公开 Token 与 Trace 保留
sources:
  - https://docs.langchain.com/langsmith/smith-api/feedback/create-feedback
  - https://docs.langchain.com/langsmith/smith-api/feedback/create-feedback-ingest-token
  - https://docs.langchain.com/langsmith/smith-api/feedback/create-feedback-with-token-get
  - https://docs.langchain.com/langsmith/smith-api/feedback/create-feedback-with-token-post
  - https://docs.langchain.com/langsmith/smith-api/feedback/delete-feedback
  - https://docs.langchain.com/langsmith/smith-api/feedback/eagerly-create-feedback
  - https://docs.langchain.com/langsmith/smith-api/feedback/list-feedback-ingest-tokens
  - https://docs.langchain.com/langsmith/smith-api/feedback/read-feedback
  - https://docs.langchain.com/langsmith/smith-api/feedback/read-feedbacks
  - https://docs.langchain.com/langsmith/smith-api/feedback/update-feedback
last_verified: 2026-08-11
---

# Feedback 数据模型、公开 Token 与保留

Feedback 将人工、应用、模型或自动评估结果关联到 Run/Trace/Project/Thread。它不只是一个分数，还可含结构化 value、评论、correction、比较实验和来源证据。

## CRUD 和查询

| 能力 | 方法与路径 |
|---|---|
| 创建 | `POST /api/v1/feedback` |
| 旧 eager 创建 | `POST /api/v1/feedback/eager`（deprecated） |
| 读单个 / 列表 | `GET /api/v1/feedback/{feedback_id}` / `GET /api/v1/feedback` |
| 更新 / 删除 | `PATCH` / `DELETE /api/v1/feedback/{feedback_id}` |
| 为 Run 列 token | `GET /api/v1/feedback/tokens?run_id=...` |

创建必填 `key`。页面描述明确 `session_id` 必填，但当前 JSON Schema 只把 `key` 标为 required、将 `session_id` 建模为 nullable；生产 client 应按更严格的文档语义要求 project/session ID，不依赖服务端宽松序列化。

其他字段：`score` 可为 number/integer/boolean，`value` 还可为 string/object；可带 comment、correction、run/trace/start time、feedback group/thread、comparative experiment、自定义 ID、source 与 config。source 类型包括 `api|model|app|auto_eval`，应从已认证调用上下文生成，不相信客户端伪造的 user/source metadata。

列表默认 `limit=100, offset=0`，可按 run、key、session、source、user、有无 comment/score、level(`run|session`)、创建时间、feedback thread 和比较实验筛选。`include_user_names` 会增加身份数据，只在有显式权限的人工审核界面开启。

## 公开 Feedback Ingest Token

`POST /api/v1/feedback/tokens` 可一次创建一个或数组 token，每项必填 `run_id` 和 `feedback_key`，可用 `expires_in` 或 `expires_at` 限时，返回 `id/url/expires_at/feedback_key`。

持 token 者可无额外认证提交：

- `GET /api/v1/feedback/tokens/{token}`：score/value/comment/correction 都在 query string；
- `POST /api/v1/feedback/tokens/{token}`：JSON body，还可带 metadata。

POST 应作为默认；GET 会把用户反馈和 token 暴露到浏览器历史、代理/CDN/服务器日志、Referer 和分析系统。对公开页设 `Referrer-Policy: no-referrer`，不加第三方脚本，访问日志脱敏 path，限流、限 body 和防自动滥用。

文档没有承诺 token 一次性；不能把“成功提交一次”当作已撤销。使用短 TTL，将 token 绑定单一 run + key，由业务端以稳定 feedback ID/去重规则防重放；管理端只显示元数据，不回显完整 token URL。

## Trace 保留的隐性成本

创建和 token 提交的 `extend_trace_retention` 默认 **true**。收集大量用户反馈会延长 Trace 保留，同时改变存储成本、数据删除 SLA 和合规范围。产品必须在创建 token 时明确这一决策，不依赖默认值，并将保留政策与用户同意/删除请求联动。

## 更新、删除和迁移

PATCH 只能修改 score/value/comment/correction/config，不应用它变更 Feedback 归属。并发审核应保存最后读时间/版本并防止后写覆盖；OpenAPI 没有 ETag/条件更新，需由业务层协调。删除前保存不含评论正文的审计信息，并重算相关聚合/规则结果。

`/feedback/eager` 已 deprecated，它假设 Run 已在数据库可见；新集成统一使用 `POST /feedback`，老 client 迁移时要验证 ingest 最终一致延迟和重试去重。