s3-ocr

用于对存储在S3中的文件运行OCR的工具

关于此项目的背景： s3-ocr：从S3存储桶中的PDF文件中提取文本

安装

使用pip安装此工具

pip install s3-ocr

演示

您可以在使用Datasette托管的一个示例表中查看运行此工具对互联网档案馆中的三个PDF文件（一个、两个、三个）的结果

在存储桶中对PDF文件启动OCR

start命令接受一个键列表并将它们提交给Textract进行OCR处理。

您需要使用环境变量、家目录中的凭据文件或使用s3-credentials生成的JSON或INI文件配置AWS。

您可以这样启动该过程

s3-ocr start name-of-your-bucket my-pdf-file.pdf

您指定的路径应该是存储桶内的路径。如果您在存储桶内部的文件夹中存储了PDF文件，则它应该看起来像这样

s3-ocr start name-of-your-bucket path/to/one.pdf path/to/two.pdf

OCR可能需要一些时间。OCR的结果将存储在您的存储桶中的textract-output目录。

要处理存储桶中所有扩展名为.pdf的文件，请使用--all

s3-ocr start name-of-bucket --all

要处理特定文件夹内所有扩展名为.pdf的文件，请使用--prefix

s3-ocr start name-of-bucket --prefix path/to/folder

s3-ocr start --help

Usage: s3-ocr start [OPTIONS] BUCKET [KEYS]...

  Start OCR tasks for PDF files in an S3 bucket

      s3-ocr start name-of-bucket path/to/one.pdf path/to/two.pdf

  To process every file with a .pdf extension:

      s3-ocr start name-of-bucket --all

  To process every .pdf in the PUBLIC/ folder:

      s3-ocr start name-of-bucket --prefix PUBLIC/

Options:
  --all                 Process all PDF files in the bucket
  --prefix TEXT         Process all PDF files within this prefix
  --dry-run             Show what this would do, but don't actually do it
  --no-retry            Don't retry failed requests
  --access-key TEXT     AWS access key ID
  --secret-key TEXT     AWS secret access key
  --session-token TEXT  AWS session token
  --endpoint-url TEXT   Custom endpoint URL
  -a, --auth FILENAME   Path to JSON/INI file containing credentials
  --help                Show this message and exit.

检查状态

s3-ocr status <bucket-name>命令显示了任务进度的粗略指示

% s3-ocr status sfms-history
153 complete out of 532 jobs

它根据.s3-ocr.json文件比较已提交的工作，与写入到textract-output/文件夹的工作进行比较。

s3-ocr status --help

Usage: s3-ocr status [OPTIONS] BUCKET

  Show status of OCR jobs for a bucket

Options:
  --access-key ...

检查工作

s3-ocr inspect-job <job_id>命令可用于检查特定作业ID的状态

% s3-ocr inspect-job b267282745685226339b7e0d4366c4ff6887b7e293ed4b304dc8bb8b991c7864
{
  "DocumentMetadata": {
    "Pages": 583
  },
  "JobStatus": "SUCCEEDED",
  "DetectDocumentTextModelVersion": "1.0"
}

s3-ocr inspect-job --help

Usage: s3-ocr inspect-job [OPTIONS] JOB_ID

  Show the current status of an OCR job

      s3-ocr inspect-job <job_id>

Options:
  --access-key ...

获取结果

一旦OCR任务完成，您可以使用fetch命令下载生成的JSON文件

s3-ocr fetch name-of-bucket path/to/file.pdf

这些文件将保存在当前目录，名称如下所示

• 4d9b5cf580e761fdb16fd24edce14737ebc562972526ef6617554adfa11d6038-1.json
• 4d9b5cf580e761fdb16fd24edce14737ebc562972526ef6617554adfa11d6038-2.json

文件的数量将根据文档的长度而变化。

如果您不希望有单独的文件，可以使用-c/--combine选项将它们合并在一起

s3-ocr fetch name-of-bucket path/to/file.pdf --combine output.json

生成的output.json文件将包含类似以下内容的数据

