本文是关于如何使用 LangSmith 的详细指南，涵盖从安装配置到核心功能的实际操作步骤。LangSmith 是 LangChain 生态系统中的工具，用于调试、测试、评估和监控基于大语言模型（LLM）的应用程序。本指南将包括代码示例、操作流程和实用建议，帮助快速上手。

1. LangSmith 概述

在深入使用方法之前，简要回顾 LangSmith 的功能：

  • Tracing（追踪）：记录 LLM 应用的每次运行（Run），包括输入、输出、中间步骤等。
  • 数据集管理：创建和存储测试数据集，用于评估和优化应用。
  • 评估（Evaluation）：自动化测试 LLM 性能，支持自定义指标。
  • 监控（Monitoring）：实时监控生产环境中的应用表现。
  • 协作：支持团队共享数据、Prompt 和结果。

接下来，我们将从安装配置开始，逐步介绍如何在实际项目中使用这些功能。

2. 安装与配置

2.1 注册 LangSmith 账户

  1. 访问 LangSmith 官网：https://smith.langchain.com/。
  2. 点击 Sign Up，使用邮箱注册账户。
  3. 登录后，进入 Settings > API Keys，生成一个 API Key（稍后需要用到）。
  4. （可选）创建一个项目（Project），用于组织你的追踪和数据集，默认为 default 项目。

2.2 安装依赖

LangSmith 主要与 LangChain 配合使用，因此需要安装相关 Python 库。确保你的环境已安装 Python（建议 3.8+）。

运行以下命令安装 LangChain 和 LangSmith：

pip install langchain langsmith

如果你使用特定 LLM 提供商（如 OpenAI、Anthropic），还需要安装对应的 SDK，例如：

pip install openai  # 用于 OpenAI 模型

2.3 配置环境变量

LangSmith 通过环境变量启用追踪功能。设置以下变量：

export LANGCHAIN_TRACING_V2=true
export LANGCHAIN_API_KEY=<your-api-key>  # 从 LangSmith 平台获取
export LANGCHAIN_PROJECT=<your-project-name>  # 可选，默认为 "default"

在 Python 代码中，也可以通过 os.environ 设置：

import os

os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "<your-api-key>"
os.environ["LANGCHAIN_PROJECT"] = "my-llm-project"

注意：

  • 确保 API Key 安全，不要泄露。
  • 如果不设置 LANGCHAIN_PROJECT，所有日志将归到默认项目。

2.4 验证配置

运行以下简单代码，检查 LangSmith 是否正确配置：

from langchain.chat_models import ChatOpenAI
from langchain.prompts import PromptTemplate
from langchain.chains import LLMChain

# 设置 LLM
llm = ChatOpenAI(api_key="<your-openai-api-key>", model="gpt-3.5-turbo")

# 创建 Prompt 和 Chain
prompt = PromptTemplate.from_template("翻译这句话到英文：{sentence}")
chain = LLMChain(llm=llm, prompt=prompt)

# 运行 Chain，LangSmith 会自动记录
result = chain.invoke({"sentence": "今天是星期五"})
print(result)

运行后，登录 LangSmith 平台（https://smith.langchain.com/），进入你的项目，查看 Traces 页面。你应该能看到这次运行的日志，包括输入、输出和 LLM 调用细节。

3. 使用 LangSmith 的核心功能

以下是 LangSmith 主要功能的详细使用方法，包括代码示例和操作步骤。

3.1 Tracing（追踪）

功能：记录 LLM 应用的每次运行，捕获输入、输出、中间步骤、工具调用等信息。

使用步骤
  1. 启用追踪：如上所述，设置 LANGCHAIN_TRACING_V2=true 即可自动启用追踪，无需额外代码。
  2. 运行应用：每次运行 LangChain 的链（Chain）、Agent 或其他组件时，LangSmith 会记录完整日志。
  3. 查看日志：
    • 登录 LangSmith 平台，进入你的项目。
    • 在 Traces 页面，点击某个 Run，查看详细信息。
    • 日志以树状结构展示，显示调用链（如 Prompt -> LLM -> 工具 -> 输出）。
