Vision API Pythonクライアントライブラリ v2.0.0リリース（BREAKING CHANGES 有り）

-
Vision API Pythonクライアントライブラリの新バージョン（2.0.0）が2020年9月29日付でリリースされたようです。これは以前のバージョンとの互換性を破る変更（BREAKING CHANGES）を含んでいるため、取り急ぎ現時点での影響と回避策を書きます。

【目次】

［１］v2.0.0リリースによる影響の概要

Vision API Pythonクライアントライブラリの新バージョン（2.0.0）が2020年9月29日付でリリースされたようです。

これにより、バージョン指定なしで、クライアントライブラリをインストール（pip install google-cloud-vision ）すると、v2.0.0がインストールされるようになっています。
また、GitHubのソースコードも最新版に置き換わっています。

（注意）
  • ここでいうv2.0.0とはgoogle-cloud-visionパッケージのリリースバージョンです。パッケージ内のvision_v1、vision_v1p1beta1、vision_v1p2beta1などのバージョン名に変更はありません。

今回のバージョンアップ（v2.0.0）は、Pythonクライアントライブラリの変更であり、Vision APIのモデルの変更ではありませんので、検出結果などが変わるものではありません。
しかしながら、以前のバージョンとの互換性を破る変更（BREAKING CHANGES）を含んでいるため、既存のプログラムをv2.0.0で動かす場合は注意が必要です。

v2.0.0の変更内容は以下を参照してください。

既にgoogle-cloud-visionのv1.0.0がインストールされた運用環境や開発環境については、喫緊の問題ではないと思いますが、Colaboratoryのように毎回新しく仮想マシンが割り当てられるような環境など、最新版のクライアントライブラリをインストールして既存のコードを動かす場合は、プログラムエラーになって動作しない可能性があります。

また、現時点（2020/10/05）では、Googleの公式ドキュメント（ガイド）にあるサンプルコードの一部はv2.0.0に対応していません。
このため、公式ガイドにしたがって「pip install --upgrade google-cloud-vision」でインストールするとv2.0.0がインストールされますが、その状態で、v2.0.0に対応していないサンプルコードを実行するとエラーで動きません。これは少々混乱するかもしれません。

本ブログの過去記事のコードや説明はv1.0.0をもとにしているため、その一部はv2.0.0には対応しておらず、v2.0.0環境ではエラーになったり、実態とは異なる説明になっている部分があります。

以下に、パッケージの内部的な変更点には触れず、v1.0.0用のコードをv2.0.0に対応させるための修正ポイントを中心に、v1.0.0とv2.0.0の違いの要点を考えてみました。
  • Python >= 3.6。（Python 2.7はサポート対象外）
  • リファレンス（https://googleapis.dev/python/vision/2.0.0/vision_v1/services.html ）には記載がなくなっているようですが、v1.0.0と同様に、annotate_imageと特徴タイプ固有のメソッド（face_detection、text_detectionなど）も利用できます。
  • 必須パラメータのみ使用して特徴タイプ固有のメソッド（face_detection、text_detectionなど）を利用している場合は、変更なく利用できると思います。
  • enums と types サブモジュールが削除されています。
    • 例えば、v1.0.0では、vision.types.Image を v2.0.0では、vision.Image として利用します。同様に、vision.enums.Feature.Typeはvision.Feature.Typeとします。
  • メッセージのフィールド名がtypeの場合は、v2.0.0ではフィールド名の後ろにアンダーバーを付けてtype_とします。
    • Feature.type　＝＞　Feature.type_
    • Landmark.type　＝＞　Landmark.type_
    • DetectedBreak.type　＝＞　DetectedBreak.type_
  • batch_annotate_images、batch_annotate_files、async_batch_annotate_images、async_batch_annotate_filesの引数が変更になっています。
    • v2.0.0では、第一引数はRPC（.proto）の定義と同じ型である、BatchAnnotateImagesRequest 、BatchAnnotateFilesRequest 、AsyncBatchAnnotateImagesRequest 、AsyncBatchAnnotateFilesRequest に変更となっています。それ以降の引数はキーワード引数で指定するようになっています。
    • v1.0.0版の第一引数で指定していたリクエスト内容は、v2.0.0では第1引数ではなく、キーワード引数として、requests=値の形式で指定します。

