langsmith-sdk
LangChain 官方 LLM 应用可观测性平台 SDK，支持链路追踪、自动化评估与数据集管理
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
LangChain 官方 LLM 应用可观测性平台 SDK，支持链路追踪、自动化评估与数据集管理
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
你开发了一个基于 GPT-4 的客服机器人，上线三个月后，用户反馈回答质量开始下降。你打开日志，看到的只是密密麻麻的 API 请求记录——但这些冷冰冰的数据根本无法回答一个核心问题：到底是模型变笨了，还是提示词设计有缺陷，还是某次更新引入了 bug？
LangChain 公司推出的 LangSmith，就是来解决这个痛点的。这是一个专为 LLM 应用设计的一站式可观测性与评估平台，而这个仓库就是它的 Python/JavaScript 双语言 SDK——让你在不离开代码编辑器的情况下，把整个 LLM 应用从"黑盒"变成"白盒"。
传统的软件调试有明确的边界：输入参数、函数调用栈、返回值。但 LLM 应用完全不同——同样的提示词，每次调用结果可能不同；同样的模型，训练数据更新后行为可能改变；RAG 系统的表现，既取决于大模型，也取决于向量数据库的召回质量。
当一个 LLM 应用出现 bug，问题可能出在：大模型的幻觉、提示词工程不够精确、检索到的上下文不相关，甚至是某个 API 的响应格式发生了变化。没有完善的链路追踪，开发者往往只能靠"猜"和"试"，效率极低。
LangSmith 正是为解决这一类问题而生的平台，由 LangChain 官方开发和维护，支持与 LangChain 无缝集成，同时也兼容任何 LLM 应用框架。它帮助开发团队实现三大核心能力：链路追踪（Tracing）、数据集管理和自动化评估（Evaluation）。
LangSmith 的追踪机制通过 @traceable 装饰器实现。只需在任意函数上添加这个装饰器，所有内部的 LLM 调用（包括 ChatGPT、Claude、Gemini 等）都会被自动记录下来，形成一棵结构化的调用树。
from langsmith import traceable
from langsmith.wrappers import wrap_openai
import openai
client = wrap_openai(openai.Client())
@traceable
def pipeline(user_input: str):
result = client.chat.completions.create(
messages=[{"role": "user", "content": user_input}],
model="gpt-3.5-turbo"
)
return result.choices[0].message.content
pipeline("帮我写一封请假邮件")
追踪结果会实时同步到 LangSmith Web 平台（smith.langchain.com），包括每次调用的输入消息、输出响应、Token 消耗、延迟、完整调用栈，以及关键中间步骤的中间输出。这让开发者能够精确还原"某次糟糕的回答"背后到底发生了什么。
传统的模型评估依赖人工打分，成本高、效率低。LangSmith SDK 提供了完整的评估框架，支持创建测试数据集（Dataset）和自定义评估器（Evaluator），实现 LLM 辅助的自动化评分。
开发者可以定义自己的评估逻辑，比如检查输出是否包含特定关键词、格式是否正确、是否满足某种语义条件。LangSmith 会自动在数据集上运行评估，生成量化报告，帮助团队判断模型或提示词的新版本是否真的改进了。
SDK 支持多种评估器类型：基于规则的字符串匹配评估器（StringEvaluator）、基于 LLM 的语义评估器（LLMJudge）等，满足不同场景的需求。
LangSmith SDK 在 integrations/ 目录下维护了大量第三方 Agent 框架的集成适配器：
这些集成让 LangSmith 的追踪能力可以渗透到 Agent 框架的内部调用链中，追踪粒度更细、覆盖范围更广。
PromptCache 模块是 SDK 的一大亮点。它允许开发者缓存语义相近的 Prompt 及其对应的 LLM 响应，当下次遇到相同或相近的请求时，直接返回缓存结果，绕过昂贵的 LLM 调用。
这对于 RAG 场景特别有价值：用户反复询问相似问题时，无需每次都调用 LLM，响应速度和成本都会显著优化。
在云端沙箱环境中，安全地访问 AWS 资源是一个常见需求。SDK 提供了 aws_auth_proxy_config 配置，允许在沙箱代码中直接使用 boto3 或 AWS CLI，无需将密钥写入环境变量或文件。这解决了 AI 应用在隔离环境中调用云服务时的凭证管理难题。
python/langsmith/_openapi_client/ 目录包含了一个完整的 OpenAPI 自动生成客户端，开发者可以绕过高级 SDK 接口，直接调用 LangSmith 的底层 REST API，实现更精细化的控制。
python/langsmith/cli/ 目录下包含命令行工具，支持直接从终端查询、上传和管理 LangSmith 上的数据集、实验记录等资源，适合 DevOps 流程和脚本自动化场景。
该仓库是 LangChain 罕见的"双语言同仓"结构，根目录下并列 python/ 和 js/ 两套 SDK。两者 API 设计高度对称，TypeScript SDK 基于 fetch API，Python SDK 基于 requests 和 httpx，均支持同步和异步调用。
Python SDK 要求 Python >= 3.10，使用 Pydantic v2 进行数据建模，通过 orjson 提升 JSON 序列化性能，通过 zstandard 压缩传输数据以降低网络开销。TypeScript SDK 则提供了完整的类型定义（.d.ts），IDE 友好。
schemas.py 定义了 LangSmith API 的所有请求/响应数据模型，充分利用了 Pydantic v2 的 model_config、Annotated 约束、StrictBool/StrictFloat 等高级特性，保证数据在传入 API 之前就完成了严格校验。
核心数据模型包括：
SDK 提供了完整的异步版本：AsyncClient、AsyncPromptCache 等，所有 API 方法均有 a 前缀的异步版本。基于 httpx 的异步 HTTP 客户端，使得 LangSmith SDK 可以无缝集成到 FastAPI、LangChain Async 等异步技术栈中，不阻塞事件循环。
pyproject.toml 中定义了多个可选依赖组：
otel：OpenTelemetry 生态集成openai-agents、claude-agent-sdk、google-adk、strands-agents：各 Agent 框架集成langsmith_pyo3：用 Rust 加速核心路径pytest：测试插件，支持将 pytest 用例自动录制到 LangSmith 数据集中追踪的核心原理是猴子补丁——wrap_openai 等函数在创建客户端时，替换底层的 _make_request 方法，将每次 HTTP 请求的数据（输入、输出、元数据）自动发往 LangSmith 的追踪接口，不改变用户原有的代码逻辑。
cassettes/ 目录（基于 VCRpy 的 HTTP 录制回放测试）和 tests/ 目录，pytest 插件可直接将测试运行结果上传到 LangSmith。py.typed 标记），Pydantic v2 严格建模，pre-commit 配置规范。| 维度 | 说明 |
|---|---|
| 技术门槛 | 低。需要基本的 Python/JS 知识，了解 LLM API 调用即可 |
| 接入成本 | 极低。pip install 后设置 3 个环境变量即可开始追踪 |
| 费用 | LangSmith 平台有免费用量，超出按量付费 |
| 适用框架 | 任意 LLM 应用，LangChain 原生支持，第三方 Agent 框架有适配器 |
| 不适用场景 | 完全离线的 LLM 应用（需要联网将追踪数据发送到 LangSmith 云） |
LangSmith 最大的局限在于它是一个闭源云平台的客户端，SDK 本身完全开源，但数据必须发送到 LangChain 官方服务器。这对于数据隐私要求极高的场景（如医疗、金融、法律领域）是一个硬性限制——所有 Prompt 和响应的内容都会离开你的基础设施。
此外，LangSmith 的评估能力高度依赖其云端平台，SDK 本身提供的评估器（如 LLMJudge）也需要调用 LLM API，存在额外的成本。另一个潜在问题是厂商锁定：一旦团队深度使用 LangSmith 的数据集和评估流程，迁移到其他可观测性平台（如 Phoenix、Weave）的成本会相当高。
LLM 应用可观测性是一个正在快速成长的赛道。随着 LangChain、AutoGen、CrewAI 等 Agent 框架的普及，开发者对"我的 Agent 到底在想什么"的需求愈发强烈。LangSmith 通过提供开箱即用的追踪+评估+数据集三位一体方案，填补了这一空白。
其背后的趋势是：AI 应用开发正在从"调 API 碰运气"向"数据驱动优化"演进。LangSmith 让这个演进有了基础设施级别的支撑，而 SDK 则是连接你的代码与这个基础设施的桥梁。
图1：LangChain 官方组织头像
分析基于 GitHub 主分支代码，stars 929（采集时），分析时间 2026-06-16。