feat(dataset): 知识库级 pdfParseConfig 文档解析开关(#68624)

document/data/doc-last-modified.json

@@ -355,10 +355,8 @@
   "content/self-host/upgrading/4-16/4161.mdx": "2026-08-24T10:06:28+08:00",
   "content/self-host/upgrading/4-16/4162.en.mdx": "2026-09-03T21:50:14+08:00",
   "content/self-host/upgrading/4-16/4162.mdx": "2026-09-03T21:50:14+08:00",
-  "content/self-host/upgrading/4-17/4170.en.mdx": "2026-09-12T20:05:26+08:00",
-  "content/self-host/upgrading/4-17/4170.mdx": "2026-09-12T20:05:26+08:00",
-  "content/self-host/upgrading/4-17/4171.en.mdx": "2026-09-12T22:05:59+08:00",
-  "content/self-host/upgrading/4-17/4171.mdx": "2026-09-12T22:05:59+08:00",
+  "content/self-host/upgrading/4-17/4170.en.mdx": "2026-09-11T13:12:32+08:00",
+  "content/self-host/upgrading/4-17/4170.mdx": "2026-09-11T13:12:32+08:00",
   "content/self-host/upgrading/outdated/40.en.mdx": "2026-08-16T23:16:43+08:00",
   "content/self-host/upgrading/outdated/40.mdx": "2026-08-16T23:16:43+08:00",
   "content/self-host/upgrading/outdated/41.en.mdx": "2026-08-16T23:16:43+08:00",
@@ -501,6 +499,6 @@
   "content/self-host/upgrading/upgrade-instruction.mdx": "2026-09-08T22:44:33+08:00",
   "content/self-host/upgrading/version-timeline.en.mdx": "2026-08-16T23:16:43+08:00",
   "content/self-host/upgrading/version-timeline.mdx": "2026-08-16T23:16:43+08:00",
-  "content/toc.en.mdx": "2026-09-12T22:05:59+08:00",
-  "content/toc.mdx": "2026-09-12T22:05:59+08:00"
+  "content/toc.en.mdx": "2026-09-03T21:50:14+08:00",
+  "content/toc.mdx": "2026-09-03T21:50:14+08:00"
 }

packages/global/core/app/type.ts

@@ -125,22 +125,24 @@ export const EntryPointItemTypeSchema = z.object({
 });
 export type EntryPointItemType = z.infer<typeof EntryPointItemTypeSchema>;
 