（追記：2021/03/13）
google.protobuf.json_format を利用して、レスポンスデータとJSONやディクショナリを相互変換する方法を、記事『Vision API Pythonクライアントライブラリを少し深堀りする（BatchAnnotateImages編）』で書きました。 
しかしながら、この方法は v1.0.0では動作しますが、v2.0.0以降では動作しません。


以下では具体的な影響の例と取り急ぎの対応について書きます。

［２］影響の具体例

（１）annotate_imageの例

以下のコードは、最新版（v2.0.0）ライブラリリファレンス（https://googleapis.dev/python/vision/latest/index.html）のExample Usageにあるコードです。（v1.0.0のリファレンスと同じサンプルコードだと思います。）
from google.cloud import vision

client = vision.ImageAnnotatorClient()
response = client.annotate_image({
  'image': {'source': {'image_uri': 'gs://my-test-bucket/image.jpg'}},
  'features': [{'type': vision.enums.Feature.Type.FACE_DETECTION}],
})

このコードを元にバージョンの違いによる影響をみてみます。
なお、実際に動作を確認する場合は、image_ruiの値を実在する値、例えば、Googleのガイドのサンプルデータ（gs://cloud-samples-data/vision/face/faces.jpeg）などに変更して実行する必要があります。

①v1.0.0の場合

以下の手順で、v1.0.0を指定してgoogle-cloud-visionをインストールします。
pip install google-cloud-vision==1.0.0

そして、環境変数GOOGLE_APPLICATION_CREDENTIALSを設定した状態で、上記コードを実行すると、エラーなく実行できます。

②v2.0.0の場合

公式ガイドにある手順通り、google-cloud-visionをインストールします。(v2.0.0がインストールされます)
pip install --upgrade google-cloud-vision

そして、環境変数GOOGLE_APPLICATION_CREDENTIALSを設定した状態で上記コードを実行します。

すると、まず以下のエラーが表示され、停止します。
AttributeError: module 'google.cloud.vision' has no attribute 'enums'

v2.0.0ではvision.enumsとvision.types以下で参照していた内容は、vision直下で参照するように変更されています。これにより上記コードは、vision.Feature.Type.FACE_DETECTIONに変更する必要があります。

これを修正して実行しても、次は、以下のエラーが表示されて停止します。
ValueError: Protocol message Feature has no "type" field.

これは、フィールド名’type’を’type_’に変更する必要があります。

結果として、v2.0.0で動作するコードは以下のようになります。
from google.cloud import vision

client = vision.ImageAnnotatorClient()
response = client.annotate_image({
  'image': {'source': {'image_uri': 'gs://my-test-bucket/image.jpg'}},
  'features': [{'type_': vision.Feature.Type.FACE_DETECTION}],
})

（２）batch_annotate_filesの例


①vision.typesで表現

v1.0.0のコード
req = vision.types.AnnotateFileRequest(
    input_config = vision.types.InputConfig(content = binary_content,mime_type = 'application/pdf'),
    features = [vision.types.Feature(type = vision.enums.Feature.Type.DOCUMENT_TEXT_DETECTION)],
    pages = [1, 2, -1]
)

# batch_annotate_files呼び出し。リクエストがリストであることに注意。
batch_response = client.batch_annotate_files([req])

v2.0.0では、vision.typesとvision.enumsのtypesとenumsを削除し、Featureのtypeフィールドをtype_に変更します。また、batch_annotate_filesの第1引数をパラメータ引数（requests=）に変更します。
req = vision.AnnotateFileRequest(
    input_config = vision.InputConfig(content = binary_content,mime_type = 'application/pdf'),
    features = [vision.Feature(type_ = vision.Feature.Type.DOCUMENT_TEXT_DETECTION)],
    pages = [1, 2, -1]
)

# batch_annotate_files呼び出し。リクエストがリストであることに注意。
batch_response = client.batch_annotate_files(requests=[req])

②ディクショナリで表現

v1.0.0の例
req = {
    'input_config': {'content': binary_content, 'mime_type': 'application/pdf'},
    'features': [{'type': vision.enums.Feature.Type.DOCUMENT_TEXT_DETECTION}],
    'pages': [1, 2, -1]
}

