建立產品集並搜尋產品

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

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

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

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

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

事前準備

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

設定專案

  1. 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.

  2. Install the Google Cloud CLI.

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

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

    gcloud init

  5. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Vision API:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

    gcloud services enable vision.googleapis.com

  8. Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/storage.objectViewer 

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

    Replace the following:

    • PROJECT_ID: Your project ID.
    • USER_IDENTIFIER: The identifier for your user account. For example, myemail@example.com.
    • ROLE: The IAM role that you grant to your user account.

  9. Install the Google Cloud CLI.

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

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

    gcloud init

  12. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

  13. Verify that billing is enabled for your Google Cloud project.

  14. Enable the Vision API:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

    gcloud services enable vision.googleapis.com

  15. Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/storage.objectViewer 

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

    Replace the following:

    • PROJECT_ID: Your project ID.
    • USER_IDENTIFIER: The identifier for your user account. For example, myemail@example.com.
    • ROLE: The IAM role that you grant to your user account.
    16.

    設定環境變數

    為了更方便執行本快速入門導覽課程中的 curl 範例，請設定下列環境變數。其中：

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

    使用資料集

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

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

    {
  "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 索引大約每 30 分鐘會更新一次。新增或刪除圖片後，這些變更會在下次更新索引時，才反映在 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. Optional: Revoke credentials from the gcloud CLI. 

      gcloud auth revoke

    2. Delete a Google Cloud project:

      gcloud projects delete PROJECT_ID

    後續步驟