文档中心

数据智能体 DataAgent（私有化）

文件转文档

文件关联知识库

调用本接口将已上传的文件关联到指定知识库，并配置解析参数。调用当前接口之前，应先调用上传文件；完成当前接口后，相关任务仅被提交、尚未正式执行，还必须继续调用开始解析文档才会真正开始执行。

接口说明

接口名称：convert_file2document_convert_post
接口地址：/file2document/convert
请求方式：POST

请求参数

说明

请求体采用 JSON 格式。最小请求只需要传入目标知识库 ID 和待导入文件 ID；如需对不同文件类型设置解析策略，可传入 chunk_settings、quality_settings 和 file_parse_type_overrides。
推荐新接入方统一使用 chunk_settings 和 quality_settings 组织解析配置；旧版字段仅用于历史兼容。
顶层旧字段 completeness_check、sensitive_word_check、duplicate_doc_check 仅保留兼容用途。新接入统一放入 quality_settings。

字段名	类型	是否必填	说明
kb_ids	Array	是	知识库 ID 列表
file_ids	Array	条件必填	文件标识符
file_parse_type_overrides	Array	否	文件解析类型覆盖；当未显式提供 file_ids/object_keys 时，可从 match.file_ids/source_keys 推断导入范围。更多信息，请参见解析类型覆盖
embd_id	String	否	嵌入模型标识符
source_type	String	否	解析模型来源类型
chunk_settings	Object	否	统一切片配置。配置详情，请参见chunk_settings 配置
quality_settings	Object	否	统一质量检测配置。配置详情，请参见quality_settings 配置。
parser_config	Object	否	解析配置，支持 LarkParserConfig / ReportifyConfig / SophonParserConfig 三种结构，详情请参见下文 parser_config 表
feishu_config	Array	否	飞书配置，详情请参见下文 feishu_config 表
schedule_config	Object	否	调度配置，详情请参见下文 schedule_config 表
object_keys	Array	条件必填	对象存储导入场景下的源文件 key 列表。未显式传入时，可由 `file_parse_type_overrides.match.source_key` 或 `file_parse_type_overrides.match.source_keys` 推导。
template_id	String	否	解析模板标识符，将覆盖 parser_config
apply_type	Number	否	应用类型
access_key	String	否	访问密钥（即将废弃）
secret_key	String	否	秘密密钥（即将废弃）
oss_config	Object	否	OSS 配置
media_platform_config	Object	否	媒体平台配置
public_url_config	Object	是	公开链接导入配置
datasource_code	String	对象存储场景必填	数据源类型标识，例如对象存储导入时使用 `object_storage`。
folder_id	Number	否	导入目标文件夹ID
datasource_meta_id	Number	对象存储场景必填	数据源元信息 ID。
data_connection_id	Number	否	数据连接ID
name	String	""	文档名称
rds_config	Object	否	RDS 配置
vecdp_config	Object	否	VecDP 配置
labels	Array	否	文档标签列表，外层列表对应多个文档，内层列表对应单个文档的标签
label_ids	Array	否	批量设置文档标签，标签ID集合
extras	Array	否	额外数据
extra	Object	否	版本组额外参数，用于向Sophon传递其他参数
ocr_model	String	否	已废弃。请使用 switch_config: switch_doc_parser_vlm_ocr来控制ocr后端
prompt_locale	String	否	透传给 Sophon VLM 解析的提示词语言环境，例如 zh-CN 或 en-US
spell_check	Boolean	否	是否启用拼写检查
completeness_check	Boolean	否	已废弃：请使用 quality_settings.*.completeness_check
sensitive_word_check	Boolean	否	已废弃：请使用 quality_settings.*.sensitive_word_check
duplicate_doc_check	Boolean	否	已废弃：请使用 quality_settings.*.duplicate_doc_check
video_parser_config	Object	否	视频解析配置，详情请参见下文 video_parser_config 表

最小可用请求示例

{
  "kb_ids": [123],
  "file_ids": [1001]
}

解析类型覆盖

file_parse_type_overrides 用于按文件声明逻辑解析类型。它只决定文件应读取哪一类解析配置，不直接覆盖具体切片参数；具体参数仍放在对应类型的 chunk_settings 和 file_overrides 中。

匹配规则

