---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - feedback-config
  - migration
topic: LangSmith Smith API Feedback Config 与已废弃 Formula 迁移
sources:
  - https://docs.langchain.com/langsmith/smith-api/feedback-configs/create-feedback-config-endpoint
  - https://docs.langchain.com/langsmith/smith-api/feedback-configs/delete-feedback-config-endpoint
  - https://docs.langchain.com/langsmith/smith-api/feedback-configs/list-feedback-configs-endpoint
  - https://docs.langchain.com/langsmith/smith-api/feedback-configs/update-feedback-config-endpoint
  - https://docs.langchain.com/langsmith/smith-api/feedback/create-feedback-formula-ep
  - https://docs.langchain.com/langsmith/smith-api/feedback/delete-feedback-formula-endpoint
  - https://docs.langchain.com/langsmith/smith-api/feedback/get-feedback-formula-ep
  - https://docs.langchain.com/langsmith/smith-api/feedback/list-feedback-formula-ep
  - https://docs.langchain.com/langsmith/smith-api/feedback/update-feedback-formula-ep
last_verified: 2026-08-11
---

# Feedback Config 与 Formula 迁移

Feedback Config 为稳定 `feedback_key` 声明值类型、范围/类别和分数方向；它是数据合同，不只是 UI 展示。Formula 是旧的加权聚合 API，全组已被 composite feedback/code evaluator + Run Rules 取代。

## Feedback Config CRUD

| 操作 | 方法与路径 | 契约 |
|---|---|---|
| 创建 | `POST /api/v1/feedback-configs` | `feedback_key + feedback_config`，可带 lower-is-better |
| 列表 | `GET /api/v1/feedback-configs` | key/name、offset/limit、sort、`read_after_write` |
| 更新 | `PATCH /api/v1/feedback-configs` | 必填 key，config/方向可选 |
| 软删除 | `DELETE /api/v1/feedback-configs?feedback_key=...` | 204；同 key 以后可重建 |

`FeedbackConfig.type` 为 `continuous|categorical|freeform`。continuous 使用 min/max；categorical 使用 `categories[{value,label}]`；freeform 容许自由值。`is_lower_score_better` 决定优化/图表方向，不能在已有大量历史分数后无迁移直接翻转。

删除是软删除，已有 Feedback 保持不变，且 key 可复用。这意味着“同名新 Config”可与旧 Feedback 语义冲突；类型、范围、类别集或 score 方向发生不兼容变更时，优先新 key/version，而不是删除后同 key 重建。

`read_after_write` 默认 false，说明列表可能走最终一致读路径。管理界面保存后需读己写时显式开启，普通列表则保持默认以减少主库压力。

## Formula 旧契约

Formula 以 `feedback_key`、`aggregation_type=sum|avg` 和 `formula_parts` 建模；每个 part 是 `part_type=weighted_key`、weight 与被引用 key。创建可绑 dataset 或 session，列表用 offset/limit（默认 20）。旧 CRUD：

- `POST/GET /api/v1/feedback/formulas`；
- `GET/PUT/DELETE /api/v1/feedback/formulas/{feedback_formula_id}`。

五个端点均 deprecated。对已启用 composite-feedback v2 的 tenant，删除旧 Formula 会返回 **410 Gone**；新客户端不应将 410 当临时错误重试。

## 迁移到 code evaluator + Run Rule

1. 读出 Formula 的作用域、输出 key、sum/avg、所有输入 key/weight；
2. 固定包含 null、缺 key、异常值和精度的黄金样本，先定义缺失值语义；
3. 用 code evaluator 实现等价公式，将输出绑定到新或明确版本的 Feedback Config；
4. 创建低采样/disabled Run Rule，对同一样本双跑新旧结果；
5. 比较数值误差、缺失率、运行时、成本和回填范围，再切读路径；
6. 停写旧 Formula，保留快照/审计后再处理旧资源。

Code evaluator 执行不可信输入，要限时、限内存、禁网络/文件副作用；Rule 要有 sampling/spend limit 和日志。不将 Formula 的“算术等价”当作统计语义已等价：`avg` 的分母、null 处理、转型和精度必须用数据对照确认。