Diese Recommendations AI-Dokumentation verweist auf die Recommendations Console. Wir empfehlen, zur Retail Console zu wechseln und die Dokumentation für Einzelhändler zu verwenden. Darin werden Recommendations AI, die Retail Console und Retail Search dokumentiert.

Wenn Sie die v1beta-Version von Recommendations AI verwenden, migrieren Sie zur Retail API-Version.

Empfehlungen abrufen

Auf dieser Seite wird beschrieben, wie Sie Empfehlungen für einen bestimmten Nutzer und Nutzerereignis anfordern.

Nachdem Sie Ihre Produkte hochgeladen und Nutzerereignisse aufgezeichnet haben, können Sie Produktempfehlungen für bestimmte Nutzer anfragen, die auf den aufgezeichneten Nutzerereignissen für diesen Nutzer und seiner aktuellen Aktivität basieren.

Recommendations AI gibt eine Liste der Produktkennzeichnungen mit Rang zurück. Du bist für das Rendern der Ergebnisse auf deiner Website mit Bildern und Text verantwortlich.

Speichern Sie keine personalisierten Ergebnisse von einem Endnutzer und geben Sie keine personalisierten Ergebnisse an einen anderen Endnutzer zurück.

Vorbereitung

Bevor Sie auf die Retail API zugreifen können, müssen Sie ein Google Cloud-Projekt erstellen und die Authentifizierung einrichten. Gehen Sie dazu wie unter Vorbereitung beschrieben vor.

Bevor Sie Vorhersagen von Recommendations AI anfordern können, benötigen Sie außerdem eine trainierte und fein abgestimmte Empfehlung (Modell) sowie mindestens ein aktives Placement.

Empfehlungsvorschau

Bevor Sie Ihren Websitecode zum Anfordern von Empfehlungen aktualisieren, können Sie mithilfe der Vorhersagevorschau prüfen, ob Ihr Modell wie erwartet funktioniert.

So sehen Sie eine Vorschau der vom Modell zurückgegebenen Empfehlungen an:

  1. Rufen Sie in der Google Cloud Console die Seite „Empfehlungen – KI-Modelle“ auf.
    Zur Seite „Recommendations AI-Modelle“

  2. Klicken Sie auf den Modellnamen, um die Detailseite zu öffnen.

  3. Klicken Sie auf die Platzierung, die Sie als Vorschau ansehen möchten.

  4. Optional: Geben Sie eine Nutzer-ID ein, um eine Vorschau der Ergebnisse für diesen Nutzer aufzurufen.

  5. Klicken Sie auf Vorhersagevorschau, um die Vorhersageergebnisse aufzurufen.

Vorhersagevorschau mit zurückgegebenen Beispielbildern

Empfehlung abrufen

Weitere Informationen zu den Kosten für Vorhersagen finden Sie unter Preise.

curl

Für eine Empfehlung senden Sie eine POST-Anfrage an die REST-Methode predict und geben Sie dazu den entsprechenden Anfragetext ein:

  • Das von Ihnen verwendete Dienstkonto muss die Rolle „Retail-Betrachter“ oder höher haben.

  • Ersetzen Sie PLACEMENT_ID durch die Platzierung, die Sie in Vorhersagen verwenden werden. Weitere Informationen zur Placement-ID finden Sie in der Referenzdokumentation unter placement.predict.

  • Wenn Sie Google Analytics 360-Nutzerereignisse mit BigQuery importiert haben, legen Sie für visitorId die Google Analytics-Client-ID fest. Weitere Informationen zum Abrufen der Client-ID finden Sie in der Google Analytics-Dokumentation.

  • Für einen A/B-Test legen Sie für experimentIds die ID dieser Testgruppe fest. Weitere Informationen.

  • Geben Sie ein Nutzerereignis-Objekt für die Nutzeraktion an, die die Empfehlungsanfrage eingeleitet hat.

    Beachten Sie, dass das Nutzereignis nicht aufgezeichnet wird. Es dient lediglich der Bereitstellung von Kontext für die Empfehlungsanfrage. Sie sollten das Nutzerereignis deshalb genauso aufzeichnen, wie Sie andere Nutzerereignisse in der Retail API aufzeichnen.

  • Optional können Sie einen Filter angeben, um die zurückgegebenen Produkte einzugrenzen. Weitere Informationen

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data '{
              "filter": "FILTER_STRING",
              "validateOnly": false,
              "userEvent": {
                "eventType": "detail-page-view",
                "visitorId": "VISITOR_ID",
                "userInfo": {
                    "userId": "USER_ID",
                    "ipAddress": "IP_ADDRESS",
                    "userAgent": "USER_AGENT"
                },
                "experimentIds": "EXPERIMENT_GROUP",
                "productDetails": [{
                    "product": {
                      "id": "PRODUCT_ID"
                   }
                }]
              }
            }' \
https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/placements/PLACEMENT_ID:predict

Die Ergebnisse sollten in etwa so aussehen:

