Esta página se ha traducido con Cloud Translation API.

Referencia de gestión de endpoints de modelos

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 gestionar endpoints de modelos. En la página también se indican los secretos que puedes gestionar mediante la gestión de endpoints de modelos. Para usar modelos de IA en entornos de producción, consulta Crea aplicaciones de IA generativa con Cloud SQL.

Modelos

Usa esta referencia para conocer los parámetros de las funciones que te permiten gestionar los endpoints de los modelos.

`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 endpoint 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 endpoints de modelos.	Un ID único que definas para el endpoint del modelo.
`REQUEST_URL`	Opcional para los endpoints de modelos de incrustaciones de texto con compatibilidad integrada	El endpoint específico del modelo al añadir otros endpoints de modelos genéricos y de inserciones de texto. La URL de solicitud que genera la función para los endpoints de modelos integrados hace referencia al proyecto y a la región o ubicación de tu clúster. Si quieres hacer referencia a otro proyecto, asegúrate de especificar el `model_request_url` explícitamente. En el caso de los endpoints de modelos alojados personalizados, asegúrate de que se pueda acceder a ellos a través de Internet.
`PROVIDER_ID`	Obligatorio para los endpoints de modelos de incrustaciones de texto con compatibilidad integrada	El proveedor del endpoint del modelo. El valor predeterminado es `custom`. En Cloud SQL, define el proveedor como `google` para los endpoints de modelos de Vertex AI, `open_ai` para los endpoints de modelos de OpenAI, `anthropic` para los endpoints de modelos de Anthropic, `hugging_face` para los endpoints de modelos de Hugging Face o `custom` para los endpoints de modelos alojados personalizados.
`MODEL_TYPE`	Opcional para los endpoints de modelos genéricos	El tipo de modelo. Puedes definir este valor como `text_embedding` para los endpoints del modelo de inserción de texto o `generic` para todos los demás endpoints del modelo.
`MODEL_QUALIFIED_NAME`	Obligatorio para los endpoints de modelos de OpenAI y opcional para otros endpoints de modelos.	El nombre completo en caso de que el endpoint del modelo tenga varias versiones o si el endpoint del modelo lo define (por ejemplo, `textembedding-gecko@001` o `textembedding-gecko@002`). Como el modelo `textembedding-gecko@001` está pre-registrado en la gestión de endpoints de modelos, puedes generar embeddings usando `textembedding-gecko@001` como ID de modelo.
`AUTH_TYPE`	Opcional, a menos que el endpoint del modelo tenga un requisito de autenticación específico.	El tipo de autenticación que usa el endpoint del modelo. Puedes definirlo como `cloudsql_service_agent_iam` para los modelos de Vertex AI o como `secret_manager` para otros proveedores.
`AUTH_ID`	No se define para los endpoints de modelos de Vertex AI. Es obligatorio para todos los demás endpoints de modelos que almacenan secretos en Secret Manager.	El ID secreto que has definido y que se usa posteriormente al registrar un endpoint de modelo.
`GENERATE_HEADER_FUNCTION`	opcional	El nombre de la función que has definido para generar encabezados personalizados. La firma de esta función depende de la función `google_ml.predict_row()`. Consulta la función de generación de encabezados HTTP.
`INPUT_TRANSFORM_FUNCTION`	Opcional para los endpoints de modelos de inserciones de texto con compatibilidad integrada. No se debe definir para los endpoints de modelos genéricos.	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`	Opcional para los endpoints de modelos de inserciones de texto con compatibilidad integrada. No se debe definir para los endpoints de modelos genéricos.	Función para transformar la salida específica del modelo en la salida 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 endpoint 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 eliminar un endpoint de modelo:

  CALL google_ml.drop_model('MODEL_ID');

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

`google_ml.list_model()`

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

  SELECT google_ml.list_model('MODEL_ID');

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

