Modelle über Modellendpunkte in AlloyDB aufrufen

Vorabversion – Verwaltung von Modellendpunkten
Diese Funktion unterliegt den „Bedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Dienstbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA‑Funktionen stehen in der vorliegenden Form zur Verfügung und bieten möglicherweise nur eingeschränkten Support.

Mit der Vorschaufunktion für die Verwaltung von Modellendpunkten können Sie einen Modellendpunkt registrieren, Metadaten von Modellendpunkten in Ihrem Datenbankcluster verwalten und dann mit den Modellen über SQL-Abfragen interagieren. Sie bietet die google_ml_integration-Erweiterung, die Funktionen zum Hinzufügen und Registrieren der Metadaten des Modellendpunkts für die Modelle enthält. Anschließend können Sie die Modelle verwenden, um Vektoreinbettungen zu generieren oder Vorhersagen aufzurufen.

Hier sind einige Beispiele für Modelltypen, die Sie mit der Modellendpunktverwaltung registrieren können:

• Vertex AI-Modelle zur Texteinbettung
• Einbettungsmodelle von Drittanbietern
• Benutzerdefiniert gehostete Texteinbettungsmodelle
• Generische Modelle mit einer JSON-basierten API, z. B. das gemini-pro-Modell aus dem Vertex AI Model Garden

Funktionsweise

Mit der Verwaltung von Modellendpunkten können Sie einen Modellendpunkt registrieren, der den folgenden Anforderungen entspricht:

• Die Eingabe und Ausgabe des Modells unterstützt das JSON-Format.
• Das Modell kann über das REST-Protokoll aufgerufen werden.

Wenn Sie einen Modellendpunkt in der Modellendpunktverwaltung registrieren, wird jeder Endpunkt mit einer eindeutigen Modell-ID registriert, die Sie als Referenz für das Modell angegeben haben. Mit dieser Modell-ID können Sie Modelle abfragen:

• Einbettungen generieren, um Text-Prompts in numerische Vektoren zu übersetzen. Sie können generierte Einbettungen als Vektordaten speichern, wenn die pgvector-Erweiterung in der Datenbank aktiviert ist.

• Rufen Sie Vorhersagen auf, um ein Modell mithilfe von SQL innerhalb einer Transaktion aufzurufen.

Ihre Anwendungen können über die Erweiterung google_ml_integration auf die Verwaltung von Modellendpunkten zugreifen. Diese Erweiterung bietet die folgenden Funktionen:

• Die SQL-Funktion google_ml.create_model(), mit der der Modellendpunkt registriert wird, der in der Vorhersage- oder Einbettungsfunktion verwendet wird.
• Die SQL-Funktion google_ml.create_sm_secret(), die Secrets im Google CloudSecret Manager verwendet, in dem die API-Schlüssel gespeichert sind.
• Die SQL-Funktion google_ml.embedding(), eine Vorhersagefunktion, die Texteinbettungen generiert.
• Die SQL-Funktion google_ml.predict_row(), mit der Vorhersagen generiert werden, wenn Sie generische Modelle aufrufen, die das JSON-Ein- und -Ausgabeformat unterstützen.
• Andere Hilfsfunktionen, die das Generieren benutzerdefinierter URLs, das Generieren von HTTP-Headern oder das Übergeben von Transformationsfunktionen für Ihre generischen Modelle verarbeiten.
• Funktionen zum Verwalten der registrierten Modellendpunkte und Secrets.

Wichtige Konzepte

Bevor Sie mit der Verwaltung von Modellendpunkten beginnen, sollten Sie die Konzepte kennen, die für die Verbindung zu den Modellen und deren Verwendung erforderlich sind.

Modellanbieter

Unter Modellanbieter sind die unterstützten Anbieter für das Modell-Hosting aufgeführt. In der folgenden Tabelle sehen Sie den Wert für den Modellanbieter, den Sie basierend auf dem von Ihnen verwendeten Modellanbieter festlegen müssen:

Modellanbieter	In Funktion festgelegt als…
Vertex AI	google
Andere Modelle	custom

Der Standardanbieter für Modelle ist custom.

Die unterstützte Authentifizierungsmethode hängt vom Anbietertyp ab. Die Vertex AI-Modelle verwenden das Distributed Cloud-Dienstkonto zur Authentifizierung, während andere Anbieter Secret Manager zur Authentifizierung verwenden können.

Modelltyp

