Registrar e chamar modelos de IA remotos no AlloyDB Omni

Para invocar previsões ou gerar embeddings usando um modelo, registre o endpoint do modelo com o gerenciamento de endpoint do modelo.

Para mais informações sobre a função google_ml.create_model(), consulte a referência de gerenciamento de endpoints de modelos.

Antes de registrar um endpoint de modelo com o gerenciamento de endpoints de modelo, ative a extensão google_ml_integration e configure a autenticação com base no provedor de modelo, se o endpoint de modelo exigir autenticação.

Acesse o banco de dados com o nome de usuário padrão postgres.

Ativar a extensão

É necessário adicionar e ativar a extensão google_ml_integration antes de começar a usar as funções associadas. O gerenciamento de endpoints do modelo exige que a extensão google_ml_integration esteja instalada.

  1. Conecte-se ao banco de dados usando psql.

  2. Opcional: se a extensão google_ml_integration já estiver instalada, atualize-a para a versão mais recente:

        ALTER EXTENSION google_ml_integration UPDATE;

  3. Adicione a extensão google_ml_integration usando o psql:

      CREATE EXTENSION google_ml_integration;

  4. Opcional: conceda permissão a um usuário não super do PostgreSQL para gerenciar metadados do modelo:

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

    Substitua NON_SUPER_USER pelo nome de usuário do PostgreSQL que não é super.

  5. Ative o gerenciamento de endpoint de modelo no seu banco de dados:

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

Configurar a autenticação

As seções a seguir mostram como configurar a autenticação antes de adicionar um endpoint de modelo da Vertex AI ou endpoints de modelo de outros provedores.

Configurar a autenticação para a Vertex AI

Para usar os endpoints de modelo da Vertex AI do Google, adicione as permissões da Vertex AI à conta de serviço usada durante a instalação do AlloyDB Omni. Para mais informações, consulte Configurar a instalação do AlloyDB Omni para consultar modelos baseados na nuvem.

Configurar a autenticação para outros provedores de modelo

Para todos os modelos, exceto os da Vertex AI, é possível armazenar chaves de API ou tokens de portador no Secret Manager. Esta etapa é opcional se o endpoint do modelo não processar a autenticação pelo Secret Manager. Por exemplo, se o endpoint do modelo usar cabeçalhos HTTP para transmitir informações de autenticação ou não usar autenticação.

Esta seção explica como configurar a autenticação se você estiver usando o Secret Manager.

Para criar e usar uma chave de API ou um token de portador, siga estas etapas:

  1. Crie o secret no Secret Manager. Para mais informações, consulte Criar e acessar uma versão do secret.

    O nome e o caminho do secret são usados na função SQL google_ml.create_sm_secret().

  2. Conceda permissões ao cluster do AlloyDB para acessar o secret.

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

    Substitua:

    • SECRET_ID: o ID do secret no Secret Manager.

    • SERVICE_ACCOUNT_ID: o ID da conta de serviço que você criou na etapa anterior. Confira se é a mesma conta usada durante a instalação do AlloyDB Omni. Isso inclui o sufixo PROJECT_ID.iam.gserviceaccount.com completo. Por exemplo: my-service@my-project.iam.gserviceaccount.com

      Também é possível conceder esse papel à conta de serviço no nível do projeto. Para mais informações, consulte Adicionar vinculação de políticas do Identity and Access Management acesso.

Modelos de embedding de texto com suporte integrado

Esta seção mostra como registrar endpoints de modelo que o gerenciamento de endpoint de modelo oferece suporte integrado.

Modelos de embedding da Vertex AI

O gerenciamento de endpoint do modelo oferece suporte integrado a todas as versões do modelo text-embedding-gecko da Vertex AI. Use o nome qualificado para definir a versão do modelo como textembedding-gecko@001 ou textembedding-gecko@002.

Como o ID de endpoint do modelo textembedding-gecko e textembedding-gecko@001 está pré-registrado com o gerenciamento de endpoint do modelo, é possível usá-los diretamente como o ID do modelo. Para esses modelos, a extensão configura automaticamente as funções de transformação padrão.

Para registrar a versão do endpoint do modelo textembedding-gecko@002, siga estas etapas:

No caso do AlloyDB Omni, configure o AlloyDB Omni para consultar modelos da Vertex AI baseados na nuvem.

  1. Crie e ative a extensão google_ml_integration.

  2. Conecte-se ao seu banco de dados usando psql.

  3. Crie e ative a extensão google_ml_integration.

  4. Chame a função de criação de modelo para adicionar o endpoint do 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 embedding de texto da Open AI

O gerenciamento de endpoint do modelo oferece suporte integrado ao modelo text-embedding-ada-002 da OpenAI.A extensão google_ml_integration configura automaticamente funções de transformação padrão e invoca chamadas para o modelo remoto.

