langsmith

LangChain 生态的 LLM 追踪、数据集与评估平台。

补充说明

LangSmith 把一次 LLM 调用拆成 run 和 span，记录输入、输出、延迟、token、工具调用和错误。它支持 LangChain/LangGraph 自动追踪，也能用 @traceable 接入任意 Python/JS 代码；数据集、实验和 evaluator 用来做回归，在线反馈和监控用来观察生产流量。

云版是 SaaS，数据保存在 LangSmith 托管环境，保留期和区域随套餐变化；自托管是 Enterprise 附加项，用 Kubernetes/Helm 部署在自己的集群，依赖 ClickHouse、PostgreSQL、Redis/Valkey 和对象存储。自托管数据不出集群，但功能、升级节奏和运维成本与云版不同，具体以当前版本的部署文档和许可证为准。

敏感数据要显式处理：LANGSMITH_HIDE_INPUTS/LANGSMITH_HIDE_OUTPUTS 可隐藏内容，Client(anonymizer=...) 可在发送前脱敏；隐藏字段和脱敏函数的适用范围不同，不能假设开了追踪就自动合规。

常用示例

安装 SDK 并配置项目；区域或自托管实例必须同时改 endpoint：

pip install -U langsmith
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="lsv2_..."
export LANGSMITH_PROJECT="rag-prod"
# export LANGSMITH_ENDPOINT="https://api.smith.langchain.com"

用 @traceable 追踪普通 Python 函数，短生命周期脚本要等待后台上报完成：

from langsmith import traceable, wait_for_all_tracers
@traceable(name="retrieve", tags=["rag"])
def retrieve(query: str) -> list[str]:
    return ["doc-a", "doc-b"]
print(retrieve("OOMKilled 怎么排查"))
wait_for_all_tracers()

创建数据集并写入样例，inputs 和 outputs 都是字典：

from langsmith import Client
client = Client()
ds = client.create_dataset("rag-regression", description="RAG 回归集")
client.create_examples(dataset_id=ds.id, examples=[{"inputs": {"question": "磁盘满了怎么查？"}, "outputs": {"answer": "df -h、du"}}])
print(ds.id)

定义 target 和 evaluator 跑实验；evaluator 签名是 (inputs, outputs, reference_outputs)：

from langsmith import evaluate
def target(inputs):
    return {"answer": inputs["question"].upper()}
def exact(inputs, outputs, reference_outputs):
    return {"key": "exact_match", "score": int(outputs["answer"] == reference_outputs["answer"])}
print(evaluate(target, data="rag-regression", evaluators=[exact], experiment_prefix="baseline"))

给生产 run 写用户反馈，分数和评论都会进入数据集筛选：

from langsmith import Client
client = Client()
client.create_feedback(run_id="<run-id>", key="user_score", score=1, comment="回答正确")

在客户端侧隐藏输入输出，或用 anonymizer 替换邮箱和手机号：

from langsmith import Client, create_anonymizer
anonymizer = create_anonymizer({"email": "[email]", "phone": "[phone]"})
client = Client(anonymizer=anonymizer)
hidden = Client(hide_inputs=True, hide_outputs=True)

列出最近的根 run，做简单的在线巡检：

from langsmith import Client
for run in Client().list_runs(project_name="rag-prod", is_root=True, limit=5):
    print(run.id, run.status, run.latency)

易错点与排错

脚本很快退出时追踪可能还没上报；调用 wait_for_all_tracers()，JS 端等待所有 callback 结束。
云版 key 与 endpoint 区域不匹配会 401/403；确认 LANGSMITH_ENDPOINT，不要只检查 key。
多 workspace 账号必须设 LANGSMITH_WORKSPACE_ID；否则 run 会落到默认 workspace，看似“丢失”。
新旧环境变量混用会关闭追踪：新 SDK 用 LANGSMITH_TRACING/LANGSMITH_PROJECT，旧版用 LANGCHAIN_TRACING_V2/LANGCHAIN_PROJECT。
evaluator 返回的 key 拼错或结构不是字典，实验里会没有分数；先在本地打印 evaluator 返回值。
重复执行 create_examples 会不断追加样例；用固定 dataset id 并去重或更新，不要在 CI 每次新建同名数据集。
自托管功能与 chart 版本、许可证相关，云版文档里的页面不一定存在；升级前查对应 release notes。
hide_inputs/hide_outputs 不会自动脱敏 metadata 和 tags；PII 可能藏在这些字段里，必要时用 anonymizer 统一处理。
SaaS 保留期有限，重要实验和数据集要定期导出；不要把 LangSmith 当唯一存档。
max_concurrency 过高会撞平台或模型限流，表现为实验随机失败；降低并发并把限流错误与低分区分开。

读完自测

@traceable 与 LangChain 自动追踪是什么关系？
云版和自托管的关键差异有哪些？
如何避免把 PII 发送到 LangSmith？

答案

LangChain/LangGraph 集成自动产生 run；@traceable 用于没有框架托管的普通函数，两者都写入同一套 project/trace 结构。
云版由 LangSmith 托管、开箱即用但数据出境且有保留期；自托管部署在自有 K8s，依赖 ClickHouse/PostgreSQL/Redis/对象存储，数据不出集群但需要许可证和运维。
用 LANGSMITH_HIDE_INPUTS/LANGSMITH_HIDE_OUTPUTS 隐藏内容，用 Client(anonymizer=...) 替换敏感字段并检查 metadata/tags；高敏环境关闭追踪或自托管。

langsmith

补充说明

常用示例

易错点与排错

相关命令

读完自测