יצירת קבוצת מוצרים וחיפוש מוצרים

במדריך למתחילים הזה נסביר איך ליצור ולהשתמש בשלושת הסוגים של משאבי Vision API Product Search: קבוצת מוצרים שמכילה קבוצה של מוצרים, ותמונות רפרנס שמשויכות למוצרים האלה.

במדריך למתחילים הזה תלמדו איך ליצור קבוצת מוצרים, מוצרים ותמונות רפרנס שלהם בשלב אחד, באמצעות ייבוא באצווה.

אחרי שקבוצת המוצרים עברה אינדוקס, אפשר לשלוח שאילתה לקבוצת המוצרים באמצעות Vision API Product Search.

במדריך למתחילים הזה נסביר איך:

  • שימוש ב-CSV ובייבוא בכמות גדולה כדי ליצור קבוצת מוצרים, מוצרים ותמונות רפרנס.
  • שליחת בקשה ל-Vision API Product Search עם תמונה שמאוחסנת בקטגוריה של Cloud Storage.

לפני שמתחילים

אם עדיין לא עשיתם את זה, צריך להגדיר את הפרויקט כמו שמוסבר בהמשך.

הגדרת הפרויקט

  1. נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

  2. התקינו את ה-CLI של Google Cloud.

  3. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  4. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה: 

    gcloud init

  5. יוצרים או בוחרים פרויקט ב- Google Cloud .

    תפקידים שנדרשים כדי לבחור או ליצור פרויקט

    • Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
    • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (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, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים 

    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: מזהה הפרויקט.
    • ‫USER_IDENTIFIER: המזהה של חשבון המשתמש . לדוגמה, myemail@example.com.
    • ‫ROLE: תפקיד ה-IAM שאתם מקצים לחשבון המשתמש.

  9. התקינו את ה-CLI של Google Cloud.

  10. אם אתם משתמשים בספק זהויות חיצוני (IdP), קודם אתם צריכים להיכנס ל-CLI של gcloud באמצעות המאגר המאוחד לניהול זהויות.

  11. כדי לאתחל את ה-CLI של gcloud, הריצו את הפקודה הבאה: 

    gcloud init

  12. יוצרים או בוחרים פרויקט ב- Google Cloud .

    תפקידים שנדרשים כדי לבחור או ליצור פרויקט

    • Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
    • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (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, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים 

    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: מזהה הפרויקט.
    • ‫USER_IDENTIFIER: המזהה של חשבון המשתמש . לדוגמה, myemail@example.com.
    • ‫ROLE: תפקיד ה-IAM שאתם מקצים לחשבון המשתמש.
    16.

שימוש במערך נתונים

במדריך הזה תשתמשו במערך נתונים של כ-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. הקבוצה הזו נקראת product_set0, ערך שהוצהר בקובץ ה-CSV של הייבוא.

קודם יוצרים קובץ JSON של בקשה בשם import_request.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. מזהי המיקום התקפים הם: us-west1,‏ us-east1,‏ europe-west1 ו-asia-east1.

תגובה מוצלחת מכילה אובייקט של פעולה ממושכת:

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

התגובה מכילה גם מזהה פעולה יחסי (לדוגמה, 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": [
      {},
      {},
      [...]
      {},
      {}
    ]
  }
}

יצירת אינדקס

אינדקס החיפוש של מוצרים מתעדכן בערך כל יום. כשמוסיפים או מוחקים תמונות, השינוי לא יופיע בתשובות של חיפוש המוצרים עד לעדכון הבא של האינדקס.

כדי לוודא שהוספת המוצרים לאינדקס הסתיימה בהצלחה, בודקים את השדה 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

אם הפעולה בוצעה ללא שגיאות, התגובה תכלול רשימה של כל קבוצות המוצרים, כולל מזהה קבוצת המוצרים (לדוגמה, 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, כמו התמונה הבאה.

תמונה של שמלה בקטגוריה של Cloud Storage.
gs://cloud-ai-vision-data/product-search-tutorial/images/468f782e70ba11e8941fd20059124800.jpg

חיפוש באמצעות תמונה מרוחקת

משתמשים בבקשה הבאה כדי לחפש באמצעות התמונה שמאוחסנת בקטגוריה ציבורית של Cloud Storage.

קודם יוצרים קובץ JSON של בקשה בשם search_request.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

אם הבקשה תצליח, תוחזר רשימה של מוצרים תואמים, שמצוינים באמצעות מזהה המוצר שלהם. התוצאות האלה מחולקות לפי מוצרים ספציפיים שמזוהים באמצעות תיבות תוחמות, אם יש כמה מוצרים בתמונה אחת.

דוגמה לזיהוי של מוצר יחיד ולזיהוי של כמה מוצרים בתמונה מופיעה במאמר הסבר על תשובות לחיפושים וזיהוי של כמה מוצרים.

מוחזר גם השדה score. השדה הזה מציין את רמת המהימנות של השירות לגבי ההתאמה של המוצר לתמונה שסופקה, בסולם של 0 (ללא מהימנות) עד 1 (מהימנות מלאה).

בשדה indexTime מוצגת הגרסה של האינדקס שבו מתבצע החיפוש. שינויים בתמונות שבוצעו אחרי השעה הזו לא יופיעו בתוצאות.

כל הכבוד! ביצעת את הבקשה הראשונה שלך ל-images.annotate, שירות חיפוש המוצרים של Vision API.

הסרת המשאבים

  1. אם רוצים, מבטלים את פרטי הכניסה של ה-CLI של gcloud. 

    gcloud auth revoke

  2. כדי למחוק פרויקט ב- Google Cloud :

    gcloud projects delete PROJECT_ID

המאמרים הבאים