Registra y llama a modelos de IA remotos en AlloyDB Omni

Para invocar predicciones o generar incorporaciones con un modelo, registra el extremo del modelo con la administración de extremos de modelos.

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

Antes de registrar un extremo de modelo con la administración de extremos de modelos, debes habilitar la extensión google_ml_integration y configurar la autenticación según el proveedor del modelo, si tu extremo de modelo requiere autenticación.

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

Habilita la extensión

Debes agregar y habilitar la extensión google_ml_integration para poder comenzar a usar las funciones asociadas. La administración de extremos de modelos requiere que se instale 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, cámbiala para actualizarla a la versión más reciente:

        ALTER EXTENSION google_ml_integration UPDATE;

  3. Agrega la extensión google_ml_integration con psql:

      CREATE EXTENSION google_ml_integration;

  4. Opcional: Otorga permiso a un usuario de PostgreSQL que no sea superusuario para administrar los metadatos del modelo:

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

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

  5. Habilita la administración de extremos de modelos en tu base de datos:

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

Configura la autenticación

En las siguientes secciones, se muestra cómo configurar la autenticación antes de agregar un extremo de modelo de Vertex AI o extremos de modelos de otros proveedores.

Configura la autenticación para Vertex AI

Para usar los extremos de modelos de Google Vertex AI, debes agregar permisos de Vertex AI a la cuenta de servicio que usaste cuando instalaste AlloyDB Omni. Para obtener más información, consulta Configura tu instalación de AlloyDB Omni para consultar modelos basados en la nube.

Configura 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 tus tokens de portador en Secret Manager. Este paso es opcional si el extremo de tu modelo no controla la autenticación a través de Secret Manager, por ejemplo, si el extremo de tu modelo usa encabezados HTTP para pasar información de autenticación o no usa la autenticación en absoluto.

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 portador, completa los siguientes pasos:

  1. Crea el Secret en Secret Manager. Para obtener más información, consulta Crea un secreto y accede a una versión de un secreto.

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

  2. Otorga 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"

    Reemplaza lo siguiente:

    • SECRET_ID: El ID del secreto en Secret Manager.

    • SERVICE_ACCOUNT_ID: El ID de la cuenta de servicio que creaste 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 puedes otorgar este rol a la cuenta de servicio a nivel del proyecto. Para obtener más información, consulta Cómo agregar una vinculación de políticas de Identity and Access Management.

Modelos de incorporación de texto con compatibilidad integrada

En esta sección, se muestra cómo registrar extremos de modelos para los que la administración de extremos de modelos proporciona compatibilidad integrada.

Modelos de incorporación de Vertex AI

La administración de extremos de modelos proporciona compatibilidad integrada con todas las versiones del modelo text-embedding-gecko de Vertex AI. Usa el nombre calificado para establecer la versión del modelo en textembedding-gecko@001 o textembedding-gecko@002.

Dado que el ID de extremo del modelo textembedding-gecko y textembedding-gecko@001 está registrado previamente con la administración de extremos de modelos, puedes usarlos directamente como el ID del modelo. Para estos modelos, la extensión configura automáticamente las funciones de transformación predeterminadas.

Para registrar la versión del extremo del modelo textembedding-gecko@002, completa los siguientes 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 agregar el extremo 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 incorporación de texto de Open AI

La administración de extremos 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 y, luego, invoca llamadas al modelo remoto.

En el siguiente ejemplo, se agrega el extremo 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. Agrega la clave de API de OpenAI como un 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');

    Reemplaza lo siguiente:

    • SECRET_ID: Es el ID secreto que estableces y que se usa posteriormente cuando registras un extremo de modelo, por ejemplo, key1.
    • SECRET_MANAGER_SECRET_ID: Es el ID de secreto establecido en Secret Manager cuando creaste el secreto.
    • PROJECT_ID: El ID de tu proyecto de Google Cloud .
    • VERSION_NUMBER: El número de versión del ID secreto.

  5. Llama a la función de creación de modelos para registrar el extremo 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');

    Reemplaza lo siguiente:

    • MODEL_ID: Un ID único para el extremo del modelo que definas. Se hace referencia a este ID de modelo para los metadatos que el extremo del modelo necesita para generar incorporaciones o invocar predicciones.
    • SECRET_ID: Es el ID secreto que usaste antes en el procedimiento google_ml.create_sm_secret().