-export const EntryPointItemsTypeSchema = z.array(EntryPointItemTypeSchema).superRefine((items, ctx) => {
-  const seenNames = new Map<string, number>();
-  items.forEach((item, index) => {
-    const normalizedName = item.name.trim();
-    const previousIndex = seenNames.get(normalizedName);
-    if (previousIndex !== undefined) {
-      ctx.addIssue({
-        code: 'custom',
-        path: [index, 'name'],
-        message: 'Entry point names must be unique'
-      });
-      return;
-    }
-    seenNames.set(normalizedName, index);
+export const EntryPointItemsTypeSchema = z
+  .array(EntryPointItemTypeSchema)
+  .superRefine((items, ctx) => {
+    const seenNames = new Map<string, number>();
+    items.forEach((item, index) => {
+      const normalizedName = item.name.trim();
+      const previousIndex = seenNames.get(normalizedName);
+      if (previousIndex !== undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: [index, 'name'],
+          message: 'Entry point names must be unique'
+        });
+        return;
+      }
+      seenNames.set(normalizedName, index);
+    });
   });
-});
 
 export const AppChatConfigTypeSchema = z.object({
   welcomeText: optionalNullToUndefined(z.string()).meta({

packages/global/core/dataset/type.ts

@@ -119,6 +119,27 @@ export const ChunkSettingsSchema = z.object({
 });
 export type ChunkSettingsType = z.infer<typeof ChunkSettingsSchema>;
 
+/* ===== Iultmzh file parse config ===== */
+// 外部文档解析服务开关,整体校验、整体存取;仅当 collection 的 customPdfParse=true
+// 且系统配置了 customPdfParse.url 时生效。缺失字段由读取层用固定默认值补全。
+export const sangforFileParseConfigSchema = z
+  .object({
+    keep_header_footer: z.boolean().optional().meta({
+      description: '是否保留页眉页脚,默认删除'
+    }),
+    keep_appendix: z.boolean().optional().meta({
+      description: '是否保留附录,默认删除首个附录标题后的内容'
+    }),
+    image_analysis: z.boolean().optional().meta({
+      description: '是否保留图片识别(含印章)结果,默认关闭'
+    }),
+    chart_analysis: z.boolean().optional().meta({
+      description: '是否保留图表转表格结果(同时保留原图片),默认关闭'
+    })
+  })
+  .meta({ description: '外部文档解析配置' });
+export type IultmzhFileParseConfigType = z.infer<typeof sangforFileParseConfigSchema>;
+
 /* ===== Dataset ===== */
 export const DatasetSchema = z
   .object({
@@ -154,6 +175,10 @@ export const DatasetSchema = z
       .meta({ description: '网站配置' }),
     chunkSettings: ChunkSettingsSchema.optional().meta({ description: '分块配置' }),
 
+    sangforFileParseConfig: sangforFileParseConfigSchema
+      .optional()
+      .meta({ description: '外部文档解析配置' }),
+
     apiDatasetServer: ApiDatasetServerSchema.optional().meta({ description: 'API 服务器配置' }),
 
     deleteTime: z.coerce.date().nullish().meta({ description: '删除时间' }),

packages/global/core/workflow/migration/legacy/systemConfig.ts

@@ -147,7 +147,10 @@ export function migrateSystemConfigToChatConfig(input: LegacyWorkflowDataInput)
     ],
     [
       'entryPoints',
-      getSystemConfigInputValue<EntryPointItemType[]>(systemConfigNode, NodeInputKeyEnum.entryPoints)
+      getSystemConfigInputValue<EntryPointItemType[]>(
+        systemConfigNode,
+        NodeInputKeyEnum.entryPoints
+      )
     ]
   ];
   configValues.forEach(([key, value]) => {

packages/global/openapi/core/dataset/api.ts

@@ -8,6 +8,7 @@ import {
   DatasetItemSchema,
   DatasetSchema,
   DatasetListItemSchema,
+  sangforFileParseConfigSchema,
   SearchDataResponseItemSchema
 } from '../../../core/dataset/type';
 import { AppListSortEnum } from '../../../core/app/constants';
@@ -72,6 +73,9 @@ export const CreateDatasetBodySchema = z.object({
   }),
   apiDatasetServer: ApiDatasetServerSchema.optional().meta({
     description: '第三方知识库服务器配置(API/飞书/语雀/钉钉)'
+  }),
+  sangforFileParseConfig: sangforFileParseConfigSchema.optional().meta({
+    description: '外部文档解析开关(页眉页脚/附录/图片识别/图转表),仅对 customPdfParse 解析路径生效'
   })
 });
 
@@ -111,6 +115,10 @@ export const CreateDatasetWithFilesBodySchema = z.object({
       vlmModelId: z.string().nullable().optional().meta({
         description: '视觉语言模型 ID；未传沿用默认，null 或空字符串表示不设置',
         example: ''
+      }),
+      sangforFileParseConfig: sangforFileParseConfigSchema.optional().meta({
+        description:
+          '外部文档解析开关(页眉页脚/附录/图片识别/图转表),仅对 customPdfParse 解析路径生效'
       })
     })
     .meta({ description: '知识库参数' }),
@@ -443,6 +451,10 @@ export const UpdateDatasetBodySchema = z.object({
   }),
   chunkSettings: ChunkSettingsSchema.optional().meta({
     description: '分块配置'
+  }),
+  sangforFileParseConfig: sangforFileParseConfigSchema.optional().meta({
+    description:
+      '外部文档解析开关(页眉页脚/附录/图片识别/图转表),仅对 customPdfParse 解析路径生效;编辑后仅对新解析的文件生效'
   })
 });
 export type UpdateDatasetBody = z.infer<typeof UpdateDatasetBodySchema>;

packages/service/common/file/read/utils.ts

@@ -1,12 +1,14 @@
 import FormData from 'form-data';
 import type { ReadFileResponse } from '../../../worker/readFile/type';
+import type { IultmzhFileParseConfigType } from '@fastgpt/global/core/dataset/type';
 import { axios } from '../../api/axios';
 import { parseMarkdownBase64Images } from '@fastgpt/global/common/string/markdown';
 import { createPdfParseUsage } from '../../../support/wallet/usage/controller';
 import { useDoc2xServer } from '../../../thirdProvider/doc2x';
 import { useTextinServer } from '../../../thirdProvider/textin';
 import { useSomarkServer } from '../../../thirdProvider/somark';
 import { parseFromSangfor, useSangforParse } from '../../../thirdProvider/sangfor';
+import { appendIultmzhFileParseFields } from '../../../thirdProvider/sangfor/parseConfig';
 import { readRawContentFromBuffer, readRawContentFromSource } from '../../../worker/function';
 import { getLogger, LogCategories } from '../../logger';
 import { getImageBuffer } from '../image/utils';
@@ -33,6 +35,7 @@ export const readFileContentByBuffer = async ({
   buffer,
   encoding,
   customPdfParse = false,
+  sangforFileParseConfig,
   usageId,
   getFormatText = true,
   imageKeyOptions,
@@ -46,6 +49,7 @@ export const readFileContentByBuffer = async ({
   encoding: string;
 
   customPdfParse?: boolean;
+  sangforFileParseConfig?: IultmzhFileParseConfigType;
   usageId?: string;
   getFormatText?: boolean;
   imageKeyOptions?: {
@@ -62,6 +66,7 @@ export const readFileContentByBuffer = async ({
     buffer,
     encoding,
     customPdfParse,
+    sangforFileParseConfig,
     usageId,
     getFormatText,
     imageKeyOptions,
@@ -77,6 +82,7 @@ export const readFileContentBySource = async ({
   tmbId,
   source,
   customPdfParse = false,
+  sangforFileParseConfig,
   usageId,
   getFormatText = true,
   imageKeyOptions,
@@ -86,6 +92,7 @@ export const readFileContentBySource = async ({
   tmbId: string;
   source: FileSource;
   customPdfParse?: boolean;
+  sangforFileParseConfig?: IultmzhFileParseConfigType;
   usageId?: string;
   getFormatText?: boolean;
   imageKeyOptions?: {
@@ -101,6 +108,7 @@ export const readFileContentBySource = async ({
     source,
     encoding: source.metadata.encoding ?? '',
     customPdfParse,
+    sangforFileParseConfig,
     usageId,
     getFormatText,
     imageKeyOptions,
@@ -115,6 +123,7 @@ const readFileContent = async ({
   source,
   encoding: initialEncoding,
   customPdfParse,
+  sangforFileParseConfig,
   usageId,
   getFormatText,
   imageKeyOptions,
@@ -127,6 +136,7 @@ const readFileContent = async ({
   source?: FileSource;
   encoding: string;
   customPdfParse: boolean;
+  sangforFileParseConfig?: IultmzhFileParseConfigType;
   usageId?: string;
   getFormatText: boolean;
   imageKeyOptions?: {
@@ -235,6 +245,7 @@ const readFileContent = async ({
     data.append('file', buffer, {
       filename: `file.${materializedExtension}`
     });
+    appendIultmzhFileParseFields(data, sangforFileParseConfig);
     const { data: response } = await axios.post<{
       pages: number;
       markdown: string;
@@ -356,7 +367,8 @@ const readFileContent = async ({
     const { text, pages } = await parseFromSangfor({
       fileBuffer: buffer,
       extension: materializedExtension,
-      imageKeyOptions
+      imageKeyOptions,
+      sangforFileParseConfig
     });
 
     reportPdfParseUsage(pages);

packages/service/common/s3/sources/dataset/index.ts

@@ -140,15 +140,24 @@ export class S3DatasetSource extends S3PrivateBucket {
   }
 
   async getDatasetFileRawText(params: GetDatasetFileContentParams) {
-    const { fileId, teamId, tmbId, customPdfParse, getFormatText, usageId, datasetId } =
-      GetDatasetFileContentParamsSchema.parse(params);
+    const {
+      fileId,
+      teamId,
+      tmbId,
+      customPdfParse,
+      sangforFileParseConfig,
+      getFormatText,
+      usageId,
+      datasetId
+    } = GetDatasetFileContentParamsSchema.parse(params);
 
     if (!isAuthorizedDatasetFileS3Key({ key: fileId, datasetId })) {
       return Promise.reject('Invalid dataset file key');
     }
 
     const rawTextBuffer = await this.rawTextSource.getRawTextBuffer({
       customPdfParse,
+      sangforFileParseConfig,
       sourceId: fileId
     });
     if (rawTextBuffer) {
@@ -166,6 +175,7 @@ export class S3DatasetSource extends S3PrivateBucket {
       tmbId,
       source,
       customPdfParse,
+      sangforFileParseConfig,
       usageId,
       getFormatText,
       imageKeyOptions: {
@@ -177,7 +187,8 @@ export class S3DatasetSource extends S3PrivateBucket {
       sourceId: fileId,
       sourceName: filename,
       text: rawText,
-      customPdfParse
+      customPdfParse,
+      sangforFileParseConfig
     });
 
     return {

packages/service/common/s3/sources/dataset/type.ts

@@ -1,4 +1,5 @@
 import { ObjectIdSchema } from '@fastgpt/global/common/type/mongo';
+import { sangforFileParseConfigSchema } from '@fastgpt/global/core/dataset/type';
 import { ReadStream } from 'fs';
 import z from 'zod';
 
@@ -29,6 +30,7 @@ export const GetDatasetFileContentParamsSchema = z.object({
   tmbId: ObjectIdSchema,
   fileId: z.string().nonempty(), // 这是 ObjectKey
   customPdfParse: z.boolean().optional(),
+  sangforFileParseConfig: sangforFileParseConfigSchema.optional(),
   getFormatText: z.boolean().optional(), // 数据类型都尽可能转化成 markdown 格式
   datasetId: ObjectIdSchema,
   usageId: ObjectIdSchema.optional()

packages/service/common/s3/sources/rawText/index.ts

@@ -25,12 +25,12 @@ export class S3RawTextSource extends S3PrivateBucket {
   }
 
   async addRawTextBuffer(params: AddRawTextBufferParams) {
-    const { sourceId, sourceName, text, customPdfParse } =
+    const { sourceId, sourceName, text, customPdfParse, sangforFileParseConfig } =
       AddRawTextBufferParamsSchema.parse(params);
 
     // 因为 Key 唯一对应一个 Object 所以不需要根据文件内容计算 Hash 直接用 Key 计算 Hash 就行了
     const hash = createHash('md5').update(sourceId).digest('hex');
-    const key = getFileS3Key.rawText({ hash, customPdfParse });
+    const key = getFileS3Key.rawText({ hash, customPdfParse, sangforFileParseConfig });
     const buffer = Buffer.from(text);
 
     await MongoS3TTL.create({
@@ -57,10 +57,10 @@ export class S3RawTextSource extends S3PrivateBucket {
   }
 
   async getRawTextBuffer(params: GetRawTextBufferParams) {
-    const { customPdfParse, sourceId } = params;
+    const { customPdfParse, sangforFileParseConfig, sourceId } = params;
 
     const hash = createHash('md5').update(sourceId).digest('hex');
-    const key = getFileS3Key.rawText({ hash, customPdfParse });
+    const key = getFileS3Key.rawText({ hash, customPdfParse, sangforFileParseConfig });
 
     if (!(await this.isObjectExists(key))) return null;
 

packages/service/common/s3/sources/rawText/type.ts

@@ -1,10 +1,15 @@
+import { sangforFileParseConfigSchema } from '@fastgpt/global/core/dataset/type';
 import z from 'zod';
 
 export const AddRawTextBufferParamsSchema = z.object({
   customPdfParse: z.boolean().optional(),
+  sangforFileParseConfig: sangforFileParseConfigSchema.optional(),
   sourceId: z.string().nonempty(),
   sourceName: z.string().nonempty(),
   text: z.string()
 });
 export type AddRawTextBufferParams = z.input<typeof AddRawTextBufferParamsSchema>;
-export type GetRawTextBufferParams = Pick<AddRawTextBufferParams, 'customPdfParse' | 'sourceId'>;
+export type GetRawTextBufferParams = Pick<
+  AddRawTextBufferParams,
+  'customPdfParse' | 'sangforFileParseConfig' | 'sourceId'
+>;

packages/service/common/s3/utils.ts

@@ -1,4 +1,5 @@
 import { isAfter } from 'date-fns';
+import { createHash } from 'node:crypto';
 import type { ClientSession } from 'mongoose';
 import { buffer as consumeStreamToBuffer } from 'node:stream/consumers';
 import type { Readable } from 'node:stream';
@@ -299,9 +300,29 @@ export const getFileS3Key = {
     };
   },
 
-  rawText: ({ hash, customPdfParse }: { hash: string; customPdfParse?: boolean }) => {
+  rawText: ({
+    hash,
+    customPdfParse,
+    sangforFileParseConfig
+  }: {
+    hash: string;
+    customPdfParse?: boolean;
+    sangforFileParseConfig?: Record<string, unknown>;
+  }) => {
+    // 解析配置纳入缓存 key,避免同文件不同开关共享缓存;未传配置保持旧 key 格式
+    const configSuffix = sangforFileParseConfig
+      ? `-${createHash('md5')
+          .update(
+            JSON.stringify(sangforFileParseConfig, (_key, value) =>
+              value instanceof Object && !Array.isArray(value)
+                ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)))
+                : value
+            )
+          )
+          .digest('hex')}`
+      : '';
     return encodeS3ObjectKey(
-      [S3Sources.rawText, `${hash}${customPdfParse ? '-true' : ''}`].join('/')
+      [S3Sources.rawText, `${hash}${customPdfParse ? '-true' : ''}${configSuffix}`].join('/')
     );
   }
 };