{
  "results": [{"id": "sample-id-1"}, {"id": "sample-id-2"}],
  "attribution_token": "sample-atr-token"
}

Sie müssen den Wert attribution_token mit einer URL verknüpfen, die Sie als Ergebnis dieser Vorhersage bereitstellen, und ihn mit Nutzerereignissen für diese URLs zurückgeben. Weitere Informationen

Preis-Reranking

Beim Preis-Reranking werden die empfohlenen Produkte mit einer ähnlichen Empfehlungswahrscheinlichkeit nach Preis sortiert, wobei die Artikel mit dem höchsten Preis zuerst aufgelistet werden. Die Relevanz wird auch noch für die Bestellung von Artikeln verwendet. Das Aktivieren des Preis-Rerankings entspricht also nicht der Sortierung nach Preis.

Das Preis-Reranking kann auf der Ebene der Bereitstellungskonfiguration oder pro Vorhersageanfrage festgelegt werden.

Wenn Sie beim Erstellen eines Modells in der Cloud Console eine Einstellung für den Preis-Reranking auswählen, gilt diese Einstellung für alle von dieser Konfiguration bereitgestellten Empfehlungen. Sie müssen nichts weiter tun.

Wenn Sie das Preis-Reranking einer bestimmten Empfehlung festlegen möchten, verwenden Sie dazu die Retail API und das Feld PredictRequest.params. Dadurch wird jede Einstellung für das Reranking auf Modellebene überschrieben, die andernfalls für diese Empfehlung gelten würde.

Vielfalt der Empfehlungen

Die Diversifizierung beeinflusst, ob die von einer einzelnen Vorhersageanfrage zurückgegebenen Ergebnisse aus verschiedenen Kategorien Ihres Produktkatalogs stammen.

Die Diversifizierung kann auf der Ebene der Bereitstellung oder pro Vorhersageanfrage festgelegt werden.

Wenn Sie beim Erstellen eines Modells in der Cloud Console eine Diversifizierungseinstellung auswählen, wird diese Einstellung standardmäßig auf alle Empfehlungen angewendet, die von diesem Modell bereitgestellt werden, ohne dass Sie weitere Maßnahmen ergreifen müssen.

Wenn Sie die Diversifizierung einer bestimmten Empfehlung steuern müssen, können Sie dies über die Retail API mit dem Feld PredictRequest.params tun. Dadurch werden alle Diversifizierungseinstellungen auf Modellebene überschrieben, die andernfalls für diese Empfehlung gelten. Zulässige Werte finden Sie in der API-Dokumentation zu PredictRequest.params.

Empfehlungsfilter verwenden

Sie können die von Recommendations AI zurückgegebenen Empfehlungen filtern. Verwenden Sie dazu das Feld filter in der Methode predict.

Das Feld filter akzeptiert zwei Arten von Filterspezifikationen:

  • Tag-Ausdrücke

    Wenn Sie Ihren Produkten beim Hochladen tag-Werte hinzugefügt haben, können Sie festlegen, dass nur Produkte, die allen von Ihnen gefilterten Tags entsprechen, als Empfehlungen zurückgegeben werden. Informationen zum Feld Product.tags[] finden Sie in der API-Referenzdokumentation.

    Tag-Ausdrücke können die booleschen Operatoren OR oder NOT enthalten. Diese müssen von den Tag-Werten durch ein oder mehrere Leerzeichen getrennt sein. Den Tag-Werten können auch Bindestriche (-) vorangestellt werden. Dies entspricht dem Operator NOT. Tag-Ausdrücke, die boolesche Operatoren verwenden, müssen in Klammern stehen.

  • filterOutOfStockItems

    Das Flag filterOutOfStockItems filtert alle Produkte heraus, für die für stockState der Wert OUT_OF_STOCK gilt.

Sie können diese beiden Filtertypen kombinieren: Es werden dann nur Artikel zurückgegeben, die allen angegebenen Filterausdrücken entsprechen.

Beispiele für Filterstrings:

"filter": "tag=\"spring-sale\""
"filter": "filterOutOfStockItems"
"filter": "tag=\"spring-sale\" tag=\"exclusive\" filterOutOfStockItems"

Im folgenden Beispiel werden nur Artikel zurückgegeben, die auf Lager sind und entweder das Tag „spring-sale“ oder das Tag „exklusiv“ (oder beides) und nicht das Tag „items-to-Exclude“ enthalten.

"filter": "tag=(\"spring-sale" OR \"exclusive\") tag=(-\"items-to-exclude\") filterOutOfStockItems"

Benachrichtigungen für Empfehlungen festlegen

Die letzte Aufgabe für Empfehlungen ist es, Benachrichtigungen über Vorhersagefehler einzurichten. Sie werden benachrichtigt, falls die Vorhersagemethode Fehler zurückgibt, damit Sie bei Bedarf Maßnahmen ergreifen können. Weitere Informationen finden Sie unter Benachrichtigungen einrichten.