Llamar a modelos mediante endpoints de modelos en AlloyDB

La vista previa de la gestión de endpoints de modelos te permite registrar un endpoint de modelo, gestionar los metadatos de los endpoints de modelos en tu clúster de base de datos y, a continuación, interactuar con los modelos mediante consultas SQL. Proporciona la extensión google_ml_integration, que incluye funciones para añadir y registrar los metadatos del endpoint del modelo relacionados con los modelos, y luego usar los modelos para generar incrustaciones de vectores o invocar predicciones.

Estos son algunos de los tipos de modelos de ejemplo que puedes registrar mediante la gestión de endpoints de modelos:

  • Modelos de inserciones de texto de Vertex AI
  • Modelos de inserción proporcionados por terceros.
  • Modelos de inserción de texto alojados de forma personalizada
  • Modelos genéricos con una API basada en JSON, como el modelo gemini-pro de Vertex AI Model Garden

Cómo funciona

Puedes usar la gestión de endpoints de modelos para registrar un endpoint de modelo que cumpla los siguientes requisitos:

  • La entrada y la salida del modelo admiten el formato JSON.
  • Se puede llamar al modelo mediante el protocolo REST.

Cuando registras un endpoint de modelo en la gestión de endpoints de modelos, se registra cada endpoint con un ID de modelo único que has proporcionado como referencia al modelo. Puedes usar este ID de modelo para consultar modelos:

  • Genera incrustaciones para traducir las peticiones de texto a vectores numéricos. Puede almacenar las inserciones generadas como datos vectoriales cuando la extensión pgvector esté habilitada en la base de datos.

  • Invoca predicciones para llamar a un modelo mediante SQL en una transacción.

Tus aplicaciones pueden acceder a la gestión de endpoints de modelos mediante la extensión google_ml_integration. Esta extensión ofrece las siguientes funciones:

  • La función SQL google_ml.create_model(), que se usa para registrar el endpoint del modelo que se utiliza en la función de predicción o de inserción.
  • La función de SQL google_ml.create_sm_secret(), que usa secretos en Google Cloud Secret Manager, donde se almacenan las claves de API.
  • La función SQL google_ml.embedding(), que es una función de predicción que genera inserciones de texto.
  • La función SQL google_ml.predict_row() que genera predicciones cuando llamas a modelos genéricos que admiten el formato de entrada y salida JSON.
  • Otras funciones auxiliares que gestionan la generación de URLs personalizadas, la generación de encabezados HTTP o la transferencia de funciones de transformación para tus modelos genéricos.
  • Funciones para gestionar los endpoints y los secretos del modelo registrado.

Conceptos clave

Antes de empezar a usar la gestión de endpoints de modelos, debes conocer los conceptos necesarios para conectarte a los modelos y usarlos.

Proveedor del modelo

Proveedor del modelo indica los proveedores de alojamiento de modelos admitidos. En la siguiente tabla se muestra el valor del proveedor del modelo que debe definir en función del proveedor del modelo que utilice:

Proveedor del modelo Definir en la función como…
Vertex AI google
Otros modelos custom

El proveedor de modelos predeterminado es custom.

El método de autenticación admitido varía en función del tipo de proveedor. Los modelos de Vertex AI usan la cuenta de servicio de Distributed Cloud para autenticarse, mientras que otros proveedores pueden usar Secret Manager para autenticarse.

Tipo de modelo

Tipo de modelo indica el tipo de modelo de IA. La extensión admite la inserción de texto, así como cualquier tipo de modelo genérico. Los tipos de modelo admitidos que puedes definir al registrar un endpoint de modelo son text-embedding y generic. Definir el tipo de modelo es opcional al registrar endpoints de modelos genéricos, ya que generic es el tipo de modelo predeterminado.

Modelos de inserción de texto con asistencia integrada
La gestión de endpoints de modelos ofrece compatibilidad integrada con todas las versiones del modelo textembedding-gecko de Vertex AI. Para registrar estos endpoints de modelo, usa la función google_ml.create_model(). Distributed Cloud configura automáticamente funciones de transformación predeterminadas para estos modelos.
El tipo de modelo de estos modelos es text-embedding.
Otros modelos de inserciones de texto
En el caso de otros modelos de inserción de texto, debes crear funciones de transformación para gestionar los formatos de entrada y salida que admite el modelo. También puedes usar la función de generación de encabezados HTTP, que genera los encabezados personalizados que necesita tu modelo.
El tipo de modelo de estos modelos es text-embedding.
Modelos genéricos
La gestión de endpoints de modelos también admite el registro de todos los demás tipos de modelos, excepto los modelos de inserción de texto. Para invocar predicciones de modelos genéricos, usa la función google_ml.predict_row(). Puedes definir metadatos de puntos de conexión de modelos, como un punto de conexión de solicitud y encabezados HTTP específicos de tu modelo.
No puedes transferir funciones de transformación al registrar un endpoint de modelo genérico. Asegúrate de que, cuando invoques las predicciones, la entrada de la función esté en formato JSON y de que analices la salida JSON para obtener la salida final.
El tipo de modelo de estos modelos es generic.

