Registrar y llamar a modelos de IA remotos en AlloyDB Omni

Selecciona una versión de la documentación:

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.

Habilitar la extensión

Debes añadir y habilitar la extensión google_ml_integration para poder empezar a usar las funciones asociadas. Para gestionar los endpoints de modelos, es necesario instalar la extensión google_ml_integration.

  1. Conéctate a tu base de datos con psql.

  2. Opcional: Si la extensión google_ml_integration ya está instalada, modifícala para actualizarla a la versión más reciente:

        ALTER EXTENSION google_ml_integration UPDATE;

  3. Añade la extensión google_ml_integration con psql:

      CREATE EXTENSION google_ml_integration;

  4. Opcional: Concede permiso a un usuario de PostgreSQL que no sea superadministrador para gestionar los metadatos del modelo:

      GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA google_ml TO NON_SUPER_USER;

    Sustituye NON_SUPER_USER por el nombre de usuario de PostgreSQL que no sea superusuario.

  5. Habilita la gestión de endpoints de modelos en tu base de datos:

      ALTER SYSTEM SET google_ml_integration.enable_model_support=on;
  SELECT pg_reload_conf();

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. Para obtener más información, consulta Configurar la instalación de AlloyDB Omni para consultar modelos basados en la nube.

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. Para obtener más información, consulta Crear un secreto y acceder a una versión de un secreto.

    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 AlloyDB 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. Para obtener más información, consulta Añadir una vinculación de política de Gestión de Identidades y Accesos.

Modelos de inserción de texto con asistencia integrada

En esta sección se muestra cómo registrar los endpoints de modelos para los que la gestión de endpoints de modelos ofrece asistencia integrada.

Modelos de inserciones de Vertex AI

La gestión de endpoints de modelos ofrece compatibilidad integrada con todas las versiones del modelo text-embedding-gecko de Vertex AI. Usa el nombre completo para definir la versión del modelo como textembedding-gecko@001 o textembedding-gecko@002.

Como el ID de endpoint de modelo textembedding-gecko y textembedding-gecko@001 está registrado previamente en la gestión de endpoints de modelo, puedes usarlos directamente como ID de modelo. En estos modelos, la extensión configura automáticamente las funciones de transformación predeterminadas.

Para registrar la versión del endpoint del modelo textembedding-gecko@002, sigue estos pasos:

En el caso de AlloyDB Omni, asegúrate de configurar AlloyDB Omni para consultar modelos de Vertex AI basados en la nube.

  1. Crea y habilita la extensión google_ml_integration.

  2. Conéctate a tu base de datos con psql.

  3. Crea y habilita la extensión google_ml_integration.

  4. Llama a la función de creación de modelos para añadir el endpoint del modelo textembedding-gecko@002:

    CALL
  google_ml.create_model(
    model_id => 'textembedding-gecko@002',
    model_provider => 'google',
    model_qualified_name => 'textembedding-gecko@002',
    model_type => 'text_embedding',
    model_auth_type => 'alloydb_service_agent_iam');

  The request URL that the function generates refers to the project associated with the AlloyDB Omni service account. If you want to refer to another project, then ensure that you specify the `model_request_url` explicitly.

Modelo de inserción de texto de Open AI

La gestión de endpoints de modelos proporciona compatibilidad integrada con el modelo text-embedding-ada-002 de OpenAI.La extensión google_ml_integration configura automáticamente las funciones de transformación predeterminadas e invoca llamadas al modelo remoto.

