# 文档解析 API：下载包的使用范围

2026-10-16，本包把当前公开 API 文档的一个截断 JSON 示例和既有公开网页演示 JSON，交给同一个本地只读检查脚本。

## 解压与运行

完整解压到新目录，使用 Python 3.9 或以上：

```bash
python3 check-doc2x-api-result.py api-docs-excerpt.json --expect-layout
python3 check-doc2x-api-result.py web-demo-pages.json --expect-layout
```

第一条退出码为0：官方文档片段包含1页、4个布局块，结构检查通过。它是已公开文档中截断的示例，不是本轮真实调用 API，也不是完整响应、OCR 准确率或布局顺序测评。

第二条退出码为2：两页网页演示使用 `pageIdx`，不是公开 PDF API 的 `page_idx`。脚本不会重命名字段、补造 `layout.blocks` 或猜测坐标。实际预期报告已一起保存，供对照。

要检查自己的结果时，明确先保存成功状态下的 `data.result`，或保存完整且成功的 parse/status 响应，再在本机运行：

```bash
python3 check-doc2x-api-result.py result.json --expect-layout
```

本脚本不联网、不读取 API Key、不创建任务、不下载图片、不改写输入文件。它只读取命令行指定的一个本地 JSON；最大20MiB，重复JSON键和NaN等非标准数值会被拒绝。无需安装第三方库。输入错误只输出固定错误码，不回显文件路径、正文、block ID 或资源 URL。

## 什么算通过

- 先检查外层 `code`、`data.status`，处理中或失败不能当成已完成。
- 每页 `page_idx` 是非负整数且不重复；Markdown 是字符串，页面宽高为正。
- 有布局时核对 `blocks` 数组、块ID、类型、四项有限 bbox、reading_order 的数据类型。未知的新类型与额外字段保留兼容，不因文档片段截断而强制补全父子引用。
- `--expect-layout` 将缺失布局视为错误；不加时只提示，适合并未要求v3布局的结果。空正文、空块或超出页面范围的坐标需要对照原页检查，即使退出码为0仍可能有warnings。

这些检查不判断文字是否识别正确、bbox是否覆盖正确内容、阅读顺序是否合理、图片链接能否访问、向量检索或生成答案是否正确。结构通过不等于可跳过原页核对。

## 来源

- API文档：https://doc2x.noedgeai.com/help/zh-cn/api/doc2x-api-v3-json.html#response-example
- 创建任务与保存结果：https://doc2x.noedgeai.com/help/zh-cn/api/doc2x-api-v2-pdf-interface.html#preupload
- 原网页演示JSON：https://doc2x.noedgeai.com/samples/data/parse-gaokao.json
- 原PDF：https://doc2x.noedgeai.com/samples/real-parse.pdf

两种JSON来源不同，不用本包声称API已经对这份试卷返回4个布局块。`acceptance-checklist.csv` 是待填写的验收清单，不是评测结果；能力、配额、保存期限与计费以当前开放平台为准。