字段	适用场景	说明
match.file_id	本地上传	匹配单个文件 ID。
match.file_ids	本地上传	批量匹配多个文件 ID。
match.source_key	对象存储导入	匹配单个源文件 key。
match.source_keys	对象存储导入	批量匹配多个源文件 key。

parse_type 可选值：text、doc、other、pdf、ppt、image、table。其中 doc 会按 text 处理。

{
  "file_parse_type_overrides": [
    {
      "match": {
        "file_ids": [1002, 1003]
      },
      "parse_type": "ppt"
    }
  ],
  "chunk_settings": {
    "ppt": {
      "max_segment_length": 800,
      "exclude_master_content": true
    }
  }
}

chunk_settings 配置

chunk_settings 按文件类型分组，用于控制不同类型文件的切片、解析和导入提取参数。字段统一使用 snake_case。

一、文件类型分组

分组	适用文件	说明
`text`/`doc`	.doc、.docx、.txt、.md 等	通用文档；`doc` 为兼容别名。
`other`	.html、.json 等	其它文档类型。
`pdf`	.pdf	PDF 文件。
`ppt`	.ppt、.pptx	演示文稿。
`image`	图片文件	图片理解和 OCR 配置。
`audio`	.mp3、.wav	音频转写配置。
`video`	.mp4、.mov、.avi	视频理解、音频转写和音视频融合配置。
`table`	.xls、.xlsx、.csv	表格自动分段或自定义分段配置。

二、通用文档、其它文档与 PDF 配置

字段名	类型	说明
`mode`	String	切片模式。可选值：`default`、`custom`、`model_summary`、`context_aware`。
`max_segment_length`	Integer	每个切片分段的最大长度，默认 1024。
`custom_separator`	String	自定义分隔符，仅在 `mode=custom` 时生效。
`associate_chunk_title`	Boolean	自定义分段时是否关联标题，仅在 `mode=custom` 时生效。
`merge_small_chunks`	Boolean	自定义分段时，是否自动合并连续小分段。
`small_chunk_token_threshold`	Integer	小分段阈值，单位 token。
`extract_images`	Boolean	是否从文档中提取图片，默认 true。
`image_understand`	Boolean	是否对提取出的图片进行智能理解，默认 false。
`image_understand_max_tokens`	Integer	图片智能理解时允许生成的最大输出 token 数。
`extract_tables`	Boolean	是否从文档中提取表格，默认 false。

三、PPT、图片、音频与视频配置

类型	字段	说明
`ppt`	`mode`、`max_segment_length`、`exclude_master_content`、`exclude_header_footer`	PPT 仅支持自动分段，可配置切片长度、去除母版噪声、去除页眉页脚。
`image`	`mode`、`image_understand`、`image_ocr`、`max_segment_length`	控制图片理解、OCR 和切片长度。
`audio`	`mode`、`asr_model`	导入音频文件时，必须提供 `asr_model`。
`video`	`mode`、`fuse_video_asr`、`asr_model`、`video_model`、`fuse_model`	导入视频文件时，必须提供 `asr_model`、`video_model` 和 `fuse_model`。

注意

导入音频文件缺少 chunk_settings.audio.asr_model，或导入视频文件缺少 chunk_settings.video.asr_model、video_model、fuse_model 时，请求会在入口校验阶段失败。

四、表格配置

表格文件支持自动分段和自定义分段。推荐按以下层级组织配置：table 表示表格默认策略，table.file_overrides[] 命中特定文件，file_overrides[].sheets[] 指定 sheet，sheets[].columns[] 指定列配置。

场景	配置方式	说明
自动分段	`mode=auto`	系统完成 sheet 和表头识别。可通过 `parse_strategy` 指定模型识别或规则配置。
模型自动识别表头	`parse_strategy=model_auto_header`	由模型识别表头。
规则配置	`parse_strategy=rule`，并配置 `header_row`、`data_start_row`	按指定行号识别表头和数据起始行，行号从 1 开始。
自定义分段	`file_overrides[].mode=custom`，并配置 `sheets`，详情参见下文 sheets 字段表	为某个表格文件的一个或多个 sheet 单独配置切分规则和列配置。

sheets 字段

字段名	类型	是否必填	说明
`sheet_name`	String	条件必填	sheet 名称；与 `sheet_id` 至少传一个。
`sheet_id`	String	条件必填	sheet ID；与 `sheet_name` 至少传一个。
`header_row`	Integer	否	当前 sheet 的表头所在行，从 1 开始。
`data_start_row`	Integer	否	当前 sheet 的数据起始行，从 1 开始。
`columns`	List	否	当前 sheet 的列配置。详情参见下文 columns 字段表。

