通过编程方式管理反馈与标注队列

使用 LangSmith SDK 以编程方式管理反馈配置和标注队列评分标准。在组织级别定义可复用的反馈模式（例如准确度评分或通过/失败判断），然后将它们分配给特定队列并附带自定义说明。这支持版本控制、跨项目自动化以及一致性——特别适用于 CI/CD 管道或跨环境复制评估设置。

本指南使用 Python 和 TypeScript SDK。有关安装和设置，请参阅 Python SDK 文档和 TypeScript SDK 文档。

反馈层级

LangSmith 使用三层架构来构建结构化的人工反馈：

反馈配置：组织范围内的反馈键定义，用于建立评估指标的模式。例如，您可以将“准确度”定义为 0–1 的连续分数，或将“正确性”定义为通过/失败的分类选择。这些配置可在您组织的所有标注队列中复用。
标注队列评分项：特定于队列的分配，决定标注员在审查特定队列中的运行时必须填写哪些反馈配置。每个评分项可以包含自定义描述、针对特定分数值的指导，以及反馈是必填还是可选。
反馈：标注员在特定运行上提交的个别分数和值。这是使用您定义的模式收集的实际评估数据。了解更多关于 LangSmith 中的反馈。

反馈配置

创建反馈配置

反馈配置定义了反馈键的模式——无论是连续分数、分类选择还是自由文本。每个配置在您的组织内由一个唯一键标识，并指定标注员如何为该指标提交反馈。

使用 create_feedback_config 调用一个与已存在配置完全相同的配置时，会返回现有配置。如果同一键已存在不同的配置，系统将引发 400 错误。

from langsmith import Client

client = Client()

# 连续分数
client.create_feedback_config(
    "accuracy",
    feedback_config={
        "type": "continuous",
        "min": 0,
        "max": 1,
    },
    is_lower_score_better=False,
)

# 分类
client.create_feedback_config(
    "correctness",
    feedback_config={
        "type": "categorical",
        "categories": [
            {"value": 1, "label": "通过"},
            {"value": 0, "label": "失败"},
        ],
    },
)

# 自由文本
client.create_feedback_config(
    "notes",
    feedback_config={"type": "freeform"},
)

import { Client } from "langsmith";

const client = new Client();

// 连续分数
await client.createFeedbackConfig({
  feedbackKey: "accuracy",
  feedbackConfig: { type: "continuous", min: 0, max: 1 },
  isLowerScoreBetter: false,
});

// 分类
await client.createFeedbackConfig({
  feedbackKey: "correctness",
  feedbackConfig: {
    type: "categorical",
    categories: [
      { value: 1, label: "通过" },
      { value: 0, label: "失败" },
    ],
  },
});

// 自由文本
await client.createFeedbackConfig({
  feedbackKey: "notes",
  feedbackConfig: { type: "freeform" },
});

连续型 ("accuracy")：定义从 0 到 1 的数字刻度。is_lower_score_better 参数指示较低的值是否代表更好的性能。使用连续配置进行评分量表或基于百分比的指标。
分类型 ("correctness")：提供带有相关值的预定义选项。每个类别需要一个 value（用于评分和分析）和一个 label（显示给标注员）。使用分类配置进行二元选择或多类分类。
自由文本型 ("notes")：允许开放式文本输入，无预定义结构。使用自由文本配置进行定性观察或解释。

列出反馈配置

使用 list_feedback_configs 检索反馈配置，以查看您的组织中有哪些评估标准可用。您可以列出所有配置或按特定键进行筛选。每个返回的配置对象包括键、类型、配置详情（如 min/max 或 categories）以及元数据（如 is_lower_score_better）：

# 列出所有配置
for config in client.list_feedback_configs():
    print(f"{config.feedback_key}: {config.feedback_config}")

# 按特定键筛选
for config in client.list_feedback_configs(
    feedback_key=["accuracy", "correctness"]
):
    print(config.feedback_key)

// 列出所有配置
for await (const config of client.listFeedbackConfigs()) {
  console.log(`${config.feedback_key}: ${JSON.stringify(config.feedback_config)}`);
}

// 按特定键筛选
for await (const config of client.listFeedbackConfigs({
  feedbackKeys: ["accuracy", "correctness"],
})) {
  console.log(config.feedback_key);
}

更新反馈配置

使用 update_feedback_config 通过更新特定字段来修改现有的反馈配置。此方法仅更改您提供的字段——其余字段保持不变。这是一种部分更新，会保留其他配置设置：

client.update_feedback_config(
    "accuracy",
    is_lower_score_better=True,
)

await client.updateFeedbackConfig("accuracy", {
  isLowerScoreBetter: true,
});

