PocketFlow + Gradio 构建 Human-in-the-Loop(HITL)工作流应用实战

  • 人工智能
  • 大模型
  • AI Agent
  • 工作流自动化
  • RAG

【免费下载链接】PocketFlow

Pocket Flow: 100-line LLM framework. Let Agents build Agents!

项目地址: https://gitcode.com/gh_mirrors/poc/PocketFlow
点击查看 免费下载

本教程以 PocketFlow 官方 cookbook 中的 pocketflow-gradio-hitl 示例为蓝本,讲解如何用 PocketFlow(100 行级 LLM 框架)编排带有人类反馈闭环的 Agent 工作流,并通过 Gradio 提供可交互的 Web 界面。读完本文,你将掌握如何设计决策式多节点 Flow、如何用共享上下文(shared)在节点间传递会话状态、如何把 LLM 的结构化 YAML 决策解析为流程跳转,以及如何借助消息队列把 Agent 的思考过程实时流式渲染到聊天界面。

示例概览:一个会订酒店、查天气的生活助手

cookbook/pocketflow-gradio-hitl 是一个"生活助理"演示应用:用户通过 Gradio 聊天界面与 AI 对话,AI 能完成两类任务——查询指定城市与日期的天气、预订酒店(含入住/退房日期);当信息不足或问题超出范围时,AI 会主动向用户追问;任务完成后则向用户播报结果并询问是否还有其他需求。

它的核心价值在于演示了 Human-in-the-Loop(HITL):整个工作流不是"一把梭"式地调 LLM,而是把"决策"与"执行"拆开——LLM 每轮只决定下一步动作,需要用户补充信息(如酒店名称、入住日期)时就暂停流程向用户提问,拿到反馈后再继续。这既避免了 LLM 一次生成错误参数,也让每个动作都在人类监督下逐步推进。

示例入口为 main.py,流程编排在 flow.py,节点实现集中在 nodes.py。

快速上手:安装、配置与启动

1. 安装依赖

先确认已克隆 PocketFlow 仓库并进入示例目录,然后安装依赖(见 requirements.txt):

pip install -r requirements.txt

依赖项及版本下限如下(与 README 中的 Requirements 一致):

依赖版本要求用途
pocketflow>= 0.0.2工作流编排框架
gradio>= 5.29.1Web 聊天界面(5.x 起采用 type="messages" 消息格式)
openai>= 1.78.1调用 OpenAI 模型

2. 配置 OpenAI API Key

应用使用 OpenAI 模型(默认 gpt-4o,见 utils/call_llm.py)做动作决策。设置环境变量:

export OPENAI_API_KEY="your-openai-api-key-here"

如果你用的是兼容 OpenAI 协议的代理或国内模型网关,也可以直接修改 utils/call_llm.py 中的 base_url 与 model 两个常量,示例默认值为 https://api.openai.com/v1 与 gpt-4o。

3. 启动应用

python main.py

启动后 Gradio 界面默认运行在 http://localhost:7860。打开浏览器即可与 AI 对话,示例会自动为每个会话生成一个 UUID 作为 conversation_id,用于隔离不同会话的状态(见 main.py 中 gr.State 与 clear_fn 的实现)。

工作流架构:五个节点与条件跳转

整体流程图

README 给出了完整的工作流拓扑:

mermaid

  • Decide Action Node:中枢决策节点。根据"上一动作 + 动作执行结果 + 聊天历史 + 当前用户问题"决定下一步动作。
  • Check Weather Node:查询指定城市与日期的天气。
  • Book Hotel Node:处理酒店预订请求(含入住、退房日期)。
  • Follow Up Node:向用户追问澄清信息,或引导超出范围的请求。
  • Result Notification Node:向用户播报任务结果并提供进一步帮助。

用 PocketFlow 的语法连接节点

flow.py 中通过 PocketFlow 的 - "action" >> 与 >> 运算符完成带动作标签的条件连接与默认连接:

from pocketflow import Flow

from nodes import (
    DecideAction, CheckWeather, BookHotel, FollowUp, ResultNotification,
)


def create_flow():
    decide_action = DecideAction()
    check_weather = CheckWeather()
    book_hotel = BookHotel()
    follow_up = FollowUp()
    result_notification = ResultNotification()

    decide_action - "check-weather" >> check_weather
    check_weather >> decide_action
    decide_action - "book-hotel" >> book_hotel
    book_hotel >> decide_action
    decide_action - "follow-up" >> follow_up
    decide_action - "result-notification" >> result_notification

    return Flow(start=decide_action)