columns 字段

字段名	类型	说明
`source_name`	String	原始列名。
`target_name`	String	导入后的列别名。未传时使用 `source_name`。
`enabled`	Boolean	是否启用该列参与召回，默认 true。
`data_type`	String	列数据类型。可选值：`STRING`、`INT`、`DOUBLE`、`DATE`、`DATETIME`、`ARRAY`、`LINK`。未传时默认 `STRING`。
`description`	String	列描述。

quality_settings 配置

quality_settings 负责管理质量检测和重复文档校验策略，按文件类型分组，类型名称与 chunk_settings 一致。当前 quality_settings 不支持 file_overrides。

字段名	类型	说明
`spell_check`	Boolean	是否开启错别字检测。
`completeness_check`	Boolean	是否开启完整度检测。
`sensitive_word_check`	Boolean	是否开启敏感词检测。
`duplicate_doc_check`	Boolean	是否开启重复文档校验。该配置会在导入前生效，只校验当前命中文件类型下开启了该开关的文件。

{
  "quality_settings": {
    "text": {
      "completeness_check": true,
      "sensitive_word_check": false,
      "duplicate_doc_check": true
    },
    "ppt": {
      "completeness_check": false,
      "sensitive_word_check": true,
      "duplicate_doc_check": false
    }
  }
}

配置生效规则

当一次请求包含多个文件时，系统会按文件逐一解析配置。高优先级配置会覆盖低优先级配置的同名字段。

优先级	配置来源	说明
1	`file_parse_type_overrides`	判断当前文件是否覆盖默认解析类型；未命中则继续按默认文件类型读取配置。
2	`file_overrides`	在最终命中的文件类型分组内，查找是否存在命中当前文件的覆盖项。
3	类型级全局配置	使用文件类型对应的全局配置，例如 `text`、`pdf`、`audio`、`video`、`table`。
4	`parser_config`	历史兼容配置，仅当新配置未定义相关字段时回退。
5	系统默认值	以上配置均未提供时，使用系统预设默认值。

校验与限制

规则	说明
表格模式互斥	`mode=auto` 时不允许在同一层级配置 `sheets`；`mode=custom` 时必须配置同层级 `sheets`。
自动分段规则配置	`mode=auto` 下，只有 `parse_strategy=rule` 时才允许配置 `header_row` 和 `data_start_row`。
自定义分段限制	`mode=custom` 时不允许配置 `parse_strategy`，也不允许在同一层级配置 `header_row` 或 `data_start_row`。
CSV 限制	CSV 文件没有 sheet 概念，不适用多 sheet 配置。
音频必填模型	导入音频文件时必须提供 `chunk_settings.audio.asr_model`。
视频必填模型	导入视频文件时必须提供 `chunk_settings.video.asr_model`、`chunk_settings.video.video_model` 和 `chunk_settings.video.fuse_model`。

parser_config

Situation 1：飞书解析配置

字段名	类型	是否必填	说明
auto_keywords	Number	是	自动关键词数量
auto_questions	Number	是	自动问题数量
strategy	Number	是	切片拆分策略
chunk_size	Number	是	切片最大长度
detect_pdf_table	Boolean	否	是否识别 PDF 表格
detect_pdf_img	Boolean	否	是否识别 PDF 图片
page_size_limit	Number	否	分页大小限制
merge_small_chunks	Boolean	否	是否合并小切片
pdf_with_ocr	Boolean	否	是否启用 PDF OCR
doctree_with_outline	Boolean	否	是否输出带大纲的文档树
custom_splitter	String	否	自定义切分符
to_md	Boolean	否	是否转换为 Markdown
md_collapsed	Boolean	否	Markdown 是否折叠
tos_bucket_name	String	否	TOS Bucket 名称
tos_access_key	String	否	TOS 访问密钥
detect_header	Boolean	否	excel解析是否开启表格识别
file_trans_timeout	Number	否	pptx/ppt解析中转换图片的超时时间设置
slides_full_page_as_image	Boolean	否	在 PPT 类文件中，使用整页图片代替小图片在 PPT 类文件中，使用整页图片代替小图片
open_access_token	String	否	飞书开放平台 access_token
lark_doc_user_id	String	否	云文档/多维表格/飞书表格域间网关鉴权所需用户ID
chunk_with_vlm	Boolean	否	是否使用 VLM 能力，包括章节理解、图片理解等
expected_level	Number	否	章节预期最大层级
deduplicate	Boolean	否	是否自动去重
spell_check	Boolean	否	是否开启错别字检测
completeness_check	Boolean	否	是否开启完整度检测
sensitive_word_check	Boolean	否	是否开启敏感词检测
enable_llm_tag	Boolean	否	是否开启非结构化打标
tableExtraction	Boolean	否	表格提取开关
imageExtraction	Boolean	否	图片提取开关

