Zerox OCR

一种将文档进行 OCR（光学字符识别）处理以供 AI 摄入的极其简单的方法。毕竟，文档本质上是一种视觉呈现。包含奇怪的布局、表格、图表等。视觉模型在这里非常适用！

基本逻辑如下：

• 传入文件（PDF、DOCX、图片等）
• 将该文件转换为一系列图片
• 将每张图片发送给 GPT 并礼貌地请求 Markdown 格式
• 聚合响应结果并返回 Markdown

在此处试用托管版本：https://getomni.ai/ocr-demo 或者访问我们的完整文档：https://docs.getomni.ai/zerox

开始使用

Zerox 同时提供 Node 和 Python 包。

• Node README - npm package
• Python README - pip package

功能	Node.js	Python
PDF 处理	✓（需要 graphicsmagick）	✓（需要 poppler）
图像处理	✓	✓
OpenAI 支持	✓	✓
Azure OpenAI 支持	✓	✓
AWS Bedrock 支持	✓	✓
Google Gemini 支持	✓	✓
Vertex AI 支持	✗	✓
数据提取	✓（schema）	✗
逐页提取	✓（extractPerPage）	✗
自定义系统提示词	✗	✓（custom_system_prompt）
保持格式选项	✓（maintainFormat）	✓（maintain_format）
异步 API	✓	✓
错误处理模式	✓（errorMode）	✗
并发处理	✓（concurrency）	✓（concurrency）
临时目录管理	✓（tempDir）	✓（temp_dir）
页面选择	✓（pagesToConvertAsImages）	✓（select_pages）
方向校正	✓（correctOrientation）	✗
边缘裁剪	✓（trimEdges）	✗

Node Zerox

(Node.js SDK - 支持来自不同提供商的视觉模型，如 OpenAI、Azure OpenAI、Anthropic、AWS Bedrock、Google Gemini 等。)

安装

npm install zerox

Zerox 使用 graphicsmagick 和 ghostscript 进行 PDF 转图片的处理步骤。这些通常会自动拉取，但您可能需要手动安装。

在 Linux 上使用：

sudo apt-get update
sudo apt-get install -y graphicsmagick

使用

使用文件 URL

import { zerox } from "zerox";

const result = await zerox({
  filePath: "https://omni-demo-data.s3.amazonaws.com/test/cs101.pdf",
  credentials: {
    apiKey: process.env.OPENAI_API_KEY,
  },
});

从本地路径

import { zerox } from "zerox";
import path from "path";

const result = await zerox({
  filePath: path.resolve(__dirname, "./cs101.pdf"),
  credentials: {
    apiKey: process.env.OPENAI_API_KEY,
  },
});

参数

const result = await zerox({
  // Required
  filePath: "path/to/file",
  credentials: {
    apiKey: "your-api-key",
    // Additional provider-specific credentials as needed
  },

  // Optional
  cleanup: true, // Clear images from tmp after run
  concurrency: 10, // Number of pages to run at a time
  correctOrientation: true, // True by default, attempts to identify and correct page orientation
  directImageExtraction: false, // Extract data directly from document images instead of the markdown
  errorMode: ErrorMode.IGNORE, // ErrorMode.THROW or ErrorMode.IGNORE, defaults to ErrorMode.IGNORE
  extractionPrompt: "", // LLM instructions for extracting data from document
  extractOnly: false, // Set to true to only extract structured data using a schema
  extractPerPage, // Extract data per page instead of the entire document
  imageDensity: 300, // DPI for image conversion
  imageHeight: 2048, // Maximum height for converted images
  llmParams: {}, // Additional parameters to pass to the LLM
  maintainFormat: false, // Slower but helps maintain consistent formatting
  maxImageSize: 15, // Maximum size of images to compress, defaults to 15MB
  maxRetries: 1, // Number of retries to attempt on a failed page, defaults to 1
  maxTesseractWorkers: -1, // Maximum number of Tesseract workers. Zerox will start with a lower number and only reach maxTesseractWorkers if needed
  model: ModelOptions.OPENAI_GPT_4O, // Model to use (supports various models from different providers)
  modelProvider: ModelProvider.OPENAI, // Choose from OPENAI, BEDROCK, GOOGLE, or AZURE
  outputDir: undefined, // Save combined result.md to a file
  pagesToConvertAsImages: -1, // Page numbers to convert to image as array (e.g. `[1, 2, 3]`) or a number (e.g. `1`). Set to -1 to convert all pages
  prompt: "", // LLM instructions for processing the document
  schema: undefined, // Schema for structured data extraction
  tempDir: "/os/tmp", // Directory to use for temporary files (default: system temp directory)
  trimEdges: true, // True by default, trims pixels from all edges that contain values similar to the given background color, which defaults to that of the top-left pixel
});

