使用 SDK 管理评估器

使用 LangSmith SDK 以编程方式创建和管理评估器。通过 SDK 创建的评估器是工作区级别的资源，会出现在 LangSmith UI 的 Evaluators 表中，与在 UI 中创建的评估器相同。您可以将它们附加到数据集以运行离线评估，或附加到追踪项目以运行在线评估。使用 SDK 可以实现评估器管理自动化，并将评估集成到您现有的工作流中。

前提条件

通过 SDK 管理评估器需要：

Python: langsmith>=0.9.8 (PyPI)
TypeScript: langsmith>=0.7.16 (npm)

有关安装和设置，请参阅 Python SDK 文档和 TypeScript SDK 文档。

本页的示例在初始化客户端时不带参数，因此它会读取 LANGSMITH_API_KEY 和 LANGSMITH_ENDPOINT 环境变量。请通过环境变量配置您的 API 密钥，而不是将其硬编码。在下面的示例中，请将 <evaluator-uuid> 等占位符替换为 LangSmith 中的相应信息。本页所有 Python 异步示例都假定它们运行在 async def main(): ... asyncio.run(main()) 内部，如创建代码评估器示例所示。

创建评估器

代码评估器

代码评估器使用您定义的函数为每次运行或示例评分。

import asyncio

from langsmith import Client


async def main():
    client = Client()

    created = await client.evaluators.create(
        name="正确性评估器",
        type="code",
        code_evaluator={
            "code": "def perform_eval(run, example):\n    return {'score': 1}",
            "language": "python",
        },
    )
    evaluator_id = created.evaluator.id
    print("已创建评估器:", evaluator_id)


asyncio.run(main())

import { Client } from "langsmith";

const client = new Client();

const created = await client.evaluators.create({
  name: "正确性评估器",
  type: "code",
  code_evaluator: {
    code: "def perform_eval(run, example):\n    return {'score': 1}",
    language: "python",
  },
});
const evaluatorId = created.evaluator?.id;
console.log("已创建评估器:", evaluatorId);

LLM 作为评判者评估器

LLM 作为评判者评估器引用提示词库中的一个提示词，并将您的运行或示例字段映射到提示词变量。

该提示词必须是一个结构化提示词（类型为 StructuredPrompt）。StructuredPrompt 将提示词模板与输出架构相结合，确保模型返回具有定义结构的数据。

import asyncio

from langsmith import Client


async def main():
    client = Client()

    created = await client.evaluators.create(
        name="LLM 评判者",
        type="llm",
        llm_evaluator={
            "prompt_repo_handle": "<prompt-repo-handle>",
            "commit_hash_or_tag": "<commit-hash-or-tag>",
            "variable_mapping": {
                "input": "inputs.question",
                "output": "outputs.answer",
                "reference": "reference.answer",
            },
        },
    )
    evaluator_id = created.evaluator.id


asyncio.run(main())

const created = await client.evaluators.create({
  name: "LLM 评判者",
  type: "llm",
  llm_evaluator: {
    prompt_repo_handle: "<prompt-repo-handle>",
    commit_hash_or_tag: "<commit-hash-or-tag>",
    variable_mapping: {
      input: "inputs.question",
      output: "outputs.answer",
      reference: "reference.answer",
    },
  },
});
const evaluatorId = created.evaluator?.id;

prompt_repo_handle 是提示词的内部仓库名称，而不是其显示标题或 URL。要查找它，请列出您的工作区提示词并读取 repo_handle 字段，或通过其在 LangSmith 中的标识符检索特定提示词。提示词的标识符可以是以下格式：

promptName（用于私有提示词），例如 my-prompt。
owner/promptName（用于公共提示词），例如 langchain-ai/correctness。

# 列出工作区提示词并读取每个仓库句柄
for prompt in client.list_prompts(limit=10).repos:
    print("提示词仓库句柄:", prompt.repo_handle)   # 用于 prompt_repo_handle 的值
    print("提示词全名:", prompt.full_name)     # 显示名称
    print("描述:", prompt.description)

