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 Vector Search für jedes Embedding speichern kann. So können Einbettungen mit nützlichem Kontext bereitgestellt werden, z. B.:

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

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

  • Nutzerinformationen für Nutzereinbettungen.

  • Koordinaten für Ortseinbettungen.

Wichtige Funktionen und Vorteile

Vorteile der Verwendung von Metadaten:

  • Kontext mit Ergebnissen: Informationen können direkt in den Suchergebnissen bereitgestellt werden. Dadurch sind keine separaten Suchvorgänge mehr erforderlich und die Wartezeit wird verkürzt.

  • Flexible Struktur: Metadaten werden als JSON-Objekt bereitgestellt, 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 Metadaten nur 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 für Funktionen wie die Anzeige von Rich-Suchergebnissen und die kontextbasierte Nachbearbeitung reduziert.

Datenformat

Ein optionales embedding_metadata-Feld enthält ein JSON-Objekt, mit dem sich umfangreiche, nicht filterbare Informationen flexibel mit Einbettungen in Vector Search verknüpfen lassen. Dadurch können Anwendungen optimiert werden, da der Kontext mit den Ergebnissen zurückgegeben wird. Außerdem sind effiziente reine Metadatenaktualisierungen mit update_mask für die upsertDatapoints API möglich.

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

Beim Hinzufügen von Datenpunkten 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. CSV wird für embedding_metadata nicht unterstützt.
  • Mit der upsertDatapoints API:
    • Übergeben Sie Datenpunktobjekte (einschließlich embedding_metadata) im Nutzlastteil der API-Anfrage.

embedding_metadata bei Abfragen abrufen

Wenn Sie eine standardmäßige Suche nach dem nächsten Nachbarn mit der findNeighbors API 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 wird aktualisiert

Aktualisieren Sie die Metadaten mit der upsertDatapoints API und einem 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.

Das Feld update_mask trägt dazu bei, dass nur embedding_metadata aktualisiert wird. So wird vermieden, dass Einschränkungs- und Einbettungsfelder noch einmal eingereicht werden müssen.

Im folgenden Beispiel wird gezeigt, wie Metadaten definiert und aktualisiert werden, um eine gezielte 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"}'