Vertex Matching Engine verwenden

In dieser Anleitung wird erläutert, wie Vertex Matching Engine konfiguriert und verwendet wird, um Vektorähnlichkeitssuchen durchzuführen.

VPC-Netzwerk-Peering-Verbindung einrichten

Wenn Sie die Netzwerklatenz für Vektorabgleiche von Onlineabfragen reduzieren möchten, rufen Sie über den privaten Dienstzugriff die Vertex AI-Dienstendpunkte von Ihrer VPC auf. Für jedes Google Cloud-Projekt kann nur ein VPC-Netzwerk über Peering mit Matching Engine verbunden werden. Wenn Sie bereits eine VPC mit konfiguriertem privatem Dienstzugriff haben, können Sie diese VPC für das Peering mit Vertex Matching Engine verwenden.

Das Konfigurieren einer VPC-Netzwerk-Peering-Verbindung ist eine anfängliche Aufgabe, die nur einmal pro Google Cloud-Projekt erforderlich ist. Nach Abschluss der Einrichtung können Sie den Matching Engine-Index von jedem Client aus aufrufen, der in Ihrer VPC ausgeführt wird.

Die VPC-Netzwerk-Peering-Verbindung ist nur für Vektorabgleiche von Onlineabfragen erforderlich. API-Aufrufe zum Erstellen, Bereitstellen und Löschen von Indexen erfordern keine VPC-Netzwerk-Peering-Verbindung.

Bitten Sie Ihren Google Cloud-Projektadministrator oder Netzwerkadministrator, die folgenden Schritte auszuführen:

  1. Führen Sie diese Schritte aus, um Ihr Google Cloud-Projekt einzurichten, die Abrechnung zu aktivieren und APIs zu aktivieren.

  2. Bevor Sie eine private Verbindung erstellen, müssen Sie einen IP-Adressbereich zuweisen, der vom Matching Engine-Dienst verwendet werden soll. Dadurch wird sichergestellt, dass kein IP-Adressenkonflikt zwischen Ihrem VPC-Netzwerk und dem Netzwerk unseres Diensterstellers auftritt, in dem die Matching Engine-Indexe bereitgestellt werden. Weitere Dokumente finden Sie hier.

    # NOTE: `prefix-length=16` means a CIDR block with mask /16 will be reserved
# for use by Google services. Make sure to enable Service Networking API.
gcloud compute addresses create $PEERING_RANGE_NAME \
  --global \
  --prefix-length=16 \
  --description="peering range for Matching Engine service" \
  --network=$NETWORK_NAME \
  --purpose=VPC_PEERING \
  --project=$PROJECT_ID

    # Create the VPC connection.
gcloud services vpc-peerings connect \
  --service=servicenetworking.googleapis.com \
  --network=$NETWORK_NAME \
  --ranges=$PEERING_RANGE_NAME \
  --project=$PROJECT_ID

Beispiel-Notebook

Nachdem Sie die Ersteinrichtung des VPC-Netzwerk-Peerings abgeschlossen haben, können Sie innerhalb dieser VPC eine Notebook-Instanz erstellen und Befehle über das Notebook ausgeben.

Starten Sie das Beispiel-Notebook in Notebooks oder rufen Sie das Notebook in GitHub auf.

Zugriffssteuerung

Vertex AI verwendet Identity and Access Management (IAM) zur Verwaltung des Zugriffs auf Ressourcen. Wenn Sie Zugriff auf eine Ressource gewähren möchten, weisen Sie einem Nutzer, einer Gruppe oder einem Dienstkonto mindestens eine Rolle zu.

Zur Verwendung von Matching Engine verwenden Sie diese vordefinierten Rollen, um auf Projektebene unterschiedliche Zugriffsrechte auf Ressourcen zu gewähren.

Format und Struktur von Eingabedaten

In diesem Abschnitt werden die Struktur und das Format beschrieben, in denen Vektoren für Matching Engine bereitgestellt werden sollten, um entweder einen neuen Index zu erstellen oder einen vorhandenen Index zu aktualisieren.

Speicher für Eingabedaten

Speichern Sie Ihre Eingabedaten in einem Cloud Storage-Bucket in Ihrem Google Cloud-Projekt.

Eingabeverzeichnisstruktur

