上周有个做设备运维的朋友找我，说他用 Dify 搭了一个维修知识库，把设备图纸、现场照片、说明书扫描件都传了上去，结果问“这张图纸里的管径标注是多少”，Dify 只回了一句“未找到相关资料”。他以为是模型太笨，我让他去知识库后台看一眼，才发现这些图片要么格式不被接受，要么进去了也检索不到。这个场景我非常熟悉——很多人对 Dify 的期待是“能传图片”，但 Dify 知识库对图片的处理，并不是把图片当成图片理解，而是要把其中的信息转换成一种可检索的结构。要让大模型知识库在 Ubuntu 上真正支持图片召回，关键不在上传入口，而在整条数据链路的改造。
这篇文章我会从原理讲到落地，覆盖 Ubuntu 环境准备、Dify 部署、图片处理脚本编写、知识库分段设计、工作流返图，以及我踩过的各种坑。适合两类人看：一类是已经在用 Dify、想让知识库支持图片检索的开发者，另一类是准备从零搭一个“图文混合”知识库、但还没想清楚技术路线的朋友。
1. 先弄明白：Dify 知识库里的“图片召回”到底是什么问题
1.1 图片在 RAG 链路中的位置：它不是一个能直接分词的“文档”
RAG 知识库的基本链路是：文档导入 → 分块 → Embedding 向量化 → 存入向量库 → 检索召回 → 交给大模型生成回答。这条链路里，所有环节都在处理“文本”：分块要对文本切分，Embedding 模型接收的是 token，向量库里比较的也是文本向量。
图片不一样。一张 PNG 在计算机里是一堆像素点，没法直接分词，也没有天然对应的 token。你把它拖进知识库，系统不知道该对它做什么。如果只是把图片二进制存入数据库，检索时没有任何语义锚点，自然“召不回”。
所以“图片召回”本质上是一个翻译问题：要么把图片翻译成文字，让文本链路能够索引；要么把图片翻译成向量，让向量链路能够比较。前者更贴近 Dify 现有架构，后者需要额外的多模态向量库。想清楚这一点，后面所有方案选择都会清晰很多。
1.2 三种实现路径：OCR、图生文、多模态向量，我为什么选图生文
我接触到的图片入库方案大体有三类，各有适用场景。
| 方案 | 基本思路 | 召回质量 | 实现成本 | Dify 集成难度 |
|---|---|---|---|---|
| 纯 OCR | 用 OCR 提取图中文字，入库文本 | 对扫描件、票据尚可，对图形化信息基本无效 | 低 | 低 |
| 图生文 | 多模态模型描述图片，生成结构化文本入库 | 高，能描述物体、属性、场景、文字 | 中 | 中 |
| 多模态向量 | 用 CLIP 等模型把图文映射到同一向量空间 | 高，但文本与图片向量不易对齐 | 高 | 高，Dify 无原生支持 |
纯 OCR 的问题在于它丢失了图片里最关键的“视觉语义”。比如一张设备外观图，OCR 只能抽出图上的几行字，但“白色外壳、左侧有散热孔、正面带一块液晶屏”这些信息全部丢失。用户如果问“哪个设备是白色带液晶屏的”，纯 OCR 方案根本召回不了。
多模态向量方案理论最优，但 Dify 目前没把这类模型内置到知识库链路里。你要自己搭一个独立的图片向量库，再写插件或服务去桥接，工程量大，而且图片向量和文本向量如果不在同一空间，检索效果照样扑街。除非你有明确的“以图搜图”需求，否则我不建议第一步就上这个方案。
我最终选择的是“图生文 + 文本 RAG + 外链返图”的组合：用视觉大模型把图片翻译成一段高质量描述文本，这段文本进入 Dify 知识库参与常规检索；图片本身放在 Nginx 或对象存储上，在描述文本里保留图片的绝对 URL。用户问到一个东西时，检索命中的是“图片描述”，回答时把原图链接带出来。这样既绕开了 Dify 的原生限制，又实现了真正意义上的“图片召回”。
1.3 Dify 原生能力边界与“曲线救国”的整体设计
所谓“曲线救国”，就是承认 Dify 知识库本质上是文本仓库，然后围绕它做外围改造。整个架构由四部分组成：
- 图片存储层：图片文件放在统一目录，由 Nginx 提供 HTTP 访问能力。
- 图片描述层：写一个 Python 脚本，调用视觉大模型把图片转成结构化 Markdown 文本。
- 知识库层：把生成的 Markdown 按“一张图一个片段”的方式导入 Dify。
- 应用层：在工作流里做知识检索，从命中片段中提取图片 URL 并展示给用户。
这个设计的好处是每一层都能独立替换。视觉模型想换就换，Nginx 可以换成 MinIO 或 S3，Dify 知识库检索策略也能按效果调整。我在后面的章节里会按这条链路逐步展开。
2. Ubuntu 上准备环境与部署 Dify 时最容易忽略的细节
2.1 检查 Docker 环境与容器编排工具
Dify 官方推荐用 Docker Compose 部署，Ubuntu 上最基础的一件事是把 Docker 环境整干净。先检查两个命令是否可用：
docker --version docker compose version如果 docker 没装，可以走 apt 安装：
sudo apt update sudo apt install -y docker.io docker-compose-v2 sudo systemctl enable --now docker这里有个小坑：Ubuntu 的 docker.io 包版本可能偏旧，但 Docker Compose 插件的 v2 基本够用。装完后记得把当前用户加入 docker 组，避免每条命令都要 sudo：
sudo usermod -aG docker $USER newgrp docker我遇到过不少人在docker compose命令上卡住，报Unknown command "compose"，基本都是因为只装了旧版 docker-compose（Python 版）。现在 Dify 的部署脚本已经按 v2 插件写了，直接用docker compose而不是docker-compose。
2.2 克隆 Dify 仓库并完成初始配置
Dify 的 Docker 编排文件都在独立目录里，拉取方式如下：
git clone https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env复制完.env后，有几项我每次都会检查：
SECRET_KEY：默认值能跑，但生产环境最好改成随机长字符串。POSTGRES_PASSWORD、REDIS_PASSWORD：如果是公网服务器，这些默认密码一定要改。- 存储类型：如果你后续要把图片或文件交给 Dify 管理，需要配置 S3/MinIO 相关变量；如果图片只是放在 Nginx 上，Dify 本地存储就够。
检查完直接启动：
docker compose up -d启动后可以通过docker compose ps看状态。服务比较多，首次启动可能要等一两分钟，等nginx、api、worker三个容器都显示 healthy 了，再打开http://服务器IP/install初始化管理员账号。
2.3 镜像拉取失败和启动卡住的排查顺序
见评论区经常有人发 Dify 拉取镜像失败的截图，我在 Ubuntu 上排查的顺序基本固定：
第一步先看是不是网络波动导致的超时：
docker compose pull如果报dial tcp: lookup registry-1.docker.io之类的解析错误，大概率是 DNS 或镜像源问题。可以在/etc/docker/daemon.json里配置国内常见的 Docker 镜像加速地址：
{ "registry-mirrors": [ "https://docker.m.daocloud.io" ] }然后重启 Docker：
sudo systemctl restart docker第二步看磁盘空间。Dify 全套镜像加起来好几个 GB，/var/lib/docker所在分区如果满了，启动会报no space left on device。
第三步看容器日志。启动卡住最常见的是 API 容器起不来，多半和数据库初始化有关。用docker compose logs api | tail -100能看到具体报错。我遇到过一次是.env里的POSTGRES_PASSWORD含特殊字符，比如@、#，导致数据库连接串解析异常。建议密码只用字母和数字。
还有一点：如果你是在国内服务器上部署，Dify 的镜像拉取偶发失败是正常的，不要反复up -d，而是先docker compose pull确认所有镜像都成功，再执行启动。
2.4 模型供应商接入：视觉模型和 Embedding 模型都要配
Dify 部署好之后，第一件事是接模型。这里需要两类模型：
- Embedding 模型：负责把文本变成向量，比如
text-embedding-3-small、bge-m3。选型时注意向量维度要和知识库一致，中途换模型会导致已入库存量无法检索。 - 视觉模型：负责给图片写描述，比如 GPT-4o、Qwen-VL、Ollama 上的 llava。这个模型不直接参与 Dify 知识库检索，但在图片预处理阶段决定了描述质量。
在 Dify 的“设置 → 模型供应商”里，可以把视觉模型也注册进去，后面做 Agent 或工作流时可以直接调用。不过我的习惯是图片描述脚本独立于 Dify 跑，不占用 Dify 的模型配额，省得把知识库 API 的并发打满。
3. 图片入库的完整链路：从图片目录到可检索的知识库文档
3.1 图片目录规划与外链存储设计
图片不是“传进 Dify”就完事，它必须有一个可被浏览器访问的地址。最简单的做法是 Nginx 挂一个静态目录。
我在服务器上习惯这么规划：
/data/images/ /product/ product_a_001.png product_a_002.jpg /manual/ manual_01.pngNginx 配置如下：
server { listen 8080; server_name _; root /data/images; autoindex off; location / { expires 30d; add_header Cache-Control "public"; } }启动后图片地址就是http://服务器IP:8080/product/product_a_001.png。记得在 Ubuntu 防火墙里放行端口：
sudo ufw allow 8080/tcp这里有个容易被忽略的问题：如果你把 Dify 和 Nginx 用 Docker 部署在同一台机器，容器里的localhost和宿主机不是一回事。Nginx 如果是容器，root路径要映射到宿主机目录；图片 URL 里也要写服务器对外 IP 或域名，不能写localhost，否则用户在浏览器里看到图片时，访问的是他自己的电脑。
3.2 写一个“图生文”预处理脚本，把图片变成结构化 Markdown
这是整条链路的核心。图片描述的质量，直接决定后面检索命中的质量。描述写得越结构化，检索时越容易被语义命中。
我用的脚本逻辑是：读取图片 → Base64 编码 → 调用视觉模型 → 得到结构化描述 → 拼成 Markdown 文件。
import base64 import glob import os from openai import OpenAI client = OpenAI( base_url="http://your-model-api/v1", api_key="your-api-key" ) IMAGE_DIR = "/data/images/product" OUTPUT_DIR = "/data/dify_input/product" IMAGE_BASE_URL = "http://your-server-ip:8080/product" SYSTEM_PROMPT = """你是一个图片信息提取专家。请用结构化方式描述图片： 1. 一句话核心摘要（30字以内） 2. 图中主体对象，包含品牌、型号、颜色、形状、材质等可检索属性 3. 图中所有可见文字，逐行输出 4. 构图、背景、环境氛围 5. 可能的用途或使用场景 不要编造图中不存在的内容。""" def image_to_markdown(img_path: str) -> str: with open(img_path, "rb") as f: b64 = base64.b64encode(f.read()).decode() ext = img_path.rsplit(".", 1)[-1].lower() if ext == "jpg": ext = "jpeg" data_url = f"data:image/{ext};base64,{b64}" resp = client.chat.completions.create( model="gpt-4o", messages=[ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": [ {"type": "text", "text": "请描述这张图片"}, {"type": "image_url", "image_url": {"url": data_url}} ]} ], temperature=0.2 ) description = resp.choices[0].message.content filename = os.path.basename(img_path) url = f"{IMAGE_BASE_URL}/{filename}" md = f"""--- source: {filename} image_url: {url} --- # {filename} {description}  """ return md def main(): os.makedirs(OUTPUT_DIR, exist_ok=True) for img_path in glob.glob(os.path.join(IMAGE_DIR, "*.png")) + \ glob.glob(os.path.join(IMAGE_DIR, "*.jpg")): md = image_to_markdown(img_path) out_path = os.path.join(OUTPUT_DIR, os.path.basename(img_path) + ".md") with open(out_path, "w", encoding="utf-8") as f: f.write(md) print(f"processed: {img_path}") if __name__ == "__main__": main()这段代码有几个设计细节：
temperature=0.2：图片描述要尽量稳定准确，温度太高会编造内容。- YAML 头里的
image_url单独存放：后面从知识库结果里提取图片地址时，直接查这个字段比从正文正则匹配稳定得多。 - Markdown 正文里再带一次图片链接：这样用户在 Dify 的文档预览里也能看到图。
脚本跑完后，/data/dify_input/product下每个图片对应一个 Markdown 文件。文件名我建议在脚本里顺手做一下规范化，比如转小写、空格换下划线，避免中文和特殊字符。
3.3 知识库分段与元数据设计，避免图片 URL 被切碎
Dify 知识库导入文档时，默认按固定长度切块。问题来了：如果分段长度太小，图片 URL 可能被从中间切断，变成![product_001](http://your-server-ip:8080/product，后半截丢了。这是图片召回里最经典的一个坑。
解决办法是在创建知识库时自定义分段设置。我的做法：
- 分段标识符设为
---，因为我们生成的 Markdown 用了---做 YAML 头和正文的分隔； - 分段最大长度设 500 左右，图片描述通常不会超过这个长度；
- 分段重叠设 0，保持每个片段独立。
这样每个 Markdown 文件基本上就是一个整体片段，YAML 头里的image_url和正文的图片链接都完整保留。
如果用的是 Dify API 上传文档，分段标识符可以显式传参。创建知识库后，在“文档 → 分段”里也能看到切分结果。我每次导入后都会抽一个文档检查：内容是否完整，image_url是否被截断。这个习惯帮我省了很多排查时间。
3.4 上传后的自测：用“召回测试”验证图片能不能被搜到
Dify 知识库页面有个“召回测试”入口，输入一段查询语句，能看到命中了哪些分段以及相似度得分。这一步必须做，而且要准备一组贴合业务的问题。
比如我导入了一批设备图片，会测试：
- “红色外壳带液晶屏的设备”
- “型号为 HK-300 的控制器”
- “产品手册里提到过压力范围是多少”
理想情况下，第一个问题应该命中那张红色液晶屏设备图的描述，分数在 0.4 以上；第二个问题命中包含型号文字的片段；第三个问题如果没附图，也应该命中说明书正文。
如果测试下来命中不了，优先检查描述文本里有没有对应的语义词。比如用户习惯问“红色外壳”，但你的描述写的是“设备外壳颜色为鲜红色”，虽然语义接近，向量模型不一定能完全对齐。解决方法是描述里同时保留“口语化说法”和“属性结构”。我在描述模板里加了一句“外观颜色：红色”，效果提升明显。
4. 应用端返图：让检索结果真正“吐出”图片而不是文字摘要
4.1 知识检索节点返回的内容结构
图片描述成功入库并召回，只完成了第一步。用户真正看到的是应用端的回答，他不在乎你后端怎么索引，他只看答案里有没有图。
Dify 工作流里接入知识库用的是“知识检索”节点。这个节点接收查询文本，输出一个数组，每个元素包含文档的分段内容、元数据、相似度得分。结构大致如下：
{ "result": [ { "content": "# product_a_001.png\n\n这是产品A的外观图...", "metadata": { "source": "product_a_001.png", "image_url": "http://your-server-ip:8080/product/product_a_001.png" }, "score": 0.56 } ] }如果你的知识库分段里没加元数据，metadata可能只有doc_id之类。所以我在第 3 章强调要保留 YAML 头，因为 YAML 头里的image_url会出现在content开头，方便提取。
4.2 通过工作流提取图片 URL 并展示
提取图片 URL 有两种方式：一种用代码节点做正则提取，另一种用 LLM 节点让模型自己判断。我两个都用过，实际体验差异很大。
代码节点稳定但需要处理 Dify 的输入输出结构。我用的核心提取逻辑是这样的：
import re def main(result: list) -> dict: urls = [] for item in result: content = item.get("content", "") # 匹配 Markdown 图片语法 found = re.findall(r"!\[.*?\]\((http[^)]+)\)", content) urls.extend(found) # 兼容 YAML 头里单独存放的 image_url m = re.search(r"image_url:\s*(http\S+)", content) if m: urls.append(m.group(1).strip()) return {"urls": list(dict.fromkeys(urls))[:3]}在 Dify 的代码节点里，输入变量名和你配置的“输入变量”映射有关。比如把知识检索节点的result映射为result，代码节点出入口都要在变量类型里定义清楚。
LLM 节点更聪明，但偶尔会“过度理解”。我试用过直接让大模型从content中提取图片链接并输出，质量不稳定。一次性给我 8 张图、漏选重要图片、或者把不相干的图片也塞进来，都遇到过。所以现在生产环境我偏好代码节点做初筛，再用 LLM 节点做排序。
4.3 提示词设计：让大模型把图片当作答案的一部分
如果只是把图片 URL 塞给用户，体验很生硬。更合理的回答方式是：先用文字说明依据，再把相关图片以 Markdown 形式展示出来。
我工作流里 LLM 节点的提示词大致如下：
你是一名熟悉设备资料库的助理。请根据检索到的文档片段回答用户问题。 要求： 1. 如果片段中有相关图片链接，在回答末尾用 Markdown 图片格式展示： 2. 每张图片对应一行，图片描述要简短准确，来自文档内容 3. 不要编造文档片段中不存在的图片 4. 如果文档片段没有图片，只输出文字回答这个提示词里的“不要编造图片”很关键。LLM 看到图片 URL 后，如果上下文里有多个 URL，它可能会自己“联想”出一张并不存在的图。加了上面这句之后，返图准确率高了很多。
4.4 检索质量优化：混合检索与 Rerank
我在第 3 章的测试中发现，单靠向量检索，图片描述里的一些精确型号、编号容易漏召回。Dify 知识库支持三种检索模式：向量检索、全文检索、混合检索。
向量检索适合语义相近但用词不同的情况，比如“红色的盒子”匹配“外壳为红色”。全文检索适合精确词命中，比如“HK-300”。图片描述里既有语义描述又有具体型号，所以我推荐用混合检索。
如果检索精度还是不够，加一层 Rerank 模型。Dify 支持配置 Rerank 模型，比如bge-reranker-v2-m3。它的作用是把召回的前 20～50 个候选重新排序，把真正相关的片段排到最前面。我实测下来，加了 Rerank 之后，图片描述片段排名明显上浮，Top1 命中率提升明显。
检索参数我建议这样调：
- TopK：8～12，候选多一点，给 Rerank 留足空间；
- Score 阈值：先设 0.3，如果误召回太多再往上调；
- Rerank TopN：最终返回给模型 3～5 条。
5. 避坑指南：这些“图片召回”相关的坑，我一个个踩过来
5.1 图片“传上去了”但知识库检索不到：格式与编码问题
很多人的第一反应是问“Dify 知识库能不能传图片”。实际情况是，Dify 把图片当文档处理的路径非常有限，即便你通过某些方式把图片文件塞进了文档，检索时也不会对图片本身建立索引。图片要进知识库，必须先经过“图生文”转换。
另外，图片文件本身也可能有问题。PNG、JPG 通常没问题，但 WebP 在某些模型服务里不支持直接 Base64 传输，需要先转码。还有一次我处理批量图片时，脚本读出来发现是 0 字节，原因是有几张图片在 Windows 下编辑后扩展名是.png，实际内容是 JPEG，后端解析失败。脚本里最好加一步文件头检查，或者统一转成 RGB 模式的 JPEG/PNG。
图像大也是隐患。一张 10MB 的图片 Base64 后约 13MB，直接塞进 API 请求很容易触发网关超时或 413 错误。我在脚本里加了一个预处理步骤：超过 2MB 的图先压缩到 1024px 宽度，质量 85 再发送。这个尺寸对视觉模型来说足够识别细节，请求量也小很多。
5.2 图片链接在分段后被截断的经典问题
这个坑我前面提过一次，但因为太典型，值得再展开。Dify 默认分段长度是 500 字符，如果 Markdown 的 YAML 头、标题、描述、图片链接连在一起超过 500，默认分段方式会从第 500 个字符硬切。图片链接长的话，极易被切在中间。
我当时遇到的现场是：检索结果里的content变成了... : try: md = image_to_markdown(img_path) break except Exception as e: print(f"retry {attempt} for {img_path}: {e}") time.sleep(2 ** attempt) else: print(f"failed: {img_path}")这里的time.sleep(2 ** attempt)是退避策略，第一次失败等 2 秒，第二次等 4 秒，第三次等 8 秒。能有效缓解瞬时限流。
5.6 改完 Embedding 模型后老数据全部失效
这个坑在图片入库场景特别容易踩。因为做图片召回时，你会反复尝试不同 Embedding 模型，想找效果最好的一个。但 Dify 知识库一旦用了某个 Embedding 模型，之前入库的向量就全部锁死在这个模型的向量空间里。中途换模型，旧向量和新查询向量不在同一空间，相似度计算就是错的。
我有一次把text-embedding-3-small换成了本地bge-m3，结果所有旧文档全部召回异常，分数普遍掉到 0.1 以下。最后只能清空知识库重新导入。
所以建议是：在图片预处理脚本写好之后，先用 10～20 张图做一轮完整测试，确认描述质量和检索效果都满意了，再正式批量入库。Embedding 模型的选型，最好第一批测试时就定下来，后期不要轻易换。
6. 最终效果与几点个人建议
这套链路跑通之后，最终效果是这样的：用户问“红色外壳带液晶屏的设备”，工作流先通过知识检索命中对应图片描述文本，代码节点从命中片段提取出image_url，LLM 节点在回答末尾展示图片，用户看到的是一条带文字的说明加一张真实的产品图片。整个过程从提问到出图，大概两三秒。
如果让我重新搭一遍，我会在第一步就把图片描述模板固定下来，并且用 10 张不同类型的图先做召回测试，确认描述风格稳定后才开始批量。描述模板里的“口语化说法”和“属性结构”两段一定要保留，这直接影响向量召回的命中率。
另外，图片 URL 不要只留在正文里，单独存到 metadata 或 YAML 头这种结构化字段里，能省掉后面 80% 的提取麻烦。Nginx、防火墙、文件名规范这些基础工作，看似和“大模型知识库”无关，但图片召回的体验 90% 都卡在这些基础环节上。把这套链路跑熟之后，你会发现图片知识库和文本知识库的差别，其实只差一个“翻译”步骤。