删除反馈配置

使用 delete_feedback_config 从您的组织中移除反馈配置。这将执行软删除，将配置标记为已删除，但不会将其从系统中永久移除。如果需要，您可以稍后使用相同的键重新创建配置：

client.delete_feedback_config("accuracy")

await client.deleteFeedbackConfig("accuracy");

标注队列评分项

评分项将反馈配置分配给特定的标注队列。它们控制标注员在审查该队列中的运行时看到哪些反馈表单，以及每个表单是必填还是可选。

创建带有评分项的队列

使用 create_annotation_queue 创建标注队列，并通过评分项将反馈配置分配给它。每个评分项通过其键引用一个反馈配置，并自定义其在此特定队列中向标注员显示的方式。此示例创建一个包含三个评分项的队列。队列级别的 rubric_instructions 提供显示在标注界面顶部的通用指导：

queue = client.create_annotation_queue(
    name="QA 审查队列",
    description="审查 LLM 输出的准确性和正确性",
    rubric_instructions="为每个回复评分。为任何异常情况添加备注。",
    rubric_items=[
        {
            "feedback_key": "accuracy",
            "description": "回复的准确度如何？",
            "score_descriptions": {
                "0": "完全错误",
                "1": "完全准确",
            },
            "is_required": True,
        },
        {
            "feedback_key": "correctness",
            "description": "回复是通过还是失败？",
            "value_descriptions": {
                "通过": "事实正确",
                "失败": "包含错误",
            },
            "is_required": True,
        },
        {
            "feedback_key": "notes",
            "description": "任何其他观察",
            "is_required": False,
        },
    ],
)

const queue = await client.createAnnotationQueue({
  name: "QA 审查队列",
  description: "审查 LLM 输出的准确性和正确性",
  rubricInstructions: "为每个回复评分。为任何异常情况添加备注。",
  rubricItems: [
    {
      feedback_key: "accuracy",
      description: "回复的准确度如何？",
      score_descriptions: { "0": "完全错误", "1": "完全准确" },
      is_required: true,
    },
    {
      feedback_key: "correctness",
      description: "回复是通过还是失败？",
      value_descriptions: { "通过": "事实正确", "失败": "包含错误" },
      is_required: true,
    },
    {
      feedback_key: "notes",
      description: "任何其他观察",
      is_required: false,
    },
  ],
});

feedback_key：现有反馈配置的键（请先创建此配置）。
description：队列特定的指导，告知标注员关于此指标的信息。
score_descriptions / value_descriptions：可选标签，解释特定值的含义（连续配置使用 score_descriptions，分类配置使用 value_descriptions）。
is_required：标注员在提交前是否必须完成此反馈。

更新现有队列上的评分项

使用 update_annotation_queue 修改分配给标注队列的评分项。此操作会替换整个评分项列表，因此您必须包含所有要保留的项目——操作会移除您未包含的任何项目。您需要队列 ID，可以在创建队列时或通过列出队列获得：

更新评分项会替换完整列表。请包含所有要保留的项目。

client.update_annotation_queue(
    queue.id,
    rubric_items=[
        {"feedback_key": "accuracy", "is_required": True},
        {"feedback_key": "correctness", "is_required": True},
        {
            "feedback_key": "tone",
            "description": "语气是否合适？",
            "is_required": False,
        },
    ],
)

await client.updateAnnotationQueue(queue.id, {
  rubricItems: [
    { feedback_key: "accuracy", is_required: true },
    { feedback_key: "correctness", is_required: true },
    { feedback_key: "tone", description: "语气是否合适？", is_required: false },
  ],
});

反馈配置类型（详细）

连续型

连续配置定义带有最小值和最大值的数字评分量表。标注员可以选择范围内的任何值，这非常适合在数字量表上对准确度、质量或相关性等维度进行评分：

# 简单的连续分数
client.create_feedback_config(
    "accuracy",
    feedback_config={
        "type": "continuous",
        "min": 0,
        "max": 1,
    },
)

# 在量表上带有标签点的连续分数
client.create_feedback_config(
    "quality",
    feedback_config={
        "type": "continuous",
        "min": 1,
        "max": 5,
        "categories": [
            {"value": 1, "label": "差"},
            {"value": 3, "label": "一般"},
            {"value": 5, "label": "优秀"},
        ],
    },
)

await client.createFeedbackConfig({
  feedbackKey: "accuracy",
  feedbackConfig: { type: "continuous", min: 0, max: 1 },
});