关键点:

  • node - "action" >> next_node 表示条件边:当节点 post 方法返回字符串 "action" 时,流程跳转到 next_node。
  • node >> next_node 表示默认边:当 post 返回 "default" 时走这条路径。
  • Flow(start=decide_action) 以决策节点为起始。PocketFlow 的节点继承自 BaseNode,其 __sub__ 返回携带动作标签的 _ConditionalTransition 对象,__rshift__ 负责注册后继节点(见 pocketflow/init.pyi 的类型声明)。

从源码结构看,CheckWeather 与 BookHotel 的 post 返回 "default"(nodes.py 与 nodes.py),因此执行完天气查询或酒店预订后会沿默认边回到决策节点,让 LLM 基于执行结果决定"继续追问、再次调用工具还是播报结果"——这正是循环型 Agent 工作流的典型形态。

决策节点:让 LLM 输出结构化 YAML 来驱动流程

DecideAction 是整条工作流的"大脑",它把"下一步做什么"完全交给 LLM 决策,并通过强约束的 YAML 输出格式把决策结果结构化。

prep:组装上下文

def prep(self, shared):
    conversation_id = shared["conversation_id"]
    session = load_conversation(conversation_id)
    return session, shared["history"], shared["query"]

prep 从 shared 字典中读取会话 ID、聊天历史与当前用户问题,并从会话缓存中加载 last_action(上一次动作)与 action_result(上一次动作结果)。

exec:构造提示词并解析决策

exec 中构造的提示词包含四部分:

  1. 角色指令:你是能订酒店、查天气的生活助理,需要基于"上一动作、动作结果、聊天历史、当前问题"决策下一步。
  2. 聊天历史:由 format_chat_history 格式化。
  3. 上下文:Last Action、Last Action Result、Current Date(当前日期由 datetime.now().date() 动态注入)。
  4. 动作空间(ACTION SPACE):四个候选动作及其参数 schema:
动作适用场景关键参数
check-weather用户询问天气city(必填)、date(选填,缺省用当天)
book-hotel用户要订酒店hotel、checkin_date、checkout_date(均必填)
follow-up问题超出范围,或当前信息不足以调用工具question(追问内容)
result-notification酒店预订或天气查询已完成result(结果播报)

提示词强制 LLM 输出固定格式的 YAML:

thinking: |
    <你的逐步推理过程>
action: check-weather OR book-hotel OR follow-up OR result-notification
reason: <选择该动作的原因>
question: <当动作是 follow-up 时>
city: <当动作是 check-weather 时>
hotel: <当动作是 book-hotel 时>
checkin_date: <当动作是 book-hotel 时>
checkout_date: <当动作是 book-hotel 时>
result: <当动作是 result-notification 时>

并在提示词末尾强调三条格式纪律:多行字段用 4 空格缩进、多行文本用 | 块引用、单行字段不用 |。随后调用 call_llm 获取响应,通过 response.split("```yaml")[1].split("```")[0].strip() 剥离代码围栏,再用 yaml.safe_load 解析为字典。

post:写回会话并决定下一跳

post 是 HITL 闭环的关键:

def post(self, shared, prep_res, exec_res):
    conversation_id = shared["conversation_id"]
    session = load_conversation(conversation_id)
    session["last_action"] = exec_res["action"]
    flow_log = shared["flow_queue"]

    for line in exec_res["thinking"].split("\n"):
        line = line.replace("-", "").strip()
        if line:
            flow_log.put(f"🤔 {line}")

    if exec_res["action"] == "check-weather":
        session["check_weather_params"] = {
            "city": exec_res["city"], "date": exec_res.get("date", None),
        }
        flow_log.put(f"➡️ Agent decided to check weather for: {exec_res['city']}")
    elif exec_res["action"] == "book-hotel":
        session["book_hotel_params"] = {
            "hotel": exec_res["hotel"],
            "checkin_date": exec_res["checkin_date"],
            "checkout_date": exec_res["checkout_date"],
        }
        flow_log.put(f"➡️ Agent decided to book hotel: {exec_res['hotel']}")
    elif exec_res["action"] == "follow-up":
        session["follow_up_params"] = {"question": exec_res["question"]}
        flow_log.put(f"➡️ Agent decided to follow up: {exec_res['question']}")
    elif exec_res["action"] == "result-notification":
        session["result_notification_params"] = {"result": exec_res["result"]}
        flow_log.put(f"➡️ Agent decided to notify the result: {exec_res['result']}")

    save_conversation(conversation_id, session)
    return exec_res["action"]

