Buat set produk dan cari produk

Buat set produk dan cari produk

Panduan memulai ini menunjukkan cara membuat dan menggunakan tiga jenis resource Product Search Vision API: kumpulan produk yang berisi grup produk, dan gambar referensi yang terkait dengan produk tersebut.

Dalam panduan memulai ini, Anda akan membuat set produk, produk, dan gambar referensinya dalam satu langkah melalui impor batch.

Setelah kumpulan produk diindeks, Anda dapat membuat kueri untuk kumpulan produk menggunakan Product Search Vision API.

Panduan memulai ini akan memandu Anda melalui proses:

• Menggunakan CSV dan impor massal untuk membuat set produk, produk, dan gambar referensi.
• Membuat permintaan ke Product Search Vision API dengan gambar yang disimpan dalam bucket Cloud Storage.

Sebelum memulai

Jika Anda belum melakukannya, siapkan project seperti yang dijelaskan di bawah.

Menyiapkan project

Login ke akun Google Cloud Anda. Jika Anda baru menggunakan Google Cloud, buat akun untuk mengevaluasi performa produk kami dalam skenario dunia nyata. Pelanggan baru juga mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.
Instal Google Cloud CLI.
Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.
Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:
gcloud init
Buat atau pilih Google Cloud project.
Peran yang diperlukan untuk memilih atau membuat project
• Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.
Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.
• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.
Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.
Aktifkan Vision API:
Peran yang diperlukan untuk mengaktifkan API
Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.
gcloud services enable vision.googleapis.com
Memberikan peran ke akun pengguna Anda. Jalankan perintah berikut satu kali untuk setiap peran IAM berikut: roles/storage.objectViewer
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Ganti kode berikut:
• PROJECT_ID: Project ID Anda.
• USER_IDENTIFIER: ID untuk akun pengguna Anda. Misalnya, [e-mail].
• ROLE: Peran IAM yang Anda berikan ke akun pengguna Anda.

Instal Google Cloud CLI.

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Untuk melakukan inisialisasi gcloud CLI, jalankan perintah berikut:

gcloud init

Buat atau pilih Google Cloud project.

Peran yang diperlukan untuk memilih atau membuat project

• Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
• Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Catatan: Jika tidak berencana untuk menyimpan resource yang Anda buat dalam prosedur ini, buatlah project, bukan memilih project yang ada. Setelah menyelesaikan langkah ini, Anda dapat menghapus project, yang menghapus semua resource yang terkait dengan project ini.

• Buat Google Cloud project:

  gcloud projects create PROJECT_ID

  Ganti PROJECT_ID dengan nama untuk Google Cloud project yang Anda buat.

• Pilih project Google Cloud yang Anda buat:

  gcloud config set project PROJECT_ID

  Ganti PROJECT_ID dengan nama project Google Cloud Anda.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

Aktifkan Vision API:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

gcloud services enable vision.googleapis.com

Memberikan peran ke akun pengguna Anda. Jalankan perintah berikut satu kali untuk setiap peran IAM berikut: roles/storage.objectViewer

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

Ganti kode berikut:

• PROJECT_ID: Project ID Anda.
• USER_IDENTIFIER: ID untuk akun pengguna Anda. Misalnya, [e-mail].
• ROLE: Peran IAM yang Anda berikan ke akun pengguna Anda.

Menggunakan set data

Dalam panduan memulai ini, Anda menggunakan set data yang berisi ~100 entri kategori produk apparel-v2. Set data yang tersedia secara publik ini terletak pada bucket Cloud Storage publik di:

• gs://cloud-samples-data/vision/product_search/product_catalog.csv

Berikut format CSV-nya:

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

Catatan: Contoh CSV ini tidak menyertakan kolom opsional product-display dan bounding-poly. Untuk informasi selengkapnya tentang persyaratan CSV, lihat topik cara Memformat CSV impor massal.

Gunakan impor massal untuk membuat set produk, produk, dan gambar referensi

Gunakan perintah curl berikut untuk membuat set produk baru dengan produk dan gambar referensi. Kumpulan ini bernama product_set0, nilai yang dideklarasikan dalam CSV impor.