O exemplo a seguir adiciona o endpoint do modelo text-embedding-ada-002 da OpenAI.

  1. Conecte-se ao banco de dados usando psql.
  2. Crie e ative a extensão google_ml_integration.
  3. Adicione a chave da API OpenAI como um secret ao Secret Manager para autenticação.

  4. Chame o secret armazenado no 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');

    Substitua:

    • SECRET_ID: o ID do secret que você definiu e que é usado ao registrar um endpoint de modelo, por exemplo, key1.
    • SECRET_MANAGER_SECRET_ID: o ID do secret definido no Secret Manager quando você criou o secret.
    • PROJECT_ID: o ID do projeto Google Cloud .
    • VERSION_NUMBER: o número da versão do ID do segredo.

  5. Chame a função de criação de modelo para registrar o endpoint do 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');

    Substitua:

    • MODEL_ID: um ID exclusivo para o endpoint do modelo que você define. Esse ID de modelo é referenciado para metadados que o endpoint do modelo precisa para gerar embeddings ou invocar previsões.
    • SECRET_ID: o ID secreto usado anteriormente no procedimento google_ml.create_sm_secret().

Para gerar embeddings, consulte como gerar embedding para endpoints de modelos com suporte integrado.

Outros modelos de embedding de texto

Esta seção mostra como registrar qualquer endpoint de modelo de embedding de texto hospedado ou endpoints de modelo de embedding de texto fornecidos por provedores de hospedagem de modelos. Com base nos metadados do endpoint do modelo, talvez seja necessário adicionar funções de transformação, gerar cabeçalhos HTTP ou definir endpoints.

Modelo de embedding de texto hospedado de forma personalizada

Esta seção mostra como registrar um endpoint de modelo hospedado de forma personalizada e criar funções de transformação e, opcionalmente, cabeçalhos HTTP personalizados. O AlloyDB Omni oferece suporte a todos os endpoints de modelo hospedados de forma personalizada, independentemente de onde eles são hospedados.

O exemplo a seguir adiciona o endpoint de modelo personalizado custom-embedding-model hospedado pelo Cymbal. As funções de transformação cymbal_text_input_transform e cymbal_text_output_transform são usadas para transformar o formato de entrada e saída do modelo no formato de entrada e saída da função de previsão.

Para registrar endpoints de modelos de incorporação de texto hospedados de forma personalizada, siga estas etapas:

  1. Conecte-se ao banco de dados usando psql.

  2. Crie e ative a extensão google_ml_integration.

  3. Opcional: adicione a chave de API como um secret ao Secret Manager para autenticação.

  4. Chame o secret armazenado no 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');

    Substitua:

    • SECRET_ID: o ID do secret que você definiu e que é usado ao registrar um endpoint de modelo, por exemplo, key1.
    • SECRET_MANAGER_SECRET_ID: o ID do secret definido no Secret Manager quando você criou o secret.
    • PROJECT_ID: o ID do projeto Google Cloud .
    • VERSION_NUMBER: o número da versão do ID do segredo.

  5. Crie as funções de transformação de entrada e saída com base na seguinte assinatura para a função de previsão dos endpoints do modelo de embedding de texto. Para mais informações sobre como criar funções de transformação, consulte Exemplo de funções de transformação.

    Confira a seguir exemplos de funções de transformação específicas para o endpoint do modelo de embedding 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. Chame a função de criação de modelo para registrar o endpoint do modelo de embedding 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');

    Substitua:

    • MODEL_ID: obrigatório. Um ID exclusivo para o endpoint do modelo que você define, por exemplo, custom-embedding-model. Esse ID de modelo é referenciado para metadados que o endpoint do modelo precisa para gerar embeddings ou invocar previsões.
    • REQUEST_URL: obrigatório. O endpoint específico do modelo ao adicionar embedding de texto personalizado e endpoints de modelo genéricos, por exemplo, https://cymbal.com/models/text/embeddings/v1.
    • MODEL_QUALIFIED_NAME: obrigatório se o endpoint do modelo usar um nome qualificado. O nome totalmente qualificado caso o endpoint do modelo tenha várias versões.
    • SECRET_ID: o ID secreto usado anteriormente no procedimento google_ml.create_sm_secret().

Modelos pequenos e grandes de OpenAI Text Embedding 3

É possível registrar os endpoints de modelo text-embedding-3-small e text-embedding-3-large da OpenAI usando a função de previsão de embedding e as funções de transformação específicas do endpoint do modelo. O exemplo a seguir mostra como registrar o endpoint do modelo text-embedding-3-small da OpenAI.

