---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - insights
  - clustering
topic: LangSmith Smith API Insights Beta 聚类配置、作业与运行集
sources:
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/auto-generate-insights-job-config-beta
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/create-insights-job-beta
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/create-insights-job-config-beta
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/delete-insights-job-beta
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/delete-insights-job-config-beta
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/get-insights-job-beta
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/get-insights-job-configs-beta
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/get-insights-jobs-beta
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/get-run-cluster-from-insights-job-beta
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/get-runs-from-insights-job-beta
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/update-insights-job-beta
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/update-insights-job-config-beta
last_verified: 2026-08-11
---

# Insights Beta：聚类配置、作业与运行集

Insights 对一个 Tracing Project 的 Run 做抽样、聚类和模型摘要，产出层级 cluster、统计、关键点与代表 Trace。整组 API 都标记 **Beta**；它适合运营/研发发现模式，不应作为不可逆业务决策的唯一依据。

## 区分 Config 和 Job

Config 是可复用/可调度配置，Job 是某次实际执行。

| 对象 | 创建 / 列表 | 读取 / 更新 / 删除 |
|---|---|---|
| Config | `POST/GET /api/v1/sessions/{session_id}/insights/configs` | `PATCH/DELETE .../configs/{config_id}` |
| Job | `POST/GET /api/v1/sessions/{session_id}/insights` | `GET/PATCH/DELETE .../insights/{job_id}` |
| Auto-generate config | `POST .../insights/configs/generate` | 返回 summary prompt/name/attribute schemas |
| Cluster | — | `GET .../insights/{job_id}/clusters/{cluster_id}` |
| Job 中 Runs | — | `GET .../insights/{job_id}/runs` |

Config 创建必填 `name` 和完整 `config`，可带 description 与 `schedule_cron`。列表的 `include_prebuilts` 默认 false；预制配置的 ID 可为 UUID 或字符串，客户端不要强制全部按 UUID 解析。

## 作业输入的五个维度

`CreateRunClusteringJobRequest` 可来自 `config_id`，或内联配置：

- 时间：`start_time/end_time` 或 `last_n_hours`；
- 样本：`filter`、`sample`、分区 `partitions`；
- 聚类：`hierarchy`、`attribute_schemas`、`user_context`；
- 摘要：`summary_prompt`、name；
- 模型：provider `openai|anthropic`，可分别指定 cluster/summary model；`validate_model_secrets` 默认 true。

Auto-generate 接口必填 `user_context`，可指定同样的 provider 与两类 model，返回建议 summary prompt 和 attribute schema。模型生成配置必须经人工审查：prompt injection、PII 放大、错误属性类型和过度细分都会让结果偏离原问题。

## 作业状态与结果

创建响应只有 `id/name/status/error`，表明是异步作业。读详情可得到时间、metadata、shape、error、config ID、clusters 及 Insights report。状态在 OpenAPI 中是自由字符串而非枚举，客户端要容忍未知新状态，只将已知终态作为完成，并对 error 做脱敏。

Job 列表用 offset/limit（默认 100），可按 config 和 legacy 筛选。Job 中 Runs 也是 offset/limit，可按 `cluster_id` 和 attribute key/order 排序；不能用页内数量代替总量。Cluster 返回父 ID、level、name/description、子节点或 Run 数与 stats；层级是分析结果，不是稳定业务分类 ID。

## 调度、成本与隐私

`schedule_cron` 和 `is_scheduled` 会使聚类反复消耗模型和扫描 Run。上线前必须为时间窗、sample、并发作业数和预算设限，同时观察运行时间、输入 Run 数、token/cost、失败率和结果稳定性。

用于聚类的 inputs/outputs/metadata 会发往选定模型 provider；执行前先过数据分类、脱敏、地域和保留期门禁。不在 Config 中写 API key，仅引用 workspace 密钥管理中的 provider credential；测试密钥失败不应在响应/日志中回显密钥。

## Beta 迁移策略

持久化原始 config/job/cluster 响应与 API 版本，读取时采用宽松解析、写入时采用严格已知字段。更新 Config 前克隆并灰度新 Job，不在正在使用的调度配置上就地大改；删除 Job/Config 前导出结果和依赖关系，文档未承诺级联删除。