LangSmith评测使用教程：给LLM应用跑通第一组评估
LangSmith 的评测功能不是单独安装的软件，而是绑定在 LangSmith 项目上的在线能力。
只要你已经能往 LangSmith 发送 trace，就可以在同一个项目里创建数据集、跑评估器，并在 Experiments 页面看到每次运行的通过率和失败样本。
本文按这个前提展开，不重复注册和 API Key 配置。
先确认评测依赖的环境已就绪
评测入口在 LangSmith SDK 的 Python 包里，所以先检查三件事：
- 已安装
langsmith包，终端执行pip show langsmith能看到版本号。 - 环境变量
LANGSMITH_API_KEY已设置，并且LANGSMITH_TRACING=true。 - 你的项目里已经有至少一条 trace，能在 LangSmith 后台的 Projects 列表里看到。
如果 trace 都还没有，先不要急着建数据集，否则评测跑完没有可对比的线上样本。
创建数据集：先放几条真实输入和期望输出
LangSmith 的数据集由若干条 example 组成，每条至少包含输入和参考输出。
最简单的做法是在后台进入项目，点 Datasets → New Dataset，命名后手动添加两三条样例。
也可以先用代码写入：
from langsmith import Client
client = Client()
dataset = client.create_dataset("qa-smoke-test")
client.create_examples(
inputs=[{"question": "LangSmith 的评测结果在哪里看？"}],
outputs=[{"answer": "Experiments 页面"}],
dataset_id=dataset.id,
)避坑点：数据集的输入字段名必须和后面目标函数接收的参数名一致，否则 evaluate 会报缺少参数。
样例数量先控制在 3 到 5 条，跑通流程后再扩充。
写目标函数和评估器，再用 evaluate 提交
目标函数就是你要测的应用本身，它接收一条输入并返回输出；
评估器负责把输出和参考输出做比较，返回分数和说明。
下面用一个最简字符串匹配评估器演示：
from langsmith import evaluate
def target(inputs: dict) -> dict:
return {"answer": "Experiments 页面"}
def exact_match(outputs: dict, reference_outputs: dict) -> dict:
score = int(outputs["answer"] == reference_outputs["answer"])
return {"key": "exact_match", "score": score}
results = evaluate(
target,
data="qa-smoke-test",
evaluators=[exact_match],
experiment_prefix="smoke",
)执行后终端会打印实验名称和结果摘要。
回到 LangSmith 后台，进入项目下的 Experiments，能看到这次运行对应的实验，点进去可以逐条查看输入、输出、评估器得分和失败原因。
常见报错和排查顺序
Dataset not found：检查data参数用的是数据集名称还是 ID，名称要和后台完全一致。- 评估器返回空结果：确认评估器函数签名是
(outputs, reference_outputs)，且返回字典里带key和score。 - 实验跑完但页面没有数据：检查环境变量是否指向正确的项目，
LANGSMITH_PROJECT要和后台项目名一致。
验证评测是否真正生效
不要只看终端有没有报错。
完成一次 evaluate 后，至少核对两点：Experiments 页面出现新实验，且评估器列有分数；
随机点开一条失败样例，能看到目标函数输出和参考输出的差异。
如果分数全是 1 或全是 0，先检查评估器逻辑是否把输入和参考输出传反了。
跑通第一组评估后，再逐步替换成更贴近业务的评估器，比如用另一个模型做语义判断，而不是字符串完全匹配。
评测的价值在于持续对比不同版本，单次运行只能说明当前样本上的表现。
