【LangGraph】langgraph.graph 模块：构建和管理基于状态的工作流图所需的类和工具

于 2025-05-15 14:32:46 发布
阅读量612 收藏 19
点赞数 16
分类专栏： LangGraph 文章标签： LangGraph langgraph.graph StateGraph MessageGraph
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/u013172930/article/details/147982579
版权

本文是对 LangGraph 中 langgraph.graph 模块的详细介绍，涵盖其定义、功能、主要类和函数、使用场景以及代码示例。

1. langgraph.graph 模块概述

langgraph.graph 是 LangGraph 库的核心模块，提供了构建和管理基于状态的工作流图所需的类和工具。它是 LangGraph 的基础组件，用于定义 有向图 结构，其中：

  • 节点（Nodes） 表示执行的操作（如调用 LLM、处理数据）。
  • 边（Edges） 定义节点之间的执行顺序（支持无条件和条件跳转）。
  • 状态（State） 是一个贯穿图执行的数据结构，用于存储和传递上下文。

该模块的主要目标是：

  • 提供灵活的 API 来构建复杂的工作流，支持分支、循环和动态逻辑。
  • 管理状态的更新和传递，确保节点之间的信息一致性。
  • 支持编译为可执行的图对象，用于运行工作流。

langgraph.graph 通常用于构建智能 Agent、对话系统、自动化流程等需要多步骤交互的场景，与 LangChain 生态（如 LLM、工具、LangSmith）无缝集成。

2. langgraph.graph 模块的主要内容

langgraph.graph 模块包含以下核心类、函数和常量，用于定义和操作工作流图：

2.1 主要类

  1. StateGraph：用于定义基于状态的工作流图。
  2. CompiledGraph：StateGraph 编译后的可执行图对象（内部类，通常不直接实例化）。
  3. MessageGraph：一种特殊的图，专为处理消息序列（如对话）设计，状态默认基于消息列表。

2.2 主要函数

  • 模块中没有直接暴露的顶级函数，大部分功能通过 StateGraph 和 MessageGraph 的方法实现。

2.3 常量

  • START：表示图的入口点（类型：str）。
  • END：表示图的终止点（类型：str）。

2.4 依赖

  • langchain_core.runnables：提供 RunnableConfig 用于运行时配置。
  • typing：用于类型注解（如 TypedDict 定义状态）。
  • langgraph.checkpoint：支持状态持久化（检查点）。

3. 核心类详解

3.1 StateGraph 类

定义
from langgraph.graph import StateGraph
from typing import Type, Optional, Any

class StateGraph:
    def __init__(
        self,
        state_schema: Optional[Type[Any]] = None,
        config_schema: Optional[Type[Any]] = None
    ) -> None:
        ...
  • 参数：
    • state_schema：状态的数据结构（如 TypedDict 或自定义类），默认为 dict。
    • config_schema：运行时配置的结构（如 TypedDict），用于验证 RunnableConfig，默认为任意配置。
功能

StateGraph 是构建工作流图的核心类，用于：

  • 定义节点、边和状态。
  • 支持条件分支和循环。
  • 编译为可执行的图。
属性
  • nodes：Dict[str, Callable]，存储节点名称和执行函数。
  • edges：Dict[str, List[str]]，存储无条件边。
  • conditional_edges：Dict[str, Tuple[Callable, Dict[str, str]]]，存储条件边。
  • entry_point：str，入口节点名称。
  • finish_points：Set[str]，终止节点集合。
  • state_schema：状态的数据结构。
  • config_schema：配置的数据结构。
方法

  1. add_node(name: str, action: Callable) -> None

    • 添加节点，action 是一个函数，接收状态和可选配置，返回更新后的状态。
    • 示例：
      def process_input(state, config):
    state["output"] = f"处理: {state['input']}"
    return state
workflow.add_node("process_input", process_input)

  2. add_edge(source: Union[str, START, END], target: Union[str, END]) -> None

    • 添加无条件边。
    • 示例：
      workflow.add_edge(START, "process_input")