# batch_annotate_files呼び出し。リクエストがリストであることに注意。
batch_response = client.batch_annotate_files([req])

v2.0.0では、vision.enumsのenumsを削除し、Featureオブジェクトのtypeをtype_に変更します。また、batch_annotate_filesの第1引数をパラメータ引数（requests=）に変更します。
req = {
    'input_config': {'content': binary_content, 'mime_type': 'application/pdf'},
    'features': [{'type_': vision.Feature.Type.DOCUMENT_TEXT_DETECTION}],
    'pages': [1, 2, -1]
}

# batch_annotate_files呼び出し。リクエストがリストであることに注意。
batch_response = client.batch_annotate_files(requests=[req])

［３］対策例

これから新しくコードを書き始める場合と、既にv1.0.0で作成したコードがある場合に分けて、取り急ぎの対策例（回避策など）を書いてみます。

（１）新しくコードを書き始める場合

一般的には、わざわざ古いバージョンのライブラリを使う必要はないように思いますので、公式ガイドの手順に沿ってv2.0.0で作成するのが良いと思います。

ただし、現時点（2020/10/15）では、公式ガイドのサンプルコードがv2.0.0用に更新されていないようですので、上記のように動作しないコード例もあります。このあたりに注意が必要かと思います。
（text_detection、face_detectionのように、enumsやtypesをラップしている関数を利用する場合は互換性の問題は無いかもしれません。）

なお、公式ガイドのサンプルのv2.0.0対応版は、GitHubの（https://github.com/googleapis/python-vision/tree/release-v2.0.0/samples/snippets）で公開されているようです。

（２）既にv1.0.0のコードがある場合

今すぐv2.0.0にバージョンアップする必要がない場合は、以下のように明示的にv1.0.0をインストールして利用するのがよいと思います。
pip install google-cloud-vision==1.0.0

v1.0.0のリファレンスマニュアルは、以下のURLで参照できます。

なお、既存のコードをv2.0.0に対応させる場合は、v2.0.0へマイグレーションするためのドキュメントが公開されています。


コメント

コメントを投稿

このブログの人気の投稿

VirtualBoxのスナップショット機能

-
イメージ
本記事では、VirtualBoxのスナップショットがもつ情報と使い方について見ていきます。   【目次】 ［１］はじめに ［２］スナップショットの保存内容 ［３］VirtualBox マネージャのスナップショット画面 ［４］スナップショットの作成 ［５］スナップショットのプロパティの表示と編集 ［６］スナップショットの復元 ［７］「最新の状態」とスナップショットの履歴 ［８］スナップショットの削除 ［９］エクスポート/インポートの注意事項 ［１］はじめに 仮想マシンを利用するの利点の一つは、ある時点の仮想マシンの状態を保存し（スナップショットを作成）、後に、保存した状態を容易に復元することができることかと思います。 例えば、開発環境のある状態を保存しておき、ライブラリのバージョンアップを実行してみて、その結果が悪ければバージョンアップ前の状態に戻す、ということが簡単にできます。 スナップショットは、実行中の仮想マシンの状態（メモリ等の状態）も保存できますので、エディタで編集中の状態まで保存、復元できたりします。（少し言い過ぎですが、ワープロ編集中にでUndoやRedoを利用するのと同じような感覚でしょうか。） また、スナップショットのデータは、仮想マシンと統合管理されているため、保存、復元操作が非常に簡単です。 （一方で、スナップショットは、一般に言うバックアップとは少し目的が異なるため、バックアップの代替えになるとは限らない点に注意が必要です。） 本記事ではVirtualBoxのスナップショットについて見ていきます。 （参考） Vagrantをお使いの場合は、記事『 Vagrantのスナップショット機能とVirtualBox 』も参考にして下さい。 ［２］スナップショットの保存内容 VirtualBoxのスナップショットについては、ユーザマニュアルに記載があります。 User Manual 1.10. Snapshots（ https://www.virtualbox.org/manual/ch01.html#snapshots ） 詳しくは上記ドキュメントをご参照頂くとして、スナップショットは仮想マシンの構成、ディスクとメモリの内容を保存しています。 ハードウェア構成を含む仮想マシン設定の完全なコピーを持っています。 これにより、例えば、ある時点
続きを読む