这里发生了三件事:

  1. 持久化动作参数:把决策中的 city/date、hotel/checkin_date/checkout_date、question、result 分别写入会话 session,供后续执行节点取用。
  2. 推送流程日志:把 LLM 的 thinking 逐行、以及动作摘要(➡️ ...)推入 flow_queue,供前端实时展示"思考过程"。
  3. 返回动作名作为跳转条件:return exec_res["action"] 的值会与 flow.py 中注册的动作标签匹配,从而驱动条件边跳转——"check-weather" 去 CheckWeather,"book-hotel" 去 BookHotel,"follow-up" 去 FollowUp,"result-notification" 去 ResultNotification。

执行节点:天气查询与酒店预订

CheckWeather / BookHotel

两个执行节点的结构完全对称,都遵循 PocketFlow 的 prep → exec → post 三段式:

  • prep:从 session 中取出上一步决策写入的参数(城市/日期,或酒店/入住/退房日期)。
  • exec:调用 mock API(utils/call_mock_api.py)返回模拟结果,避免真实调用外部服务。
  • post:把结果推入 flow_queue(⬅️ ...),写入 session["action_result"],然后返回 "default" 让流程回到决策节点。

Mock API 内置了贴近真实业务的校验规则,是很好的参数边界参考:

  • 天气查询:日期与当前日期相差超过 7 天返回失败(abs(date_diff) > 7)。
  • 酒店预订:入住日期必须晚于当前日期;入住日期不得晚于(等于)退房日期;入住天数不得超过 7 天。
  • 模拟返回值:天气为 sunny/cloudy/rainy/snowy 随机选择、温度 10~30°C 随机;酒店预订成功返回包含日期范围的确认信息。

这些规则保证了 LLM 即使"脑补"了参数,也会在执行层被校验拦截并反馈回决策节点,触发 follow-up 追问,这正是 HITL 的意义所在。

FollowUp / ResultNotification:通过消息队列与前端通信

这两个节点不再直接操作 LLM,而是通过 shared["queue"](一个 Python queue.Queue)把要展示给用户的最终文本发送给 Gradio 前端:

class FollowUp(Node):
    def prep(self, shared):
        flow_log = shared["flow_queue"]
        flow_log.put(None)  # 标记思考日志结束
        conversation_id = shared["conversation_id"]
        session = load_conversation(conversation_id)
        question = session["follow_up_params"]["question"]
        return question, shared["queue"]

    def exec(self, prep_res):
        question, queue = prep_res
        queue.put(question)
        queue.put(None)  # 标记聊天消息结束
        return question

    def post(self, shared, prep_res, exec_res):
        conversation_id = shared["conversation_id"]
        session = load_conversation(conversation_id)
        session["action_result"] = exec_res
        return "done"

注意 post 返回 "done",而 flow.py 中没有注册 "done" 边,因此流程在 FollowUp / ResultNotification 节点处自然终止——用户的每条消息触发一轮完整的"决策→执行→(可能)追问/播报"循环,而追问的答案由用户在下一条消息中给出。ResultNotification 在播报后还会清空 action_result 与 last_action(nodes.py),为下一轮对话重置上下文。

会话管理:shared 与内存级会话缓存

PocketFlow 的节点之间通过 shared 字典共享数据。在本示例中,main.py 为每轮对话构造了:

shared = {
    "conversation_id": str(uuid),
    "query": message,
    "history": history,
    "queue": chat_queue,       # 用户可见的聊天消息
    "flow_queue": flow_queue,  # 思考过程/流程日志
}

而跨节点、跨轮次的状态(last_action、action_result、各动作参数)则由 utils/conversation.py 提供的内存缓存管理:

conversation_cache = {}

def load_conversation(conversation_id: str):
    return conversation_cache.get(conversation_id, {})

def save_conversation(conversation_id: str, session: dict):
    conversation_cache[conversation_id] = session