workflow.add_edge("process_input", END)

  3. add_conditional_edges(source: str, condition: Callable, edge_mapping: Dict[Any, Union[str, END]]) -> None

    • 添加条件边，condition 返回值决定跳转目标。
    • 示例：
      def route(state):
    return "process" if len(state["input"]) > 5 else "skip"
workflow.add_conditional_edges("check", route, {"process": "process_input", "skip": "skip"})

  4. set_entry_point(name: str) -> None

    • 设置入口节点，等效于 add_edge(START, name)。

  5. set_finish_point(name: str) -> None

    • 设置终止节点，等效于 add_edge(name, END)。

  6. compile(checkpointer: Optional[BaseCheckpointSaver] = None, interrupt_after: Optional[List[str]] = None, interrupt_before: Optional[List[str]] = None) -> CompiledGraph

    • 编译为 CompiledGraph，支持检查点和中断。
示例
from typing import TypedDict
from langgraph.graph import StateGraph, START, END

class State(TypedDict):
    input: str
    output: str

workflow = StateGraph(State)
workflow.add_node("process", lambda state: {"output": f"处理: {state['input']}"})
workflow.add_edge(START, "process")
workflow.add_edge("process", END)
graph = workflow.compile()
result = graph.invoke({"input": "Hello"})
print(result)  # {'input': 'Hello', 'output': '处理: Hello'}

3.2 MessageGraph 类

定义
from langgraph.graph import MessageGraph

class MessageGraph(StateGraph):
    def __init__(self) -> None:
        super().__init__(state_schema=None)
  • 继承：MessageGraph 是 StateGraph 的子类。
  • 状态：默认状态是一个消息列表（List[BaseMessage]），适合对话或消息处理场景。
  • 限制：不支持自定义 state_schema 或 config_schema。
功能

MessageGraph 简化了对话系统的构建，状态自动管理为消息序列，节点函数通常处理或生成消息。

方法

与 StateGraph 相同，但状态操作基于消息列表。例如：

  • 节点函数接收和返回 List[BaseMessage] 或单个 BaseMessage。
  • 边和条件边逻辑基于消息内容。
示例
from langgraph.graph import MessageGraph, START, END
from langchain_core.messages import HumanMessage, AIMessage

workflow = MessageGraph()
workflow.add_node("respond", lambda messages: AIMessage(content=f"回复: {messages[-1].content}"))
workflow.add_edge(START, "respond")
workflow.add_edge("respond", END)
graph = workflow.compile()
result = graph.invoke([HumanMessage(content="Hello")])
print(result)  # [HumanMessage(content='Hello'), AIMessage(content='回复: Hello')]

3.3 CompiledGraph 类（内部类）

  • 定义：StateGraph.compile() 的返回值，是可执行的图对象。
  • 功能：提供运行工作流的方法，如 invoke、stream、astream。
  • 主要方法：
    • invoke(input: Dict[str, Any], config: Optional[RunnableConfig] = None) -> Dict[str, Any]：同步执行。
    • stream(...) -> Iterator[Dict[str, Any]]：流式执行。
    • astream(...) -> AsyncIterator[Dict[str, Any]]：异步流式执行。
    • astream_events(...) -> AsyncIterator[Dict[str, Any]]：异步流式事件。
  • 注意：开发者通常不直接实例化 CompiledGraph，而是通过 StateGraph.compile() 获取。

4. 常量

  • START：字符串 "__start__"，表示图的入口点，用于 add_edge(START, ...)。
  • END：字符串 "__end__"，表示图的终止点，用于 add_edge(..., END)。

示例：

workflow.add_edge(START, "first_node")
workflow.add_edge("last_node", END)

5. 使用场景和示例

以下是 langgraph.graph 模块的典型使用场景和代码示例。

5.1 简单线性工作流

from typing import TypedDict
from langgraph.graph import StateGraph, START, END

class State(TypedDict):
    input: str
    output: str

def process(state):
    return {"output": f"处理: {state['input']}"}

workflow = StateGraph(State)
workflow.add_node("process", process)
workflow.add_edge(START, "process")
workflow.add_edge("process", END)
graph = workflow.compile()
result = graph.invoke({"input": "Hello"})
print(result)  # {'input': 'Hello', 'output': '处理: Hello'}