Pertama-tama, buat file permintaan JSON bernama import_request.json dan simpan di direktori kerja Anda saat ini:

import_request.json

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

Setelah membuat file permintaan JSON, kirim permintaan:

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

Ganti kode berikut:

• LOCATION_ID: Lokasi yang akan menjalankan tutorial Anda, misalnya, us-east1. ID lokasi yang valid adalah: us-west1, us-east1, europe-west1, dan asia-east1 .

Respons yang berhasil berisi objek operasi yang berjalan lama:

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

Responsnya juga berisi ID operasi relatif (misalnya, 0a0aec86192599fa) yang dapat digunakan untuk mendapatkan status operasi.

Mendapatkan status operasi impor

Anda dapat menggunakan OPERATION_ID yang ditampilkan dari operasi impor untuk memeriksa status operasi impor massal:

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

Respons yang berhasil akan terlihat seperti ini:

{
  "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": [
      {},
      {},
      [...]
      {},
      {}
    ]
  }
}

Pengindeksan

Indeks Product Search untuk produk diperbarui sekitar setiap hari. Ketika gambar ditambahkan atau dihapus, perubahan tidak akan ditampilkan dalam respons Product Search hingga indeks diperbarui berikutnya.

Untuk memastikan pengindeksan telah berhasil diselesaikan, periksa kolom indexTime dari kumpulan produk.

Mencantumkan set produk dan memeriksa pengindeksan

Anda dapat mencantumkan semua set produk dan menggunakan kolom indexTime untuk memverifikasi bahwa pengindeksan telah berhasil diselesaikan:

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

Respons yang berhasil akan mencantumkan semua set produk Anda, termasuk ID set produk (misalnya, product_set0) serta kolom indexTime yang menunjukkan saat pengindeksan selesai:

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

Membuat daftar produk

Anda dapat menggunakan PRODUCT_SET_ID yang ditampilkan dari daftar set produk untuk mencantumkan semua produk dalam set produk Anda:

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

Respons yang berhasil akan mencantumkan detail produk.

Dalam permintaan ini, Anda menggunakan parameter kueri opsional pageSize untuk menetapkan daftar hasil ke 15 produk. nextPageToken dalam respons juga menunjukkan ada produk lain yang dapat dicantumkan. Anda dapat menggunakan token yang tercantum untuk mengambil hasil lebih lanjut. Untuk informasi selengkapnya tentang penggunaan pageToken, lihat Mendapatkan dan mencantumkan resource.

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

Telusuri produk yang cocok dengan Product Search Vision API

Setelah pengindeksan selesai, Anda dapat menelusuri produk yang cocok dengan gambar sampel. Dalam panduan memulai ini, Anda menggunakan gambar yang disimpan dalam bucket Google Cloud Storage seperti gambar berikut.

Catatan: Anda juga dapat melakukan penelusuran menggunakan image lokal berenkode base64. Untuk contoh kode yang menggunakan gambar lokal, lihat Menelusuri produk.

gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg

Menelusuri menggunakan gambar eksternal

Gunakan permintaan berikut untuk menelusuri menggunakan image yang disimpan di bucket Cloud Storage publik.

Pertama-tama, buat file permintaan JSON bernama search_request.json dan simpan di direktori kerja Anda saat ini. Ubah nilai berikut dalam permintaan JSON agar sesuai dengan informasi project Anda:

• 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"
        }
      }
    }
  ]
}

Setelah membuat file permintaan JSON, kirim permintaan:

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

Permintaan yang berhasil akan menampilkan daftar produk yang cocok, yang ditunjukkan oleh ID produknya. Hasil ini akan diperinci lebih lanjut berdasarkan masing-masing produk yang diidentifikasi dengan kotak pembatas jika terdapat beberapa produk dalam satu gambar.

Untuk contoh deteksi produk tunggal dan multi-deteksi produk dalam gambar, lihat Memahami respons penelusuran & multi-deteksi.

Kolom score juga ditampilkan. Kolom ini menunjukkan keyakinan terhadap layanan yang menganggap produk tersebut cocok dengan gambar yang diberikan, dalam skala 0 (tanpa keyakinan) hingga 1 (keyakinan penuh).

