建立產品集並搜尋產品

本快速入門導覽課程將示範如何建立及使用三種類型的 Vision API Product Search 資源：「產品集」，其包含一組「產品」，以及與這些產品相關聯的「參考圖片」。

在本快速入門導覽課程中，您將透過批次匯入，在單一步驟中建立產品集、產品和參考圖片。

產品集編入索引後，您可以使用 Vision API Product Search 查詢產品集。

本快速入門導覽課程會逐步引導您完成下列程序：

  • 使用 CSV 和大量匯入功能來建立產品集、產品和參考圖片。
  • 使用儲存在 Cloud Storage bucket 中的圖片，向 Vision API Product Search 提出要求。

事前準備

如果您尚未設定專案，請按照下文說明操作。

設定專案

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  2. 安裝 Google Cloud CLI。

  3. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  4. 執行下列指令，初始化 gcloud CLI：

    gcloud init

  5. 建立或選取 Google Cloud 專案。

    選取或建立專案所需的角色

    • 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
    • 建立專案：如要建立專案，您需要「專案建立者」角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

    • 建立 Google Cloud 專案：

      gcloud projects create PROJECT_ID

      將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

    • 選取您建立的 Google Cloud 專案：

      gcloud config set project PROJECT_ID

      將 PROJECT_ID 替換為 Google Cloud 專案名稱。

  6. 確認專案已啟用計費功能 Google Cloud 。

  7. 啟用 Vision API：

    啟用 API 時所需的角色

    如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

    gcloud services enable vision.googleapis.com

  8. 將角色授予使用者帳戶。針對下列每個 IAM 角色，執行一次下列指令： roles/storage.objectViewer 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    更改下列內容：

    • PROJECT_ID：專案 ID。
    • USER_IDENTIFIER：使用者帳戶的 ID。 例如：myemail@example.com。
    • ROLE：授予使用者帳戶的 IAM 角色。

  9. 安裝 Google Cloud CLI。

  10. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  11. 執行下列指令，初始化 gcloud CLI：

    gcloud init

  12. 建立或選取 Google Cloud 專案。

    選取或建立專案所需的角色

    • 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
    • 建立專案：如要建立專案，您需要「專案建立者」角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

    • 建立 Google Cloud 專案：

      gcloud projects create PROJECT_ID

      將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

    • 選取您建立的 Google Cloud 專案：

      gcloud config set project PROJECT_ID

      將 PROJECT_ID 替換為 Google Cloud 專案名稱。

  13. 確認專案已啟用計費功能 Google Cloud 。

  14. 啟用 Vision API：

    啟用 API 時所需的角色

    如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

    gcloud services enable vision.googleapis.com

  15. 將角色授予使用者帳戶。針對下列每個 IAM 角色，執行一次下列指令： roles/storage.objectViewer 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    更改下列內容：

    • PROJECT_ID：專案 ID。
    • USER_IDENTIFIER：使用者帳戶的 ID。 例如：myemail@example.com。
    • ROLE：授予使用者帳戶的 IAM 角色。
    16.

使用資料集

在本快速入門導覽課程中，您會使用約 100 個apparel-v2產品類別項目的資料集。這個公開資料集位於公開的 Cloud Storage bucket，網址如下：

CSV 格式如下：

gs://cloud-ai-vision-data/product-search-tutorial/images/filename1.jpg,image0,product_set0,product_id0,apparel-v2,,"style=women,category=shoe",
gs://cloud-ai-vision-data/product-search-tutorial/images/filename2.jpg,image1,product_set0,product_id1,apparel-v2,,"style=men,category=shoe",
gs://cloud-ai-vision-data/product-search-tutorial/images/filename3.jpg,image2,product_set0,product_id2,apparel-v2,,"style=women,category=dress",

使用大量匯入功能建立產品集、產品和參考圖片

使用下列 curl 指令，建立包含產品和參考圖片的新產品集。這個產品集名為 product_set0，也就是匯入 CSV 中宣告的值。

首先，請建立名為 import_request.json 的要求 JSON 檔案，並儲存至目前的工作目錄：

import_request.json

{
  "inputConfig": {
    "gcsSource": {
      "csvFileUri": "gs://cloud-samples-data/vision/product_search/product_catalog.csv"
    }
  }
}

建立要求 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 @import_request.json \
    https://vision.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/productSets:import

更改下列內容：

  • LOCATION_ID：執行教學課程的位置，例如 us-east1。有效位置 ID 包括：us-west1、us-east1、europe-west1 和 asia-east1。

成功的回應會包含長時間執行的作業物件：

{
  "name": "locations/LOCATION_ID/operations/0a0aec86192599fa"
}

回應也會包含相對作業 ID (例如 0a0aec86192599fa)，可用於取得作業狀態。

取得匯入作業狀態

您可以使用匯入作業傳回的 OPERATION_ID 檢查大量匯入作業的狀態：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json" \
    https://vision.googleapis.com/v1/locations/LOCATION_ID/operations/OPERATION_ID

成功的回應如下所示：

