Referencia de administración de extremos del modelo

Vista previa

Este producto está sujeto a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones específicas del Servicio. Los productos de la fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

MySQL   |  PostgreSQL   |  SQL Server

En esta página, se enumeran los parámetros de las diferentes funciones que proporciona la extensión google_ml_integration para registrar y administrar los extremos de modelos. En la página, también se enumeran los secretos que puedes administrar con la administración de extremos de modelos. Para usar modelos de IA en entornos de producción, consulta Compila aplicaciones de IA generativa con Cloud SQL.

Nota: Antes de que puedas comenzar a usar la extensión para la administración de extremos de modelos, debes establecer la marca de base de datos google_ml_integration.enable_model_support en on. Además, para obtener más información sobre la administración de extremos de modelos, consulta Cómo registrar y llamar a modelos de IA remotos en Cloud SQL.

Modelos

Usa esta referencia para comprender los parámetros de las funciones que te permiten administrar los extremos del modelo.

google_ml.create_model()

A continuación, se muestra cómo llamar a la función SQL google_ml.create_model() que se usa para registrar los metadatos del extremo del modelo:

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

Parámetro	Obligatorio	Descripción
MODEL_ID	obligatorio para todos los extremos de modelos	Un ID único para el extremo del modelo que definas.
REQUEST_URL	Opcional para los extremos de modelos de incorporación de texto con compatibilidad integrada	El extremo específico del modelo cuando se agregan otros extremos de modelos genéricos y de incorporación de texto La URL de solicitud que genera la función para los extremos de modelos integrados hace referencia al proyecto y la región o ubicación de tu clúster. Si deseas hacer referencia a otro proyecto, asegúrate de especificar model_request_url de forma explícita. En el caso de los extremos de modelos alojados personalizados, asegúrate de que se pueda acceder al extremo del modelo a través de Internet.
PROVIDER_ID	obligatorio para los extremos de modelos de incorporación de texto con compatibilidad integrada	El proveedor del extremo del modelo El valor predeterminado es custom. Para Cloud SQL, establece el proveedor en google para los extremos de modelos de Vertex AI, open_ai para los extremos de modelos de OpenAI, anthropic para los extremos de modelos de Anthropic, hugging_face para los extremos de modelos de Hugging Face o custom para los extremos de modelos alojados de forma personalizada.
MODEL_TYPE	opcional para extremos de modelos genéricos	El tipo de modelo. Puedes establecer este valor en text_embedding para los extremos de modelos de incorporación de texto o en generic para todos los demás extremos de modelos.
MODEL_QUALIFIED_NAME	obligatorio para los extremos de modelos de OpenAI; opcional para otros extremos de modelos	Es el nombre completamente calificado en caso de que el extremo del modelo tenga varias versiones o si el extremo del modelo lo define, por ejemplo, textembedding-gecko@001 o textembedding-gecko@002. Dado que el modelo textembedding-gecko@001 está registrado previamente con la administración de extremos de modelos, puedes generar incorporaciones con textembedding-gecko@001 como el ID del modelo.
AUTH_TYPE	Es opcional, a menos que el extremo del modelo tenga un requisito de autenticación específico.	Es el tipo de autenticación que usa el extremo del modelo. Puedes establecerlo en cloudsql_service_agent_iam para modelos de Vertex AI o en secret_manager para otros proveedores.
AUTH_ID	No se establece para los extremos de modelos de Vertex AI; es obligatorio para todos los demás extremos de modelos que almacenan secretos en Secret Manager	Es el ID secreto que configuraste y que se usa posteriormente cuando se registra un extremo de modelo.
GENERATE_HEADER_FUNCTION	opcional	Es el nombre de la función que configuraste para generar encabezados personalizados. La firma de esta función depende de la función google_ml.predict_row(). Consulta Función de generación de encabezados HTTP.
INPUT_TRANSFORM_FUNCTION	Es opcional para los extremos de modelos de incorporación de texto con compatibilidad integrada. No se establece para los extremos de modelos genéricos.	Es la función para transformar la entrada de la función de predicción correspondiente en la entrada específica del modelo. Consulta Funciones de transformación.
OUTPUT_TRANSFORM_FUNCTION	Es opcional para los extremos de modelos de incorporación de texto con compatibilidad integrada. No se establece para los extremos de modelos genéricos.	Es la función para transformar el resultado específico del modelo en el resultado de la función de predicción. Consulta Funciones de transformación.