Para generar incorporaciones, consulta cómo generar incorporaciones para extremos de modelos con compatibilidad integrada.

Otros modelos de incorporación de texto

En esta sección, se muestra cómo registrar cualquier extremo de modelo de incorporación de texto alojado de forma personalizada o los extremos de modelos de incorporación de texto que proporcionan los proveedores de alojamiento de modelos. Según los metadatos del extremo de tu modelo, es posible que necesites agregar funciones de transformación, generar encabezados HTTP o definir extremos.

Modelo de incorporación de texto alojado de forma personalizada

En esta sección, se muestra cómo registrar un extremo de modelo alojado de forma personalizada junto con la creación de funciones de transformación y, de forma opcional, encabezados HTTP personalizados. AlloyDB Omni admite todos los extremos de modelos alojados de forma personalizada, independientemente de dónde se alojen.

En el siguiente ejemplo, se agrega el extremo de modelo personalizado custom-embedding-model alojado por 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 al formato de entrada y salida de la función de predicción.

Para registrar extremos de modelos de incorporación de texto alojados de forma personalizada, completa los siguientes pasos:

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

  2. Crea y habilita la extensión google_ml_integration.

  3. Opcional: Agrega la clave de API como un 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');

    Reemplaza lo siguiente:

    • SECRET_ID: Es el ID secreto que estableces y que se usa posteriormente cuando registras un extremo de modelo, por ejemplo, key1.
    • SECRET_MANAGER_SECRET_ID: Es el ID de secreto establecido en Secret Manager cuando creaste el secreto.
    • PROJECT_ID: El ID de tu proyecto de Google Cloud .
    • VERSION_NUMBER: El número de versión del ID secreto.

  5. Crea las funciones de transformación de entrada y salida según la siguiente firma para la función de predicción de los extremos del modelo de incorporación de texto. Si deseas obtener más información para crear funciones de transformación, consulta el ejemplo de funciones de transformación.

    A continuación, se incluyen ejemplos de funciones de transformación específicas del extremo del modelo de incorporación 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 extremo del modelo de incorporació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');

    Reemplaza lo siguiente:

    • MODEL_ID: Obligatorio. Un ID único para el extremo del modelo que definas, por ejemplo, custom-embedding-model. Se hace referencia a este ID de modelo para los metadatos que el extremo del modelo necesita para generar incorporaciones o invocar predicciones.
    • REQUEST_URL: Obligatorio. El extremo específico del modelo cuando se agregan incorporaciones de texto personalizadas y extremos de modelos genéricos, por ejemplo, https://cymbal.com/models/text/embeddings/v1.
    • MODEL_QUALIFIED_NAME: Es obligatorio si el extremo de tu modelo usa un nombre calificado. Es el nombre completamente calificado en caso de que el extremo del modelo tenga varias versiones.
    • SECRET_ID: Es el ID secreto que usaste antes en el procedimiento google_ml.create_sm_secret().

3 modelos de incorporación de texto de OpenAI: pequeño, mediano y grande

Puedes registrar los extremos de los modelos text-embedding-3-small y text-embedding-3-large de OpenAI con la función de predicción de incorporación y las funciones de transformación específicas del extremo del modelo. En el siguiente ejemplo, se muestra cómo registrar el extremo del modelo text-embedding-3-small de OpenAI.