# 或者通过标识符检索特定提示词
prompt = client.get_prompt("<prompt-identifier>")
print("提示词仓库句柄:", prompt.repo_handle)

// 列出工作区提示词并读取每个仓库句柄。
// 在此 SDK 版本中，listPrompts() 没有 `limit` 选项——它是一个异步
// 生成器，涵盖所有提示词，因此请在客户端限制数量并中断。
const prompts = client.listPrompts();
let count = 0;
for await (const prompt of prompts) {
  console.log("提示词仓库句柄:", prompt.repo_handle);
  console.log("提示词全名:", prompt.full_name);
  console.log("描述:", prompt.description);
  console.log("---");
  if (++count >= 10) break; // 仅前 10 个；停止进一步分页
}

// 或者通过标识符检索特定提示词
const prompt = await client.getPrompt("<prompt-identifier>");
console.log("提示词仓库句柄:", prompt.repo_handle);

检索评估器

通过 ID 获取单个评估器，以读取其配置，包括名称、类型、反馈键和运行规则。

import asyncio

from langsmith import Client


async def main():
    client = Client()
    evaluator_id = "<evaluator-uuid>"

    evaluator = await client.evaluators.retrieve(evaluator_id)
    print(evaluator.name)
    print(evaluator.type)
    print(evaluator.feedback_keys)
    print(evaluator.run_rules)


asyncio.run(main())

const evaluator = await client.evaluators.retrieve(evaluatorId);
console.log(evaluator.name);
console.log(evaluator.type);
console.log(evaluator.feedback_keys);
console.log(evaluator.run_rules);

更新评估器

传递与评估器类型匹配的字段：代码评估器使用 code_evaluator，LLM 作为评判者评估器使用 llm_evaluator。update 方法仅更改您传递的字段。

import asyncio

from langsmith import Client


async def main():
    client = Client()

    # 更新一个代码评估器
    code_evaluator_id = "<code-evaluator-uuid>"

    updated = await client.evaluators.update(
        code_evaluator_id,
        name="已更新的正确性评估器",
        code_evaluator={
            "code": "def perform_eval(run, example):\n    return {'score': 0.8}",
            "language": "python",
        },
    )
    print(updated.evaluator.name if updated.evaluator else None)

    # 更新一个 LLM 作为评判者评估器的名称和提示词
    llm_evaluator_id = "<llm-evaluator-uuid>"

    await client.evaluators.update(
        llm_evaluator_id,
        name="已更新的 LLM 评判者",
        llm_evaluator={
            "prompt_repo_handle": "<prompt-repo-handle>",
            "commit_hash_or_tag": "<commit-hash-or-tag>",
        },
    )


asyncio.run(main())

// 更新一个代码评估器
const codeEvaluatorId = "<code-evaluator-uuid>";

const updated = await client.evaluators.update(codeEvaluatorId, {
  name: "已更新的正确性评估器",
  code_evaluator: {
    code: "def perform_eval(run, example):\n    return {'score': 0.8}",
    language: "python",
  },
});
console.log(updated.evaluator?.name);

// 更新一个 LLM 作为评判者评估器的名称和提示词
const llmEvaluatorId = "<llm-evaluator-uuid>";

await client.evaluators.update(llmEvaluatorId, {
  name: "已更新的 LLM 评判者",
  llm_evaluator: {
    prompt_repo_handle: "<prompt-repo-handle>",
    commit_hash_or_tag: "<commit-hash-or-tag>",
  },
});

配置运行时设置

LLM 作为评判者评估器接受额外的设置，以控制其对追踪进行评分的方式：

variable_mapping：将运行或示例字段映射到评判者提示词变量。当评估器运行时应用。
use_corrections_dataset 和 num_few_shot_examples：启用基于人工评分修正的少样本学习。仅当评估器附加到项目或数据集且已提交修正时才应用。

这些设置在下一次评估运行时生效，而不是在您调用 update 时立即生效。

import asyncio

from langsmith import Client