In diesem Abschnitt wird erläutert, wie Sie das Eingabedatenverzeichnis strukturieren.

  • Batch-Stammverzeichnis: Erstellen Sie ein Stammverzeichnis für jeden Batch von Eingabedatendateien. Dies sollte ein einzelnes Cloud Storage-Verzeichnis sein, das in diesem Beispiel batch_root heißt.

  • Benennung von Dateien: Platzieren Sie einzelne Datendateien direkt unter batch_root und benennen Sie sie mit den folgenden Suffixen: .csv, .json oder .avro. Je nachdem, welches Dateiformat Sie verwenden.

    • Matching Engine interpretiert jede Datendatei als eine Gruppe von Einträgen.

      Das Format des Eintrags wird durch das Suffix des Dateinamens bestimmt und in einem der folgenden Abschnitte beschrieben.

    • Jeder Datensatz sollte eine ID und einen Featurevektor enthalten, optional mit zusätzlichen Feldern wie Einschränkungen und Crowding.

  • Verzeichnis löschen: Sie können ein Unterverzeichnis delete unter batch_root erstellen. Dieses Verzeichnis ist optional.

    • Jede Datei direkt unter batch_root/delete ist eine Textdatei mit Datensatz-IDs, mit einer ID in jeder Zeile. Jede ID muss ein gültiger UTF-8-String sein.

  • Alle anderen Verzeichnisse und Dateien werden ignoriert.

  • Alle Datensätze aus allen Datendateien, einschließlich der Datensätze unter delete, enthalten einen einzelnen Einabebatch. Die relative Reihenfolge der Datensätze innerhalb einer Datendatei ist unerheblich.

  • Eine einzelne ID sollte nur einmal in einem Batch auftauchen.

    • Hinweis: Eine ID darf auch nicht gleichzeitig in einer regulären Datendatei und einer delete-Datendatei enthalten sein.

  • Alle IDs aus einer Datendatei unter delete führen dazu, dass sie aus der nächsten Indexversion entfernt werden. Datensätze aus regulären Datendateien werden in die nächste Version aufgenommen, wobei ein Wert in einer älteren Indexversion möglicherweise überschrieben wird.

Datendateiformate

In diesem Abschnitt werden die Formatanforderungen für die einzelnen Datendateien beschrieben. Die Datendateien können CSV-, JSON- oder Avro-Dateien sein.

CSV

  • Codieren Sie die Datei mit UTF-8.
  • Jede Zeile muss eine gültige CSV sein und wird als einzelner Datensatz interpretiert.
  • Der erste Wert sollte die id sein. Es muss ein gültiger UTF-8-String sein.
  • Die nächsten N Werte sollten der Featurevektor sein. N ist die Dimension des Featurevektors und sollte beim Erstellen eines Index konfiguriert werden. Jeder Wert sollte ein Gleitkommaliteral sein, wie in der Java-Sprachspezifikation definiert.

JSON

  • Die Datei muss UTF-8-codiert sein.
  • Jede Zeile muss ein gültiges JSON-Objekt sein, das als Eintrag interpretiert wird.
  • Jeder Eintrag muss ein Feld mit dem Namen id haben. Dies ist die ID des Vektors. Es muss ein gültiger UTF-8-String sein.
  • Jeder Eintrag muss ein Feld mit dem Namen embedding enthalten und ein Array von Zahlen sein. Dies ist der Featurevektor.

AVRO

  • Die Datei muss eine gültige Avro-Datei sein.

  • Avro-Einträge sollten eine ähnliche Struktur haben wie im JSON-Format definiert. Insbesondere sollte dem folgenden Schema entsprochen werden:

    {
   "type": "record",
   "name": "FeatureVector",
   "fields": [
      {"name": "id", "type": "string"},
      {"name": "embedding",
       "type": {
          "type": "array",
          "items": "float"
        }
      }
   ]
}

Indexe verwalten

In diesem Abschnitt wird beschrieben, wie Sie Indexe erstellen, löschen oder aktualisieren. Siehe API-Dokumente für Indexe.

Index-Metadatendatei

Bevor Sie einen Index erstellen, müssen Sie die Parameter für Ihren Index konfigurieren.

Erstellen Sie beispielsweise eine Datei mit dem Namen index_metadata.json:

