제품 세트 만들기 및 제품 검색

이 빠른 시작에서는 세 가지 유형의 Vision API 제품 검색 리소스, 즉 제품과 여러 제품이 모여 구성된 제품 세트, 해당 제품 관련 참조 이미지를 만들고 사용하는 방법을 보여줍니다.

이 빠른 시작에서는 일괄 가져오기를 통해 제품 세트, 제품, 참조 이미지를 한 번에 만듭니다.

제품 세트의 색인이 생성된 후에는 Vision API 제품 검색을 사용하여 제품 세트를 쿼리할 수 있습니다.

이 빠른 시작에서는 다음 작업 과정을 안내합니다.

  • CSV와 일괄 가져오기를 사용하여 제품 세트, 제품, 참조 이미지 만들기
  • Cloud Storage 버킷에 저장된 이미지로 Vision API 제품 검색 요청하기

시작하기 전에

아직 프로젝트를 설정하지 않았으면 아래의 설명에 따라 설정하세요.

프로젝트 설정

  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. 외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 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. 외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 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). 유효한 위치 식별자는 us-west1, us-east1, europe-west1, asia-east1입니다.

    데이터 세트 사용

    이 빠른 시작에서는 약 100개의 apparel-v2 제품 카테고리 항목으로 구성된 데이터 세트를 사용합니다. 공개적으로 사용 가능한 이 데이터 세트는 다음 위치의 공개 Cloud Storage 버킷에 있습니다.

    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 명령어를 사용하여 제품과 참조 이미지가 있는 새 제품 세트를 만듭니다. 이 세트는 CSV 가져오기에 선언된 값인 product_set0으로 이름이 지정됩니다.

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

    색인 생성

    제품의 제품 검색 색인은 약 30분마다 업데이트됩니다. 이미지가 추가되거나 삭제되어도 다음 번에 색인이 업데이트될 때까지 제품 검색 응답에 변경사항이 반영되지 않습니다.

    색인 생성이 성공적으로 완료되었는지 확인하려면 제품 세트의 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 제품 검색을 사용하여 일치하는 제품 검색하기

    색인 생성이 완료되면 샘플 이미지와 일치하는 제품을 검색할 수 있습니다. 이 빠른 시작에서는 다음 이미지와 같이 Google Cloud Storage 버킷에 저장된 이미지를 사용합니다.

    Cloud Storage 버킷의 드레스 이미지입니다.
    gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg

    원격 이미지를 사용한 검색

    다음 요청을 사용하여 공개 Cloud Storage 버킷에 저장된 이미지를 사용하여 검색합니다.

    먼저 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 제품 검색 서비스에 대한 첫 번째 images.annotate 요청이 완료되었습니다.

    삭제

    1. Optional: Revoke credentials from the gcloud CLI. 

      gcloud auth revoke

    2. Delete a Google Cloud project:

      gcloud projects delete PROJECT_ID

    다음 단계