跳转到主要内容

​
概念

文档解析是将非结构化文件内容提取并转换为结构化文档元素的过程。 与简单将文件视为纯文本不同，xParse 通过解析保留了文件的语义结构，让您能够在后续处理流程中进行更灵活的控制，并能充分考虑文件的结构特点。同时，通过将不同文件格式统一转换为 xParse 的元素类型，无论源文件是什么格式，您都可以在下游采用相同的方式处理。

​
用途

文档解析的主要用途：
  • 内容提取：从 PDF、WORD、EXCEL、PPT、图片等多种格式中提取文本和其他内容
  • 结构化转换：将提取的内容转换为标准化的文档元素，便于后续处理
  • 语义保留：保留文档的语义结构，如标题、段落、表格等
  • 格式统一：将不同格式的文档统一转换为相同的元素结构

​
参数说明

​
provider

类型: string
必填: 是
默认值: textin
可选值: textin | textin-lite | mineru | paddle Parser 解析引擎选择：
  • textin: TextIn 自研高性能解析引擎，在速度、准确性上均为行业领先，适合大多数场景（推荐）
  • textin-lite: TextIn 全文识别解析引擎，适合纯文本、表格图片、电子档 pdf 等场景，速度更快，价格更低
  • mineru: MinerU 解析引擎，在学术论文等场景表现优异
  • paddle: PaddleOCR 解析引擎，在多语言和复杂文档场景（如PPT）表现优异
更多先进引擎正在陆续支持中，敬请期待。

​
pdf_pwd

类型: string
必填: 否 PDF 密码。当 PDF 为加密文档时，需要提供密码。
安全提示：对前端封装该接口参数时，需要自行对密码进行安全防护。

​
page_ranges

类型： string
必填: 否 指定解析页码范围，格式为逗号分隔的字符串。
  • 15: 只解析第 15 页
  • 20-25: 解析第 20 页到第 25 页
  • 1,3,5-7: 解析第 1、3、5、6、7 页

​
crop_dewarp

类型: integer
必填: 否
默认值: 0
可选值: 0 | 1
是否进行切边矫正预处理，默认为0，不进行切边矫正。
  • 0: 不进行切边矫正
  • 1: 进行切边矫正

​
remove_watermark

类型: integer
必填: 否
默认值: 0
可选值: 0 | 1 是否进行去水印预处理，默认为0，不去水印。
  • 0: 不去水印
  • 1: 去水印

​
get_page_image

类型: boolean
必填: 否
默认值: false
是否返回每一页的图片，适用于PDF等需要转成图片解析的文件。当设置为 true 时，返回结果中会包含 page_image_url 字段。

​
get_sub_image

类型: boolean
必填: 否
默认值: false
是否返回页面内的子图。当设置为 true 时，返回结果中会包含 image_base64 字段。

​
image_storage_config

类型: object
必填: 否
S3存储配置，用于存储每页的图片。如果缺省，默认托管在xParse后台，通过xParse提供的链接下载图片。 字段说明：
  • endpoint (string): S3端点地址，例如 "https://s3.oss-cn-beijing.aliyuncs.com"
  • access_key (string): S3访问密钥
  • secret_key (string): S3密钥
  • bucket (string): S3存储桶名称
  • region (string): S3区域，例如 "cn-beijing"
  • prefix (string): 存储前缀，默认为空字符串
  • url_prefix (string): 自定义配置图片下载服务URL前缀。xParse会将图片存储到目标S3，每张图片拥有唯一的hash_id，通过 url_prefix + hash_id 即可下载图片

​
Textin 引擎特定参数（provider = textin 时）

​
parse_mode

类型: string
必填: 否
默认值: scan
可选值: auto | scan pdf文档的解析模式，默认为scan模式。图片不用设置，均默认按scan模式处理。
  • auto: 综合文字识别和解析模式：对pdf电子档解析，会直接提取pdf中的文字
  • scan: 仅按文字识别模式：将pdf当成图片处理

​
underline_level

