建立產品集並搜尋產品

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

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

產品集建立索引後,您可以使用 Vision API Product Search 查詢產品集。

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

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

事前準備

設定專案

  1. 安裝 Google Cloud CLI。

  2. 設定 gcloud CLI,使用您的聯合身分。

    詳情請參閱「使用聯合身分登入 gcloud CLI」。

  3. 執行下列指令,初始化 gcloud CLI:

    gcloud init
  4. 建立或選取 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 專案名稱。

  5. 如要使用現有專案進行本指南中的操作,請確認您具有完成本指南所需的權限。如果您建立新專案,則已具備必要權限。

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

  7. 啟用 Vision API (如果尚未啟用):

    啟用 API 所需的角色

    如要啟用 API,您必須具備 serviceusage.services.enable 權限。如果您建立了專案,可能已透過「擁有者」角色 (roles/owner) 取得這項權限。否則,您可以透過「Service Usage 管理員」角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

    gcloud services enable vision.googleapis.com

必要的角色

如要取得完成本快速入門導覽課程所需的權限,請要求管理員在專案中授予您 Storage 物件檢視者 (roles/storage.objectViewer) IAM 角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色,取得必要權限。

使用資料集

在本快速入門導覽課程中,您會使用約 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

後續步驟