函数式 API 概念¶
概述¶
函数式 API 允许您将 LangGraph 的核心功能——持久化、记忆、人机交互和流式处理——添加到您的应用程序中,而只需对现有代码进行最小的改动。
它旨在将这些功能集成到可能使用标准语言原语(如 if
语句、for
循环和函数调用)进行分支和控制流的现有代码中。与许多要求将代码重构为显式管道或有向无环图(DAG)的数据编排框架不同,函数式 API 允许您在不强制执行刚性执行模型的情况下整合这些功能。
函数式 API 使用两个关键构建块
@entrypoint
– 将一个函数标记为工作流的起点,封装逻辑并管理执行流,包括处理长时间运行的任务和中断。@task
– 表示一个离散的工作单元,例如 API 调用或数据处理步骤,可以在入口点内异步执行。任务返回一个类似 future 的对象,可以被等待(await)或同步解析。
这为构建具有状态管理和流式处理的工作流提供了一个最小的抽象。
提示
有关如何使用函数式 API 的信息,请参阅使用函数式 API。
函数式 API 与图 API 对比¶
对于喜欢更具声明性方法的用户,LangGraph 的图 API 允许您使用图范式定义工作流。两种 API 共享相同的底层运行时,因此您可以在同一个应用程序中将它们一起使用。
以下是一些关键区别
- 控制流:函数式 API 不需要考虑图结构。您可以使用标准的 Python 结构来定义工作流。这通常会减少您需要编写的代码量。
- 短期记忆:图 API 需要声明一个状态(State),并且可能需要定义归约器(reducers)来管理图状态的更新。
@entrypoint
和@tasks
不需要显式的状态管理,因为它们的状态作用域限定在函数内部,不会跨函数共享。 - 检查点:两种 API 都会生成和使用检查点。在图 API 中,每个超级步骤(superstep)之后都会生成一个新的检查点。在函数式 API 中,当任务执行时,其结果会保存到与给定入口点关联的现有检查点中,而不是创建一个新的检查点。
- 可视化:图 API 可以轻松地将工作流可视化为图,这对于调试、理解工作流以及与他人共享非常有用。函数式 API 不支持可视化,因为图是在运行时动态生成的。
示例¶
下面我们演示一个简单的应用程序,它会撰写一篇文章,然后中断以请求人工审核。
API 参考:InMemorySaver | entrypoint | task | interrupt
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.func import entrypoint, task
from langgraph.types import interrupt
@task
def write_essay(topic: str) -> str:
"""Write an essay about the given topic."""
time.sleep(1) # A placeholder for a long-running task.
return f"An essay about topic: {topic}"
@entrypoint(checkpointer=InMemorySaver())
def workflow(topic: str) -> dict:
"""A simple workflow that writes an essay and asks for a review."""
essay = write_essay("cat").result()
is_approved = interrupt({
# Any json-serializable payload provided to interrupt as argument.
# It will be surfaced on the client side as an Interrupt when streaming data
# from the workflow.
"essay": essay, # The essay we want reviewed.
# We can add any additional information that we need.
# For example, introduce a key called "action" with some instructions.
"action": "Please approve/reject the essay",
})
return {
"essay": essay, # The essay that was generated
"is_approved": is_approved, # Response from HIL
}
详细解释
这个工作流将撰写一篇关于“猫”这个主题的文章,然后暂停以获取人工审核。工作流可以被无限期中断,直到提供了审核意见。
当工作流恢复时,它会从头开始执行,但由于 writeEssay
任务的结果已经被保存,任务结果将从检查点加载,而不会重新计算。
import time
import uuid
from langgraph.func import entrypoint, task
from langgraph.types import interrupt
from langgraph.checkpoint.memory import InMemorySaver
@task
def write_essay(topic: str) -> str:
"""Write an essay about the given topic."""
time.sleep(1) # This is a placeholder for a long-running task.
return f"An essay about topic: {topic}"
@entrypoint(checkpointer=InMemorySaver())
def workflow(topic: str) -> dict:
"""A simple workflow that writes an essay and asks for a review."""
essay = write_essay("cat").result()
is_approved = interrupt(
{
# Any json-serializable payload provided to interrupt as argument.
# It will be surfaced on the client side as an Interrupt when streaming data
# from the workflow.
"essay": essay, # The essay we want reviewed.
# We can add any additional information that we need.
# For example, introduce a key called "action" with some instructions.
"action": "Please approve/reject the essay",
}
)
return {
"essay": essay, # The essay that was generated
"is_approved": is_approved, # Response from HIL
}
thread_id = str(uuid.uuid4())
config = {"configurable": {"thread_id": thread_id}}
for item in workflow.stream("cat", config):
print(item)
# > {'write_essay': 'An essay about topic: cat'}
# > {
# > '__interrupt__': (
# > Interrupt(
# > value={
# > 'essay': 'An essay about topic: cat',
# > 'action': 'Please approve/reject the essay'
# > },
# > id='b9b2b9d788f482663ced6dc755c9e981'
# > ),
# > )
# > }
一篇文章已撰写完毕,等待审核。一旦提供了审核意见,我们就可以恢复工作流
from langgraph.types import Command
# Get review from a user (e.g., via a UI)
# In this case, we're using a bool, but this can be any json-serializable value.
human_review = True
for item in workflow.stream(Command(resume=human_review), config):
print(item)
工作流已完成,审核意见已添加到文章中。
入口点¶
@entrypoint
装饰器可用于从一个函数创建工作流。它封装了工作流逻辑并管理执行流程,包括处理长时间运行的任务和中断。
定义¶
通过用 @entrypoint
装饰器修饰一个函数来定义一个入口点。
该函数必须接受一个位置参数,作为工作流的输入。如果需要传递多个数据片段,请使用字典作为第一个参数的输入类型。
用 entrypoint
装饰一个函数会产生一个 Pregel
实例,它有助于管理工作流的执行(例如,处理流式处理、恢复和检查点)。
您通常需要向 @entrypoint
装饰器传递一个检查点管理器(checkpointer),以启用持久化并使用人机交互等功能。
序列化
入口点的输入和输出必须是 JSON 可序列化的,以支持检查点。请参阅序列化部分了解更多详情。
可注入参数¶
在声明 entrypoint
时,您可以请求访问在运行时自动注入的额外参数。这些参数包括
参数 | 描述 |
---|---|
previous | 访问与给定线程的上一个 checkpoint 关联的状态。请参阅短期记忆。 |
store | 一个 BaseStore 的实例。对于长期记忆很有用。 |
writer | 在处理 Async Python < 3.11 时用于访问 StreamWriter。请参阅函数式 API 的流式处理了解详情。 |
config | 用于访问运行时配置。请参阅 RunnableConfig 获取信息。 |
重要
用适当的名称和类型注解声明参数。
请求可注入参数
from langchain_core.runnables import RunnableConfig
from langgraph.func import entrypoint
from langgraph.store.base import BaseStore
from langgraph.store.memory import InMemoryStore
in_memory_store = InMemoryStore(...) # An instance of InMemoryStore for long-term memory
@entrypoint(
checkpointer=checkpointer, # Specify the checkpointer
store=in_memory_store # Specify the store
)
def my_workflow(
some_input: dict, # The input (e.g., passed via `invoke`)
*,
previous: Any = None, # For short-term memory
store: BaseStore, # For long-term memory
writer: StreamWriter, # For streaming custom data
config: RunnableConfig # For accessing the configuration passed to the entrypoint
) -> ...:
执行¶
使用 @entrypoint
会产生一个 Pregel
对象,可以使用 invoke
、ainvoke
、stream
和 astream
方法执行。
恢复¶
在 中断 后恢复执行,可以通过向 Command 原语传递一个恢复(resume)值来完成。
错误后恢复
要从错误中恢复,请使用 None
和相同的线程 ID(配置)来运行 entrypoint
。
这假设底层的错误已经解决,并且执行可以成功继续。
短期记忆¶
当一个 entrypoint
用 checkpointer
定义时,它会在同一线程 ID 的连续调用之间将信息存储在检查点中。
这允许使用 previous
参数访问上一次调用的状态。
默认情况下,previous
参数是上一次调用的返回值。
@entrypoint(checkpointer=checkpointer)
def my_workflow(number: int, *, previous: Any = None) -> int:
previous = previous or 0
return number + previous
config = {
"configurable": {
"thread_id": "some_thread_id"
}
}
my_workflow.invoke(1, config) # 1 (previous was None)
my_workflow.invoke(2, config) # 3 (previous was 1 from the previous invocation)
entrypoint.final
¶
entrypoint.final
是一个可以从入口点返回的特殊原语,它允许将保存在检查点中的值与入口点的返回值进行解耦。
第一个值是入口点的返回值,第二个值是将保存在检查点中的值。类型注解为 entrypoint.final[return_type, save_type]
。
@entrypoint(checkpointer=checkpointer)
def my_workflow(number: int, *, previous: Any = None) -> entrypoint.final[int, int]:
previous = previous or 0
# This will return the previous value to the caller, saving
# 2 * number to the checkpoint, which will be used in the next invocation
# for the `previous` parameter.
return entrypoint.final(value=previous, save=2 * number)
config = {
"configurable": {
"thread_id": "1"
}
}
my_workflow.invoke(3, config) # 0 (previous was None)
my_workflow.invoke(1, config) # 6 (previous was 3 * 2 from the previous invocation)
任务¶
一个任务代表一个离散的工作单元,例如 API 调用或数据处理步骤。它有两个关键特性
- 异步执行:任务被设计为异步执行,允许多个操作并发运行而不会阻塞。
- 检查点:任务结果被保存到检查点,从而可以从上次保存的状态恢复工作流。(有关更多详细信息,请参阅持久化)。
定义¶
任务是使用 @task
装饰器定义的,它包装了一个常规的 Python 函数。
API 参考:task
from langgraph.func import task
@task()
def slow_computation(input_value):
# Simulate a long-running operation
...
return result
序列化
任务的输出必须是 JSON 可序列化的,以支持检查点。
执行¶
任务只能从入口点、另一个任务或状态图节点内部调用。
任务不能直接从主应用程序代码中调用。
当您调用一个任务时,它会立即返回一个 future 对象。future 是一个占位符,表示一个稍后可用的结果。
要获取任务的结果,您可以同步等待它(使用 result()
)或异步等待它(使用 await
)。
何时使用任务¶
任务在以下场景中非常有用
- 检查点:当您需要将长时间运行的操作结果保存到检查点时,这样在恢复工作流时就不需要重新计算它。
- 人机交互:如果您正在构建一个需要人工干预的工作流,您必须使用任务来封装任何随机性(例如,API 调用),以确保工作流可以正确恢复。有关更多详细信息,请参阅确定性部分。
- 并行执行:对于 I/O 密集型任务,任务可以实现并行执行,允许多个操作并发运行而不会阻塞(例如,调用多个 API)。
- 可观察性:将操作包装在任务中,提供了一种使用 LangSmith 跟踪工作流进度和监控单个操作执行的方法。
- 可重试工作:当需要重试工作以处理故障或不一致时,任务提供了一种封装和管理重试逻辑的方法。
序列化¶
在 LangGraph 中,序列化有两个关键方面
entrypoint
的输入和输出必须是 JSON 可序列化的。task
的输出必须是 JSON 可序列化的。
这些要求对于启用检查点和工作流恢复是必要的。使用 Python 原语,如字典、列表、字符串、数字和布尔值,以确保您的输入和输出是可序列化的。
序列化确保工作流状态(如任务结果和中间值)可以被可靠地保存和恢复。这对于实现人机交互、容错和并行执行至关重要。
当工作流配置了检查点管理器时,提供不可序列化的输入或输出将导致运行时错误。
确定性¶
为了利用人机交互等功能,任何随机性都应该封装在任务内部。这保证了当执行被暂停(例如,为了人机交互)然后恢复时,它将遵循相同的步骤序列,即使任务结果是非确定性的。
LangGraph 通过在任务和子图执行时持久化其结果来实现此行为。一个精心设计的工作流确保恢复执行时遵循相同的步骤序列,从而可以正确检索先前计算的结果,而无需重新执行它们。这对于长时间运行的任务或具有非确定性结果的任务特别有用,因为它避免了重复已完成的工作,并允许从本质上相同的状态恢复。
虽然工作流的不同运行可以产生不同的结果,但恢复特定的运行应始终遵循相同的已记录步骤序列。这使得 LangGraph 能够有效地查找在图被中断之前执行的任务和子图结果,并避免重新计算它们。
幂等性¶
幂等性确保多次运行相同的操作会产生相同的结果。这有助于在由于故障而重新运行步骤时,防止重复的 API 调用和冗余处理。始终将 API 调用放在任务函数内部以进行检查点,并将其设计为在重新执行时是幂等的。如果一个任务开始但未能成功完成,就可能发生重新执行。然后,如果工作流被恢复,该任务将再次运行。使用幂等性密钥或验证现有结果以避免重复。
常见陷阱¶
处理副作用¶
将副作用(例如,写入文件、发送电子邮件)封装在任务中,以确保在恢复工作流时它们不会被多次执行。
在此示例中,副作用(写入文件)直接包含在工作流中,因此在恢复工作流时它将被第二次执行。
在此示例中,副作用被封装在一个任务中,确保在恢复时执行一致。
from langgraph.func import task
@task
def write_to_file():
with open("output.txt", "w") as f:
f.write("Side effect executed")
@entrypoint(checkpointer=checkpointer)
def my_workflow(inputs: dict) -> int:
# The side effect is now encapsulated in a task.
write_to_file().result()
value = interrupt("question")
return value
非确定性控制流¶
每次可能给出不同结果的操作(如获取当前时间或随机数)应封装在任务中,以确保在恢复时返回相同的结果。
- 在任务中:获取随机数(5)→ 中断 → 恢复 → (再次返回 5)→ ...
- 不在任务中:获取随机数(5)→ 中断 → 恢复 → 获取新的随机数(7)→ ...
这在使用具有多次中断调用的人机交互工作流时尤其重要。LangGraph 为每个任务/入口点保留一个恢复值列表。当遇到中断时,它会与相应的恢复值匹配。这种匹配是严格基于索引的,因此恢复值的顺序应与中断的顺序匹配。
如果在恢复时没有保持执行顺序,一个 interrupt
调用可能会与错误的 resume
值匹配,从而导致不正确的结果。
请阅读关于确定性的部分了解更多详情。
在此示例中,工作流使用当前时间来确定要执行哪个任务。这是非确定性的,因为工作流的结果取决于其执行的时间。
from langgraph.func import entrypoint
@entrypoint(checkpointer=checkpointer)
def my_workflow(inputs: dict) -> int:
t0 = inputs["t0"]
t1 = time.time()
delta_t = t1 - t0
if delta_t > 1:
result = slow_task(1).result()
value = interrupt("question")
else:
result = slow_task(2).result()
value = interrupt("question")
return {
"result": result,
"value": value
}
在此示例中,工作流使用输入 t0
来确定要执行哪个任务。这是确定性的,因为工作流的结果仅取决于输入。
import time
from langgraph.func import task
@task
def get_time() -> float:
return time.time()
@entrypoint(checkpointer=checkpointer)
def my_workflow(inputs: dict) -> int:
t0 = inputs["t0"]
t1 = get_time().result()
delta_t = t1 - t0
if delta_t > 1:
result = slow_task(1).result()
value = interrupt("question")
else:
result = slow_task(2).result()
value = interrupt("question")
return {
"result": result,
"value": value
}