En el siguiente ejemplo se añade el endpoint del modelo text-embedding-ada-002 de OpenAI.

  1. Conéctate a tu base de datos con psql.
  2. Crea y habilita la extensión google_ml_integration.
  3. Añade la clave de API de OpenAI como secreto a Secret Manager para la autenticación.

  4. Llama al secreto almacenado 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');

    Haz los cambios siguientes:

    • SECRET_ID: el ID secreto que has definido y que se usa posteriormente al registrar un endpoint de modelo. Por ejemplo, key1.
    • SECRET_MANAGER_SECRET_ID: el ID de secreto definido en Secret Manager al crear el secreto.
    • PROJECT_ID: el ID de tu proyecto de Google Cloud .
    • VERSION_NUMBER: el número de versión del ID del secreto.

  5. Llama a la función de creación de modelos para registrar el endpoint del modelo text-embedding-ada-002:

      CALL
    google_ml.create_model(
      model_id => 'MODEL_ID',
      model_provider => 'open_ai',
      model_type => 'text_embedding',
      model_qualified_name => 'text-embedding-ada-002',
      model_auth_type => 'secret_manager',
      model_auth_id => 'SECRET_ID');

    Haz los cambios siguientes:

    • MODEL_ID: un ID único para el endpoint del modelo que definas. Este ID de modelo se utiliza como referencia para los metadatos que necesita el endpoint del modelo para generar inserciones o invocar predicciones.
    • SECRET_ID: el ID secreto que has usado anteriormente en el procedimiento de google_ml.create_sm_secret().

Para generar embeddings, consulta cómo generar embeddings para endpoints de modelos con compatibilidad integrada.

Otros modelos de inserciones de texto

En esta sección se muestra cómo registrar cualquier endpoint de modelo de inserción de texto alojado de forma personalizada o endpoints de modelo de inserción de texto proporcionados por proveedores de alojamiento de modelos. En función de los metadatos del punto final del modelo, es posible que tengas que añadir funciones de transformación, generar encabezados HTTP o definir puntos finales.

Modelo de inserción de texto alojado de forma personalizada

En esta sección se muestra cómo registrar un endpoint de modelo alojado de forma personalizada, así como crear funciones de transformación y, opcionalmente, encabezados HTTP personalizados. AlloyDB Omni admite todos los endpoints de modelos alojados de forma personalizada, independientemente de dónde estén alojados.

En el siguiente ejemplo se añade el endpoint del modelo personalizado custom-embedding-model alojado en Cymbal. Las funciones de transformación cymbal_text_input_transform y cymbal_text_output_transform se usan para transformar el formato de entrada y salida del modelo en el formato de entrada y salida de la función de predicción.