5.2 条件分支工作流

from typing import TypedDict
from langgraph.graph import StateGraph, START, END

class State(TypedDict):
    input: str
    output: str
    needs_processing: bool

def check(state):
    state["needs_processing"] = len(state["input"]) > 5
    return state

def process(state):
    state["output"] = f"处理: {state['input']}"
    return state

def skip(state):
    state["output"] = "输入太短"
    return state

def route(state):
    return "process" if state["needs_processing"] else "skip"

workflow = StateGraph(State)
workflow.add_node("check", check)
workflow.add_node("process", process)
workflow.add_node("skip", skip)
workflow.add_edge(START, "check")
workflow.add_conditional_edges("check", route, {"process": "process", "skip": "skip"})
workflow.add_edge("process", END)
workflow.add_edge("skip", END)
graph = workflow.compile()
result = graph.invoke({"input": "Hi"})
print(result)  # {'input': 'Hi', 'output': '输入太短', 'needs_processing': False}

5.3 对话系统（使用 MessageGraph）

from langgraph.graph import MessageGraph, START, END
from langchain_core.messages import HumanMessage, AIMessage
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4o-mini")
workflow = MessageGraph()
workflow.add_node("agent", lambda messages: llm.invoke(messages))
workflow.add_edge(START, "agent")
workflow.add_edge("agent", END)
graph = workflow.compile()
result = graph.invoke([HumanMessage(content="Hello!")])
print(result[-1].content)  # LLM 的回复

5.4 检查点和中断

from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import MemorySaver
from typing import TypedDict

class State(TypedDict):
    input: str
    output: str

workflow = StateGraph(State)
workflow.add_node("process", lambda state: {"output": f"处理: {state['input']}"})
workflow.add_edge(START, "process")
workflow.add_edge("process", END)
graph = workflow.compile(checkpointer=MemorySaver(), interrupt_after=["process"])
result = graph.invoke({"input": "Hello"}, config={"configurable": {"thread_id": "thread_001"}})
print(result)  # 中断后的状态

6. 与其他模块的关系

  • langgraph.checkpoint：提供 BaseCheckpointSaver（如 MemorySaver），用于状态持久化，与 StateGraph.compile(checkpointer=...) 配合。
  • langchain_core.runnables：提供 RunnableConfig，用于传递运行时配置（如 thread_id、user_id）。
  • langchain_core.messages：与 MessageGraph 配合，处理消息序列。
  • langsmith：与 LangSmith 集成，用于调试和可视化图执行。

7. 注意事项

  1. 状态一致性：

    • 确保节点函数返回的状态符合 state_schema，否则可能导致类型错误。
    • 在 MessageGraph 中，状态是消息列表，节点需返回 BaseMessage 或其列表。

  2. 条件边逻辑：

    • add_conditional_edges 的 edge_mapping 必须覆盖条件函数的所有可能返回值，否则可能抛出异常。

  3. 异步支持：

    • 节点函数可以是异步的（async def），配合 graph.astream 或 graph.astream_events 使用。
    • 示例：
      async def async_node(state):
    result = await some_async_function(state["input"])
    return {"output": result}

  4. 版本兼容性：

    • 使用最新版本的 LangGraph（如 0.2.x）以获得最佳性能。
    • 确保依赖（如 langchain-core）版本匹配，避免 API 变更问题。

  5. 性能优化：

    • 减少节点数量和复杂条件逻辑，以降低执行开销。
    • 使用检查点（checkpointer）缓存中间状态，避免重复计算。

8. 总结

langgraph.graph 模块是 LangGraph 的核心，提供了 StateGraph 和 MessageGraph 两个主要类，用于构建和管理工作流图：

  • StateGraph：通用工作流图，支持自定义状态和配置，适合复杂逻辑。
  • MessageGraph：专为对话系统设计，简化消息处理。
  • 常量：START 和 END 用于定义图的入口和出口。

通过 add_node、add_edge、add_conditional_edges 等方法，你可以灵活定义节点和执行逻辑。编译后的 CompiledGraph 支持同步、流式和异步执行，结合检查点和中断功能，适用于生产级应用。

参考文献：

评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

彬彬侠

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值