agestic-doc 是一个功能强大的 Python 库，可从 PDF 和图像等复杂文档中提取结构化、视觉上基于的数据，使文档自动化变得简单可靠。
您是否曾经为从凌乱的 PDF、扫描的发票或长报告中提取表格、图像或重要数据而苦恼？如果是，那么您并不孤单。
从复杂的文档中手动提取数据非常耗时，普通的 OCR 工具经常会遗漏结构、位置，有时甚至会遗漏内容。
Agentic-Doc 是 LandingAI 的一个 Python 库，旨在解决这个问题。它由代理文档提取 （ADE） 提供支持，帮助我们从最复杂的文档中提取结构化的、视觉上基于的数据，并以易于使用的 JSON 和 Markdown 格式返回结果。
一、什么是代理文档提取？
ADE 是一种人工智能驱动的方法， 超越了简单的 OCR。它不仅仅是阅读文本，而是：
-
理解视觉布局： 识别表格、图片、标题、段落、图表等。
-
提供地面实况边界框： 准确显示每个数据块在页面上的位置。
-
返回结构化输出： 以分层方式组织内容，包括位置和类型信息。
文档中的数据不仅与文本有关，还与结构、表格、标题和视觉提示有关。ADE 保留所有这些上下文，这对于下游自动化、搜索和 QA 非常有用。
二、什么是 agestic-doc？
agestic-doc 是 ADE API 的 Python 包装器。它通过以下方式使开发人员更容易提取文档：
- 支持任何长度的 PDF（甚至 1000+ 页）；
- 在 API 错误或超时时自动重试；
- 从图像、URL、云存储等中提取；
- 提供可视化和调试提取的工具；
- 允许批量和并行处理以提高速度；
- 以 Markdown 和结构化 JSON 的形式返回数据
总之： 如果您想自动化和扩大文档数据提取 - 这就是适合您的工具！
2.1 流程图：
主要功能一览：
📄 所有文件类型： 支持 PDF、图像（png、jpg 等）和 URL。
📚 处理长文档： 自动并行拆分和处理大文件。
🏃 批处理和并行处理： 一次高效地从多个文件中提取。
🧩 结构化输出： 易于使用的 JSON 和 Markdown。
👁️ 可视化调试： 查看每个块的提取位置，以及边界框图像。
🔄 弹性 ： 使用智能退避逻辑重试失败的请求。
🛠️ 帮助程序： 处理大多数任务的简单 Python 函数。
⚙️ 灵活配置： 环境变量和 .env 支持批量大小、日志记录、重试。
🌐 云就绪：Google Drive、Amazon S3、本地文件夹、URL 甚至内存中的字节。
2.2 安装和配置
a）前提条件：
- Python 3.9、3.10、3.11 或 3.12；
- LandingAI Agentic AI API 密钥（从https://landing.ai/agentic-document-extraction获取）
b）安装库
pip install agentic-doc
c）设置API Key
export VISION\_AGENT\_API\_KEY=<your-api-key>
或者将其放在项目文件夹中的 .env 文件中。
三、agestic-doc基本用法
3.1 从单文档获取数据
from agentic_doc.parse import parse
result = parse("path/to/document.pdf")
print(result[0].markdown) # Extracted data in Markdown
print(result[0].chunks) # Extracted data as structured JSON
还可以从 URL 或图像进行解析：
result = parse("https://example.com/report.pdf")
result = parse("path/to/image.png")
3.2 从多文档获取数据
file_paths = ["invoice1.pdf", "invoice2.pdf"]
results = parse(file_paths)
for r in results:
print(r.markdown)
3.3 将结果保存到目录
results = parse(file_paths, result_save_dir="output/")
for r in results:
print(r.result_path) # Each result saved as JSON
3.4 使用 Pydantic 进行现场提取
您可以使用 Pydantic 模型直接提取特定字段：
from pydantic import BaseModel, Field
from agentic_doc.parse import parse
class ExtractedFields(BaseModel):
name: str = Field(description="Employee name")
amount: float = Field(description="Gross pay")
address: str = Field(description="Employee address")
results = parse("salary_slip.pdf", extraction_model=ExtractedFields)
fields = results[0].extraction
meta = results[0].extraction_metadata
print(f"Name: {fields.name}, Confidence: {meta.name.confidence}")
3.5 连接器：从云端提取
3.5.1 Google Drive 示例：
from agentic_doc.parse import parse
from agentic_doc.connectors import GoogleDriveConnectorConfig
config = GoogleDriveConnectorConfig(
client_secret_file="credentials.json",
folder_id="your-folder-id"
)
results = parse(config)
3.5.2 Amazon S3 示例：
from agentic_doc.parse import parse
from agentic_doc.connectors import S3ConnectorConfig
config = S3ConnectorConfig(
bucket_name="my-bucket",
region_name="us-east-1"
)
results = parse(config)
3.6 本地目录
from agentic_doc.parse import parse
from agentic_doc.connectors import LocalConnectorConfig
config = LocalConnectorConfig(recursive=True)
results = parse(config, connector_path="docs/")
以原始字节的方式读取
with open("document.pdf", "rb") as f:
data = f.read()
results = parse(data)
四、可视化调试和接地
保存每个提取的块的边界框图像：
from agentic_doc.parse import parse_documents
results = parse_documents(["report.pdf"], grounding_save_dir="groundings/")
# Each chunk's bounding box saved as image in the output folder
整页可视化：
from agentic_doc.utils import viz_parsed_document
images = viz_parsed_document("report.pdf", results[0], output_dir="viz/")
# Shows bounding boxes and labels on the original document image
五、错误处理和配置
Retries：API/网络错误自动重试（HTTP 408、429、502、503、504）
Backoff & Jitter： 在两次重试之间等待更长的时间，增加随机性以避免“群体”问题
Configurable： 在 .env 中设置 BATCH_SIZE、MAX_WORKERS、MAX_RETRIES 等参数
.env示例：
BATCH_SIZE=4
MAX_WORKERS=2
MAX_RETRIES=80
MAX_RETRY_WAIT_TIME=30
RETRY_LOGGING_STYLE=log_msg
六、性能
超快： 平均文档的中位处理时间为 ~8 秒（而旧 API 为 135 秒）。
可靠： 自动处理非常大的文件、多个文档和网络问题。