En esta página, se muestra la documentación de la versión 15.7.0 de AlloyDB Omni.
Ve a Versiones de la documentación de AlloyDB Omni para elegir una versión diferente.

Se usó la API de Cloud Translation para traducir esta página.

Referencia de administración de extremos del modelo

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 extremos de modelos, y secretos con la administración de extremos de modelos.

Debes establecer la marca de la base de datos google_ml_integration.enable_model_support en on antes de comenzar a usar la extensión.

Para obtener más información, consulta Cómo usar la administración de extremos de modelos con AlloyDB Omni para modelos de IA.

Modelos

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

Función `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`	Es opcional para otros 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 Para AlloyDB para PostgreSQL, proporciona una URL de `https`. 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. Para obtener una lista de las URLs de solicitud de los extremos de los modelos de Vertex AI, consulta URL de solicitud de los extremos de los modelos de Vertex AI. En el caso de los extremos de modelos alojados personalizados, asegúrate de que se pueda acceder al extremo del modelo desde la red en la que se encuentra AlloyDB.
`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`. Establece una de las siguientes opciones: `google` para extremos de modelos de Vertex AI `open_ai` para extremos de modelos de OpenAI `hugging_face` para extremos de modelos de Hugging Face `anthropic` para extremos de modelos de Anthropic `custom` para otros proveedores
`MODEL_TYPE`	opcional para extremos de modelos genéricos	El tipo de modelo. Configúralo en uno de los siguientes valores: `text_embedding` para extremos de modelos de incorporación de texto `generic` para todos los demás extremos de modelos
`MODEL_QUALIFIED_NAME`	obligatorio para los modelos de incorporación de texto con compatibilidad integrada; opcional para otros extremos de modelos	Es el nombre completamente calificado de los modelos de incorporación de texto con compatibilidad integrada. Para conocer los nombres calificados de Vertex AI que debes usar para los modelos registrados previamente, consulta Modelos de Vertex AI registrados previamente. Para conocer los nombres calificados que debes usar para los modelos de OpenAI con compatibilidad integrada, consulta Modelos con compatibilidad integrada.
`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 `alloydb_service_agent_iam` para los modelos de Vertex AI o en `secret_manager` para otros proveedores, si usan Secret Manager para la autenticación. No necesitas establecer este valor si usas encabezados de autenticación.
`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 genera encabezados personalizados. En el caso de los modelos de Anthropic, la administración de extremos de 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 uses. Consulta Función de generación de encabezados.
`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');

Para obtener información sobre los valores que debes establecer para cada parámetro, consulta Crea un modelo.

Función `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 definiste.

Función `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 definiste.

`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 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.

Función `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 configuraste y que se usa posteriormente cuando se registra un extremo de modelo.
`PROJECT_ID`	El ID de tu proyecto de Google Cloud que contiene el secreto
`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.

Función `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');

Para obtener información sobre los valores que debes establecer para cada parámetro, consulta Cómo crear un secreto.

Función `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`	El ID secreto que estableciste y que se usó posteriormente cuando registraste 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.

Función `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`	Es el texto que se traducirá en una incorporación de vectores.

Por ejemplo, para ver las consultas de SQL que generan incorporaciones de texto, consulta Ejemplos de funciones de transformación para AlloDB Omni.

Función `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.

Por ejemplo, para ver consultas SQL que invoquen predicciones, consulta Ejemplos de AlloyDB Omni.

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 entradas y salidas 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": ["AlloyDB 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, podemos 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 del modelo 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": ["AlloyDB 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;
$$;

Función de generación de encabezados con clave de API

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

modelo de incorporación

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

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

Reemplaza 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 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.

Modelos compatibles

Puedes usar la administración de extremos de modelos para registrar cualquier incorporación de texto o extremo de modelo genérico. La administración de extremos de modelos también incluye modelos de Vertex AI registrados previamente y modelos con compatibilidad integrada. Para obtener más información sobre los diferentes tipos de modelos, consulta Tipo de modelo.

Modelos de Vertex AI registrados previamente

Tipo de modelo	ID de 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 del modelo calificado	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 del modelo calificado	Tipo de modelo
`text-embedding-ada-002`	`text-embedding`
`text-embedding-3-small`	`text-embedding`
`text-embedding-3-large`	`text-embedding`

Anthropic

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