【LangGraph】二.State 和 Node 的设计细节

写在前面

这篇文章深入探讨 State 和 Node 的设计细节。理解这些细节，能帮你写出更清晰、更可维护的 LangGraph 应用。我们会讲解：

• State 字段的设计原则和更新策略
• Node 的职责划分和最佳实践
• 常见的错误和如何避免
• 实用的调试技巧

这些内容看似是细节，但直接影响你的代码质量。一个好的设计能让后续的功能扩展变得简单，而一个糟糕的设计会让代码越来越难以维护。希望这篇文章能帮你避开那些我们曾经踩过的坑。

State 设计

什么是 State

State 是整个图共享的数据容器。所有节点都能读取 State，也可以更新 State。

from typing import TypedDict

class State(TypedDict):
    question: str
    documents: list
    answer: str

字段更新策略

State 的更新不是简单的赋值，而是通过"合并"机制。理解这个机制很重要。

覆盖更新（默认）

def node_a(state: State) -> dict:
    return {"answer": "新答案"}

这个节点返回 {"answer": "新答案"}，LangGraph 会直接用新值替换旧的 answer 值。

追加更新（用于列表）

有些场景需要追加而不是覆盖。比如对话历史，你希望新消息追加到末尾，而不是替换整个列表。

from typing import Annotated
from operator import add

class State(TypedDict):
    messages: Annotated[list, add]  # 使用 add Reducer

这样定义后，节点返回 {"messages": [新消息]} 时，新消息会追加到列表末尾，而不是替换整个列表。

为什么需要 Reducer？

因为 LangGraph 支持节点并行执行。如果两个节点同时更新同一个列表字段，需要知道如何合并它们的更新。add Reducer 会把两个列表拼接起来。

你也可以自定义 Reducer：

def merge_dicts(left: dict, right: dict) -> dict:
    """合并两个字典"""
    return {**left, **right}

class State(TypedDict):
    metadata: Annotated[dict, merge_dicts]

State 设计原则

原则 1：只放跨节点共享的数据

State 是节点之间传递数据的媒介。如果某个数据只在一个节点内部使用，不应该放在 State 里。

# ❌ 错误：放了临时变量
class State(TypedDict):
    question: str
    documents: list
    answer: str
    temp_counter: int      # 只在一个节点用
    cache_data: dict       # 只在一个节点用

# ✅ 正确：只放共享数据
class State(TypedDict):
    question: str
    documents: list
    answer: str

临时变量应该在节点内部处理：

def my_node(state: State) -> dict:
    # 临时变量在函数内部
    counter = 0
    cache = {}
    
    # 使用它们
    counter += 1
    
    # 只返回需要更新的 State 字段
    return {"answer": "结果"}

原则 2：字段名要清晰

字段名应该清楚表达含义，避免使用泛泛的名称。

# ❌ 错误：太泛
class State(TypedDict):
    data: str           # 什么数据？
    result: str         # 什么结果？
    info: dict          # 什么信息？

# ✅ 正确：一目了然
class State(TypedDict):
    user_question: str
    retrieved_documents: list
    generated_answer: str
    processing_metadata: dict

清晰的字段名让代码更容易理解，也减少了注释的需要。

原则 3：考虑更新策略

设计 State 时，要想清楚每个字段如何更新：

• 是覆盖更新（默认）还是追加更新？
• 是否会被多个节点同时更新？
• 是否需要自定义合并逻辑？

from typing import Annotated
from operator import add

class State(TypedDict):
    # 对话历史：需要追加
    messages: Annotated[list, add]
    
    # 当前步骤：覆盖更新
    current_step: str
    
    # 检索结果：追加
    documents: Annotated[list, add]
    
    # 最终答案：覆盖更新
    answer: str

Node 设计

什么是 Node

Node 是执行具体逻辑的函数。它接收当前 State，返回 State 的更新。

def retrieve_node(state: State) -> dict:
    # 读取 State
    question = state["question"]
    
    # 执行操作
    documents = search(question)
    
    # 返回更新
    return {"documents": documents}

Node 的基本结构

一个好的节点函数通常包含三个部分：

def my_node(state: State) -> dict:
    """节点的文档字符串，说明功能"""
    
    # 1. 从 State 读取需要的数据
    data = state["some_field"]
    
    # 2. 执行具体操作
    result = process(data)
    
    # 3. 返回 State 的更新
    return {"result_field": result}

关键点：

• 接收完整的 State，但只读取需要的字段
• 执行操作（调用 LLM、访问数据库、计算等）
• 返回 dict，表示 State 的更新

常见节点类型

LLM 节点：调用大模型

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

model = ChatOpenAI(model="gpt-4")

def llm_node(state: State) -> dict:
    # 从 State 获取输入
    messages = state["messages"]
    
    # 调用模型
    response = model.invoke(messages)
    
    # 返回更新（追加到对话历史）
    return {"messages": [response]}

工具节点：执行工具

from langchain.tools import tool

@tool
def search(query: str) -> str:
    """搜索工具"""
    return f"搜索结果：{query}"

def tool_node(state: State) -> dict:
    # 获取工具调用参数
    query = state["query"]
    
    # 执行工具
    result = search.invoke(query)
    
    # 返回结果
    return {"search_result": result}

判断节点：路由决策

def router_node(state: State) -> dict:
    """根据问题类型返回路由"""
    question = state["question"]
    
    if "代码" in question.lower():
        return {"route": "code_agent"}
    elif "数学" in question.lower():
        return {"route": "math_agent"}
    else:
        return {"route": "general_agent"}

