RAGFlow 在 8 月 4 號更新了 v0.20 版本，這是時隔兩個多月之后，更新的一個里程碑式的版本，RAGFlow 在 Agent 板塊的拼圖這次終于算是完整了。其實早在一年前，RAGFlow 就有了 Agent 模塊，但是一直只包含 Workflow。而且相比于 Dify 而言，社群對這部分的工具/插件的豐富度、易用性和 UI 美觀度而言，一直也有吐槽。

過去大半年，市場上也出現了很多 RAGFlow 知識庫+Dify 工作流的各種混合用法。這也說明了從產品定位上來說，RAGFlow 更偏向于一個專業的 RAG 引擎。而 Dify 則把工作流編排作為核心競爭力之一，投入了更多資源在易用性和社區建設上。不過隨著 RAGFlow 在企業級應用中的不斷深入，或許會催生出更多標準化的集成需求，從而為其工作流插件生態的發展帶來新的可能性。

言歸正傳，這篇試圖說清楚：

這篇來做個 text2sql 的簡單 RAGFlow agent 的案例演示，順便介紹下這次的主要 Agent 更新特性。選題是來自官方公眾號一周前發布的一篇關于 SQL Assistant 的 demo 基礎上，優化了數據樣例和測試問題，但出現了增加了驗證與自修復環節的報錯，最后也會對比下在 Dify 上實現效果。

以下，enjoy：

1、版本升級參考

為了方便不熟悉版本升級的盆友操作，這里再簡要介紹下相關操作。由于數據卷是獨立于容器的，新的容器會重新掛載已存在的數據卷，從而保留歷史項目文件。

所以為了升級 v0.20（或者最新的 0.21），不需要重新部署。修改 ragflow/docker/.env 文件，更新 RAGFLOW_IMAGE 變量為你想要升級到的版本號。然后運行下述 Docker 命令會拉取 .env 文件中指定的新版本鏡像，并使用新的鏡像重新創建和啟動容器。

cd docker
docker compose -f docker-compose.yml pull
docker compose -f docker-compose.yml up -d

2、工作流邏輯

先看下工作流的整體架構，以及關鍵節點的配置操作。然后在正式測試前我會再介紹下知識庫和數據庫的相關配置。

2.1三個檢索節點

Schema：返回表結構片段（召回參數放寬，保證至少返回一條，用作硬約束）。

Question to SQL：召回 few-shot SQL 示例。

Database Description：返回字段語義/同義詞（可選，易超時時可暫時移除）。

2.2生成節點（SQL Generator）

system prompt 放“角色/輸出規范”，從三個檢索節點注入上下文。

user prompt 只放 {sys.query}（最佳實踐：把用戶問題與系統上下文分層，避免被覆蓋）。

注：官方演示文章中這部分是錯誤的，如果把三個知識庫的輸出變量放在 user prompt 中，會被實際用戶消息覆蓋，導致 LLM 收不到 Schema 示例而不觸發生成。應把檢索到的上下文注入 system prompt（或模型的“上下文位”），user 僅放用戶提問。

值得注意的是，在Agent節點中可以選擇添加平臺內置的工具或者MCP，也可以選擇嵌套其他的Agent。

2.3執行節點（ExeSQL）

讀取生成的 SQL，連接本機 MySQL。參照下述配置：庫 test，用戶 root，密碼 ragflow，端口 3306。主機按運行位置三選一：127.0.0.1 / host.docker.internal / 實際 IP

注意配置完數據庫后，在執行節點做下連通性測試。

3、知識庫構成

先用 Schema.txt 鎖定可用表與字段 → 用 Database Description EN.txt 做語義對齊與別名映射 → 召回 QuestiontoSQL_mysql.csv 的最相近示例做 few-shot 參考并生成/修正 SQL。

不建議直接使用官方提供的 Huggingface 樣例數據，實際測試發現有以下問題：

Snowflake/PG 方言（ILIKE、DATE_PART、三段式 db.schema.table）、摻雜解釋文字/Markdown、外部數據集引用、部分語句殘缺、中英文重復等問題，和本地 MySQL 架構不匹配。

3.1Schema.txt（結構真相/DDL）

讓模型知道真實的表/字段/約束，防止“編字段”；同一份 DDL 也用于實際建表。

切片方法：General、文本塊大小：2 Token、文本分段標識符： “ ; “

3.2Database Description EN.txt（業務語義）

用自然語言解釋表/字段，提供同義詞/口徑，幫助從中文/英文問題映射到正確字段。

切片方法：General 建議文本塊大小：2 Token 文本分段標識符：##

3.3QuestiontoSQL_mysql.csv（few-shot 示例）

“問題→SQL”成對樣例，嚴格使用 MySQL 8 方言，且字段/表只來自 Schema.txt 的 users/products/merchants。覆蓋單表篩選、JOIN、聚合/HAVING、時間過濾、排序/TopN 等常見模式。

配置切片方法為 Q&A

4、數據庫配置

4.1Schema_ordered.sql

與 Schema.txt 等價，但按依賴順序建表：merchants → users → products，避免外鍵引用表未創建導致的導入報錯。

4.2seed.sql

插入更“像真實數據”的分布（價格/庫存/類別/時間差異、零庫存、空描述、商家分配不均），便于測試 TopN、時間、HAVING、多指標聚合；腳本會先 TRUNCATE 三表再插入。已修復外鍵映射，確保 merchant_id 一定落在實際存在的商家集合。

5、實際測試

5.1問題測試

統計最近 7 天每天新增的用戶數量，按日期從早到晚展示

選擇理由：覆蓋時間過濾與按日分組；檢驗是否用 MySQL 的日期函數（如 DATE()、INTERVAL），避免方言錯誤。

更多測試用例各位可以自由探索，完整的工作流json文件及測試文檔已發布至知識星球。

5.2擴展報錯

我嘗試增加了驗證與自修復環節的處理邏輯，但是報錯顯示 CodeExecParam 。這是由于平臺端定義的“代碼節點工具”的參數模型/適配器。缺失這個任何 Code 節點都會在解析階段失敗。

這通常由“后端版本不含代碼工具/未開啟安全開關/版本不匹配”導致。我沒有具體研究如何解決，感興趣的盆友可以再具體測試下。

總結來說，還是期待RAGFlow的Agent組件后續保持快速迭代。目前版本看起來，相比在Dify上實現類似功能，似乎還有很多核心節點的穩定性和延展性上做不少優化工作。