Referenz zur Modellendpunktverwaltung

Auf dieser Seite sind die Parameter für die verschiedenen Funktionen aufgeführt, die von der google_ml_integration-Erweiterung zum Registrieren und Verwalten von Modellendpunkten bereitgestellt werden. Auf der Seite werden auch die Secrets aufgeführt, die Sie mithilfe der Modellendpunktverwaltung verwalten können. Informationen zur Verwendung von KI-Modellen in Produktionsumgebungen finden Sie unter Generative KI-Anwendungen mit Cloud SQL erstellen.

Modelle

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

google_ml.create_model()

Im Folgenden wird gezeigt, 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 Erforderlich für alle Modellendpunkte Eine eindeutige ID für den von Ihnen definierten Modellendpunkt.
REQUEST_URL

Optional für Endpunkte von Texteinbettungsmodellen mit integrierter Unterstützung

Der modellspezifische Endpunkt, wenn Sie andere Endpunkte für Text-Embedding und generische Modellendpunkte hinzufügen.

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.

Bei benutzerdefinierten gehosteten Modellendpunkten muss der Modellendpunkt über das Internet zugänglich sein.

PROVIDER_ID Erforderlich für Endpunkte von Modelleinbettungen für Texte mit integrierter Unterstützung Der Anbieter des Modellendpunkts. Der Standardwert ist custom. Legen Sie für Cloud SQL den Anbieter auf google für Vertex AI-Modellendpunkte, open_ai für OpenAI-Modellendpunkte, anthropic für Anthropic-Modellendpunkte, hugging_face für Hugging Face-Modellendpunkte oder custom für benutzerdefinierte gehostete Modellendpunkte fest.
MODEL_TYPE Optional für Endpunkte für generische Modelle Der Modelltyp. Sie können diesen Wert auf text_embedding für Endpunkte von Modellen für Texteinbettungen oder auf generic für alle anderen Modellendpunkte festlegen.
MODEL_QUALIFIED_NAME Erforderlich für OpenAI-Modellendpunkte, optional für andere Modellendpunkte Der voll qualifizierte Name, falls der Modellendpunkt mehrere Versionen hat oder vom Modellendpunkt definiert wird, z. B. textembedding-gecko@001 oder textembedding-gecko@002. Da das Modell textembedding-gecko@001 bereits für die Modellendpunktverwaltung registriert ist, können Sie textembedding-gecko@001 als Modell-ID verwenden, um Einbettungen zu generieren.
AUTH_TYPE Optional, es sei denn, der Modellendpunkt hat eine bestimmte Authentifizierungsanforderung Der vom Modellendpunkt verwendete Authentifizierungstyp. Sie können sie entweder auf cloudsql_service_agent_iam für Vertex AI-Modelle oder auf secret_manager für andere Anbieter festlegen.
AUTH_ID Nicht für Vertex AI-Modellendpunkte festgelegt; erforderlich für alle anderen Modellendpunkte, in denen Geheimnisse im Secret Manager gespeichert werden Die Secret-ID, die Sie festlegen und die anschließend bei der Registrierung eines Modellendpunkts verwendet wird.
GENERATE_HEADER_FUNCTION optional Der Funktionsname, den Sie zum Generieren benutzerdefinierter Header festgelegt haben. Die Signatur dieser Funktion hängt von der google_ml.predict_row()-Funktion ab. Weitere Informationen finden Sie unter Funktion zum Generieren von HTTP-Headern.
INPUT_TRANSFORM_FUNCTION Optional für Endpunkte von Modellen für Texteinbettungen mit integrierter Unterstützung; nicht für Endpunkte von generischen Modellen festlegen Die Funktion, mit der die Eingabe der entsprechenden Vorhersagefunktion in die modellspezifische Eingabe umgewandelt wird. Weitere Informationen finden Sie unter Transformationsfunktionen.
OUTPUT_TRANSFORM_FUNCTION Optional für Endpunkte von Modellen für Texteinbettungen mit integrierter Unterstützung; nicht für Endpunkte von generischen Modellen festlegen Die Funktion, mit der die modellspezifische Ausgabe in die Ausgabe der Vorhersagefunktion umgewandelt wird. Weitere Informationen finden Sie unter Transformationsfunktionen.

google_ml.alter_model()

Im Folgenden wird gezeigt, wie die SQL-Funktion google_ml.alter_model() aufgerufen wird, die zum Aktualisieren der Metadaten des Modellendpunkts verwendet wird:

    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');

google_ml.drop_model()

Im Folgenden wird gezeigt, wie die SQL-Funktion google_ml.drop_model() aufgerufen wird, um einen Modellendpunkt zu erstellen:

  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()

Im Folgenden wird gezeigt, wie die SQL-Funktion google_ml.list_model() aufgerufen wird, um Informationen zu Modellendpunkten aufzulisten:

  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

Im Folgenden wird gezeigt, wie die Ansicht google_ml.model_info_view aufgerufen wird, in der Informationen zu Modellendpunkten für alle Modellendpunkte aufgelistet werden:

  SELECT * FROM google_ml.model_info_view;

Secrets

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

google_ml.create_sm_secret()

Im Folgenden wird gezeigt, wie die SQL-Funktion google_ml.create_sm_secret() aufgerufen wird, mit der das im Secret Manager erstellte Secret hinzugefügt wird:

    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 bei der Registrierung eines Modellendpunkts verwendet wird.
