Die Produktsuche befindet sich im Wartungsmodus. Für eine bessere Skalierbarkeit und dieselben Funktionen wie bei der Produktsuche können Sie das Vision Warehouse verwenden.
Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Sie können die import-Methode verwenden, um mithilfe einer CSV-Datei eine Produktgruppe und Produkte mit Referenzbildern gleichzeitig zu erstellen. Auf dieser Seite wird beschrieben, wie Sie die CSV-Datei formatieren.
Referenzbilder erstellen
Referenzbilder sind Bilder mit verschiedenen Ansichten Ihrer Artikel. Hierbei gelten folgende Empfehlungen:
Die Datei darf maximal 20 MB groß sein.
Überlegen Sie, welche Perspektiven das Produkt auf natürliche Weise hervorheben und in welchen Perspektiven die relevanten optischen Informationen enthalten sind.
Erstellen Sie Referenzbilder, die fehlende Perspektiven ergänzen. Wenn Sie beispielsweise nur Bilder vom rechten Schuh haben, stellen Sie diese für den linken Schuh gespiegelt bereit.
Laden Sie das Bild mit der höchsten Auflösung hoch.
Präsentieren Sie das Produkt vor einem weißen Hintergrund.
Konvertieren Sie PNGs mit transparentem Hintergrund in einen soliden Hintergrund.
Bilder müssen in einem Cloud Storage-Bucket gespeichert sein. Wenn Sie die Anfrage zur Bilderstellung mit einem API-Schlüssel authentifizieren, muss der Bucket öffentlich sein. Wenn Sie für die Authentifizierung ein Dienstkonto verwenden, muss dieses Dienstkonto Lesezugriff auf den Bucket haben.
CSV-Formatierungsrichtlinien
Zur Verwendung der Methode import müssen sowohl die CSV-Datei als auch die Bilder, auf die sie verweist, in einem Cloud Storage-Bucket enthalten sein. CSV-Dateien sind auf maximal 20.000 Zeilen beschränkt. Jede Zeile ist auf maximal 2.048 Zeichen beschränkt. Wenn Sie weitere Bilder importieren möchten, teilen Sie sie in mehrere CSV-Dateien auf.
Die CSV-Datei muss ein Bild pro Zeile und die folgenden Spalten enthalten:
image-uri: Der Cloud Storage-URI des Referenzbilds.
image-id: Optional. Ein nur einmal vorkommender Wert, wenn Sie ihn angeben. Andernfalls weist das System einen einmaligen Wert zu.
product-set-id: Eine eindeutige ID für die Produktgruppe, in die die Bilder importiert werden sollen.
product-id: Eine benutzerdefinierte ID für das zum Referenzbild gehörende Produkt. Eine product-id kann mehreren Referenzbildern zugeordnet sein.
product-category: Zulässige Werte sind homegoods-v2, apparel-v2, toys-v2, packagedgoods-v1 und general-v1 *; die Kategorie für das durch das Referenzbild identifizierte Produkt. Wird vom System abgeleitet, wenn nicht in der Anfrage zur Erstellung angegeben.
Die zulässigen Werte können Sie auch der Referenzdokumentation zu productCategory entnehmen.
product-display-name: Optional. Wenn Sie keinen Namen für das Produkt angeben, wird displayName auf " " gesetzt. Sie können diesen Wert später aktualisieren.
labels: Optional. Ein String (mit Anführungszeichen) von Schlüssel/Wert-Paaren, die die Produkte im Referenzbild beschreiben. Beispiel:
"category=shoes"
"color=black,style=formal"
Mit der Vision API-Produktsuche können Sie auch mehrere Werte für einen einzelnen Schlüssel angeben. Beispiel:
"category=shoes,category=heels"
"color=black,style=formal,style=mens"
bounding-poly: Optional. Definiert den Bereich im Referenzbild, der von Interesse ist. Wenn kein Begrenzungsrahmen angegeben wurde:
Begrenzungsrahmen für das Bild werden von der Vision API abgeleitet. Mehrere Bereiche in einem einzelnen Bild können indiziert werden, wenn mehrere Produkte von der API erkannt werden.
Das letzte Zeichen in der Zeile muss ein Komma sein.
In diesem Beispiel finden Sie ein Produkt, für das kein Begrenzungspolygon angegeben wurde.
Wenn Sie einen Begrenzungsrahmen angeben, muss die Spalte boundingPoly eine gerade Anzahl von durch Kommas getrennten Zahlen in diesem Format enthalten: p1_x,p1_y,p2_x,p2_y,...,pn_x,pn_y. Beispielzeile: 0.1,0.1,0.9,0.1,0.9,0.9,0.1,0.9.
Verwenden Sie nicht negative Ganzzahlen, um einen Begrenzungsrahmen mit den tatsächlichen Pixelwerten Ihres Bildes festzulegen. So können Sie einen Begrenzungsrahmen in Bildern mit 1.000 x 1.000 Pixeln ausdrücken:
In der Vision API-Produktsuche können Sie auch normalisierte Werte für Begrenzungsrahmen verwenden. Definieren Sie einen Markierungsrahmen mit normalisierten Werten mit Gleitkommawerten in [0, 1].
Bei Verwendung normalisierter Werte könnten die obigen Referenzbildzeilen auch so ausgedrückt werden:
[[["Leicht verständlich","easyToUnderstand","thumb-up"],["Mein Problem wurde gelöst","solvedMyProblem","thumb-up"],["Sonstiges","otherUp","thumb-up"]],[["Schwer verständlich","hardToUnderstand","thumb-down"],["Informationen oder Beispielcode falsch","incorrectInformationOrSampleCode","thumb-down"],["Benötigte Informationen/Beispiele nicht gefunden","missingTheInformationSamplesINeed","thumb-down"],["Problem mit der Übersetzung","translationIssue","thumb-down"],["Sonstiges","otherDown","thumb-down"]],["Zuletzt aktualisiert: 2025-08-19 (UTC)."],[],[],null,["# Formatting a bulk import CSV\n\nYou can use the [`import`](/vision/product-search/docs/reference/rest/v1/projects.locations.productSets/import)\nmethod to create a product set and products with reference images all at the\nsame time using a CSV file. This page describes how to format the CSV file.\n\nCreating your reference images\n------------------------------\n\nReference images are images containing various views of your products. The\nfollowing recommendations apply:\n\n- Make sure the size of the file doesn't exceed the maximum size (20MB).\n- Consider viewpoints that logically highlight the product and contain relevant visual information.\n- Create reference images that supplement any missing viewpoints. For example, if you only have images of the right shoe in a pair, provide mirrored versions of those files as the left shoe.\n- Upload the highest resolution image available.\n- Show the product against a white background.\n- Convert PNGs with transparent backgrounds to a solid background.\n\nImages must be stored in a [Cloud Storage](https://cloud.google.com/storage/)\nbucket. If you're authenticating your image create call with an API key, the bucket must be\npublic. If you're authenticating with a service account, that service account\nmust have read access on the bucket.\n\nCSV formatting guidelines\n-------------------------\n\nTo use the `import` method, both the CSV file *and* the images it points to\nmust be in a Cloud Storage bucket. CSV files are limited to a maximum of\n20,000 lines; each line is limited to a maximum of 2,048 characters. To import\nmore images, split them into multiple CSV files.\n\nThe CSV file must contain one image per line and contain the following columns:\n\n1. `image-uri`: The Cloud Storage URI of the reference image.\n2. `image-id`: ***Optional***. A unique value if you supply it. Otherwise, the system will assign a unique value.\n3. `product-set-id`: A unique identifier for the product set to import the images into.\n4. `product-id`: A user-defined ID for the product identified by the reference\n image. A `product-id` can be associated with multiple reference images.\n\n | **Note:** A single product may also belong to several product sets. If a `product-id` already exists on bulk import then `product-category`, `product-display`, and `labels` are ignored for that line entry.\n5. `product-category`: Allowed values are `homegoods-v2`, `apparel-v2`,\n `toys-v2`, `packagedgoods-v1`,\n and `general-v1`\n \\*;\n the category for the product identified by the\n reference image. Inferred by the system if not specified in the create\n request.\n Allowed values are also listed in the\n [`productCategory`](/vision/product-search/docs/reference/rest/v1/projects.locations.products#Product.FIELDS.product_category)\n reference documentation.\n\n \u003cbr /\u003e\n\n | **\\* Legacy `productCategory` codes:** Legacy categories (`homegoods`, `apparel`, and `toys`) are still supported, but the updated `-v2` categories should be used for new products.\n\n \u003cbr /\u003e\n\n6. `product-display-name`: ***Optional*** . If you don't provide a name for\n the product [`displayName`](/vision/product-search/docs/reference/rest/v1/projects.locations.products#Product.FIELDS.display_name)\n will be set to \" \". You can [update](/vision/product-search/docs/reference/rest/v1/projects.locations.products/patch) this value later.\n\n7. `labels`: ***Optional***. A string (with quotation marks) of key-value\n pairs that describe the products in the reference image. For example:\n\n - `\"category=shoes\"`\n - `\"color=black,style=formal\"`\n\n Vision API Product Search also allows you to provide multiple values for\n a single key. For example:\n - `\"category=shoes,category=heels\"`\n\n - `\"color=black,style=formal,style=mens\"`\n\n8. `bounding-poly`: ***Optional*** . Specifies the area of interest in the\n reference image. If a bounding box is **not** specified:\n\n 1. Bounding boxes for the image are inferred by the Vision API; multiple regions in a single image may be indexed if multiple products are detected by the API.\n 2. The line must end with a comma.\n\n See the example below for a product without a bounding poly specified.\n\n If you include a bounding box, the `boundingPoly` column should contain\n an even number of comma-separated numbers, with the format\n `p1_x,p1_y,p2_x,p2_y,...,pn_x,pn_y`. An example\n line looks like this: `0.1,0.1,0.9,0.1,0.9,0.9,0.1,0.9`.\n\n To define a bounding box with the actual pixel values of your image use\n non-negative integers. Thus, you could express bounding boxes in 1000 pixel\n by 1000 pixel images in the following way: \n\n gs://example-reference-images/10001-001/10001-001_A.jpg,img001,sample-set-summer,sample-product-123,tan summer bag,apparel-v2,\"style=womens,color=tan\",100,150,450,150,450,550,100,550\n gs://example-reference-images/10001-001/10001-001_A.jpg,img001,sample-set-summer,sample-product-456,blue summer bag,apparel-v2,\"style=womens,color=blue\",670,790,980,790,980,920,670,920\n gs://example-reference-images/10002-002/10002-002_B.jpg,img002,sample-set-summer,sample-product-123,apparel-v2,,,\n\n | **Note:** You can use Vision API's [Object Localizer](/vision/docs/detecting-objects) feature to get bounding box coordinates for generalized objects in images.\n\n Vision API Product Search also allows you to use normalized values for\n bounding boxes. Define a bounding box using normalized values with float\n values in \\[0, 1\\].\n\n Using normalized values, the above reference image rows could also be\n expressed as: \n\n gs://example-reference-images/10001-001/10001-001_A.jpg,img001,sample-set-summer,sample-product-123,tan summer bag,apparel-v2,\"style=womens,color=tan\",0.10,0.15,0.45,0.15,0.45,0.55,0.10,0.55\n gs://example-reference-images/10001-001/10001-001_A.jpg,img001,sample-set-summer,sample-product-456,blue summer bag,apparel-v2,\"style=womens,color=blue\",0.67,0.79,0.98,0.79,0.98,0.92,0.67,0.92\n gs://example-reference-images/10002-002/10002-002_B.jpg,img002,sample-set-summer,sample-product-123,apparel-v2,,,"]]
