Jupyter和LangSmith——AI Agent开发调试监控工具

Jypyter和LangSmith简介

欲善其功，必先利其器。在进行AI Agent开发时，日志非常的多，往往会淹没在文本的海洋中，调试步骤也比较麻烦，如果每次都从头调试不仅浪费时间还很烧钱(token).此时，选择趁手的工具就很重要了。你可以选择Jupyter 作为你的"实验台"，LangSmith 是你的"监控器"，两者都要用，但侧重点不同。

Jupyter Notebook 是AI的IDE，在这里**"运行即保存"** 。你不需要每次为了调试最后一步，而重新跑前面耗时、耗 Token 的第一步。它是你构建 LangGraph 节点的草稿本 。你先在 Jupyter 里把一个个 Node 函数写通，最后再拼成一个 .py 文件。

LangSmith：必须同步开启（它是你的"黑匣子"）在写第一行 LangChain 代码时就挂载它即可（声明几个环境变量API Key、ProjectName就好了）。 LangGraph 的逻辑很复杂，模型在后台到底收到了什么 Prompt？它为什么没走你设定的分支？只看控制台输出（Print）会让你崩溃。挂载LangSmith后，你在 Jupyter 里跑的每一行代码，在 LangSmith 后台都会生成一个精美的可视化链路图。方便你查看问题。

Jupyter Notebook的安装方法是两条命令，然后登录web入口即可使用，参考https://docs.jupyter.org/en/latest/install/notebook-classic.html https://github.com/langchain-ai/langchain-academy/

LangSmith是需要外网环境，先到Langsmith官网申请key，创建project然后把这些变量export到你的代码开头，当langgraph真正运行起来后就可以到langsmith官网你创建的这个工程链接里面看到图的动态变化了。可以参考https://smith.langchain.com/

下面就是我根据以上官方文档安装以及使用jupyter和langsmith的详细步骤，需要的话可以往后看。

Jupyter安装和使用

Jupyter的安装