PROJECT_ID Die ID des Projekts Google Cloud , das das Secret enthält. Dieses Projekt kann sich von dem Projekt unterscheiden, das Ihre Cloud SQL-Instanz enthält.
SECRET_MANAGER_SECRET_ID Die Secret-ID, die Sie beim Erstellen des Secrets in Secret Manager festgelegt haben.
VERSION_NUMBER Die Versionsnummer der Secret-ID.

google_ml.alter_sm_secret()

Im Folgenden wird gezeigt, wie die SQL-Funktion google_ml.alter_sm_secret() aufgerufen wird, die zum Aktualisieren von geheimen Informationen verwendet wird:

  CALL
    google_ml.alter_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 bei der Registrierung eines Modellendpunkts verwendet wird.
PROJECT_ID Die ID des Projekts Google Cloud , das das Secret enthält. Dieses Projekt kann sich von dem Projekt unterscheiden, das Ihre Cloud SQL-Instanz enthält.
SECRET_MANAGER_SECRET_ID Die Secret-ID, die Sie beim Erstellen des Secrets in Secret Manager festgelegt haben.
VERSION_NUMBER Die Versionsnummer der Secret-ID.

google_ml.drop_sm_secret()

Im Folgenden wird gezeigt, wie die SQL-Funktion google_ml.drop_sm_secret() aufgerufen wird, die zum Löschen eines Secrets verwendet wird:

  CALL google_ml.drop_sm_secret('SECRET_ID');
Parameter Beschreibung
SECRET_ID Die Secret-ID, die Sie festlegen und die anschließend bei der Registrierung eines Modellendpunkts verwendet wird.

Vorhersagefunktionen

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

google_ml.embedding()

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 von Ihnen definierten Modellendpunkt.
CONTENT den Text, der in eine Vektoreinbettung umgewandelt werden soll.

Beispiele für SQL-Abfragen zum Generieren von Texteinbettungen finden Sie unter Beispiele.

google_ml.predict_row()

So rufen Sie Vorhersagen auf:

SELECT
  google_ml.predict_row(
    model_id => 'MODEL_ID',
    request_body => 'REQUEST_BODY');
Parameter Beschreibung
MODEL_ID Eine eindeutige ID für den von Ihnen definierten Modellendpunkt.
REQUEST_BODY die Parameter für die Vorhersagefunktion im JSON-Format.

Beispiele für SQL-Abfragen zum Aufrufen von Vorhersagen finden Sie unter Beispiele.

Transformationsfunktionen

In dieser Referenz finden Sie Informationen zu den Parametern für Eingabe- und Ausgabetransformationsfunktionen.

Eingabetransformationsfunktion

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

  CREATE OR REPLACE FUNCTION INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;
Parameter Beschreibung
INPUT_TRANSFORM_FUNCTION Die Funktion, mit der die Eingabe der entsprechenden Vorhersagefunktion in die modellspezifische Eingabe für den Endpunkt umgewandelt wird.

Ausgabetransformationsfunktion

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

  CREATE OR REPLACE FUNCTION OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS real[];
Parameter Beschreibung
OUTPUT_TRANSFORM_FUNCTION Die Funktion, mit der die modellspezifische Endpunktausgabe in die Ausgabe der Vorhersagefunktion umgewandelt wird.

Beispiel für Transformationsfunktionen

Um besser zu verstehen, wie Sie Transformationsfunktionen für Ihren Modellendpunkt erstellen, betrachten Sie einen benutzerdefinierten gehosteten Endpunkt für ein Text-Embedding-Modell, der JSON-Eingabe und ‑Ausgabe erfordert.

In der folgenden Beispiel-cURL-Anfrage werden basierte auf dem Prompt und dem Modellendpunkt Einbettungen erstellt:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
    -H "Content-Type: application/json"
    -d '{"prompt": ["Cloud SQL 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 Sie 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 Textzeile erwartet. Sie müssen also 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, gibt sie jeweils nur eine Eingabe zurück. Sie müssen also eine Ausgabetransformationsfunktion erstellen, mit der das Einbetten aus dem Array extrahiert werden kann.

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

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;
$$;
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 Headergenerierung, die mit der Vorhersagefunktion google_ml.embedding() verwendet werden kann, wenn Sie andere Endpunkte für Modelle zur Texteinbettung registrieren.

  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:

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 Autorisierungsheader, der von der Funktion zur Headergenerierung generiert wird, 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 gehosteten Endpunkt für das Modell zum Einbetten von Text an.

In der folgenden Beispiel-cURL-Anfrage wird der version-HTTP-Header ü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": ["Cloud SQL Embeddings"]}'

Das Modell erwartet eine Texteingabe über das Feld version und gibt den Versionswert im JSON-Format zurück. Im folgenden Beispiel wird die Funktion zum Generieren von Headern gezeigt, die für diesen Endpunkt des Modells für Text-Embeddings verwendet wird, wenn er bei der Modellendpunktverwaltung registriert ist:

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;
$$;

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. Hier sehen Sie die Signatur für diese Funktion:

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 Anfrage-URL, die von der Erweiterung für Modellendpunkte mit integrierter Unterstützung generiert wird.