{
  "contentsDeltaUri": "gs://BUCKET_NAME/path",
  "config": {
    "dimensions": 100,
    "approximateNeighborsCount": 150,
    "distanceMeasureType": "DOT_PRODUCT_DISTANCE",
    "algorithm_config": {
      "treeAhConfig": {
        "leafNodeEmbeddingCount": 500,
        "leafNodesToSearchPercent": 7
      }
    }
  }
}

Sie finden die Definition für jedes dieser Felder unter Indexe konfigurieren oder Sie rufen die Definitionen im folgenden Schema auf:

title: NearestNeighborSearch
type: object
properties:
  contentsDeltaUri:
    type: string
    description: >
      Allows inserting, updating  or deleting the contents of the Matching Engine Index.
      The string must be a valid Cloud Storage directory path. If this
      field is set when calling IndexService.UpdateIndex, then no other
      Index field can be also updated as part of the same call.
      The expected structure and format of the files this URI points to is
      described at https://cloud.google.com/vertex-ai/docs/matching-engine/using-matching-engine#input-data-format
    writeOnly: true
  isCompleteOverwrite:
    type: boolean
    description: >
      If this field is set together with contentsDeltaUri when calling IndexService.UpdateIndex,
      then existing content of the Index will be replaced by the data from the contentsDeltaUri.
    default: false
  config:
    type: object
    description: >
      The configuration of the Matching Engine Index.
    required:
    - dimensions
    - algorithmConfig
    properties:
      dimensions:
        type: integer
        format: int32
        description: >
          The number of dimensions of the input vectors.
      approximateNeighborsCount:
        type: integer
        format: int32
        description: >
          The default number of neighbors to find via approximate search before exact reordering is
          performed. Exact reordering is a procedure where results returned by an
          approximate search algorithm are reordered via a more expensive distance computation.
          Required if tree-AH algorithm is used.
      distanceMeasureType:
        description: >
          The distance measure used in nearest neighbor search.
        oneOf:
        - enum: [SQUARED_L2_DISTANCE]
          description: >
            Euclidean (L_2) Distance
        - enum: [L1_DISTANCE]
          description: >
            Manhattan (L_1) Distance
        - enum: [COSINE_DISTANCE]
          description: >
            Cosine Distance. Defined as 1 - cosine similarity.
        - enum: [DOT_PRODUCT_DISTANCE]
          description: >
            Dot Product Distance. Defined as a negative of the dot product
        default: DOT_PRODUCT_DISTANCE
      featureNormType:
        description: >
          Type of normalization to be carried out on each vector.
        oneOf:
        - enum: [UNIT_L2_NORM]
          description: >
            Unit L2 normalization type.
        - enum: [NONE]
          description: >
            No normalization type is specified.
        default: NONE
      algorithmConfig:
        description: >
          The configuration with regard to the algorithms used for efficient search.
        oneOf:
        - type: object
          description: >
             Configuration options for using the tree-AH algorithm (Shallow tree + Asymmetric Hashing).
             Please refer to this paper for more details: https://arxiv.org/abs/1908.10396
          properties:
            type:
              type: string
              enum: [treeAhConfig]
            leafNodeEmbeddingCount:
              type: integer
              format: int64
              description: >
                 Number of embeddings on each leaf node. The default value is 1000 if not set.
            leafNodesToSearchPercent:
              type: number
              format: int32
              description: >
                 The default percentage of leaf nodes that any query may be searched. Must be in
                 range 1-100, inclusive. The default value is 10 (means 10%) if not set.
        - type: object
          description: >
             Configuration options for using brute force search, which simply implements the
             standard linear search in the database for each query.
          properties:
            type:
              type: string
              enum: [bruteForceConfig]
        discriminator:
          propertyName: type

Diese Metadaten-Schemadatei kann aus Cloud Storage heruntergeladen werden.

Index erstellen

So erstellen Sie einen Index:

  1. Indexmetadaten definieren

  2. Senden Sie die Anfrage mit gcloud beta ai indexes create:

    gcloud beta ai indexes create \
  --display-name=INDEX_NAME \
  --description=test \
  --metadata-file=LOCAL_PATH_TO_METADATA_FILE \
  --project=PROJECT_ID \
  --region=us-central1