Modelltyp gibt den Typ des KI-Modells an. Die Erweiterung unterstützt Texteinbettung sowie alle generischen Modelltypen. Die unterstützten Modelltypen, die Sie beim Registrieren eines Modellendpunkts festlegen können, sind text-embedding und generic. Das Festlegen des Modelltyps ist optional, wenn Sie generische Modellendpunkte registrieren, da generic der Standardmodelltyp ist.

Texteinbettungsmodelle mit integrierter Unterstützung

Die Modellendpunktverwaltung bietet integrierte Unterstützung für alle Versionen des textembedding-gecko-Modells von Vertex AI. Verwenden Sie die Funktion google_ml.create_model(), um diese Modellendpunkte zu registrieren. Distributed Cloud richtet automatisch Standardtransformationsfunktionen für diese Modelle ein.

Der Modelltyp für diese Modelle ist text-embedding.

Andere Modelle zur Texteinbettung

Für andere Modelle für Texteinbettungen müssen Sie Transformationsfunktionen erstellen, um die vom Modell unterstützten Eingabe- und Ausgabeformate zu verarbeiten. Optional können Sie die Funktion zur Generierung von HTTP-Headern verwenden, mit der benutzerdefinierte Header generiert werden, die für Ihr Modell erforderlich sind.

Der Modelltyp für diese Modelle ist text-embedding.

Generische Modelle

Die Modellendpunktverwaltung unterstützt auch die Registrierung aller anderen Modelltypen außer Modelle für Texteinbettungen. Verwenden Sie die Funktion google_ml.predict_row(), um Vorhersagen für generische Modelle aufzurufen. Sie können Metadaten für Modellendpunkte festlegen, z. B. einen Anfrageendpunkt und HTTP-Header, die für Ihr Modell spezifisch sind.

 Sie können keine Transformationsfunktionen übergeben, wenn Sie einen generischen Modellendpunkt registrieren. Achten Sie darauf, dass die Eingabe für die Funktion im JSON-Format vorliegt, wenn Sie Vorhersagen aufrufen, und dass Sie die JSON-Ausgabe parsen, um die endgültige Ausgabe zu erhalten.

Der Modelltyp für diese Modelle ist generic.

Authentifizierung

Auth types (Authentifizierungstypen) gibt den Authentifizierungstyp an, den Sie verwenden können, um mit der google_ml_integration-Erweiterung eine Verbindung zur Modellendpunktverwaltung herzustellen. Die Authentifizierung ist optional und nur erforderlich, wenn Sie sich authentifizieren müssen, um auf Ihr Modell zuzugreifen.

Für Vertex AI-Modelle wird das Distributed Cloud-Dienstkonto für die Authentifizierung verwendet. Bei anderen Modellen kann ein API-Schlüssel oder ein Bearer-Token, das als Secret im Secret Manager gespeichert ist, mit der SQL-Funktion google_ml.create_sm_secret() verwendet werden.

In der folgenden Tabelle sind die Authentifizierungstypen aufgeführt, die Sie festlegen können:

Authentifizierungsmethode	In Funktion festgelegt als…	Modellanbieter
Distributed Cloud-Dienst-Agent	alloydb_service_agent_iam	Vertex AI-Anbieter
Secret Manager	secret_manager	Drittanbieter

Vorhersagefunktionen

Die google_ml_integration-Erweiterung enthält die folgenden Vorhersagefunktionen:

google_ml.embedding()

Wird verwendet, um einen registrierten Endpunkt für ein Texteinbettungsmodell aufzurufen, um Einbettungen zu generieren. Es bietet integrierte Unterstützung für das Modell textembedding-gecko von Vertex AI.

Bei Modelleinbettungsmodellen ohne integrierte Unterstützung sind die Ein- und Ausgabeparameter für ein Modell eindeutig und müssen für die Funktion transformiert werden, damit das Modell aufgerufen werden kann. Erstellen Sie eine Funktion zum Transformieren der Eingabe, um die Eingabe der Vorhersagefunktion in die modellspezifische Eingabe zu transformieren, und eine Funktion zum Transformieren der Ausgabe, um die modellspezifische Ausgabe in die Ausgabe der Vorhersagefunktion zu transformieren.

google_ml.predict_row()

Wird verwendet, um einen registrierten generischen Modellendpunkt aufzurufen, sofern dieser eine JSON-basierte API unterstützt, um Vorhersagen zu treffen.

Transformationsfunktionen

