功能开发文档

文档标识

• 任务前缀：图搜图-当前需求
• 文档文件名：图搜图-当前需求-功能开发文档.md
• 更新时间：2026-05-01
• 文档状态：v2.0 反向核对完成，补齐重建链路与搜索测试页 UI
• 文档定位：面向开发和 AI 实现的任务拆解文档。旧的 图搜图-接入-* 文档不覆盖，本文件按用户最新确认需求重新规划。

0. 开发目标与约束

• 功能目标：接入图搜图能力，覆盖 embedding 模型配置页 支持图片识别 开关、创建知识库模型选择、图片自动索引、图片向量索引生成、分块弹窗 UI、搜索测试本地上传图片、工作流知识库搜索节点 Array<string> 检索内容和后端图文混合检索。
• 代码范围：packages/global、packages/service、packages/web、projects/app、pro/admin、document/content。
• 非目标：不新增知识库类型；不新增搜索模式大类；不重做模型配置页整体框架；不做存量图片向量自动迁移；不做全量工作流文件系统重构；不改训练状态展示大类。
• 实现原则：最小改动、复用现有搜索/RRF/权限/计费能力；图片向量索引和 VLM 文本索引分清楚；能靠配置和 helper 解决的不要到处散落判断。
• 必须遵循规范：references/style-standards-entry.md。
• 适用维度：API[x] DB[x] Front[x] Logger[x] Package[x] BugFix[ ] DocUpdate[x] DocI18n[x]。

1. 实施任务拆解（可直接执行）

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