以 conversation_id(UUID)为键隔离不同会话,避免多人同时使用时状态串扰。需要说明的是,这是单进程内存缓存,重启进程后状态即丢失;如需持久化,可以替换为文件存储或 Redis 等方案。此外,utils/format_chat_history.py 在把历史喂给 LLM 前会过滤掉以 - 🤔、- ➡️、- ⬅️ 开头的思考/流程日志行,防止 Agent 把自己的"思维链"当成对话内容重复输入。

前端集成:Gradio 多线程流式渲染

main.py 展示了如何把 PocketFlow 同步流程嵌入 Web 应用:

  1. 全局线程池:ThreadPoolExecutor(max_workers=5) 让多个会话的 Flow 并发运行,避免阻塞 Gradio 事件循环。
  2. 异步提交:chatflow_thread_pool.submit(chat_flow.run, shared) 把 Flow 丢到后台线程执行。
  3. 双队列流式输出:主线程先消费 flow_queue 累积"思考日志",逐条 yield 更新 ChatMessage(其 metadata 含 title="Flow Log"、status 与 duration 字段);待流程结束(队列收到 None 哨兵)后,再消费 chat_queue,把追问或结果作为普通消息 yield 出去。
  4. 界面搭建:gr.Blocks(fill_height=True, theme="ocean") 中放置 gr.Chatbot(type="messages") 与 gr.ChatInterface,通过 gr.State 保存 UUID;点击清除按钮时 clear_fn 生成新 UUID 开启全新会话。

这样,用户能在界面上实时看到 Agent 的思考步骤与节点执行顺序,而不仅仅是最终答案。

运行效果与流程可视化

应用提供实时流程可视化:节点激活顺序按时间先后展示,用户可以看到哪些决策路径被触发,从而理解 AI 的决策过程。

下图是用户发送 hello 时的完整界面:上方是带耗时统计的 Flow Log,逐条展示 Agent 的分析与决策("用户用 hello 问候,无天气或酒店预订的上下文,需友好跟进以明确需求"),下方是 AI 的友好追问:

flow visualization

预订酒店的示例输出——用户提出"明天订酒店",AI 追问酒店与入住时长,发现"最长只能订 7 天"后与用户协商,最终确认纽约希尔顿 2025-05-31 至 2025-06-07 的预订:

book hotel

对话中途改变意图的示例——用户从"订酒店"临时转向"查纽约明天天气",AI 先给出天气结果,再确认继续预订希尔顿 3 天,展示了 HITL 工作流对用户意图变化的灵活响应:

change intention

文件结构与扩展建议

示例目录结构如下:

文件作用
main.py入口:Gradio 界面搭建、线程池、双队列流式输出
flow.py定义 PocketFlow 图与节点连接关系
nodes.py五个节点的实现
utils/call_llm.pyOpenAI 调用封装(模型、base_url 可改)
utils/call_mock_api.py天气/酒店的模拟 API 与业务校验
utils/conversation.py内存级会话缓存
utils/format_chat_history.py聊天历史格式化(过滤思考日志)
requirements.txt依赖清单

想扩展这个示例时,推荐按以下顺序动手:

  1. 新增工具节点:在 ACTION SPACE 中追加新动作描述与参数 schema,在 flow.py 中注册条件边,在 nodes.py 中实现新节点,并在 post 中保存参数。
  2. 替换 mock API:把 call_book_hotel_api / call_check_weather_api 换成真实后端 HTTP 调用,业务校验可保留在服务端。
  3. 持久化会话:将 conversation_cache 换成数据库或 Redis,即可支持多实例部署。
  4. 升级异步:如需更高并发,可参考仓库内 docs/core_abstraction/async.md 与 tests/test_async_flow.py,将节点改为 AsyncNode。

小结

pocketflow-gradio-hitl 用约 300 行代码完整演示了"决策循环 + 人工介入 + 可视化"的 HITL 应用范式:LLM 只做结构化决策,工具执行与参数校验交给普通节点,用户追问通过消息队列回到前端,整个流程由 PocketFlow 的 shared 上下文与动作标签无缝串联。这套模式稍加改造即可复用于预订、下单、审批等任何"AI 出主意、人来拍板"的真实业务场景。

  • 人工智能
  • 大模型
  • AI Agent
  • 工作流自动化
  • RAG

【免费下载链接】PocketFlow

Pocket Flow: 100-line LLM framework. Let Agents build Agents!

项目地址: https://gitcode.com/gh_mirrors/poc/PocketFlow
点击查看 免费下载

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

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

抵扣说明:

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

余额充值