Referenz zur Modellendpunktverwaltung

Auf dieser Seite werden Parameter für verschiedene Funktionen aufgeführt, die von der google_ml_integration-Erweiterung zum Registrieren und Verwalten von Modellendpunkten bereitgestellt werden. Auf der Seite sind auch die Secrets aufgeführt, die Sie mit der Verwaltung von Modellendpunkten 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 Parametern für Funktionen, mit denen Sie Modellendpunkte verwalten können.

google_ml.create_model()

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 Endpunkte von Texteinbettungsmodellen mit integrierter Unterstützung

 Der modellspezifische Endpunkt beim Hinzufügen anderer Endpunkte für Texteinbettung und generische Modelle.

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 Texteinbettungsmodellen 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 generische Modellendpunkte Der Modelltyp. Sie können diesen Wert für Endpunkte von Modelle für Texteinbettungen auf text_embedding und für alle anderen Modellendpunkte auf generic festlegen.
MODEL_QUALIFIED_NAME für OpenAI-Modellendpunkte erforderlich; für andere Modellendpunkte optional Der voll qualifizierte Name, falls der Modellendpunkt mehrere Versionen hat oder wenn er vom Modellendpunkt definiert wird, z. B. textembedding-gecko@001 oder textembedding-gecko@002. Da das textembedding-gecko@001-Modell bereits bei der Modellendpunktverwaltung registriert ist, können Sie Einbettungen mit textembedding-gecko@001 als Modell-ID generieren.
AUTH_TYPE Optional, es sei denn, für den Modellendpunkt gelten bestimmte Authentifizierungsanforderungen. 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 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 Funktionsname, den Sie zum Generieren benutzerdefinierter Header festlegen. 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 Texteinbettungsmodellen mit integrierter Unterstützung; nicht für generische Modellendpunkte festlegen Die Funktion zum Transformieren der Eingabe der entsprechenden Vorhersagefunktion in die modellspezifische Eingabe. Weitere Informationen finden Sie unter Transformationsfunktionen.
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. Weitere Informationen finden Sie unter Transformationsfunktionen.

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

google_ml.drop_model()

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 Modellendpunkt, die Sie definieren.

google_ml.list_model()

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 Modellendpunkt, die Sie definieren.

google_ml.model_info_view

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

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 Ihre Cloud SQL-Instanz 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()

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');
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 Ihre Cloud SQL-Instanz 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.drop_sm_secret()

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 festlegen und die anschließend beim Registrieren eines Modellendpunkts verwendet wird.

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

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.

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

google_ml.predict_row()

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.

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

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": ["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 Texteingabe 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, 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": ["Cloud SQL 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;
$$;

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.