🎯 前言

上一篇我们搞定了 Checkpoint断点持久化，解决了AI工作流「中断丢进度、重复执行、稳定性差」的生产级问题，让我们的LangGraph项目真正具备线上运行的基础条件。

但随着工作流越来越复杂：分支路由、并行任务、循环迭代、子流程嵌套、断点续传叠加，我们会遇到新的调试痛点：

• 本地代码正常，线上运行莫名报错，完全找不到问题节点

• 工作流执行耗时过长，不知道是模型慢、节点慢还是逻辑冗余

• 多轮迭代、子流程嵌套执行，看不到完整执行链路，流程黑盒

• 报错只有笼统提示，无法定位具体：哪一步出错、入参是什么、状态怎么变

• 无法统计Token消耗、调用次数、模型耗时，成本完全不可控

如果说Checkpoint是AI项目的稳定性兜底，那 LangSmith 就是企业AI项目的可视化监控与调试神器。

本篇零基础手把手实战LangSmith全链路监控，无需复杂部署、一行代码开启，实现全流程可视化、日志追溯、性能分析、报错精准定位、成本统计，彻底告别AI工作流黑盒调试，是大厂生产环境标配工具。

一、LangSmith核心认知（小白一次性弄懂）

1.1 什么是LangSmith？

LangSmith 是 LangChain 官方配套的大模型应用全链路监控、调试、评测平台，完美适配所有 LangGraph 工作流。

它可以把我们看不见的代码执行过程、节点流转、状态变化、模型调用、耗时消耗，全部可视化展示在网页后台。

1.2 核心解决的问题

• 解决流程黑盒：清晰看到每一个节点执行顺序、是否执行、是否跳过

• 解决报错难定位：精准定位报错节点、错误原因、入参出参

• 解决性能未知：统计每个节点耗时、模型响应耗时、总链路耗时

• 解决成本不可控：实时统计输入/输出Token、单次消耗、累计消耗

• 解决无法复盘：所有运行记录永久留存，支持随时回溯复盘

1.3 企业生产必备理由

个人Demo可以靠print打印调试，企业级复杂AI系统绝对不能靠print。

线上排查问题、迭代优化性能、核算模型成本、优化Prompt、修复隐性Bug，全部依赖LangSmith，是2026年大模型工程化的标准刚需工具。

二、LangSmith核心能力清单

• 全链路可视化追踪：DAG流程图动态展示执行路径，分支、循环、子流程一目了然

• 细粒度日志记录：每一步State状态变更、入参、出参、Prompt内容完整留存

• 性能耗时分析：节点耗时、LLM耗时、网络耗时精准拆分

• Token成本统计：精准统计单次调用、累计调用Token消耗

• 报错堆栈定位：运行异常精准定位到具体代码节点与原因

• 会话线程管理：按thread_id分类所有任务，断点续传流程完整追溯

• 项目分组管理：多项目、多环境隔离，适配大型项目迭代

三、前期准备：账号与密钥配置

3.1 注册账号（免费够用）

直接官网注册：www.langsmith.com，支持Github/邮箱登录，个人免费额度完全满足学习、测试、小型项目使用。

3.2 获取API Key

1. 登录后台，进入个人设置（Settings）

2. 找到 API Keys 栏目

3. 新建密钥，复制生成的LANGSMITH_API_KEY

无需部署服务器、无需搭建数据库，开箱即用。

3.3 环境依赖

本系列环境已自带，无需额外安装，确保版本匹配即可：

pip install langchain==0.3.0
pip install langgraph==1.1.0
pip install langchain-openai python-dotenv

四、完整可运行实战代码（开启全链路监控）

基于上一篇断点续传迭代工作流改造，全程无侵入、一行配置开启LangSmith监控，完美兼容断点持久化能力。

from dotenv import load_dotenv
import os
import time
from typing import TypedDict, Literal
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import MemorySaver

# 加载环境变量
load_dotenv()

# ===================== LangSmith核心监控配置（全局开启）=====================
# 开启全链路追踪
os.environ["LANGCHAIN_TRACING_V2"] = "true"
# 填写你的LangSmith密钥
os.environ["LANGCHAIN_API_KEY"] = os.getenv("LANGSMITH_API_KEY")
# 项目名称（后台自动分组展示）
os.environ["LANGCHAIN_PROJECT"] = "LangGraph-2026-生产级实战"
# =========================================================================

# --------------------------
# 1、全局状态定义
# --------------------------
class IterState(TypedDict):
    user_requirement: str
    content: str
    check_result: str
    iter_count: int

# --------------------------
# 2、模型与持久化初始化
# --------------------------
llm = ChatOpenAI(
    api_key=os.getenv("API_KEY"),
    base_url=os.getenv("BASE_URL"),
    model="gpt-3.5-turbo",
    temperature=0.3
)

# 内存断点持久化
memory = MemorySaver()

# --------------------------
# 3、业务节点定义
# --------------------------
def create_content(state: IterState) -> IterState:
    prompt = f"根据需求撰写一篇优质短文案：{state['user_requirement']}"
    res = llm.invoke(prompt)
    state["content"] = res.content.strip()
    state["iter_count"] = 0
    return state

def check_content(state: IterState) -> IterState:
    prompt = f"""
    质检文案，达标输出【达标】，不达标输出【不达标】+优化问题
    文案：{state['content']}
    """
    res = llm.invoke(prompt)
    state["check_result"] = res.content.strip()
    return state

