需求设计文档

0. 文档标识

• 任务前缀：图搜图-当前需求
• 文档文件名：图搜图-当前需求-需求设计文档.md
• 更新时间：2026-05-01
• 文档状态：v2.0 反向核对完成，补齐重建链路与搜索测试页 UI
• 文档定位：基于用户提供的两份 PDF、UI 截图、最新补充确认口径，以及当前 FastGPT 仓库事实，重新定义图搜图功能的产品边界、前后端影响域和实现策略。

1. 需求背景与目标

1.1 背景

当前 FastGPT 知识库已支持文本向量检索、全文检索、混合检索、VLM 图片解析、图片文本索引和知识库搜索节点，但还没有完整的“图片作为查询输入，检索相似图片/图文分块”的链路。

用户提供的资料包括：

• 产品设计稿：/Users/xxyyh/Downloads/图搜图产品设计.pdf
• 团队讨论稿：/Users/xxyyh/Downloads/图片检索图片的技术方案.pdf
• 用户补充 UI 图：创建通用知识库弹窗、索引模型下拉、文件分块弹窗、图片分块弹窗、知识库搜索节点、搜索测试页、搜索测试图片上传态；图片自动索引为逻辑矩阵，不作为 UI 图放入。

注意：团队讨论稿里已有方案只作为参考，不能机械照搬。本文档以用户最新确认口径为准。

1.2 最新确认口径

1.3 业务目标

• 创建知识库时，用户能直观看到哪些索引模型支持多模态能力。
• 创建知识库时，用户能通过 索引模型 问号提示理解向量索引用途、跨模型查询限制和切换模型需重建全量向量索引的风险。
• 用户 hover 多模态 标签时，能看到“多模态索引模型可以给图片生成向量。”的能力解释。
• 创建知识库时，用户能通过 图片理解模型 问号提示理解 VLM 会自动标注文档图片并生成文本描述，辅助文本检索。
• 知识库导入图片或含图片文档时，可生成“多模态图片索引”，支持以图搜图。
• 搜索测试页支持本地上传图片，支持纯文本、纯图、图文混合测试；本地上传只支持图片，不支持文件；最多 10 张，超出提示 最多支持上传10张图片；搜索测试上传图片只作为临时检索输入，上传对象过期时间固定 3 小时。若当前知识库既没有多模态索引模型也没有图片理解模型，则禁用图片上传按钮并提示 请配置图片理解模型或多模态索引模型。
• 图文混合检索按知识库能力分支召回：多模态 embedding 直接检索图片向量和文本向量；有 VLM 时合并 VLM 文本描述索引；普通 embedding 仅在配置 VLM 时把查询图片转成文字后参与文本检索。
• 工作流知识库搜索节点的“检索内容”改为 Array<string>，可同时接入用户问题和文件链接；文件链接里只有图片链接参与图搜图，PDF、docx、表格等非图片文件链接由后端过滤。
• 文件分块与图片分块弹窗按新 UI 展示右侧数据索引卡片，图片分块展示图片预览和图片内容。
• 索引增强里的“图片自动索引”根据商业版、多模态索引模型、VLM 配置动态决定可用性和提示文案。

1.4 技术目标

• 不新增知识库类型。
• 不新增搜索模式大类。
• 不改变现有训练状态展示口径。
• 复用现有向量库、RRF 合并、知识库权限、工作流变量引用体系。
• 将“VLM 图片文本索引”和“多模态图片向量索引”明确分开，避免重建和检索走错链路。

2. 当前项目事实基线（基于代码）

3. 需求澄清记录

3.1 影响域判定（先判定，再核对规范）

4. 范围定义

4.1 In Scope（本期必须）