Alternativ haben wir den folgenden curl-API-Beispielaufruf gezeigt, bei dem die Indexmetadaten direkt übergeben werden:

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer `gcloud auth print-access-token`" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexes \
-d '{
    displayName: "'${DISPLAY_NAME}'",
    description: "'${DESCRIPTION}'",
    metadata: {
       contentsDeltaUri: "'${INPUT_DIR}'",
       config: {
          dimensions: 100,
          approximateNeighborsCount: 150,
          distanceMeasureType: "DOT_PRODUCT_DISTANCE",
          algorithm_config: {
          treeAhConfig: {
            leafNodeEmbeddingCount: 500,
            leafNodesToSearchPercent: 7
            }
          }
       }
    }
}'

Hier sehen Sie die Beispielausgabe:

{
  "name": "projects/xxx/locations/us-central1/indexes/xxxx/operations/yyyy",
  "metadata": {...}
}

Sehen Sie sich die Vorgangsausgabe an und suchen Sie die Zeile mit "name": "projects/xxxx/locations/us-central1/indexes/xxx/operations/yyyy". Der Teil yyyy ist Ihre Vorgangs-ID. Fragen Sie den Vorgang ab, bis er erfolgreich abgeschlossen wurde. Warten Sie, bis "done": true in der Antwort enthalten ist.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexes/xxxx/operations/yyyy"

Indexe auflisten

Führen Sie zum Auflisten der Indexe gcloud beta ai indexes list aus:

gcloud beta ai indexes list \
  --project=PROJECT_ID \
  --region=us-central1

Indexinhalt aktualisieren

Mit der Methode IndexService.UpdateIndex können Sie den Inhalt eines vorhandenen Index aktualisieren.

So ersetzen Sie den vorhandenen Inhalt eines Index:

  • Setzen Sie Index.metadata.contentsDeltaUri auf den Cloud Storage-URI, der die zu aktualisierenden Vektoren enthält.
  • isCompleteOverwrite auf „true“ festlegen.

Wenn Sie das Feld contentsDeltaUri beim Aufruf von IndexService.UpdateIndex festlegen, können keine anderen Indexfelder (z. B. displayName, description oder userLabels) im Rahmen desselben Aufrufs aktualisiert werden.

Hier ist ein Beispiel für einen curl API-Aufruf:

curl -X PATCH -H "Content-Type: application/json" \
-H "Authorization: Bearer `gcloud auth print-access-token`" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexes/${INDEX_ID} \
-d '{
   metadata: {
       contentsDeltaUri: "'${INPUT_DIR}'",
       isCompleteOverwrite: <true|false>
    },
}'

Genauso wie beim Erstellen eines Index fragen Sie den vom UpdateIndex-Aufruf zurückgegeben Vorgang so lange ab, bis der Vorgang erfolgreich abgeschlossen ist.

Wenn im Index verknüpfte Bereitstellungen vorhanden sind (siehe Feld Index.deployed_indexes) und bestimmte Änderungen am ursprünglichen Index vorgenommen werden, wird der DeployedIndex im Hintergrund automatisch asynchron aktualisiert, um diese Änderungen widerzuspiegeln.

Vergleichen Sie die Endzeit des Vorgang zur Indexaktualisierung mit der DeployedIndex.index_sync_time, um zu prüfen, ob die Änderung übernommen wurde.

Index löschen

Sie können den Index nicht löschen, bis die Bereitstellung aller Index.deployed_indexes aufgehoben wurde.

curl -X DELETE -H "Content-Type: application/json" \
-H "Authorization: Bearer `gcloud auth print-access-token`" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexes/${INDEX_ID}

Indexe bereitstellen und verwalten

Die Bereitstellung eines Index besteht aus den folgenden drei Aufgaben:

  1. Erstellen Sie bei Bedarf einen IndexEndpoint oder verwenden Sie einen vorhandene IndexEndpoint.
  2. Rufen Sie die ID IndexEndpoint ab.
  3. Stellen Sie den Index auf dem IndexEndpoint bereit.

Erstellen Sie einen IndexEndpoint in Ihrem VPC-Netzwerk.

Bevor Sie einen Index zum Bereitstellen von Onlineabfragen für den Vektorabgleich verwenden können, müssen Sie den Index auf einem IndexEndpoint innerhalb Ihres VPC-Netzwerk-Peering-Netzwerks bereitstellen. Daher muss im ersten Schritt ein IndexEndpoint erstellt werden. Sie können mehr als einen Index auf einem IndexEndpoint bereitstellen, der dasselbe VPC-Netzwerk verwendet.

