ラベル検出

注: Vision API では、すべての特徴に対してオフラインの非同期処理で画像のアノテーションを一括で生成できるようになりました。この非同期リクエストは 2,000 個までの画像ファイルをサポートし、Google Cloud Storage バケットに保存されるレスポンス ファイルを JSON 形式で返します。この機能の詳細については、オフラインのバッチ画像アノテーションをご覧ください。

Vision API では、画像内のエンティティについての情報を、幅広いカテゴリにわたって検出、抽出できます。

ラベルにより、一般的な物体、場所、活動、動物の種類、商品などを識別できます。ターゲットを設定したカスタムラベルが必要な場合、Cloud AutoML Vision では、カスタム機械学習モデルをトレーニングして画像を分類できます。

ラベルは英語でのみ返されます。Cloud Translate API は、英語のラベルを多数の他言語のいずれかに翻訳できます。

画像クレジット: Alex Knight、Unsplash より

たとえば、上の画像の場合は、次のラベルのリストが返されます。

説明	スコア
街路	0.872
スナップショット	0.852
町	0.848
夜	0.804
路地	0.713

モバイルアプリでこの API を使用する場合は、Firebase Machine Learning と ML Kit を試してください。これは、Cloud Vision サービスを使用するための Android および iOS 用ネイティブ SDK のほか、デバイス上の ML Vision API、カスタム ML モデルを使用したデバイス上の推論を提供します。

ラベル検出のリクエスト

GCP プロジェクトと認証の設定

Google Cloud Platform（GCP）プロジェクトとサービス アカウント認証情報を作成していない場合は、ここで作成します。手順については、このセクションを展開してください。

1. Google Cloud アカウントにログインします。Google Cloud を初めて使用する場合は、アカウントを作成して、実際のシナリオでの Google プロダクトのパフォーマンスを評価してください。新規のお客様には、ワークロードの実行、テスト、デプロイができる無料クレジット $300 分を差し上げます。
2. Cloud Console プロジェクトを設定する

   プロジェクトの設定

   クリックして、以下を行います。

   • プロジェクトを作成または選択します。
   • プロジェクトに対して Vision API を有効にします。
   • サービス アカウントを作成します。
   • JSON として秘密鍵をダウンロードします。

   これらのリソースは、いつでも Cloud Console で表示、管理できます。

3. 環境変数 GOOGLE_APPLICATION_CREDENTIALS を、サービス アカウント キーが含まれる JSON ファイルのパスに設定します。 この変数は現在のシェル セッションにのみ適用されるため、新しいセッションを開く場合は、変数を再度設定します。

   例: Linux または macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   KEY_PATH をサービス アカウント キーが含まれる JSON ファイルのパスに置き換えます。

   例:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   例: Windows

   PowerShell の場合:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   KEY_PATH をサービス アカウント キーが含まれる JSON ファイルのパスに置き換えます。

   例:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   コマンド プロンプトの場合:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   KEY_PATH をサービス アカウント キーが含まれる JSON ファイルのパスに置き換えます。

4. Cloud SDK をインストールして初期化します。

ローカル画像でラベルを検出する

Vision API は、リクエストの本文で画像ファイルのコンテンツを Base64 エンコードの文字列として送信し、ローカル画像ファイルの特徴検出を行います。

REST とコマンドライン

リクエストのデータを使用する前に、次のように置き換えます。

• base64-encoded-image: バイナリ画像データの base64 表現（ASCII 文字列）。これは次のような文字列になります。
  • /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==
  詳細については、base64 エンコードをご覧ください。

HTTP メソッドと URL:

POST https://vision.googleapis.com/v1/images:annotate

JSON 本文のリクエスト:

