Referenz zur Verwaltung von Modellendpunkten

Auf dieser Seite sind Parameter für verschiedene Funktionen aufgeführt, die von Cloud SQL bereitgestellt werden, um Modellendpunkte zu registrieren und zu verwalten. Auf der Seite sind auch die Secrets aufgeführt, die Sie mit der Modellendpunktverwaltung verwalten können.

Modelle

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

mysql.ml_create_model_registration()

Im Folgenden sehen Sie, wie Sie die Funktion mysql.ml_create_model_registration() verwenden, um Metadaten für Modellendpunkte zu registrieren:

  CALL
    mysql.ml_create_model_registration(
      'MODEL_ID',
      'REQUEST_URL',
      'PROVIDER_ID',
      'MODEL_TYPE',
      'MODEL_QUALIFIED_NAME',
      'AUTH_TYPE',
      'AUTH_ID',
      'GENERATE_HEADER_FUNCTION',
      'INPUT_TRANSFORM_FUNCTION',
      'OUTPUT_TRANSFORM_FUNCTION');
Parameter Erforderlich Beschreibung
MODEL_ID Für alle Modellendpunkte erforderlich Eine eindeutige ID für den Modellendpunkt, den Sie definieren.
REQUEST_URL Kann für Vertex AI-Modelle NULL sein Der modellspezifische Endpunkt beim Hinzufügen anderer Modellendpunkte für Texteinbettungen und generischer Modellendpunkte.

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 die model_request_url explizit angeben.

Prüfen Sie bei benutzerdefinierten gehosteten Modellendpunkten, ob der Modellendpunkt über das Internet erreichbar ist.
PROVIDER_ID Erforderlich für Modellendpunkte zur Texteinbettung 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 Kann für generische Modellendpunkte NULL sein Der Modelltyp. Sie können diesen Wert für Modellendpunkte zur Texteinbettung auf text_embedding und für alle anderen Modellendpunkte auf generic festlegen.
MODEL_QUALIFIED_NAME Erforderlich für OpenAI-Modellendpunkte; kann für andere Modellendpunkte NULL sein 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 in der Modellendpunktverwaltung registriert ist, können Sie Einbettungen mit textembedding-gecko@001 als Modell-ID generieren.
AUTH_TYPE Kann NULL sein, sofern für den Modellendpunkt keine bestimmte Authentifizierung erforderlich ist. Der vom Modellendpunkt verwendete Authentifizierungstyp. Sie können ihn entweder auf auth_type_cloudsql_service_agent_iam für Vertex AI-Modelle oder auf auth_type_secret_manager für andere Anbieter festlegen.
AUTH_ID Für Vertex AI-Endpunkte als NULL übergeben; für alle anderen Modellendpunkte erforderlich, in denen Secrets in Secret Manager gespeichert werden Die Secret-ID, die Sie festlegen und die anschließend beim Registrieren eines Modellendpunkts verwendet wird.
GENERATE_HEADER_FUNCTION Kann NULL sein Der Funktionsname, den Sie zum Generieren benutzerdefinierter Header festgelegt haben. Die Signatur dieser Funktion hängt von der mysql.ml_predict_row()-Funktion ab. Weitere Informationen finden Sie unter Funktion zum Generieren von HTTP-Headern.
INPUT_TRANSFORM_FUNCTION Optional für Modellendpunkte zur Texteinbettung 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 Modellendpunkte zur Texteinbettung 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.

mysql.ml_alter_model_registration()

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

    CALL
    mysql.ml_alter_model_registration(
      'MODEL_ID',
      'REQUEST_URL',
      'PROVIDER_ID',
      'MODEL_TYPE',
      'MODEL_QUALIFIED_NAME',
      'AUTH_TYPE',
      'AUTH_ID',
      'GENERATE_HEADER_FUNCTION',
      'INPUT_TRANSFORM_FUNCTION',
      'OUTPUT_TRANSFORM_FUNCTION');

mysql.ml_drop_model_registration()

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

  CALL mysql.ml_drop_model_registration('MODEL_ID');
Parameter Beschreibung
MODEL_ID Eine eindeutige ID für den Modellendpunkt, den Sie definieren.

mysql.ml_list_registered_model()

Im Folgenden sehen Sie, wie Sie die SQL-Funktion mysql.ml_list_registered_model() aufrufen, die zum Auflisten von Informationen zu Modellendpunkten verwendet wird:

  SELECT mysql.ml_list_registered_model('MODEL_ID');
Parameter Beschreibung
MODEL_ID Eine eindeutige ID für den Modellendpunkt, den Sie definieren.

mysql.cloudsql_ml_models

Im Folgenden sehen Sie, wie Sie die Tabelle mysql.cloudsql_ml_models abfragen, die zum Auflisten von Informationen zu Modellendpunkten für alle Modellendpunkte verwendet wird:

  SELECT * FROM mysql.cloudsql_ml_models;

Secrets

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