flowchart TD
  A["T1 模型能力字段
vision"] --> B["T2 模型配置页
支持图片识别开关"]
  B --> C["T3/T4 创建知识库与模型下拉"]
  B --> D["T5 图片自动索引矩阵"]
  B --> E["T6 图片 embedding 服务"]
  E --> F["T7 图片向量索引类型与写入"]
  F --> G["T8 训练/重建分流"]
  E --> H["T9 搜索核心
文本 + 图片召回"]
  H --> I["T10 搜索测试 API + 本地上传"]
  I --> J["T11 搜索测试页 UI/store"]
  H --> K["T12 工作流检索内容 Array<string>"]
  G --> L["T13 分块弹窗索引卡片"]
  J --> M["T14 文档/i18n/日志/计费"]
  K --> M
  L --> M
  M --> N["T15 测试与验收"]

实现说明：

• T1 是所有判断的地基，别在前后端散写 model.includes('xxx') 这种土法炼钢。
• T2 是模型是否支持图片输入的唯一人工配置入口；embedding 模型复用现有 vision 字段，语义为“支持图片向量化”，不再新增 modalities。
• T5 是本次用户特别补充点，禁用状态和提示文案必须跟矩阵一致。
• T12 不能改成额外 fileUrlList 外露输入，用户已经确认“检索内容本身改 Array<string>”；但数组里的文件链接只有图片能参与检索，非图片文件链接必须在后端过滤。

2. 文件级改动清单

2.1 关键代码片段（用于规划核对）

2.1.1 模型能力字段与 helper

// packages/global/core/ai/model.schema.ts
export const EmbeddingModelItemSchema = BaseAIModelSchema.extend({
  vision: z.boolean().optional()
});

// packages/service/core/ai/model.ts
export const isImageEmbeddingModel = (model?: string) => {
  const modelData = getEmbeddingModel(model);
  return !!modelData.vision;
};

2.1.2 embedding 模型配置开关映射

// projects/app/src/pageComponents/account/model/AddModelBox.tsx
// 注意：embedding 复用 vision 字段，但语义是图片向量化能力。
const supportImageRecognition = !!watch('vision');

<SwitchField
  label={t('account:model.vision')}
  tip={t('account:model.embedding_vision_tip')}
  isChecked={supportImageRecognition}
  onChange={(e) => {
    setValue('vision', e.target.checked);
  }}
/>;

实现要求：

1. 开关默认关闭，旧 embedding 模型无 vision 时按 text-only 展示。
2. 打开后保存 vision=true；关闭后保存/恢复为 vision=false 或缺省。
3. UI 样式参考 LLM 模型 功能配置 区域，但 helper 必须区分 LLM 的图片理解能力和 embedding 的图片向量化能力，别在业务里裸读字段到处判断。
4. 配置保存成功后，模型配置列表、创建知识库索引模型下拉、图片自动索引矩阵都必须读到同一份 vision。

2.1.3 图片自动索引状态矩阵

// projects/app/src/pageComponents/dataset/detail/Form/CollectionChunkForm.tsx
const getImageIndexConfigState = ({
  isPlus,
  isImageEmbeddingModel,
  vlmModel
}: {
  isPlus: boolean;
  isImageEmbeddingModel: boolean;
  vlmModel?: string;
}) => {
  if (!isPlus) {
    return {
      disabled: true,
      tooltip: t('common:commercial_function_tip'),
      tip: t('dataset:image_auto_parse_tip_commercial')
    };
  }

  if (isImageEmbeddingModel && vlmModel) {
    return {
      disabled: false,
      tooltip: '',
      tip: t('dataset:image_auto_parse_tip_multimodal_with_vlm')
    };
  }

  if (isImageEmbeddingModel) {
    return {
      disabled: false,
      tooltip: '',
      tip: t('dataset:image_auto_parse_tip_multimodal_without_vlm')
    };
  }

  if (vlmModel) {
    return {
      disabled: false,
      tooltip: '',
      tip: t('dataset:image_auto_parse_tip_vlm_only')
    };
  }

  return {
    disabled: true,
    tooltip: t('dataset:image_auto_parse_tip_no_vlm_or_multimodal'),
    tip: t('dataset:image_auto_parse_tip_no_vlm_or_multimodal')
  };
};

2.1.4 搜索测试 schema

// packages/global/openapi/core/dataset/api.ts
export const SearchDatasetTestBodySchema = z
  .object({
    datasetId: ObjectIdSchema,
    text: z.string().optional(),
    queryImageUrls: z.array(z.string()).max(10, '最多支持上传10张图片').optional(),
    limit: z.number().optional(),
    similarity: z.number().optional(),
    searchMode: z.enum(DatasetSearchModeEnum).optional(),
    usingReRank: z.boolean().optional(),
    datasetSearchUsingExtensionQuery: z.boolean().optional()
  })
  .refine((data) => !!data.text?.trim() || !!data.queryImageUrls?.length, {
    message: 'text or queryImageUrls is required'
  });

实现要求：

1. text 可为空，只要 queryImageUrls 有值就允许搜索，支持“仅上传图片，不带文字”。
2. schema 只校验输入形态，不判断知识库是否支持图片搜索；普通 embedding 且无 VLM 的能力限制由前端禁用上传按钮和搜索核心兜底处理。
3. 图片数量上限为 10 张；前端和后端都要校验，前端超出时提示 最多支持上传10张图片，后端作为兜底防绕过。
4. 搜索测试上传入口只支持图片，不支持 PDF、docx、xlsx、txt、pptx 等文件。
5. 图片格式和大小限制跟随系统现有上传规则，不在搜索测试里单独定义一套阈值。
6. 非图片文件、系统不支持格式、超出系统大小限制的图片直接过滤，不加入待上传列表，也不生成 queryImageUrls。
7. 如果一批选择中同时有合法图片和非法文件，合法图片正常加入，非法项过滤；只有图片数量超过 10 张需要使用本需求指定提示文案。
8. 搜索测试上传图片只用于临时检索，上传对象必须设置 3 小时过期时间：expiredTime = addHours(new Date(), 3)，并走现有 S3 TTL 清理链路。
9. 搜索测试历史/store 不保存 base64、完整私有 URL 或长期可访问 URL，只保存图片数量、文本摘要和受控缩略图引用。

2.1.5 工作流检索内容归一化

// packages/service/core/workflow/dispatch/dataset/search.ts
import { ChatFileTypeEnum } from '@fastgpt/global/core/chat/constants';
import { parseUrlToFileType } from '@fastgpt/service/core/workflow/utils/context';

const isLikelyFileLinkValue = (value: string) => {
  const trimmed = value.trim();
  return (
    trimmed.startsWith('data:') ||
    trimmed.startsWith('chat/') ||
    trimmed.startsWith('/') ||
    /^https?:\/\//i.test(trimmed)
  );
};

const normalizeDatasetSearchInput = (rawInput?: unknown) => {
  // 兼容层：旧节点可能存 string，新节点为 arrayString；业务层只使用归一化结果。
  const input =
    typeof rawInput === 'string' || Array.isArray(rawInput) ? rawInput : undefined;
  const values = Array.isArray(input) ? input : input ? [input] : [];

  return values.reduce(
    (acc, value) => {
      const trimmed = value.trim();
      if (!trimmed) return acc;

      if (isLikelyFileLinkValue(trimmed)) {
        const file = parseUrlToFileType(trimmed);
        if (file?.type === ChatFileTypeEnum.image) {
          acc.queryImageUrls.push(trimmed);
          return acc;
        }

        if (file?.type === ChatFileTypeEnum.file) {
          acc.filteredFileCount += 1;
          return acc;
        }
      }

      acc.textQueries.push(trimmed);
      return acc;
    },
    {
      textQueries: [] as string[],
      queryImageUrls: [] as string[],
      filteredFileCount: 0
    }
  );
};

过滤口径：

1. 只把 parseUrlToFileType(value)?.type === ChatFileTypeEnum.image 的链接放入 queryImageUrls。
2. ChatFileTypeEnum.file 的链接，包括 PDF、docx、xlsx、txt、pptx、html 等，一律过滤，不进入 textQueries。
3. 普通用户问题仍进入 textQueries；不要对所有字符串无脑调用 parseUrlToFileType 后就当文件处理，因为当前 parser 对无后缀文本也可能返回 file，容易误伤正常问题。
4. 不建议在工作流 dispatch 阶段对 URL 发起 HEAD 请求探测 MIME，成本、权限和 SSRF 风险都不划算；优先使用 queryUrlTypeMap、上传时文件类型和后缀白名单判断。
5. 过滤不作为节点错误。若输入数组只有非图片文件链接且无文本，节点按空检索返回空结果，并在 nodeResponse 或日志里记录 filteredFileCount，不记录完整 URL。

2.1.6 搜索核心分流

// packages/service/core/dataset/search/controller.ts
const supportImageEmbedding = isImageEmbeddingModel(dataset.vectorModel);
const hasVlm = !!dataset.vlmModel;

const imageCaptionQueries =
  queryImageUrls.length && hasVlm
    ? await getQueryImageCaptionsByVlm({
        imageUrls: queryImageUrls,
        vlmModel: dataset.vlmModel
      })
    : [];

const recallTasks = [
  textQueries.length
    ? runTextRecall({
        textQueries,
        searchMode,
        usingReRank,
        datasetSearchUsingExtensionQuery
      })
    : Promise.resolve([]),

  imageCaptionQueries.length
    ? runTextRecall({
        textQueries: imageCaptionQueries,
        searchMode,
        usingReRank: false,
        datasetSearchUsingExtensionQuery: false,
        source: 'imageCaption'
      })
    : Promise.resolve([]),

  queryImageUrls.length && supportImageEmbedding
    ? runImageRecall({
        imageUrls: queryImageUrls,
        model: dataset.vectorModel,
        datasetIds,
        limit
      })
    : Promise.resolve([])
];

const [textRecallResult, imageCaptionRecallResult, imageRecallResult] =
  await Promise.all(recallTasks);

const mergedResult = datasetSearchResultConcat(
  [
    { weight: textQueries.length ? embeddingWeight : 0, list: textRecallResult },
    { weight: imageCaptionQueries.length ? embeddingWeight : 0, list: imageCaptionRecallResult },
    { weight: queryImageUrls.length && supportImageEmbedding ? 1 : 0, list: imageRecallResult }
  ].filter((item) => item.weight > 0)
);

分支规则：

1. 多模态 embedding 的知识库：
   • 纯文本：文本 query 使用同一个多模态 embedding 的 text modality 检索。
   • 纯图片：图片 query 使用 image modality 检索 imageEmbedding。
   • 图片 + 文字：文本分支和图片向量分支并行召回后 RRF 合并。
2. 多模态 embedding + VLM：
   • 除图片向量召回外，查询图片还可以先经 VLM 转成文本，再检索 VLM 文本描述索引。
   • 同一数据同时命中 imageEmbedding 和 VLM 文本描述索引时，RRF 合并后排序权重自然提升。
3. 普通 embedding + VLM：
   • 图片不能直接走图片 embedding。
   • 查询图片先经 VLM 转文字，再用普通 embedding 做文本检索。
   • 图片 + 文字时，用户文字和图片 caption 作为多路文本 query 合并。
4. 普通 embedding + 无 VLM：
   • 不做图片检索。
   • 纯图片返回空召回结果；图片 + 文字只使用文字部分，不额外报错。
5. Query Extension 和 ReRank 默认只作用在用户文本分支；图片 caption 分支是否开启扩展/重排应保守处理，避免 VLM 已生成的描述被二次扩写导致语义漂移。

2.1.7 模型切换后的训练方式选择

// 伪代码：dataset vectorModel/vlmModel 更新后统一调用
const resolveImageIndexStrategy = ({
  vectorModel,
  vlmModel,
  imageIndex
}: {
  vectorModel: string;
  vlmModel?: string;
  imageIndex: boolean;
}) => {
  const supportImageEmbedding = isImageEmbeddingModel(vectorModel);

  return {
    enableImageEmbeddingIndex: imageIndex && supportImageEmbedding,
    enableVlmTextIndex: imageIndex && !!vlmModel,
    normalizedImageIndex: imageIndex && (supportImageEmbedding || !!vlmModel)
  };
};

const handleDatasetModelChanged = async (datasetId: string) => {
  // 模型切换后全部重建，不能只局部清理旧 imageIndex。
  await markDatasetRebuildRequired(datasetId);
};

2.1.8 重建索引分流

// projects/app/src/service/core/dataset/queues/generateVector.ts
const textIndexes = indexes.filter((item) => item.type !== DatasetDataIndexTypeEnum.imageEmbedding);
const imageIndexes = indexes.filter((item) => item.type === DatasetDataIndexTypeEnum.imageEmbedding);

await Promise.all([
  textIndexes.length
    ? rebuildTextVectors({ dataId, indexes: textIndexes, model })
    : Promise.resolve(),
  imageIndexes.length
    ? rebuildImageVectors({ dataId, indexes: imageIndexes, model })
    : Promise.resolve()
]);

2.1.8.1 单条数据差量重建策略

目标：单条数据点击“更新索引”时，不能默认全量重建所有索引。需要先基于“内容是否变化”和“当前 VLM 有无变化/是否可用”生成重建计划，只处理缺失、失效或受内容变更影响的索引。

输入状态：

核心判断：

const contentChanged = oldQ !== nextQ || oldA !== nextA;
const imageUrlsChanged = !isEqualSet(oldImageUrls, nextImageUrls);
const needRebuildAutoIndex =
  autoIndexes && (contentChanged || !hasQuestionIndex || !hasSummaryIndex);

差量规划输出：

type DatasetDataIndexRebuildPlan = {
  indexes: DatasetDataIndexItemType[];
  contentChanged: boolean;
  imageUrlsChanged: boolean;
  hasMarkdownImages: boolean;
  needRebuildVlmImageIndex: boolean;
  needRebuildAutoIndex: boolean;
};

规则矩阵：

必须遵守：

1. 内容没变时，只补当前训练参数下没有创建出来的索引，并清理当前能力不再支持的旧索引。
2. 内容变了时，文本索引必须重建；VLM image 也必须重建，因为 VLM 描述受上下文文本影响。
3. 内容变了但图片链接没变时，不重建已有 imageEmbedding，因为图片本体没变，图片向量不需要重新生成。
4. 无论内容是否变化，都必须检查当前 VLM 状态：无 VLM 删除 image；有 VLM 且缺失则补。
5. 单条“更新索引”不负责处理多模态模型切换带来的全库重建；多模态模型切换由知识库配置侧触发全量重建。单条更新只检查当前模型参数下是否缺少 imageEmbedding，缺才补。
6. custom 索引永远保留，除非用户显式删除该自定义索引。
7. summary / question 属于自动生成索引，不是用户自定义索引：autoIndexes=false 时删除；autoIndexes=true 且内容变化或任一缺失时删除旧自动索引并创建 TrainingModeEnum.auto 任务重建。
8. 删除旧派生索引时只删除能力派生索引和自动生成索引，不得误删 custom。

推荐执行顺序：

flowchart TD
  A["读取旧数据和当前模型能力"] --> B["解析 old/new 图片 URL"]
  B --> C["生成 DatasetDataIndexRebuildPlan"]
  C --> D["同步删除失效派生索引"]
  D --> E{"需要 VLM image 索引?"}
  E -- 是 --> F["进入 image 队列，仅重建 VLM 文本图片索引"]
  E -- 否 --> G["跳过 VLM 队列"]
  F --> H{"需要自动索引?"}
  G --> H
  H -- 是 --> I["进入 auto 队列生成 question/summary"]
  H -- 否 --> J["跳过 auto 队列"]
  I --> K["进入 vector 写入阶段"]
  J --> K
  K --> L["只写入缺失 imageEmbedding 和需重建文本索引"]
  L --> M["保留 custom 和未变化 imageEmbedding"]

落地建议：

1. 在 service 层新增/抽取 buildDatasetDataIndexRebuildPlan()，供 data/update.ts、rebuildEmbedding.ts、generateVector.ts 复用。
2. imageIndex.ts 只负责 VLM 文本图片索引，不负责图片向量。
3. generateVector.ts 按 plan 追加缺失 imageEmbedding，已有同 URL 的图片向量索引直接保留。
4. 前端“更新索引”按钮需要等异步重建结果写回后再刷新数据索引列表，不能把“训练任务创建成功”当成索引完成。
5. data/update.ts 在 needRebuildVlmImageIndex=true 时创建 TrainingModeEnum.image；在 needRebuildAutoIndex=true 时创建 TrainingModeEnum.auto，由 pro/admin 的 generateAutoTraining 生成 question / summary 后再转 chunk 写向量。
6. 如果本地或部署环境没有启动 pro/admin 训练进程，TrainingModeEnum.auto 任务只会停留在队列中，不会产出自动索引。

2.1.9 文档图文分块的多模态图片索引补齐

目标：把 DOCX、PDF 解析服务、HTML、Markdown、网页等来源统一成同一种处理方式。只要最终训练分块里保留 markdown 图片引用，并且当前知识库启用了图片自动索引、索引模型支持图片向量化，就在建索引阶段补齐 imageEmbedding。不要按文件扩展名分别写补丁。

职责边界：

1. pro/admin/src/service/core/dataset/training/imageIndex.ts 只负责 VLM 识别图片并生成 DatasetDataIndexTypeEnum.image 文本索引。
2. projects/app/src/service/core/dataset/queues/generateVector.ts 负责在真正建索引前追加 DatasetDataIndexTypeEnum.imageEmbedding。
3. insertData2Dataset / updateData2Dataset 继续负责按索引类型分流：文本索引走文本 embedding，imageEmbedding 走 getVectorsByImage。

图片来源收敛：

推荐伪代码：

const getMarkdownImageUrlsFromTrainingData = (trainingData: TrainingDataType) => {
  const texts = [trainingData.q, trainingData.data?.q].filter(Boolean) as string[];
  return unique(texts.flatMap(matchMarkdownImageUrls));
};

const appendMarkdownImageEmbeddingIndexes = ({
  indexes,
  trainingData,
  embModel
}: {
  indexes: DatasetDataIndexItemType[];
  trainingData: TrainingDataType;
  embModel: ReturnType<typeof getEmbeddingModel>;
}) => {
  if (!trainingData.collection.imageIndex) return indexes;
  if (!isImageEmbeddingModel(embModel)) return indexes;

  const existedImageUrls = new Set(
    indexes
      .filter((item) => item.type === DatasetDataIndexTypeEnum.imageEmbedding)
      .map((item) => item.text)
  );

  const appendIndexes = getMarkdownImageUrlsFromTrainingData(trainingData)
    .filter((url) => !existedImageUrls.has(url))
    .map((url) => ({
      type: DatasetDataIndexTypeEnum.imageEmbedding,
      text: url,
      dataId: ''
    }));

  return indexes.concat(appendIndexes);
};

接入要求：

1. rebuildData() 调用该 helper，保证存量数据重建时能从 trainingData.data.q 补齐图片向量索引。
2. insertData() 调用该 helper，保证 DOCX/PDF/HTML/Markdown/网页等初次导入时就生成 imageEmbedding。
3. 不在 imageIndex.ts 中调用 getVectorsByImage，避免 VLM 队列承担建向量职责。
4. 普通 embedding 模型或 collection.imageIndex=false 时不追加 imageEmbedding，避免出现没有实际向量的假索引卡片。
5. 同一分块里相同图片 URL 只追加一次 imageEmbedding。

3. 后端实施说明

3.1 API 改动

请求示例：

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

响应示例：

{
  "list": [],
  "duration": "0.523s",
  "limit": 5000,
  "searchMode": "mixedRecall",
  "usingReRank": false,
  "similarity": 0.4,
  "queryExtensionModel": ""
}

3.2 Service/Core 改动

3.3 数据层改动

3.4 计费与用量

3.5 搜索策略

实现注意：

1. 不能把所有 queryImageUrls 都直接丢给图片 embedding。只有 isImageEmbeddingModel(dataset.vectorModel) 为 true 时才允许。
2. 有 VLM 时，查询图片也要转成文本，才能检索入库阶段生成的 VLM 文本描述索引。
3. 同一数据同时被图片向量索引和 VLM 文本描述索引召回时，不要去重到只保留一条召回源；应进入 RRF 合并，让排序权重自然变大。
4. 普通 embedding 无 VLM 的纯图片输入返回空列表即可，不作为接口错误；图文混合时忽略图片分支。
5. 日志中可记录 textQueryCount/imageQueryCount/imageCaptionQueryCount/supportImageEmbedding/hasVlm，不要记录完整图片 URL 和完整 caption。

4. 前端实施说明

4.1 UI 参考图全集

说明：下面这些图用于开发实现时对齐 UI，图片来源为 /Users/xxyyh/Desktop/figme 中导出的真实 Figma 图片。原先临时手绘的 SVG 已移除，后续实现以这些 PNG/JPEG 为准。

4.1.1 创建通用知识库弹窗

4.1.2 索引模型下拉样式

实现注意：截图里展示顺序看起来是 多模态 在前，但用户已确认最终实现为 Beta 放在 多模态 前。hover 多模态 标签时展示 多模态索引模型可以给图片生成向量。 开发时按文字口径实现，别被旧截图带偏。

4.1.3 文件分块点击后弹窗

4.1.4 QA 模式文件分块弹窗

4.1.5 图片分块点击后弹窗

4.1.6 工作流知识库搜索节点

4.1.7 搜索测试页基础态

4.1.8 搜索测试页上传图片与历史 hover 态

4.1.9 模型配置页参考

实现注意：该图只表达 embedding 模型设置里新增 支持图片识别 开关的视觉样式。开发时参考 LLM 模型已有 功能配置 区域，保存字段为 embedding 模型的 vision。

4.2 创建知识库弹窗与模型下拉 UI 细节

1. 索引模型 label 后保留问号提示，hover/click 后展示：索引模型可以将知识库内容转成向量，用于进行语义检索。注意，不同索引模型的知识库无法同时查询，切换索引模型需重建全量向量索引，请慎重选择。
2. 图片理解模型 label 后保留问号提示，hover/click 后展示：自动标注文档里的图片并生成文本描述，辅助文本检索
3. 索引模型下拉中，支持图片的 embedding 模型展示 Beta 和 多模态 标签时，顺序必须是 Beta 在前、多模态 在后。
4. hover 多模态 标签时展示：多模态索引模型可以给图片生成向量。
5. 多模态 hover 只绑定在 多模态 标签上，不绑定整行模型；Beta 标签不展示该说明。
6. 长模型名仍按现有省略规则处理，不能把 Beta、多模态 标签挤出可视区域。
7. 以上三段文案必须走 i18n，覆盖 zh-CN/en/zh-Hant；中文文案以本文档为准。
8. 现有 common.json 中旧 索引模型可以将自然语言转成向量...选择完索引模型后将无法修改 口径需要替换或停用，别让新旧文案在不同入口同时出现，用户看完容易怀疑人生。

4.3 模型配置页 UI 细节

1. 入口仍是现有模型配置页，针对 embedding 模型点击设置后进入 AddModelBox 表单。
2. 在 embedding 模型表单中新增 功能配置 区域，位置和样式参考 LLM 模型已有的 功能配置。
3. 区域内新增 支持图片识别 开关，默认关闭。
4. 开关关闭时，保存/恢复为 vision=false 或缺省，模型按 text-only 处理。
5. 开关打开时，保存 vision=true。
6. 开关再次关闭时必须关闭 vision，并让模型配置列表、模型下拉、图片自动索引矩阵立即回到普通 embedding 表现。
7. 文案可复用 支持图片识别 label；tip 建议新增 embedding 专用 key，说明“开启后该 embedding 模型可接收图片输入并用于图片向量索引/图搜图”。
8. vision 在 LLM 和 embedding 上语义不同：LLM 是图片理解，embedding 是图片向量化。必须通过模型类型和 helper 判断，别一看字段名一样就到处裸用，后面排障基本就是开盲盒。

4.4 分块弹窗数据索引 UI 细节

1. 右侧标题仍为 数据索引（n），数量按当前可展示索引数量计算。
2. 默认索引 是基础索引，不展示删除入口，不允许被删除。
3. 默认索引 和 多模态图片索引 都不展示删除入口，不允许被删除。
4. 其他索引展示删除入口并允许删除，包括 推测问题索引、摘要索引、自定义索引等。
5. 多模态图片索引 的索引内容不可见，不展示向量、图片 URL、S3 key、原始索引文本或任何内部字段。
6. 多模态图片索引 展开后只展示 UI 默认说明文案：已通过多模态模型生成图片向量，支持以图搜图。
7. 删除可删除索引时应有确认或防误触处理；删除成功后右侧索引数量和卡片列表立即刷新。
8. 删除动作必须同步后端索引数据，不能只在前端隐藏卡片，否则搜索仍可能命中已删除索引，这种“假删除”后面排查要命。

4.5 搜索测试页 UI 细节

1. 左侧标题为 输入测试内容。
2. 标题右侧为 搜索配置 按钮，使用 gear icon，点击打开现有搜索参数弹窗。
3. 输入区域是一个大 textarea 容器，placeholder 为 输入需要测试的内容。
4. 图片上传按钮放在输入框左下角，使用图片图标按钮，不使用文字按钮。
5. 若当前知识库 !isImageEmbeddingModel(dataset.vectorModel) && !dataset.vlmModel，图片上传按钮 disabled；hover 提示 请配置图片理解模型或多模态索引模型。
6. 图片上传只支持图片，不支持文件；文件选择器优先限制为图片类型，拖拽/粘贴/选择到非图片文件时直接过滤。
7. 支持仅上传图片不输入文字直接测试；只要待搜索图片列表非空，测试 按钮可用。
8. 图片数量上限为 10 张；选择后超过 10 张时提示 最多支持上传10张图片，超出的图片不加入列表。
9. 图片大小和格式限制跟随系统现有上传规则；不符合系统规则的图片直接过滤，不进入上传中状态。
10. 搜索测试上传图片必须设置 3 小时过期时间，前端不暴露配置项；后端上传时写入 TTL。
11. 已上传图片在输入框顶部横向排列，缩略图尺寸固定，避免 textarea 高度被图片加载状态反复撑开。
12. 单张图片 hover 或选中态展示右上角删除按钮，点击后从待搜索图片列表移除。
13. 图片上传中展示独立的上传中卡片，卡片尺寸与缩略图一致，中间显示 loading 圆环。
14. 输入文字区域位于图片缩略图下方；没有图片时，placeholder 仍从输入框上方自然显示。
15. 测试 按钮放在输入框下方，撑满左侧区域。
16. 测试历史 标题前不展示 icon。
17. 历史项不展示搜索模式 icon/title，只展示内容摘要、图片 token、时间或删除。
18. 图片检索历史用 [图片] token 表示图片输入；多张图片显示多个 [图片] token，超出宽度按现有文本省略规则处理。
19. 鼠标 hover 到含图片的历史项时，在历史项下方或右下方弹出图片缩略图浮层。
20. 缩略图浮层展示该次检索对应的图片缩略图，横向排列，尺寸固定，浮层有白底、圆角、阴影和边框。
21. 鼠标移出历史项和浮层后关闭缩略图浮层；hover 删除按钮时仍应优先展示删除操作，不要被浮层挡住。
22. 纯文本历史不展示图片缩略图浮层。
23. 中间区域保留 测试参数 和 测试结果。
24. 右侧知识库信息栏保持现有能力，不在本期做大改。

4.6 工作流节点 UI 细节

1. 知识库搜索 节点的 检索内容 valueType 改为 WorkflowIOValueTypeEnum.arrayString。
2. 同一个输入框允许同时引用：
   • 流程开始 > 用户问题
   • 流程开始 > 文件链接
3. 默认新建节点时只自动带上 流程开始 > 用户问题；不默认带 流程开始 > 文件链接。
4. 旧工作流若仍存 string 值，前端展示和后端运行都要兼容。
5. 后端归一化时将图片文件链接拆到 queryImageUrls，普通文本拆到 textQueries。
6. 文件链接变量里可能包含 PDF、docx、xlsx、txt、音视频等非图片文件；这些链接必须在后端过滤，不参与图搜图，也不要降级塞进文本检索。
7. 过滤非图片文件链接时不要弹前端错误。节点响应可记录 filteredFileCount，日志只记录数量和类型，不记录完整 URL。

4.7 图片自动索引配置逻辑

该部分不是 UI 图，不需要放截图。实现时必须按下面的配置矩阵控制 imageIndex 复选框、tooltip、QuestionTip 和最终提交值。

实现要求：

1. 前端禁用时如果当前表单里 imageIndex=true，必须立即 setValue('imageIndex', false)，别出现“灰了但提交还是 true”的离谱状态。
2. 后端接收 chunkSettings.imageIndex 时也要复核同一套条件，前端禁用不是安全边界。
3. 多模态索引 + 无 VLM 时允许开启图片自动索引，但只生成图片向量索引，不生成 VLM 文本描述索引。
4. 普通索引 + 有 VLM 时允许开启图片自动索引，但只生成 VLM 文本描述索引，不生成图片向量索引。
5. 搜索阶段不额外报错：普通索引 + 无 VLM 的行为和现有逻辑一致，配置阶段负责禁止用户创建“以为有图片索引但实际没有”的状态。
6. 当知识库 vectorModel 或 vlmModel 发生切换时，前端和后端都要重新执行本矩阵，更新 imageIndex 可用性和提示文案。
7. 从普通 embedding 切到多模态 embedding 后，后续训练/重建应切到“图片向量索引 + 可选 VLM 文本描述索引”的生成方式。
8. 从多模态 embedding 切到普通 embedding 后，后续训练/重建不得继续生成 imageEmbedding 图片向量索引；如果没有 VLM，则必须强制 imageIndex=false。
9. 模型切换后必须全库重建或明确标记待重建，否则存量向量仍由旧 embedding/VLM 模型组合生成，搜索质量和配置会对不上。

5. 日志与可观测性

注意事项：

• 统一使用 @fastgpt/service/common/logger。
• 不记录 token、密码、密钥、base64、完整私有 URL、完整用户问题。
• 搜索历史只保存摘要、图片数量和受控缩略图引用，不保存 base64 或完整私有预签名 URL。

6. 文档更新提醒（必填）

7. 文档 i18n 实施说明（命中时必填）

7.1 翻译范围识别

• 自动检测命令：
  • git diff --name-only
  • git diff --cached --name-only
• 手动指定路径：
  • document/content/openapi/dataset.mdx
  • document/content/openapi/dataset.en.mdx
  • 知识库功能文档中文/英文对应文件
  • 工作流知识库搜索节点中文/英文对应文件

7.2 文件映射与动作

7.3 翻译约束清单

• 保持不变：import、图片路径、URL、HTML/JSX 结构、表格结构、代码块字段名。
• 必须翻译：frontmatter、正文、表格文字、中文注释。
• 术语建议：
  • 图搜图：image-to-image search
  • 多模态图片索引：multimodal image index
  • 图片自动索引：automatic image indexing
  • 搜索配置：Search configuration

7.4 缺失文件与提醒

8. 测试与验证

测试规范来源：references/testing-standards.md。

8.1 测试文件映射（必填）

8.2 自动化测试设计

8.3 场景覆盖核对

8.4 执行命令与结果

开发中优先局部测试：

pnpm test test/cases/service/core/ai/model.test.ts
pnpm test projects/app/test/pages/api/core/ai/model/update.test.ts
pnpm test projects/app/test/pages/api/core/ai/model/list.test.ts
pnpm test projects/app/test/pageComponents/account/model/AddModelBox.test.tsx
pnpm test projects/app/test/pageComponents/account/model/ModelConfigTable.test.tsx
pnpm test test/cases/service/core/ai/embedding/index.test.ts
pnpm test test/cases/service/core/dataset/search/controller.test.ts
pnpm test test/cases/service/core/workflow/dispatch/dataset/search.test.ts
pnpm test projects/app/test/pages/api/core/dataset/searchTest.test.ts
pnpm test projects/app/test/pageComponents/dataset/detail/Test.test.tsx
pnpm test projects/app/test/pageComponents/dataset/detail/InputDataModal.test.tsx

最终合并前：

pnpm test
pnpm lint

pro/admin 补充验证：

8.5 手工验证

9. 质量自检清单

• 旧文档未覆盖。
• embedding 模型复用 vision 作为图片向量化能力字段，不新增 modalities。
• embedding 模型 支持图片识别 开关默认关闭，打开才保存 vision=true。
• vision 在 LLM 和 embedding 上通过模型类型/helper 隔离语义，没有在业务里裸读导致混用。
• 模型下拉 Beta 在 多模态 前。
• 创建知识库 索引模型 问号、图片理解模型 问号和 多模态 标签 hover 使用固定 i18n 文案。
• “检索内容”本身为 Array<string>，不是新增外露 fileUrlList 字段替代。
• 工作流知识库搜索只把图片文件链接放入 queryImageUrls，PDF/docx/xlsx 等非图片文件链接被后端过滤，且普通无后缀 URL 不被误过滤。
• 搜索召回按知识库模型能力分支：多模态 embedding 直接图/文检索，普通 embedding 只能通过 VLM caption 处理图片。
• 多模态 embedding + VLM 时，图片向量召回和 VLM caption 文本召回都参与 RRF；同一数据多路命中排序权重提升。
• 普通 embedding + 无 VLM 时不做图片检索，纯图片返回空召回，图文混合只用文字。
• 搜索测试支持本地上传图片，且图片按钮、缩略图、删除按钮、上传中卡片符合最新 UI。
• 搜索测试只支持上传图片，不支持文件；允许纯图片无文字搜索。
• 普通 embedding 且无 VLM 时搜索测试图片上传按钮禁用，hover 提示 请配置图片理解模型或多模态索引模型。
• 搜索测试最多 10 张图片，超过提示 最多支持上传10张图片。
• 搜索测试图片大小和格式跟随系统上传规则，不符合规则的输入直接过滤。
• 搜索测试上传图片对象设置 3 小时过期时间，并写入 S3 TTL 清理链路。
• 图片检索历史显示 [图片] token，hover 后展示图片缩略图浮层，纯文本历史不展示浮层。
• 多模态图片索引内容不可见，只展示默认说明文案。
• 默认索引和多模态图片索引不可删除；其他索引可以删除。
• 图片自动索引 5 场景矩阵全部实现。
• 普通索引 + 无 VLM 时图片自动索引禁用且提交值为 false。
• 多模态 + 无 VLM 时仍可生成图片向量索引。
• embedding/索引模型或 VLM 切换后，图片自动索引可用性、后续训练方式和全库重建/待重建状态同步更新；切到普通 embedding 且无 VLM 时后端清理 imageIndex=false。
• 图片向量索引和 VLM 图片文本索引不会混淆。
• 重建索引按索引类型分流。
• API 使用 zod schema parse。
• 工作流旧 string 输入兼容。
• 日志不记录 base64、完整私有 URL、完整用户输入。
• i18n 覆盖 zh-CN/en/zh-Hant。
• OpenAPI 和功能文档中英文同步。
• 局部测试和最终检查通过。

10. 发布与回滚

10.1 发布步骤

1. 合并模型配置 vision，先确认现网 embedding 模型缺省字段可解析。
2. 发布后端搜索核心和训练分流，默认不影响 text-only 模型。
3. 发布前端 UI，开启多模态标签、图片自动索引矩阵、搜索测试图片上传。
4. 更新文档和 OpenAPI。
5. 灰度验证多模态模型数据集的图片导入、搜索测试、工作流搜索。

10.2 回滚触发条件

• 图片 embedding 大面积失败或向量维度不兼容。
• 工作流 Array<string> 兼容旧节点出现运行异常。
• 搜索测试图片上传存在权限或隐私风险。
• 图片自动索引误启用导致普通索引无 VLM 的知识库生成异常任务。

10.3 回滚动作

1. 前端隐藏搜索测试图片上传和多模态图片索引入口。
2. 模型配置关闭 embedding vision，前端自动回到普通模型表现。
3. 后端保留输入兼容层，但关闭图片 query 分支。
4. 停止新生成 imageEmbedding 索引，保留已有索引不影响文本检索。
5. 若工作流新模板有问题，回退模板但保留运行时兼容，避免已有应用崩溃。