langGraph从入门到精通（三）——基于LangGraph的智能问答系统开发：Python单代理架构实战

1 导语

在构建复杂的LLM应用时，如何精细化控制AI的执行流程与状态流转一直是开发者的痛点。LangGraph作为LangChain生态中的明星级框架，通过图论（Graph）的思想完美解决了状态持久化与循环逻辑控制的问题。本文将带你通过一个亲测有效的实战案例，掌握LangGraph的底层构建流程、State状态模式设计以及单代理架构的实现。学习本文后，你将能够独立搭建具备状态管理能力的智能对话系统。

2 技术栈清单

Python == 3.10.x
langgraph == 1.0.5
langchain-openai == 1.1.7
python-dotenv == 1.2.1
DashScope (通义千问) API支持

3 项目核心原理

本项目基于LangGraph的StateGraph 构建。核心逻辑是将对话过程抽象为一个有向无环图（DAG），通过定义强类型的TypedDict状态对象（State）来管理节点的输入与输出。通过START和END标记控制流转生命周期，实现数据在节点间的精准传递。

4 实战步骤

4.1 环境准备

首先，我们需要配置环境变量以接入大模型。在项目根目录创建.env文件。

bash 复制代码

# 安装必要依赖包
pip install langgraph==1.0.5 langchain-openai==1.1.7 python-dotenv==1.2.1

4.2 代码实现

创建01-langgraph.py文件，核心逻辑如下：

python 复制代码

from langgraph.graph import StateGraph, START, END
from typing_extensions import TypedDict
from langchain_openai import ChatOpenAI
from dotenv import load_dotenv
import os

# 加载环境变量
load_dotenv()
key = os.getenv("DASHSCOPE_API_KEY")
base_url = os.getenv("DASHSCOPE_API_BASE")

# 1. 定义状态模式
class InputState(TypedDict):
    question: str

class OutputState(TypedDict):
    answer: str

class OverallState(InputState, OutputState):
    pass

# 2. 定义处理节点
def llm_node(state: InputState):
    llm = ChatOpenAI(model="qwen-plus", api_key=key, base_url=base_url, temperature=0)
    response = llm.invoke([("human", state["question"])]) 
    return {"answer": response.content} # 返回符合OutputState结构的字典

# 3. 构建并编译图
builder = StateGraph(OverallState, input=InputState, output=OutputState)
builder.add_node("llm_node", llm_node)
builder.add_edge(START, "llm_node")
builder.add_edge("llm_node", END)
graph = builder.compile()

4.3 功能测试

执行脚本验证图的调用流程。

python 复制代码

if __name__ == "__main__":
    result = graph.invoke({"question": "你好，请自我介绍"})
    print(result)

5 核心代码解析

5.1 State 状态模式设计

划重点 ：LangGraph的核心在于状态管理。

python 复制代码

class OverallState(InputState, OutputState):
    pass

核心作用：定义了图中流转的数据契约。
关键参数 ：InputState约束了入口参数，OutputState约束了最终返回。
关联逻辑 ：OverallState通过继承实现了状态的合并。在图中，每个节点都可以读取并更新这个共享状态，确保了数据的一致性。

5.2 节点与图的编排

python 复制代码

builder = StateGraph(OverallState, input=InputState, output=OutputState)
builder.add_node("llm_node", llm_node)
builder.add_edge(START, "llm_node")

核心作用：将函数逻辑转化为可执行的图节点。
为何这样实现 ：通过显式指定input和output模式，LangGraph可以在编译阶段进行类型校验，避免了动态运行时出现由于字段缺失导致的报错。

6 效果验证

执行代码后，我们可以看到系统成功调用了通义千问模型，并返回了结构化的answer。

7 踩坑记录

7.1 节点返回值格式错误

错误现象 ：TypeError: Expected dict, got str
根因分析：LangGraph节点必须返回一个字典，且Key必须是State中定义的字段。
解决方案 ：确保llm_node返回的是{"answer": ...}而非直接返回字符串。

7.2 环境变量加载失效

错误现象：API Key为None导致鉴权失败。
根因分析 ：未正确执行load_dotenv()或.env路径不正确。
解决方案：在代码头部优先执行环境变量加载。

7.3 State继承冲突

错误现象：State合并后部分字段无法识别。
根因分析 ：使用TypedDict时，若父类字段定义冲突会导致不可预期的行为。
解决方案：严格区分输入、输出和中间状态字段，保持逻辑清晰。

本文通过LangGraph 成功构建了一个具备状态约束的单代理问答系统。核心收获 在于理解了State模式如何为LLM应用提供确定性的数据流转保障。后续我们可以进一步尝试在图中加入条件边（Conditional Edges）实现更复杂的逻辑判断。

欢迎评论区留言讨论LangGraph底层原理及State状态管理相关的问题~