1. EmbeddingModelItemSchema 增加 vision?: boolean，语义为该 embedding 模型是否支持图片向量化。
2. 模型配置页中 embedding 模型点击设置后，新增 功能配置 区域，包含 支持图片识别 开关；样式参考 LLM 模型参数设置/功能配置，默认关闭。
3. embedding 模型 支持图片识别 打开后，保存 vision=true；关闭时保存/恢复为 vision=false 或缺省，按 text-only 模型处理。
4. 创建知识库索引模型下拉展示 Beta、多模态 标签，且 Beta 在前。
5. 创建通用知识库弹窗按新稿调整宽度和字段布局，并更新字段提示：索引模型 问号、图片理解模型 问号和索引模型下拉中的 多模态 标签 hover 文案必须使用本文档固定口径。
6. 索引增强里的“图片自动索引”根据商业版、多模态索引模型、VLM 配置动态启用/禁用和展示提示。
7. 多模态索引模型导入图片时，即使未配置 VLM，也可生成图片向量索引。
8. 多模态索引模型 + VLM 时，同时生成图片向量索引和文本描述索引。
9. 普通索引模型 + VLM 时，沿用 VLM 自动标注图片并生成文本描述索引。
10. 普通索引模型 + 无 VLM 时，“图片自动索引”禁用，提示配置图片理解模型或切换多模态向量模型。
11. 文件分块点击弹窗按第三张图改样式：左侧内容，右侧数据索引卡片。
12. 图片分块点击弹窗按第四张图改样式：左侧图片预览 + 图片内容，右侧数据索引卡片。
13. 右侧数据索引卡片展示“多模态图片索引”卡片时，索引内容不可见，仅展示 UI 默认说明文案：已通过多模态模型生成图片向量，支持以图搜图。
14. 数据索引删除规则：默认索引 和 多模态图片索引 不可删除；其他索引可以删除，包括推测问题索引、摘要索引、自定义索引等。
15. 知识库 embedding/索引模型切换时，必须按切换后的 vectorModel + vlmModel 组合重新决定索引生成策略：多模态模型走图片向量索引能力，普通模型只走 VLM 文本描述索引能力。
16. embedding/索引模型或 VLM 模型切换后，知识库必须进入全库重建流程或明确待重建状态，所有索引按切换后的模型组合重新生成；不能继续混用旧模型生成的向量。
17. 搜索测试页按最新上传图片 UI 改版：搜索配置、测试按钮下移、历史标题和历史项去掉前置模式 icon/title。
18. 搜索测试支持本地上传图片并参与搜索；输入框左下角放图片上传按钮，顶部横向展示图片缩略图、删除按钮和上传中 loading 卡片。
19. 搜索测试图片上传只支持图片，不支持文件；支持仅上传图片、不输入文字直接测试；最多支持 10 张图片，超过时提示 最多支持上传10张图片。
20. 搜索测试图片大小和格式限制跟随系统现有上传规则；不符合系统规则的图片、非图片文件直接过滤，不进入待上传/待搜索列表。
21. 搜索测试图片上传对象必须设置 3 小时过期时间，建议复用已有 S3 TTL 机制，写入 expiredTime = addHours(new Date(), 3)；不能复用正式图片集导入的长过期策略。
22. 若当前知识库 !isImageEmbeddingModel(dataset.vectorModel) && !dataset.vlmModel，搜索测试图片上传按钮 disabled，hover 提示 请配置图片理解模型或多模态索引模型；SearchDatasetTestBodySchema 仍保留 queryImageUrls 兼容能力，后端搜索核心兜底处理绕过前端的请求。
23. 搜索测试历史如果包含图片检索记录，列表中用 [图片] token 表示图片输入，鼠标 hover 到该历史项时弹出图片缩略图浮层。
24. 工作流知识库搜索节点的“检索内容”改为 Array<string>，可同时引用用户问题和文件链接。
25. 后端统一归一化检索输入：从 Array<string> 中拆出文本内容和图片文件链接；文件链接中只有 ChatFileTypeEnum.image 进入 queryImageUrls，非图片文件链接进入 filtered 统计并被忽略。
26. 搜索核心支持纯文本、纯图、图文混合、多图并行召回，并复用现有 RRF 合并排序。
27. 更新 OpenAPI、文档、i18n、测试。

4.2 Out of Scope（本期不做）

