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へマイグレーションするためのドキュメントが公開されています。


コメント

コメントを投稿

このブログの人気の投稿

マイナンバーカードの電子証明書（公的個人認証サービス）にJava APIでアクセスする

-
イメージ
本記事では、マイナンバーカード（個人番号カード）に搭載されている電子証明書（公的的個人認証サービス）にJavaプログラムからアクセスする方法を見ていきます。 【目次】 ［１］はじめに ［２］事前準備（利用者クライアントソフトで動作確認） （１）ICカードリーダライタの準備 （２）利用者クライアントソフトのインストール （３）利用者クライアントソフトの動作確認 ［３］APIについて （１）仕様の構成 （２）Javaインターフェイスの仕様 （３）Javaライブラリ（クラスパス）の設定 ［４］JavaのカードAPライブラリを利用して電子証明書を取得 （１）マイナンバーカードの署名用電子証明書（JPKICryptSignJNI） （２）マイナンバーカードの利用者証明用電子証明書（ JPKICryptAuthJNI） （３）住基カードの署名用電子証明書を取得 （JPKICryptJNI） ［５］電子証明書の扱い ［６］Javaの個人認証サービス APを利用する （１）電子証明書の表示（showCertViewer） （２）署名用電子証明書から基本4情報を取得（getBasicData） （３）利用者証明書の有効性確認（confirm） （４） ICカードリーダライタに挿入されているICカードの種別を取得（getCardType） ［１］はじめに 最近何かと話題のマイナンバーカードですが、本記事では、マイナンバーカードに搭載されている電子証明書（公的的個人認証サービス）にプログラムからアクセスする方法を見ていきます。 公的個人認証サービスのリーフレットには、以下のように書かれています。 誰もが安心してオンライン手続きを行うには、他人を装って虚偽の申請を行う「なりすまし」や、第三者が送信されたデータを書き換える「改ざん」などへの対策が必要です。 公的個人認証サービスは「なりすまし」や「改ざん」を防ぎ、インターネットを通じて安全・確実な行政手続き等を行うための機能を電子証明書という形で提供しています。 電子証明書は、市区町村窓口において取得でき、個人番号カード（番号カード）内に記録されます。 電子証明書には、利用者証明用証明書と署名用電子証明書の２種類があります。電子申請・申告には、署名用電子証明書が必要です ここで個人番号カードとはマイナンバーカードのことです。そして、
続きを読む

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円」云々と文章でつらつら書かれるより分かりやすいです。 一方で、これを機械的に認識しようとすると、単語レベルの文字列が散らばって配置されているレイアウトのようにも見えて、解釈が難しい場合が多いです。実際、汎用目的の機械的な表の認識を行
続きを読む

Vagrantfileの仮想マシン設定項目とVirtualBoxの設定画面の対応

-
イメージ
 本記事では、VirtualBoxの設定画面のうち、「一般」、「システム／マザーボード」、「ディスプレイ」画面の設定項目とVagrantfileの設定項目の対応を見ていきます。 【目次】 ［１］はじめに ［２］Vagrantfileの設定方法 ［３］VirtualBoxの設定画面とVagrantfileの設定項目の対応 （１）「一般／高度」画面の項目 （２）「一般／説明」画面の項目 （３）「システム／マザーボード」画面の項目 （４）「システム／プロセッサー」画面の項目 （５）「システム／アクセラレーション」画面の項目 （６）「ディスプレイ／スクリーン」画面の項目 （７）「ディスプレイ／リモートディスプレイ」画面の項目 ［１］はじめに VirtualBoxの仮想マシンに対する設定は、「Oracle VM VritualBox マネージャー」の設定画面から行うことができます。 また、VirtualBoxをインストールすると、VBoxManageというコマンドラインツールが提供されており、コマンドラインからも仮想マシンの設定や運用を行うことができます。 Chapter 8. VBoxManage（ https://www.virtualbox.org/manual/ch08.html ） これをみると非常に細かく様々な項目をコントロールできることが分かりますが、利用する立場からみると、（英語という障害？を除いても）分量も多く、理解して利用するのは大変だと思います。 一方で、Vagrantは、一般的な設定が行われているBOXから仮想マシンを生成することと、高レベルなvagrantコマンドが用意されていることで、詳細な設定を考えなくても非常に簡単に仮想マシンを利用できるようになっています。しかし、それでも少しはカスタマイズしたい項目が残ります。 ありがたいことに、Vagrantは、VBoxManageコマンドのパラメータ（仮想マシンの設定）をVagrantfileに記述する方法を提供してくれており、仮想マシンが起動する前にその設定値を反映してくれます。これを利用すれば、Vagrantから仮想マシンの細かな設定を行うことが可能です。 私の場合、これまで仮想マシンの設定は、マニュアルに頼るというより、VritualBox マネージャーの設定画面で直観的に行っていたため、
続きを読む