Mithilfe von Einbettungen suchen

Bei Onlinespeicherinstanzen, die für die optimierte Onlinebereitstellung erstellt wurden, können Sie eine Suche nach Vektorähnlichkeiten durchführen, um eine Liste von semantisch ähnlichen oder verwandten Entitäten, auch als ungefähre nächste Nachbarn bezeichnet, abzurufen. Sie können die Suche anhand der Entitäts-ID oder einer Einbettung durchführen.

Abhängig vom Typ des für Ihre Onlineshop-Instanz konfigurierten Endpunkts haben Sie folgende Möglichkeiten:

Hinweis

Um nach den ungefähren nächsten Nachbarn zu suchen, müssen Sie zuerst Folgendes tun:

Übereinstimmungen mit den nächsten Nachbarn über einen öffentlichen Endpunkt suchen

Wenn Sie Ihre Onlineshop-Instanz so konfiguriert haben, dass Featurewerte über die optimierte Onlinebereitstellung von einem öffentlichen Endpunkt bereitgestellt werden, müssen Sie die folgenden Schritte ausführen, um ungefähre Übereinstimmungen mit den nächsten Nachbarn abzurufen:

  1. Domainnamen des öffentlichen Endpunkts für den Onlinespeicher abrufen

  2. Nächste Nachbar-Übereinstimmungen einer Einbettung oder Entität abrufen

Domainnamen des öffentlichen Endpunkts für den Onlinespeicher abrufen

Wenn Sie eine Onlinespeicher-Instanz für optimierte Onlinebereitstellung erstellen, generiert Vertex AI Feature Store einen öffentlichen Endpunkt-Domainnamen für den Onlinespeicher. Bevor Sie im Feature Store nach den nächsten Nachbarn aus einer Feature-Ansicht im Onlinespeicher suchen können, müssen Sie den Domainnamen des öffentlichen Endpunkts aus den Onlinespeicherdetails abrufen.

Verwenden Sie das folgende Beispiel, um die Details einer Onlinespeicherinstanz abzurufen.

REST

Sie rufen die Details eines FeatureOnlineStore Ressource in Ihrem Projekt ab, indem Sie senden eine GET Anfrage mithilfe des featureOnlineStores.get-Methode.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • LOCATION_ID: Die Region, in der sich der Onlinespeicher befindet, z. B. us-central1.
  • PROJECT_ID: Ihre Projekt-ID.
  • FEATUREONLINESTORE_NAME: Der Name der Onlinespeicherinstanz.

HTTP-Methode und URL:

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME

Senden Sie die Anfrage mithilfe einer der folgenden Optionen:

curl

Führen Sie folgenden Befehl aus: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME"

PowerShell

Führen Sie folgenden Befehl aus: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME" | Select-Object -Expand Content

Sie sollten in etwa folgende JSON-Antwort erhalten:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME_1",
  "createTime": "2023-09-06T23:25:04.256314Z",
  "updateTime": "2023-09-06T23:25:04.256314Z",
  "etag": "AMEw9yMgoV0bAsYuKwVxz4Y7lOmxV7riNVHg217KaQAKORqvdqGCrQ1DIt8yHgoGXf8=",
  "state": "STABLE",
  "dedicatedServingEndpoint": {
    "publicEndpointDomainName": "PUBLIC_ENDPOINT_DOMAIN_NAME"
  },
  "optimized": {}
}

Sie benötigen die PUBLIC_ENDPOINT_DOMAIN_NAME aus der Antwort, um im folgenden Schritt die ungefähren nächsten Nachbarn abrufen.

Ungefähre nächste Nachbarn über einen öffentlichen Endpunkt abrufen

Nachdem Sie den Domainnamen des öffentlichen Endpunkts für den Onlinespeicher abgerufen haben, können Sie ihn verwenden, um nach ungefähren nächsten Nachbarn einer Einbettung oder Entität zu suchen.

Ungefähre nächste Nachbarn einer Einbettung abrufen

Verwenden Sie das folgende Beispiel, um mithilfe einer Einbettung eine Suche nach semantisch verwandten Entitäten durchzuführen, indem Sie einen öffentlichen Endpunkt angeben.

REST