maintainFormat 选项尝试通过传递前一页面的输出作为下一页面的额外上下文，以一致的格式返回 Markdown。这需要请求同步运行，因此速度要慢得多。但如果您的文档包含大量表格数据，或经常有跨页表格，则非常有价值。

请求 #1 => page_1_image
请求 #2 => page_1_markdown + page_2_image
请求 #3 => page_2_markdown + page_3_image

示例输出

{
  completionTime: 10038,
  fileName: 'invoice_36258',
  inputTokens: 25543,
  outputTokens: 210,
  pages: [
    {
      page: 1,
      content: '# INVOICE # 36258\n' +
        '**Date:** Mar 06 2012  \n' +
        '**Ship Mode:** First Class  \n' +
        '**Balance Due:** $50.10  \n' +
        '## Bill To:\n' +
        'Aaron Bergman  \n' +
        '98103, Seattle,  \n' +
        'Washington, United States  \n' +
        '## Ship To:\n' +
        'Aaron Bergman  \n' +
        '98103, Seattle,  \n' +
        'Washington, United States  \n' +
        '\n' +
        '| Item                                       | Quantity | Rate   | Amount  |\n' +
        '|--------------------------------------------|----------|--------|---------|\n' +
        "| Global Push Button Manager's Chair, Indigo | 1        | $48.71 | $48.71  |\n" +
        '| Chairs, Furniture, FUR-CH-4421             |          |        |         |\n' +
        '\n' +
        '**Subtotal:** $48.71  \n' +
        '**Discount (20%):** $9.74  \n' +
        '**Shipping:** $11.13  \n' +
        '**Total:** $50.10  \n' +
        '---\n' +
        '**Notes:**  \n' +
        'Thanks for your business!  \n' +
        '**Terms:**  \n' +
        'Order ID : CA-2012-AB10015140-40974  ',
      contentLength: 747,
    }
  ],
  extracted: null,
  summary: {
    totalPages: 1,
    ocr: {
      failed: 0,
      successful: 1,
    },
    extracted: null,
  },
}

数据提取

Zerox 支持使用模式（schema）从文档中提取结构化数据。这允许您以结构化格式从文档中拉取特定信息，而不是获取完整的 markdown 转换。

设置 extractOnly: true 并提供 schema 以提取结构化数据。该模式遵循 JSON Schema 标准。

使用 extractPerPage 按页提取数据，而不是一次性从整个文档中提取。

您还可以设置 extractionModel、extractionModelProvider 和 extractionCredentials，以便在提取时使用与 OCR 不同的模型。默认情况下，使用相同的模型。

支持的模型

Zerox 支持来自不同提供商的多种模型：

• Azure OpenAI

  • GPT-4 Vision (gpt-4o)
  • GPT-4 Vision Mini (gpt-4o-mini)
  • GPT-4.1 (gpt-4.1)
  • GPT-4.1 Mini (gpt-4.1-mini)

• OpenAI

  • GPT-4 Vision (gpt-4o)
  • GPT-4 Vision Mini (gpt-4o-mini)
  • GPT-4.1 (gpt-4.1)
  • GPT-4.1 Mini (gpt-4.1-mini)

• AWS Bedrock

  • Claude 3 Haiku (2024.03, 2024.10)
  • Claude 3 Sonnet (2024.02, 2024.06, 2024.10)
  • Claude 3 Opus (2024.02)

• Google Gemini

  • Gemini 1.5 (Flash, Flash-8B, Pro)
  • Gemini 2.0 (Flash, Flash-Lite)

import { zerox } from "zerox";
import { ModelOptions, ModelProvider } from "zerox/node-zerox/dist/types";

// OpenAI
const openaiResult = await zerox({
  filePath: "path/to/file.pdf",
  modelProvider: ModelProvider.OPENAI,
  model: ModelOptions.OPENAI_GPT_4O,
  credentials: {
    apiKey: process.env.OPENAI_API_KEY,
  },
});

