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

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

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

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

以下，enjoy：

1、版本升級參考

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

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

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

2、工作流邏輯

先看下工作流的整體架構(gòu)，以及關(guān)鍵節(jié)點的配置操作。然后在正式測試前我會再介紹下知識庫和數(shù)據(jù)庫的相關(guān)配置。

2.1三個檢索節(jié)點

Schema：返回表結(jié)構(gòu)片段（召回參數(shù)放寬，保證至少返回一條，用作硬約束）。

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

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

2.2生成節(jié)點（SQL Generator）

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

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

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

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

2.3執(zhí)行節(jié)點（ExeSQL）

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

注意配置完數(shù)據(jù)庫后，在執(zhí)行節(jié)點做下連通性測試。

3、知識庫構(gòu)成

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

不建議直接使用官方提供的 Huggingface 樣例數(shù)據(jù)，實際測試發(fā)現(xiàn)有以下問題：

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

3.1Schema.txt（結(jié)構(gòu)真相/DDL）

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

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

3.2Database Description EN.txt（業(yè)務(wù)語義）

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

切片方法：General 建議文本塊大?。? Token 文本分段標(biāo)識符：##

3.3QuestiontoSQL_mysql.csv（few-shot 示例）

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

配置切片方法為 Q&A

4、數(shù)據(jù)庫配置

4.1Schema_ordered.sql

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

4.2seed.sql

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

5、實際測試

5.1問題測試

統(tǒng)計最近 7 天每天新增的用戶數(shù)量，按日期從早到晚展示

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

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

5.2擴展報錯

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

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

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