Hier ist ein Beispiel für einen curl API-Aufruf:

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer `gcloud auth print-access-token`" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexEndpoints \
-d '{
    display_name: "'${DISPLAY_NAME}'",
    network: "'${VPC_NETWORK_NAME}'",
}'

Hier sehen Sie die Beispielausgabe:

{
  "name": "projects/xxx/locations/us-central1/indexEndpoints/xxxx/operations/yyyy",
  "metadata": {...}
}

Sehen Sie sich die Vorgangsausgabe an und suchen Sie die Zeile mit "name": "projects/xxxx/locations/us-central1/indexEndpoints/xxx/operations/yyyy". Der Teil yyyy ist Ihre Vorgangs-ID. Fragen Sie den Vorgang ab, bis er erfolgreich abgeschlossen wurde. Warten Sie, bis "done": true in der Antwort enthalten ist.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexEndpoints/xxxx/operations/yyyy"

Index bereitstellen

So stellen Sie einen Index bereit:

curl -H "Content-Type: application/json" \
-H "Authorization: Bearer `gcloud auth print-access-token`" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexEndpoints/${INDEX_ENDPOINT_ID}:deployIndex \
-d '{
  deployedIndex: {
    id: "'${DEPLOYED_INDEX_ID}'",
    index: "'${INDEX_RESOURCE_NAME}'",
    displayName: "'${DISPLAY_NAME}'"
  }
}'

Wie bei anderen Vorgängen rufen Sie die Vorgangs-ID aus der Antwort ab und verwenden diese, um den Vorgang abzufragen, bis der Vorgang abgeschlossen ist.

Automatische Skalierung aktivieren

Matching Engine unterstützt Autoscaling, mit dem die Anzahl der Knoten automatisch an die Anforderungen Ihrer Arbeitslasten angepasst werden kann. Bei hoher Nachfrage werden Knoten dem Knotenpool hinzugefügt (überschreiten aber die von Ihnen festgelegte maximale Größe nicht). Bei geringer Nachfrage wird der Knotenpool wieder auf eine von Ihnen festgelegte Mindestgröße herunterskaliert. Sie können die tatsächlich verwendeten Knoten und die Änderungen prüfen, wenn Sie die aktuellen Replikate überwachen.

Um das Autoscaling zu aktivieren, geben Sie beim Bereitstellen des Index maxReplicaCount und minReplicaCount an:

curl -H "Content-Type: application/json" \
-H "Authorization: Bearer `gcloud auth print-access-token`" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexEndpoints/${INDEX_ENDPOINT_ID}:deployIndex \
-d '{
  deployedIndex: {
    id: "'${DEPLOYED_INDEX_ID}'",
    index: "'${INDEX_RESOURCE_NAME}'",
    displayName: "'${DISPLAY_NAME}'"
    automaticResources: {
      minReplicaCount: 2,
      maxReplicaCount: 5
    }
  }
}'
  • Wenn minReplicaCount und maxReplicaCount nicht festgelegt sind, werden sie standardmäßig auf 1 gesetzt.
  • Wenn nur maxReplicaCount festgelegt ist, wird minReplicaCount standardmäßig auf 1 gesetzt.
  • Wenn nur minReplicaCount festgelegt ist, wird maxReplicaCount entsprechend minReplicaCount festgelegt.

IndexEndpoints auflisten

Führen Sie den folgenden Befehl aus, um Ihre IndexEndpoints aufzulisten und die Informationen zu allen zugehörigen DeployedIndex-Instanzen aufzurufen:

curl -H "Content-Type: application/json" \
-H "Authorization: Bearer `gcloud auth print-access-token`" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexEndpoints

Hier ist die Antwort:

{
  "indexEndpoints": [
    {
      "name": "projects/<ProjectId>/locations/us-central1/indexEndpoints/<IndexEndpoingId>",
      "displayName": "...",
      "deployedIndexes": [
        {
          "id": "<user specified deployed index id>",
          "index": "projects/<ProjectId>/locations/us-central1/indexes/<IndexId>",
          "displayName": "demo",
          "createTime": "2021-06-18T00:19:13.242212Z",
          "privateEndpoints": {
            "matchGrpcAddress": "10.29.2.5"
          },
          "indexSyncTime": "2021-08-13T19:52:48.671205Z",
          "automaticResources": {
            "minReplicaCount": 1,
            "maxReplicaCount": 1
          }
        }
        ...
      ],
      "etag": "AMEw9yP9cMX3cjWFRuyLqI6YbB2UQcb-OU3tMwx9_B2p_MUiMlsMKPWX5KCphr1vbyiv",
      "createTime": "2021-06-18T00:16:59.320793Z",
      "updateTime": "2021-06-18T00:16:59.850034Z",
      "network": "projects/<ProjectId>/global/networks/<NetworkId>"
    },
    ...
  ]
}