google_ml.alter_model()

A continuación, se muestra cómo llamar a la función SQL google_ml.alter_model() que se usa para actualizar los metadatos del extremo del modelo:

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

A continuación, se muestra cómo llamar a la función SQL google_ml.drop_model() que se usa para descartar un extremo de modelo:

  CALL google_ml.drop_model('MODEL_ID');

Parámetro	Descripción
MODEL_ID	Un ID único para el extremo del modelo que definas.

google_ml.list_model()

A continuación, se muestra cómo llamar a la función de SQL google_ml.list_model() que se usa para enumerar la información del extremo del modelo:

  SELECT google_ml.list_model('MODEL_ID');

Parámetro	Descripción
MODEL_ID	Un ID único para el extremo del modelo que definas.

google_ml.model_info_view

A continuación, se muestra cómo llamar a la vista google_ml.model_info_view que se usa para enumerar la información del extremo del modelo para todos los extremos del modelo:

  SELECT * FROM google_ml.model_info_view;

Secrets

Usa esta referencia para comprender los parámetros de las funciones que te permiten administrar secretos.

google_ml.create_sm_secret()

A continuación, se muestra cómo llamar a la función SQL google_ml.create_sm_secret() que se usa para agregar el secreto creado en Secret Manager:

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

Parámetro	Descripción
SECRET_ID	Es el ID secreto que estableces y que se usa posteriormente cuando registras un extremo de modelo.
PROJECT_ID	El ID de tu proyecto de Google Cloud que contiene el secreto Este proyecto puede ser diferente del que contiene tu instancia de Cloud SQL.
SECRET_MANAGER_SECRET_ID	El ID de secreto establecido en Secret Manager cuando creaste el secreto
VERSION_NUMBER	El número de versión del ID del secreto.

google_ml.alter_sm_secret()

A continuación, se muestra cómo llamar a la función SQL google_ml.alter_sm_secret() que se usa para actualizar la información secreta:

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

Parámetro	Descripción
SECRET_ID	Es el ID secreto que estableces y que se usa posteriormente cuando registras un extremo de modelo.
PROJECT_ID	El ID de tu proyecto de Google Cloud que contiene el secreto Este proyecto puede ser diferente del que contiene tu instancia de Cloud SQL.
SECRET_MANAGER_SECRET_ID	El ID de secreto establecido en Secret Manager cuando creaste el secreto
VERSION_NUMBER	El número de versión del ID del secreto.

google_ml.drop_sm_secret()

A continuación, se muestra cómo llamar a la función SQL google_ml.drop_sm_secret() que se usa para descartar un secreto:

  CALL google_ml.drop_sm_secret('SECRET_ID');

Parámetro	Descripción
SECRET_ID	Es el ID secreto que estableces y que se usa posteriormente cuando registras un extremo de modelo.

Funciones de predicción

Usa esta referencia para comprender los parámetros de las funciones que te permiten generar incorporaciones o invocar predicciones.

google_ml.embedding()

A continuación, se muestra cómo generar incorporaciones:

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

Parámetro	Descripción
MODEL_ID	Un ID único para el extremo del modelo que definas.
CONTENT	el texto que se traducirá en una incorporación de vectores.

Para ver ejemplos de consultas de SQL para generar incorporaciones de texto, consulta Ejemplos.

google_ml.predict_row()

