基于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-failure

1、端口已映射: 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.1

Bucket 创建

登录 MinIO Console 后（使用 .env 文件中的用户名/密码)创建 Bucket。点击左侧 "Buckets" 、 "Create Bucket"，建议使用一个明确的名称，例如 ragflow-public-assets ，取消勾选 "Versioning" (版本控制)，否则会占用更多空间。

3.2

设置公共读策略

创建 Bucket 后，点击该 Bucket 名称进入详情。选择 "Access Policy" 将 Bucket 的访问策略设置为 "public"。这一步很重要，确保 Dify 和最终用户能通过 URL 读取图片和映射文件。

4

相关脚本优化

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 的完整输出才能进行处理