Autenticación

Los tipos de autenticación indican el tipo de autenticación que puedes usar para conectarte a la gestión de endpoints de modelos mediante la extensión google_ml_integration. Configurar la autenticación es opcional y solo es necesario si necesitas autenticarte para acceder a tu modelo.

En el caso de los modelos de Vertex AI, la cuenta de servicio de Distributed Cloud se usa para la autenticación. En otros modelos, se puede usar una clave de API o un token de portador almacenado como secreto en Secret Manager con la función google_ml.create_sm_secret() SQL.

En la siguiente tabla se muestran los tipos de autenticación que puedes definir:

Método de autenticación Definir en la función como… Proveedor del modelo
Agente de servicio de Distributed Cloud alloydb_service_agent_iam Proveedor de Vertex AI
Secret Manager secret_manager proveedores externos

Funciones de predicción

La extensión google_ml_integration incluye las siguientes funciones de predicción:

google_ml.embedding()
Se usa para llamar a un endpoint de modelo de incrustación de texto registrado para generar incrustaciones. Incluye compatibilidad integrada con el modelo textembedding-gecko de Vertex AI.
En el caso de los modelos de inserción de texto que no tienen asistencia integrada, los parámetros de entrada y salida son únicos para cada modelo y deben transformarse para que la función pueda llamar al modelo. Crea una función de entrada de transformación para transformar la entrada de la función de predicción en la entrada específica del modelo y una función de salida de transformación para transformar la salida específica del modelo en la salida de la función de predicción.
google_ml.predict_row()
Se usa para llamar a un endpoint de modelo genérico registrado, siempre que admita APIs basadas en JSON, para invocar predicciones.

Transformar funciones

Las funciones de transformación modifican la entrada a un formato que el modelo entiende y convierten la respuesta del modelo al formato que espera la función de predicción. Las funciones de transformación se usan al registrar el endpoint del modelo text-embedding sin compatibilidad integrada. La firma de las funciones de transformación depende de la función de predicción del tipo de modelo.

No puedes usar funciones de transformación al registrar un endpoint de modelo generic.

A continuación, se muestran las firmas de la función de predicción de los modelos de inserción de texto:

// define custom model specific input/output transform functions.
CREATE OR REPLACE FUNCTION input_transform_function(model_id VARCHAR(100), input_text TEXT) RETURNS JSON;

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

Función de generación de encabezados HTTP

La función de generación de encabezados HTTP genera la salida en pares clave-valor JSON que se utilizan como encabezados HTTP. La firma de la función de predicción define las firmas de la función de generación de encabezados.

En el siguiente ejemplo se muestra la firma de la función de predicción google_ml.embedding().

CREATE OR REPLACE FUNCTION generate_headers(model_id VARCHAR(100), input 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 VARCHAR(100), input JSON) RETURNS JSON;

Registrar un modelo

Para invocar predicciones o generar inserciones mediante un modelo, registra el endpoint del modelo con la gestión de endpoints de modelos.

Para obtener más información sobre la función google_ml.create_model(), consulta la referencia de gestión de endpoints de modelos.

Antes de registrar un endpoint de modelo con la gestión de endpoints de modelos, debes habilitar la extensión google_ml_integration y configurar la autenticación en función del proveedor del modelo, si tu endpoint de modelo requiere autenticación.

Asegúrate de acceder a tu base de datos con el nombre de usuario predeterminado postgres.

Configurar la autenticación

En las siguientes secciones se muestra cómo configurar la autenticación antes de añadir un endpoint de modelo de Vertex AI o endpoints de modelos de otros proveedores.

Configurar la autenticación de Vertex AI

Para usar los endpoints de modelos de Google Vertex AI, debes añadir permisos de Vertex AI a la cuenta de servicio que usaste al instalar AlloyDB Omni.

Configurar la autenticación para otros proveedores de modelos

En el caso de todos los modelos, excepto los de Vertex AI, puedes almacenar tus claves de API o tokens de portador en Secret Manager. Este paso es opcional si tu endpoint de modelo no gestiona la autenticación a través de Secret Manager. Por ejemplo, si tu endpoint de modelo usa encabezados HTTP para transferir información de autenticación o no usa la autenticación.

En esta sección se explica cómo configurar la autenticación si usas Secret Manager.