类型: integer
必填: 否
默认值: 0
可选值: 0 | 1 | 控制下划线识别范围。
  • 0: 不识别
  • 1: 仅识别无文字的下划线（仅 scan 模式可用）

​
apply_chart

类型: integer
必填: 否
默认值: 0
可选值: 0 | 1 图表识别。是否开启图表识别，开启图表识别会将识别到的图表以表格形式输出。
  • 0: 不开启图表识别
  • 1: 开启图表识别

​
MinerU 引擎特定参数（provider = mineru 时）

xParse 支持 MinerU vlm 模型，除了上述通用参数，xParse 内部会将其余参数设置为默认值，暂时不支持用户自定义，具体参数请参考MinerU API 文档。

​
Paddle 引擎特定参数（provider = paddle 时）

xParse 支持 PaddleOCR-VL 模型，除了上述通用参数，xParse 内部会将其余参数设置为默认值，暂时不支持用户自定义，具体参数请参考PaddleOCR API 文档。

​
输出结果说明

parse 阶段返回一个文档元素列表。每个元素包含以下字段：
  • element_id: 元素的唯一标识符（文本+坐标+页码+文件名的 SHA-256）
  • type: 元素类型（如 NarrativeText、Title、Table 等）
  • text: 提取的文本内容
  • metadata: 元数据信息，常见字段包括：
    • filename / filetype
    • last_modified
    • page_number / page_width / page_height
    • coordinates：8位数组，表示四边形四个点，归一化坐标，范围 [0, 1]
    • parent_id / category_depth
    • image_base64 / image_mine_type：image_base64 当开启 get_sub_image 时返回
    • page_image_url：当开启 get_page_image 时返回，表示页面图片的下载链接。如果开启预处理参数，返回的是预处理后的页面图片
    • original_image_url：仅在开启预处理参数（crop_dewarp=1或remove_watermark=1）时返回，表示未经预处理的原始页面图片链接
    • figure_caption_id：当元素为图片时（type=Image），表示图片对应的标题元素id（type=FigureCaption）
    • text_as_html：表格或富文本元素的HTML表示
    • data_source ：数据源详细信息

​
返回结果示例

{
    "code": 200,
    "message": "success",
    "x_request_id": "81017abf0fdd3f63ca5c42872cd09a0b",
    "data": {
        "elements": [
            {
                "element_id": "13a9939f23e485ca20a16c741658bcf64efd82309a6f0a8cf35679a65b2fd0dc",
                "type": "NarrativeText",
                "text": "xParse 是一个端到端文档处理 AI 基础设施，致力于将非结构化文档高效转化为可查询、可分析的向量数据资产。",
                "metadata": {
                    "filename": "example.pdf",
                    "filetype": "application/pdf",
                    "last_modified": "1758624866230",
                    "page_number": 1,
                    "page_width": 1191,
                    "page_height": 1684,
                    "parent_id": "23a9939f23e485ca20a16c741658bcf64efd82309a6f0a8cf35679a65b2fd0dc",
                    "category_depth": 1,
                    "coordinates": [0.1822, 0.2316, 0.6717, 0.2316, 0.6717, 0.2732, 0.1822, 0.2732],
                    "text_as_html": "<p>...</p>",
                    "data_source": {
                        "record_locator": {
                            "protocol": "file",
                            "remote_file_path": "/projects/demo/example.pdf"
                        },
                        "url": "file:///projects/demo/example.pdf",
                        "version": "1758624866230967485",
                        "date_created": "1764555574237",
                        "date_modified": "1758624866230",
                        "date_processed": "1764742970688"
                    }
                }
            },
            // ... more elements
        ]
    },
}
更多返回结果示例请参考文档元素和元数据。

​
使用示例

​
示例 1：基础解析配置

from xparse_client import (
    Pipeline,
    LocalSource,
    LocalDestination,
    Stage,
    ParseConfig
)

# 创建数据源
source = LocalSource(
    directory='./documents',
    pattern=['*.pdf']
)