判断节点通常配合条件边使用：

def route_by_category(state: State) -> str:
    """条件函数，返回下一个节点的名称"""
    return state["route"]

graph.add_conditional_edges(
    "router",
    route_by_category,
    {
        "code_agent": "code_node",
        "math_agent": "math_node",
        "general_agent": "general_node",
    }
)

Node 设计原则

原则 1：单一职责

每个节点应该只做一件事。这样更容易理解、测试和维护。

# ❌ 错误：一个节点做太多事
def retrieve_and_generate(state: State) -> dict:
    # 检索
    docs = retrieve(state["question"])
    
    # 生成答案
    answer = generate(docs)
    
    # 验证答案
    quality = validate(answer)
    
    return {
        "documents": docs,
        "answer": answer,
        "quality": quality
    }

# ✅ 正确：拆分成多个节点
def retrieve_node(state: State) -> dict:
    return {"documents": retrieve(state["question"])}

def generate_node(state: State) -> dict:
    return {"answer": generate(state["documents"])}

def validate_node(state: State) -> dict:
    return {"quality": validate(state["answer"])}

拆分后，每个节点职责清晰，也更容易单独测试和优化。

原则 2：只返回需要更新的字段

节点应该只返回真正需要更新的字段，不要返回整个 State。

# ❌ 错误：返回整个 State
def node(state: State) -> dict:
    return {
        "question": state["question"],      # 没变化
        "documents": state["documents"],    # 没变化
        "answer": "新答案",                 # 有变化
    }

# ✅ 正确：只返回变化的字段
def node(state: State) -> dict:
    return {"answer": "新答案"}

只返回变化的字段有几个好处：

• 代码更清晰，一眼看出更新了哪些字段
• 减少不必要的数据复制
• 避免意外覆盖其他节点的更新

原则 3：幂等性

节点应该是幂等的：多次执行相同输入，应该得到相同输出。

# ❌ 错误：依赖历史状态，不幂等
def bad_node(state: State) -> dict:
    # 每次执行都加 1，结果依赖执行次数
    count = state.get("count", 0) + 1
    return {"count": count}

# ✅ 正确：只依赖输入，幂等
def good_node(state: State) -> dict:
    # 结果只取决于 input，多次执行结果相同
    result = compute(state["input"])
    return {"result": result}

幂等性在以下场景很重要：

• 重试：节点执行失败需要重试
• 恢复：从断点恢复执行
• 调试：回到之前的状态重新执行

节点命名

给节点起清晰的名称，方便理解和调试。

# ❌ 错误：名称不清晰
graph.add_node("node1", func1)
graph.add_node("node2", func2)

# ✅ 正确：名称清晰表达职责
graph.add_node("retrieve_documents", retrieve_node)
graph.add_node("generate_answer", generate_node)
graph.add_node("validate_quality", validate_node)

好的节点名称让流程图更易读，调试时也更容易定位问题。

调试技巧

打印 State 变化

在节点中打印输入和输出，帮助理解数据流。

def debug_node(state: State) -> dict:
    print(f"\n=== {node_name} ===")
    print(f"输入 State: {state}")
    
    result = process(state)
    
    print(f"输出更新：{result}")
    return result

使用 LangSmith

LangSmith 可以自动追踪每个节点的输入输出。

import os

os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = "lsv2_..."

# 执行时会自动追踪
result = app.invoke({"question": "Hello"})

# 在 LangSmith 平台查看完整的执行轨迹

可视化图结构

把图结构画出来，帮助理解执行流程。

from IPython.display import Image, display

# 生成并显示流程图
display(Image(app.get_graph().draw_mermaid_png()))

常见错误

错误 1：直接修改 State

# ❌ 错误：直接修改 State
def node(state: State) -> dict:
    state["answer"] = "新答案"  # 直接修改
    return state

# ✅ 正确：返回更新
def node(state: State) -> dict:
    return {"answer": "新答案"}

LangGraph 通过合并更新来管理 State。直接修改 State 会破坏这个机制。

错误 2：返回未定义的字段

# ❌ 错误：返回 State 中没有的字段
class State(TypedDict):
    answer: str

def node(state: State) -> dict:
    return {"result": "xxx"}  # State 中没有 result 字段

# ✅ 正确：返回已定义的字段
def node(state: State) -> dict:
    return {"answer": "xxx"}

错误 3：节点过于复杂

# ❌ 错误：一个节点 100 行代码
def complex_node(state: State) -> dict:
    # 50 行检索逻辑
    # 30 行生成逻辑
    # 20 行验证逻辑
    ...

# ✅ 正确：拆分成多个节点
def retrieve_node(state: State) -> dict:
    # 只负责检索
    ...

def generate_node(state: State) -> dict:
    # 只负责生成
    ...

def validate_node(state: State) -> dict:
    # 只负责验证
    ...

错误 4：忽略并行更新冲突

# ❌ 错误：并行节点更新同一个字段
class State(TypedDict):
    result: str  # 覆盖更新

# 如果两个节点并行执行，后执行的会覆盖先执行的

# ✅ 正确：使用追加更新
class State(TypedDict):
    results: Annotated[list, add]  # 追加更新

总结

State 设计要点：

• 只放跨节点共享的数据
• 字段名要清晰
• 考虑更新策略（覆盖 vs 追加）

Node 设计要点：

• 单一职责
• 只返回需要更新的字段
• 保持幂等性
• 起清晰的名称

调试技巧：

• 打印 State 变化
• 使用 LangSmith
• 可视化图结构