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

​
反馈层级

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

​
更新反馈配置

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

​
删除反馈配置

使用 delete_feedback_config 从您的组织中移除反馈配置。这将执行软删除，将配置标记为已删除，但不会将其从系统中永久移除。如果需要，您可以稍后使用相同的键重新创建配置： 
client.delete_feedback_config("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,
        },
    ],
)
  • 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,
        },
    ],
)

​
反馈配置类型（详细）

​
连续型

连续配置定义带有最小值和最大值的数字评分量表。标注员可以选择范围内的任何值，这非常适合在数字量表上对准确度、质量或相关性等维度进行评分： 
# 简单的连续分数
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": "优秀"},
        ],
    },
)
第一个示例显示了一个没有标签的 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": "正面"},
        ],
    },
)
第一个示例显示了一个二元通过/失败配置。第二个示例演示了一个具有三个选项的情感多类配置。数字值允许您即使对分类反馈也能计算汇总分数。

​
自由文本型

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

​
验证规则

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

​
参考

​
反馈配置类型

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

​
评分项字段

字段类型描述
feedback_keystring必需。必须与现有反馈配置键匹配。
descriptionstring向标注员显示此项的指导。
score_descriptionsRecord<string, string>特定分数值的标签（连续型）。
value_descriptionsRecord<string, string>特定类别值的标签（分类型）。
is_requiredboolean标注员在提交前是否必须完成此项。默认为 false。
将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。
在 GitHub 上编辑此页面 或 提交问题。