{
  "Blocks": [
    {
      "BlockType": "PAGE",
      "Geometry": {...}
      "Page": 1,
      ...
    },
    {
      "BlockType": "LINE",
      "Page": 1,
      ...
      "Text": "Barry",
    },

s3-ocr fetch --help

Usage: s3-ocr fetch [OPTIONS] BUCKET KEY

  Fetch the OCR results for a specified file

      s3-ocr fetch name-of-bucket path/to/key.pdf

  This will save files in the current directory called things like

      a806e67e504fc15f...48314e-1.json     a806e67e504fc15f...48314e-2.json

  To combine these together into a single JSON file with a specified name, use:

      s3-ocr fetch name-of-bucket path/to/key.pdf --combine output.json

  Use "--output -" to print the combined JSON to standard output instead.

Options:
  -c, --combine FILENAME  Write combined JSON to file
  --access-key ...

获取页面文本

如果您不想直接处理JSON，可以使用text命令仅检索从PDF中提取的文本

s3-ocr text name-of-bucket path/to/file.pdf

这将输出纯文本到标准输出。

要将它们保存到文件，请使用以下命令

s3-ocr text name-of-bucket path/to/file.pdf > text.txt

单独的页面将以三个换行符分隔。要使用----水平分隔符而不是换行符进行分隔，请添加--divider

s3-ocr text name-of-bucket path/to/file.pdf --divider

s3-ocr text --help

Usage: s3-ocr text [OPTIONS] BUCKET KEY

  Retrieve the text from an OCRd PDF file

      s3-ocr text name-of-bucket path/to/key.pdf

Options:
  --divider             Add ---- between pages
  --access-key ...

避免处理重复项

如果您在S3存储桶内移动文件，s3-ocr可能会丢失跟踪哪些文件已被处理。这可能导致您运行s3-ocr start对这些新文件时产生额外的处理费用。

s3-ocr dedupe命令通过扫描存储桶中具有新名称但先前已处理过的文件来解决此问题。它是通过查看每个文件的ETag来完成的，该ETag代表文件内容的MD5哈希。

该命令将为每个检测到的重复项写入新的.s3ocr.json文件。这将避免在您运行s3-ocr start时对这些重复项进行第二次OCR处理。

s3-ocr dedupe name-of-bucket

添加--dry-run以预览将对存储桶进行的更改。

s3-ocr dedupe --help

Usage: s3-ocr dedupe [OPTIONS] BUCKET

  Scan every file in the bucket checking for duplicates - files that have not
  yet been OCRd but that have the same contents (based on ETag) as a file that
  HAS been OCRd.

      s3-ocr dedupe name-of-bucket

Options:
  --dry-run             Show output without writing anything to S3
  --access-key ...

对存储桶所做的更改

为了跟踪哪些文件已提交以进行处理，s3-ocr将为它添加到OCR队列的每个文件创建一个JSON文件。

此文件将命名为

path-to-file/name-of-file.pdf.s3-ocr.json

这些JSON文件中的每个都包含类似以下数据

{
  "job_id": "a34eb4e8dc7e70aa9668f7272aa403e85997364199a654422340bc5ada43affe",
  "etag": "\"b0c77472e15500347ebf46032a454e8e\""
}

记录的job_id可以在以后用于将文件与其在textract-output/中的OCR任务结果关联起来。

etag是在提交时S3对象的ETag。这可以在以后用来确定自上次对文件运行OCR以来文件是否已更改。

这种为工具设计的方式，通过.s3-ocr.json文件跟踪已提交的作业，意味着可以安全地多次对同一存储桶运行s3-ocr start，而不会风险启动重复的OCR作业。

创建OCR结果的SQLite索引

s3-ocr index <bucket> <database_file>命令创建一个包含OCR结果的SQLite数据库，并配置SQLite全文搜索针对文本

% s3-ocr index sfms-history index.db
Fetching job details  [####################################]  100%
Populating pages table  [####################----------------]   55%  00:03:18

生成的数据库的架构如下（不包括FTS表）

CREATE TABLE [pages] (
   [path] TEXT,
   [page] INTEGER,
   [folder] TEXT,
   [text] TEXT,
   PRIMARY KEY ([path], [page])
);
CREATE TABLE [ocr_jobs] (
   [key] TEXT PRIMARY KEY,
   [job_id] TEXT,
   [etag] TEXT,
   [s3_ocr_etag] TEXT
);
CREATE TABLE [fetched_jobs] (
   [job_id] TEXT PRIMARY KEY
);

数据库设计为与Datasette一起使用。

s3-ocr index --help

Usage: s3-ocr index [OPTIONS] BUCKET DATABASE

  Create a SQLite database with OCR results for files in a bucket

Options:
  --access-key ...

开发

要为此工具做出贡献，首先检出代码。然后创建一个新的虚拟环境

cd s3-ocr
python -m venv venv
source venv/bin/activate

现在安装依赖项和测试依赖项

pip install -e '.[test]'

要运行测试

pytest

要使用最新的--help重新生成README文件

cog -r README.md