GCP Vision と Python による画像からのテキスト抽出の自動化
小さな Python コマンドラインプログラムで、スキャンしたページやスクリーンショットをテキストに変換します。この例では、ローカルの JPEG または PNG を一つ Google Cloud Vision に送信し、認識したテキスト、または別のプログラムで利用するための JSON サマリーを出力します。Cloud Storage バケットは不要です。
前提条件
- Python のダウンロードページからインストールした Python 3.14.7、またはそれ以降の Python 3.14 メンテナンスリリース
- Google Cloud CLI と、課金および Cloud Vision API が有効な Google Cloud プロジェクト
- Google Cloud への送信が許可されているローカルの JPEG または PNG
以下のシェルコマンドは macOS の Bash を使用します。この手順は Python 3.14.7 と
google-cloud-vision 3.16.0 でテスト済みです。この例専用のディレクトリでターミナルを開き、プログラムと画像をそこに保存してください。仮想環境を作成する前に、必要なコマンドが実行できることを確認します。
python3.14 --version && gcloud --version
クラウドプロジェクトの設定
Google Cloud Console でプロジェクトを選択し、課金が有効であることを確認して、Cloud Vision API を有効にします。プロジェクト ID を控えてください。別の担当者がプロジェクトを管理している場合は、これらの設定とアカウントへの権限付与を依頼してください。詳しくは Google の Vision セットアップガイドを参照してください。
開発環境の設定
ローカル開発では Application Default Credentials(ADC)を使用します。以下の PROJECT_ID をプロジェクト ID に置き換え、そのプロジェクトの使用権限があるアカウントでログインしてください。
gcloud auth application-default login &&
gcloud auth application-default set-quota-project PROJECT_ID
ADC の認証情報は、CLI の通常のログインとは別のものです。割り当てプロジェクトの設定コマンドには、Service Usage Consumer ロールで付与される
serviceusage.services.use が必要です。既存の GOOGLE_APPLICATION_CREDENTIALS 設定はローカルの ADC ファイルより優先されます。意図した認証情報を指していることを確認するか、ローカルのログインを使う前に、このターミナルからその上書き設定を削除してください。Google の認証ガイドでは、ログインと割り当てプロジェクトの両方の要件を説明しています。プログラム内に認証情報を記述しないでください。
本番環境の認証
将来デプロイする際は、Google Cloud ではアタッチされたサービスアカウントを、それ以外の環境では Workload Identity Federation を優先してください。どちらもサービスアカウントキーをダウンロードせずに ADC を利用できます。この手順ではローカルのユーザー認証情報を使用し、本番デプロイの設定は行いません。
Python クライアントのインストール
新しい仮想環境を作成し、バージョンを固定したクライアントをインストールします。その環境のインタープリターを直接呼び出すことで、シェルでの有効化を省き、このディレクトリ内にインストール先を限定します。
test ! -e .venv && test ! -L .venv &&
python3.14 -m venv .venv &&
./.venv/bin/python -m pip install 'google-cloud-vision==3.16.0'
最初の確認処理は、既存の .venv の再利用を拒否します。環境の作成後にインストールが失敗した場合は、ファイルを残したまま、インストールコマンドだけを再実行してください。
./.venv/bin/python -m pip install 'google-cloud-vision==3.16.0'
仮想環境の作成自体に失敗した場合は、新しい例用ディレクトリを選んでから設定をやり直してください。以降のコマンドには、ターミナルで別の環境が有効になっていても、.venv インタープリターを使用します。
OCR プログラムの保存
ブロック全体を extract_text.py として保存してください。このプログラムは、文字が密集したページのテキストに document_text_detection を使用し、full_text_annotation.text を読み取ります。詳しくは Google のドキュメントテキスト検出チュートリアルを参照してください。REST トランスポートでも、公式 Python クライアントと ADC を使用します。
import argparse
import json
from pathlib import Path
import sys
import time
from google.api_core.exceptions import ServiceUnavailable
from google.cloud import vision
class OcrError(RuntimeError):
"""A safe diagnostic generated by this program."""
def process_ocr_text(raw_text: str) -> dict:
lines = raw_text.splitlines()
return {
'full_text': raw_text,
'lines': lines,
'line_count': len(lines),
'word_count': len(raw_text.split()),
'cleaned_text': ' '.join(raw_text.split()),
}
def safe_ocr_call(client, image):
for attempt in range(3):
try:
response = client.document_text_detection(
image=image, retry=None, timeout=30.0
)
except ServiceUnavailable:
if attempt == 2:
raise
time.sleep(2 ** attempt)
continue
if response.error.code:
raise OcrError(f'Vision OCR failed (code {response.error.code}).')
return response
def extract_text(image_path: str) -> str:
path = Path(image_path)
if path.suffix.lower() not in ('.jpg', '.jpeg', '.png'):
raise OcrError('Use one JPEG or PNG image, not a PDF or TIFF.')
content = path.read_bytes()
if not content.startswith((b'\x89PNG\r\n\x1a\n', b'\xff\xd8\xff')):
raise OcrError('Input does not have a JPEG or PNG signature.')
with vision.ImageAnnotatorClient(transport='rest') as client:
response = safe_ocr_call(client, vision.Image(content=content))
return response.full_text_annotation.text
def main() -> int:
parser = argparse.ArgumentParser(description='Extract text from one JPEG or PNG.')
parser.add_argument('image_path')
parser.add_argument('--json', action='store_true', help='Print a JSON summary.')
args = parser.parse_args()
try:
text = extract_text(args.image_path)
except OcrError as error:
print(error, file=sys.stderr)
return 1
except Exception as error:
print(f'OCR failed ({type(error).__name__}).', file=sys.stderr)
return 1
if args.json:
print(json.dumps(process_ocr_text(text), ensure_ascii=False))
else:
sys.stdout.write(text)
if not text:
print('No text detected.', file=sys.stderr)
return 0
if __name__ == '__main__':
sys.exit(main())
シグネチャの確認により、リクエスト前に空のファイルや明らかな形式の誤りを検出します。画像を完全にデコードまたは検証するわけではありません。ヘッダー以降の破損については、Vision が拒否する場合も、復旧できる場合もあります。結果を利用する前に、元の画像を確認し、認識されたテキストと照合してください。
画像での実行
鮮明なスキャン画像またはスクリーンショットを、プログラムと同じディレクトリに
invoice.png として保存し、次のコマンドを実行します。
./.venv/bin/python extract_text.py invoice.png
認識されたテキストは、元の改行を保持したまま標準出力に出力されます。リクエストが成功してもテキストが認識されなかった場合は、終了ステータスは 0 となり、標準出力は空のまま、標準エラー出力に No text detected. が出力されます。これは認識結果であり、画像に文字がないことの証明ではありません。エラーの場合はステータス 1 で終了し、抽出テキストは出力しません。コマンドライン引数が不正な場合はステータス 2 で終了します。
連携する正規化処理の例を試すには、同じプログラムに
--json を指定して実行します。
./.venv/bin/python extract_text.py --json invoice.png
full_text は OCR レスポンスを保持します。lines、line_count、word_count はそのテキストの情報を表します。cleaned_text は検索用に空白をまとめます。これらのフィールドは、請求書の合計金額、表、文書の段落を識別するものではありません。結果が空の場合は、空文字列、空の lines 配列、0 のカウントが生成されます。
抽出失敗の診断
このプログラムはクライアントの自動再試行を無効にし、OCR メソッドの呼び出しを最大 3 回に制限します。再試行するのは ServiceUnavailable の場合のみで、待機時間は 1 秒と 2 秒です。各呼び出しのリクエストタイムアウトは 30 秒です。これは、認証や再試行の待機時間を含めたコマンド全体の制限時間ではありません。権限エラー、割り当ての枯渇、レスポンスに埋め込まれた画像ごとのエラーは再試行しません。
FileNotFoundError:画像のファイル名とターミナルの現在のディレクトリを確認してください。DefaultCredentialsError:ADC のログインを完了するか、意図しない認証情報の上書き設定を修正してください。Forbidden、PermissionDenied、または埋め込みコード 7:プロジェクトへのアクセス権、API の有効化、ADC の割り当てプロジェクトを確認してください。同じリクエストを繰り返しても権限は付与されません。TooManyRequests、ResourceExhausted、または埋め込みコード 8:手動で再試行する前に、プロジェクトの割り当てを確認してください。- 埋め込みコード 3 または
InvalidArgument:入力が読み取り可能で破損のない JPEG または PNG であることを確認してください。
サードパーティーのエラーメッセージにはリクエストの詳細が含まれる場合があるため、出力しません。埋め込まれた数値コードと例外名により、詳細を公開せずに次の確認箇所を特定できます。
画像ワークフローの制約
このプログラムは一つの画像全体をメモリに読み込み、クラウドサービスに送信します。まず小さなテスト画像を使用し、対応形式とサイズ制限を確認してください。大きなワークロードを実行する前に、Vision の料金も確認してください。バッチ処理はリクエストのオーバーヘッドを削減できますが、画像ごとの機能利用料金はなくなりません。
複数ページの PDF または TIFF には、ファイル名を変更したり、この画像用 CLI に渡したりせず、ファイルアノテーション API を使用してください。自動言語検出や OCR でもテキストを誤認識する場合があります。実際に使用するスキャン画像、文字体系、レイアウトで評価してください。鮮明な合成サンプルでの結果だけでは、レシート、手書き文字、本番の文書での精度は確認できません。
