Parse-Flow：開源可視化文檔智能工作流設計器

非結構化文檔仍然是企業存儲和共享信息的主要方式。從合同到發票再到報告，這些文檔的共同點是包含佈局、語言和上下文的混合，下游系統無法直接消費。文檔智能——即將這些文檔轉化為結構化機器可讀數據的學科——是使現代AI堆棧對企業真正有用的關鍵層。如果沒有強大的解析、分類、拆分和提取，任何檢索流水線、智能體或分析儀表板都將建立在脆弱的基礎之上。

Parse-Flow 是一個小型開源項目，它將四個文檔處理原語——解析（Parsing）、提取（Extraction）、分類（Classification）和拆分（Splitting）——置於可視化工作流設計器、異步工作器和實時事件儀表板的中心。用户將步驟拖到畫布上，放入文檔，然後觀察流水線運行時事件的流回。本文介紹了它的構建方式，特別關注後端工作流如何在 llama-agents 工作流之上設計。

系統形狀

Parse-Flow 分為四個協作進程：

• React 前端：託管基於節點的工作流設計器、運行視圖和作業儀表板。
• Bun 服務器：處理上傳、與 LlamaParse 平台通信、將作業排隊、從 Postgres 讀取歷史記錄，並通過服務器發送事件將事件流橋接到瀏覽器。
• Python 工作器：消費作業並執行實際的文檔工作流。
• Redis：作為作業隊列和事件總線，Postgres 作為作業及其事件歷史的系統記錄。

通信模式如下：Bun 服務器將作業推送到 Redis 列表，工作器拉取作業，並在作業運行時，每個事件被添加到每個作業的 Redis 流中，同時持久化到 Postgres。Bun 服務器通過創建專用訂閲者連接將該流橋接到瀏覽器，發送心跳，並在觀察到最終事件時關閉連接。

這種分離帶來了兩個主要好處：工作器可以慢速運行而不阻塞 HTTP 層；每個事件被捕獲兩次（一次在實時流中，一次在持久存儲中），因此重新加載頁面的用户可以查看並重放從 Postgres 重建的完整歷史記錄。

四個原語，任意組合

工作流詞彙表有意圍繞 LlamaParse 平台提供的服務收窄：

• 解析：使用 Parse 將文檔轉為乾淨的 Markdown 和文本，可選擇層級和提示。
• 分類：根據一組用户定義的規則為文檔分配類別，附帶推理和置信度分數。
• 拆分：根據類別列表將文檔分割成有類型的塊。
• 提取：根據用户提供的 JSON 模式從文檔中提取結構化 JSON。

系統的表達能力並非來自原語本身，而是來自限制它們如何鏈接的允許對圖。並非每個轉換都有意義：提取總是終端，解析可以交給其他三個，分類和拆分可以根據匹配的規則或類別路由到解析或提取。前端在提交之前根據此圖驗證流程，後端在進入時重新驗證。

結果是一個基於 JSON 的小型領域特定語言：一個包含有序步驟和類型化交接的 FlowDefinition，足以描述大多數真實的文檔流水線（解析後提取、分類後路由到正確模式、按章節拆分後分別解析），同時保持足夠小以進行徹底推理。

核心的 LlamaAgent 工作流

有趣的設計工作在工作器中，單個 LlamaAgent Workflow 在運行時解釋用户定義的流程。

llama-agents 框架提供了一個事件驅動的、非固執己見的工作流引擎：每個 @step 是一個異步函數，接收一個事件並返回一個或多個事件，運行時將事件路由到類型簽名匹配的任何步驟。狀態保存在類型化的 Context 存儲中，步驟可以事務性地讀取和編輯。通過 ctx.write_event_to_stream 寫入的事件會被觀察運行的人看到（在我們的例子中是工作器，它將事件轉發到 Redis 和 Postgres）。

Parse-Flow 的 DocumentWorkflow 正好暴露三個步驟，執行系統的關鍵在於它們如何協作以遍歷任意長度的流程。

步驟 1 — 引導

第一個步驟接收一個攜帶解析後的 FlowDefinition 和 LlamaCloud 文件 ID 的 RedisInitialEvent。它將流程寫入工作流狀態，記錄當前索引為零，併發出第一個步驟對應的類型化輸入事件（ParsingInputEvent、ClassifyInputEvent、SplitInputEvent 或 ExtractInputEvent）。從此以後，工作流由數據驅動；引導步驟不再運行。

步驟 2 — 工作器

工作器步驟有一個故意的寬輸入類型：任何 InputEvent。它根據事件類型進行模式匹配，推進步驟索引，並分派到 LlamaParse 平台上的相應操作。每個操作返回一個類似 Rust 的 Result，該結果被解包為類型化的成功事件（帶有解析後的 Markdown、分類判定、分割塊或提取的 JSON）或攜帶失敗消息的 ErrorOutputEvent。

一個重要細節：一旦解析步驟產生了 parse_job_id，後續的分類和提取操作會優先使用該 ID 而不是原始文件。這意味着當用户鏈接解析 → 提取時，提取步驟操作的是已解析的表示，而不是從頭重新解析文件，這是跨步驟共享狀態帶來的免費延遲和成本降低。

步驟 3 — 路由器

後處理步驟是在運行時實際執行允許對圖的地方。它查看最後一個輸出事件、流程中的當前步驟以及上一步驟記錄的交握描述符。從這三條信息中，它決定下一步發出什麼：

• 如果已經走到流程末尾，則將最後一個輸出包裝在 WrapperStopEvent 中，工作流終止。
• 如果輸出是錯誤，則短路至停止。
• 否則，它根據交握（如 classify-extract、parse-classify、split-parse 等）構造下一個輸入事件。對於路由交握，這意味着查找與前一步驟匹配的規則對應的 JSON 模式、解析層級和提示或類別，並將它們打包到下一個輸入事件中。

然後，該路由器再次發出 InputEvent，直接循環回工作器步驟。引導-工作器-路由器三元組成為一個狀態機，一步一步地遍歷用户的工作流，每個轉換都是類型化的，每個交握都經過驗證，每個事件都可觀察。

儀表板顯示 Parse-Flow 運行期間的事件

為什麼這種設計成立

三個屬性使設計令人愉悦：

1. 流程存在於事件中，而非代碼中。相同的 DocumentWorkflow 運行每個作業。新流水線不需要新的 Python 代碼，只需要一個新的 JSON 流程定義。這使得在其之上構建可視化設計器變得可行。
2. 每個轉換都是可觀察的。因為每個步驟在返回之前將其事件寫入流，儀表板看到的工作流與工作流自身看到的一樣。沒有單獨的日誌層會與現實不同步。
3. 失敗是一個值。錯誤是一等輸出事件，路由器知道如何將其轉為乾淨的停止。用户收到一個帶有真實消息的最終事件；系統永遠不會靜默掛起。

文檔智能是重要的層

在 2026 年，很容易將解析和提取視為隱藏在模型調用後面的已解決問題。事實並非如此。一個用錯誤模式分類發票、或在錯誤邊界拆分合同、或從錯誤頁面提取日期的流水線，會以下游無法恢復的方式失敗。持久的系統是那些將文檔智能視為頭等工程問題的系統：可組合的原語、驗證過的轉換、可觀察的運行、持久化的歷史。

Parse-Flow 是當你讓工作流層得到正確設計時的一個小例子：四個原語、一個類型化交握圖和一個只負責遍歷它的 LlamaAgent 工作流。

嘗試它

完整源碼是開源的。克隆它，指向一個 LlamaCloud 密鑰，然後帶上你自己的文檔。 → github.com/run-llama/parse-flow