Transformationsfunktionen ändern die Eingabe in ein Format, das das Modell versteht, und konvertieren die Modellantwort in das Format, das die Vorhersagefunktion erwartet. Die Transformationsfunktionen werden verwendet, wenn der text-embedding-Modellendpunkt ohne integrierte Unterstützung registriert wird. Die Signatur der Transformationsfunktionen hängt von der Vorhersagefunktion für den Modelltyp ab.

Sie können keine Transformationsfunktionen verwenden, wenn Sie einen generic-Modellendpunkt registrieren.

Nachfolgend sehen Sie die Signaturen für die Vorhersagefunktion für Modelle für Texteinbettungen:

// define custom model specific input/output transform functions.
CREATE OR REPLACE FUNCTION input_transform_function(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

CREATE OR REPLACE FUNCTION output_transform_function(model_id VARCHAR(100), response_json JSON) RETURNS real[];

Funktion zum Generieren von HTTP-Headern

Die Funktion zur Generierung von HTTP-Headern gibt die Ausgabe in JSON-Schlüssel/Wert-Paaren aus, die als HTTP-Header verwendet werden. Die Signatur der Vorhersagefunktion definiert die Signaturen der Header-Generierungsfunktion.

Das folgende Beispiel zeigt die Signatur für die Vorhersagefunktion google_ml.embedding().

CREATE OR REPLACE FUNCTION generate_headers(model_id VARCHAR(100), input TEXT) RETURNS JSON;

Für die Vorhersagefunktion google_ml.predict_row() lautet die Signatur so:

CREATE OR REPLACE FUNCTION generate_headers(model_id VARCHAR(100), input JSON) RETURNS JSON;

Modell registrieren

Wenn Sie Vorhersagen aufrufen oder Einbettungen mit einem Modell generieren möchten, registrieren Sie den Modellendpunkt bei der Modellendpunktverwaltung.

Weitere Informationen zur google_ml.create_model()-Funktion finden Sie in der Referenz zur Verwaltung von Modellendpunkten.

Bevor Sie einen Modellendpunkt bei der Modellendpunktverwaltung registrieren, müssen Sie die Erweiterung google_ml_integration aktivieren und die Authentifizierung basierend auf dem Modellanbieter einrichten, falls für Ihren Modellendpunkt eine Authentifizierung erforderlich ist.

Achten Sie darauf, dass Sie mit dem Standardnutzernamen postgres auf Ihre Datenbank zugreifen.

Authentifizierung einrichten

In den folgenden Abschnitten wird beschrieben, wie Sie die Authentifizierung einrichten, bevor Sie einen Vertex AI-Modellendpunkt oder Modellendpunkte anderer Anbieter hinzufügen.

Authentifizierung für Vertex AI einrichten

Wenn Sie die Google Vertex AI-Modellendpunkte verwenden möchten, müssen Sie dem Dienstkonto, das Sie bei der Installation von AlloyDB Omni verwendet haben, Vertex AI-Berechtigungen hinzufügen.

Authentifizierung für andere Modellanbieter einrichten

Für alle Modelle mit Ausnahme von Vertex AI-Modellen können Sie Ihre API-Schlüssel oder Inhabertokens in Secret Manager speichern. Dieser Schritt ist optional, wenn Ihr Modellendpunkt die Authentifizierung nicht über Secret Manager abwickelt, z. B. wenn Ihr Modellendpunkt HTTP-Header zum Übergeben von Authentifizierungsinformationen verwendet oder überhaupt keine Authentifizierung verwendet.

In diesem Abschnitt wird beschrieben, wie Sie die Authentifizierung einrichten, wenn Sie Secret Manager verwenden.

So erstellen und verwenden Sie einen API-Schlüssel oder ein Bearer-Token:

1. Erstellen Sie das Secret in Secret Manager.

   Der Secret-Name und der Secret-Pfad werden in der SQL-Funktion google_ml.create_sm_secret() verwendet.

2. Gewähren Sie dem Distributed Cloud-Cluster Berechtigungen für den Zugriff auf das Secret.

     gcloud secrets add-iam-policy-binding 'SECRET_ID' \
         --member="serviceAccount:SERVICE_ACCOUNT_ID" \
         --role="roles/secretmanager.secretAccessor"
   

   Ersetzen Sie Folgendes:

   • SECRET_ID: die Secret-ID im Secret Manager.

   • SERVICE_ACCOUNT_ID: die ID des Dienstkontos, das Sie im vorherigen Schritt erstellt haben. Achten Sie darauf, dass dies dasselbe Konto ist, das Sie bei der Installation von AlloyDB Omni verwendet haben. Dazu gehört das vollständige Suffix PROJECT_ID.iam.gserviceaccount.com. Beispiel: [e-mail]

     Sie können diese Rolle dem Dienstkonto auch auf Projektebene zuweisen.

Einbettungen generieren

In diesem Abschnitt wird eine Vorabversion beschrieben, mit der Sie das Registrieren eines KI-Modellendpunkts und das Aufrufen von Vorhersagen mit der Verwaltung von Modellendpunkten testen können.

Nachdem die Modellendpunkte hinzugefügt und in der Modellendpunktverwaltung registriert wurden, können Sie mit der Modell-ID darauf verweisen, um Einbettungen zu generieren.

Hinweise

Achten Sie darauf, dass Sie Ihren Modellendpunkt in der Modellendpunktverwaltung registriert haben.

Einbettungen generieren

Mit der SQL-Funktion google_ml.embedding() können Sie den registrierten Modellendpunkt mit dem Texteinbettungsmodelltyp aufrufen, um Einbettungen zu generieren.

Verwenden Sie die folgende SQL-Abfrage, um das Modell aufzurufen und Einbettungen zu generieren:

SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    content => 'CONTENT');