await client.createFeedbackConfig({
  feedbackKey: "quality",
  feedbackConfig: {
    type: "continuous",
    min: 1,
    max: 5,
    categories: [
      { value: 1, label: "差" },
      { value: 3, label: "一般" },
      { value: 5, label: "优秀" },
    ],
  },
});

第一个示例显示了一个没有标签的 0–1 量表。第二个示例演示了在量表上添加带有标签锚点（如“差”、“一般”、“优秀”）的 categories，以帮助标注员理解不同值的含义。这些标签是可选的，但可以提高标注员解释量表的一致性。

分类型

分类配置为标注员提供一组离散的预定义选项。每个类别必须有一个 value（用于评分和分析的数字标识符）和一个 label（显示给标注员的文本）。您必须定义至少 2 个类别。使用分类配置进行二元决策（通过/失败、正确/错误）、多类分类（情感、主题类别）或任何具有固定离散选项集的评估。不要为分类配置设置 min 或 max：

# 二元通过/失败
client.create_feedback_config(
    "correctness",
    feedback_config={
        "type": "categorical",
        "categories": [
            {"value": 1, "label": "通过"},
            {"value": 0, "label": "失败"},
        ],
    },
)

# 多类
client.create_feedback_config(
    "sentiment",
    feedback_config={
        "type": "categorical",
        "categories": [
            {"value": 0, "label": "负面"},
            {"value": 1, "label": "中性"},
            {"value": 2, "label": "正面"},
        ],
    },
)

await client.createFeedbackConfig({
  feedbackKey: "correctness",
  feedbackConfig: {
    type: "categorical",
    categories: [
      { value: 1, label: "通过" },
      { value: 0, label: "失败" },
    ],
  },
});

await client.createFeedbackConfig({
  feedbackKey: "sentiment",
  feedbackConfig: {
    type: "categorical",
    categories: [
      { value: 0, label: "负面" },
      { value: 1, label: "中性" },
      { value: 2, label: "正面" },
    ],
  },
});

第一个示例显示了一个二元通过/失败配置。第二个示例演示了一个具有三个选项的情感多类配置。数字值允许您即使对分类反馈也能计算汇总分数。

自由文本型

自由文本配置允许标注员提供开放式文本反馈，无需任何预定义结构或约束。此类型没有 min、max 或 categories 字段——标注员可以输入任何他们想要的文本。自由文本反馈对于捕捉细微洞察很有价值，但与结构化反馈类型相比，更难汇总和分析：

client.create_feedback_config(
    "notes",
    feedback_config={"type": "freeform"},
)

await client.createFeedbackConfig({
  feedbackKey: "notes",
  feedbackConfig: { type: "freeform" },
});

验证规则

类型	min/max	categories	约束
`continuous`	可选	可选（带标签的量表点）	`min < max`；类别值在 [`min`, `max`] 范围内
`categorical`	不得设置	必需，至少 2 个	值和标签唯一
`freeform`	不得设置	不得设置	不适用

参考

反馈配置类型

类型	字段	描述
`continuous`	`min`, `max`	范围内的数字分数
`categorical`	categories (`{value, label}` 列表)	从预定义选项中选择
`freeform`	无	自由文本输入

评分项字段

字段	类型	描述
`feedback_key`	`string`	必需。必须与现有反馈配置键匹配。
`description`	`string`	向标注员显示此项的指导。
`score_descriptions`	`Record<string, string>`	特定分数值的标签（连续型）。
`value_descriptions`	`Record<string, string>`	特定类别值的标签（分类型）。
`is_required`	`boolean`	标注员在提交前是否必须完成此项。默认为 false。

将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交问题。

Datasets

Set up evaluations

Analyze experiment results

Annotation & human feedback

Common data types

通过编程方式管理反馈与标注队列

反馈层级

反馈配置

创建反馈配置

列出反馈配置

更新反馈配置

删除反馈配置

标注队列评分项

创建带有评分项的队列

更新现有队列上的评分项

反馈配置类型（详细）

连续型

分类型

自由文本型

验证规则

参考

反馈配置类型

评分项字段

​反馈层级

​反馈配置

​创建反馈配置

​列出反馈配置

​更新反馈配置

​删除反馈配置

​标注队列评分项

​创建带有评分项的队列

​更新现有队列上的评分项

​反馈配置类型（详细）

​连续型

​分类型

​自由文本型

​验证规则

​参考

​反馈配置类型

​评分项字段

反馈层级

反馈配置

创建反馈配置

列出反馈配置

更新反馈配置

删除反馈配置

标注队列评分项

创建带有评分项的队列

更新现有队列上的评分项

反馈配置类型（详细）

连续型

分类型

自由文本型

验证规则

参考

反馈配置类型

评分项字段