Para registrar endpoints de modelos de inserción de texto alojados de forma personalizada, sigue estos pasos:

  1. Conéctate a tu base de datos con psql.

  2. Crea y habilita la extensión google_ml_integration.

  3. Opcional: Añade la clave de API como secreto a Secret Manager para la autenticación.

  4. Llama al secreto almacenado 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');

    Haz los cambios siguientes:

    • SECRET_ID: el ID secreto que has definido y que se usa posteriormente al registrar un endpoint de modelo. Por ejemplo, key1.
    • SECRET_MANAGER_SECRET_ID: el ID de secreto definido en Secret Manager al crear el secreto.
    • PROJECT_ID: el ID de tu proyecto de Google Cloud .
    • VERSION_NUMBER: el número de versión del ID del secreto.

  5. Crea las funciones de transformación de entrada y salida basándote en la siguiente firma de la función de predicción de los endpoints del modelo de inserción de texto. Para obtener más información sobre cómo crear funciones de transformación, consulta el ejemplo de funciones de transformación.

    A continuación, se muestran funciones de transformación de ejemplo específicas del endpoint del modelo de inserciones de texto custom-embedding-model:

    -- Input Transform Function corresponding to the custom model endpoint
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;
$$;
-- Output Transform Function corresponding to the custom model endpoint
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;
$$;

  6. Llama a la función de creación de modelos para registrar el endpoint del modelo de inserción personalizado:

    CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_request_url => 'REQUEST_URL',
    model_provider => 'custom',
    model_type => 'text_embedding',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID',
    model_qualified_name => 'MODEL_QUALIFIED_NAME',
    model_in_transform_fn => 'cymbal_text_input_transform',
    model_out_transform_fn => 'cymbal_text_output_transform');

    Haz los cambios siguientes:

    • MODEL_ID: obligatorio. Un ID único para el endpoint del modelo que definas (por ejemplo, custom-embedding-model). Este ID de modelo se utiliza como referencia para los metadatos que necesita el endpoint del modelo para generar inserciones o invocar predicciones.
    • REQUEST_URL: obligatorio. El endpoint específico del modelo al añadir una inserción de texto personalizada y endpoints de modelos genéricos (por ejemplo, https://cymbal.com/models/text/embeddings/v1).
    • MODEL_QUALIFIED_NAME: es obligatorio si el endpoint de tu modelo usa un nombre cualificado. El nombre completo en caso de que el endpoint del modelo tenga varias versiones.
    • SECRET_ID: el ID secreto que has usado anteriormente en el procedimiento de google_ml.create_sm_secret().

Modelos Text Embedding 3 Small y Large de OpenAI

Puedes registrar los endpoints de los modelos text-embedding-3-small y text-embedding-3-large de OpenAI mediante la función de predicción de inserciones y las funciones de transformación específicas del endpoint del modelo. En el siguiente ejemplo se muestra cómo registrar el endpoint del modelo text-embedding-3-small de OpenAI.

Para registrar el endpoint del modelo de inserciones text-embedding-3-small, sigue estos pasos:

  1. Conéctate a tu base de datos con psql.
  2. Crea y habilita la extensión google_ml_integration.
  3. Añade la clave de API de OpenAI como secreto a Secret Manager para la autenticación. Si ya has creado un secreto para otro modelo de OpenAI, puedes reutilizarlo.

  4. Llama al secreto almacenado 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');

    Haz los cambios siguientes:

    • SECRET_ID: el ID secreto que has definido y que se usa posteriormente al registrar un endpoint de modelo.
    • SECRET_MANAGER_SECRET_ID: el ID de secreto definido en Secret Manager al crear el secreto.
    • PROJECT_ID: el ID de tu proyecto de Google Cloud .
    • VERSION_NUMBER: el número de versión del ID del secreto.

  5. Crea las funciones de transformación de entrada y salida basadas en la siguiente firma de la función de predicción de los modelos de inserción de texto. Para obtener más información sobre cómo crear funciones de transformación, consulta el ejemplo de funciones de transformación. Para obtener información sobre los formatos de entrada y salida que esperan los endpoints de los modelos de OpenAI, consulta Inserciones.

    A continuación, se muestran ejemplos de funciones de transformación para los endpoints de modelos de inserciones de texto de text-embedding-ada-002, text-embedding-3-small y text-embedding-3-largeOpenAI. 

    -- Input Transform Function corresponding to openai_text_embedding model endpoint family
CREATE OR REPLACE FUNCTION openai_text_input_transform(model_id VARCHAR(100), input_text TEXT)
RETURNS JSON
LANGUAGE plpgsql
AS $$
#variable_conflict use_variable
DECLARE
  transformed_input JSON;
  model_qualified_name TEXT;
BEGIN
  SELECT google_ml.model_qualified_name_of(model_id) INTO model_qualified_name;
  SELECT json_build_object('input', input_text, 'model', model_qualified_name)::JSON INTO transformed_input;
  RETURN transformed_input;
END;
$$;

-- Output Transform Function corresponding to openai_text_embedding model endpoint family
CREATE OR REPLACE FUNCTION openai_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->'data'->0->'embedding')) INTO transformed_output;
  RETURN transformed_output;
END;
$$;

  6. Llama a la función de creación de modelos para registrar el endpoint del modelo de inserciones text-embedding-3-small:

    CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'open_ai',
    model_type => 'text_embedding',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID',
    model_qualified_name => 'text-embedding-3-small',
    model_in_transform_fn => 'openai_text_input_transform',
    model_out_transform_fn => 'openai_text_output_transform');

    Haz los cambios siguientes:

    • MODEL_ID: un ID único para el endpoint del modelo que definas (por ejemplo, openai-te-3-small). Este ID de modelo se utiliza como referencia para los metadatos que necesita el endpoint del modelo para generar inserciones o invocar predicciones.
    • SECRET_ID: el ID secreto que has usado anteriormente en el procedimiento de google_ml.create_sm_secret().

