LangChain 中文文档

主题

Studio 实验室

Studio 故障排除

Safari 连接问题 ​

Safari 会阻止 localhost 上的纯 HTTP 流量。当使用 langgraph dev 运行 Studio 时，您可能会看到“Failed to load assistants”错误。

解决方案 1：使用 Cloudflare 隧道 ​

Python
JS
shell
pip install -U langgraph-cli>=0.2.6
langgraph dev --tunnel

该命令会输出一个如下格式的 URL：

shell
https://smith.langchain.com/studio/?baseUrl=https://hamilton-praise-heart-costumes.trycloudflare.com

在 Safari 中使用此 URL 来加载 Studio。这里的 baseUrl 参数指定了您的代理服务器端点。

解决方案 2：使用 Chromium 浏览器 ​

Chrome 和其他基于 Chromium 的浏览器允许 localhost 上的 HTTP 连接。无需额外配置，直接使用 langgraph dev 即可。

Chrome 连接问题 ​

从 Chrome 版本 142 开始，当您尝试通过 langgraph dev 将 LangSmith Studio 连接到本地开发服务器时，可能会遇到“Failed to initialize Studio”错误，并伴随“TypeError: Failed to fetch”。即使 http://127.0.0.1:2024/docs 处的 API 服务器已成功加载，此问题仍会发生。

根本原因： Chrome 142 完全强制执行私有网络访问 (Private Network Access, PNA) 规范，且没有回退机制，这默认会阻止 HTTPS 站点（如 https://smith.langchain.com）访问 HTTP 本地主机服务器。

症状 ​

  • 运行 langgraph dev 成功启动服务器。
  • 访问 http://127.0.0.1:2024/docs 能正确显示 API 文档。
  • https://smith.langchain.com 上的 LangSmith Studio 显示：“Failed to initialize Studio - Please verify if the API server is running or accessible from the browser. TypeError: Failed to fetch”。
  • 浏览器控制台显示类似错误：Permission was denied for this request to access the 'unknown' address space。

解决方案：在 Chrome 中允许本地网络访问 ​

  1. 在 Chrome 中打开 https://smith.langchain.com 上的 LangSmith Studio。
  2. 点击地址栏左侧的锁形图标（或网站信息图标）。
  3. 在下拉菜单中查找 "Local network access" 选项。
  4. 将设置从 "Ask (default)" 或 "Block" 更改为 "Allow"。
  5. 重新加载页面。

现在 Studio 应该能成功连接到您的本地开发服务器了。

其他故障排除 ​

检查浏览器扩展冲突

浏览器扩展（尤其是 Ollama Chrome 扩展或 AI 模型扩展）可能会干扰 localhost 连接：

  1. 暂时禁用所有浏览器扩展。
  2. 重启 Chrome。
  3. 尝试再次连接到 Studio。
  4. 如果连接成功，则逐个重新启用扩展以找出问题根源。

验证依赖项是否为最新版本

shell
pip install -U "langgraph-cli[inmem]"

清除浏览器缓存和站点数据

  1. 在 Chrome 中，转到 设置 > 隐私和安全 > 网站设置。
  2. 在列表中找到 https://smith.langchain.com。
  3. 点击 清除数据。
  4. 重启 Chrome 并重试。

Brave 连接问题 ​

当启用 Brave Shields 时，Brave 会阻止 localhost 上的纯 HTTP 流量。当使用 langgraph dev 运行 Studio 时，您可能会看到“Failed to load assistants”错误。

解决方案 1：禁用 Brave Shields ​

使用 URL 栏中的 Brave 图标为 LangSmith 禁用 Brave Shields。

解决方案 2：使用 Cloudflare 隧道 ​

Python
JS
shell
pip install -U langgraph-cli>=0.2.6
langgraph dev --tunnel

该命令会输出一个如下格式的 URL：

shell
https://smith.langchain.com/studio/?baseUrl=https://hamilton-praise-heart-costumes.trycloudflare.com

在 Brave 中使用此 URL 来加载 Studio。这里的 baseUrl 参数指定了您的代理服务器端点。

图边连接问题 ​

未定义的条件边可能会在您的图中显示意外的连接。这是因为如果没有正确定义，Studio 会假定条件边可以访问所有其他节点。要解决此问题，请使用以下方法之一明确定义路由路径：

解决方案 1：路径映射 ​

定义路由器输出与目标节点之间的映射：

Python
Javascript
python
graph.add_conditional_edges("node_a", routing_function, {True: "node_b", False: "node_c"})

解决方案 2：路由器类型定义 ​

使用 Python 的 Literal 类型指定可能的路由目标：

python
def routing_function(state: GraphState) -> Literal["node_b","node_c"]:
    if state['some_condition'] == True:
        return "node_b"
    else:
        return "node_c"

Studio 中的实验故障排除 ​

运行实验 按钮被禁用 ​

请检查以下内容：

  • 已部署的应用程序：如果您的应用程序部署在 LangSmith 上，您可能需要创建一个新的修订版才能启用此功能。
  • 本地开发服务器：如果您在本地运行应用程序，请确保已升级到最新版本的 langgraph-cli (pip install -U langgraph-cli)。此外，请确保通过在项目的 .env 文件中设置 LANGSMITH_API_KEY 来启用追踪功能。

评估器结果缺失 ​

当您运行实验时，任何附加的评估器都会被安排在队列中执行。如果您没有立即看到结果，很可能意味着它们仍在等待处理中。

LangChain 中文文档

Copyright © 王码码