Situation 2：报告解析配置

字段名	类型	是否必填	说明
delimiter	String	否	分隔符
deduplicate	Boolean	否	是否自动去重
enable_llm_tag	Boolean	否	是否开启非结构化打标

Situation 3：Sophon 解析配置

字段名	类型	是否必填	说明
imageExtraction	Boolean	否	图片提取开关
tableExtraction	Boolean	否	表格提取开关
chunkType	String	否	分片策略类型
genAtomicQuestion	Boolean	否	是否生成原子问题
maxSegmentLength	Number	否	分片最大字符数
maxToken	Number	否	已废弃：兼容旧字段，当前本地上传按字符解释
removeSpaces	Boolean	否	去除空白字符
removeUrlsPics	Boolean	否	去除图片 URL
separator	String	否	分隔符
customSeparator	String	否	自定义分隔符
mergeSmallChunks	Boolean	否	是否合并连续小分段
smallChunkTokenThreshold	Number	否	小分段阈值，单位 token
pipelineTypeEnum	String	否	解析方式，如 VISION_MODEL
visionPagesPerChunk	Number	否	Vision model 模式下每次处理的页数
spell_check	Boolean	否	是否开启错别字检测
completeness_check	Boolean	否	是否开启完整度检测
sensitive_word_check	Boolean	否	是否开启敏感词检测
enable_llm_tag	Boolean	否	是否开启非结构化打标
deduplicate	Boolean	否	是否自动去重

feishu_config

字段名	类型	是否必填	说明
user_id	String	否	飞书用户ID
name	String	否	文档名称
doc_type	String	否	文档内容类型
source	String	否	文档导入来源
url	String	否	文档 URL
token	String	是	飞书文档导入 token
sheets	Array	否	飞书表格 sheet 设置，详情请参见下文 sheets 表
callback_url	String	否	飞书文档导入完成后的回调 URL

sheets

字段名	类型	是否必填	说明
sheet_title	String	否	飞书表格 sheet 名称
sheet_id	String	否	飞书表格 sheet ID

schedule_config

字段名	类型	是否必填	说明
schedule_type	Number	否	调度类型：0-无需更新，1-定时更新
frequency	String	否	调度频率
time_setting	String	否	时间设置
day_of_week	Array	否	星期几
day_of_month	Array	否	每月几号
bdb_task_id	Number	否	任务ID

video_parser_config

字段名	类型	是否必填	说明
fuse_video_asr	Boolean	否	是否使用音视频融合解析
asr_model	String 或 Object	否	ASR 模型，详情请参见上文 asr_model 章节
video_model	String 或 Object	否	视频模型，详情请参见上文 video_model 章节
fuse_model	String 或 Object	否	融合模型，详情请参见上文 fuse_model 章节

asr_model

Situation 1：String 类型，非必传，ASR 模型
Situation 2：Object 类型，必传，ASR 模型端点

参数名	类型	是否必传	描述
host	String	否	服务地址
api_key	String	否	接口密钥
access_token	String	是	访问令牌
app_id	String	是	应用ID
resourceId	String	是	资源ID
endpoint_id	String	否	端点ID
temperature	Number	否	采样温度
top_p	Number	否	核采样概率 Top P
model_id	Number	否	模型ID

Situation 3：Object 类型，必传，模型索引

参数名	类型	是否必传	描述
operator_key	String	是	算子标识
model_id	Number	是	模型ID

video_model

Situation 1：String 类型，非必传，视频模型
Situation 2：Object 类型，必传，模型端点

参数名	类型	是否必传	描述
url	String	是	模型访问地址
model_name	String	是	模型名称
api_key	String	是	接口密钥

Situation 3：Object 类型，必传，模型索引