{
  "name": "locations/LOCATION_ID/operations/0a0aec86192599fb",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.BatchOperationMetadata",
    "state": "SUCCESSFUL",
    "submitTime": "2018-11-30T03:11:04.808114024Z",
    "endTime": "2018-11-30T03:11:38.624444324Z"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.vision.v1.ImportProductSetsResponse",
    "referenceImages": [
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id0/referenceImages/image0",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/46a0cbcf70ba11e89399d20059124800.jpg"
      },
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id1/referenceImages/image1",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/46a1aea370ba11e888d4d20059124800.jpg"
      },
      ...
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id93/referenceImages/image93",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/4697319970ba11e8a7bfd20059124800.jpg"
      },
      {
        "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id94/referenceImages/image94",
        "uri": "gs://cloud-ai-vision-data/product-search-tutorial/images/4698596370ba11e8bf6ad20059124800.jpg"
      }
    ],
    "statuses": [
      {},
      {},
      [...]
      {},
      {}
    ]
  }
}

建立索引

產品的 Product Search 搜尋索引大約每天會更新一次。新增或刪除圖片後，這些變更會在下次更新索引時，才反映在 Product Search 回應中。

如要確認索引編製作業是否已順利完成，請檢查產品組合的 indexTime 欄位。

列出產品集並檢查索引建立情形

您可以列出所有產品集，並使用 indexTime 欄位來確認索引建立作業是否順利完成：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json" \
    https://vision.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/productSets

成功的回應會列出所有產品集，包括產品集 ID (例如 product_set0)，以及指出索引建立作業完成時間的 indexTime 欄位：

{
  "productSets": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/productSets/product_set0",
      "displayName": " ",
      "indexTime": "2019-11-30T18:33:40.093508652Z",
      "indexError": {}
    }
  ]
}

列出產品

您可以使用從產品集清單中傳回的 PRODUCT_SET_ID，列出產品集中的所有產品：

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json" \
    https://vision.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/productSets/PRODUCT_SET_ID/products?pageSize=15

成功的回應會列出產品詳細資料。

在這項要求中，您可以使用選用的查詢參數 pageSize，將結果清單設為 15 項產品。回應中的 nextPageToken 也表示還有更多可列出的產品。您可以使用列出的符記擷取更多結果。如要進一步瞭解如何使用 pageToken，請參閱「取得及列出資源」。

{
  "products": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id0",
      "displayName": " ",
      "productCategory": "apparel",
      "productLabels": [
        {
          "key": "style",
          "value": "women"
        },
        {
          "key": "category",
          "value": "shoe"
        }
      ]
    },
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id1",
      "displayName": " ",
      "productCategory": "apparel",
      "productLabels": [
        {
          "key": "style",
          "value": "men"
        },
        {
          "key": "category",
          "value": "shoe"
        }
      ]
    },
    ...
    {
      "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id21",
      "displayName": " ",
      "productCategory": "apparel",
      "productLabels": [
        {
          "key": "style",
          "value": "women"
        },
        {
          "key": "category",
          "value": "dress"
        }
      ]
    }
  ],
  "nextPageToken": "1LqhSgZfM_uWKOxvog"
}

使用 Vision API Product Search 搜尋相符的產品

索引建立完畢後，即可搜尋與範例圖片相符的產品。在本快速入門導覽課程中，您將使用儲存在 Google Cloud Storage bucket 的圖片，例如下圖。

Cloud Storage bucket 中的洋裝圖片。
gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg

使用遠端圖片搜尋

使用下列要求，透過儲存在公開 Cloud Storage bucket 中的圖片進行搜尋。

請先建立名為 search_request.json 的要求 JSON 檔案，並儲存至目前的工作目錄。請變更要求 JSON 中的下列值，確保與專案資訊相符：

  • PROJECT_ID
  • LOCATION_ID
  • PRODUCT_SET_ID

search_request.json

{
  "requests": [
    {
      "image": {
        "source": {
          "gcsImageUri": "gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg"
        }
      },
      "features": [
        {
          "type": "PRODUCT_SEARCH"
        }
      ],
      "imageContext": {
        "productSearchParams": {
          "productSet": "projects/PROJECT_ID/locations/LOCATION_ID/productSets/PRODUCT_SET_ID",
          "productCategories": [
            "apparel-v2"
          ],
          "filter": "style=womens OR style=women"
        }
      }
    }
  ]
}

建立要求 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 @search_request.json \
    https://vision.googleapis.com/v1/images:annotate

如果要求成功，系統會傳回相符的產品清單，並以產品 ID 表示這些產品。如果單張圖片中有多個產品，則會以定界框識別個別產品，來進而進一步細分這些結果。

如要查看單一產品偵測和圖片中多項產品偵測的範例，請參閱「瞭解搜尋回應和多重偵測」。

系統也會傳回 score 欄位。這個欄位表示服務認為產品與所提供圖片相符的信心水準，等級為 0 (完全沒有信心) 至 1 (完全有信心)。

「indexTime」欄位會顯示正在搜尋的索引版本。在這個時間點之後進行的圖片變更不會反映在結果中。

恭喜！您已向 Vision API Product Search 服務發出第一項 images.annotate 要求。

清除所用資源

  1. 選用：從 gcloud CLI 撤銷憑證。 

    gcloud auth revoke

  2. 刪除 Google Cloud 專案：

    gcloud projects delete PROJECT_ID

後續步驟