LangGraph 中的核心数据结构: TypedDict 如何提升 LLM 应用的可靠性与可维护性

在构建基于大语言模型（LLM）的复杂应用时，如何有效地组织和管理数据，确保数据结构的一致性，是保证应用可靠性和可维护性的关键。LangGraph，作为一种用于编排 LLM 工作流的强大工具，其内部使用了特定的数据结构来管理和传递步骤之间的状态。理解这些数据结构，特别是 TypedDict，对于充分利用 LangGraph 的潜力至关重要。本文将深入探讨 LangGraph 中数据结构的应用，并通过实例展示 TypedDict 如何帮助开发者构建更健壮的 LLM 应用。

问题的起源：无结构的字典带来的挑战

在传统的 Python 编程中，字典（dictionary）是一种非常灵活的数据结构，允许开发者以键值对的形式存储各种类型的数据。例如，我们可以用字典来表示一个人的信息：

alice = {"name": "Alice", "age": 30}
john = {"Name": "John", "Age": 50, "job_title": "Manager"}

这段代码看起来简单易懂，但很快就会暴露出一些问题：

键名不一致： alice 的键是 "name"，而 john 的键是 "Name"。这种大小写不一致会导致在后续处理数据时出现错误。
缺少必要字段： alice 没有 job_title 字段，而 john 有。如果程序依赖 job_title 字段，那么处理 alice 时就会出错。
类型不明确： 虽然我们知道 "age" 应该是一个整数，但 Python 并没有强制规定 age 的类型。如果有人不小心将 age 设置为字符串，程序可能会出现意想不到的错误。

这些问题在小型项目中可能并不明显，但在大型、复杂的 LLM 应用中，由于数据量巨大且处理流程复杂，这些问题会被放大，最终导致应用崩溃或产生错误的结果。因此，我们需要一种更严格、更可靠的数据结构来管理和传递数据。

TypedDict：为字典带来类型安全的保障

TypedDict 是 Python typing 模块中的一个类，它允许开发者定义具有特定键和对应数据类型的字典类型。TypedDict 的作用就像是一个字典的蓝图，它规定了字典应该包含哪些键，以及每个键对应的值应该是什么类型。

让我们用 TypedDict 来重新定义表示人的信息的字典：

from typing import TypedDict

class Person(TypedDict):
    name: str
    age: int
    job_title: str

person1: Person = {"name": "Alice", "age": 30, "job_title": "Software Engineer"}
person2: Person = {"name": "Bob", "age": 40, "job_title": "Data Scientist"}

在这个例子中，我们定义了一个名为 Person 的 TypedDict，它包含三个键：name、age 和 job_title。name 的类型是字符串，age 的类型是整数，job_title 的类型是字符串。

现在，如果我们尝试创建一个不符合 Person 规范的字典，Python 的类型检查器会发出警告或错误：

# 错误：缺少 job_title 字段
# person3: Person = {"name": "Charlie", "age": 50}

# 错误：age 的类型错误
# person4: Person = {"name": "David", "age": "60", "job_title": "Project Manager"}

使用 TypedDict 的好处是显而易见的：

类型安全： 确保字典中的每个键都对应着正确的数据类型，避免类型错误。
代码可读性： 清楚地定义了字典的结构，提高了代码的可读性和可维护性。
静态检查： 允许类型检查器在运行时之前发现潜在的错误，减少了调试的时间和成本。

在 LangGraph 中，TypedDict 被广泛用于定义状态对象，这些状态对象在不同的步骤之间传递数据。

LangGraph 中的状态管理：TypedDict 的应用实例

在 LangGraph 中，状态是 LLM 应用的中心，它存储了在工作流中流动的数据。状态通常包含用户输入、LLM 的输出、以及其他中间结果。为了保证状态的一致性和可靠性，LangGraph 强烈建议使用 TypedDict 来定义状态对象。

让我们看一个简单的 LangGraph 例子，这个例子演示了如何使用 TypedDict 来定义状态：

from typing import TypedDict
from langgraph.graph import StateGraph, END
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import chain
from langchain_openai import ChatOpenAI

# 定义状态对象
class GraphState(TypedDict):
    user_input: str
    parsed_response: str

# 定义 LLM
model = ChatOpenAI(temperature=0.0)

# 定义 prompt
prompt = ChatPromptTemplate.from_template("你是一个助手，将用户输入的内容进行翻译成中文：{user_input}")

# 定义节点1：接收用户输入并调用 LLM
def node1(state: GraphState):
    response = model.invoke(prompt.format(user_input=state["user_input"]))
    return {"parsed_response": response.content}

# 定义节点2：将 LLM 的输出返回给用户
def node2(state: GraphState):
    print(f"翻译后的内容：{state['parsed_response']}")
    return {}

# 构建 LangGraph 图
graph_builder = StateGraph(GraphState)
graph_builder.add_node("node1", node1)
graph_builder.add_node("node2", node2)
graph_builder.set_entry_point("node1")
graph_builder.add_edge("node1", "node2")
graph_builder.add_edge("node2", END)

graph = graph_builder.compile()

# 运行 LangGraph
inputs = {"user_input": "Hello, world!"}
graph.invoke(inputs)

