基于MiniO存儲的RAGFlow+Dify圖片處理方案
上篇文章中介紹了如何基于 RAGFlow 知識庫，通過 Dify 的 HTTP 請求獲取映射 + Code 節點替換，將占位符解析為最終的 <img> 標簽，來穩定的實現問答中圖片正常顯示問題。
Dify+RAGFLow：基于占位符的圖片問答升級方案（最佳實踐）
其中的"占位符"和"實際圖片訪問 URL"映射關系的存儲使用了阿里云的 OSS 存儲服務。初期選擇阿里云 OSS 作為存儲，主要是方便大家快速驗證和迭代 RAG 應用的核心邏輯，避免過早陷入基礎設施的維護細節。
有知識星球的星友提出希望能提供本地部署的存儲方案，市面上有挺多優秀的開源對象存儲框架可供選擇，Ceph、OpenStack Swift 功能全面但架構復雜高，出于規模可控和運維簡單的考慮，MinIO 和 SeaweedFS 都是不錯的選擇。
鑒于 RAGFlow 的 Docker 部署本就包含了一個 MinIO 實例，原本主要用于存儲知識庫的原始文件、塊數據等，利用這個現有的 MinIO 服務來存儲提取的圖片和映射關系是一個很好的本地化部署方案，也可以在上一版方案基礎上，移除對外部云服務（阿里云 OSS）和獨立圖片服務器的依賴。
以下，enjoy：
1、“語義幻覺” vs “格式遵循”
在正式進入 MinIO 的存儲方案調整前，我們再來回顧下，在富文本中直接嵌入完整 URL 可能導致 LLM“幻覺”并修改圖片鏈接的考量所在。
1.1直接嵌入 URL
當 LLM 在其上下文中看到一個完整的、看似有意義的 URL 時，例如<img src="..."> 或 http://.../filename.png，特別是像<img>標簽這樣結構化的 HTML，它有一定概率（不同 LLM 實測篡改 URL 的概率不太一致）會嘗試去“理解”這個 URL 指向的內容，并結合周圍的文本進行推理。
例如如果文本描述了“燃油噴射器泄漏”，而 URL 的文件名是 page1_img1_uuid.png，LLM 可能會認為存在不匹配，并“好心”地嘗試生成一個它認為更符合語義的 URL，例如 .../fuel_injector_leak.png。這樣導致了很多盆友說為什么知識庫中能渲染圖片，但是回答中卻無法顯示的問題。
其實這也很好理解，本質上這是源于 LLM 被訓練來生成連貫、相關的文本，有時會過度泛化到它不應修改的結構化數據上。
1.2占位符方案的意義
[IMG::page1_img1_uuid.png]這種格式對 LLM 來說，更像是一個需要特殊處理的“元數據標記”或“代碼片段”，而不是一段可供自由發揮的自然語言或標準 HTML。通過 Prompt 工程明確指示 LLM 將這些標記視為特殊占位符，并在需要引用時原樣復制，實測確實可以大大降低它進行“創造性修改”的動機。LLM 更傾向于遵循這種明確的格式指令，而不是去猜測 page1_img1_uuid.png 的語義含義并嘗試“改進”它。
總結來說，使用占位符的方案，是把潛在的圖片鏈接錯誤問題，從一個不可控的 LLM“語義理解導致的幻覺修改”問題，轉變為一個相對更容易通過 Prompt 工程來約束的“格式遵循”問題。要求 LLM 精確復制一個特殊格式的字符串，通常比要求它不對一個看起來像自然語言一部分的 URL 進行語義修改要更容易實現和控制。
2、RAGFlow 的 MinIO 訪問結構
2.1內部訪問
RAGFlow 的其他服務（如 API 服務、Worker）在 Docker 網絡內部通常通過服務名（例如 minio）和默認端口（9000 for API, 9001 for Console）訪問 MinIO。
2.2外部訪問
首先需要明確的是，RAGFlow的MinIO 服務是否映射到了宿主機。在 docker-compose.yml 的開頭第一行可以看到 include: - ./docker-compose-base.yml 這行，它表示 docker-compose.yaml 文件本身并不包含所有服務的完整定義，而是包含了同目錄下另一個名為 docker-compose-base.yml 文件的內容。
像 MinIO、MySQL 這些基礎服務的具體配置實際是定義在 docker-compose-base.yml 文件中。
我們打開 docker-compose.yaml 同級文件夾下的 docker-compose-base.yml，來看下 minio 服務的具體定義內容。
為了方便大家看的更直觀些，我在關鍵的位置添加了注釋如下：
minio:
image: quay.io/minio/minio:RELEASE.2023-12-20T01-00-02Z
container_name: ragflow-minio
command: server --console-address ":9001" /data
ports: # <--- 關鍵部分在這里
- ${MINIO_PORT}:9000 # <--- API 端口映射
- ${MINIO_CONSOLE_PORT}:9001 # <--- Console 端口映射
env_file: .env # <--- 環境變量從 .env 文件加載
environment:
- MINIO_ROOT_USER=${MINIO_USER} # <--- MinIO 用戶名 (來自 .env)
- MINIO_ROOT_PASSWORD=${MINIO_PASSWORD} # <--- MinIO 密碼 (來自 .env)
- TZ=${TIMEZONE}
volumes:
- minio_data:/data
networks:
- ragflow
restart: on-failure1、端口已映射: minio 服務明確定義了 ports: 部分，將容器內部的 API 端口 9000 和 Console 端口 9001 映射到了宿主機。
2、端口號是變量: 映射到宿主機的具體端口號不是固定的 9000 和 9001，而是由環境變量 ${MINIO_PORT} 和 ${MINIO_CONSOLE_PORT} 決定的。
3、環境變量來源: 這些環境變量（MINIO_PORT, MINIO_CONSOLE_PORT, 以及 MINIO_USER, MINIO_PASSWORD）的值是從項目根目錄下的 .env 文件中讀取的 (env_file: .env)。
2.3訪問憑證獲取
我們需要找到 env 中的 minio 訪問憑證，以便接下里修改 process_pdf.py 腳本能夠連接和上傳文件。打開與 docker-compose.yaml 和 docker-compose-base.yml 文件位于同一目錄下的 .env 文件后可以發現，MinIO 配置信息如下:
MinIO API 宿主機端口: 9000
MinIO Console 宿主機端口: 9001
MinIO 用戶名 (Access Key ID): rag_flow
MinIO 密碼 (Secret Access Key): infini_rag_flow
2.4訪問測試
通過瀏覽器訪問 http://<你的宿主機 IP>:9001 來打開 MinIO 的 Web 管理界面 (Console)。注意需要把<你的宿主機 IP>替換為你運行 Docker 的那臺機器的實際 IP 地址。如果不清楚如何查看宿主機的 IP 地址，參考下方圖示進行操作：
3、MinIO Bucket 配置
3.1Bucket 創建
登錄 MinIO Console 后（使用 .env 文件中的用戶名/密碼)創建 Bucket。點擊左側 "Buckets" 、 "Create Bucket"，建議使用一個明確的名稱，例如 ragflow-public-assets ，取消勾選 "Versioning" (版本控制)，否則會占用更多空間。
3.2設置公共讀策略
創建 Bucket 后，點擊該 Bucket 名稱進入詳情。選擇 "Access Policy" 將 Bucket 的訪問策略設置為 "public"。這一步很重要，確保 Dify 和最終用戶能通過 URL 讀取圖片和映射文件。
4、相關腳本優化
修改后的源碼和Dify YAML文件在知識星球No.33期
4.1修改 process_pdf.py
主要改動包括：
替換 oss2 導入為 minio 導入，移除與 oss2 相關的初始化和配置代碼。
移除 --oss_map_prefix, --image_dir, --mount_dir 命令行參數及其相關邏輯（包括本地圖片復制）。
修改 extract_images_from_pdf 的調用簽名，傳入 MinIO 相關參數。
添加將 placeholder_map 上傳到 MinIO 的邏輯，并打印 MinIO 公開 URL。
更新腳本末尾的說明，移除關于 image-server 的指令，改為提示用戶在 Dify HTTP 節點中使用 MinIO 映射文件的 URL。
移除錯誤處理和最終清理中與 ./images 相關的部分。
4.2修改 PyMuPDF_test.py
修改函數簽名:
接收minio_client, bucket_name, image_prefix, minio_endpoint_for_url，移除 image_server_dir, image_server_url。
移除本地臨時目錄:
刪除 temp_dir 和 os.makedirs(temp_dir, ...).
圖片處理循環:
獲取 png_bytes 后，不再保存到本地 temp_path。
生成 MinIO 的 image_object_name（使用 image_prefix）。
直接使用 minio_client.put_object 上傳 png_bytes (包裹在 io.BytesIO 中)，設置 content_type='image/png'。
構建 MinIO 的公開 image_url（使用傳入的 minio_endpoint_for_url）。
占位符 placeholder 使用 os.path.basename(image_object_name)。
img_info 中記錄 object_name 和 MinIO URL，移除 temp_path。 更新錯誤處理。
移除本地保存
刪除 with open(temp_path, "wb") 代碼塊。
4.3修改 Dify 工作流
HTTP Request 節點:
將其中的 URL 字段修改為指向 MinIO 上傳的 *map.json 文件的公開訪問 URL（即 process_pdf.py 腳本最后打印出的那個 URL，例如 http://<你的宿主機 IP>:9000/ragflow-public-assets/mappings/your_document_map.json）。
確保請求方法是 GET。
其他如 Header、Body 等通常不需要設置。
Code 節點:
其輸入應該連接到上述 HTTP Request 節點的 body 輸出。
其代碼邏輯保持不變：解析傳入的 JSON 字符串（映射關系），然后在 LLM 返回的文本中查找 [IMG::...] 占位符，并使用映射中的 MinIO URL 將其替換為 <img src="..."> HTML 標簽。
5、寫在最后
完成以上所有修改后，處理流程將完全依賴于 RAGFlow 自帶的 MinIO 實例，不再需要獨立的圖片服務器和外部 OSS 服務，同時保留了占位符方案帶來的 LLM 輸出穩定性優勢。這種方法簡化了部署架構，實現了完全本地化，是更優的方案，尤其是在項目成熟后。
仍需說明的是，當前工作流設計有個無法流式輸出影響體驗的問題，主要因為 Code 節點是一個批處理節點，需要等待 LLM 的完整輸出才能進行處理，下期展示下如何進一步通過 Tampermonkey 用戶腳本為本地 Dify 添加前端圖片占位符替換功能。