# 创建目标存储
destination = LocalDestination(
    output_dir='./output'
)

# 创建解析配置
parse_config = ParseConfig(
    provider='textin',
    parse_mode='auto'
)

# 创建 Pipeline
pipeline = Pipeline(
    source=source,
    destination=destination,
    api_base_url='https://api.textin.com/api/xparse',
    api_headers={
        'x-ti-app-id': 'your-app-id',
        'x-ti-secret-code': 'your-secret-code'
    },
    stages=[
        Stage(
            type='parse',
            config=parse_config
        )
    ]
)

pipeline.run()

​
示例 2：解析加密 PDF

from xparse_client import ParseConfig

# 创建解析配置，包含 PDF 密码
parse_config = ParseConfig(
    provider='textin',
    pdf_pwd='your-password'  # 提供 PDF 密码
)

# 在 Pipeline 中使用
# pipeline = Pipeline(
#     source=source,
#     destination=destination,
#     stages=[
#         Stage(type='parse', config=parse_config)
#     ],
#     # ... 其他配置
# )

​
示例 3：仅解析特定页面

from xparse_client import ParseConfig

# 创建解析配置，指定解析页面范围
parse_config = ParseConfig(
    provider='textin',
    page_ranges='5-7'  # 解析第 5 页到第 7 页
)

# 在 Pipeline 中使用
# pipeline = Pipeline(
#     source=source,
#     destination=destination,
#     stages=[
#         Stage(type='parse', config=parse_config)
#     ],
#     # ... 其他配置
# )

​
示例 4：使用图片存储功能

from xparse_client import ParseConfig

# 创建解析配置，启用图片存储功能
parse_config = ParseConfig(
    provider='textin',
    get_page_image=True,  # 返回页面图片
    get_sub_image=True,    # 返回子图
    image_storage_config={
        'endpoint': 'https://s3.oss-cn-beijing.aliyuncs.com',
        'access_key': 'your-access-key',
        'secret_key': 'your-secret-key',
        'bucket': 'your-bucket-name',
        'region': 'cn-beijing',
        'prefix': '',
        'url_prefix': 'https://your-file-server.com/download?filename='
    }
)

# 在 Pipeline 中使用
# pipeline = Pipeline(
#     source=source,
#     destination=destination,
#     stages=[
#         Stage(type='parse', config=parse_config)
#     ],
#     # ... 其他配置
# )

​
Parse API说明

xParse提供了三种方式使用Parse功能：

​
1. Pipeline中的Parse节点

在Pipeline API中使用Parse作为第一个stage，可以与其他stage（chunk、embed、extract）组合使用。 适用场景：
  • 需要组合多个处理阶段（parse + chunk + embed）
  • 需要批量处理文档
  • 需要将结果存储到向量数据库
API文档：Pipeline API

​
2. Parse同步API

直接调用Parse API，立即返回解析结果。 适用场景：
  • 只需要文档解析功能
  • 需要同步获取结果
  • 处理单个文档
API文档：Parse同步API

​
3. Parse异步API

提交Parse任务，通过job_id查询处理状态和结果。 适用场景：
  • 处理大文件或批量文件
  • 需要异步处理，避免长时间等待
  • 需要webhook回调通知
API文档：Parse异步API 使用教程：详细的使用示例和最佳实践请参考API使用指南。

​
同步 vs 异步API比较

特性同步API异步API
响应方式立即返回结果返回job_id，需查询状态
等待时间需要等待处理完成立即返回，后台处理
适用场景小文件、单个文档大文件、批量处理
超时限制受HTTP超时限制无超时限制
Webhook支持不支持支持
使用复杂度简单需要轮询或webhook

​
选择建议

  • 小文件（<10MB）：使用同步API，简单直接
  • 大文件（>10MB）或批量处理：使用异步API，避免超时
  • 需要组合处理：使用Pipeline API
  • 需要实时响应：使用同步API
  • 需要后台处理：使用异步API + Webhook

​
相关文档