Weitere Informationen finden Sie in der Referenzdokumentation zu IndexEndpoint.

Bereitstellung eines Index aufheben

Mit dem folgenden Befehl heben Sie die Bereitstellung eines Index auf:

curl -H "Content-Type: application/json"  \
-H "Authorization: Bearer `gcloud auth print-access-token`" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexEndpoints/${INDEX_ENDPOINT_ID}:undeployIndex \
-d '{
  deployed_index_id: "'${DEPLOYED_INDEX_ID}'",
}'

IndexEndpoint löschen

Bevor Sie einen IndexEndpoint löschen, müssen Sie alle zugehörigen Indexe aufheben.

curl -X DELETE -H "Content-Type: application/json" \
-H "Authorization: Bearer `gcloud auth print-access-token`" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexEndpoints/${INDEX_ENDPOINT_ID}

Indexe zum Abrufen der nächsten Nachbarn abfragen

Jeder DeployedIndex hat eine DEPLOYED_INDEX_SERVER_IP, die Sie durch Auflisten von IndexEndpoints abrufen können. Zum Abfragen eines DeployedIndex stellen Sie eine Verbindung zu der zugehörigen IP-Adresse DEPLOYED_INDEX_SERVER_IP an Port 10000 her und rufen die Methode MatchRequest oder BatchMatchRequest auf.

Im folgenden Beispiel wird grpc_cli verwendet.

./grpc_cli call ${DEPLOYED_INDEX_SERVER_IP}:10000 google.cloud.aiplatform.container.v1.MatchService.BatchMatch 'requests: [{deployed_index_id: "<deployed index id 1>", requests: [{deployed_index_id: "<deployed index id 1>", float_val: [-0.1,..<your query input>]}, {deployed_index_id: "<deployed index id 1>", float_val: [-0.1,..<your query input>]}]}]'

Aufrufe an diese APIs sollten von einem Client aus erfolgen, der in derselben VPC ausgeführt wird, zu der eine Peering-Verbindung des Dienstes hergestellt wurde.

Sie können ein Beispiel-Notebook starten, das zusätzliche Anleitungen zum Erstellen der Abfragen enthält, und es in Notebooks ausführen.

Index feinabstimmen

In diesem Abschnitt werden die Konfigurationsparameter beschrieben, die sich auf die Leistung, insbesondere Recall und Latenz, von bereitgestellten Indexen auswirken. Diese Parameter werden beim Erstellen des Index festgelegt. Außerdem wird erläutert, wie Sie Brute-Force-Indexe zur Messung des Recalls verwenden.

Konfigurationsparameter, die sich auf Recall und Latenz auswirken:

1) 'distanceMeasureType'

Folgende Werte werden unterstützt:

  • SQUARED_L2_DISTANCE – Euklidische L2-Distanz
  • L1_DISTANCE – Manhattan L1-Distanz
  • COSINE_DISTANCE – Kosinus-Distanz, definiert als "1 – Kosinus-Ähnlichkeit"
  • DOT_PRODUCT_DISTANCE – vDot-Produkt-Distanz, definiert als negativer Wert des Skalarprodukts. Dies ist der Standardwert.

In den meisten Fällen werden die Einbettungsvektoren, die zur Ermittlung von näherungsweisen Übereinstimmungen verwendet werden, mithilfe von Metric Learning-Modellen berechnet, die auch als "Siamese-Netzwerke" oder "Two-Tower-Modelle" bezeichnet werden. Diese Modelle verwenden einen Distanzmesswert, um die Kontrastverlustfunktion zu berechnen. Idealerweise sollte der Parameter distanceMeasureType für den Matching-Index dem Distanzmesswert entsprechen, der von dem Modell verwendet wurde, mit dem die Einbettungsvektoren berechnet wurden.

2) approximateNeighborsCount