mysql.ml_create_sm_secret_registration()

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

    CALL
    mysql.ml_create_sm_secret_registration(
      'SECRET_ID',
      '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.

mysql.ml_alter_sm_secret_registration()

Im Folgenden wird gezeigt, wie die SQL-Funktion mysql.ml_alter_sm_secret_registration() aufgerufen wird, mit der Secret-Informationen aktualisiert werden:

  CALL
    mysql.ml_alter_sm_secret_registration(
      'SECRET_ID',
      '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.

mysql.ml_drop_sm_secret_registration()

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

  CALL mysql.ml_drop_sm_secret_registration('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.

mysql.ml_embedding()

Im Folgenden wird gezeigt, wie Einbettungen generiert werden:

SELECT
  mysql.ml_embedding(
    'MODEL_ID',
    'CONTENT');
Parameter Beschreibung
MODEL_ID Eine eindeutige ID für den Modellendpunkt, den 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.

mysql.ml_predict_row()

Im Folgenden wird gezeigt, wie Vorhersagen aufgerufen werden:

SELECT
  mysql.ml_predict_row(
    'MODEL_ID',
    'REQUEST_BODY');
Parameter Beschreibung
MODEL_ID Eine eindeutige ID für den Modellendpunkt, den 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 Ausgabetransformationsfunktionen.

Eingabetransformationsfunktion

Unten sehen Sie die Signatur für die Vorhersagefunktion für Modellendpunkte zur Texteinbettung:

  CREATE FUNCTION IF NOT EXISTS
  INPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;
Parameter Beschreibung
INPUT_TRANSFORM_FUNCTION Die Funktion zum Transformieren der Eingabe der entsprechenden Vorhersagefunktion in die Modellendpunkt-spezifische Eingabe.

Ausgabetransformationsfunktion

Unten sehen Sie die Signatur für die Vorhersagefunktion für Modellendpunkte zur Texteinbettung:

  CREATE FUNCTION IF NOT EXISTS
  OUTPUT_TRANSFORM_FUNCTION(model_id VARCHAR(100), response_json JSON) RETURNS BLOB DETERMINISTIC;
Parameter Beschreibung
OUTPUT_TRANSFORM_FUNCTION Die Funktion zum Transformieren der Modellendpunkt-spezifischen Ausgabe 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 vom Kunden gehosteten Modellendpunkt für Texteinbettungen an, der JSON-Eingaben und -Ausgaben erfordert.

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 eine JSON-Eingabe über das Feld prompt. In dieses Feld kann ein Array von Eingaben eingegeben werden. Da die Funktion mysql.ml_embedding() eine Funktion auf Zeilenebene ist, wird jeweils eine Texteingabe nach der anderen 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 jede Prompteingabe für das Modell. Da die Funktion mysql.ml_embedding() eine Funktion auf Zeilenebene ist, wird jeweils eine Eingabe nach der anderen zurückgegeben. Daher müssen Sie eine Ausgabetransformationsfunktion erstellen, mit der die Einbettung 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

DELIMITER $$
CREATE FUNCTION IF NOT EXISTS cymbal_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
DETERMINISTIC

BEGIN
  RETURN JSON_OBJECT('prompt', JSON_ARRAY(input_text));
END $$

Ausgabetransformationsfunktion

CREATE FUNCTION IF NOT EXISTS cymbal_text_output_transform(model_id VARCHAR(100), response_json JSON)
RETURNS BLOB
DETERMINISTIC

BEGIN
  RETURN STRING_TO_VECTOR(
         JSON_EXTRACT(
              content,
              '$.predictions[0].embeddings.values'
            )
    );

END $$
DELIMITER ;

HTTP header generation function

The following shows signature for the header generation function that can be used with the `mysql.ml_embedding()` prediction function when registering other text embedding model endpoints.

  CREATE FUNCTION IF NOT EXISTS GENERATE_HEADERS(model_id VARCHAR(100), input_text TEXT) RETURNS JSON DETERMINISTIC;

For the mysql.ml_predict_row() prediction function, the signature is as follows:

CREATE FUNCTION IF NOT EXISTS GENERATE_HEADERS(model_id TEXT, input JSON) RETURNS JSON DETERMINISTIC;
Parameter Description
GENERATE_HEADERS The function to generate custom headers. You can also pass the authorization header generated by the header generation function while registering the model endpoint.

Header generation function example

To better understand how to create a function that generates output in JSON key value pairs that are used as HTTP headers, consider a custom-hosted text embedding model endpoint.

The following example curl request passes the version HTTP header, which is used by the model endpoint:

  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"]}'

The model expects text input through the version field and returns the version value in JSON format. The following example shows the header generation function that is used for this text embedding model endpoint when it is registered with model endpoint management:

DELIMITER $$
CREATE FUNCTION IF NOT EXISTS header_gen_fn(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
DETERMINISTIC
BEGIN
  RETURN JSON_OBJECT('version', '2024-01-01');
END;
$$
DELIMITER ;