{
  "requests": [
    {
      "image": {
        "content": "base64-encoded-image"
      },
      "features": [
        {
          "maxResults": 5,
          "type": "LABEL_DETECTION"
        }
      ]
    }
  ]
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

注: GOOGLE_APPLICATION_CREDENTIALS 環境変数がサービス アカウントの秘密鍵ファイルのパスに設定されていることを確認します。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://vision.googleapis.com/v1/images:annotate"

PowerShell

注: GOOGLE_APPLICATION_CREDENTIALS 環境変数がサービス アカウントの秘密鍵ファイルのパスに設定されていることを確認します。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://vision.googleapis.com/v1/images:annotate" | Select-Object -Expand Content

リクエストが成功すると、サーバーは 200 OK HTTP ステータス コードと JSON 形式のレスポンスを返します。

LABEL_DETECTION レスポンスには、検出されたラベル、スコア、トピカリティ、不透明ラベル ID が含まれます。

• mid: 存在する場合は、このエンティティの Google Knowledge Graph エントリに対応する MID（Machine-generated Identifier）が格納されます。mid の値は異なる言語間でも一意であるため、異なる言語のエンティティをまとめるために使用することもできます。MID 値を調べるには、Google Knowledge Graph API のドキュメントをご覧ください。
• description - ラベルの説明。
• score - 信頼スコア。0（信頼できない）から 1（信頼度が非常に高い）の範囲で示されます。
• topicality - 画像に対する ICA（Image Content Annotation）ラベルの関連度。ページの全体的なコンテキストに対するラベルの重要度 / 関連度を測定します。

    {
  "responses": [
    {
      "labelAnnotations": [
        {
          "mid": "/m/01c8br",
          "description": "Street",
          "score": 0.87294734,
          "topicality": 0.87294734
        },
        {
          "mid": "/m/06pg22",
          "description": "Snapshot",
          "score": 0.8523099,
          "topicality": 0.8523099
        },
        {
          "mid": "/m/0dx1j",
          "description": "Town",
          "score": 0.8481104,
          "topicality": 0.8481104
        },
        {
          "mid": "/m/01d74z",
          "description": "Night",
          "score": 0.80408716,
          "topicality": 0.80408716
        },
        {
          "mid": "/m/01lwf0",
          "description": "Alley",
          "score": 0.7133322,
          "topicality": 0.7133322
        }
      ]
    }
  ]
}

Go

このサンプルを試す前に、Vision クイックスタート: クライアント ライブラリの使用にある Go の設定手順を行ってください。詳細については、Vision Go API のリファレンス ドキュメントをご覧ください。

GitHub で表示 フィードバック

// detectLabels gets labels from the Vision API for an image at the given file path.
func detectLabels(w io.Writer, file string) error {
	ctx := context.Background()

	client, err := vision.NewImageAnnotatorClient(ctx)
	if err != nil {
		return err
	}

	f, err := os.Open(file)
	if err != nil {
		return err
	}
	defer f.Close()

	image, err := vision.NewImageFromReader(f)
	if err != nil {
		return err
	}
	annotations, err := client.DetectLabels(ctx, image, nil, 10)
	if err != nil {
		return err
	}

	if len(annotations) == 0 {
		fmt.Fprintln(w, "No labels found.")
	} else {
		fmt.Fprintln(w, "Labels:")
		for _, annotation := range annotations {
			fmt.Fprintln(w, annotation.Description)
		}
	}

	return nil
}

Java

このサンプルを試す前に、Vision API クイックスタート: クライアント ライブラリの使用の Java の設定手順に従ってください。詳細については、Vision API Java API のリファレンス ドキュメントをご覧ください。

注: Java Spring Framework を使用している場合、Spring Cloud GCP で認証設定と Vision API を使用するクライアント オブジェクトを自動的に構成できます。

GitHub で表示 フィードバック

import com.google.cloud.vision.v1.AnnotateImageRequest;
import com.google.cloud.vision.v1.AnnotateImageResponse;
import com.google.cloud.vision.v1.BatchAnnotateImagesResponse;
import com.google.cloud.vision.v1.EntityAnnotation;
import com.google.cloud.vision.v1.Feature;
import com.google.cloud.vision.v1.Image;
import com.google.cloud.vision.v1.ImageAnnotatorClient;
import com.google.protobuf.ByteString;
import java.io.FileInputStream;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

public class DetectLabels {

  public static void detectLabels() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String filePath = "path/to/your/image/file.jpg";
    detectLabels(filePath);
  }

  // Detects labels in the specified local image.
  public static void detectLabels(String filePath) throws IOException {
    List<AnnotateImageRequest> requests = new ArrayList<>();

    ByteString imgBytes = ByteString.readFrom(new FileInputStream(filePath));

    Image img = Image.newBuilder().setContent(imgBytes).build();
    Feature feat = Feature.newBuilder().setType(Feature.Type.LABEL_DETECTION).build();
    AnnotateImageRequest request =
        AnnotateImageRequest.newBuilder().addFeatures(feat).setImage(img).build();
    requests.add(request);

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ImageAnnotatorClient client = ImageAnnotatorClient.create()) {
      BatchAnnotateImagesResponse response = client.batchAnnotateImages(requests);
      List<AnnotateImageResponse> responses = response.getResponsesList();

      for (AnnotateImageResponse res : responses) {
        if (res.hasError()) {
          System.out.format("Error: %s%n", res.getError().getMessage());
          return;
        }

        // For full list of available annotations, see http://g.co/cloud/vision/docs
        for (EntityAnnotation annotation : res.getLabelAnnotationsList()) {
          annotation
              .getAllFields()
              .forEach((k, v) -> System.out.format("%s : %s%n", k, v.toString()));
        }
      }
    }
  }
}