代码示例

以下是一个使用 LangChain 的 Agent 示例，LangSmith 会记录整个过程：

from langchain.agents import initialize_agent, Tool
from langchain.chat_models import ChatOpenAI

# 定义一个简单工具
def calculator(query: str) -> str:
    return str(eval(query))

tools = [Tool(name="Calculator", func=calculator, description="用于数学计算")]

# 初始化 LLM 和 Agent
llm = ChatOpenAI(api_key="<your-openai-api-key>", model="gpt-4")
agent = initialize_agent(tools, llm, agent_type="zero-shot-react-description")

# 运行 Agent
result = agent.run("计算 2 + 3 * 4")
print(result)

在 LangSmith 中的表现：

  • 打开 LangSmith 平台，找到这次运行的 Trace。
  • 你会看到：
    • Agent 的输入（“计算 2 + 3 * 4”）。
    • 中间步骤：Agent 如何解析任务，调用 Calculator 工具。
    • 工具的输入输出（例如，3 * 4 和 12）。
    • 最终输出（14）。
实用建议
  • 调试复杂链：如果你的链涉及多个步骤（如检索、生成、后处理），使用 Trace 查看哪一步出错。
  • 性能分析：检查每个步骤的延迟，优化慢的调用。
  • 上下文检查：验证 Prompt 是否正确传递上下文。

3.2 数据集管理

功能：创建和管理测试数据集，用于批量测试和评估 LLM 应用。

使用步骤

  1. 创建数据集：

    • 登录 LangSmith 平台，进入 Datasets & Testing 页面。
    • 点击 New Dataset，输入名称（例如 qa-dataset）。
    • 手动添加数据点，或上传 CSV/JSON 文件。
    • 每个数据点通常包含：
      • Inputs：输入字段（如问题、句子）。
      • Outputs：预期输出（可选，用于评估）。

  2. 通过代码上传数据集：
    使用 langsmith 库上传数据：

    from langsmith import Client

# 初始化 LangSmith 客户端
client = Client()

# 创建数据集
dataset_name = "qa-dataset"
dataset = client.create_dataset(dataset_name=dataset_name)

# 添加数据点
client.create_examples(
    inputs=[
        {"question": "中国的首都是哪里？"},
        {"question": "1+1等于多少？"}
    ],
    outputs=[
        {"answer": "北京"},
        {"answer": "2"}
    ],
    dataset_id=dataset.id
)

  3. 查看和管理数据集：

    • 在 LangSmith 平台上，进入数据集页面，查看数据点。
    • 支持编辑、删除或导出数据。
代码示例

假设你想测试一个问答链的表现：

from langchain.chat_models import ChatOpenAI
from langchain.prompts import PromptTemplate
from langchain.chains import LLMChain

# 初始化 LLM 和 Chain
llm = ChatOpenAI(api_key="<your-openai-api-key>")
prompt = PromptTemplate.from_template("回答：{question}")
chain = LLMChain(llm=llm, prompt=prompt)

# 运行数据集测试
from langsmith import Client

client = Client()
dataset_name = "qa-dataset"
runs = client.run_on_dataset(
    dataset_name=dataset_name,
    llm_or_chain_factory=lambda: chain,
    project_name="test-qa-chain"
)

在 LangSmith 中的表现：

  • 测试结果会出现在指定项目（test-qa-chain）中。
  • 你可以看到每个数据点的输入、输出和运行状态（成功/失败）。
实用建议
  • 数据多样性：确保数据集覆盖多种场景（如简单问题、复杂问题、边缘案例）。
  • 版本控制：每次修改数据集时，LangSmith 会自动保存版本，便于回溯。
  • 批量测试：用数据集测试不同 Prompt 或模型，比较性能。

3.3 评估（Evaluation）

功能：自动化评估 LLM 应用的性能，支持预定义或自定义指标。

