Vision API クライアントライブラリの概要（Python編）
本記事では、Vision APIの使い方について、Pythonクライアントライブラリを中心に、少し深堀してみたいと思います。
【目次】
［１］Vision APIの公式ドキュメント
Vision APIの仕様に関する公式ドキュメントは、主に以下の二つはないかと思います。
- ガイド（https://cloud.google.com/vision/docs?hl=ja）
- 「画像内のテキストを検出する」のようなシナリオに応じて、Vision APIの簡単なサンプルコードとともに利用方法が説明されています。
- APIとリファレンス（https://cloud.google.com/vision/docs/apis?hl=ja）
- クライアントライブラリ、REST、RPC、gcloudコマンドのそれぞれについて、形式的な仕様の説明があります。
ガイドを見れば、シナリオに応じて直観的な利用方法は分かりますが、サンプルコードの範囲以上の情報は得られません。もう少し突っ込んだ情報を知りたい場合は、リファレンスを見ることになりますが、リファレンスを見ても、最初は分かりにくいのではないかと思います。
この理由として、ガイドは日本語だけどリファレンスは英語のみということもあるかもしれませんが、それよりも、ガイドとリファレンスでは視点が違うことが原因かな、と思いました。
Vision APIは顔認識、OCRなどの多くの特徴検出機能をサポートしており、ガイドでは検出する特徴ごとに個別に説明されています。一方で、Vision APIは、それらをまとめて処理できる包括的な仕様として構成されているため、リファレンスでは、個々の機能に対する説明や制限事項の記述が少なく、対応関係が分かりにくいように思えます。
本記事では、Vision APIクライアントライブラリを少し深堀して、ガイドにあるサンプルコードと、リファレンスの内容のギャップを少し埋めてみたいと思います。
なお、各言語毎にクライアントライブラリが用意されていますが、『Colaboratory＋GoogleドライブでVision APIの実験環境を作る』の流れから、今回はPython用のクライアントライブラリを取り上げます。
［２］PythonクライアントライブラリとRPC、REST
Vision APIは、RESTとRPCの２つの方式で利用可能です。
Googleは、RPCやRESTを直接利用するよりも、クライアントライブラリの利用を推奨しています。
（理由については、『Google Vision APIの画像認識（特にOCR）を業務システム開発の立場から検討してみる／（３）Vision API呼び出しの実装方法』も参照してください。）
Pythonのクライアントライブラリについては、ライブラリリファレンスに加えて、GitHubでソースコードが公開されています。
- リファレンス：Python Client for Google Cloud Vision（https://googleapis.dev/python/vision/latest/index.html）
- ソースコード：Python Client for Google Cloud Vision（https://github.com/googleapis/python-vision）
Pythonクライアントライブラリのソースコードを見ると、RPC呼び出しのラッパーのような形で作られていますので、以下ではRPCの仕様と対応させながら見ていきます。
RPCでは、Vision APIの特徴検出機能はImageAnnotatorサービスで提供されています。これに対応する形で、Pythonのクライアントライブラリでは、ImageAnnotatorClientクラスが定義されています。このImageAnnotatorClientクラスを通して、Vision APIの各種機能にアクセスします。
［３］ImageAnnotatorサービス概要
（１）４つのメソッド
ImageAnnotatorサービスには、
- 画像（JPEG、PNGなど）か、ファイル（PDFなど）か
- 同期（オンライン）か、非同期（オフライン）か
の２つの要素の組み合わせで、合計４つのメソッドが定義されています。
解析したいファイルの種類によってメソッドを使い分ける必要があります。さらに、各メソッドは一度に複数の画像を処理できますが、一度に処理する画像数によって、同期（オンライン）または非同期（オフライン）のメソッドを使い分ける必要があります。
各メソッドの利用条件を元にした使い分けを図にすると以下のようになります。
ただし、例えば、PDFファイルであっても、特徴検出したいページのみJPEGなどに画像化してBatchAnnotateImagesを利用するとか、逆に、複数のJPEGなどの画像ファイルをPDFファイルにまとめて一括してAsyncBatchAnnotateFilesを利用するなど、実際の利用状況に応じて様々な使い方が可能です。
なお、AsyncBatchAnnotateFilesで指定できる特徴タイプは、TEXT_DETECTIONとDOCUMENT_TEXT_DETECTIONのみです（OCR機能のみ利用できます）。それ以外を指定するとエラーとなります。
（２）画像（Image）とファイル（File）
Vision APIは、JPEG、PNG、GIF、BMP、WEBP、RAW、ICO、PDF、TIFFの画像形式ががサポートされています。
これをみると、ImageAnnotatorが提供するメソッド全てがこれらの画像形式をサポートしているように思えてしまいますが、そうではありません。画像形式が、画像かファイルかを区別してメソッドを使い分ける必要があります。
画像（Image）
- １枚の画像データを対象とする画像形式です。
- 具体的には、JPEG、PNG、GIF、BMP、WEBP、RAW、ICOです。（但し、アニメーションGIFは最初のフレームのみ）
- 画像ファイルサイズの上限は２０MBとなっています。
- BatchAnnotateImagesまたはAsyncBatchAnnotateImagesで利用できます。
ファイル（File）
- １つのファイルに複数のページやフレームを含めることが出来る画像形式です。
- 具体的には、PDF、TIFF、アニメーションGIFです。
- 複数ページ（フレーム）を含むファイルに対して、一度のリクエストで複数ページの解析が可能です。また解析する対象ページも指定できます。
- BatchAnnotateFilesまたはAsyncBatchAnnotateFilesで利用できます。
- メソッド呼び出し時は、MIMEタイプを明示する必要があります。
- PDF＝application/pdf
- GIF＝image/gif
- TIFF＝image/tiff
（３）バッチ（Batch）
基本となる処理単位は、１つの画像に対して特徴検出を行うことです。（１つの画像に対して同時に複数の特徴検出を行うことが可能です）。
Vision APIでは、一つの画像またはファイル毎にリクエストを送信して処理することが出来ます。
しかし、多くの画像を処理したい場合、１つ１つ個別にリクエストを送信するのは非効率です。そこで、Vision APIでは、複数の画像を１つのリクエストにまとめて送信して、一括処理することができるようになっています。つまり、バッチ処理要求が可能です。
ImageAnnotatorが提供する４つのメソッドは全て１度に複数の画像を処理できますが、１度に処理できる画像の数はメソッドによって異なります。（同期か非同期かを選択する必要があります。）
（４）同期（オンライン）と非同期（オフライン）
ImageAnnotatorが提供する４つのメソッドは全てバッチ処理（まとめてリクエスト）が可能ですが、メソッドごとにバッチ処理可能な数（一度に送信できる画像やファイルの数）の上限が異なります。このため、一度に処理する画像あるいはファイル数に応じて、同期（オンライン）か非同期（オフライン）のメソッドを選択する必要があります。
同期（オンライン）
- 同期では、メソッド呼び出しの戻り値として解析結果が得られます。
- 画像（JPEGなど）の同期処理：BatchAnnotateImagesメソッド
- 一度に16個の画像ファイルまで処理できます。
- ファイル（PDFなど）の同期処理：BatchAnnotateFilesメソッド
- 送信できるのは１ファイルのみですが、ファイル内の５ページ分まで指定して処理できます。
非同期（オフライン）
- 非同期では、メソッド呼び出しの戻り値は、解析結果ではなく、長時間実行オペレーション（long-running operation：LRO）の状況を表す情報（Operationクラス）となります。この情報を元に、処理終了を検知して解析結果を取得したり、実行をキャンセルしたりします。
- 非同期メソッドでは、画像あるいはファイルを直接送信するのではなく、Google Cloud Storageに保存している画像またはファイルのパスを指定して実行する必要があります、また、解析結果もGoogle Cloud Storageに記録されます。
- 画像（JPEGなど）の非同期処理：AsyncBatchAnnotateImagesメソッド
- 一度に2,000個の画像ファイルまで処理できるとされています。
- ファイル（PDFなど）の非同期処理：AsyncBatchAnnotateFilesメソッド
- 特徴タイプは、TEXT_DETECTIONとDOCUMENT_TEXT_DETECTIONのみ指定できます。それ以外はエラーとなります（顔認識などはできません）。
- 一度に2,000 ページまでのファイルを処理できるとされています。
［４］ImageAnnotatorClientのメソッド構成の概要
PythonクライアントライブラリのImageAnnotatorClientクラスには、ImageAnnotatorサービスが提供する４つのメソッドに加えて、便利なメソッドが追加されています。
ImageAnnotatorサービスの４つのメソッドに対応する、PythonクライアントライブラリのImageAnnotatorClientクラスのメソッドは、batch_annotate_images、async_batch_annotate_files、batch_annotate_files、async_batch_annotate_imagesの４つです。
これに加えて、batch_annotate_imagesについては、用途を絞って簡単に利用できるメソッドが追加されています。
annotate_imageは、batch_annotate_imagesを１画像（リクエスト）に限定したものです。ただし、１画像に対して複数の検出機能を同時に指定できる機能は維持したうえで、さらに引数となるリクエストオブジェクトに工夫が追加されています。
face_detection、text_detection等の機能毎のメソッドは、１画像（リクエスト）に対して１つの検出機能に限定して簡易に利用できるものです。実装としては、メソッド名に対応した機能を指定してannotate_imageを呼び出しています。
１つの画像ファイルに対してTEXT_DETECTIONのみ行うような場合は、text_detectionメソッドを利用するのが便利です。もし、１つの画像に対してTEXT_DETECTIONとFACE_DETECTIONを利用するなら、image_annotateメソッドを利用するのが便利です。
（2020/9/12）
続きを『Vision API Pythonクライアントライブラリを少し深堀りする（BatchAnnotateImages編）』に書きましたので、参考にしてください。
［５］その他
（１）料金
Vision APIは、１つの画像に対する特徴タイプ（顔検出、OCRなど）毎に課金されます。つまりバッチ処理の単位とは関係ありませんので、画像毎にリクエストしても、複数まとめてリクエストしても料金は同じです。
なお、Google Cloud Storage経由でVision APIを利用する場合は、Google Cloud Storageの利用料金も考慮する必要があります。
詳細は以下のサイトを参照してください。
（２）利用状況の確認方法
Vision APIの利用状況（リクエスト回数、エラー率など）は、Cloud Console（統合型 Google Cloud Platform 管理コンソール）から確認することが出来ます。
- Cloud Console（https://cloud.google.com/cloud-console?hl=ja）
確認方法
- Cloud Cosoleの左側メニューから「APIとサービス」を選択してダッシュボードを表示します。
- トラフィック、エラー、中央値のレイテンシの下にある一覧表に、Cloud Vision APIの項目を探します。ここに、リクエスト、エラー、レイテンシの概要が表示されています。
- さらに、Cloud Vision APIをクリックすると、概要ページに遷移します。左側メニューの「指標」を選択します。
- このページで、さらにメソッド毎のリクエスト、エラー、レイテンシの情報が得られます。
但し、ここでAPIレベルの指標は確認できますが、特徴タイプ毎の利用状況を確認することはできないようです。
（３）割り当てと上限
簡単なテストを行うだけなら気にする必要はないと思いますが、本格的な運用を行う場合は、プロジェクトに対するVision APIの割り当てなどの制限事項も考慮する必要があるかもしれません。
詳細は以下のサイトを参照してください。
コメント
コメントを投稿