Um die nächsten Nachbarn einer Einbettung zu suchen, senden Sie eine POST-Anfrage mithilfe der Methode featureViews.searchNearestEntities.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PUBLIC_ENDPOINT_DOMAIN_NAME: Der Domainname des öffentlichen Endpunkts für die Onlinespeicherinstanz, die Sie mit der Methode featureOnlineStores.get abgerufen haben.
  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION_ID: Die Region, in der sich die Onlinespeicherinstanz befindet, z. B. us-central1.
  • FEATUREONLINESTORE_NAME: Der Name der Onlinespeicherinstanz mit der Featureansicht, in der Sie nach ungefähren nächsten Nachbarn-Übereinstimmungen suchen möchten.
  • FEATUREVIEW_NAME: Der Name der Featureansicht, in der Sie nach ungefähren nächsten Nachbarn-Übereinstimmungen suchen möchten.
  • EMBEDDING: Einbettung, für die Sie ungefähre nächste Nachbarn-Übereinstimmungen abrufen möchten. Eine Einbettung wird durch ein Array von double-Werten dargestellt.
  • RETURN_FULL_ENTITY: Optional: Geben Sie an, ob die Features für die Entitäten in die Antwort ein- oder ausgeschlossen werden sollen. Geben Sie true ein, um die Features zusammen mit den Entitäten in die Antwort aufzunehmen. Der Standardwert ist false.
  • NEIGHBOR_COUNT: Anzahl der ungefähren nächsten Nachbarn, die Sie abrufen möchten.

HTTP-Methode und URL:

POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities

JSON-Text der Anfrage:

{
  "query": {
    "embedding": {
      "value": EMBEDDING
    },
    "neighbor_count": NEIGHBOR_COUNT
  },
  "return_full_entity": RETURN_FULL_ENTITY
}

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities"

PowerShell

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities" | Select-Object -Expand Content

Sie sollten in etwa folgende JSON-Antwort erhalten:

{
  "nearestNeighbors": {
    "neighbors": [
    {
      "entityId": "305281",
      "distance": -41.115459442138672
    },
    {
      "entityId": "80280",
      "distance": -38.703567504882812
    },
    {
      "entityId": "80280",
      "distance":-38.703567504882812
    },
    {
      "entityId": "903779",
      "distance": -38.214759826660156
    },
    {
      "entityId": "1008145",
      "distance": -36.271354675292969
    },
    {
      "entityId": "606431",
      "distance": -34.791431427001953
    } ]
  }
}

Ungefähre nächste Nachbarn einer Entität abrufen

Verwenden Sie das folgende Beispiel, um mithilfe einer Entitäts-ID über einen öffentlichen Endpunkt nach semantisch verwandten Entitäten zu suchen.

REST

Um die nächsten Nachbarn einer Entitäts-ID zu suchen, senden Sie eine POST-Anfrage mithilfe der Methode featureViews.searchNearestEntities.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • PUBLIC_ENDPOINT_DOMAIN_NAME: Der Domainname des öffentlichen Endpunkts für die Onlinespeicherinstanz, die Sie mit der Methode featureOnlineStores.get abgerufen haben.
  • PROJECT_ID: Ihre Projekt-ID.
  • LOCATION_ID: Die Region, in der sich die Onlinespeicherinstanz befindet, z. B. us-central1.
  • FEATUREONLINESTORE_NAME: Der Name der Onlinespeicherinstanz mit der Featureansicht, in der Sie nach ungefähren nächsten Nachbarn-Übereinstimmungen suchen möchten.
  • FEATUREVIEW_NAME: Der Name der Featureansicht, in der Sie nach ungefähren nächsten Nachbarn-Übereinstimmungen suchen möchten.
  • ENTITY_ID: Entitäts-ID der Entität, für die Sie ungefähre nächste Nachbar-Übereinstimmungen abrufen möchten.
  • RETURN_FULL_ENTITY: Optional: Geben Sie an, ob die Features für die Entitäten in die Antwort ein- oder ausgeschlossen werden sollen. Geben Sie true ein, um die Features zusammen mit den Entitäten in die Antwort aufzunehmen. Der Standardwert ist false.
  • NEIGHBOR_COUNT: Anzahl der ungefähren nächsten Nachbarn, die Sie abrufen möchten.

HTTP-Methode und URL:

POST https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities

JSON-Text der Anfrage:

{
  "query": {
    "entity_id": ENTITY_ID,
    "neighbor_count": NEIGHBOR_COUNT
  },
  "return_full_entity": RETURN_FULL_ENTITY
}

Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

curl

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities"

PowerShell

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://PUBLIC_ENDPOINT_DOMAIN_NAME/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME:searchNearestEntities" | Select-Object -Expand Content

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

{
  "nearestNeighbors": {
    "neighbors": [
    {
      "entityId": "305281",
      "distance": -41.115459442138672
    },
    {
      "entityId": "80280",
      "distance": -38.703567504882812
    },
    {
      "entityId": "80280",
      "distance":-38.703567504882812
    },
    {
      "entityId": "903779",
      "distance": -38.214759826660156
    },
    {
      "entityId": "1008145",
      "distance": -36.271354675292969
    },
    {
      "entityId": "606431",
      "distance": -34.791431427001953
    } ]
  }
}

Übereinstimmungen mit den nächsten Nachbarn über einen Private Service Connect-Endpunkt suchen