// Azure OpenAI
const azureResult = await zerox({
  filePath: "path/to/file.pdf",
  modelProvider: ModelProvider.AZURE,
  model: ModelOptions.OPENAI_GPT_4O,
  credentials: {
    apiKey: process.env.AZURE_API_KEY,
    endpoint: process.env.AZURE_ENDPOINT,
  },
});

// AWS Bedrock
const bedrockResult = await zerox({
  filePath: "path/to/file.pdf",
  modelProvider: ModelProvider.BEDROCK,
  model: ModelOptions.BEDROCK_CLAUDE_3_SONNET_2024_10,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    region: process.env.AWS_REGION,
  },
});

// Google Gemini
const geminiResult = await zerox({
  filePath: "path/to/file.pdf",
  modelProvider: ModelProvider.GOOGLE,
  model: ModelOptions.GOOGLE_GEMINI_1_5_PRO,
  credentials: {
    apiKey: process.env.GEMINI_API_KEY,
  },
});

Python Zerox

(Python SDK - 支持来自不同提供商的视觉模型，如 OpenAI、Azure OpenAI、Anthropic、AWS Bedrock 等。)

安装

• 在系统上安装 poppler，确保其可在路径变量中找到。请参阅 pdf2image 文档 获取各平台的安装说明。
• 安装 py-zerox:

pip install py-zerox

pyzerox.zerox 函数是一个异步 API，使用视觉模型将 OCR（光学字符识别）转换为 markdown。它处理 PDF 文件并将其转换为 markdown 格式。在使用此 API 之前，请确保设置好模型和模型提供者的环境变量。

有关设置环境和传递正确模型名称的说明，请参阅 LiteLLM 文档。

使用

from pyzerox import zerox
import os
import json
import asyncio

### Model Setup (Use only Vision Models) Refer: https://docs.litellm.ai/docs/providers ###

## placeholder for additional model kwargs which might be required for some models
kwargs = {}

## system prompt to use for the vision model
custom_system_prompt = None

# to override
# custom_system_prompt = "For the below PDF page, do something..something..." ## example

###################### Example for OpenAI ######################
model = "gpt-4o-mini" ## openai model
os.environ["OPENAI_API_KEY"] = "" ## your-api-key


###################### Example for Azure OpenAI ######################
model = "azure/gpt-4o-mini" ## "azure/<your_deployment_name>" -> format <provider>/<model>
os.environ["AZURE_API_KEY"] = "" # "your-azure-api-key"
os.environ["AZURE_API_BASE"] = "" # "https://example-endpoint.openai.azure.com"
os.environ["AZURE_API_VERSION"] = "" # "2023-05-15"


###################### Example for Gemini ######################
model = "gemini/gpt-4o-mini" ## "gemini/<gemini_model>" -> format <provider>/<model>
os.environ['GEMINI_API_KEY'] = "" # your-gemini-api-key


###################### Example for Anthropic ######################
model="claude-3-opus-20240229"
os.environ["ANTHROPIC_API_KEY"] = "" # your-anthropic-api-key

###################### Vertex ai ######################
model = "vertex_ai/gemini-1.5-flash-001" ## "vertex_ai/<model_name>" -> format <provider>/<model>
## GET CREDENTIALS
## RUN ##
# !gcloud auth application-default login - run this to add vertex credentials to your env
## OR ##
file_path = 'path/to/vertex_ai_service_account.json'

# Load the JSON file
with open(file_path, 'r') as file:
    vertex_credentials = json.load(file)

# Convert to JSON string
vertex_credentials_json = json.dumps(vertex_credentials)

vertex_credentials=vertex_credentials_json

## extra args
kwargs = {"vertex_credentials": vertex_credentials}

###################### For other providers refer: https://docs.litellm.ai/docs/providers ######################

# Define main async entrypoint
async def main():
    file_path = "https://omni-demo-data.s3.amazonaws.com/test/cs101.pdf" ## local filepath and file URL supported

    ## process only some pages or all
    select_pages = None ## None for all, but could be int or list(int) page numbers (1 indexed)

    output_dir = "./output_test" ## directory to save the consolidated markdown file
    result = await zerox(file_path=file_path, model=model, output_dir=output_dir,
                        custom_system_prompt=custom_system_prompt,select_pages=select_pages, **kwargs)
    return result


