> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

<Callout icon="code">
  本指南使用 Python 和 TypeScript SDK。有关安装和设置，请参阅 [Python SDK 文档](https://reference.langchain.com/python/langsmith) 和 [TypeScript SDK 文档](https://reference.langchain.com/javascript/modules/langsmith.html)。
</Callout>

## 反馈层级

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

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

## 反馈配置

### 创建反馈配置

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

<Note>
  使用 [`create_feedback_config`](https://reference.langchain.com/python/langsmith/client/Client/create_feedback_config) 调用一个与已存在配置完全相同的配置时，会返回现有配置。如果同一键已存在不同的配置，系统将引发 400 错误。
</Note>

<CodeGroup>
  ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  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"},
  )
  ```

  ```typescript TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  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" },
  });
  ```
</CodeGroup>

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

### 列出反馈配置

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

<CodeGroup>
  ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # 列出所有配置
  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)
  ```

  ```typescript TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  // 列出所有配置
  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);
  }
  ```
</CodeGroup>

### 更新反馈配置

使用 [`update_feedback_config`](https://reference.langchain.com/python/langsmith/client/Client/update_feedback_config) 通过更新特定字段来修改现有的反馈配置。此方法仅更改您提供的字段——其余字段保持不变。这是一种部分更新，会保留其他配置设置：

<CodeGroup>
  ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  client.update_feedback_config(
      "accuracy",
      is_lower_score_better=True,
  )
  ```

  ```typescript TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  await client.updateFeedbackConfig("accuracy", {
    isLowerScoreBetter: true,
  });
  ```
</CodeGroup>

### 删除反馈配置

使用 [`delete_feedback_config`](https://reference.langchain.com/python/langsmith/client/Client/delete_feedback_config) 从您的组织中移除反馈配置。这将执行软删除，将配置标记为已删除，但不会将其从系统中永久移除。如果需要，您可以稍后使用相同的键重新创建配置：

<CodeGroup>
  ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  client.delete_feedback_config("accuracy")
  ```

  ```typescript TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  await client.deleteFeedbackConfig("accuracy");
  ```
</CodeGroup>

## 标注队列评分项

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

### 创建带有评分项的队列

使用 [`create_annotation_queue`](https://reference.langchain.com/python/langsmith/client/Client/create_annotation_queue) 创建标注队列，并通过评分项将反馈配置分配给它。每个评分项通过其键引用一个反馈配置，并自定义其在此特定队列中向标注员显示的方式。

此示例创建一个包含三个评分项的队列。队列级别的 `rubric_instructions` 提供显示在标注界面顶部的通用指导：

<CodeGroup>
  ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  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,
          },
      ],
  )
  ```

  ```typescript TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  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,
      },
    ],
  });
  ```
</CodeGroup>

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

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

使用 [`update_annotation_queue`](https://reference.langchain.com/python/langsmith/client/Client/update_annotation_queue) 修改分配给标注队列的评分项。此操作会替换整个评分项列表，因此您必须包含所有要保留的项目——操作会移除您未包含的任何项目。

您需要队列 ID，可以在创建队列时或通过列出队列获得：

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

<CodeGroup>
  ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  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,
          },
      ],
  )
  ```

  ```typescript TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  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 },
    ],
  });
  ```
</CodeGroup>

## 反馈配置类型（详细）

### 连续型

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

<CodeGroup>
  ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # 简单的连续分数
  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": "优秀"},
          ],
      },
  )
  ```

  ```typescript TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  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: "优秀" },
      ],
    },
  });
  ```
</CodeGroup>

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

### 分类型

分类配置为标注员提供一组离散的预定义选项。每个类别必须有一个 `value`（用于评分和分析的数字标识符）和一个 `label`（显示给标注员的文本）。您必须定义至少 2 个类别。

使用分类配置进行二元决策（通过/失败、正确/错误）、多类分类（情感、主题类别）或任何具有固定离散选项集的评估。不要为分类配置设置 `min` 或 `max`：

<CodeGroup>
  ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # 二元通过/失败
  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": "正面"},
          ],
      },
  )
  ```

  ```typescript TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  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: "正面" },
      ],
    },
  });
  ```
</CodeGroup>

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

### 自由文本型

自由文本配置允许标注员提供开放式文本反馈，无需任何预定义结构或约束。此类型没有 `min`、`max` 或 `categories` 字段——标注员可以输入任何他们想要的文本。

自由文本反馈对于捕捉细微洞察很有价值，但与结构化反馈类型相比，更难汇总和分析：

<CodeGroup>
  ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  client.create_feedback_config(
      "notes",
      feedback_config={"type": "freeform"},
  )
  ```

  ```typescript TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  await client.createFeedbackConfig({
    feedbackKey: "notes",
    feedbackConfig: { type: "freeform" },
  });
  ```
</CodeGroup>

## 验证规则

| 类型            | 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。 |

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/annotation-queues-sdk.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>