使用langgraph时短节点名引发Mermaid.ink超时错误

问题描述 #

在Jupyter Notebook中使用LangGraph构建简单状态机，通过mermaid.ink渲染Mermaid图时，若将节点命名为"A"会触发超时错误；但将节点名改为"chatbot"后，图能正常渲染。

复现代码（超时场景） #

%%capture --no-stderr
%pip install -U langgraph typing-extensions
from IPython.display import Image
from typing_extensions import TypedDict
from langgraph.graph import StateGraph

class ClientContext(TypedDict):
    client_id: str

graph_builder = StateGraph(ClientContext)

def chatbot(state: ClientContext):
    return {"messages": "Yam"}

graph_builder.add_node("A", chatbot)
graph_builder.set_entry_point("A")
graph_builder.set_finish_point("A")
graph = graph_builder.compile()

graph_image = Image(graph.get_graph().draw_mermaid_png())  # 此处触发超时

错误信息 #

TimeoutError: The read operation timed out

requests.exceptions.ReadTimeout: HTTPSConnectionPool(host='mermaid.ink', port=443): 
Read timed out. (read timeout=10)

正常运行代码（节点名改为"chatbot"） #

from IPython.display import Image
from typing_extensions import TypedDict
from langgraph.graph import StateGraph

class ClientContext(TypedDict):
    client_id: str

graph_builder = StateGraph(ClientContext)

def chatbot(state: ClientContext):
    return {"messages": "Yam"}

graph_builder.add_node("chatbot", chatbot)
graph_builder.set_entry_point("chatbot")
graph_builder.set_finish_point("chatbot")
graph = graph_builder.compile()

graph_image = Image(graph.get_graph().draw_mermaid_png())  # 正常渲染

可能原因与解决思路 #

• Mermaid语法解析异常：单个字母"A"作为节点名，可能生成了让mermaid.ink服务端难以处理的极简图结构，或是与Mermaid内置语法规则冲突，导致服务端处理超时。
• 服务端处理策略：mermaid.ink对某些极端简单的图结构可能存在处理延迟，单个节点的图触发了服务端的特殊逻辑，进而超时。

临时解决办法：

• 避免使用单个字母作为节点名称，改用具有描述性的名称（如示例中的"chatbot"）。
• 手动验证Mermaid语法：通过graph.get_graph().draw_mermaid()获取Mermaid文本，直接在本地Mermaid编辑器中测试渲染，排查是否为语法问题。
• 自定义超时逻辑：如果需要使用单个字母节点，可以手动实现mermaid.ink的请求逻辑，调整超时参数（LangGraph的draw_mermaid_png默认封装了请求，需自行改写部分代码）。

内容的提问来源于stack exchange，提问作者Ohm