# run the main function:
result = asyncio.run(main())

# print markdown result
print(result)

参数

async def zerox(
    cleanup: bool = True,
    concurrency: int = 10,
    file_path: Optional[str] = "",
    maintain_format: bool = False,
    model: str = "gpt-4o-mini",
    output_dir: Optional[str] = None,
    temp_dir: Optional[str] = None,
    custom_system_prompt: Optional[str] = None,
    select_pages: Optional[Union[int, Iterable[int]]] = None,
    **kwargs
) -> ZeroxOutput:
  ...

参数

• cleanup (bool, 可选): 是否在处理完成后清理临时文件。默认为 True。
• concurrency (int, 可选): 要运行的并发进程数量。默认为 10。
• file_path (Optional[str], 可选): 要处理的 PDF 文件的路径。默认为空字符串。
• maintain_format (bool, 可选): 是否保留上一页的格式。默认为 False。
• model (str, 可选): 用于生成补全内容的模型。默认为 "gpt-4o-mini"。 请参考 LiteLLM 提供商 (LiteLLM Providers) 以获取正确的模型名称，因为它可能因提供商而异。
• output_dir (Optional[str], 可选): 保存 Markdown 输出的目录。默认为 None。
• temp_dir (str, 可选): 存储临时文件的目录，默认为系统临时目录中的某个命名文件夹。如果已存在，Zerox 在使用前将删除其中的内容。
• custom_system_prompt (str, 可选): 为模型使用的系统提示词，这将覆盖 Zerox 的默认系统提示词。通常不需要，除非您想要某些特定行为。默认为 None。
• select_pages (Optional[Union[int, Iterable[int]]], 可选): 要处理的页面，可以是单个页码或页码的可迭代对象。默认为 None。
• kwargs (dict, 可选): 传递给 litellm.completion 方法的额外关键字参数。 有关详细信息，请参阅 LiteLLM 文档和补全输入 (Completion Input)。

返回

• ZeroxOutput: 包含模型生成的 Markdown 内容以及一些元数据（见下文）。

示例输出 (来自 "azure/gpt-4o-mini")

注意：为了便于阅读，此文档中的输出已手动包装。

ZeroxOutput(
    completion_time=9432.975,
    file_name='cs101',
    input_tokens=36877,
    output_tokens=515,
    pages=[
        Page(
            content='| Type    | Description                          | Wrapper Class |\n' +
                    '|---------|--------------------------------------|---------------|\n' +
                    '| byte    | 8-bit signed 2s complement integer   | Byte          |\n' +
                    '| short   | 16-bit signed 2s complement integer  | Short         |\n' +
                    '| int     | 32-bit signed 2s complement integer  | Integer       |\n' +
                    '| long    | 64-bit signed 2s complement integer  | Long          |\n' +
                    '| float   | 32-bit IEEE 754 floating point number| Float         |\n' +
                    '| double  | 64-bit floating point number         | Double        |\n' +
                    '| boolean | may be set to true or false          | Boolean       |\n' +
                    '| char    | 16-bit Unicode (UTF-16) character    | Character     |\n\n' +
                    'Table 26.2.: Primitive types in Java\n\n' +
                    '### 26.3.1. Declaration & Assignment\n\n' +
                    'Java is a statically typed language meaning that all variables must be declared before you can use ' +
                    'them or refer to them. In addition, when declaring a variable, you must specify both its type and ' +
                    'its identifier. For example:\n\n' +
                    '```java\n' +
                    'int numUnits;\n' +
                    'double costPerUnit;\n' +
                    'char firstInitial;\n' +
                    'boolean isStudent;\n' +
                    '```\n\n' +
                    'Each declaration specifies the variable’s type followed by the identifier and ending with a ' +
                    'semicolon. The identifier rules are fairly standard: a name can consist of lowercase and ' +
                    'uppercase alphabetic characters, numbers, and underscores but may not begin with a numeric ' +
                    'character. We adopt the modern camelCasing naming convention for variables in our code. In ' +
                    'general, variables must be assigned a value before you can use them in an expression. You do not ' +
                    'have to immediately assign a value when you declare them (though it is good practice), but some ' +
                    'value must be assigned before they can be used or the compiler will issue an error.\n\n' +
                    'The assignment operator is a single equal sign, `=` and is a right-to-left assignment. That is, ' +
                    'the variable that we wish to assign the value to appears on the left-hand-side while the value ' +
                    '(literal, variable or expression) is on the right-hand-side. Using our variables from before, ' +
                    'we can assign them values:\n\n' +
                    '> 2 Instance variables, that is variables declared as part of an object do have default values. ' +
                    'For objects, the default is `null`, for all numeric types, zero is the default value. For the ' +
                    'boolean type, `false` is the default, and the default char value is `\\0`, the null-terminating ' +
                    'character (zero in the ASCII table).',
            content_length=2333,
            page=1
        )
    ]
)