Die Standardanzahl der Neighbors, die über die ungefähre Suche gefunden werden soll, bevor die genaue Neusortierung ausgeführt wird. Bei der genauen Neusortierung werden Ergebnisse, die von einem ungefähren Suchalgorithmus zurückgegeben werden, über eine aufwändigere Entfernungsberechnung neu angeordnet. Durch Erhöhen dieses Werts wird der Recall erhöht, es kann jedoch auch ein proportionaler Anstieg der Latenz erfolgen.

3) treeAhConfig.leafNodesToSearchPercent

Der Prozentsatz der Blätter, die für jede Abfrage gesucht werden sollen. Durch Erhöhen dieses Werts wird der Recall erhöht, es kann jedoch auch ein proportionaler Anstieg der Latenz erfolgen. Der Standardwert ist 10, d. h., wir suchen nach 10 % der Blätter.

4) treeAhConfig.leafNodeEmbeddingCount

Die Anzahl der Einbettungen für jeden Blattknoten. Standardmäßig ist dies auf 1000 eingestellt.

Dieser Parameter hat keine lineare Korrelation zum Recall. Durch Erhöhen oder Verringern des Werts wird der Recall nicht immer erhöht oder verringert. Für jeden Anwendungsfall gibt es in der Regel eine Optimierung, die möglicherweise etwas Experimentieren erfordert. Im Allgemeinen sind die Auswirkungen dieses Parameters jedoch niedriger als die Auswirkungen der anderen Parameter.

Brute-Force-Index zum Messen des Recalls verwenden

Indexe mit dem Brute-Force-Algorithmus können verwendet werden, um die nächstgelegenen Neighbors zu ermitteln, was zu einem Recall von 100 % führt, auf Kosten einer höheren Latenz. Dies ist in der Regel keine gute Wahl für Produktionsbereitstellungen, kann jedoch nützlich sein, wenn Sie beispielsweise den Recall verschiedener Indexierungsoptionen offline prüfen möchten.

Wenn Sie einen Index mit dem Brute-Force-Algorithmus erstellen möchten, geben Sie brute_force_config in den Index-Metadaten an:

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer `gcloud auth print-access-token`" \
https://us-central1-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/us-central1/indexes \
-d '{
    displayName: "'${DISPLAY_NAME}'",
    description: "'${DESCRIPTION}'",
    metadata: {
       contentsDeltaUri: "'${INPUT_DIR}'",
       config: {
          dimensions: 100,
          approximateNeighborsCount: 150,
          distanceMeasureType: "DOT_PRODUCT_DISTANCE",
          featureNormType: "UNIT_L2_NORM",
          algorithmConfig: {
             bruteForceConfig: {}
          }
       },
    },
}'

Das Beispielnotebook veranschaulicht die Verwendung eines "Brute Force"-Index zum Messen des Recalls.

IndexEndpoint überwachen

Wir bieten zwei Messwerte zum Monitoring von IndexEndpoint:

  • aiplatform.googleapis.com/matching_engine/current_shards

    Die Anzahl der Fragmentierungen von DeployedIndex. Nachdem Daten hinzugefügt und gelöscht wurden, passt Matching Engine den Index automatisch neu an, um eine optimale Leistung zu erzielen. Dieser Messwert gibt die aktuelle Anzahl der Fragmentierungen des bereitgestellten Index an.

  • aiplatform.googleapis.com/matching_engine/current_replicas

    Die Anzahl der aktiven Replikate, die von DeployedIndex verwendet werden. Matching Engine skaliert Replikatserver automatisch hoch und herunter (je nachdem, welche minimalen und maximalen Replikateinstellungen Sie beim Erstellen des Index festgelegt haben), um das Abfragevolumen zu erreichen. Dieser Messwert gibt die Gesamtzahl der Replikatserver an. Wenn der Index mehrere Shards hat, kann jeder Shard mit einer anderen Anzahl von Replikaten bereitgestellt werden. Dieser Messwert gibt die Gesamtzahl der Replikate in allen Shards des jeweiligen Index an.

Weitere Informationen zum Auswählen, Abfragen und Anzeigen dieser Messwerte in Metrics Explorer.

Kontingente

Weitere Informationen zu Vertex Matching Engine-Kontingenten und zum Anfordern von Kontingenterhöhungen.

FAQ

Wie viele IP-Adressen sollte ich reservieren?

Wenn Sie in Bezug auf den IP-Bereich, den Sie zuweisen können, nicht eingeschränkt sind, sollten Sie einen großen IP-Bereich wie /16 reservieren, um in Zukunft das Problem zu vermeiden, dass die IP-Bereiche erschöpft sind.