Ersetzen Sie Folgendes:

• MODEL_ID: Die Modell-ID, die Sie bei der Registrierung des Modellendpunkts definiert haben.
• CONTENT: Der Text, der in eine Vektoreinbettung übersetzt werden soll.

Beispiele

In diesem Abschnitt finden Sie einige Beispiele für das Generieren von Einbettungen mit einem registrierten Modellendpunkt.

Texteinbettungsmodelle mit integrierter Unterstützung

Führen Sie die folgende Anweisung aus, um Einbettungen für einen registrierten textembedding-gecko@002-Modellendpunkt zu generieren:

    SELECT
      google_ml.embedding(
        model_id => 'textembedding-gecko@002',
        content => 'AlloyDB is a managed, cloud-hosted SQL database service');

Vorhersagen aufrufen

In diesem Abschnitt wird eine Vorabversion beschrieben, mit der Sie das Registrieren eines KI-Modellendpunkts und das Aufrufen von Vorhersagen mit der Verwaltung von Modellendpunkten testen können.

Nachdem die Modellendpunkte hinzugefügt und in der Modellendpunktverwaltung registriert wurden, können Sie mit der Modell-ID auf sie verweisen, um Vorhersagen aufzurufen.

Hinweise

Achten Sie darauf, dass Sie Ihren Modellendpunkt in der Modellendpunktverwaltung registriert haben.

Vorhersagen für generische Modelle aufrufen

Verwenden Sie die SQL-Funktion google_ml.predict_row(), um einen registrierten generischen Modellendpunkt aufzurufen und Vorhersagen zu generieren. Sie können die Funktion google_ml.predict_row() mit jedem Modelltyp verwenden.

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');

Ersetzen Sie Folgendes:

• MODEL_ID: Die Modell-ID, die Sie bei der Registrierung des Modellendpunkts definiert haben.
• REQUEST_BODY: Die Parameter für die Vorhersagefunktion im JSON-Format.

Beispiele

In diesem Abschnitt finden Sie einige Beispiele für das Aufrufen von Vorhersagen über registrierte Modellendpunkte.

