上周我把 RAGFlow 部署好准备在文档问答里试一下 DeepSeek Flash 视觉模型的效果结果打开模型选择下拉框翻了两遍——没有。用 OpenAI-API-Compatible 走自定义模型源接进去之后整个过程其实只要五分钟但第一遍踩坑的人基本都倒在两个地方要么不知道“模型列表不是自动扫描出来的”要么没搞懂“注册完还要分配角色”。这篇文章就用我的实际配置过程把 RAGFlow 对接自定义视觉模型这条路完整捋一遍。适合正在部署 RAGFlow、想换国产模型或视觉多模态模型又对“为什么搜不到新模型”一头雾水的开发、运维和算法同学。后面每一步我都会说清楚“为什么这么做”而不是只丢给你一堆按钮路径。1. 为什么 RAGFlow 搜不到 DeepSeek Flash模型发现机制先搞懂1.1 RAGFlow 的模型列表不是“实时扫描”出来的很多人的第一反应是DeepSeek 的接口本来就是 OpenAI 格式RAGFlow 只要连上 API不是应该自动把所有模型都列出来吗还真不是。RAGFlow 对模型的管理方式更像手机通讯录而不是实时通讯录助手。它启动时不会向每个模型服务商发送“GET /models”之类的请求去拉全量模型清单而是使用一套内置模型供应商配置 用户手动添加模型源的机制。你看到的那个下拉列表来自 RAGFlow 安装包预置的模型清单以及你自己在“模型供应商”里新建的模型条目。这样设计有它的道理。RAGFlow 在调度模型时不光要知道“能不能连上”还得知道这个模型能干什么。它内部把模型能力粗略分成聊天、嵌入、重排、语音识别、图像理解等几类。比如文档切片阶段要用 embedding 模型生成引用回答要用 chat 模型上传图片做多模态问答时要用 vision 类型的模型。这些能力标签必须在模型注册阶段就确定下来而不是每次调用时现去探测。否则每次都会慢、会不稳定离线部署和局域网环境更是会直接挂掉。所以“搜不到 DeepSeek Flash”很正常。它只是没被预置清单收录并不代表 RAGFlow 不支持它。你要做的是手动把它加进去顺便告诉 RAGFlow“这个模型到底属于哪一类”。1.2 模型能力声明比“能不能连”更重要RAGFlow 里有一个专门的供应商类型叫 OpenAI-API-Compatible。这个类型的意义在于不管对方是 DeepSeek 官方接口、国内某个模型聚合网关还是你自己用 vLLM 架起来的模型服务只要它遵循 OpenAI 的请求/响应格式RAGFlow 就可以通过同一个适配器对接。它就相当于一个万能转接头。你告诉 RAGFlow 四个信息地址在哪里、密钥是什么、模型叫什么、这个模型能干什么它后续就会按 OpenAI 格式把请求发过去。这里有个非常容易被忽略的点OpenAI 官方供应商和 OpenAI-API-Compatible 是两回事。你如果直接去改 OpenAI 那个内置供应商的配置那是针对 OpenAI 官方 API 的。想接 DeepSeek Flash 这类第三方/聚合模型必须在“添加新模型源”时选 OpenAI-API-Compatible让 RAGFlow 把它当作一个独立的自定义源来管理。搞清楚这个机制后面所有步骤就都顺了你不是在“让 RAGFlow 认识一个新模型”而是在“手动向 RAGFlow 注册一个新模型源并把能力标签填对”。2. 接入前需要准备的三样东西API Key、Base URL 与模型 ID2.1 模型 ID以你服务商控制台显示的为准这是最容易出错的地方。很多人会凭直觉把模型名填成“deepseek-flash”或者“DeepSeek-Flash-VL”其实不一定对。DeepSeek 官方开放平台的 API 模型名主力是 deepseek-chat 和 deepseek-reasoner。视觉相关的 DeepSeek-VL 系列模型并不一定以完全相同的命名出现在第三方平台。你现在拿到的“DeepSeek Flash 视觉模型”更常见的是通过某个模型聚合平台、云服务商网关或者企业内部统一网关来提供同一个底层模型在 A 平台可能叫 deepseek-flash-vl在 B 平台可能叫 deepseek-vl-7b。所以配置前必须做一件事登录你申请 API Key 的那个平台在模型列表里把这个视觉模型对应的真实模型 ID 复制出来。这个 ID 才是要填进 RAGFlow 的“模型名称”字段的值。不要猜猜错就是 404。顺带说一句RAGFlow 里“供应商名称”是给你自己看的标识“模型名称”才是真正发给服务商的请求参数。所以供应商名称你可以随便起一个方便辨认的名字但模型名称必须严格匹配平台文档。2.2 Base URL 的两种拼法和一个 curl 连通性测试Base URL 也经常填错。OpenAI 完整接口路径是 POST /v1/chat/completions所以 Base URL 一般填到 /v1 这层。例如 DeepSeek 官方兼容接口填 https://api.deepseek.com/v1 就行RAGFlow 会在后面拼上 /chat/completions。DeepSeek 官方文档说 https://api.deepseek.com 不带 /v1 也能调但为了兼容其他平台和减少拼接歧义我统一建议填带 /v1 的版本。最坑的写法是把完整路径填进去比如 https://api.deepseek.com/v1/chat/completions这样 RAGFlow 最终请求会拼成 /v1/chat/completions/chat/completions必挂。拿到模型 ID 和 Base URL 之后先用 curl 把连通性验证一遍不要直接往 RAGFlow 里填。以 DeepSeek 官方兼容接口为例curl https://api.deepseek.com/v1/chat/completions \ -H Authorization: Bearer $DEEPSEEK_API_KEY \ -H Content-Type: application/json \ -d { model: deepseek-chat, messages: [{role: user, content: ping}], max_tokens: 10 }如果你要从聚合平台接入 Flash 视觉模型就把上面 URL 换成平台的 Base URL模型名换成平台给的视觉模型 ID。返回 200 说明 Key、Base URL、模型名三者匹配可以继续返回 401 是 Key 问题返回 404 或者 model not found基本是模型 ID 或 Base URL 没对上。这一步能帮你省掉后面 90% 的排查时间。因为 RAGFlow 界面上的报错信息有时候比较模糊你分不清是它的问题还是服务商的问题。先用 curl 确认外部接口是通的之后再出问题就可以笃定是 RAGFlow 配置的问题。3. RAGFlow 添加 OpenAI-API-Compatible 模型源的分步操作3.1 新增模型源时的字段怎么填进入 RAGFlow 控制台找到“模型供应商”页面右上角有新增模型源的入口。不同小版本的界面文字可能略有差异但逻辑是固定的选择供应商类型为 OpenAI-API-Compatible然后填一组参数。我把我实际填过的字段列成表格你直接抄字段填写示例说明供应商名称DeepSeek-Flash-VL自定义标识方便在下拉列表里认出它模型名称deepseek-flash-vl必须和你平台控制台显示的模型 ID 完全一致Base URLhttps://api.deepseek.com/v1到 /v1 为止别多带路径API Keysk-xxx你从服务商平台申请到的密钥模型类型聊天 / 图像理解按平台提供的模型能力勾选Max Tokens4096按你实际需求调整这里最关键的字段就是“模型类型”。RAGFlow 不是靠自动试探判断模型能不能看图而是看你有没有给它打上“图像理解”这个能力标签。你只勾“聊天”那么它在图片问答场景就不会调用这个模型或者调用后直接报错。你只勾“图像理解”而没勾“聊天”那它在普通文本对话里又不会被选中。视觉模型通常两个能力都要勾。我当时在这个页面上看到有“测试连接”之类的按钮就顺手点了一下。它能帮你验证 Base URL、Key、模型名是不是已经通到服务商那边比保存完才发现错了要省事。如果你用的版本没有测试按钮就靠前面那一步 curl 兜底。3.2 保存后在系统默认模型里把新模型“分配”出去模型源保存成功之后别急着去聊天页面。这时候你去聊天页面的模型下拉框大概率还是看不到新模型。我当时就在这里卡了快二十分钟一度以为是没保存成功。原因很简单新模型只是完成了“注册”还没有被指定为任何任务的默认模型。RAGFlow 的系统默认模型设置里聊天模型、嵌入模型、重排模型、图像理解模型是分开配的。新注册的模型不会自动顶上任何角色你要手动去“系统默认模型设置”有些版本在模型供应商页面顶部把“聊天模型”和“图像理解模型”指向刚添加的 DeepSeek Flash 视觉模型。这里有个选择建议如果你想所有对话都走这个新模型就把聊天模型和图像理解模型都切过去如果你只是想让它负责看图聊天模型可以继续保持原来的文本模型。RAGFlow 的调用链路里上传图片时是“图像理解模型”在做视觉识别识别结果拼进上下文后再交给“聊天模型”生成最终回答。分配完之后如果聊天下拉框还没出现退出登录重新进来或者刷新一下页面。RAGFlow 的模型列表不是实时热更新的这一点很多刚上手的人都踩过。embedding 模型就别选它了。视觉模型拿来当嵌入模型跑文档切片基本跑不动RAGFlow 的嵌入模型是要对文本向量化的两者不是一回事。4. 验证链路保证新视觉模型真的被 RAGFlow 用上了4.1 用一张图片做端到端视觉验证配置完成不等于万事大吉。我见过不少人配完就以为成功了结果真正上传图片问答时才发现模型根本没被调用。所以一定要做端到端验证。新建一个测试知识库解析方式保持默认就行。上传一张带内容的图片进去比如发票截图、产品说明书截图、或者随便一张有文字的图文。然后在聊天对话框里上传这张图片或把它作为引用文件问一句具体的问题“这张图片里面大概是什么内容”或者“把图片里的文字整理成表格”。如果配置正确RAGFlow 会先把图片转成 base64通常会做压缩处理随请求发给视觉模型视觉模型返回对图片的理解文字再拼给聊天模型生成最终回答。你能看到回答是真的“看懂”了图而不是在敷衍你。如果返回“抱歉我无法查看图片”或者类似提示最可能的原因就是模型类型没勾“图像理解”。回去编辑模型源把图像理解能力补上再试一次。如果上传图片时直接报错那就去看日志下面小节具体说。4.2 从日志和返回结果反推调用细节想确认 RAGFlow 到底调了哪个模型最直接的办法是看日志。我的部署方式是 docker-compose所以先找到 ragflow 服务端容器docker ps | grep ragflow docker logs -f ragflow-server容器名然后在日志里搜模型相关字段重点看请求 payload 里的“model”到底是不是你新加的模型 ID。这一步非常管用因为我之前遇到过一种诡异情况模型源已经加了默认模型也切了但实际返回结果还是旧模型。看日志才发现知识库关联的 Agent 或 Chatbot 配置里模型是单独指定的并不会跟着全局默认设置走。你把全局切了但某个具体聊天应用还是用旧模型。另外如果你用的是聚合网关平台也可以登录它的控制台查看调用记录。请求里如果没有出现视觉模型的 ID说明 RAGFlow 没把请求发过去出现了但报错就按 HTTP 状态码继续排查401 是 Key 无效404 是模型 ID 或 Base URL 不对429 是限流。5. 接入 DeepSeek 视觉模型最容易翻车的 5 个点5.1 模型类型没勾“图像理解”这是视觉模型接入失败的头号原因。RAGFlow 的模型类型字段不同版本可能有不同展示方式有的叫“模型类型”有的叫“能力集”但核心是一样的它决定这个模型能不能被图片问答链路选中。你勾“聊天”但不勾“图像理解”模型注册成功了、连通性测试也过了但上传图片就是不行。操作上找到已添加的模型源编辑它把图像理解类型补上保存后重新加载。如果版本太老不支持一个模型打多个类型标签那就新建一个同模型 ID 的图像理解模型源反正 Base URL 和 Key 一样不影响调用。5.2 Base URL 末尾多写了一段路径我在前面已经反复强调过Base URL 只要到版本号这层。还是会有人填成 https://api.deepseek.com/v1/chat/completions或者聚合平台的 /v1/messages 这种完整端点。RAGFlow 在你填的 Base URL 后面拼 /chat/completions 时就会拼出双路径直接报错。判断规则很简单你填写的 Base URL后面加上 /chat/completions 之后必须能直接访问到有效接口。如果你在浏览器里打开这个拼好的地址能看到错误提示或者文档页说明路径层数是对的如果直接 404大概率就是填多了。5.3 系统默认模型没切换白配一场模型源添加成功、类型也选对了但聊天页面就是看不到新模型或者在某个具体聊天应用里选了新模型回答还是不对劲。这种情况十有八九是“全局默认模型”或“聊天应用自带的模型配置”没同步。RAGFlow 里模型的使用是分层的全局默认设置管的是新建聊天时的兜底而已经创建好的应用/Agent/知识库聊天配置可能固定绑定了某个模型。你要么在全局设置里切要么去你实际使用的那个对话应用里单独改模型两层都得看一眼。5.4 平台 API Key 和模型 ID 不匹配导致的 404/401聚合平台经常有多个模型但不是每个 Key 都有全部模型权限。有些平台的 Key 分了主账号和子账号子账号要单独开通某个模型的访问白名单有些平台的模型分“体验版”和“正式版”同一个 ID 不同后缀。你在 RAGFlow 里填了正确的模型 ID但请求还是 401/403/404先去平台控制台确认一下这个 Key 下是否真的开通了对应模型。这也是我为什么坚持让你先用 curl 测一遍的原因。curl 通了说明 Key 和模型 ID 匹配没问题curl 不通就先别折腾 RAGFlow。5.5 图片被默认压缩小而密的文字识别效果偏差RAGFlow 在把图片发给视觉模型前一般会把图片压缩到较小的尺寸。这套默认策略对自然场景拍照图是够用的但如果你上传的是密密麻麻的表格、票据、代码截图识别效果就会明显变差甚至漏字。这个不完全是你接入方式的问题更多是视觉模型和预处理策略的综合效果。我的个人建议是在服务商网关允许的情况下打开图片高质量/高清模式上传前尽量裁掉无关背景只留信息区域。同时也别期待一个残幅压缩后的图片能产出 OCR 级别的精细结果RAGFlow 目前对图片的定位是“辅助理解”不是“文档高精度识别”。最后分享两个小习惯我给自己所有自定义模型源命名都是“厂商-系列-用途”的结构比如 DeepSeek-Flash-VL-Vision。这样在聊天页面下拉列表里一眼就能认出哪个是视觉模型哪个是纯文本模型不用每次点了才知道是谁。还有一个建议接完之后先拿测试知识库跑两三天把图片问答、文档引用、纯文本对话都过一遍确认稳定了再切生产。尤其是视觉模型的响应速度和网关限流只有实际用起来才知道能不能扛得住你的日常请求量。如果你只想让 RAGFlow 具备“看懂上传图片”的能力聊天主模型其实可以继续用之前的文本模型把图像理解模型指向新的视觉源就行成本和响应速度都会更可控。