`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 de los endpoints de modelo de todos los endpoints de modelo:

  SELECT * FROM google_ml.model_info_view;

Secretos

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

`google_ml.create_sm_secret()`

A continuación, se muestra cómo llamar a la función SQL google_ml.create_sm_secret() para añadir 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`	El ID secreto que has definido y que se usa posteriormente al registrar un endpoint de modelo.
`PROJECT_ID`	El ID del proyecto 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 del secreto definido en Secret Manager al crear el secreto.
`VERSION_NUMBER`	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 de secretos:

  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`	El ID secreto que has definido y que se usa posteriormente al registrar un endpoint de modelo.
`PROJECT_ID`	El ID del proyecto 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 del secreto definido en Secret Manager al crear el secreto.
`VERSION_NUMBER`	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() para eliminar un secreto:

  CALL google_ml.drop_sm_secret('SECRET_ID');

Parámetro	Descripción
`SECRET_ID`	El ID secreto que has definido y que se usa posteriormente al registrar un endpoint de modelo.

Funciones de predicción

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

`google_ml.embedding()`

A continuación, se muestra cómo generar las inserciones:

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

Parámetro	Descripción
`MODEL_ID`	Un ID único que definas para el endpoint del modelo.
`CONTENT`	el texto que se va a traducir a una incrustación de vector.

Para ver ejemplos de consultas de SQL para generar incrustaciones de texto, consulta la sección 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 que definas para el endpoint del modelo.
`REQUEST_BODY`	Los parámetros de la función de predicción, en formato JSON.

Para ver ejemplos de consultas SQL para invocar predicciones, consulta la sección Ejemplos.

Transformar funciones

Usa esta referencia para entender 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 de los endpoints del modelo de inserció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`	Función para transformar la entrada de la función de predicción correspondiente en la entrada específica del endpoint del modelo.

Función de transformación de salida

A continuación, se muestra la firma de la función de predicción de los endpoints del modelo de inserció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`	Función para transformar la salida específica del endpoint del modelo en la salida de la función de predicción.

Ejemplo de funciones de transformación

Para entender mejor cómo crear funciones de transformación para el endpoint de tu modelo, considera un endpoint de modelo de inserciones de texto alojado de forma personalizada que requiera entradas y salidas JSON.

La siguiente solicitud curl de ejemplo crea inserciones basadas en la petición y el endpoint 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 devuelve 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]]

A partir de esta entrada y respuesta, puedes deducir lo siguiente:

El modelo espera una entrada JSON a través del campo prompt. Este campo acepta una matriz de entradas. Como la función google_ml.embedding() es una función a nivel de fila, espera una entrada de texto cada vez. Por lo tanto, debe crear una función de transformación de entrada que genere una matriz con un solo elemento.
La respuesta del modelo es una matriz de inserciones, una por cada petición introducida en el modelo. Como la función google_ml.embedding() es una función de nivel de fila, devuelve una sola entrada cada vez. Por lo tanto, debes crear una función de transformación de salida que se pueda usar para extraer la inserción de la matriz.

En el siguiente ejemplo se muestran las funciones de transformación de entrada y salida que se usan en este endpoint de modelo cuando se registra en la gestión de endpoints de modelos:

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() al registrar otros endpoints de modelos de inserciones de texto.

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

En el caso de 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`	Función para generar encabezados personalizados. También puede enviar el encabezado de autorización generado por la función de generación de encabezados al registrar el endpoint del modelo.

Ejemplo de función de generación de encabezados

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

En el siguiente ejemplo de solicitud curl se envía el encabezado HTTP version, que utiliza el endpoint 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 devuelve 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 endpoint del modelo de inserción de texto cuando se registra con la gestión de endpoints de modelos:

sql
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 endpoints del modelo con asistencia 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`	Función para generar la URL de solicitud generada por la extensión para los endpoints del modelo con asistencia integrada.

Referencia de gestión de endpoints de modelos Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.

Modelos

google_ml.create_model()

google_ml.alter_model()

google_ml.drop_model()

google_ml.list_model()

google_ml.model_info_view