Führen Sie die folgende Anweisung aus, um Vorhersagen für einen registrierten gemini-pro-Modellendpunkt zu generieren:

    SELECT
        json_array_elements(
        google_ml.predict_row(
            model_id => 'gemini-pro',
            request_body => '{
        "contents": [
            {
                "role": "user",
                "parts": [
                    {
                        "text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation."
                    }
                ]
            }
        ]
        }'))-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';

API-Referenz für die Verwaltung von Modellendpunkten

In diesem Abschnitt werden Parameter für verschiedene Funktionen aufgeführt, die von der Erweiterung google_ml_integration bereitgestellt werden, um Modellendpunkte und Secrets mit der Modellendpunktverwaltung zu registrieren und zu verwalten.

Sie müssen das Datenbankflag google_ml_integration.enable_model_support auf on setzen, bevor Sie die Erweiterung verwenden können.

Modelle

In dieser Referenz finden Sie Informationen zu Parametern für Funktionen, mit denen Sie Modellendpunkte verwalten können.

google_ml.create_model()-Funktion

Im Folgenden sehen Sie, wie die SQL-Funktion google_ml.create_model() aufgerufen wird, die zum Registrieren von Metadaten für Modellendpunkte verwendet wird:

  CALL
    google_ml.create_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');

Parameter	Erforderlich	Beschreibung
MODEL_ID	Für alle Modellendpunkte erforderlich	Eine eindeutige ID für den Modellendpunkt, die Sie definieren.
REQUEST_URL	optional für andere Endpunkte von Texteinbettungsmodellen mit integrierter Unterstützung	Der modellspezifische Endpunkt beim Hinzufügen anderer Endpunkte für Texteinbettung und generische Modelle. Geben Sie für AlloyDB for PostgreSQL eine https-URL an.  Die Anfrage-URL, die die Funktion für integrierte Modellendpunkte generiert, bezieht sich auf das Projekt und die Region oder den Standort Ihres Clusters. Wenn Sie auf ein anderes Projekt verweisen möchten, müssen Sie model_request_url explizit angeben.  Achten Sie bei benutzerdefinierten gehosteten Modellendpunkten darauf, dass der Modellendpunkt über das Netzwerk erreichbar ist, in dem sich Distributed Cloud befindet.
PROVIDER_ID	Erforderlich für Endpunkte von Texteinbettungsmodellen mit integrierter Unterstützung	Der Anbieter des Modellendpunkts. Der Standardwert ist custom. Legen Sie einen der folgenden Werte fest: google für Vertex AI-Modellendpunkte custom für andere Anbieter
MODEL_TYPE	optional für generische Modellendpunkte	Der Modelltyp. Legen Sie einen der folgenden Werte fest: text_embedding für Endpunkte von Texteinbettungsmodellen generic für alle anderen Modellendpunkte
MODEL_QUALIFIED_NAME	erforderlich für Texteinbettungsmodelle mit integrierter Unterstützung; optional für andere Modellendpunkte	Der vollständig qualifizierte Name für Texteinbettungsmodelle mit integrierter Unterstützung.
AUTH_TYPE	Optional, es sei denn, für den Modellendpunkt gelten bestimmte Authentifizierungsanforderungen.	Der vom Modellendpunkt verwendete Authentifizierungstyp. Sie können sie entweder auf alloydb_service_agent_iam für Vertex AI-Modelle oder auf secret_manager für andere Anbieter festlegen, wenn diese Secret Manager für die Authentifizierung verwenden.  Sie müssen diesen Wert nicht festlegen, wenn Sie Authentifizierungsheader verwenden.
AUTH_ID	Nicht für Vertex AI-Modellendpunkte festlegen; für alle anderen Modellendpunkte erforderlich, in denen Geheimnisse in Secret Manager gespeichert werden	Die Secret-ID, die Sie festlegen und die anschließend beim Registrieren eines Modellendpunkts verwendet wird.
GENERATE_HEADER_FUNCTION	optional	Der Name der Funktion, die benutzerdefinierte Header generiert. Die Signatur dieser Funktion hängt von der verwendeten Vorhersagefunktion ab.
INPUT_TRANSFORM_FUNCTION	optional für Endpunkte von Texteinbettungsmodellen mit integrierter Unterstützung; nicht für generische Modellendpunkte festlegen	Die Funktion zum Transformieren der Eingabe der entsprechenden Vorhersagefunktion in die modellspezifische Eingabe.
OUTPUT_TRANSFORM_FUNCTION	optional für Endpunkte von Texteinbettungsmodellen mit integrierter Unterstützung; nicht für generische Modellendpunkte festlegen	Die Funktion zum Transformieren der modellspezifischen Ausgabe in die Ausgabe der Vorhersagefunktion.

google_ml.alter_model()

Im Folgenden sehen Sie, wie die SQL-Funktion google_ml.alter_model() aufgerufen wird, mit der Metadaten von Modellendpunkten aktualisiert werden:

    CALL
    google_ml.alter_model(
      model_id => 'MODEL_ID',
      model_request_url => 'REQUEST_URL',
      model_provider => 'PROVIDER_ID',
      model_type => 'MODEL_TYPE',
      model_qualified_name => 'MODEL_QUALIFIED_NAME',
      model_auth_type => 'AUTH_TYPE',
      model_auth_id => 'AUTH_ID',
      generate_headers_fn => 'GENERATE_HEADER_FUNCTION',
      model_in_transform_fn => 'INPUT_TRANSFORM_FUNCTION',
      model_out_transform_fn => 'OUTPUT_TRANSFORM_FUNCTION');

Informationen zu den Werten, die Sie für die einzelnen Parameter festlegen müssen, finden Sie unter Modell erstellen.

google_ml.drop_model()-Funktion

Im Folgenden sehen Sie, wie die SQL-Funktion google_ml.drop_model() aufgerufen wird, mit der ein Modellendpunkt gelöscht wird:

  CALL google_ml.drop_model('MODEL_ID');

Parameter	Beschreibung
MODEL_ID	Eine eindeutige ID für den von Ihnen definierten Modellendpunkt.

google_ml.list_model()-Funktion

Im Folgenden sehen Sie, wie Sie die SQL-Funktion google_ml.list_model() aufrufen, mit der Informationen zum Modellendpunkt aufgeführt werden:

  SELECT google_ml.list_model('MODEL_ID');

Parameter	Beschreibung
MODEL_ID	Eine eindeutige ID für den von Ihnen definierten Modellendpunkt.

google_ml.model_info_view Ansicht

Im Folgenden sehen Sie, wie Sie die Ansicht google_ml.model_info_view aufrufen, mit der Informationen zu Modellendpunkten für alle Modellendpunkte aufgeführt werden:

  SELECT * FROM google_ml.model_info_view;

Secrets

In dieser Referenz finden Sie Informationen zu Parametern für Funktionen, mit denen Sie Secrets verwalten können.

google_ml.create_sm_secret()-Funktion

Im Folgenden wird gezeigt, wie die SQL-Funktion google_ml.create_sm_secret() aufgerufen wird, um das in Secret Manager erstellte Secret hinzuzufügen:

    CALL
    google_ml.create_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

Parameter	Beschreibung
SECRET_ID	Die Secret-ID, die Sie festlegen und die anschließend beim Registrieren eines Modellendpunkts verwendet wird.
PROJECT_ID	Die ID Ihres Google Cloud -Projekts, das das Secret enthält. Dieses Projekt kann sich von dem Projekt unterscheiden, das Ihren AlloyDB for PostgreSQL-Cluster enthält.  Für AlloyDB Omni die ID des Projekts Google Cloud , das das Secret enthält.
SECRET_MANAGER_SECRET_ID	Die Secret-ID, die in Secret Manager festgelegt wurde, als Sie das Secret erstellt haben.
VERSION_NUMBER	Die Versionsnummer der Secret-ID.

google_ml.alter_sm_secret()-Funktion

Im Folgenden wird gezeigt, wie die SQL-Funktion google_ml.alter_sm_secret() aufgerufen wird, mit der geheime Informationen aktualisiert werden:

  CALL
    google_ml.alter_sm_secret(
      secret_id => 'SECRET_ID',
      secret_path => 'projects/project-id/secrets/SECRET_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

Informationen zu den Werten, die Sie für die einzelnen Parameter festlegen müssen, finden Sie unter Secret erstellen.

google_ml.drop_sm_secret()-Funktion

Im Folgenden wird gezeigt, wie die SQL-Funktion google_ml.drop_sm_secret() aufgerufen wird, mit der ein Secret gelöscht wird:

  CALL google_ml.drop_sm_secret('SECRET_ID');

Parameter	Beschreibung
SECRET_ID	Die Secret-ID, die Sie festgelegt haben und die anschließend bei der Registrierung eines Modellendpunkts verwendet wurde.

Vorhersagefunktionen

In dieser Referenz finden Sie Informationen zu Parametern für Funktionen, mit denen Sie Einbettungen generieren oder Vorhersagen aufrufen können.

google_ml.embedding()-Funktion

Im Folgenden wird gezeigt, wie Einbettungen generiert werden:

SELECT
  google_ml.embedding(
    model_id => 'MODEL_ID',
    contents => 'CONTENT');

Parameter	Beschreibung
MODEL_ID	Eine eindeutige ID für den Modellendpunkt, die Sie definieren.
CONTENT	Der Text, der in eine Vektoreinbettung übersetzt werden soll.

google_ml.predict_row()-Funktion

Im Folgenden wird gezeigt, wie Vorhersagen aufgerufen werden:

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');

Parameter	Beschreibung
MODEL_ID	Eine eindeutige ID für den Modellendpunkt, die Sie definieren.
REQUEST_BODY	Die Parameter für die Vorhersagefunktion im JSON-Format.

Transformationsfunktionen

In dieser Referenz finden Sie Informationen zu Parametern für Eingabe- und Ausgabe-Transformationsfunktionen.

Eingabetransformationsfunktion

Unten sehen Sie die Signatur für die Vorhersagefunktion für Endpunkte von Texteinbettungsmodellen:

  CREATE OR REPLACE FUNCTION INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

Parameter	Beschreibung
INPUT_TRANSFORM_FUNCTION	Die Funktion zum Transformieren der Eingabe der entsprechenden Vorhersagefunktion in die eingabespezifische Eingabe des Modellendpunkts.

Ausgabetransformationsfunktion

Unten sehen Sie die Signatur für die Vorhersagefunktion für Endpunkte von Texteinbettungsmodellen:

  CREATE OR REPLACE FUNCTION OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS real[];

Parameter	Beschreibung
OUTPUT_TRANSFORM_FUNCTION	Die Funktion zum Transformieren der ausgabespezifischen Ausgabe des Modellendpunkts in die Ausgabe der Vorhersagefunktion.

Beispiel für Transformationsfunktionen

Um besser zu verstehen, wie Sie Transformationsfunktionen für Ihren Modellendpunkt erstellen, sehen Sie sich einen benutzerdefinierten gehosteten Texteinbettungsmodellendpunkt an, für den JSON-Ein- und -Ausgabe erforderlich ist.

Mit der folgenden Beispiel-cURL-Anfrage werden Einbettungen basierend auf dem Prompt und dem Modellendpunkt erstellt:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
    -H "Content-Type: application/json"
    -d '{"prompt": ["AlloyDB Embeddings"]}'

Die folgende Beispielantwort wird zurückgegeben:

[[ 0.3522231  -0.35932037  0.10156056  0.17734447 -0.11606089 -0.17266059
   0.02509351  0.20305622 -0.09787305 -0.12154685 -0.17313677 -0.08075467
   0.06821183 -0.06896557  0.1171584  -0.00931572  0.11875633 -0.00077482
   0.25604948  0.0519384   0.2034983  -0.09952664  0.10347155 -0.11935943
  -0.17872004 -0.08706985 -0.07056875 -0.05929353  0.4177883  -0.14381726
   0.07934926  0.31368294  0.12543282  0.10758053 -0.30210832 -0.02951015
   0.3908268  -0.03091059  0.05302926 -0.00114946 -0.16233777  0.1117468
  -0.1315904   0.13947351 -0.29569918 -0.12330773 -0.04354299 -0.18068913
   0.14445548  0.19481727]]

Anhand dieser Eingabe und Antwort können wir Folgendes ableiten:

• Das Modell erwartet JSON-Eingabe über das Feld prompt. In dieses Feld kann ein Array von Eingaben eingegeben werden. Da die Funktion google_ml.embedding() eine Funktion auf Zeilenebene ist, wird jeweils nur eine Texteingabe erwartet. Daher müssen Sie eine Eingabetransformationsfunktion erstellen,die ein Array mit einem einzelnen Element erstellt.

• Die Antwort des Modells ist ein Array von Einbettungen, eine für jeden Prompt, der in das Modell eingegeben wird. Da die Funktion google_ml.embedding() eine Funktion auf Zeilenebene ist, wird jeweils nur eine Eingabe zurückgegeben. Daher müssen Sie eine Ausgabetransformationsfunktion erstellen, mit der das Embedding aus dem Array extrahiert werden kann.

Im folgenden Beispiel sehen Sie die Ein- und Ausgabetransformationsfunktionen, die für diesen Modellendpunkt verwendet werden, wenn er bei der Modellendpunktverwaltung registriert ist:

Eingabetransformationsfunktion

CREATE OR REPLACE FUNCTION cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_input JSON;
  model_qualified_name TEXT;
BEGIN
  SELECT json_build_object('prompt', json_build_array(input_text))::JSON INTO transformed_input;
  RETURN transformed_input;
END;
$$;

Ausgabetransformationsfunktion

CREATE OR REPLACE FUNCTION cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS REAL[]
LANGUAGE plpgsql
AS $$
DECLARE
  transformed_output REAL[];
BEGIN
SELECT ARRAY(SELECT json_array_elements_text(response_json->0)) INTO transformed_output;
RETURN transformed_output;
END;
$$;

Funktion zum Generieren von HTTP-Headern

Im Folgenden sehen Sie die Signatur für die Funktion zur Header-Generierung, die mit der Vorhersagefunktion google_ml.embedding() verwendet werden kann, wenn andere Endpunkte für Modelle zur Texteinbettung registriert werden.

  CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

Für die Vorhersagefunktion google_ml.predict_row() lautet die Signatur so:

CREATE OR REPLACE FUNCTION GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON;

Parameter	Beschreibung
GENERATE_HEADERS	Die Funktion zum Generieren benutzerdefinierter Header. Sie können den von der Header-Generierungsfunktion generierten Autorisierungsheader auch beim Registrieren des Modellendpunkts übergeben.

Beispiel für eine Funktion zum Generieren von Headern

Um besser zu verstehen, wie Sie eine Funktion erstellen, die eine Ausgabe in JSON-Schlüssel/Wert-Paaren generiert, die als HTTP-Header verwendet werden, sehen Sie sich einen benutzerdefinierten Endpunkt für ein selbst gehostetes Texteinbettungsmodell an.

Im folgenden Beispiel für eine cURL-Anfrage wird der HTTP-Header version übergeben, der vom Modellendpunkt verwendet wird:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
      -H "Content-Type: application/json" \
      -H "version: 2024-01-01" \
      -d '{"prompt": ["AlloyDB Embeddings"]}'

Das Modell erwartet Texteingaben über das Feld version und gibt den Versionswert im JSON-Format zurück. Im folgenden Beispiel sehen Sie die Funktion zur Header-Generierung, die für diesen Endpunkt des Modelleinbettungsmodells verwendet wird, wenn er bei der Verwaltung von Modellendpunkten registriert wird:

CREATE OR REPLACE FUNCTION header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
BEGIN
  RETURN json_build_object('version', '2024-01-01')::JSON;
END;
$$;

Funktion zum Generieren von Headern mit API-Schlüssel

Die folgenden Beispiele zeigen, wie Sie die Authentifizierung mit dem API-Schlüssel einrichten.

Einbettungsmodell

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  input_text TEXT
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
BEGIN
  RETURN json_build_object('Authorization', 'API_KEY')::JSON;
END;
$$;

Ersetzen Sie API_KEY durch den API-Schlüssel des Modellanbieters.

Generisches Modell

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  response_json JSON
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
transformed_output REAL[];
BEGIN
  -- code to add Auth token to API request
RETURN json_build_object('x-api-key', 'API_KEY', 'model-version', '2023-06-01')::JSON;
END;
$$;

Ersetzen Sie API_KEY durch den API-Schlüssel des Modellanbieters.

Anfrage-URL generieren

Verwenden Sie die Funktion zum Generieren von Anfrage-URLs, um die Anfrage-URLs für die Modellendpunkte mit integrierter Unterstützung abzuleiten. Die Signatur für diese Funktion sieht so aus:

CREATE OR REPLACE FUNCTION GENERATE_REQUEST_URL(provider google_ml.model_provider, model_type google_ml.MODEL_TYPE, model_qualified_name VARCHAR(100), model_region VARCHAR(100) DEFAULT NULL)

Parameter	Beschreibung
GENERATE_REQUEST_URL	Die Funktion zum Generieren der von der Erweiterung generierten Anfrage-URL für Modellendpunkte mit integrierter Unterstützung.

Unterstützte Modelle

Mit der Verwaltung von Modellendpunkten können Sie beliebige Text-Embedding- oder generische Modellendpunkte registrieren. Die Verwaltung von Modellendpunkten umfasst auch vorregistrierte Vertex AI-Modelle und Modelle mit integrierter Unterstützung.

Vorregistrierte Vertex AI-Modelle

Hinweis :Die Unterstützung von Vertex AI-Modellen unterliegt den Richtlinien für die Versionsverwaltung und den Lebenszyklus von Vertex AI-Modellen.

Modelltyp	Modell-ID	Version der Erweiterung
generic	gemini-1.5-pro:streamGenerateContent gemini-1.5-pro:generateContent gemini-1.0-pro:generateContent	Version 1.4.2 und höher
text_embedding	textembedding-gecko text-embedding-gecko@001	Version 1.3 und höher

Modelle mit integrierter Unterstützung

Vertex AI

Qualifizierter Modellname	Modelltyp
text-embedding-gecko@001	text-embedding
text-embedding-gecko@003	text-embedding
text-embedding-004	text-embedding
text-embedding-preview-0815	text-embedding
text-multilingual-embedding-002	text-embedding