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