偵測標籤

注意：Vision API 現已支援所有功能的離線非同步批次圖片註解。這項非同步要求最多支援 2000 個圖片檔案，並會傳回儲存在 Cloud Storage bucket 中的 JSON 回應檔案。如要進一步瞭解這項功能，請參閱離線批次圖片加註。

Vision API 可偵測及擷取圖片中實體的資訊，涵蓋廣泛的類別。

標籤可辨識一般物體、地點、活動、動物物種、產品等內容。如要使用指定的自訂標籤，建議使用 Cloud AutoML Vision 訓練自訂機器學習模型，以便分類圖片。

系統只會傳回英文標籤。Cloud Translation API 可將英文標籤翻譯成多種其他語言。

圖片來源：Unsplash 上的 Alex Knight。

舉例來說，上方的圖片可能會傳回下列標籤清單：

說明	分數
街道	0.872
快照	0.852
城鎮	0.848
夜間	0.804
Alley	0.713

在行動裝置應用程式中使用這個 API 嗎？請試用 Firebase 機器學習和 ML Kit，這兩項服務提供 Android 和 iOS 專用的 SDK，可使用 Cloud Vision 服務，以及裝置端 ML Vision API，並透過自訂 ML 模型進行裝置端推論。

標籤偵測要求

設定 Google Cloud 專案和驗證

如果您尚未建立 Google Cloud 專案，請立即建立。展開這個部分即可查看操作說明。

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vision API.

Enable the API

Install the Google Cloud CLI.

如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

如要初始化 gcloud CLI，請執行下列指令：

gcloud init

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vision API.

Enable the API

Install the Google Cloud CLI.

如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

如要初始化 gcloud CLI，請執行下列指令：

gcloud init

偵測本機圖片中的標籤

您可以使用 Vision API 對本機圖片檔執行特徵偵測。

如果是 REST 要求，請在要求主體中，以 base64 編碼字串的形式傳送圖片檔案內容。

如果是 gcloud 和用戶端程式庫要求，請在要求中指定本機圖片的路徑。

REST

使用任何要求資料之前，請先替換以下項目：

• BASE64_ENCODED_IMAGE：二進位圖片資料的 Base64 表示法 (ASCII 字串)。這個字串應類似下列字串：
  • /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==
  詳情請參閱 base64 編碼主題。
• RESULTS_INT：(選填) 要傳回的結果整數值。如果省略 "maxResults" 欄位及其值，API 會傳回預設值，也就是 10 個結果。這個欄位不適用於下列特徵類型：TEXT_DETECTION、DOCUMENT_TEXT_DETECTION 或 CROP_HINTS。
• PROJECT_ID：您的 Google Cloud 專案 ID。

HTTP 方法和網址：

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

JSON 要求主體：

{
  "requests": [
    {
      "image": {
        "content": "BASE64_ENCODED_IMAGE"
      },
      "features": [
        {
          "maxResults": RESULTS_INT,
          "type": "LABEL_DETECTION"
        }
      ]
    }
  ]
}

如要傳送要求，請選擇以下其中一個選項：

curl

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

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 知識圖譜項目的機器建立識別碼 (MID)。請注意，儘管語言不同，但都會使用相同的 mid 值，因此您可透過該值來連結不同語言的相同實體。如要檢查 MID 值，請參閱 Google 知識圖譜 API 說明文件。
• description - 標籤說明。
• score：信心分數，範圍從 0 (無信心) 到 1 (非常有信心)。
• topicality - ICA (圖片內容註解) 標籤與圖片的關聯性。這項指標會評估標籤對網頁整體脈絡的重要性/中心性。

