---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - evaluator
  - prompt-optimization
topic: LangSmith Smith API Evaluator、实验视图、Prompt 优化与 Playground 配置
sources:
  - https://docs.langchain.com/langsmith/smith-api/evaluators/bulk-delete-evaluators
  - https://docs.langchain.com/langsmith/smith-api/evaluators/create-evaluator
  - https://docs.langchain.com/langsmith/smith-api/evaluators/delete-evaluator
  - https://docs.langchain.com/langsmith/smith-api/evaluators/get-evaluator
  - https://docs.langchain.com/langsmith/smith-api/evaluators/get-evaluator-spend
  - https://docs.langchain.com/langsmith/smith-api/evaluators/list-evaluators
  - https://docs.langchain.com/langsmith/smith-api/evaluators/update-evaluator
  - https://docs.langchain.com/langsmith/smith-api/experiment-view-overrides/create-new-experiment-view-override-configuration-for-a-dataset
  - https://docs.langchain.com/langsmith/smith-api/experiment-view-overrides/delete-experiment-view-override-configuration
  - https://docs.langchain.com/langsmith/smith-api/experiment-view-overrides/get-experiment-view-override-configuration-by-specific-id
  - https://docs.langchain.com/langsmith/smith-api/experiment-view-overrides/get-experiment-view-override-configurations-for-a-dataset
  - https://docs.langchain.com/langsmith/smith-api/experiment-view-overrides/update-existing-experiment-view-override-configuration
  - https://docs.langchain.com/langsmith/smith-api/experiments/evaluate-experiment-adhoc
  - https://docs.langchain.com/langsmith/smith-api/optimization-jobs/create-job
  - https://docs.langchain.com/langsmith/smith-api/optimization-jobs/create-log
  - https://docs.langchain.com/langsmith/smith-api/optimization-jobs/delete-job
  - https://docs.langchain.com/langsmith/smith-api/optimization-jobs/delete-log
  - https://docs.langchain.com/langsmith/smith-api/optimization-jobs/get-job
  - https://docs.langchain.com/langsmith/smith-api/optimization-jobs/get-log
  - https://docs.langchain.com/langsmith/smith-api/optimization-jobs/list-job-logs
  - https://docs.langchain.com/langsmith/smith-api/optimization-jobs/list-jobs
  - https://docs.langchain.com/langsmith/smith-api/optimization-jobs/update-job
  - https://docs.langchain.com/langsmith/smith-api/playground-settings/create-playground-settings
  - https://docs.langchain.com/langsmith/smith-api/playground-settings/delete-playground-settings
  - https://docs.langchain.com/langsmith/smith-api/playground-settings/get-playground-settings
  - https://docs.langchain.com/langsmith/smith-api/playground-settings/list-playground-settings
  - https://docs.langchain.com/langsmith/smith-api/playground-settings/update-playground-settings
last_verified: 2026-08-11
---

# Smith API：Evaluator、实验视图、Prompt 优化与 Playground 配置

这组 API 覆盖四个层面：定义自动 evaluator、触发实验评估、配置实验 UI、管理 prompt 优化作业与模型连接设置。它们共享同一评估链路，但生命周期和权限边界不同，不能合成一个“评估配置”对象。

## Evaluator 资源

平台 evaluator 支持 LLM 和 code 两类。创建请求包含统一的 `name/type`，再携带对应的 `llm_evaluator` 或 `code_evaluator` 配置。响应会包含 feedback keys、creator、run rules、子配置、租户与时间戳；`is_managed` 标识 LangChain 管理的 evaluator，目前文档举例为 Perceived Error judge。

列表可按 type、名称/creator 子串、tag value、feedback key 和 resource ID 过滤，offset/limit 最大 100，并支持排序。读取单个 evaluator 会内嵌 run rules，因此删除前应先判断依赖。

删除有两种策略：

- 默认删除若仍被 run rule 引用，可能返回 409；
- `delete_run_rules=true` 先删除同租户的全部引用规则，再删 evaluator。

后者是级联破坏性操作，应先列出关联规则并要求明确确认。批量删除返回 succeeded/failed 每项结果，不可只判断顶层 200。

更新可以修改 name 以及 LLM/code 配置。类型切换是否允许、嵌套配置是 patch 还是 replacement，文档未给足语义；客户端应保留 read-modify-write 契约测试，禁止发送与 type 不匹配的两个子对象。

## 成本查询

spend 接口返回指定 7 天窗口内按天的 LLM evaluator 成本。`period_start` 必填，而且以下四者必须恰好一个：

- `group_by`；
- `evaluator_id`；
- `session_id`；
- `dataset_id`。