Kolom indexTime menunjukkan versi indeks yang sedang ditelusuri. Perubahan gambar yang dilakukan setelah waktu ini tidak akan ditampilkan dalam hasil.

Respons

{
  "responses": [
    {
      "productSearchResults": {
        "indexTime": "2020-01-07T18:33:45.300851144Z",
        "results": [
          {
            "product": {
              "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16",
              "displayName": " ",
              "productCategory": "apparel-v2",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                }
              ]
            },
            "score": 1,
            "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16/referenceImages/image16"
          },
          {
            "product": {
              "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id29",
              "displayName": " ",
              "productCategory": "apparel-v2",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                }
              ]
            },
            "score": 0.27578148,
            "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id29/referenceImages/image29"
          },
          ...
          {
            "product": {
              "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id22",
              "displayName": " ",
              "productCategory": "apparel-v2",
              "productLabels": [
                {
                  "key": "style",
                  "value": "women"
                },
                {
                  "key": "category",
                  "value": "dress"
                },
                {
                  "key": "kids",
                  "value": "true"
                }
              ]
            },
            "score": 0.20356013,
            "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id22/referenceImages/image22"
          }
        ],
        "productGroupedResults": [
          {
            "boundingPoly": {
              "normalizedVertices": [
                {
                  "x": 0.25542393,
                  "y": 0.15517132
                },
                {
                  "x": 0.8196448,
                  "y": 0.15517132
                },
                {
                  "x": 0.8196448,
                  "y": 0.92001766
                },
                {
                  "x": 0.25542393,
                  "y": 0.92001766
                }
              ]
            },
            "results": [
              {
                "product": {
                  "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16",
                  "displayName": " ",
                  "productCategory": "apparel-v2",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 1,
                "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id16/referenceImages/image16"
              },
              {
                "product": {
                  "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id57",
                  "displayName": " ",
                  "productCategory": "apparel-v2",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 0.27369013,
                "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id57/referenceImages/image57"
              },
              ...
              {
                "product": {
                  "name": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id18",
                  "displayName": " ",
                  "productCategory": "apparel-v2",
                  "productLabels": [
                    {
                      "key": "style",
                      "value": "women"
                    },
                    {
                      "key": "category",
                      "value": "dress"
                    }
                  ]
                },
                "score": 0.21221256,
                "image": "projects/PROJECT_ID/locations/LOCATION_ID/products/product_id18/referenceImages/image18"
              }
            ],
            "objectAnnotations": [
              {
                "mid": "/m/01d40f",
                "name": "Dress",
                "score": 0.968603
              }
            ]
          }
        ]
      }
    }
  ]
}

Selamat! Anda telah membuat permintaan images.annotate pertama ke layanan Product Search Vision API.

Pembersihan

1. Opsional: Cabut kredensial dari gcloud CLI.

   gcloud auth revoke

2. Perhatian: Menghapus project memiliki efek berikut:

   • Semua hal dalam project akan dihapus. Jika Anda menggunakan project yang ada untuk mengerjakan tugas di dokumen ini, saat Anda menghapusnya, pekerjaan lain dalam project tersebut juga akan dihapus.
   • Project ID kustom akan hilang. Saat membuat project ini, Anda mungkin juga membuat project ID kustom yang masih ingin digunakan pada masa mendatang. Agar tidak kehilangan URL yang menggunakan project ID tersebut, seperti URL appspot.com, hapus resource yang dipilih di dalam project, bukan menghapus seluruh project.

   Jika Anda berencana mempelajari beberapa arsitektur, tutorial atau panduan memulai, dengan menggunakan kembali project dapat membantu Anda agar tidak melampaui batas kuota project.

   Menghapus Google Cloud project:

   gcloud projects delete PROJECT_ID

Langkah berikutnya

• Mulai Product Search Vision API dalam bahasa pilihan Anda dengan menggunakan Library Klien Product Search Vision API.
• Pelajari Panduan Cara Kerja.
• Ikuti Tutorial.