使用步骤

  1. 选择评估指标：

    • LangSmith 提供内置指标（如准确率、字符串匹配）。
    • 也可以定义自定义指标，例如基于规则或 LLM 的评分。

  2. 运行评估：

    • 使用数据集运行批量测试，自动计算指标。
    • 或者手动标记输出质量。

  3. 查看结果：

    • 在 LangSmith 平台的 Runs 或 Feedback 页面，查看评估分数和详细报告。
代码示例

以下是使用自定义评估器的示例：

from langsmith import Client
from langchain.chat_models import ChatOpenAI
from langchain.prompts import PromptTemplate
from langchain.chains import LLMChain

# 初始化 Chain
llm = ChatOpenAI(api_key="<your-openai-api-key>")
prompt = PromptTemplate.from_template("翻译：{sentence}")
chain = LLMChain(llm=llm, prompt=prompt)

# 定义自定义评估器
def exact_match_evaluator(run, example):
    predicted = run.outputs.get("text", "").strip()
    expected = example.outputs.get("answer", "").strip()
    return {"key": "exact_match", "score": int(predicted == expected)}

# 运行评估
client = Client()
dataset_name = "translation-dataset"
client.run_on_dataset(
    dataset_name=dataset_name,
    llm_or_chain_factory=lambda: chain,
    evaluation=[exact_match_evaluator],
    project_name="test-translation"
)

在 LangSmith 中的表现：

  • 评估结果显示每个数据点的得分（例如，exact_match 的 0 或 1）。
  • 汇总统计信息（如平均准确率）会展示在项目页面。
实用建议
  • 自定义指标：根据任务需求设计指标，例如翻译任务可以用 BLEU 分数，问答任务可以用语义相似度。
  • LLM 评估：可以用另一个 LLM 作为评估器，判断输出是否符合预期（需要额外配置）。
  • 迭代优化：根据评估结果调整 Prompt、模型或逻辑。

3.4 监控（Monitoring）

功能：在生产环境中实时监控 LLM 应用的性能和行为。

使用步骤

  1. 部署应用：

    • 确保你的 LangChain 应用已部署，并启用了 LangSmith 追踪。
    • 生产环境中，建议使用更高配额的 LangSmith 付费计划。

  2. 配置监控：

    • 在 LangSmith 平台，进入 Monitoring 页面，设置关键指标（如延迟、错误率）。
    • 启用用户反馈功能，允许用户标记输出质量。

  3. 分析数据：

    • 查看实时仪表盘，监控应用表现。
    • 检查异常 Run（例如，输出为空或延迟过高）。
代码示例

在生产环境中，追踪用户交互：

from langchain.chat_models import ChatOpenAI
from langchain.prompts import PromptTemplate
from langchain.chains import LLMChain

# 初始化 Chain
llm = ChatOpenAI(api_key="<your-openai-api-key>")
prompt = PromptTemplate.from_template("回答用户问题：{user_input}")
chain = LLMChain(llm=llm, prompt=prompt)

# 处理用户输入
user_input = "如何重置我的密码？"
result = chain.invoke({"user_input": user_input})
print(result["text"])

在 LangSmith 中的表现：

  • 每次用户交互都会生成一个 Run，记录输入、输出和元数据（如时间戳、Token 消耗）。
  • 你可以在 Feedback 页面查看用户提交的评分或评论。
实用建议
  • 异常检测：设置警报，监控错误率或延迟异常。
  • 用户反馈：鼓励用户提供反馈，收集低质量输出的案例，用于改进模型。
  • 成本优化：监控 Token 消耗，优化 Prompt 或模型选择。

3.5 协作与版本控制

功能：支持团队共享数据、Prompt 和结果，跟踪变更历史。