async def main():
    client = Client()
    llm_evaluator_id = "<llm-evaluator-uuid>"

    await client.evaluators.update(
        llm_evaluator_id,
        llm_evaluator={
            "prompt_repo_handle": "<prompt-repo-handle>",
            "commit_hash_or_tag": "<commit-hash-or-tag>",
            "variable_mapping": {
                "input": "inputs.question",
                "output": "outputs.answer",
            },
            "use_corrections_dataset": True,
            "num_few_shot_examples": 3,
        },
    )


asyncio.run(main())

const llmEvaluatorId = "<llm-evaluator-uuid>";

await client.evaluators.update(llmEvaluatorId, {
  llm_evaluator: {
    prompt_repo_handle: "<prompt-repo-handle>",
    commit_hash_or_tag: "<commit-hash-or-tag>",
    variable_mapping: {
      input: "inputs.question",
      output: "outputs.answer",
    },
    use_corrections_dataset: true,
    num_few_shot_examples: 3,
  },
});

列出评估器

按名称、类型、反馈键、附加资源或标签值进行过滤，并对结果进行排序或分页。当您直接迭代返回的对象时，list() 会自动分页遍历所有匹配项。limit 设置每页结果数（1 到 100），而不是总结果数。sort_by 是可选的，接受 created_at 或 updated_at，默认为 created_at。

import asyncio

from langsmith import Client


async def main():
    client = Client()

    # 读取单页结果
    page = await client.evaluators.list(
        name_contains="正确性",
        type="code",
        limit=10,
    )
    for evaluator in page.evaluators:
        print(evaluator.id, evaluator.name, evaluator.type)

    # 将所有匹配项收集到一个列表中
    evaluators = [
        evaluator
        async for evaluator in client.evaluators.list(feedback_key="正确性", limit=20)
    ]

    # 过滤、排序和分页
    page = await client.evaluators.list(
        feedback_key="正确性",
        name_contains="评判者",
        resource_id=["<project-or-dataset-uuid>"],
        tag_value_id=["<tag-value-uuid>"],
        type="llm",
        sort_by="updated_at",  # "created_at"（默认）或 "updated_at"
        sort_by_desc=False,
        limit=20,
        offset=0,
    )


asyncio.run(main())

// 读取单页结果
const page = await client.evaluators.list({
  name_contains: "正确性",
  type: "code",
  limit: 10,
});
for (const evaluator of page.evaluators) {
  console.log(evaluator.id, evaluator.name, evaluator.type);
}

// 将所有匹配项收集到一个数组中
const evaluators = [];
for await (const evaluator of client.evaluators.list({
  feedback_key: "正确性",
  limit: 20,
})) {
  evaluators.push(evaluator);
}

// 过滤、排序和分页
await client.evaluators.list({
  feedback_key: "正确性",
  name_contains: "评判者",
  resource_id: ["<project-or-dataset-uuid>"],
  tag_value_id: ["<tag-value-uuid>"],
  type: "llm",
  sort_by: "updated_at", // "created_at"（默认）或 "updated_at"
  sort_by_desc: false,
  limit: 20,
  offset: 0,
});

跟踪评估器花费

检索评估器的预估美元花费和追踪计数：

period_start：一个纯日期的 ISO 字符串，例如 2026-06-29。传递 datetime 会返回 400 错误。
- 窗口：period_start 开始一个固定的 7 天窗口，包含 period_start 及其后的六天。该窗口是半开放的，[period_start, period_start + 7 days)，因此 period_end（period_start 加 7 天）被排除。例如，period_start 为 2026-06-29 时，涵盖 2026-06-29 到 2026-07-05，而 2026-07-06 被排除。
type：将结果范围限定为单一评估器类型，llm 或 code。省略它则包含所有类型。
空结果：如果该窗口没有记录任何花费，则返回的 groups 列表为空。

请仅传递 group_by、evaluator_id、session_id（LangSmith 追踪项目 UUID）或 dataset_id 中的一个。

import asyncio

from langsmith import Client