Para registrar o endpoint de incorporação do modelo text-embedding-3-small, faça o seguinte:

  1. Conecte-se ao banco de dados usando psql.
  2. Crie e ative a extensão google_ml_integration.
  3. Adicione a chave da API OpenAI como um secret ao Secret Manager para autenticação. Se você já tiver criado um secret para qualquer outro modelo do OpenAI, poderá reutilizar o mesmo secret.

  4. Chame o secret armazenado no 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');

    Substitua:

    • SECRET_ID: o ID secreto que você define e é usado ao registrar um endpoint de modelo.
    • SECRET_MANAGER_SECRET_ID: o ID do secret definido no Secret Manager quando você criou o secret.
    • PROJECT_ID: o ID do projeto Google Cloud .
    • VERSION_NUMBER: o número da versão do ID do segredo.

  5. Crie as funções de transformação de entrada e saída com base na assinatura a seguir para a função de previsão de modelos de embedding de texto. Para mais informações sobre como criar funções de transformação, consulte Exemplo de funções de transformação. Para saber mais sobre os formatos de entrada e saída que os endpoints de modelos da OpenAI esperam, consulte Embeddings.

    Confira abaixo exemplos de funções de transformação para os endpoints do modelo de embedding de texto text-embedding-ada-002, text-embedding-3-small e text-embedding-3-large da OpenAI. 

    -- 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. Chame a função de criação de modelo para registrar o endpoint do modelo de embedding 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');

    Substitua:

    • MODEL_ID: um ID exclusivo para o endpoint do modelo que você define, por exemplo, openai-te-3-small. Esse ID de modelo é referenciado para metadados que o endpoint do modelo precisa para gerar embeddings ou invocar previsões.
    • SECRET_ID: o ID secreto usado anteriormente no procedimento google_ml.create_sm_secret().

Para mais informações, consulte como gerar embeddings para outros endpoints de modelos de embedding de texto.

Modelos genéricos

Esta seção mostra como registrar qualquer endpoint de modelo genérico disponível em um provedor de modelo hospedado, como Hugging Face, OpenAI, Vertex AI ou qualquer outro provedor. Esta seção mostra exemplos para registrar um endpoint de modelo genérico hospedado no Hugging Face e um modelo gemini-pro genérico do Model Garden da Vertex AI, que não tem suporte integrado.

É possível registrar qualquer endpoint de modelo genérico, desde que a entrada e a saída estejam no formato JSON. Com base nos metadados do endpoint do modelo, talvez seja necessário gerar cabeçalhos HTTP ou definir endpoints.

Modelo genérico no Hugging Face

O exemplo a seguir adiciona o endpoint do modelo de classificação personalizada facebook/bart-large-mnli hospedado no Hugging Face.

  1. Conecte-se ao banco de dados usando psql.
  2. Crie e ative a extensão google_ml_integration.
  3. Adicione o token do portador como um secret ao Secret Manager para autenticação.

  4. Chame o secret armazenado no 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');

    Substitua:

    • SECRET_ID: o ID secreto que você define e é usado ao registrar um endpoint de modelo.
    • SECRET_MANAGER_SECRET_ID: o ID do secret definido no Secret Manager quando você criou o secret.
    • PROJECT_ID: o ID do projeto Google Cloud .
    • VERSION_NUMBER: o número da versão do ID do segredo.

  5. Chame a função de criação de modelo para registrar o endpoint do 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');

    Substitua:

    • MODEL_ID: um ID exclusivo para o endpoint do modelo que você define, por exemplo, custom-classification-model. Esse ID de modelo é referenciado para metadados que o endpoint do modelo precisa para gerar embeddings ou invocar previsões.
    • REQUEST_URL: o endpoint específico do modelo ao adicionar a incorporação de texto personalizada e os endpoints de modelo genéricos, por exemplo, https://api-inference.huggingface.co/models/facebook/bart-large-mnli.
    • MODEL_QUALIFIED_NAME: o nome totalmente qualificado da versão do endpoint do modelo, por exemplo, facebook/bart-large-mnli.
    • SECRET_ID: o ID secreto usado anteriormente no procedimento google_ml.create_sm_secret().

Modelo do Gemini

Configure o AlloyDB Omni para consultar modelos da Vertex AI baseados na nuvem.

O exemplo a seguir adiciona o endpoint do modelo gemini-1.0-pro do Model Garden da Vertex AI.

  1. Conecte-se ao banco de dados usando psql.
  2. Crie e ative a extensão google_ml_integration.

  3. Chame a função de criação de modelo para registrar o 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');

    Substitua:

    • MODEL_ID: um ID exclusivo para o endpoint do modelo que você define, por exemplo, gemini-1. Esse ID de modelo é referenciado para metadados que o endpoint do modelo precisa para gerar embeddings ou invocar previsões.
    • PROJECT_ID: o ID do projeto Google Cloud .

Para mais informações, consulte como invocar previsões para endpoints de modelos genéricos.

A seguir