参数名	类型	是否必传	描述
operator_key	String	是	算子标识
model_id	Number	是	模型ID

fuse_model

Situation 1：String 类型，非必传，视频模型
Situation 2：Object 类型，必传，模型端点

参数名	类型	是否必传	描述
url	String	是	模型访问地址
model_name	String	是	模型名称
api_key	String	是	接口密钥

Situation 3：Object 类型，必传，模型索引

参数名	类型	是否必传	描述
operator_key	String	是	算子标识
model_id	Number	是	模型ID

响应参数

说明

接口返回统一 JSON 结构。调用方应优先根据 code 判断请求是否成功：code=0 表示成功，非 0 表示失败。

参数名称	参数类型	参数说明
code	Integer	响应码。`0` 表示成功，非 `0` 表示失败。
msg	string	响应信息。成功时通常为 `success`，失败时返回错误原因。
data	List	成功时返回导入结果列表；失败时通常为 `null`。详情参见下文 data 表。

data

参数名称	参数类型	参数说明
data[].id	Integer	文件与文档关联记录 ID。
data[].file_id	Integer	本次导入的源文件 ID。
data[].document_id	Integer	导入后生成的文档 ID。后续查询、管理或重新分段时可使用该 ID。
data[].running_state	String	解析任务运行状态，可为空。该字段用于兼容异步处理状态展示，未返回时以实际文档状态查询结果为准。

请求示例

{
  "kb_ids": [123],
  "file_parse_type_overrides": [
    {
      "match": {
        "file_ids": [1001]
      },
      "parse_type": "text"
    },
    {
      "match": {
        "file_ids": [1002]
      },
      "parse_type": "ppt"
    },
    {
      "match": {
        "file_ids": [1004]
      },
      "parse_type": "table"
    }
  ],
  "chunk_settings": {
    "text": {
      "mode": "custom",
      "max_segment_length": 1200,
      "custom_separator": "\\n---\\n",
      "associate_chunk_title": true,
      "merge_small_chunks": true,
      "small_chunk_token_threshold": 128,
      "extract_images": true,
      "image_understand": true,
      "image_understand_max_tokens": 1024,
      "extract_tables": true
    },
    "ppt": {
      "max_segment_length": 800,
      "exclude_master_content": true,
      "exclude_header_footer": true
    },
    "table": {
      "mode": "auto",
      "parse_strategy": "model_auto_header",
      "file_overrides": [
        {
          "match": {
            "file_id": 1004
          },
          "mode": "custom",
          "sheets": [
            {
              "sheet_name": "汇总",
              "header_row": 2,
              "data_start_row": 3,
              "columns": [
                {
                  "source_name": "城市",
                  "target_name": "city",
                  "enabled": true,
                  "data_type": "STRING",
                  "description": "城市列"
                },
                {
                  "source_name": "金额",
                  "target_name": "amount",
                  "enabled": true,
                  "data_type": "DOUBLE",
                  "description": "金额列"
                }
              ]
            }
          ]
        }
      ]
    }
  },
  "quality_settings": {
    "text": {
      "completeness_check": true,
      "sensitive_word_check": false,
      "duplicate_doc_check": true
    },
    "ppt": {
      "completeness_check": false,
      "sensitive_word_check": true,
      "duplicate_doc_check": false
    }
  }
}

响应示例

成功响应示例

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "id": 9001,
      "file_id": 1001,
      "document_id": 2001,
      "running_state": null
    }
  ]
}

失败响应示例

{
  "code": 500,
  "msg": "kb_ids 不能为空",
  "data": null
}

最近更新时间：2026.07.27 21:58:47

这个页面对您有帮助吗？

有用

无用

数据智能体 DataAgent（私有化）

最小可用请求示例 #

解析类型覆盖 #

匹配规则 #

chunk_settings 配置 #

一、文件类型分组 #

二、通用文档、其它文档与 PDF 配置 #

三、PPT、图片、音频与视频配置 #

四、表格配置 #

sheets 字段

columns 字段

quality_settings 配置 #

配置生效规则 #

校验与限制 #

parser_config #

Situation 1：飞书解析配置 #

Situation 2：报告解析配置 #

Situation 3：​Sophon 解析配置 #

feishu_config #

sheets #

schedule_config #

video_parser_config #

asr_model #

video_model #

fuse_model #

data #

成功响应示例 #

失败响应示例 #