Vektorsuche nach Einbettungen mit Metadaten

Dieser Leitfaden enthält Informationen zu optionalen Metadaten für Vektoreinbettungen. Mit der Vektorsuche können Sie Metadaten für jede Einbettung definieren.

Metadaten sind nicht filterbare, beliebige Informationen, die von der Vektorsuche für jede Einbettung gespeichert werden können. So können Einbettungen mit nützlichem Kontext versehen werden, z. B.:

  • Produktdetails wie Name, Preis und eine Bild-URL.

  • Beschreibungen, Snippets, Datumsangaben und Autorenschaft für Texteinbettungen.

  • Nutzerinformationen für Nutzereinbettungen.

  • Koordinaten für Orteinbettungen.

Wichtige Funktionen und Vorteile

Zu den Funktionen und Vorteilen der Verwendung von Metadaten gehören:

  • Kontext mit Ergebnissen: Informationen können direkt in den Suchergebnissen bereitgestellt werden. Dadurch sind keine separaten Suchvorgänge erforderlich und die Latenz wird reduziert.

  • Flexible Struktur: Metadaten werden als JSON-Objekt, sodass sie als komplexe, verschachtelte Daten definiert werden können.

  • Nicht filterbar: Metadaten für Vektoreinbettungen dienen zum Speichern und Abrufen von nicht filterbaren Informationen, die sich von restricts und numeric_restricts unterscheiden.

  • Effiziente Aktualisierungen: Mit dem Feld update_mask können Sie angeben, dass APIs nur Metadaten aktualisieren, um das erneute Senden von Einbettungsvektoren zu vermeiden.

  • Entkoppelte Informationen: Nicht filterbare Informationen können von filterbaren Attributen wie restricts getrennt werden.

  • Optimierte Entwicklung: Suchantworten enthalten Metadaten, die mit einer Vektoreinbettung verknüpft sind. Gleichzeitig wird die Komplexität reduziert, die für Funktionen wie die Anzeige von Rich-Suchergebnissen und die kontextbasierte Nachbearbeitung erforderlich ist.

Datenformat

Ein optionales Feld embedding_metadata enthält ein JSON-Objekt, mit dem sich Rich-Informationen, die nicht filterbar sind, flexibel mit Einbettungen in der Vektorsuche verknüpfen lassen. Dadurch können Anwendungen optimiert werden, indem Kontext mit Ergebnissen zurückgegeben wird. Außerdem lassen sich mit update_mask für die upsertDatapoints API effizient nur Metadaten aktualisieren.

Beispiel für die Struktur eines Datenpunkts:

    {
        "id": "movie_001",
        "embedding": [0.1, 0.2, ..., 0.3],
        "sparse_embedding": {
            "values": [-0.4, 0.2, -1.3],
            "dimensions": [10, 20, 30]
        },
        "numeric_restricts": [{'namespace': 'year', 'value_int': 2022}],
        "restricts": [{'namespace': 'genre', 'allow': ['action', 'comedy']}],

        # --- New embedding_metadata field ---
        "embedding_metadata": {
            "title": "Ballet Train",
            "runtime": {
                "hours": 2,
                "minutes": 6
            },
            "review_info": {
                "review": "This movie is fun and...",
                "rotten_potatoes_rating": 76
            }
        }
        # ------------------------------------
    },
    # ... other data points

Daten mit embedding_metadata aufnehmen

Wenn Sie Datenpunkte hinzufügen, können Sie embedding_metadata einfügen, wenn eine der folgenden Aktionen ausgeführt wird:

  • Datei hochladen (Cloud Storage):
    • Verwenden Sie die Formate JSON oder AVRO formats. CSV wird für embedding_metadata nicht unterstützt.
  • Die upsertDatapoints API verwenden:
    • Übergeben Sie Datenpunktobjekte (einschließlich embedding_metadata) in der Nutzlast der API-Anfrage.

embedding_metadata bei Abfragen abrufen

Wenn Sie mit der findNeighbors API eine Standardsuche nach den nächsten Nachbarn durchführen, wird das Feld embedding_metadata für jeden Nachbarn automatisch in die Antwort aufgenommen , wenn returnFullDatapoint auf True gesetzt ist.

curl

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://${PUBLIC_ENDPOINT_DOMAIN}/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexEndpoints/${INDEX_ENDPOINT_ID}:findNeighbors" \
-d '{deployedIndexId:"${DEPLOYED_INDEX_ID}", "queries":[{datapoint:{"featureVector":"<FEATURE_VECTOR>"}}], returnFullDatapoint:true}'

embedding_metadata aktualisieren

Aktualisieren Sie Metadaten mit der upsertDatapoints API und einer update_mask mit dem Wert embedding_metadata. Das Feld update_mask kann auch zusätzliche Maskenwerte enthalten. Informationen zur Verwendung einer Feldmaske finden Sie unter Metadaten für Einbettungen aktualisieren.

Mit dem Feld update_mask lässt sich sicherstellen, dass nur embedding_metadata aktualisiert wird. So wird das erneute Senden von Einschränkungs- und Einbettungsfeldern vermieden.

Im folgenden Beispiel wird gezeigt, wie Sie Metadaten definieren und aktualisieren, um einen gezielten IndexDatapoint zu erstellen, update_mask anzugeben und upsertDatapoints aufzurufen.

curl

curl -H "Content-Type: application/json" -H "Authorization: Bearer `gcloud auth print-access-token`" https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/indexes/${INDEX_ID}:upsertDatapoints \
-d '{
datapoints:[
    {
        datapoint_id: "'${DATAPOINT_ID_1}'",
        feature_vector: [...],
        embedding_metadata:{"title": "updated title", "rating": 4.5, "tags": ["updated", "reviewed"]
    }, update_mask: "embedding_metadata"}'