Para obtener más información, consulta cómo generar una inserción para otros endpoints de modelos de inserción de texto.

Modelos genéricos

En esta sección se muestra cómo registrar cualquier endpoint de modelo genérico que esté disponible en un proveedor de modelos alojado, como Hugging Face, OpenAI, Vertex AI o cualquier otro proveedor. En esta sección se muestran ejemplos para registrar un endpoint de modelo genérico alojado en Hugging Face y un modelo genérico gemini-pro de Vertex AI Model Garden, que no tiene asistencia integrada.

Puedes registrar cualquier endpoint de modelo genérico siempre que la entrada y la salida estén en formato JSON. En función de los metadatos del punto de conexión del modelo, puede que tengas que generar encabezados HTTP o definir puntos de conexión.

Modelo genérico en Hugging Face

En el siguiente ejemplo se añade el endpoint del modelo de clasificación personalizado facebook/bart-large-mnli alojado en Hugging Face.

  1. Conéctate a tu base de datos con psql.
  2. Crea y habilita la extensión google_ml_integration.
  3. Añade el token de portador como secreto a Secret Manager para la autenticación.

  4. Llama al secreto almacenado en Secret Manager:

    CALL
  google_ml.create_sm_secret(
    secret_id => 'SECRET_ID',
    secret_path => 'projects/project-id/secrets/SECRE_MANAGER_SECRET_ID/versions/VERSION_NUMBER');

    Haz los cambios siguientes:

    • SECRET_ID: el ID secreto que has definido y que se usa posteriormente al registrar un endpoint de modelo.
    • SECRET_MANAGER_SECRET_ID: el ID de secreto definido en Secret Manager al crear el secreto.
    • PROJECT_ID: el ID de tu proyecto de Google Cloud .
    • VERSION_NUMBER: el número de versión del ID del secreto.

  5. Llama a la función de creación de modelos para registrar el endpoint del modelo facebook/bart-large-mnli:

    CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_provider => 'custom',
    model_request_url => 'REQUEST_URL',
    model_qualified_name => 'MODEL_QUALIFIED_NAME',
    model_auth_type => 'secret_manager',
    model_auth_id => 'SECRET_ID');

    Haz los cambios siguientes:

    • MODEL_ID: un ID único para el endpoint del modelo que definas (por ejemplo, custom-classification-model). Este ID de modelo se utiliza como referencia para los metadatos que necesita el endpoint del modelo para generar inserciones o invocar predicciones.
    • REQUEST_URL: el endpoint específico del modelo al añadir una inserción de texto personalizada y endpoints de modelos genéricos, como https://api-inference.huggingface.co/models/facebook/bart-large-mnli.
    • MODEL_QUALIFIED_NAME: nombre completo de la versión del endpoint del modelo (por ejemplo, facebook/bart-large-mnli).
    • SECRET_ID: el ID secreto que has usado anteriormente en el procedimiento de google_ml.create_sm_secret().

Modelo de Gemini

Asegúrate de configurar AlloyDB Omni para consultar modelos de Vertex AI basados en la nube.

En el siguiente ejemplo, se añade el endpoint del modelo gemini-1.0-pro de Vertex AI Model Garden.

  1. Conéctate a tu base de datos con psql.
  2. Crea y habilita la extensión google_ml_integration.

  3. Llama a la función de creación de modelos para registrar el modelo gemini-1.0-pro:

    CALL
  google_ml.create_model(
    model_id => 'MODEL_ID',
    model_request_url => 'https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-1.0-pro:streamGenerateContent',
    model_provider => 'google',
    model_auth_type => 'alloydb_service_agent_iam');

    Haz los cambios siguientes:

    • MODEL_ID: un ID único para el endpoint del modelo que definas (por ejemplo, gemini-1). Este ID de modelo se utiliza como referencia para los metadatos que necesita el endpoint del modelo para generar inserciones o invocar predicciones.
    • PROJECT_ID: el ID de tu proyecto de Google Cloud .

Para obtener más información, consulte cómo invocar predicciones para endpoints de modelos genéricos.

Siguientes pasos