Node.js

このサンプルを試す前に、Vision クイックスタート: クライアント ライブラリの使用にある Node.js の設定手順を行ってください。詳細については、Vision Node.js API のリファレンス ドキュメントをご覧ください。

GitHub で表示 フィードバック

// Imports the Google Cloud client library
const vision = require('@google-cloud/vision');

// Creates a client
const client = new vision.ImageAnnotatorClient();

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const fileName = 'Local image file, e.g. /path/to/image.png';

// Performs label detection on the local file
const [result] = await client.labelDetection(fileName);
const labels = result.labelAnnotations;
console.log('Labels:');
labels.forEach(label => console.log(label.description));

Python

このサンプルを試す前に、Vision クイックスタート: クライアント ライブラリの使用にある Python の設定手順を行ってください。詳細については、Vision Python API のリファレンス ドキュメントをご覧ください。

GitHub で表示 フィードバック

def detect_labels(path):
    """Detects labels in the file."""
    from google.cloud import vision
    import io
    client = vision.ImageAnnotatorClient()

    with io.open(path, 'rb') as image_file:
        content = image_file.read()

    image = vision.Image(content=content)

    response = client.label_detection(image=image)
    labels = response.label_annotations
    print('Labels:')

    for label in labels:
        print(label.description)

    if response.error.message:
        raise Exception(
            '{}\nFor more info on error messages, check: '
            'https://cloud.google.com/apis/design/errors'.format(
                response.error.message))

その他の言語

C#: クライアント ライブラリ ページの C# の設定手順を実行してから、.NET 用の Vision リファレンス ドキュメントをご覧ください。

PHP: クライアント ライブラリ ページの PHP の設定手順を実行してから、PHP 用の Vision リファレンス ドキュメントをご覧ください。

Ruby: クライアント ライブラリ ページの Ruby の設定手順を実行してから、Ruby 用の Vision リファレンス ドキュメントをご覧ください。

リモート画像でラベルを検出する

ご参考までに、Vision API を使用すると、画像ファイルのコンテンツをリクエストの本文で送信することなく、Google Cloud Storage またはウェブ上にある画像ファイルに対して特徴検出を直接実行できます。

注意: HTTP / HTTPS URL から画像を取得する場合、リクエストが完了するとは限りません。リクエストの調整や DoS 防止などのため、指定したホストがリクエストを拒否することがあります。また、不正利用を防止するため、Google がサイトに対するリクエストを調整することもあります。このような状況ではリクエストが失敗します。したがって、本番環境のアプリケーションが外部ホストの画像に頼ることはよくありません。

REST とコマンドライン

リクエストのデータを使用する前に、次のように置き換えます。

• cloud-storage-image-uri: Cloud Storage バケット内の有効な画像ファイルへのパス。少なくとも、ファイルに対する読み取り権限が必要です。たとえば次のように指定します。

  • gs://cloud-samples-data/vision/label/setagaya.jpeg

HTTP メソッドと URL:

POST https://vision.googleapis.com/v1/images:annotate

JSON 本文のリクエスト:

{
  "requests": [
    {
      "image": {
        "source": {
          "gcsImageUri": "cloud-storage-image-uri"
        }
      },
      "features": [
        {
          "maxResults": 5,
          "type": "LABEL_DETECTION"
        },
      ]
    }
  ]
}

