学习笔记 · Obsidian
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
- 读出 Formula 的作用域、输出 key、sum/avg、所有输入 key/weight;
- 固定包含 null、缺 key、异常值和精度的黄金样本,先定义缺失值语义;
- 用 code evaluator 实现等价公式,将输出绑定到新或明确版本的 Feedback Config;
- 创建低采样/disabled Run Rule,对同一样本双跑新旧结果;
- 比较数值误差、缺失率、运行时、成本和回填范围,再切读路径;
- 停写旧 Formula,保留快照/审计后再处理旧资源。
Code evaluator 执行不可信输入,要限时、限内存、禁网络/文件副作用;Rule 要有 sampling/spend limit 和日志。不将 Formula 的“算术等价”当作统计语义已等价:avg 的分母、null 处理、转型和精度必须用数据对照确认。