使用步骤

  1. 共享项目：

    • 在 LangSmith 平台，进入 Settings > Collaborators，邀请团队成员。
    • 成员可以访问项目中的 Traces、数据集和评估结果。

  2. 版本控制：

    • 数据集和 Prompt 的每次修改都会自动保存版本。
    • 在 Datasets 页面，点击数据集查看版本历史。

  3. 集成外部工具：

    • LangSmith 支持与 Weights & Biases、Datadog 等工具集成，扩展协作能力。
实用建议
  • 团队分工：Prompt 工程师可以专注于优化 Prompt，数据科学家可以管理数据集。
  • 变更管理：使用版本控制跟踪改动，避免意外覆盖。
  • 文档记录：在数据集或项目中添加描述，方便团队理解。

4. 高级用法

4.1 自定义 Tracing

你可以通过 langsmith 库自定义追踪行为，例如添加元数据：

from langsmith import traceable

@traceable(run_type="chain", extra_metadata={"user_id": "123"})
def my_chain(input_text):
    llm = ChatOpenAI(api_key="<your-openai-api-key>")
    prompt = PromptTemplate.from_template("总结：{text}")
    chain = LLMChain(llm=llm, prompt=prompt)
    return chain.invoke({"text": input_text})

result = my_chain("这是一段很长的文本...")

效果：在 LangSmith 中，这次运行会附带 user_id 元数据，便于按用户过滤日志。

4.2 集成外部工具

LangSmith 支持与外部工具集成，例如：

  • Weights & Biases：记录实验参数和结果。
  • Datadog：发送监控数据到 Datadog 仪表盘。

配置方法参考 LangSmith 文档（https://docs.smith.langchain.com/）。

5. 注意事项

  • 成本管理：LangSmith 免费计划有使用限制（如每月 500 次追踪）。生产环境建议升级到付费计划。
  • 数据隐私：上传到 LangSmith 的数据（如用户输入）可能包含敏感信息，确保符合隐私政策。
  • 学习资源：
  • 调试技巧：从简单链开始，逐步增加复杂性，熟悉 Tracing 和评估功能。

6. 总结

LangSmith 是一个功能强大的平台，通过追踪、数据集管理、评估和监控，简化了 LLM 应用的开发和运维。使用步骤包括：

  1. 注册账户，安装依赖，配置环境变量。
  2. 使用 Tracing 调试复杂工作流。
  3. 创建数据集，运行批量测试。
  4. 自动化评估，优化模型性能。
  5. 部署后监控生产环境，支持团队协作。
Logo
智能体开发者社区

中国智能体开发者社区，聚焦智能体与大模型开发，提供前沿资讯、实用工具链、开源项目及行业案例。通过技术沙龙、开发者大赛等活动，促进经验交流与协作，助力开发者快速构建创新智能应用。

更多推荐

MCP协议开发实战：从零搭建AI Agent工具链

创建静态资源（如项目 README 文件）。创建动态资源（如实时系统状态）。在 Client 中请求并利用资源上下文。回顾 MCP 协议如何降低 AI Agent 开发门槛。当前生态的局限与未来的演进方向。鼓励读者基于此大纲进行实践，并参与开源贡献。

avatar 智能体开发者社区

AI Agent可观测性：破解多步推理黑盒

随着AI Agent在复杂任务中承担越来越多的决策角色，其内部的多步推理过程往往如同一个“黑盒”，难以理解、调试和信任。本文旨在探讨AI Agent可观测性（Observability）的核心概念、技术挑战与实践方案，为开发者提供一套系统的方法论和工具链，以“照亮”Agent的推理黑盒，实现对其行为、决策逻辑与内部状态的全面洞察。构建AI Agent的可观测性体系不再是“锦上添花”，而是保障其在大

avatar 智能体开发者社区

MCP协议开发实战：从零搭建AI Agent工具链

回顾：我们从协议概念到动手搭建了一个可用的MCP工具链。MCP的生态现状：官方与社区提供的Server示例（GitHub, Jira, Notion等）。未来方向：更复杂的工具编排、多模型协作、可视化工具开发平台。鼓励动手：鼓励读者基于此框架，开发解决自己实际问题的工具。

avatar 智能体开发者社区