{
  "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

在試用這個範例之前，請先按照Go「使用用戶端程式庫的 Vision 快速入門導覽課程」中的設定說明操作。詳情請參閱 Vision Go API 參考說明文件。

如要向 Vision 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

// 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 參考說明文件。

注意：Java Spring Framework 使用者可以透過 Spring Cloud Google Cloud 自動設定驗證設定和用戶端物件，以使用 Vision API。

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

在試用這個範例之前，請先按照Node.js「使用用戶端程式庫的 Vision 快速入門導覽課程」中的設定說明操作。詳情請參閱 Vision Node.js API 參考說明文件。

如要向 Vision 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

// 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

在試用這個範例之前，請先按照Python「使用用戶端程式庫的 Vision 快速入門導覽課程」中的設定說明操作。詳情請參閱 Vision Python API 參考說明文件。

如要向 Vision 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

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

    client = vision.ImageAnnotatorClient()

    with 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，對位於 Cloud Storage 或網路上的遠端圖片檔案執行特徵偵測。如要傳送遠端檔案要求，請在要求內文中指定檔案的網頁網址或 Cloud Storage URI。

注意：從 HTTP/HTTPS 網址擷取圖片時，Google 無法保證要求會完成。如果指定主機拒絕要求 (例如因要求節流或DoS防範)，或 Google 為防範濫用行為而節流對網站的要求，您的要求可能會失敗。最佳做法是不要在正式版應用程式中，依賴外部託管的圖片。

REST

使用任何要求資料之前，請先替換以下項目：

• CLOUD_STORAGE_IMAGE_URI：Cloud Storage 值區中有效圖片檔案的路徑。您必須至少擁有檔案的讀取權限。 範例：
  • gs://cloud-samples-data/vision/label/setagaya.jpeg

• RESULTS_INT：(選填) 要傳回的結果整數值。如果省略 "maxResults" 欄位及其值，API 會傳回預設值，也就是 10 個結果。這個欄位不適用於下列特徵類型：TEXT_DETECTION、DOCUMENT_TEXT_DETECTION 或 CROP_HINTS。
• PROJECT_ID：您的 Google Cloud 專案 ID。

HTTP 方法和網址：

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

JSON 要求主體：

{
  "requests": [
    {
      "image": {
        "source": {
          "gcsImageUri": "CLOUD_STORAGE_IMAGE_URI"
        }
      },
      "features": [
        {
          "maxResults": RESULTS_INT,
          "type": "LABEL_DETECTION"
        },
      ]
    }
  ]
}

如要傳送要求，請選擇以下其中一個選項：

curl

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell，自動登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

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

PowerShell

注意： 下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。 您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

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 知識圖譜項目的機器建立識別碼 (MID)。請注意，儘管語言不同，但都會使用相同的 mid 值，因此您可透過該值來連結不同語言的相同實體。如要檢查 MID 值，請參閱 Google 知識圖譜 API 說明文件。
• description - 標籤說明。
• score：信心分數，範圍從 0 (無信心) 到 1 (非常有信心)。
• topicality - 圖片內容註解 (ICA) 標籤與圖片的相關性。這項指標會評估標籤對網頁整體脈絡的重要性/中心性。

{
  "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

在試用這個範例之前，請先按照Go「使用用戶端程式庫的 Vision 快速入門導覽課程」中的設定說明操作。詳情請參閱 Vision Go API 參考說明文件。

如要向 Vision 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

// 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 參考說明文件。

注意：Java Spring Framework 使用者可以透過 Spring Cloud Google Cloud 自動設定驗證設定和用戶端物件，以使用 Vision API。

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

在試用這個範例之前，請先按照Node.js「使用用戶端程式庫的 Vision 快速入門導覽課程」中的設定說明操作。詳情請參閱 Vision Node.js API 參考說明文件。

如要向 Vision 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

// 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

在試用這個範例之前，請先按照Python「使用用戶端程式庫的 Vision 快速入門導覽課程」中的設定說明操作。詳情請參閱 Vision Python API 參考說明文件。

如要向 Vision 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

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)，也可以指定自己的圖片。選取「Execute」，傳送要求。



圖片來源：Unsplash 上的 Alex Knight。

要求主體：

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