async def main():
    client = Client()
    evaluator_uuid = "<evaluator-uuid>"
    start_date = "<period-start-date>" # 例如，"2026-06-29"

    # 单个评估器的花费
    spend = await client.evaluators.spend(
        period_start=start_date,
        evaluator_id=evaluator_uuid,
    )
    for group in spend.groups or []:
        print(group.evaluator_name, group.total_spend_usd, group.total_trace_count)

    # 按评估器分组花费
    spend_by_evaluator = await client.evaluators.spend(
        period_start=start_date,
        group_by="evaluator",
        type="llm",
    )
    print("按评估器分组")
    for group in spend_by_evaluator.groups or []:
        print(group.evaluator_name, group.total_spend_usd, group.total_trace_count)

    # 按资源分组花费
    spend_by_resource = await client.evaluators.spend(
        period_start=start_date,
        group_by="resource",
        type="llm",
    )
    print("按资源分组")
    for group in spend_by_resource.groups or []:
        print(group.session_name, group.dataset_name, group.total_spend_usd, group.total_trace_count)

    # 按运行规则分组花费
    spend_by_run_rule = await client.evaluators.spend(
        period_start=start_date,
        group_by="run_rule",
        type="llm",
    )
    print("按运行规则分组")
    for group in spend_by_run_rule.groups or []:
        print(group.run_rule_name, group.total_spend_usd, group.total_trace_count)


asyncio.run(main())

const evaluatorUUID = "<evaluator-uuid>";
const startDate = "<period-start-date>"; // 例如，"2026-06-29"

// 单个评估器的花费
const spend = await client.evaluators.spend({
  period_start: startDate,
  evaluator_id: evaluatorUUID,
});
for (const group of spend.groups ?? []) {
  console.log(group.evaluator_name, group.total_spend_usd, group.total_trace_count);
}

// 按评估器分组花费
const spendByEvaluator = await client.evaluators.spend({
  period_start: startDate,
  group_by: "evaluator",
  type: "llm",
});
console.log("按评估器分组");
for (const group of spendByEvaluator.groups ?? []) {
  console.log(group.evaluator_name, group.total_spend_usd, group.total_trace_count);
}

// 按资源分组花费
const spendByResource = await client.evaluators.spend({
  period_start: startDate,
  group_by: "resource",
  type: "llm",
});
console.log("按资源分组");
for (const group of spendByResource.groups ?? []) {
  console.log(group.session_name, group.dataset_name, group.total_spend_usd, group.total_trace_count);
}

// 按运行规则分组花费
const spendByRunRule = await client.evaluators.spend({
  period_start: startDate,
  group_by: "run_rule",
  type: "llm",
});
console.log("按运行规则分组");
for (const group of spendByRunRule.groups ?? []) {
  console.log(group.run_rule_name, group.total_spend_usd, group.total_trace_count);
}

删除评估器

当评估器附加到追踪项目或数据集时，您无法删除它。请设置 delete_run_rules 为 true，以在删除评估器之前删除引用该评估器的运行规则。

import asyncio

from langsmith import Client


async def main():
    client = Client()
    evaluator_id = "<evaluator-uuid>"

    await client.evaluators.delete(
        evaluator_id,
        delete_run_rules=True, # 首先删除引用该评估器的运行规则
    )


asyncio.run(main())

const evaluatorId = "<evaluator-uuid>";

await client.evaluators.delete(evaluatorId, {
  delete_run_rules: true, // 首先删除引用该评估器的运行规则
});

Evaluator types

Frameworks & integrations

Improve evaluators

前提条件

创建评估器

代码评估器

LLM 作为评判者评估器

检索评估器

更新评估器

配置运行时设置

列出评估器

跟踪评估器花费

删除评估器

相关

​前提条件

​创建评估器

​代码评估器

​LLM 作为评判者评估器

​检索评估器

​更新评估器

​配置运行时设置

​列出评估器

​跟踪评估器花费

​删除评估器

​相关

前提条件

创建评估器

代码评估器

LLM 作为评判者评估器

检索评估器

更新评估器

配置运行时设置

列出评估器

跟踪评估器花费

删除评估器

相关