Para registrar el extremo del modelo de incorporación text-embedding-3-small, haz lo siguiente:

  1. Conéctate a tu base de datos con psql.
  2. Crea y habilita la extensión google_ml_integration.
  3. Agrega la clave de API de OpenAI como un secreto a Secret Manager para la autenticación. Si ya creaste un secreto para cualquier otro modelo de OpenAI, puedes reutilizar el mismo secreto.

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

    Reemplaza lo siguiente:

    • SECRET_ID: Es el ID secreto que configuraste y que se usa posteriormente cuando se registra un extremo de modelo.
    • SECRET_MANAGER_SECRET_ID: Es el ID de secreto establecido en Secret Manager cuando creaste el secreto.
    • PROJECT_ID: El ID de tu proyecto de Google Cloud .
    • VERSION_NUMBER: El número de versión del ID secreto.

  5. Crea las funciones de transformación de entrada y salida según la siguiente firma para la función de predicción de los modelos de incorporació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 extremos de los modelos de OpenAI, consulta Incorporaciones.

    Los siguientes son ejemplos de funciones de transformación para los extremos de los modelos de incorporación de texto de OpenAI text-embedding-ada-002, text-embedding-3-small y text-embedding-3-large. 

    -- 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 extremo del modelo de incorporación 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');

    Reemplaza lo siguiente:

    • MODEL_ID: Es un ID único para el extremo del modelo que definas, por ejemplo, openai-te-3-small. Se hace referencia a este ID de modelo para los metadatos que el extremo del modelo necesita para generar incorporaciones o invocar predicciones.
    • SECRET_ID: Es el ID secreto que usaste antes en el procedimiento google_ml.create_sm_secret().

Para obtener más información, consulta cómo generar incorporaciones para otros extremos de modelos de incorporación de texto.

Modelos genéricos

En esta sección, se muestra cómo registrar cualquier extremo 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 extremo de modelo genérico alojado en Hugging Face y un modelo gemini-pro genérico de Vertex AI Model Garden, que no tiene compatibilidad integrada.

Puedes registrar cualquier extremo de modelo genérico, siempre que la entrada y la salida estén en formato JSON. Según los metadatos del extremo de tu modelo, es posible que debas generar encabezados HTTP o definir extremos.

Modelo genérico en Hugging Face

En el siguiente ejemplo, se agrega el extremo 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. Agrega el token portador como un 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');

    Reemplaza lo siguiente:

    • SECRET_ID: Es el ID secreto que configuraste y que se usa posteriormente cuando se registra un extremo de modelo.
    • SECRET_MANAGER_SECRET_ID: Es el ID de secreto establecido en Secret Manager cuando creaste el secreto.
    • PROJECT_ID: El ID de tu proyecto de Google Cloud .
    • VERSION_NUMBER: El número de versión del ID secreto.

  5. Llama a la función de creación de modelos para registrar el extremo 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');

    Reemplaza lo siguiente:

    • MODEL_ID: Es un ID único para el extremo del modelo que definas, por ejemplo, custom-classification-model. Se hace referencia a este ID de modelo para los metadatos que el extremo del modelo necesita para generar incorporaciones o invocar predicciones.
    • REQUEST_URL: Es el extremo específico del modelo cuando se agregan incorporaciones de texto personalizadas y extremos de modelos genéricos, por ejemplo, https://api-inference.huggingface.co/models/facebook/bart-large-mnli.
    • MODEL_QUALIFIED_NAME: Es el nombre completamente calificado de la versión del extremo del modelo, por ejemplo, facebook/bart-large-mnli.
    • SECRET_ID: Es el ID secreto que usaste antes en el procedimiento 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 agrega el extremo del modelo gemini-1.0-pro desde 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');

    Reemplaza lo siguiente:

    • MODEL_ID: Es un ID único para el extremo del modelo que definas, por ejemplo, gemini-1. Se hace referencia a este ID de modelo para los metadatos que el extremo del modelo necesita para generar incorporaciones o invocar predicciones.
    • PROJECT_ID: El ID de tu proyecto de Google Cloud .

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

¿Qué sigue?