Wenn Sie Ihre Onlineshop-Instanz so konfiguriert haben, dass Featurewerte über die optimierte Onlinebereitstellung von einem Private Service Connect-Endpunkt bereitgestellt werden, müssen Sie Folgendes tun, um ungefähre nächste Nachbarn abzurufen:

  1. String des Dienstanhangs für den Onlinespeicher abrufen

  2. Fügen Sie Ihrer Netzwerkkonfiguration einen Endpunkt für Private Service Connect hinzu.

  3. Über gRPC eine Verbindung zum Private Service Connect-Endpunkt herstellen

  4. Nächste Nachbar-Übereinstimmungen einer Einbettung oder Entität abrufen

String des Dienstanhangs für den Onlinespeicher abrufen

Wenn Sie eine Onlinespeicher-Instanz für die optimierte Onlinebereitstellung mit einem Private Service Connect-Endpunkt erstellen, generiert Vertex AI Feature Store einen String für den Dienstanhang. Sie können den String des Dienstanhangs in den Details des Onlinespeichers abrufen und damit den Private Service Connect-Endpunkt einrichten.

Verwenden Sie das folgende Beispiel, um die Details einer Onlinespeicherinstanz abzurufen.

REST

Sie rufen die Details eines FeatureOnlineStore Ressource in Ihrem Projekt ab, indem Sie senden eine GET Anfrage mithilfe des featureOnlineStores.get-Methode.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • LOCATION_ID: Die Region, in der sich der Onlinespeicher befindet, z. B. us-central1.
  • PROJECT_ID: Ihre Projekt-ID.
  • FEATUREONLINESTORE_NAME: Der Name der Onlinespeicherinstanz.

HTTP-Methode und URL:

GET https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME

Senden Sie die Anfrage mithilfe einer der folgenden Optionen:

curl

Führen Sie folgenden Befehl aus: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME"

PowerShell

Führen Sie folgenden Befehl aus: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION_ID-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME" | Select-Object -Expand Content

Sie sollten in etwa folgende JSON-Antwort erhalten:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME_1",
  "createTime": "2023-09-06T23:25:04.256314Z",
  "updateTime": "2023-09-06T23:25:04.256314Z",
  "etag": "AMEw9yMgoV0bAsYuKwVxz4Y7lOmxV7riNVHg217KaQAKORqvdqGCrQ1DIt8yHgoGXf8=",
  "state": "STABLE",
  "dedicatedServingEndpoint": {
    "privateServiceConnectConfig": {
      "enablePrivateServiceConnect": "true",
      "projectAllowlist": [
        "PROJECT_NAME"
      ]
    },
    serviceAttachment: "SERVICE_ATTACHMENT_STRING"
  },
  "optimized": {}
}

Sie benötigen den SERVICE_ATTACHMENT_STRING aus der Antwort, um im folgenden Schritt Featurewerte abzurufen.

Endpunkt für Private Service Connect hinzufügen

So fügen Sie Ihrer Netzwerkkonfiguration einen Private Service Connect-Endpunkt für eine optimierte Onlinebereitstellung hinzu:

  1. Wählen Sie in der Cloud de Confiance -Console das Projekt mit der Onlineshop-Instanz aus.

  2. Erstellen Sie einen Endpunkt für Private Service Connect, indem Sie SERVICE_ATTACHMENT_STRING als Zieldienst angeben.

Nachdem Sie den Endpunkt erstellt haben, wird er auf dem Tab Verbundene Endpunkte auf der Seite Private Service Connect angezeigt. Die IP-Adresse des Endpunkts wird in der Spalte IP-Adressen angezeigt.

Zum Tab „Verbundene Endpunkte“

Sie benötigen diese IP-Adresse, um im folgenden Schritt eine Verbindung zum Endpunkt für Ihre Onlinespeicher-Instanz zum Private Service Connect-Endpunkt über gRPC herzustellen.

Über gRPC eine Verbindung zum Private Service Connect-Endpunkt herstellen

Verwenden Sie das folgende Codebeispiel, um eine Verbindung zum erstellten Private Service Connect-Endpunkt für Ihren Onlinespeicher über gRPC herzustellen.

Python 

from google.cloud.aiplatform_v1 import FeatureOnlineStoreServiceClient
from google.cloud.aiplatform_v1.services.feature_online_store_service.transports.grpc import FeatureOnlineStoreServiceGrpcTransport
import grpc

data_client = FeatureOnlineStoreServiceClient(
  transport = FeatureOnlineStoreServiceGrpcTransport(
    # Add the IP address of the Endpoint you just created.
    channel = grpc.insecure_channel("ENDPOINT_IP:10002")
  )
)

Ersetzen Sie Folgendes:

  • ENDPOINT_IP: Die IP-Adresse des Endpunkts in der Spalte IP-Adressen auf der Seite Private Service Connect.