Wenn Sie jedoch keine übermäßige Zuweisung von IP-Bereichen wünschen, können Sie eine grobe Schätzung basierend auf der Datengröße und dem Traffic durchführen. Jeder Shard kann etwa 20 GB Daten im Avro-Format hosten und jedes Replikat des Shards kann etwa 800～1.000 QPS/s bereitstellen. Die genauen Abfragen, die jedes Replikat bereitstellen kann, hängen beispielsweise von der Einbettungsgröße, den Dimensionen, den Algorithmuskonfigurationen ab. Wir empfehlen dringend, einen Lasttest durchzuführen, um die genaue Anzahl zu ermitteln. Die Gesamtzahl der bereitgestellten Indexknoten beträgt (die Anzahl der Shards the die Anzahl der Replikate pro Shard).

Wenn die Datengröße beispielsweise 30 GB und 1.200 Abfragen pro Sekunde beträgt, benötigen Sie mindestens zwei Fragmentierungen und zwei Replikate pro Fragmentierung, also insgesamt vier bereitgestellte Indexknoten.

Nachdem Sie die Gesamtzahl der bereitgestellten Indexknoten geschätzt haben, können Sie das IP-Bereichspräfix anhand der folgenden Tabelle auswählen.

Gesamte bereitgestellte Indexknoten Empfohlenes reserviertes IP-Präfix
1 - 10 /21
11 - 25 /20
26 - 50 /19
51 - 120 /18

Was kann ich tun, wenn ich die Fehlermeldung erhalte, dass die IP-Bereiche erschöpft sind?

Prüfen Sie zuerst, ob nicht genutzte DeployedIndexes vorhanden sind und heben Sie ihre Bereitstellung auf, um einige IP-Bereiche freizugeben.

Außerdem können Sie vorhandene reservierte IP-Bereiche erweitern oder weitere IP-Bereiche zuweisen. Hier finden Sie eine detaillierte Anleitung.

Warum darf ich die bereitgestellte Index-ID nicht wiederverwenden, wenn der vorherige DeployedIndex entfernt wurde?

Für UndeployIndex wird immer ein erfolgreicher Vorgang zurückgegeben, sodass unsere Kunden sich keine Gedanken über Fehler bei der Aufhebung der Bereitstellung machen müssen. Der Abschluss des zugrunde liegenden Bereinigungsjobs dauert jedoch mindestens 10 ~ 20 Minuten. Wir empfehlen, 10 ~ 20 Minuten zu warten, bevor Sie dieselbe ID wiederverwenden oder eine andere ID verwenden können.

Support

Wenn bei der Verwendung von Vertex Matching Engine ein Problem auftritt, gibt es zwei Möglichkeiten, Support zu erhalten. Geben Sie in beiden Fällen die folgenden Informationen in Ihrer Kommunikation an.

  • Ihre Projekt-ID.
  • Der Befehl oder Code, den Sie ausgeführt haben, der das Problem ausgelöst hat.
  • Die Umgebung, in der Sie den Befehl oder Code ausgeführt haben. Wurde es beispielsweise in einer Compute Engine-Instanz oder auf einem lokalen Computer ausgeführt?
  • Das beobachtete Verhalten und den Unterschied zum erwarteten Verhalten.

Cloud-Support-Ticket erstellen

Wenn Sie ein Google-Supportpaket haben, können Sie ein Support-Ticket einreichen. Informationen zum Abrufen eines Google-Supportpakets finden Sie unter Google Cloud-Support.

Rufen Sie in der Cloud Console im Abschnitt Support die Option Fälle auf und klicken Sie auf Fall erstellen.

  • Fügen Sie "Matching Engine Serving" in das Feld Titel ein.
  • Wählen Sie "Machine Learing" als Kategorie aus.
  • Wählen Sie "Vertex: Sonstiges" als Komponente aus.
  • Fügen Sie den Text „Vertex Matching Engine“ oben im Beschreibungsfeld ein.
  • Füllen Sie die verbleibende Beschreibung und andere Felder so gut wie möglich aus.

E-Mails senden

Wenn Sie kein Google-Supportpaket haben, können Sie eine E-Mail an die folgende Adresse senden:

gcp-ann-feedback@google.com

Nächste Schritte