En esta página, se documenta la versión 15.7.0 de AlloyDB Omni con la opción de implementación de Kubernetes. Elige otra opción de implementación.

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

Referencia de gestión de endpoints de modelos

Selecciona una versión de la documentación:

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, así como secretos con la gestión de endpoints de modelos.

Debes definir la marca de base de datos google_ml_integration.enable_model_support en on para poder empezar a usar la extensión.

Para obtener más información, consulta Usar la gestión de puntos finales de modelos con AlloyDB Omni para modelos de IA.

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()` función

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 otros 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. En el caso de AlloyDB para PostgreSQL, proporciona una `https`URL. 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. Para ver una lista de URLs de solicitud de los endpoints de modelos de Vertex AI, consulta URL de solicitud de los endpoints de modelos de Vertex AI. En el caso de los endpoints de modelos alojados personalizados, asegúrate de que se pueda acceder al endpoint del modelo desde la red en la que se encuentra AlloyDB.
`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`. Se debe configurar como uno de los siguientes valores: `google` para endpoints de modelos de Vertex AI `open_ai` para endpoints de modelos de OpenAI `hugging_face` para endpoints de modelos de Hugging Face `anthropic` para endpoints de modelos de Anthropic `custom` para otros proveedores
`MODEL_TYPE`	Opcional para los endpoints de modelos genéricos	El tipo de modelo. Se debe configurar como uno de los siguientes valores: `text_embedding` para endpoints de modelos de inserciones de texto `generic` para todos los demás endpoints de modelos
`MODEL_QUALIFIED_NAME`	Obligatorio para los modelos de inserciones de texto con compatibilidad integrada; opcional para otros endpoints de modelos	Nombre completo de los modelos de inserciones de texto con asistencia integrada. Para ver los nombres cualificados de Vertex AI que debes usar en los modelos pre-registrados, consulta Modelos de Vertex AI pre-registrados. Para ver los nombres cualificados que debes usar en los modelos de OpenAI con asistencia integrada, consulta Modelos con asistencia integrada.
`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 `alloydb_service_agent_iam` para los modelos de Vertex AI o como `secret_manager` para otros proveedores, si usan Secret Manager para la autenticación. No es necesario que defina este valor si usa encabezados de autenticación.
`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	Nombre de la función que genera encabezados personalizados. En el caso de los modelos de Anthropic, la gestión de los endpoints de los modelos proporciona una función `google_ml.anthropic_claude_header_gen_fn` que puedes usar para las versiones predeterminadas. La firma de esta función depende de la función de predicción que utilices. Consulta la función de generación de encabezados.
`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');

Para obtener información sobre los valores que debe definir en cada parámetro, consulte Crear un modelo.

`google_ml.drop_model()` función

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 del endpoint del modelo que has definido.

`google_ml.list_model()` función

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 del endpoint del modelo que has definido.

`google_ml.model_info_view` vista

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()` función

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.
`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()` función

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

Para obtener información sobre los valores que debe definir en cada parámetro, consulte Crear un secreto.

`google_ml.drop_sm_secret()` función

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 ha usado 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()` función

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 inserciones de texto, consulta Ejemplos de funciones de transformación para AlloyDB Omni.

`google_ml.predict_row()` función

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 de SQL para invocar predicciones, consulta Invocar predicciones con modelos genéricos.

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 incrustaciones basadas en la petición y en el endpoint del modelo:

  curl -m 100 -X POST https://cymbal.com/models/text/embeddings/v1 \
    -H "Content-Type: application/json" 
    -d '{"prompt": ["AlloyDB 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 información y respuesta, podemos 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 de nivel de fila, espera una entrada de texto cada vez. Por lo tanto,debes crear una función de transformación de entrada que cree 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 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": ["AlloyDB 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:

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

Función de generación de encabezados mediante una clave de API

En los siguientes ejemplos se muestra cómo configurar la autenticación mediante la clave de API.

Modelo de embedding

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  input_text TEXT
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
BEGIN
  RETURN json_build_object('Authorization', 'API_KEY')::JSON;
END;
$$;

Sustituye API_KEY por la clave de API del proveedor del modelo.

modelo genérico

CREATE OR REPLACE FUNCTION header_gen_func(
  model_id VARCHAR(100),
  response_json JSON
)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
transformed_output REAL[];
BEGIN
  -- code to add Auth token to API request
RETURN json_build_object('x-api-key', 'API_KEY', 'anthropic-version', '2023-06-01')::JSON;
END;
$$;

Sustituye API_KEY por la clave de API del proveedor del modelo.

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.

Modelos admitidos

Puedes usar la gestión de endpoints de modelos para registrar cualquier endpoint de modelo genérico o de inserción de texto. La gestión de endpoints de modelos también incluye modelos de Vertex AI pre-registrados y modelos con asistencia integrada. Para obtener más información sobre los distintos tipos de modelos, consulta Tipo de modelo.

Modelos de Vertex AI pre-registrados

Tipo de modelo	ID del modelo	Versión de la extensión
`generic`	`gemini-1.5-pro:streamGenerateContent` `gemini-1.5-pro:generateContent` `gemini-1.0-pro:generateContent`	Versión 1.4.2 y posteriores
`text_embedding`	`textembedding-gecko` `text-embedding-gecko@001`	Versión 1.3 y posteriores

Modelos con compatibilidad integrada

Vertex AI

Nombre de modelo cualificado	Tipo de modelo
`text-embedding-gecko@001`	`text-embedding`
`text-embedding-gecko@003`	`text-embedding`
`text-embedding-004`	`text-embedding`
`text-embedding-005`	`text-embedding`
`text-embedding-preview-0815`	`text-embedding`
`text-multilingual-embedding-002`	`text-embedding`

OpenAI

Nombre de modelo cualificado	Tipo de modelo
`text-embedding-ada-002`	`text-embedding`
`text-embedding-3-small`	`text-embedding`
`text-embedding-3-large`	`text-embedding`

Anthropic

Nombre de modelo cualificado	Tipo de modelo
`claude-3-opus-20240229`	`generic`
`claude-3-sonnet-20240229`	`generic`
`claude-3-haiku-20240307`	`generic`