1. 不新增知识库类型。
2. 不新增搜索模式大类。
3. 不重做模型配置页整体框架，仅在 embedding 模型设置表单中新增图片能力开关。
4. 不做存量知识库自动迁移补图片向量。
5. 不重构所有工作流文件变量体系。
6. 不把图片 base64 写入搜索历史、日志或持久化 query。
7. 不做向量库多维度动态建表。图片 embedding 的向量维度与现有向量写入链路保持一致，维度不匹配沿用现有校验/报错路径处理。

5. 方案对比

推荐组合：方案B + 方案D。

选型原则：

• 同等可行时优先最少新增字段、最少新增 UI、复用现有训练和搜索能力。
• 对用户已确认口径不再另起方案绕开，否则设计就是自嗨，开发还得返工。

6. 推荐方案详细设计

6.1 API 设计

搜索测试请求示例：

{
  "datasetId": "68ad85a7463006c963799a05",
  "text": "找一下类似这张图的内容",
  "queryImageUrls": ["dataset/tmp/search-test/xxx.png"],
  "limit": 5000,
  "similarity": 0.4,
  "searchMode": "mixedRecall",
  "usingReRank": false
}

工作流节点运行时归一化前示例：

{
  "userChatInput": [
    "用户想找红色花朵相关图片",
    "https://example.com/files/query-flower.png"
  ]
}

工作流节点运行时归一化后示例：

{
  "textQueries": ["用户想找红色花朵相关图片"],
  "queryImageUrls": ["https://example.com/files/query-flower.png"]
}

6.2 数据设计

6.3 图片自动索引可用性矩阵

实现注意：

• 这个矩阵作用在创建/导入/索引增强配置阶段，不改变搜索阶段“和现在的逻辑一样”的口径。
• 如果禁用时当前表单值为 true，前端需要自动置回 false，避免灰掉但提交 true，这种坑线上最爱冒烟。
• 多模态能力来自模型配置页 embedding 模型的“支持图片识别”开关，而不是模型名或模型供应商写死判断。开关默认关闭，只有用户主动打开后才把 vision=true 写入 embedding 模型配置。
• 当知识库 vectorModel 或 vlmModel 发生切换，整个知识库必须按新的模型组合重新生成索引，不能只局部清理 imageIndex 或继续沿用旧向量。
• 切换后的重建策略由 vectorModel.vision 和 vlmModel 共同决定：多模态 embedding + VLM 生成 imageEmbedding 与 VLM 文本索引；多模态 embedding + 无 VLM 只生成 imageEmbedding；普通 embedding + VLM 只生成 VLM 文本索引；普通 embedding + 无 VLM 不生成图片相关索引。
• 存量数据不会因为模型字段变化自动拥有新索引；必须通过全库重建把旧索引替换成切换后模型组合对应的新索引。

6.4 核心代码设计

6.5 技术实现流程图（必填）