Google Document AIで画像から表形式データを抽出する（Vision API OCRとの違い）

-
イメージ
本記事では、GoogleのDocument AIを利用して、表形式（テーブル形式）で記載された画像から、表形式の情報を抽出してみます。また、GoogleのVision API OCRを利用した場合との違いについてもみておきます。 【目次】 ［１］はじめに ［２］Document AIとVision API（OCR）の違い ［３］テスト用の表形式画像 （１）英語版表形式画像（shoppinglist.jpg） （２）日本語版表形式画像（okaimonolist.jpg） （３）PDFファイルへの変換 ［４］Vision APIによる表形式画像の認識 （１）実験方法 （２）英語版表形式画像の認識結果 （３）日本語版表形式画像の認識結果 ［５］Document AIによる表形式画像の認識 （１）実験方法 （２）英語版表形式画像の認識結果 （３）日本語版表形式画像の認識結果 ［６］最後に ［１］はじめに Google Vision APIを利用すると、画像から文字を抽出（OCR）できます。 https://cloud.google.com/vision/ Vision APIは、本などの文章の画像や、風景の画像から文字を抽出するといったケースでは、かなりいい感じで文字を抽出してくれます。文章が書かれているような画像の場合は、画像から文字を抽出するだけでなく、大雑把に文書の構造も得ることができます。 しかし、Vision API OCRでは期待した抽出が難しい例もあります。 例えば、下図のような、よくある表形式で書かれた書類です。 文章の画像は、隣接する文字の塊を抽出するだけでも、期待した文章が抽出できることが多いと思います。 しかし、上図のような表形式の書類は、隣接した文字の塊を抽出するだけでは利用価値が低い場合が多く、表形式のデータとして認識する必要があります。 表形式の書類は、人間が見れば、表組の意味を理解して要点を把握しやすい表現だと思います。例えば、「2021/2/2のお菓子の値段は300円であり、同日のお弁当は1,000円」云々と文章でつらつら書かれるより分かりやすいです。 一方で、これを機械的に認識しようとすると、単語レベルの文字列が散らばって配置されているレイアウトのようにも見えて、解釈が難しい場合が多いです。実際、汎用目的の機械的な表の認識を行
続きを読む

Ubuntu/Colab環境でPDFファイルのページを画像化する（pdf2image、pdftoppm、pdftocairo）

-
本記事では、UbuntuやGoogle Colaboratory環境で、オープンソースライブラリのPoppler（poppler-utilsに含まれるpdftoppm、pdftocairo）あるいはPythonライブラリのpdf2imageを利用して、PDFファイルのページをJPEGなどの画像ファイルに変換する方法を見ていきます。 【目次】 ［１］PDFファイルを画像に変換したいとき？ ［２］PDFファイル扱うオープンソースライブラリ （参考）ページの画像化と情報抽出について ［３］コマンドラインからの利用：poppler-utils （１）poppler-utils （２）インストール （３）pdftoppmの利用例 （４）pdftocairoの利用例 ［４］Pythonからの利用：pdf2image （１）pdf2image （２）インストール （３）最も簡単な使い方 （４）メモリを節約する方法（output_folderを利用する方法） （５）メモリを節約する方法（fmtを利用する方法） （６）サムネイルの作成サンプル （７）ページを指定して変換する方法（first_page, last_page） （８）大量ページの変換速度を上げる方法（thread_count） （９）解像度（dpi） （１０）pdftocairo/pdftoppmの画像変換結果を直接利用する（use_pdftocairo） （参考）pdfinfo_from_path関数 ［１］PDFファイルを画像に変換したいとき？ PDF（Portable Document Format）ファイルは広く使われている電子文書です。 PDFファイルは、ブラウザでも表示できますし、無料のAdobe Acrobat Readerをインストールして表示することもできます。 しかし、こういったツールでファイル内容を表示するだけではなく、PDFファイル内のページをJPEGなどの画像ファイルに変換して利用したい場合もあります。 例えば、システム開発において、Webサイトやアプリ内で、PDFファイルの概要をサムネイル表示したいとか、PDFファイルをダウンロードさせたり、ブラウザの別タブでPDFファイルを表示するのではなく、（導線が途切れないように）ページを移動することなく内容を見てもらいたい場合など、いろいろ
続きを読む