リクエストを送信するには、次のいずれかのオプションを選択します。

curl

注: GOOGLE_APPLICATION_CREDENTIALS 環境変数がサービス アカウントの秘密鍵ファイルのパスに設定されていることを確認します。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://vision.googleapis.com/v1/images:annotate"

PowerShell

注: GOOGLE_APPLICATION_CREDENTIALS 環境変数がサービス アカウントの秘密鍵ファイルのパスに設定されていることを確認します。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType: "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://vision.googleapis.com/v1/images:annotate" | Select-Object -Expand Content

リクエストが成功すると、サーバーは 200 OK HTTP ステータス コードと JSON 形式のレスポンスを返します。

LABEL_DETECTION レスポンスには、検出されたラベル、スコア、トピカリティ、不透明ラベル ID が含まれます。

• mid: 存在する場合は、このエンティティの Google Knowledge Graph エントリに対応する MID（Machine-generated Identifier）が格納されます。mid の値は異なる言語間でも一意であるため、異なる言語のエンティティをまとめるために使用することもできます。MID 値を調べるには、Google Knowledge Graph API のドキュメントをご覧ください。
• description - ラベルの説明。
• score - 信頼スコア。0（信頼できない）から 1（信頼度が非常に高い）の範囲で示されます。
• topicality - 画像に対する ICA（Image Content Annotation）ラベルの関連度。ページの全体的なコンテキストに対するラベルの重要度 / 関連度を測定します。

    {
  "responses": [
    {
      "labelAnnotations": [
        {
          "mid": "/m/01c8br",
          "description": "Street",
          "score": 0.87294734,
          "topicality": 0.87294734
        },
        {
          "mid": "/m/06pg22",
          "description": "Snapshot",
          "score": 0.8523099,
          "topicality": 0.8523099
        },
        {
          "mid": "/m/0dx1j",
          "description": "Town",
          "score": 0.8481104,
          "topicality": 0.8481104
        },
        {
          "mid": "/m/01d74z",
          "description": "Night",
          "score": 0.80408716,
          "topicality": 0.80408716
        },
        {
          "mid": "/m/01lwf0",
          "description": "Alley",
          "score": 0.7133322,
          "topicality": 0.7133322
        }
      ]
    }
  ]
}

Go

このサンプルを試す前に、Vision クイックスタート: クライアント ライブラリの使用にある Go の設定手順を行ってください。詳細については、Vision Go API のリファレンス ドキュメントをご覧ください。

GitHub で表示 フィードバック

// detectLabels gets labels from the Vision API for an image at the given file path.
func detectLabelsURI(w io.Writer, file string) error {
	ctx := context.Background()

	client, err := vision.NewImageAnnotatorClient(ctx)
	if err != nil {
		return err
	}

	image := vision.NewImageFromURI(file)
	annotations, err := client.DetectLabels(ctx, image, nil, 10)
	if err != nil {
		return err
	}

	if len(annotations) == 0 {
		fmt.Fprintln(w, "No labels found.")
	} else {
		fmt.Fprintln(w, "Labels:")
		for _, annotation := range annotations {
			fmt.Fprintln(w, annotation.Description)
		}
	}

	return nil
}

Java

このサンプルを試す前に、Vision API クイックスタート: クライアント ライブラリの使用の Java の設定手順に従ってください。詳細については、Vision API Java API のリファレンス ドキュメントをご覧ください。

注: Java Spring Framework を使用している場合、Spring Cloud GCP で認証設定と Vision API を使用するクライアント オブジェクトを自動的に構成できます。

GitHub で表示 フィードバック

import com.google.cloud.vision.v1.AnnotateImageRequest;
import com.google.cloud.vision.v1.AnnotateImageResponse;
import com.google.cloud.vision.v1.BatchAnnotateImagesResponse;
import com.google.cloud.vision.v1.EntityAnnotation;
import com.google.cloud.vision.v1.Feature;
import com.google.cloud.vision.v1.Image;
import com.google.cloud.vision.v1.ImageAnnotatorClient;
import com.google.cloud.vision.v1.ImageSource;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

public class DetectLabelsGcs {