flowchart TD
  A["模型 schema
EmbeddingModelItem.vision"] --> B["模型配置页
支持图片识别开关"]
  B --> C["创建知识库
索引模型下拉显示 Beta + 多模态"]
  C --> D["索引增强配置
按商业版/多模态/VLM 决定图片自动索引可用性"]
  D --> E["导入图片或含图片文档"]
  E --> F["多模态图片索引
getVectorsByImage 写向量库"]
  E --> G["VLM 文本描述索引
有 VLM 时生成文本索引"]
  F --> H["搜索入口
搜索测试 / 工作流知识库搜索"]
  G --> H
  H --> I["输入归一化
文本 + 图片 URL"]
  I --> J["文本召回
文本向量/全文检索"]
  I --> K["图片召回
每张图单独生成 query vector"]
  J --> L["RRF 合并排序"]
  K --> L
  L --> M["返回引用结果
测试参数/测试结果/quoteQA"]

实现说明：

• embedding 模型图片能力复用 vision 字段，不再新增 modalities 或 multiModal 字段。
• vision=true 在 LLM 场景表示图片理解能力，在 embedding 场景表示图片向量化能力；必须通过 isImageEmbeddingModel 这类 helper 隔离语义，别在业务里到处裸读字段。
• 图片自动索引 用现有 imageIndex 字段承载，但提示和启用条件要按矩阵变化。
• 工作流检索内容 是一个 Array<string> 槽位，后端不能偷懒当纯文本 join 完事，否则图片链接会被当普通文本，图搜图直接歇菜。
• 工作流文件链接过滤只在后端兼容层做最终判断：复用 packages/service/core/workflow/utils/context.ts 的 parseUrlToFileType，只有解析为 ChatFileTypeEnum.image 的链接进入 queryImageUrls；解析为 ChatFileTypeEnum.file 的 PDF、docx、xlsx 等链接过滤掉，不进入文本检索。
• 多模态图片索引 和 VLM 文本描述索引 可以同时存在，但索引类型必须区分。

6.6 前端设计

6.6.1 创建知识库模型提示文案

该组文案是用户最新明确指定的产品文案，开发时必须接 i18n，不允许沿用旧文案或在组件内写死。

建议 i18n 落点：

• packages/web/i18n/*/common.json：更新 core.dataset.embedding model tip 或新增语义更明确的 core.dataset.embedding_model_tip。
• packages/web/i18n/*/common.json：新增 core.ai.model.multimodal_tip，用于模型下拉 多模态 标签 hover。
• packages/web/i18n/*/account_model.json 或 dataset 相关 namespace：更新/新增 vlm_model_tip，用于创建知识库 图片理解模型 问号提示。

6.6.2 搜索测试图片上传约束

说明：

• “直接过滤”表示该文件不会进入待搜索图片列表，也不会生成 queryImageUrls。若本批次同时有合法图片，合法图片仍正常加入。
• 只有数量超过 10 张需要明确弹出 最多支持上传10张图片；格式和大小超限沿用系统已有过滤/提示行为，不在本需求里新增另一套提示文案。
• 无图片搜索能力时禁用上传入口属于前端体验优化，不改变 API schema 的兼容性；后端仍按搜索核心策略兜底，避免旧客户端或绕过前端的请求直接报错。

6.7 后端搜索策略

说明：

• 多模态 embedding 的“直接检索”指使用同一个 embedding 模型的不同 modality：文本走 text modality，图片走 image modality。
• 有 VLM 时，入库图片可能同时存在 imageEmbedding 图片向量索引和 VLM 文本描述索引；查询图片也需要额外经 VLM 转文字后，才有机会命中 VLM 文本描述索引。
• RRF 合并按多路召回列表进行；同一数据同时被图片向量索引和 VLM 文本索引命中，排序权重应自然提升。
• 普通 embedding 无 VLM 时不做图片检索。纯图片输入返回空召回结果；图文混合输入只使用文字部分，搜索阶段不额外报错。
• 创建/索引增强阶段仍必须按矩阵禁用非法“图片自动索引”，避免用户以为能生成图片索引。

6.8 日志与观测设计

6.9 文档 i18n 设计（命中时必填）

补充要求：

• 若新增中文文档，必须同步英文文档和导航文件。
• 保持代码块字段名不翻译，例如 vision、queryImageUrls、imageEmbedding。

6.10 文档更新提醒（必填）

7. 风险、迁移与回滚

7.1 风险清单

1. 工作流兼容风险：现有 dataset search 节点的 userChatInput 是 string，新版是 Array<string>，需要兼容旧运行数据和旧模板。
2. 图片链接误判风险：Array<string> 同时含文本和文件链接，后端必须用可靠的文件解析逻辑区分；不能简单按 URL 字符串粗暴判断，也不能把 PDF、docx 等非图片文件链接当文本 query。
3. 索引类型混淆风险：现有 image 更偏 VLM 图片文本索引，必须和 imageEmbedding 分开。
4. 向量维度风险：图片 embedding 维度必须和现有向量写入链路保持一致；若模型输出维度不匹配，沿用现有校验/报错路径处理，不在本期引入多维度向量库策略。
5. 搜索成本风险：多图查询会多次图片 embedding，并行召回会增加模型调用和向量检索成本。
6. 隐私风险：本地上传图片、私有 S3 URL、预签名 URL 不能进入日志和长期历史明文；搜索测试上传图片必须 3 小时过期，避免测试图长期留存。
7. UI 误导风险：普通索引 + 无 VLM 时如果“图片自动索引”不禁用，用户会以为图片能被索引，最后搜不到就是纯纯给自己挖坑。

7.2 迁移策略

• 老 embedding 模型缺省无 vision，运行时按 vision=false 处理，无需迁移。
• 旧工作流 userChatInput: string 由兼容层归一化为单元素文本数组，搜索业务层只接收规范化后的 textQueries/queryImageUrls。
• 新工作流模板将“检索内容”展示为 Array<string>，默认只引用用户问题；允许用户按需手动追加文件链接。
• 存量知识库不自动补图片向量索引；当 vectorModel 或 vlmModel 切换时，必须进入全库重建流程或明确待重建状态。
• 旧搜索历史无图片字段时按纯文本历史展示。
• 新搜索历史若含图片，只保存可用于缩略图展示的受控图片引用、图片数量和摘要，不保存 base64 或完整私有预签名 URL。

7.3 回滚策略

1. 前端隐藏搜索测试图片上传入口和多模态图片索引展示。
2. 工作流模板回滚为 string 前，保留后端输入兼容层，避免旧流程直接崩。
3. 停止生成新的 imageEmbedding 索引，保留已生成索引不影响文本检索。
4. 搜索核心关闭图片 query 分支，纯文本链路保持现有行为。
5. 配置层关闭 embedding 模型 vision 后，前端自动回到普通模型表现。

8. 验收标准

9. MECE 核查结论

9.1 相互独立检查结果

• 模型能力字段和知识库字段独立：vision 属于模型配置，不写入 Dataset。
• 图片自动索引配置和搜索阶段行为独立：配置阶段负责能否生成索引，搜索阶段保持现有逻辑并使用已存在索引。
• VLM 文本描述索引和多模态图片向量索引独立：一个图转文，一个图转向量，索引类型不能混。
• 搜索测试和工作流入口独立：前者本地上传图片，后者从 Array<string> 中解析文件链接，但后端搜索核心复用。
• UI 分块弹窗和训练索引链路独立：弹窗展示索引状态，不应自己承担训练逻辑。

9.2 完全穷尽检查结果

9.3 修订动作与最终边界

• 旧文档 图搜图-接入-* 不覆盖，保留历史讨论痕迹。
• 本文档按最新确认口径作为后续实现依据。
• 后续若需要再改“工作流检索内容是否保留 string 兼容展示”，只能在实现文档中做兼容策略，不能推翻本期“Array<string>”产品口径。

10. TODO

• 按本文档同步更新 图搜图-当前需求-功能开发文档.md。
• 开发前确认创建知识库弹窗的三处提示文案对应 i18n key：索引模型问号、多模态 hover、图片理解模型问号。
• 开发前核对模型配置中实际可用的多模态 embedding 模型。
• 开发前确认搜索测试本地图片上传复用接口还是新增临时接口，并复用系统图片格式/大小限制；本次采用新增搜索测试临时上传接口，过期时间固定 3 小时。
• 实现后补齐 OpenAPI、知识库、工作流文档与英文版。
• 实现后按测试矩阵跑局部测试和最终检查。
• 恢复 pro 子模块后，补齐 pro/admin/src/service/core/dataset/training/imageParse.ts 和 pro/admin/src/service/core/dataset/training/imageIndex.ts 的图片向量/VLM 文本索引分流实现。
• 反向核对后补齐模型切换重建链路：切到普通 embedding 且无 VLM 时同步清理 dataset/collection 的 imageIndex=false。
• 反向核对后补齐工作流输入归一化：普通无后缀 URL 不再被误判为非图片文件并过滤。
• 反向核对后补齐搜索测试页 UI：输入标题、搜索配置按钮、图片缩略图顶部、上传按钮、测试按钮下移、历史标题去 icon。