第十章：RAG知识库开发之【LangSmith 从入门到精通：构建生产级 LLM 应用的全链路可观测性平台】

前言

[一、LangSmith 概念详解](#一、LangSmith 概念详解)

[1.1 什么是 LangSmith？](#1.1 什么是 LangSmith？)

[1.2 LangSmith 与 LangChain 的关系](#1.2 LangSmith 与 LangChain 的关系)

[1.3 核心价值主张：可观测性](#1.3 核心价值主张：可观测性)

二、主要功能详解

[2.1 Prompt 调试与版本管理](#2.1 Prompt 调试与版本管理)

[2.1.1 Playground 交互式调试](#2.1.1 Playground 交互式调试)

[2.1.2 提示词版本管理](#2.1.2 提示词版本管理)

[2.1.3 提示词优化建议](#2.1.3 提示词优化建议)

[2.2 Chain/Agent 执行流程可视化](#2.2 Chain/Agent 执行流程可视化)

[2.2.1 追踪树的结构](#2.2.1 追踪树的结构)

[2.2.2 Agent 推理过程的可视化](#2.2.2 Agent 推理过程的可视化)

[2.2.3 与传统日志的对比](#2.2.3 与传统日志的对比)

[2.3 输出质量监控](#2.3 输出质量监控)

[2.3.1 在线监控仪表盘](#2.3.1 在线监控仪表盘)

[2.3.2 自动化评估](#2.3.2 自动化评估)

[2.3.3 人工反馈收集](#2.3.3 人工反馈收集)

三、使用方法

[3.1 准备工作：注册与 API Key 配置](#3.1 准备工作：注册与 API Key 配置)

[3.1.1 注册 LangSmith 账号](#3.1.1 注册 LangSmith 账号)

[3.1.2 环境变量配置](#3.1.2 环境变量配置)

[3.1.3 安装依赖](#3.1.3 安装依赖)

[3.2 在 LangChain 代码中接入 LangSmith](#3.2 在 LangChain 代码中接入 LangSmith)

[3.2.1 基础示例：自动追踪](#3.2.1 基础示例：自动追踪)

[3.2.2 使用 @traceable 装饰器进行细粒度控制](#3.2.2 使用 @traceable 装饰器进行细粒度控制)

[3.2.3 完整示例：RAG 应用的追踪](#3.2.3 完整示例：RAG 应用的追踪)

[3.2.4 配置验证与故障排查](#3.2.4 配置验证与故障排查)

四、本章练习题及答案

[4.1 选择题](#4.1 选择题)

[4.2 填空题](#4.2 填空题)

[4.3 简答题](#4.3 简答题)

[4.4 实操题](#4.4 实操题)

前言

在大语言模型（LLM）应用开发如火如荼的今天，每一位开发者都面临着同样的困境：为什么我的 AI 应用突然回答得这么离谱？是提示词写错了，还是模型产生了幻觉？是检索环节出了问题，还是上下文传递有遗漏？

传统的软件调试工具在面对 LLM 应用时显得力不从心。LLM 的非确定性本质意味着，同样的输入在不同时间可能产生完全不同的输出，这使得传统的断点调试和日志打印方法难以奏效。我们无法像调试普通函数那样，简单地通过查看输入输出来定位问题，因为问题的根源往往隐藏在复杂的提示词设计、多步推理链路、工具调用顺序以及上下文管理中。

这正是 LangSmith 诞生的背景。作为 LangChain 团队推出的官方 LLM 应用开发平台，LangSmith 提供了一套完整的可观测性、评估和提示词管理解决方案。它能够自动捕获应用中每一次 LLM 调用的详细信息，以可视化追踪树的形式展现代码的执行逻辑，并提供强大的评估框架来量化应用性能。

本教程将从零开始，带你全面掌握 LangSmith 的使用方法。无论你是后端工程师、AI 爱好者，还是正在学习大模型技术的学生，本文都将为你提供从基础概念到实战应用的全方位指导。我们将通过大量可运行的代码示例、详细的注释以及配套的练习题，帮助你在实践中真正掌握这一强大的工具。

一、LangSmith 概念详解

1.1 什么是 LangSmith？

LangSmith 是由 LangChain 团队开发的一个专门用于监控、调试、测试和评估 LLM 应用程序的综合性平台。它的核心使命是帮助开发者将 LLM 应用从原型阶段顺利推向生产环境，解决 LLM 应用开发中最棘手的可观测性和可靠性问题。

简单来说，如果你的 LLM 应用是一个复杂的迷宫，那么 LangSmith 就是悬挂在迷宫上方的一台无人机摄像机------它能够实时捕捉应用执行的每一个步骤，让你清晰地看到数据是如何流动的、每个环节产生了什么输出、耗时多久、消耗了多少 Token，以及最终是在哪里出现了偏差。

与传统的 APM（应用性能监控）工具不同，LangSmith 是专门为 LLM 应用设计的。它理解提示词、Token、嵌入向量这些 LLM 领域的概念，能够提供针对性的分析视角，而非仅仅停留在请求延迟和错误率这种通用指标上。

1.2 LangSmith 与 LangChain 的关系

很多初学者容易混淆 LangSmith 和 LangChain 这两个概念。实际上，它们是两个不同但高度互补的产品：

维度	LangChain	LangSmith
定位	开发框架	工程化平台
作用	帮助构建 LLM 应用	帮助调试、测试、监控 LLM 应用
使用阶段	开发阶段	开发 + 测试 + 生产阶段
核心产物	Chain、Agent、Tool 等组件	Trace、Dataset、Evaluation 等数据

打个比方：LangChain 就像是建筑施工用的脚手架和建材，帮助你搭建 LLM 应用的"骨架"；而 LangSmith 则是在建筑完工后安装的"监控系统"------它能实时报告每个房间的温度、湿度、能耗，并在出现异常时发出警报。

值得注意的是，LangSmith 虽然与 LangChain 深度集成，但它并非必须与 LangChain 一起使用。你可以在任何 Python 或 TypeScript 应用中通过 SDK 手动埋点，实现对自定义 LLM 工作流的追踪。

1.3 核心价值主张：可观测性

在软件工程中，"可观测性"是指通过分析系统的外部输出来推断其内部状态的能力。对于传统的微服务架构，可观测性通常由日志（Logging）、指标（Metrics）和追踪（Tracing）三大支柱构成。

LLM 应用的可观测性则提出了更高的要求：

非确定性行为的追踪：LLM 每次调用可能产生不同的输出，我们需要能够重现和分析这些差异。

提示词的可见性：最终发送给模型的提示词往往包含系统指令、历史对话、检索文档等多个动态拼接的部分，我们需要查看每一轮的完整提示词。

中间推理步骤的展示：Agent 应用可能涉及多轮"思考-行动-观察"循环，我们需要理解模型是如何一步步得出结论的。

成本与性能的量化：Token 消耗直接转化为成本，我们需要知道每个环节花费了多少。

LangSmith 正是围绕这些需求设计的。它通过自动捕获应用中每个 Runnable 组件的输入输出，构建出完整的执行追踪树，让开发者能够以极高的细粒度观察应用的内部运作。

二、主要功能详解

2.1 Prompt 调试与版本管理

提示词是 LLM 应用的灵魂。一个微小的措辞调整可能带来巨大的效果差异，而这种差异往往需要通过反复试验才能发现。

2.1.1 Playground 交互式调试

LangSmith 提供了一个强大的 Playground 环境，让你可以在 Web UI 中直接测试和迭代提示词。在这里，你可以：

实时修改提示词模板，观察模型响应的变化

调整模型参数（temperature、top_p、max_tokens 等）

切换不同的模型（GPT-4、Claude、Llama 等）进行对比

保存满意的提示词版本，直接同步到代码中

2.1.2 提示词版本管理

在生产环境中，提示词的变更是最频繁的操作之一。LangSmith 的提示词 Hub 提供了完善的版本管理能力：

将提示词作为代码进行版本控制，支持 commit、tag、branch 等 Git 风格的操作

通过 langsmith hub 命令行工具或 SDK 拉取指定版本的提示词

支持 A/B 测试，对比不同版本提示词的效果差异

代码示例：从 Hub 拉取提示词

python 复制代码

from langsmith import Client

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

# 从 Hub 拉取指定版本的提示词
# 格式: "用户名/提示词名:tag"
prompt = client.pull_prompt("your-username/qa-bot:production")

# 使用提示词
formatted = prompt.format(question="什么是 LangSmith？")
print(formatted)

2.1.3 提示词优化建议

结合评估结果，LangSmith 能够提供提示词优化建议。例如，当评估器检测到模型输出过于冗长时，平台可能会建议在提示词中添加"请用三句话以内回答"这样的约束指令。

2.2 Chain/Agent 执行流程可视化

这是 LangSmith 最直观、最令人惊叹的功能。当你通过 LangChain 构建了一个包含多个步骤的应用（例如：检索文档 -> 整合上下文 -> 调用 LLM -> 解析输出），LangSmith 会自动生成一棵完整的追踪树（Trace Tree）。

2.2.1 追踪树的结构

一次完整的应用执行称为一个 Trace 。Trace 内部包含多个层级嵌套的 Run：

Trace: 完整的请求-响应周期

│

├─ RunnableSequence: 整个 RAG 流程

│ │

│ ├─ Retriever: 向量检索

│ │ ├─ Embedding: 将问题转换为向量

│ │ └─ VectorStore: 相似度搜索

│ │

│ ├─ LLMChain: 生成回答

│ │ ├─ PromptTemplate: 渲染后的完整提示词

│ │ ├─ ChatModel: OpenAI API 调用

│ │ │ ├─ 耗时: 2.1s

│ │ │ ├─ Token 使用: prompt=450, completion=120

│ │ │ └─ 成本: $0.002

│ │ └─ OutputParser: 解析 LLM 输出

│ │

│ └─ ✅ 最终输出

2.2.2 Agent 推理过程的可视化

对于 Agent 应用，LangSmith 的可视化能力尤为强大。你可以清晰地看到 Agent 的每一步思考：

Trace: Agent 执行"查询今天北京的天气"

│

├─ Agent 思考: 需要调用天气 API

├─ Tool 调用: search_weather(city="北京")

│ └─ Tool 输出: "北京今天晴，22°C，微风"

│

├─ Agent 思考: 已获取天气信息，可以回答用户

└─ 💬 最终回答: "北京今天天气晴朗，气温22摄氏度，风力较小，适合户外活动。"

2.2.3 与传统日志的对比

传统日志往往是线性的文本输出，难以展示复杂的调用关系。而 LangSmith 的追踪树结构与 LCEL（LangChain Expression Language）的执行图完全同构，这意味着代码的嵌套结构直接反映在可视化界面上，极大地降低了调试的认知负担。

2.3 输出质量监控

生产环境中的 LLM 应用需要一个完善的质量监控体系。LangSmith 提供了一套完整的解决方案。

2.3.1 在线监控仪表盘

部署到生产环境后，LangSmith 的仪表盘会实时展示：

请求量（RPS）：每秒处理的请求数量

错误率：4xx/5xx 错误的比例

延迟分布：P50、P90、P99 延迟

Token 消耗：输入/输出 Token 的实时统计

成本估算：基于模型定价的实时成本计算

2.3.2 自动化评估

LangSmith 提供了丰富的评估器，可以对每次执行进行自动化评分：

基于标准答案的评估：

精确匹配（Exact Match）
正则表达式匹配
语义相似度（Embedding distance）

无参考答案的评估：

答案相关性（Answer relevance）
忠实度/幻觉检测（Faithfulness / Hallucination detection）
上下文相关性（Context relevance）

自定义评估器：

你可以编写任意的 Python 函数作为评估逻辑
支持使用 LLM 作为裁判（LLM-as-a-Judge）

2.3.3 人工反馈收集

对于需要人工审核的场景，LangSmith 提供了 Feedback API，允许你在应用中嵌入点赞/点踩按钮，将用户反馈直接关联到具体的 Trace 上。这些反馈数据可以用于后续的模型微调或提示词优化。

三、使用方法

3.1 准备工作：注册与 API Key 配置

3.1.1 注册 LangSmith 账号

访问 LangSmith 官网

使用 GitHub 或 Google 账号登录

进入 Settings → API Keys 页面

点击 Create API Key ，保存生成的密钥（格式通常以 ls__ 开头）

3.1.2 环境变量配置

LangSmith 通过环境变量与你的应用集成。推荐使用 .env 文件管理配置：

项目目录结构

my-langchain-project/

├── .env

├── requirements.txt

└── app.py

.env 文件内容

bash 复制代码

# LangSmith 配置
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=ls__你的密钥
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_PROJECT=my-first-project

# 如果你使用 OpenAI
OPENAI_API_KEY=sk-你的OpenAI密钥

重要提示 ：环境变量名是 LANGSMITH_API_KEY，而不是 LANGCHAIN_API_KEY。尽管旧版文档可能使用后者，但新版本统一使用 LANGSMITH_ 前缀。

3.1.3 安装依赖

bash 复制代码

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装 LangSmith 及相关依赖
pip install -U langsmith langchain langchain-openai python-dotenv

3.2 在 LangChain 代码中接入 LangSmith

接入过程非常简单------只需正确设置环境变量，LangChain 会自动完成所有追踪工作。你无需修改现有的业务代码。

3.2.1 基础示例：自动追踪

python 复制代码

"""
最简单的 LangSmith 接入示例
只需设置环境变量，LangChain 会自动追踪所有执行
"""

import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import StrOutputParser

# 加载 .env 文件中的环境变量
load_dotenv()

# 验证环境变量是否正确加载
required_vars = ["LANGSMITH_API_KEY", "LANGSMITH_PROJECT", "OPENAI_API_KEY"]
for var in required_vars:
    if not os.getenv(var):
        raise ValueError(f"请设置环境变量 {var}")

print(f"LangSmith 已启用，项目名称: {os.getenv('LANGSMITH_PROJECT')}")
print(f"LangSmith 端点: {os.getenv('LANGSMITH_ENDPOINT', 'https://api.smith.langchain.com')}")

# ------------------------------------------------------------
# 以下代码与没有 LangSmith 时完全相同
# 所有的执行细节都会被自动记录到 LangSmith 平台
# ------------------------------------------------------------

# 初始化模型
llm = ChatOpenAI(
    model="gpt-3.5-turbo",
    temperature=0.7,
)

# 创建提示词模板
prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一个乐于助人的助手，请用{language}回答问题。"),
    ("user", "{question}")
])

# 构建处理链
chain = prompt | llm | StrOutputParser()

# 执行调用 - 这次调用会被自动追踪
response = chain.invoke({
    "language": "中文",
    "question": "请解释一下什么是 LangSmith？"
})

print(f"\n回答: {response}")
print("\n提示: 请登录 LangSmith 控制台查看本次执行的详细追踪信息")

3.2.2 使用 @traceable 装饰器进行细粒度控制

虽然自动追踪已经能满足大部分需求，但有时你希望更精确地控制哪些函数被追踪，或者为追踪添加额外的元数据。这时可以使用 @traceable 装饰器。

python 复制代码

"""
使用 @traceable 装饰器进行手动追踪
适用于自定义函数或非 LangChain 组件的追踪
"""

import os
from dotenv import load_dotenv
from langsmith import traceable
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage

load_dotenv()

# 初始化 LLM
llm = ChatOpenAI(model="gpt-3.5-turbo")

@traceable(
    run_type="llm",  # 运行类型: llm, chain, tool, retriever, embedding 等
    name="custom_translation",  # 在追踪树中显示的名称
    metadata={
        "source_lang": "en",
        "target_lang": "zh",
        "version": "1.0"
    }  # 附加元数据
)
def translate_text(text: str, target_language: str = "中文") -> str:
    """
    翻译文本的自定义函数
    使用 @traceable 装饰器后，此函数的执行会被 LangSmith 记录
    """
    messages = [
        SystemMessage(content=f"你是一个专业的翻译，请将以下文本翻译成{target_language}，只输出翻译结果："),
        HumanMessage(content=text)
    ]
    
    response = llm.invoke(messages)
    return response.content

@traceable(run_type="chain", name="multi_step_processing")
def process_text(text: str) -> dict:
    """
    多步骤处理流程
    内部的子函数调用也会被自动记录到同一个 Trace 中
    """
    # 第一步：翻译成中文
    translated = translate_text(text, "中文")
    
    # 第二步：对翻译结果进行总结
    summary = summarize_text(translated)
    
    return {
        "original": text,
        "translated": translated,
        "summary": summary
    }

@traceable(run_type="llm", name="summarizer")
def summarize_text(text: str) -> str:
    """总结文本"""
    messages = [
        SystemMessage(content="请用一句话总结以下内容："),
        HumanMessage(content=text)
    ]
    response = llm.invoke(messages)
    return response.content

# 执行测试
if __name__ == "__main__":
    result = process_text(
        "LangSmith is a platform for building production-grade LLM applications. "
        "It provides debugging, monitoring, and evaluation capabilities."
    )
    
    print(f"原始文本: {result['original']}")
    print(f"翻译结果: {result['translated']}")
    print(f"一句话总结: {result['summary']}")

3.2.3 完整示例：RAG 应用的追踪

这是一个更贴近生产场景的完整 RAG（检索增强生成）应用示例，展示了 LangSmith 如何帮助我们调试复杂的多步骤流程。

python 复制代码

"""
完整的 RAG 应用 + LangSmith 追踪示例
演示：文档加载 -> 向量化 -> 检索 -> 生成的完整链路追踪
"""

import os
from dotenv import load_dotenv
from langsmith import traceable
from langchain_openai import OpenAIEmbeddings, ChatOpenAI
from langchain_community.document_loaders import TextLoader
from langchain_community.vectorstores import FAISS
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser

load_dotenv()

# ============================================================
# 第一步：准备知识库（仅需执行一次）
# ============================================================

def setup_vectorstore():
    """
    创建向量数据库
    实际项目中，这一步通常在数据准备阶段完成
    """
    # 创建示例文档（实际使用时替换为真实文件）
    documents = [
        "LangSmith是LangChain团队开发的LLM应用开发平台。",
        "LangSmith提供了调试、监控和评估三大核心功能。",
        "通过LangSmith的可视化追踪树，开发者可以清晰看到应用的每一步执行。",
        "LangSmith支持提示词版本管理，可以在多个版本之间进行A/B测试。",
        "LangSmith的评估框架支持自动化测试和人工反馈收集。",
    ]
    
    # 写入临时文件（演示用）
    with open("temp_knowledge.txt", "w", encoding="utf-8") as f:
        f.write("\n".join(documents))
    
    # 加载文档
    loader = TextLoader("temp_knowledge.txt", encoding="utf-8")
    docs = loader.load()
    
    # 文本分割
    text_splitter = RecursiveCharacterTextSplitter(
        chunk_size=100,
        chunk_overlap=20,
    )
    chunks = text_splitter.split_documents(docs)
    
    # 创建向量存储
    embeddings = OpenAIEmbeddings()
    vectorstore = FAISS.from_documents(chunks, embeddings)
    
    # 清理临时文件
    os.remove("temp_knowledge.txt")
    
    return vectorstore

# ============================================================
# 第二步：构建 RAG 链（带追踪）
# ============================================================

@traceable(run_type="retriever", name="knowledge_retrieval")
def retrieve_context(question: str, vectorstore):
    """
    检索相关上下文
    被 @traceable 装饰后，检索的输入、输出、耗时都会被记录
    """
    docs = vectorstore.similarity_search(question, k=2)
    context = "\n\n".join([doc.page_content for doc in docs])
    return context

@traceable(run_type="chain", name="rag_chain")
def answer_question(question: str, vectorstore) -> dict:
    """
    完整的 RAG 问答流程
    """
    # 步骤1：检索相关文档
    context = retrieve_context(question, vectorstore)
    
    # 步骤2：构建提示词
    prompt = ChatPromptTemplate.from_messages([
        ("system", """你是一个知识助手。请基于以下上下文回答用户的问题。
        如果上下文中没有相关信息，请诚实地说"我不知道"。
        
        上下文：
        {context}
        """),
        ("user", "{question}")
    ])
    
    # 步骤3：调用 LLM 生成回答
    llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
    
    chain = (
        {"context": RunnablePassthrough(), "question": RunnablePassthrough()}
        | prompt
        | llm
        | StrOutputParser()
    )
    
    answer = chain.invoke({"context": context, "question": question})
    
    return {
        "question": question,
        "context": context,
        "answer": answer
    }

# ============================================================
# 第三步：执行测试
# ============================================================

if __name__ == "__main__":
    # 初始化向量存储
    print("正在初始化知识库...")
    vectorstore = setup_vectorstore()
    
    # 测试问题列表
    test_questions = [
        "LangSmith是什么？",
        "LangSmith提供了哪些功能？",
        "LangSmith是谁开发的？",
        "今天天气怎么样？",  # 这个问题超出了知识库范围，测试"不知道"的情况
    ]
    
    # 逐个回答问题
    for question in test_questions:
        print(f"\n{'='*50}")
        print(f"问题: {question}")
        
        result = answer_question(question, vectorstore)
        
        print(f"检索到的上下文: {result['context']}")
        print(f"回答: {result['answer']}")
    
    print("\n完成！请登录 LangSmith 查看完整的追踪树")

3.2.4 配置验证与故障排查

有时候你可能遇到追踪未生效的情况，以下代码可以帮助你诊断配置问题：

python 复制代码

"""
LangSmith 配置验证脚本
运行此脚本检查你的环境配置是否正确
"""

import os
import sys
from dotenv import load_dotenv

load_dotenv()

def check_langsmith_config():
    """检查 LangSmith 配置"""
    print("=" * 50)
    print("LangSmith 配置检查")
    print("=" * 50)
    
    # 必需的环境变量
    required = {
        "LANGSMITH_API_KEY": "API 密钥",
        "LANGSMITH_TRACING": "追踪开关 (应为 'true')",
    }
    
    # 可选的环境变量
    optional = {
        "LANGSMITH_ENDPOINT": "API 端点",
        "LANGSMITH_PROJECT": "项目名称",
    }
    
    all_ok = True
    
    print("\n📋 检查必需配置:")
    for var, desc in required.items():
        value = os.getenv(var)
        if value:
            # 隐藏 API Key 的部分内容
            if var == "LANGSMITH_API_KEY" and len(value) > 10:
                display_value = value[:8] + "..." + value[-4:]
            else:
                display_value = value
            print(f"{var} = {display_value}")
        else:
            print(f"{var} 未设置 - {desc}")
            all_ok = False
    
    print("\n检查可选配置:")
    for var, desc in optional.items():
        value = os.getenv(var)
        if value:
            print(f"{var} = {value}")
        else:
            print(f"{var} 未设置 (将使用默认值) - {desc}")
    
    # 测试连接
    if all_ok and os.getenv("LANGSMITH_API_KEY"):
        print("\n🔗 测试 LangSmith 连接...")
        try:
            from langsmith import Client
            client = Client()
            # 尝试获取项目列表（轻量级请求）
            projects = client.list_projects(limit=1)
            print("连接成功！可以正常使用 LangSmith")
        except Exception as e:
            print(f"连接失败: {e}")
            all_ok = False
    
    return all_ok

if __name__ == "__main__":
    if check_langsmith_config():
        print("\n配置正确！现在可以开始使用 LangSmith 了")
    else:
        print("\n配置存在问题，请检查后重试")
        sys.exit(1)

四、本章练习题及答案

4.1 选择题

第1题：LangSmith 的主要定位是什么？

A. LLM 模型训练框架
B. LLM 应用开发框架
C. LLM 应用监控、调试和评估平台
D. LLM 模型部署工具

答案：C

解析：LangSmith 是 LangChain 团队开发的工程化平台，专注于 LLM 应用的可观测性、调试和评估，而非模型训练或部署。

第2题：以下哪个环境变量是启用 LangSmith 追踪所必需的？

A. LANGCHAIN_API_KEY
B. LANGSMITH_TRACING
C. OPENAI_API_KEY
D. LANGSMITH_ENDPOINT

答案：B

解析：LANGSMITH_TRACING 必须设置为 true 才能启用追踪功能。LANGSMITH_API_KEY 也是必需的（虽然选项中没有列出），而 OPENAI_API_KEY 是 OpenAI 服务的凭证，与 LangSmith 本身无关。

第3题：关于 LangSmith 的追踪树（Trace Tree），以下描述正确的是？

A. 追踪树只能显示线性的执行顺序
B. 追踪树的每个节点只能包含文本信息
C. 追踪树能够展示嵌套的调用关系，如 Chain 内部的 Prompt 和 LLM 调用
D. 追踪树只能在应用执行完成后生成

答案：C

解析：追踪树的核心优势就是能够展示嵌套的执行结构，每个 Run 节点可以包含子节点，清晰地反映 LCEL 的执行图。

第4题：以下哪种评估方式不需要预先准备标准答案？

A. 精确匹配
B. 正则表达式匹配
C. 答案相关性（Answer Relevance）
D. 语义相似度

答案：C

解析：答案相关性评估是将模型的输出与用户的问题进行比较，判断回答是否切题，不需要参考答案。而精确匹配、正则匹配和语义相似度都需要一个标准的正确答案作为参照。

第5题：LangSmith 与 LangChain 的关系是？

A. LangSmith 是 LangChain 的替代品
B. LangSmith 必须与 LangChain 一起使用
C. LangSmith 可以独立使用，但与 LangChain 集成时体验最佳
D. LangSmith 是 LangChain 的旧版本名称

答案：C

解析：LangSmith 虽然是 LangChain 团队开发的，但它可以与任何 LLM 应用框架配合使用。不过与 LangChain 集成时，可以实现自动追踪，无需手动埋点。

4.2 填空题

第1题 ：在 Python 代码中，可以使用 ________ 装饰器来手动标记一个函数，使其执行过程被 LangSmith 追踪。

答案：@traceable

解析：from langsmith import traceable 后使用 @traceable() 装饰器，可以精细控制追踪行为。

第2题 ：LangSmith 中一次完整的请求-响应周期称为一个 ________，其内部的每一步执行称为一个 ________。

答案：Trace；Run

解析：Trace 代表一次完整的应用执行，Run 代表其中的一个步骤（如一次 LLM 调用、一次检索操作等）。

第3题 ：要从 LangSmith Hub 拉取提示词，可以使用 client.________("用户名/提示词名:tag") 方法。

答案：pull_prompt

解析：pull_prompt 方法用于从 Hub 获取指定版本的提示词模板。

第4题 ：设置环境变量 LANGSMITH_PROJECT 的作用是指定追踪数据所属的 ________，用于数据分类和管理。

答案：项目（Project）

解析：Project 是 LangSmith 中组织 Trace 的逻辑单元，类似于标签或文件夹。

第5题 ：LangSmith 的评估框架中，使用 LLM 来判断另一个 LLM 的输出质量，这种方式被称为 ________。

答案：LLM-as-a-Judge

解析：这是评估 LLM 输出的常见模式，让一个模型评估另一个模型的输出。

4.3 简答题

第1题：请简述 LLM 应用开发相比传统软件开发，在调试方面面临哪些独特挑战？LangSmith 是如何应对这些挑战的？

参考答案：

LLM 应用开发面临的独特挑战包括：

非确定性输出：同样的输入在不同时间可能得到不同的输出，传统断点调试无法复现问题。

黑箱特性：LLM 内部的推理过程不可见，难以定位问题根源。

复杂的上下文管理：RAG 应用涉及检索、Prompt 拼接、多轮对话管理等环节，任何一个环节出错都会影响最终输出。

成本考量：每次 LLM 调用都有 Token 成本，需要量化和优化。

LangSmith 的应对方案：

完整追踪记录：记录每一次执行的输入、输出、耗时、Token 消耗，支持历史回溯和对比。

可视化追踪树：以嵌套结构展示执行流程，让黑箱变透明。

自动捕获上下文：自动记录 Prompt 渲染结果、检索文档内容、中间变量值等。

成本监控仪表盘：实时展示 Token 消耗和成本估算，帮助优化。

第2题：解释 LangSmith 中 Trace、Run 和 Project 三个核心概念及其关系。

参考答案：

Trace（调用链）：代表一次完整的应用执行周期，从接收用户输入到返回最终结果。一个 Trace 包含唯一的 ID，用于关联该次执行中的所有步骤。

Run（运行步骤）：是 Trace 的组成单元，代表一次具体的操作，如一次 LLM API 调用、一次向量检索、一个 Chain 的执行。Run 之间可以存在父子关系，形成树状结构。每个 Run 记录了操作类型、输入、输出、耗时、Token 使用等元数据。

Project（项目） ：是 Trace 的逻辑分组单元，用于按应用、环境或团队分类管理追踪数据。通过设置 LANGSMITH_PROJECT 环境变量，可以将不同场景的 Trace 隔离到不同的 Project 中（如开发环境用 dev 项目，生产环境用 prod 项目）。

关系：一个 Project 包含多个 Trace，一个 Trace 包含多个 Run（树形结构）。Project 是管理维度，Trace 是执行实例维度，Run 是步骤维度。

第3题：如何在 LangSmith 中评估一个 RAG 应用的检索质量？请列出至少两种评估方法。

参考答案：

RAG 应用的检索质量评估可以从以下维度进行：

上下文相关性评估：

方法：使用 LangSmith 的内置评估器 ContextRelevanceEvaluator

原理：让 LLM 判断检索到的文档内容是否与用户问题相关

无需参考答案，适合快速验证

上下文召回率评估：

方法：将检索到的文档与标准答案中的关键信息进行比对

原理：计算标准答案中有多少关键信息出现在检索文档中

需要预先准备包含标准答案的数据集

精确匹配评估：

方法：检查检索结果中是否包含预期的文档 ID 或内容片段

原理：适用于已知正确答案来源的场景

简单直接，但灵活性较低

自定义评估器：

方法：编写 Python 函数，使用向量相似度计算问题与检索文档的语义距离

原理：将问题和文档分别嵌入，计算余弦相似度

灵活可控，可根据业务需求定制

4.4 实操题

题目：使用 LangSmith 构建一个带有评估功能的客服问答系统

要求：

创建一个简单的客服问答应用，支持用户提问产品相关问题
在 LangSmith 中创建一个测试数据集，包含至少 3 个测试用例（问题 + 预期答案）
运行评估，使用 LangSmith 的内置评估器计算准确率
编写代码实现上述功能，并提供详细注释

参考答案：

python 复制代码

"""
客服问答系统 + LangSmith 评估完整示例
演示：数据集创建 -> 批量运行 -> 自动化评估
"""

import os
from dotenv import load_dotenv
from langsmith import Client
from langsmith.evaluation import evaluate
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

load_dotenv()

# ============================================================
# 第一部分：初始化
# ============================================================

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

# 初始化 LLM
llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)

# 客服问答的提示词模板
CUSTOMER_SERVICE_PROMPT = ChatPromptTemplate.from_messages([
    ("system", """你是一个专业的客服助手，专门回答关于 Acme 公司产品的问题。

产品信息：
- Acme Pro：专业版，售价 299 元/月，支持团队协作，包含数据分析功能
- Acme Basic：基础版，售价 99 元/月，支持个人使用，包含核心功能
- Acme Free：免费版，包含基础功能，限制 100 次调用/月

请基于以上信息回答用户问题。如果问题超出知识范围，请礼貌地说"这个问题我需要咨询技术团队"。
"""),
    ("user", "{question}")
])

# 构建问答链
qa_chain = CUSTOMER_SERVICE_PROMPT | llm

# ============================================================
# 第二部分：创建测试数据集
# ============================================================

def create_test_dataset():
    """在 LangSmith 中创建测试数据集"""
    
    # 定义测试用例
    test_cases = [
        {
            "question": "Acme Pro 版本的价格是多少？",
            "expected_answer": "299 元/月"
        },
        {
            "question": "免费版有什么限制？",
            "expected_answer": "限制 100 次调用/月"
        },
        {
            "question": "Basic 版本支持团队协作吗？",
            "expected_answer": "不支持，Basic 版本仅支持个人使用"
        }
    ]
    
    # 检查数据集是否已存在
    try:
        dataset = client.read_dataset(dataset_name="客服问答测试集")
        print(f"数据集已存在: {dataset.name}")
        return dataset
    except:
        pass
    
    # 创建新数据集
    dataset = client.create_dataset(
        dataset_name="客服问答测试集",
        description="客服问答系统的测试数据集",
    )
    
    # 添加测试用例
    for case in test_cases:
        client.create_example(
            inputs={"question": case["question"]},
            outputs={"answer": case["expected_answer"]},
            dataset_id=dataset.id,
        )
    
    print(f"数据集创建成功: {dataset.name}，包含 {len(test_cases)} 个测试用例")
    return dataset

# ============================================================
# 第三部分：定义预测函数
# ============================================================

def predict(question: str) -> dict:
    """
    预测函数：输入问题，返回模型的回答
    这个函数会被 evaluate 函数调用
    """
    response = qa_chain.invoke({"question": question})
    return {"output": response.content}

# ============================================================
# 第四部分：定义评估器
# ============================================================

def accuracy_evaluator(run, example) -> dict:
    """
    准确率评估器
    检查模型的回答是否包含预期的关键词
    """
    predicted = run.outputs.get("output", "").lower()
    expected = example.outputs.get("answer", "").lower()
    
    # 简单检查：预期答案是否出现在模型回答中
    is_correct = expected in predicted
    
    return {
        "key": "accuracy",
        "score": 1.0 if is_correct else 0.0,
        "comment": f"预期包含: {expected} | 实际: {predicted[:100]}"
    }

def length_evaluator(run, example) -> dict:
    """
    回答长度评估器
    检查回答是否过长或过短（用于优化体验）
    """
    predicted = run.outputs.get("output", "")
    length = len(predicted)
    
    # 理想长度范围：20-200 字符
    if 20 <= length <= 200:
        score = 1.0
        comment = "回答长度适中"
    elif length < 20:
        score = 0.5
        comment = "回答过短"
    else:
        score = 0.5
        comment = "回答过长"
    
    return {
        "key": "length_score",
        "score": score,
        "comment": comment
    }

# ============================================================
# 第五部分：运行评估
# ============================================================

def run_evaluation(dataset):
    """运行评估并输出结果"""
    
    print("\n" + "="*50)
    print("开始运行评估...")
    print("="*50)
    
    # 运行评估
    experiment_results = evaluate(
        predict,                    # 预测函数
        data=dataset.name,          # 数据集名称
        evaluators=[                # 评估器列表
            accuracy_evaluator,
            length_evaluator,
        ],
        experiment_prefix="客服问答评估",
        metadata={"version": "1.0"},
    )
    
    # 输出结果摘要
    print("\n" + "="*50)
    print("评估结果摘要")
    print("="*50)
    
    # 获取结果
    results = list(experiment_results)
    
    total = len(results)
    correct_count = 0
    
    for result in results:
        # 获取准确率评分
        for feedback in result.get("feedback", []):
            if feedback.key == "accuracy" and feedback.score == 1.0:
                correct_count += 1
                break
    
    accuracy = correct_count / total if total > 0 else 0
    print(f"总测试用例数: {total}")
    print(f"准确数量: {correct_count}")
    print(f"准确率: {accuracy:.1%}")
    
    return experiment_results

# ============================================================
# 第六部分：交互式测试
# ============================================================

def interactive_test():
    """交互式测试模式"""
    print("\n" + "="*50)
    print("进入交互式测试模式（输入 'quit' 退出）")
    print("="*50)
    
    while True:
        question = input("\n请输入问题: ").strip()
        if question.lower() == 'quit':
            break
        
        response = qa_chain.invoke({"question": question})
        print(f"回答: {response.content}")

# ============================================================
# 主程序
# ============================================================

if __name__ == "__main__":
    print("客服问答系统启动")
    
    # 1. 创建数据集
    dataset = create_test_dataset()
    
    # 2. 运行评估
    run_evaluation(dataset)
    
    # 3. 交互式测试
    interactive_test()
    
    print("\n完成！请登录 LangSmith 查看详细的评估报告")

运行说明：

确保 .env 文件中已配置 LANGSMITH_API_KEY 和 OPENAI_API_KEY

运行脚本：python customer_service_eval.py

登录 LangSmith 控制台，查看：

创建的数据集 客服问答测试集

评估实验的详细结果

每个测试用例的预测输出和评分

总结

通过本教程的学习，我们已经全面掌握了 LangSmith 的核心概念和实战技能。让我们回顾一下关键要点：

核心收获

概念层面：

LangSmith 不仅仅是另一个监控工具，它是专门为 LLM 应用设计的全链路可观测性平台。它理解提示词、Token、向量检索这些 LLM 领域的特有概念，能够提供比传统 APM 工具更深层次的洞察。LangSmith 与 LangChain 形成完美的互补关系------LangChain 负责构建，LangSmith 负责验证和优化。

功能层面：

LangSmith 的三大支柱功能------可观测性、评估和提示词管理------构成了 LLM 应用工程化的完整闭环。可观测性让我们能够"看见"应用内部的执行过程；评估让我们能够"量化"应用的质量水平；提示词管理让我们能够"迭代"和"优化"应用的性能。

实践层面：

通过本教程中的代码示例，我们已经掌握了：

如何使用环境变量快速接入 LangSmith

如何使用 @traceable 装饰器进行精细化追踪

如何创建和管理测试数据集

如何编写自定义评估器并进行批量评估

从入门到精通的学习路径

对于刚刚开始使用 LangSmith 的开发者，建议按以下路径逐步深入：

入门阶段：先学会配置环境变量，让 LangChain 应用自动生成 Trace。登录控制台查看追踪树，熟悉各个字段的含义。

进阶阶段：学会使用 Playground 调试提示词，创建简单的测试数据集，运行基础的评估实验。

精通阶段：掌握自定义评估器的编写，构建完整的 CI/CD 评估流水线，将评估结果集成到开发流程中，实现自动化优化。

最佳实践建议

尽早引入评估：不要等到应用上线后再考虑评估。在开发阶段就建立测试数据集和评估基准，可以帮助你更快地发现问题和迭代优化。

合理划分项目 ：使用 LANGSMITH_PROJECT 按环境（dev/staging/prod）或功能模块划分项目，便于数据隔离和问题定位。

结合人工反馈：在生产环境中收集用户反馈（点赞/点踩），将其作为评估的重要数据源，形成持续优化的闭环。

成本意识：虽然 LangSmith 本身功能强大，但大规模的评估和长时间的 Trace 存储会带来成本。建议合理设置采样率，对生产环境的关键请求进行全量追踪，对非关键请求进行采样追踪。

未来展望

随着 LLM 技术的快速发展，LangSmith 也在持续演进。未来，我们可以期待更多智能化功能的加入，如自动化的提示词优化建议、更丰富的评估指标体系、以及与更多第三方工具的无缝集成。

无论你是刚开始探索 LLM 应用开发的新手，还是正在构建生产级 AI 系统的资深工程师，LangSmith 都将成为你工具箱中不可或缺的利器。希望通过本教程的学习，你已经能够自信地将 LangSmith 应用到实际项目中，构建出更加可靠、可控、可优化的 LLM 应用。

下一步行动：

注册 LangSmith 账号，完成第一个追踪

将本教程中的代码示例改写并应用到你的项目中

阅读 LangSmith 官方文档，探索更多高级功能

加入 LangChain 社区，与其他开发者交流经验

祝你在 LLM 应用开发的道路上越走越远！

🌟 感谢您耐心阅读到这里！

🚀 技术成长没有捷径，但每一次的阅读、思考和实践，都在默默缩短您与成功的距离。

💡 如果本文对您有所启发，欢迎点赞👍、收藏📌、分享📤给更多需要的伙伴！

🗣️ 期待在评论区看到您的想法、疑问或建议，我会认真回复，让我们共同探讨、一起进步～

🔔 关注我，持续获取更多干货内容！

🤗 我们下篇文章见！