偵測標籤

Vision API 可偵測及擷取圖片中實體的資訊,橫跨多個類別。

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

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

世田谷區街景圖像
圖片版權Unsplash 上的 Alex Knight

舉例來說,上圖可能會傳回以下標籤清單:

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

標籤偵測要求

設定 Google Cloud 專案和驗證

偵測本機圖片中的標籤

您可以使用 Vision API 在本機圖片檔案上執行功能偵測。

針對 REST 要求,請在要求主體中,將圖片檔案的內容傳送為base64 編碼字串。

針對 gcloud 和用戶端程式庫要求,請在要求中指定本機圖片的路徑。

REST

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

  • BASE64_ENCODED_IMAGE:二進位圖片資料的 Base64 表示法 (ASCII 字串)。這個字串應類似下列字串:
    • /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==
    詳情請參閱「base64 編碼」主題。
  • RESULTS_INT:(選用) 要傳回的結果整數值。如果您省略 "maxResults" 欄位及其值,API 會傳回預設值 10 個結果。這個欄位不適用於下列地圖項目類型:TEXT_DETECTIONDOCUMENT_TEXT_DETECTIONCROP_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

將要求主體儲存在名為 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

將要求主體儲存在名為 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

在試用這個範例之前,請先按照 使用用戶端程式庫的 Vision 快速入門中的操作說明設定 Go。詳情請參閱 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 參考說明文件


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

如要向 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

在試用這個範例之前,請先按照 使用用戶端程式庫的 Vision 快速入門中的操作說明設定 Python。詳情請參閱 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。

REST

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

  • CLOUD_STORAGE_IMAGE_URI:Cloud Storage 值區中有效圖片檔案的路徑。您至少必須具備檔案的讀取權限。示例:
    • gs://cloud-samples-data/vision/label/setagaya.jpeg
  • RESULTS_INT:(選用) 要傳回的結果整數值。如果您省略 "maxResults" 欄位及其值,API 會傳回預設值 10 個結果。這個欄位不適用於下列地圖項目類型:TEXT_DETECTIONDOCUMENT_TEXT_DETECTIONCROP_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

將要求主體儲存在名為 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

將要求主體儲存在名為 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

在試用這個範例之前,請先按照 使用用戶端程式庫的 Vision 快速入門中的操作說明設定 Go。詳情請參閱 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 參考說明文件


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

如要向 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

在試用這個範例之前,請先按照 使用用戶端程式庫的 Vision 快速入門中的操作說明設定 Python。詳情請參閱 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"
        }
      }
    }
  ]
}