def optimize_content(state: IterState) -> IterState:
    time.sleep(1.5)
    prompt = f"""
    根据问题优化文案，只修复瑕疵不重写整体：
    原文：{state['content']}
    问题：{state['check_result']}
    """
    res = llm.invoke(prompt)
    state["content"] = res.content.strip()
    state["iter_count"] += 1
    print(f"✅ 第{state['iter_count']}次迭代优化完成")
    return state

# --------------------------
# 4、循环路由逻辑
# --------------------------
def route_iter(state: IterState) -> Literal["optimize", "end"]:
    if state["iter_count"] >= 3:
        return "end"
    if "达标" in state["check_result"]:
        return "end"
    return "optimize"

# --------------------------
# 5、搭建带监控+断点的生产工作流
# --------------------------
graph = StateGraph(IterState)
graph.add_node("create_content", create_content)
graph.add_node("check_content", check_content)
graph.add_node("optimize", optimize_content)

graph.add_edge(START, "create_content")
graph.add_edge("create_content", "check_content")
graph.add_conditional_edges("check_content", route_iter, {"optimize": "optimize", "end": END})
graph.add_edge("optimize", "check_content")

# 绑定持久化+监控
iter_workflow = graph.compile(checkpointer=memory)

# --------------------------
# 6、运行测试
# --------------------------
if __name__ == "__main__":
    config = {"configurable": {"thread_id": "2026_langsmith_demo_001"}}
    user_req = "写一篇零基础AI学习入门短文案，适合新手、简洁吸引人"
    result = iter_workflow.invoke({"user_requirement": user_req}, config=config)

    print("\n🎉 任务执行完成！")
    print("最终文案：", result["content"])
    print("最终迭代次数：", result["iter_count"])
    print("\n👉 前往LangSmith后台查看全链路监控日志")

五、.env环境变量配置（关键）

在本地.env文件中新增一行LangSmith密钥，和大模型密钥同级配置：

API_KEY=你的大模型密钥
BASE_URL=你的代理地址
LANGSMITH_API_KEY=你的LangSmith密钥

六、后台监控页面全功能解读

运行代码后，打开LangSmith后台，即可看到本次完整运行记录，核心可查看四大核心数据：

6.1 可视化执行链路

系统自动绘制DAG执行流程图，清晰展示：

• 哪些节点成功执行

• 分支路由走了哪条路径

• 循环迭代执行了几次

• 哪些节点被跳过、哪些节点重复执行

彻底告别代码猜逻辑，流程流转100%可视化。

6.2 完整状态追溯

每一个节点执行前后的 State全局状态 全部留存：

用户需求、初稿内容、质检结果、迭代次数，每一次变更都可回溯，精准定位状态异常问题。

6.3 耗时性能分析

后台自动拆分耗时明细：

• LLM模型响应耗时

• 节点代码执行耗时

• 整体链路总耗时

轻松优化瓶颈节点，大幅提升工作流响应速度。

6.4 Token成本统计

自动统计：输入Token、输出Token、单次消耗，长期运行可直观看到整体成本，避免盲目消耗。

七、报错调试实战演示

当工作流线上报错时，LangSmith可以直接定位：

1. 精准定位报错具体节点

2. 查看报错前的入参数据是否异常

3. 查看Prompt是否存在问题

4. 查看模型返回结果是否为空/异常

相比本地print调试，效率提升10倍以上，是线上排错的唯一方案。

八、新手高频坑点避坑指南

坑1：开启追踪后看不到日志

原因：LANGCHAIN_TRACING_V2 未设置为 true、密钥填写错误、网络不通。

解决：严格核对三个环境变量，确保全部配置生效。

坑2：项目名称混乱，日志杂乱

解决：不同业务工作流配置不同 LANGCHAIN_PROJECT，自动分组归类，方便管理。

坑3：只监控模型，不监控节点

说明：新版LangGraph默认全链路监控，包含自定义节点、LLM调用、状态变更，无需额外配置。

坑4：本地正常，后台无记录

解决：代码运行必须走完完整链路，中途强制终止可能导致日志上报不全。

九、生产级高阶用法

1. 团队协作监控：多人共用密钥，统一后台查看所有项目日志，团队排错协同

2. 版本迭代对比：不同版本工作流执行效果、耗时、Token消耗对比，精准优化

3. 自定义标签分组：按场景、版本、环境打标签，批量管理任务

4. 告警通知配置：任务报错、超时自动推送通知，实时感知线上异常

5. 数据集评测：基于历史运行日志，快速构建评测数据集，迭代模型与Prompt效果

十、零基础自测巩固

1、LangSmith在AI工程化落地中的核心作用是什么？

2、开启LangSmith全链路监控必须配置的三个环境变量是什么？

3、相比传统print打印调试，LangSmith的核心优势体现在哪里？

✅ 本篇核心总结

1、LangSmith是LangGraph企业级落地的标配监控工具，彻底解决AI工作流黑盒问题；

2、一行配置即可开启全链路追踪，可视化流程、状态、耗时、Token、报错信息；

3、搭配上一篇Checkpoint断点持久化，实现稳定运行+可监控、可追溯、可排错的生产双保障；

4、所有线上AI Agent、复杂工作流，必须开启LangSmith监控，是工程化成熟的标志。

📌 下一篇预告

第十四篇：【2026零基础AI教程14】LangGraph异常熔断、重试、兜底容错机制实战，彻底解决线上报错、超时、崩溃问题，打造高可用AI系统