在这个例子中，我们首先定义了一个名为 GraphState 的 TypedDict，它包含两个键：user_input 和 parsed_response。user_input 存储用户的输入，parsed_response 存储 LLM 的输出。

然后，我们定义了两个节点：node1 和 node2。node1 接收 GraphState 作为输入，调用 LLM 对用户输入进行翻译，并将翻译结果存储在 parsed_response 中。node2 接收 GraphState 作为输入，并将 parsed_response 的内容输出到控制台。

最后，我们使用 StateGraph 构建 LangGraph 图，并运行该图。

在这个例子中，TypedDict 确保了状态对象始终包含 user_input 和 parsed_response 两个键，并且它们的类型分别是字符串。这有助于防止类型错误，并提高代码的可读性和可维护性。

更复杂的 LangGraph 应用：利用 TypedDict 管理多步状态

上面的例子只是一个简单的演示，在实际应用中，LangGraph 应用通常包含更多的步骤和更复杂的状态。在这种情况下，TypedDict 的作用更加重要。

例如，我们可以扩展上面的例子，添加一个节点来对 LLM 的输出进行验证：

from typing import TypedDict
from langgraph.graph import StateGraph, END
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import chain
from langchain_openai import ChatOpenAI

# 定义状态对象
class GraphState(TypedDict):
    user_input: str
    parsed_response: str
    validation_result: bool

# 定义 LLM
model = ChatOpenAI(temperature=0.0)

# 定义 prompt
prompt = ChatPromptTemplate.from_template("你是一个助手，将用户输入的内容进行翻译成中文：{user_input}")

# 定义节点1：接收用户输入并调用 LLM
def node1(state: GraphState):
    response = model.invoke(prompt.format(user_input=state["user_input"]))
    return {"parsed_response": response.content}

# 定义节点2：验证 LLM 的输出
def node2(state: GraphState):
    # 这里可以添加更复杂的验证逻辑
    if len(state["parsed_response"]) > 10:
        validation_result = True
    else:
        validation_result = False
    return {"validation_result": validation_result}

# 定义节点3：将 LLM 的输出返回给用户
def node3(state: GraphState):
    if state["validation_result"]:
        print(f"翻译后的内容：{state['parsed_response']}")
    else:
        print("翻译后的内容太短，无法显示。")
    return {}

# 构建 LangGraph 图
graph_builder = StateGraph(GraphState)
graph_builder.add_node("node1", node1)
graph_builder.add_node("node2", node2)
graph_builder.add_node("node3", node3)
graph_builder.set_entry_point("node1")
graph_builder.add_edge("node1", "node2")
graph_builder.add_edge("node2", "node3")
graph_builder.add_edge("node3", END)

graph = graph_builder.compile()

# 运行 LangGraph
inputs = {"user_input": "Hello, world!"}
graph.invoke(inputs)

在这个例子中，我们添加了一个名为 node2 的节点，用于验证 LLM 的输出。node2 将 GraphState 作为输入，并根据 parsed_response 的长度设置 validation_result 的值。然后，我们修改了 node3，使其根据 validation_result 的值决定是否输出 LLM 的输出。

为了支持这个新的节点，我们修改了 GraphState，添加了一个名为 validation_result 的键，其类型为布尔值。

通过使用 TypedDict，我们可以确保在添加新的节点和状态变量时，不会破坏现有的代码，并保证状态的一致性和可靠性。

使用 TypedDict 的最佳实践

在使用 TypedDict 时，可以遵循以下最佳实践：

尽早定义状态对象： 在开始编写 LangGraph 应用之前，应该首先定义状态对象。这有助于明确应用的数据流，并减少后续修改代码的成本。
保持状态对象简单： 状态对象应该只包含必要的变量。避免将不相关的数据存储在状态对象中，以免增加代码的复杂性。
使用清晰的键名： 状态对象的键名应该清晰、简洁、易懂。这有助于提高代码的可读性和可维护性。
添加类型注释： 状态对象的每个键都应该有明确的类型注释。这有助于类型检查器发现潜在的错误。
考虑使用第三方库： 除了 Python typing 模块提供的 TypedDict，还可以考虑使用第三方库，例如 pydantic，来定义更复杂的状态对象。pydantic 提供了更强大的验证和序列化功能。

总结：TypedDict 是构建可靠 LangGraph 应用的基石

TypedDict 是 LangGraph 中一种非常重要的数据结构，它通过提供类型安全和清晰的结构，有效地解决了传统字典带来的问题。在构建基于 LLM 的复杂应用时，使用 TypedDict 来定义状态对象可以显著提高代码的可读性、可维护性和可靠性。本文通过具体的例子展示了 TypedDict 在 LangGraph 中的应用，并提供了一些最佳实践建议。掌握 TypedDict 的使用，是构建高效、可靠的 LangGraph 应用的关键一步。在未来的 LLM 应用开发中，我们应该更加重视数据结构的设计和选择，利用 TypedDict 等工具，构建更健壮、更易于维护的 AI 系统。

LangGraph 中的核心数据结构: TypedDict 如何提升 LLM 应用的可靠性与可维护性