Para crear y usar una clave de API o un token de portador, sigue estos pasos:

  1. Crea el secreto en Secret Manager.

    El nombre y la ruta del secreto se usan en la función SQL google_ml.create_sm_secret().

  2. Concede permisos al clúster de Distributed Cloud para acceder al secreto.

      gcloud secrets add-iam-policy-binding 'SECRET_ID' \
      --member="serviceAccount:SERVICE_ACCOUNT_ID" \
      --role="roles/secretmanager.secretAccessor"

    Haz los cambios siguientes:

    • SECRET_ID: el ID del secreto en Secret Manager.

    • SERVICE_ACCOUNT_ID: el ID de la cuenta de servicio que has creado en el paso anterior. Asegúrate de que sea la misma cuenta que usaste durante la instalación de AlloyDB Omni. Esto incluye el sufijo PROJECT_ID.iam.gserviceaccount.com completo. Por ejemplo: my-service@my-project.iam.gserviceaccount.com

      También puede asignar este rol a la cuenta de servicio a nivel de proyecto.

Generar inserciones

En esta sección se describe una vista previa que te permite experimentar con el registro de un endpoint de modelo de IA y con la invocación de predicciones mediante la gestión de endpoints de modelos.

Una vez que se hayan añadido y registrado los endpoints del modelo en la gestión de endpoints de modelos, podrás hacer referencia a ellos mediante el ID del modelo para generar inserciones.

Antes de empezar

Asegúrate de haber registrado tu endpoint de modelo con la gestión de endpoints de modelos.

Generar inserciones

Usa la función SQL google_ml.embedding() para llamar al endpoint del modelo registrado con el tipo de modelo de inserción de texto para generar inserciones.

Para llamar al modelo y generar las inserciones, usa la siguiente consulta de SQL:

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

Haz los cambios siguientes:

  • MODEL_ID: el ID del modelo que definiste al registrar el endpoint del modelo.
  • CONTENT: el texto que se va a traducir a una incrustación de vector.

Ejemplos

En esta sección se incluyen algunos ejemplos de cómo generar inserciones mediante un endpoint de modelo registrado.

Modelos de inserción de texto con asistencia integrada

Para generar embeddings de un endpoint de modelo textembedding-gecko@002 registrado, ejecuta la siguiente instrucción:

    SELECT
      google_ml.embedding(
        model_id => 'textembedding-gecko@002',
        content => 'AlloyDB is a managed, cloud-hosted SQL database service');

Invocar predicciones

En esta sección se describe una vista previa que te permite experimentar con el registro de un endpoint de modelo de IA y con la invocación de predicciones mediante la gestión de endpoints de modelos.

Una vez que se hayan añadido y registrado los endpoints del modelo en la gestión de endpoints de modelos, podrá hacer referencia a ellos mediante el ID del modelo para invocar predicciones.

Antes de empezar

Asegúrate de haber registrado tu endpoint de modelo con la gestión de endpoints de modelos.

Invocar predicciones de modelos genéricos

Usa la función SQL google_ml.predict_row() para llamar a un endpoint de modelo genérico registrado e invocar predicciones. Puedes usar la función google_ml.predict_row() con cualquier tipo de modelo.

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

Haz los cambios siguientes:

  • MODEL_ID: el ID del modelo que definiste al registrar el endpoint del modelo.
  • REQUEST_BODY: los parámetros de la función de predicción en formato JSON.

Ejemplos

En esta sección se incluyen algunos ejemplos de cómo invocar predicciones mediante endpoints de modelos registrados.

Para generar predicciones de un endpoint de modelo gemini-pro registrado, ejecuta la siguiente instrucción:

    SELECT
        json_array_elements(
        google_ml.predict_row(
            model_id => 'gemini-pro',
            request_body => '{
        "contents": [
            {
                "role": "user",
                "parts": [
                    {
                        "text": "For TPCH database schema as mentioned here https://www.tpc.org/TPC_Documents_Current_Versions/pdf/TPC-H_v3.0.1.pdf , generate a SQL query to find all supplier names which are located in the India nation."
                    }
                ]
            }
        ]
        }'))-> 'candidates' -> 0 -> 'content' -> 'parts' -> 0 -> 'text';

Referencia de la API de gestión de endpoints de modelos

En esta sección 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.

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

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 al endpoint del modelo desde la red en la que se encuentra Distributed Cloud.
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
  • 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.
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.

La firma de esta función depende de la función de predicción que utilices.
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.
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.

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. Este proyecto puede ser diferente del que contiene tu clúster de AlloyDB para PostgreSQL.

En AlloyDB Omni, el ID del Google Cloud proyecto 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.

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.

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', 'model-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.

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-preview-0815 text-embedding
text-multilingual-embedding-002 text-embedding