`group_by` 可选 evaluator、resource 或 run_rule；只有 group 模式才允许 resource ID、type、feedback key 等进一步过滤。成本告警应基于服务端日期边界，避免把本地时区自然周误当 API 的固定 7 天窗口。

## 触发一次性实验评估

`POST /runs/experiments/{experiment_id}/evaluate` 用 `rule_id` 对既有 experiment 立即执行评估，并按批处理 runs。它是异步成本/吞吐风险入口：

- 先固定 experiment 和 evaluator/rule 版本；
- 对大 experiment 设置并发与预算；
- 防止用户重复点击造成重复评分；
- 以 run/evaluation 状态追踪完成，不以 HTTP 200 当全部评估完成。

## 实验视图覆盖

每个 Dataset 可配置 experiment view 的列显示。列名必须以前缀之一开头：`inputs`、`outputs`、`reference_outputs`、`feedback`、`metrics`、`attachments`、`metadata`。每项可设置：

- 数值颜色梯度；
- 1 到 6 位小数精度；
- hide 可见性。

一次配置 1–50 个 column overrides；同 Dataset 已存在时 create 返回 409。PATCH 是**完整替换**全部列配置，不是逐列合并。因此 UI 保存时必须带上完整期望状态；多个管理员并发编辑需要 ETag/版本或客户端冲突检查。DELETE 永久移除配置并恢复默认显示，但不删除实验数据。

视图颜色只是展示，不改变 metric 数值。颜色梯度要考虑色盲、空值、异常值和反向指标，不能让红绿视觉成为唯一质量判断。

## Prompt 优化作业

Optimization Job 挂在 prompt repo 下，包含 algorithm、Promptim/Demo config、status、results 和 timestamps。API 覆盖创建、列表、读取、更新、删除，以及 job log 的创建/列表/读取/删除。

更新只接受 status 和一个 result，文档称“replace existing job”，调用方不能假设是 append；多 worker 写结果时需要唯一 job owner 或乐观并发。日志包含 type、message 和任意 data，可能泄露 prompt、example 或模型响应，必须在写入前做 secrets/PII 过滤。

路径模板带 `{owner}/{repo}`，但部分自动生成页面的 parameter 表没有列出 owner，或只列 repo/job ID。这是 OpenAPI 文档映射不一致，不代表 owner 可省略；应以实际路径参数和当前 SDK 为准。

删除 job/log 是不可逆控制面操作。状态机至少应限制 terminal job 被重新标为 running，并让取消、失败、成功都可审计。

## Playground Settings

Settings 可以是 `complex` 或 `simple`，scope 是 workspace 或 organization；响应还控制配置是否出现在 playground、evaluators、agent builder、Polly 与 insights 等产品入口。

配置可含 OAuth：token URL、client ID、client secret、token endpoint auth method、params 和 headers。这里的 `oauth_client_secret` 是高敏感字段：

- 不应写入 Obsidian、普通日志、前端状态或错误报告；
- API 响应即使包含字段，也不能默认会遮罩；
- organization scope 会扩大爆炸半径，需单独审批；
- token URL 必须做 SSRF allowlist、TLS 与 DNS 重绑定防护；
- 更新时避免空字符串覆盖已有 secret。

`settings` 本身是自由对象，创建前用 provider-specific schema 校验。可用范围的 flags 应从默认拒绝开始，再按功能开启；删除前检查是否仍被 evaluator/agent builder 使用。

## 推荐的资源边界

| 资源 | 版本/审计重点 | 主要风险 |
|---|---|---|
| Evaluator | 配置、feedback key、run rules | 级联删除、模型成本、代码执行 |
| Experiment evaluation | experiment + rule 快照 | 重复运行、批量成本 |
| View override | Dataset 级完整 replacement | 并发覆盖、误导性可视化 |
| Optimization job | 状态、结果、日志 | 多 worker 竞态、敏感日志 |
| Playground settings | scope、provider/OAuth 配置 | secret 泄露、SSRF、过宽可用范围 |

## 上线检查

- evaluator 先在小 Dataset 做 golden test，再挂 run rule。
- 为 LLM evaluator 设置每日成本阈值和失败降级；code evaluator 必须沙箱化。
- 一次性 experiment 评估带幂等键和明确预算。
- 视图 PATCH 先 GET 合并并检测并发版本。
- optimization job 只允许受控 worker 更新状态/日志。
- Playground OAuth secret 进入专用 secret store，任何 GET 响应都做脱敏测试。

Dataset 固定版本的原因见 [[01-Dataset版本实验共享与导入导出]]；Prompt repo、commit 和 webhook 见 [[05-Prompt-Hub版本Webhook与公开分享边界]]。