Ungefähre nächste Nachbarn über einen Private Service Connect-Endpunkt abrufen

Nachdem Sie über gRPC eine Verbindung zum Private Service Connect-Endpunkt hergestellt haben, können Sie nach ungefähren nächsten Nachbarn einer Einbettung oder Entität suchen.

Ungefähre nächste Nachbarn einer Einbettung abrufen

Verwenden Sie das folgende Beispiel, um mithilfe einer Einbettung eine Suche nach semantisch verwandten Entitäten durchzuführen, während Sie einen privaten Endpunkt verwenden.

Python 

data_client.search_nearest_entities(
  request=feature_online_store_service_pb2.SearchNearestEntitiesRequest(
      feature_view=f"projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME",
      query=feature_online_store_service_pb2.NearestNeighborQuery(
          embedding = "EMBEDDING",
          neighbor_count = NEIGHBOR_COUNT,
      ),
      return_full_entity=RETURN_FULL_ENTITY
  ))

Ersetzen Sie Folgendes:

  • LOCATION_ID: Die Region, in der sich der Onlinespeicher befindet, z. B. us-central1.

  • PROJECT_ID: Ihre Projekt-ID.

  • FEATUREONLINESTORE_NAME: Der Name des Onlinespeichers, der die Featureansicht enthält.

  • FEATUREVIEW_NAME: Der Name der Featureansicht, in der Sie nach ungefähren nächsten Nachbarn-Übereinstimmungen suchen möchten.

  • EMBEDDING: Einbettung, für die Sie ungefähre nächste Nachbarn-Übereinstimmungen abrufen möchten. Eine Einbettung wird durch ein Array von double-Werten dargestellt.

  • FORMAT: Optional: Das Format, in dem Sie die Featurewerte abrufen möchten. Zu den unterstützten Formaten gehören das JSON-Schlüssel/Wert-Paar und die Proto-Formate "Struct". Das Proto-Format Struct unterstützt den Werttyp „bytes“ nicht. Wenn Sie Feature-Werte abrufen möchten, die als Byte formatiert sind, verwenden Sie JSON als Antwortformat.

  • RETURN_FULL_ENTITY: Optional: Geben Sie an, ob die Features für die Entitäten in die Antwort ein- oder ausgeschlossen werden sollen. Geben Sie true ein, um die Features zusammen mit den Entitäten in die Antwort aufzunehmen. Der Standardwert ist false.

  • NEIGHBOR_COUNT: Anzahl der ungefähren nächsten Nachbarn, die Sie abrufen möchten.

Ungefähre nächste Nachbarn einer Entität abrufen

Verwenden Sie das folgende Beispiel, um mithilfe einer Entitäts-ID über einen privaten Endpunkt nach semantisch verwandten Entitäten zu suchen.

Python 

data_client.search_nearest_entities(
  request=feature_online_store_service_pb2.SearchNearestEntitiesRequest(
      feature_view=f"projects/PROJECT_ID/locations/LOCATION_ID/featureOnlineStores/FEATUREONLINESTORE_NAME/featureViews/FEATUREVIEW_NAME",
      query=feature_online_store_service_pb2.NearestNeighborQuery(
          entity_id = "ENTITY_ID",
          neighbor_count = NEIGHBOR_COUNT,
      ),
      return_full_entity=RETURN_FULL_ENTITY
  ))
 ```

Ersetzen Sie Folgendes:

  • LOCATION_ID: Die Region, in der sich der Onlinespeicher befindet, z. B. us-central1.

  • PROJECT_ID: Ihre Projekt-ID.

  • FEATUREONLINESTORE_NAME: Der Name des Onlinespeichers, der die Featureansicht enthält.

  • FEATUREVIEW_NAME: Der Name der Featureansicht, in der Sie nach ungefähren nächsten Nachbarn-Übereinstimmungen suchen möchten.

  • ENTITY_ID: Entitäts-ID der Entität, für die Sie ungefähre nächste Nachbar-Übereinstimmungen abrufen möchten.

  • FORMAT: Optional: Das Format, in dem Sie die Featurewerte abrufen möchten. Zu den unterstützten Formaten gehören das JSON-Schlüssel/Wert-Paar und die Proto-Formate "Struct". Das Proto-Format Struct unterstützt den Werttyp „bytes“ nicht. Wenn Sie Feature-Werte abrufen möchten, die als Byte formatiert sind, verwenden Sie JSON als Antwortformat.

  • RETURN_FULL_ENTITY: Optional: Geben Sie an, ob die Features für die Entitäten in die Antwort ein- oder ausgeschlossen werden sollen. Geben Sie true ein, um die Features zusammen mit den Entitäten in die Antwort aufzunehmen. Der Standardwert ist false.

  • NEIGHBOR_COUNT: Anzahl der ungefähren nächsten Nachbarn, die Sie abrufen möchten.