Easydoc 文档解析

概述

EasyDoc文档内容提取助手（支持扫描件/图片）

概述

调用 EasyDoc 异步解析接口，把原始文档转换成适合 AI 应用继续处理的结构化结果–“AI Ready Data”。解析时不仅提取文字，还尽量保留版面、层级和语义关系，为后续问答、检索和推理提供更完整的上下文。

核心解析能力包括：

• 复杂版面识别：识别多栏排版、图文混排、跨页文本和跨页表格，保留内容块之间的位置与逻辑关系。
• 文档层次还原：识别标题层级、段落组织和章节关系，并通过节点关系保留文档上下文。
• 表格与表单解析：识别有线表、无线表、合并单元格及跨页表格，保留表头、数据和键值对之间的对应关系。
• 图片与图表理解：提取图片文字，并为图片、柱状图、折线图、流程图等视觉内容生成语义描述，帮助下游检索和分析。
• 公式解析：识别数学公式、化学方程等复杂符号，并以 LaTeX 等结构化形式输出。
• 布局分析与精准溯源：识别页眉、页脚、题注、脚注等内容类型，提供页码和坐标信息，便于定位解析结果在原文中的位置。

具体能力和返回字段以解析模式及 API 实际响应为准。

始终按以下顺序处理：检查输入、提交任务、查询进度、整理输出。

RAG 检索

解析结果用于 RAG 时，默认不要一次性读取整个 JSON 文件。

1. 先搜索，再读取

• 如果当前环境提供 Grep、Search 或其他文件内容搜索工具，优先使用这些工具。
• 先在解析后的 JSON 中查找可能相关的段落、标题、节点 ID、表格标记或元数据字段。
• 打开大型文件前，先搜索用户问题中的关键词、实体名称、日期范围、章节标题和节点 type。
• 不要为这一检索过程额外编写 Python 搜索脚本。
• 当前环境已有同类搜索工具时，不要再通过 Shell 调用 grep 或 rg。

1. 只读取命中片段

• 找到相关内容后，只读取命中行及其附近的少量内容。
• 只提取后续摘要或向量化需要的节点、章节或页面。

1. 仅在确有必要时读取完整文件

• 只有任务需要完整文档结构、整棵节点树或完整导出时，才读取整个 JSON。
• 必须完整读取时，说明原因。

API Key 配置

用户没有 API Key 时，提供以下配置指引：

• 打开 https://platform.easylink-ai.com
• 注册或登录
• 进入 API Key 管理页面并创建密钥
• 将密钥保存为 EASYLINK_API_KEY

API 接口

• 基础地址：https://api.easylink-ai.com
• 提交任务：POST /v1/easydoc/parse
• 查询结果：GET /v1/easydoc/parse/{task_id}
• 文件上传字段：files
• 推荐模式：easydoc-parse-flash、easydoc-parse-premium

工作流程

1. 检查输入

• 从用户安全提供的值或环境变量中读取 api-key。
• 接口需要解析模式时必须提供 mode。使用随附脚本且未指定模式时，默认采用 easydoc-parse-premium。
• 按接口支持的扩展名检查文件格式，并确认文件不超过 100MB。
• 如果缺少密钥，提供申请步骤，并说明需要设置 EASYLINK_API_KEY。

1. 提交解析任务

• 使用上述提交地址和文件上传字段。
• 提交时带上 mode。
• 从响应中读取 task_id。

1. 查询任务进度

• 使用上述结果查询接口。
• 任务仍在等待或处理中时继续查询。
• 遇到结束状态（SUCCESS、ERROR、FAILED、COMPLETED、DONE）或超时后停止查询。

1. 整理输出

• 将 API 原始响应保存在 raw 中。
• 按统一结构返回 task_id、status 和 files，供后续流程直接使用。

1. 处理异常

• 能够取得 task_id 时，在错误信息中一并返回。
• API 请求失败时，报告 HTTP 状态码和响应正文。
• 文档解析失败时，建议更换解析模式或重新提交。

1. 读取大型解析结果

• JSON 较大时，先使用当前环境提供的文本搜索工具定位相关内容，再决定是否读取更多内容。
• 除非任务必须遍历完整文档，否则不要把整个解析结果粘贴或加载到上下文中。

快速调用

curl -X POST "https://api.easylink-ai.com/v1/easydoc/parse" 
  -H "api-key: $EASYLINK_API_KEY" 
  -F "files=@document.pdf" 
  -F "mode=easydoc-parse-premium"

随附的 Python 辅助脚本：

python3 scripts/easydoc_parse.py --platform cn --api-key "$EASYLINK_API_KEY" 
  --mode easydoc-parse-premium --file ./document.pdf --save ./result-cn.json

# key can come from environment if --api-key is omitted
export EASYLINK_API_KEY="your-cn-key"
python3 scripts/easydoc_parse.py --platform cn --file ./document.pdf --save ./result-cn.json

参考资料与脚本

• 需要确认接口地址、支持格式和参数时，查看 references/easydoc-rest-api.md。
• 使用 scripts/easydoc_parse.py，按固定流程提交任务并查询结果。
• 脚本默认输出 normalized 格式；只需要原始响应时，使用 --output-format raw。
• 在 RAG 工作流中，先使用当前环境内置的文件内容搜索工具检索已保存的 JSON，再打开大型文件片段。

输出格式

{
  "task_id": "string",
  "status": "SUCCESS|ERROR|PENDING|PROCESSING|FAILED|COMPLETED|DONE",
  "files": [
    {
      "file_name": "string",
      "markdown": "string or null",
      "nodes": []
    }
  ],
  "raw": {}
}