A continuación, se muestra cómo invocar predicciones:

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

Parámetro	Descripción
MODEL_ID	Un ID único para el extremo del modelo que definas.
REQUEST_BODY	los parámetros de la función de predicción, en formato JSON

Para obtener ejemplos de consultas de SQL para invocar predicciones, consulta Ejemplos.

Funciones de transformación

Usa esta referencia para comprender los parámetros de las funciones de transformación de entrada y salida.

Función de transformación de entrada

A continuación, se muestra la firma de la función de predicción para los extremos del modelo de incorporación de texto:

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

Parámetro	Descripción
INPUT_TRANSFORM_FUNCTION	Es la función para transformar la entrada de la función de predicción correspondiente en la entrada específica del extremo del modelo.

Función de transformación de salida

A continuación, se muestra la firma de la función de predicción para los extremos del modelo de incorporación de texto:

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

Parámetro	Descripción
OUTPUT_TRANSFORM_FUNCTION	Es la función para transformar el resultado específico del extremo del modelo en el resultado de la función de predicción.

Ejemplo de funciones de transformación

Para comprender mejor cómo crear funciones de transformación para el extremo de tu modelo, considera un extremo de modelo de incorporación de texto alojado de forma personalizada que requiera entrada y salida de JSON.

En la siguiente solicitud cURL de ejemplo, se crean incorporaciones basadas en la instrucción y el extremo del modelo:

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

Se muestra la siguiente respuesta de ejemplo:

[[ 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]]

En función de esta entrada y respuesta, puedes inferir lo siguiente:

• El modelo espera una entrada JSON a través del campo prompt. Este campo acepta un array de entradas. Como la función google_ml.embedding() es una función a nivel de la fila, espera una entrada de texto a la vez. Por lo tanto, debes crear una función de transformación de entrada que cree un array con un solo elemento.

• La respuesta del modelo es un array de incorporaciones, una para cada entrada de instrucción al modelo. Como la función google_ml.embedding() es una función a nivel de la fila, muestra una sola entrada a la vez. Por lo tanto, debes crear una función de transformación de salida que se pueda usar para extraer la incorporación del array.

En el siguiente ejemplo, se muestran las funciones de transformación de entrada y salida que se usan para este extremo de modelo cuando se registra con la administración de extremos de modelo:

función de transformación de entrada

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

función de transformación de salida

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

Función de generación de encabezados HTTP

A continuación, se muestra la firma de la función de generación de encabezados que se puede usar con la función de predicción google_ml.embedding() cuando se registran otros extremos de modelos de incorporación de texto.

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

Para la función de predicción google_ml.predict_row(), la firma es la siguiente:

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

Parámetro	Descripción
GENERATE_HEADERS	Es la función para generar encabezados personalizados. También puedes pasar el encabezado de autorización que genera la función de generación de encabezados mientras registras el extremo del modelo.

Ejemplo de función de generación de encabezados

Para comprender mejor cómo crear una función que genere resultados en pares clave-valor JSON que se usan como encabezados HTTP, considera un extremo de modelo de incorporación de texto alojado de forma personalizada.

En la siguiente solicitud de ejemplo de cURL, se pasa el encabezado HTTP version, que usa el extremo del modelo:

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

El modelo espera una entrada de texto a través del campo version y muestra el valor de la versión en formato JSON. En el siguiente ejemplo, se muestra la función de generación de encabezados que se usa para este extremo de modelo de incorporación de texto cuando se registra con la administración de extremos de modelos:

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

Generación de URLs de solicitud

Usa la función de generación de URLs de solicitud para inferir las URLs de solicitud de los extremos del modelo con compatibilidad integrada. A continuación, se muestra la firma de esta función:

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)

Parámetro	Descripción
GENERATE_REQUEST_URL	Es la función para generar la URL de solicitud que genera la extensión para extremos de modelos con compatibilidad integrada.