支持的文件类型

我们结合使用 libreoffice（LibreOffice）和 graphicsmagick（GraphicsMagick）来实现文档到图像的转换。对于非图像/非 PDF（Portable Document Format）文件，我们使用 libreoffice 将该文件转换为 PDF，然后再转换为图像。

[
  "pdf", // Portable Document Format
  "doc", // Microsoft Word 97-2003
  "docx", // Microsoft Word 2007-2019
  "odt", // OpenDocument Text
  "ott", // OpenDocument Text Template
  "rtf", // Rich Text Format
  "txt", // Plain Text
  "html", // HTML Document
  "htm", // HTML Document (alternative extension)
  "xml", // XML Document
  "wps", // Microsoft Works Word Processor
  "wpd", // WordPerfect Document
  "xls", // Microsoft Excel 97-2003
  "xlsx", // Microsoft Excel 2007-2019
  "ods", // OpenDocument Spreadsheet
  "ots", // OpenDocument Spreadsheet Template
  "csv", // Comma-Separated Values
  "tsv", // Tab-Separated Values
  "ppt", // Microsoft PowerPoint 97-2003
  "pptx", // Microsoft PowerPoint 2007-2019
  "odp", // OpenDocument Presentation
  "otp", // OpenDocument Presentation Template
];

致谢

• Litellm: https://github.com/BerriAI/litellm | 此项目为我们的 Python SDK（软件开发工具包）提供支持，以兼容来自不同提供商的所有流行视觉模型。

许可证

本项目根据 MIT License（MIT 许可证）获得许可。

Zerox 快速上手指南

简介

Zerox 是一款简单的 OCR 工具，旨在将文档（PDF、DOCX、图片等）转换为 Markdown 格式，以便 AI 模型直接摄入。它擅长处理包含复杂布局、表格和图表的文档。

环境准备

Node.js 环境

Zerox 依赖 graphicsmagick 和 ghostscript 进行 PDF 转图片处理。

• Linux 用户请手动安装：

  sudo apt-get update
  sudo apt-get install -y graphicsmagick
  

• Windows/macOS 通常会自动处理，若遇到问题请查阅相关包管理器文档。

Python 环境

• 系统需安装 poppler，并确保其位于环境变量 PATH 中。
• 参考 pdf2image 安装文档 获取各平台安装说明。

API 密钥

• 准备支持视觉模型的大厂 API 密钥（如 OpenAI, Azure, AWS Bedrock 等）。
• 设置对应的环境变量（例如 OPENAI_API_KEY）。

安装步骤

Node.js

npm install zerox

Python

pip install py-zerox

基本使用

Node.js 示例

支持传入本地文件路径或远程 URL，以下为使用 OpenAI 模型的极简示例：

import { zerox } from "zerox";

const result = await zerox({
  filePath: "path/to/file.pdf",
  credentials: {
    apiKey: process.env.OPENAI_API_KEY,
  },
});

console.log(result.pages[0].content);

Python 示例

Python SDK 为异步 API，需配置环境变量后调用：

from pyzerox import zerox
import os
import asyncio

# 设置环境变量
os.environ["OPENAI_API_KEY"] = "your-api-key"

async def main():
    result = await zerox(
        filepath="path/to/file.pdf",
        model="gpt-4o-mini"
    )
    print(result)

asyncio.run(main())

支持的模型

Zerox 支持多种模型提供商，包括 OpenAI、Azure OpenAI、AWS Bedrock 和 Google Gemini。开发者可通过 modelProvider 和 model 参数灵活切换。