安装Jupyter官网(https://docs.jupyter.org/en/latest/install/notebook-classic.html)的描述，安装方法如下：

在主机上安装Jypyter

bash 复制代码

pip3 install --upgrade pip
pip3 install jupyter
# 卸载命令如下
# pip3 uninstall notebook jupyter_core jupyter_server jupyterlab -y

# 启动 jupyter 服务
# 注意：生产环境不建议用 --allow-root， --no-browser不启动浏览器
jupyter notebook --ip=0.0.0.0 --port=8888 --no-browser --allow-root

安装完成后，启动时可能报错 ModuleNotFoundError: No module named 'jupyter_core'，这可能是因为主机上安装了多套 python 环境，系统命令链接出了问题，用以下命令试一下（如果你安装了python3.12）:

bash 复制代码

 python3.12 -m jupyter notebook --ip=0.0.0.0 --port=8888 --allow-root

鉴于这种方法容易出现环境链接问题，因此我不推荐使用这种方法，可以考虑下面几种环境隔离的方法。

使用conda安装Jypyter

bash 复制代码

conda install jupyter
# 如果已经安装过 jupyter conda 环境那么就更新即可
conda update jupyter
# 以上在你的 Conda 环境里"全新安装" Jupyter 全家桶，还需要另外创建jupter环境 
# 创建一个专门的环境（例如叫 jupyter_env）
conda create -n jupyter_env python=3.12 jupyter -y
# 激活环境
conda activate jupyter_env
# 在该环境中启动jupyter
jupyter notebook --ip=0.0.0.0 --allow-root

使用 uv安装Jypyter

uv是一种现在的方法，怎么个现代法？

uv 的"现代"不只是安装环境速度更快，更是一套全新的、更符合直觉的项目管理哲学。它将 Python 开发中繁琐的环境管理步骤大大简化，让你能更专注于 LangGraph 等具体的业务逻辑。

bash 复制代码

# 1. 安装 uv
pip install uv

# 2. 创建虚拟环境并安装 jupyter 和 langgraph
uv init my_langgraph_study
cd my_langgraph_study

# 3. 添加你需要的依赖 (uv 会自动创建虚拟环境)
uv add langgraph langchain jupyter

# 3. 运行 jupyter（如果是本地开发，去掉权限参数）
uv run jupyter notebook

# 如果是 Docker/服务器环境，需要暴露端口
uv run jupyter notebook --ip=0.0.0.0 --port=8888 --no-browser --allow-root

uv venv 创建环境

uv add 安装自动添加依赖，自动生成跨平台的 uv.lock 锁定文件，保证团队成员、生产环境与本地环境100%一致. 注意，这里uv add 和 uv pip install 是平行关系，不是前后步骤。用了 uv add 就不需要 uv pip install。

使用 uv run python script.py 自动执行，无需手动激活和记忆环境路径。注意uv add 是直接在环境里面安装包，命令退出包还在。如果是共享服务器建议使用uv venv命令，该命令会创建虚拟环境（在当前目录生成 .venv），然后需要激活虚拟环境 source .venv/bin/activate 然后在环境里面干活。

pip、conda和uv的区别

前面叙述了pip、conda和uv三种工具，你可能会想这三种方法到底有啥区别，下面简述如下：

特性	pip	Conda	uv
主要功能	安装包	环境管理 + 安装包	极速安装 + 环境管理
语言	Python	Python/C	Rust
速度	慢	中等	极快
依赖解决	有时冲突，需手动修	稳健，擅长处理非Python库	非常稳健，兼容 pip 标准
运行限制	只管安装不管运行	必须激活环境(conda activate)	在指定目录下运行
定位	Python 官方默认工具	数据科学领域的"老大哥"	新一代的高性能挑战者

使用传统虚拟环境安装Jupyter

这种方法更简单稳定

bash 复制代码

# 1. 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

# 2. 安装包
pip install jupyter langgraph langchain

# 3. 运行
jupyter notebook

运行jupyter

其实上面的内容里，已经提到了这几种安装方法如何拉起jupyter进程，运行界面如下所示：

你在那个目录下敲运行命令`uv run jupyter notebook `，就显示的是该目录下的所有文件，然后你选择你的工程目录，这里使用的是langchain学院的代码，你可以到github上去下载https://github.com/langchain-ai/langchain-academy.git。

另外，还可以参考deep_research_scratch项目：

https://github.com/langchain-ai/deep_research_from_scratch.git 重点关注notebooks文件夹。

如果才conda环境中切换目录运行jupyter进程，需要重新activate虚拟环境。

然后打开module-0/basics.ipynb，通过查看界面上的菜单可以知道jupyter notebook的单元是cell，即一块一块的代码段。你可以通过菜单栏来创建、删除、运行、中断你当前选中的cell.

你可以复用这段初始化代码：

python 复制代码

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
import os, getpass

def _set_env(var: str):
    if not os.environ.get(var):
        os.environ[var] = getpass.getpass(f"{var}: ")
_set_env("OPENAI_API_KEY")

deepseek_chat = ChatOpenAI(model="deepseek-v3-2-251201", 
                           base_url="https://ark.cn-beijing.volces.com/api/v3",
                           temperature=0)

# Create a message
msg = HumanMessage(content="Hello world", name="Lance")

# Message list
messages = [msg]

# Invoke the model with a list of messages 

deepseek_chat.invoke(messages)

鼠标放在cell上，点击Run按钮就单独运行该cell的代码，不用加打印语句，运行结果会自动显示在下面，如果运行错误也会有日志显示在Cell下面。运行完毕cell左侧的中括号里面会显示数字编号，即当前运行的几号cell，正在运行时显示为[*]，如果一直是这样的话则说明有问题点击kernel interrupt或者直接点击那个停止按钮。

LangSmith的注册和使用

Jupyter需要你安装环境，而langsmith不需要安装，只需要注册，然后到langsmith官网查看你的工程详情。下面就以langchain-academy(https://github.com/langchain-ai/langchain-academy.git)为例来说明如何利用LangSmith进行便捷的监控，即看agent干了些啥。

本地langgraph dev 方式

打开langchain-academy/module-1/router.ipynb文件最下面，让你在langchain-academy/module-1/studio/目录下用langgraph dev 命令拉起进程，然后输出提示符：

bash 复制代码

- 🚀 API: http://127.0.0.1:2024
- 🎨 Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
- 📚 API Docs: http://127.0.0.1:2024/docs

然后你在浏览器中输入出Studio UI 地址。由于我的运行环境是服务器，导致访问不通，如下所示：

这是因为baseUrl=[http://127.0.0.1:2024](http://127.0.0.1:2024) 指向的是你当前电脑（宿主机）的本地环回地址。当你在自己电脑的浏览器里打开 LangChain Studio 时，它会尝试去你自己电脑上寻找 2024 端口，而你的程序实际上跑在远程服务器上，两边根本没有通，所以才会报 Failed to fetch。注意不要把127.0.0.1改成你的服务器地址。而是需要做SSH 端口转发，即在你的主机上输入如下命令 "ssh -N -L 2024:127.0.0.1:2024 用户名@服务器IP"：

-N：表示只建立连接，不打开远程服务器的 Shell 终端（单纯做端口转发）。

-L 2024:127.0.0.1:2024：将远程服务器本地的 2024 端口映射到你当前电脑的 2024 端口。

输入命令和密码成功后，终端会处于静止/阻塞状态，这是正常的，说明通道已经建立，请不要关闭这个终端窗口。再去刷新刚才失败的页面正常显示如下：

我们观察到langchain-academy/module-1/studio目录下有三个py文件和一个langgraph.json以及其他环境依赖文件。其中，langgraph.json内容如下：

bash 复制代码

{
  "dockerfile_lines": [],
  "graphs": {
    "simple_graph": "./simple.py:graph",
    "router": "./router.py:graph",
    "agent": "./agent.py:graph"
  },
  "env": "./.env",
  "python_version": "3.11",
  "dependencies": [
    "."
  ]
}

这意味着当你运行 langgraph dev 时，它在后台同时加载了 3 个独立的工作流（Graphs）：

去 simple.py 里加载一个叫 graph 的变量（对应 simple_graph）。

去 router.py 里加载一个叫 graph 的变量（对应 router）。

去 agent.py 里加载一个叫 graph 的变量（对应 agent）。

这在 LangChain Studio 网页里意味着什么？

当你通过浏览器和 SSH 隧道成功进入 LangChain Studio 的可视化界面后，你会在界面的左上角或者顶部看到一个下拉切换菜单。在这个菜单里，你可以在 simple_graph、router 和 agent 之间自由切换：

切换到 simple_graph：网页会把 simple.py 里的 Python 逻辑画成节点流程图，你可以在输入框里给它发消息进行测试。

切换到 agent：网页就会实时渲染 agent.py 里的复杂智能体流程。

其他关键配置：

"env": "./.env"：它在启动时会自动读取当前目录下的 .env 文件。你的大模型 API 密钥（比如 OPENAI_API_KEY 或 ANTHROPIC_API_KEY）就必须写在这个文件里，否则程序和网页虽然能通，但运行节点时会报密钥缺失的错误。

"dependencies": ["."]：告诉系统，把当前目录（.）加入到 Python 的搜索路径中，这样这几个 .py 文件之间才能互相 import（引用）。

运行条件

langgraph dev这种本地运行方式需要几个条件：

有 langgraph.json 配置文件
图是纯 LangGraph，不依赖外部基础设施，或者能解决外部依赖问题
入口模块直接暴露 graph = builder.compile()

如果我们要这种模式，那么就需要解决以上三个问题，其中外部依赖是工程中常常遇到的问题。例如MCP Server, 数据库的连接等。

langsmith环境变量方式

还有一种工程中常用的方式，就是在工程中设置环境变量，首先你需要在langsmith网站创建project,如下所示：

我这里创建了多个project用于不同环境的测试，创建好工程后网页会自动跳转到如下页面：

注意这里产生API key, 并且把红框里面的环境变量生效到你的程序运行环境中。注意要等到图开始运行之后然后再点击该工程就能看到图运转的详细过程了。