第11章 LangSmith 调试与综合项目

第11章 LangSmith 调试与综合项目

1. 本章目标

前面章节已经完成了 LangChain 的核心能力：

• 调用 DeepSeek
• 使用 Prompt 模板
• 结构化输出
• LCEL 链式调用
• 文档加载与切分
• Embedding 和向量数据库
• RAG 知识库问答
• Tool 和 Agent

应用能跑起来之后，如何调试、观察和评估效果？

学完本章后，你应该能够：

• 理解 LangSmith 的作用
• 开启 LangChain 调用追踪
• 在 LangSmith 中查看模型调用、Prompt、Token 和耗时
• 给不同项目设置追踪名称
• 给运行过程添加标签和元数据
• 编写简单的测试集评估 RAG 效果
• 编写简单的测试集评估 Agent 工具调用
• 完成一个课程综合项目
• 理解上线前应该检查哪些关键问题

2. 为什么需要 LangSmith

在简单案例中，我们通常只看终端输出：

你需要知道：

• 用户原始问题是什么
• Retriever 检索到了哪些文档
• Prompt 最终长什么样
• 模型输入了多少 Token
• 模型输出了什么
• 哪一步耗时最长
• Agent 有没有调用工具
• 工具参数是否正确
• 工具返回了什么

LangSmith 就是用来观察、调试和评估大模型应用的平台。

它可以把一次 LangChain 调用记录成完整链路。

3. LangSmith 能看到什么

开启追踪后，LangSmith 中可以看到：

对于 RAG 项目，重点看：

• 检索问题是否正确
• 检索结果是否相关
• 上下文是否传给模型
• 模型是否根据资料回答

对于 Agent 项目，重点看：

• 是否调用了工具
• 调用了哪个工具
• 工具参数是否正确
• 工具结果是否被模型正确使用

4. 开通和配置 LangSmith

访问：

https://smith.langchain.com

登录后创建 API Key。

在项目根目录创建 .env：

DEEPSEEK_API_KEY=你的DeepSeek API Key
DEEPSEEK_BASE_URL=https://api.deepseek.com

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=你的LangSmith API Key
LANGSMITH_PROJECT=langchain-work-demo

环境变量说明：

如果暂时不想开启 LangSmith，可以改成：

LANGSMITH_TRACING=false

5. 安装依赖

安装本章依赖：

pip install langsmith

6. 案例一：追踪一次普通模型调用

创建 01_trace_chat.py：

from utils.model_factory import get_deepSeek_model

model=get_deepSeek_model()
respone=model.invoke("帅哥为什么这么帅？")
print(respone.content)

运行结果如下：终端界面：

 如果 .env 中配置了

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=…
LANGSMITH_PROJECT=langchain-course-demo

运行后就可以在 LangSmith 项目中看到这次调用。

你可以重点查看：

• 输入内容
• 模型输出
• 调用耗时
• Token 消耗
• 模型名称

langsmith界面：

打开这个项目可以看到：

7. 案例二：追踪 LCEL Chain

创建 02_trace_chain.py：

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate

from utils.model_factory import get_deepSeek_model

model = get_deepSeek_model()

prompt_template = ChatPromptTemplate.from_messages(
[
(
"system",
"你是一名编程课程讲师，回答要适合初学者。",
),
(
"human",
"请用不超过 150 字解释：{topic}",
)
]
)

chain = prompt_template | model | StrOutputParser()

result = chain.invoke(
{
'topic':'RAG检索增强生成'
},
config = {
'run_name':'concept_explain_chain',
'tags':['chapter10','lcel'],
'metadata':{
'course':'langChain',
'chapter':10
}
}
)

print(result)

这里的 config 可以给本次运行增加信息：

config={
"run_name": "concept_explain_chain",
"tags": ["chapter10", "lcel"],
"metadata": {
"course": "LangChain",
"chapter": 10,
},
}

在 LangSmith 中，run_name、tags 和 metadata 可以帮助你筛选和定位调用记录。

这些都是我们配置的信息：

过滤：

8. 案例三：追踪 Agent 工具调用

创建 03_trace_agent.py：

from langchain.agents import create_agent
from langchain_core.tools import tool

from utils.model_factory import get_deepSeek_model

@tool
def get_order_status(order_id:str) -> str:
"""根据订单号查询订单状态，包括是否付款、是否发货、快递单号和签收状态。"""
fake_orders = {
"A1001": "已付款，等待发货",
"A1002": "已发货，快递单号 SF123456",
"A1003": "已签收",
}

return fake_orders.get(order_id, "没有查询到该订单")

model = get_deepSeek_model()

agent = create_agent(
model = model,
tools = [get_order_status],
system_prompt = "你是一名电商客服助手，必须根据工具结果回答订单问题。"
)

result = agent.invoke(
{
'messages':[
{
'role':'user',
'content':'帮我查一下订单A1002发货了么'
}

]
},

config = {
'run_name':'order_agent_demo_run', # trace的名字
'tags':['chapter10','agent','tool'],
'metadata':{
'name':'order_agent_demo_meta', #Metadata_name
'biz': ' ecommerce'
},
}

)

print(result['messages'][-1].content)

在 LangSmith 中可以看到：

用户问题
-> 模型请求调用 get_order_status
-> 工具返回订单状态
-> 模型生成最终回答

用户提问 → 大模型识别需要调用工具 → 调用查询订单接口 → 获取接口数据 → 大模型把原始数据整理成自然语言回答用户

这对调试 Agent 非常有用。

如果 Agent 没有调用工具，可以在 Trace 中检查：

• 工具描述是否传给模型
• 用户问题是否包含订单号
• 模型是否直接生成了答案
• 工具调用参数是否错误