  public static void detectLabelsGcs() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String filePath = "gs://your-gcs-bucket/path/to/image/file.jpg";
    detectLabelsGcs(filePath);
  }

  // Detects labels in the specified remote image on Google Cloud Storage.
  public static void detectLabelsGcs(String gcsPath) throws IOException {
    List<AnnotateImageRequest> requests = new ArrayList<>();

    ImageSource imgSource = ImageSource.newBuilder().setGcsImageUri(gcsPath).build();
    Image img = Image.newBuilder().setSource(imgSource).build();
    Feature feat = Feature.newBuilder().setType(Feature.Type.LABEL_DETECTION).build();
    AnnotateImageRequest request =
        AnnotateImageRequest.newBuilder().addFeatures(feat).setImage(img).build();
    requests.add(request);

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ImageAnnotatorClient client = ImageAnnotatorClient.create()) {
      BatchAnnotateImagesResponse response = client.batchAnnotateImages(requests);
      List<AnnotateImageResponse> responses = response.getResponsesList();

      for (AnnotateImageResponse res : responses) {
        if (res.hasError()) {
          System.out.format("Error: %s%n", res.getError().getMessage());
          return;
        }

        // For full list of available annotations, see http://g.co/cloud/vision/docs
        for (EntityAnnotation annotation : res.getLabelAnnotationsList()) {
          annotation
              .getAllFields()
              .forEach((k, v) -> System.out.format("%s : %s%n", k, v.toString()));
        }
      }
    }
  }
}

Node.js

このサンプルを試す前に、Vision クイックスタート: クライアント ライブラリの使用にある Node.js の設定手順を行ってください。詳細については、Vision Node.js API のリファレンス ドキュメントをご覧ください。

GitHub で表示 フィードバック

// Imports the Google Cloud client libraries
const vision = require('@google-cloud/vision');

// Creates a client
const client = new vision.ImageAnnotatorClient();

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Bucket where the file resides, e.g. my-bucket';
// const fileName = 'Path to file within bucket, e.g. path/to/image.png';

// Performs label detection on the gcs file
const [result] = await client.labelDetection(
  `gs://${bucketName}/${fileName}`
);
const labels = result.labelAnnotations;
console.log('Labels:');
labels.forEach(label => console.log(label.description));

Python

このサンプルを試す前に、Vision クイックスタート: クライアント ライブラリの使用にある Python の設定手順を行ってください。詳細については、Vision Python API のリファレンス ドキュメントをご覧ください。

GitHub で表示 フィードバック

def detect_labels_uri(uri):
    """Detects labels in the file located in Google Cloud Storage or on the
    Web."""
    from google.cloud import vision
    client = vision.ImageAnnotatorClient()
    image = vision.Image()
    image.source.image_uri = uri

    response = client.label_detection(image=image)
    labels = response.label_annotations
    print('Labels:')

    for label in labels:
        print(label.description)

    if response.error.message:
        raise Exception(
            '{}\nFor more info on error messages, check: '
            'https://cloud.google.com/apis/design/errors'.format(
                response.error.message))

gcloud

画像内のラベルを検出するには、次の例で示すように gcloud ml vision detect-labels コマンドを実行します。

gcloud ml vision detect-labels gs://cloud-samples-data/vision/label/setagaya.jpeg

その他の言語

C#: クライアント ライブラリ ページの C# の設定手順を実行してから、.NET 用の Vision リファレンス ドキュメントをご覧ください。

PHP: クライアント ライブラリ ページの PHP の設定手順を実行してから、PHP 用の Vision リファレンス ドキュメントをご覧ください。

Ruby: クライアント ライブラリ ページの Ruby の設定手順を実行してから、Ruby 用の Vision リファレンス ドキュメントをご覧ください。

試してみる

ラベルの検出を試してみましょう。すでに指定済みの画像（gs://cloud-samples-data/vision/label/setagaya.jpeg）を使用することも、独自の画像を指定することもできます。[実行] を選択してリクエストを送信します。

画像クレジット: Alex Knight、Unsplash より

リクエストの本文:

{
  "requests": [
    {
      "features": [
        {
          "maxResults": 5,
          "type": "LABEL_DETECTION"
        }
      ],
      "image": {
        "source": {
          "imageUri": "gs://cloud-samples-data/vision/label/setagaya.jpeg"
        }
      }
    }
  ]
}