Esta página foi traduzida pela API Cloud Translation.

Registrar e chamar modelos de IA remotos usando o gerenciamento de endpoints de modelo

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

Antes de começar

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.

Verifique se a flag do banco de dados google_ml_integration.enable_model_support está definida como on para uma instância. Para mais informações sobre como definir flags do banco de dados, consulte Configurar flags do banco de dados de uma instância.
Conecte-se ao seu banco de dados usando o psql ou o AlloyDB para PostgreSQL Studio.
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;
```

Adicione a extensão google_ml_integration usando o psql:

  CREATE EXTENSION IF NOT EXISTS google_ml_integration;

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.
Verifique se o IP de saída está ativado para acessar modelos hospedados fora da VPC, como modelos de terceiros. Para mais informações, consulte Adicionar conectividade de saída.

Configurar a autenticação

As seções a seguir mostram como configurar a autenticação antes de registrar um endpoint de modelo.

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 do AlloyDB baseada no IAM que você usa para se conectar ao banco de dados. Para mais informações sobre a integração com a Vertex AI, consulte Integrar com a Vertex AI.

Configurar a autenticação usando o Secret Manager

Esta seção explica como configurar a autenticação se você estiver usando o Secret Manager para armazenar detalhes de autenticação de provedores de terceiros.

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 a autenticação.

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

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

O caminho do segredo é usado na função SQL google_ml.create_sm_secret().
Conceda permissões ao cluster do AlloyDB para acessar o secret.
```
  gcloud secrets add-iam-policy-binding 'SECRET_NAME' \
      --member="serviceAccount:SERVICE_ACCOUNT_ID" \
      --role="roles/secretmanager.secretAccessor"
```
Substitua:
- SECRET_NAME: o nome do secret no Secret Manager.
- SERVICE_ACCOUNT_ID: o ID da conta de serviço baseada no IAM no formato serviceAccount:service-PROJECT_ID@gcp-sa-alloydb.iam.gserviceaccount.com, por exemplo, service-212340152456@gcp-sa-alloydb.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.

Configurar a autenticação usando cabeçalhos

O exemplo a seguir mostra como configurar a autenticação usando uma função. A função retorna um objeto JSON que contém os cabeçalhos necessários para fazer uma solicitação ao modelo de incorporação.

  CREATE OR REPLACE FUNCTION HEADER_GEN_FUNCTION(
    model_id VARCHAR(100),
    input_text TEXT
  )
  RETURNS JSON
  LANGUAGE plpgsql
  AS $$
  #variable_conflict use_variable
  DECLARE
    api_key VARCHAR(255) := 'API_KEY';
    header_json JSON;
  BEGIN
    header_json := json_build_object(
      'Content-Type', 'application/json',
      'Authorization', 'Bearer ' || api_key
    );
    RETURN header_json;
  END;
  $$;

Substitua:

HEADER_GEN_FUNCTION: o nome da função de geração de cabeçalho que pode ser usada ao registrar um modelo.
API_KEY: a chave de API do provedor de modelo.

Modelos de embeddings de texto

Esta seção mostra como registrar endpoints de modelos com o gerenciamento de endpoints de modelos.

O gerenciamento de endpoint do modelo oferece suporte a alguns modelos de embeddings de texto e modelos genéricos da Vertex AI como endpoints de modelo pré-registrados. É possível usar o ID do modelo diretamente para gerar embeddings ou invocar previsões com base no tipo de modelo. Para mais informações sobre os modelos pré-registrados compatíveis, consulte Modelos pré-registrados da Vertex AI.

Por exemplo, para chamar o modelo textembedding-gecko pré-registrado, chame-o diretamente usando a função de incorporação:

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

Da mesma forma, para chamar o modelo gemini-1.5-pro:generateContent pré-registrado, chame-o diretamente usando a função de previsão:

 SELECT
        json_array_elements(
        google_ml.predict_row(
            model_id => 'gemini-1.5-pro:generateContent',
            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';

Para gerar embeddings, consulte como gerar embeddings para endpoints de modelos pré-registrados. Para invocar previsões, consulte como invocar previsões para endpoints de modelos pré-registrados.

Modelos de embedding de texto com suporte integrado

O gerenciamento de endpoint de modelo oferece suporte integrado a alguns modelos da Vertex AI e da OpenAI. Para conferir a lista de modelos com suporte integrado, consulte Modelos com suporte integrado.

Para modelos com suporte integrado, é possível definir o nome qualificado como o nome qualificado do modelo e especificar o URL da solicitação. O gerenciamento de endpoint do modelo identifica automaticamente o modelo e configura funções de transformação padrão.

Modelos de embedding da Vertex AI

As etapas a seguir mostram como registrar modelos da Vertex AI com suporte integrado. O endpoint do modelo text-embedding-005 e text-multilingual-embedding-002 é usado como exemplo.

Verifique se o cluster do AlloyDB e o modelo da Vertex AI que você está consultando estão na mesma região.

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

Chame a função de criação de modelo para adicionar o endpoint do modelo:

text-embedding-005

  CALL
    google_ml.create_model(
      model_id => 'text-embedding-005',
      model_request_url => 'publishers/google/models/text-embedding-005',
      model_provider => 'google',
      model_qualified_name => 'text-embedding-005',
      model_type => 'text_embedding',
      model_auth_type => 'alloydb_service_agent_iam');

text-multilingual-embedding-002

  CALL
    google_ml.create_model(
      model_id => 'text-multilingual-embedding-002',
      model_request_url => 'publishers/google/models/text-multilingual-embedding-002',
      model_provider => 'google',
      model_qualified_name => 'text-multilingual-embedding-002',
      model_type => 'text_embedding',
      model_auth_type => 'alloydb_service_agent_iam'
      model_in_transform_fn => 'google_ml.vertexai_text_embedding_input_transform',
      model_out_transform_fn => 'google_ml.vertexai_text_embedding_output_transform');

Se o modelo estiver armazenado em outro projeto e região, e não no cluster do AlloyDB, defina o URL da solicitação como projects/PROJECT_ID/locations/REGION_ID/publishers/google/models/MODEL_ID, em que REGION_ID é a região em que o modelo está hospedado e MODEL_ID é o nome qualificado do modelo.

Além disso, conceda o papel de usuário da Vertex AI (roles/aiplatform.user) à conta de serviço do AlloyDB do projeto em que a instância do AlloyDB está localizada para que o AlloyDB possa acessar o modelo hospedado no outro projeto.

Modelo de embedding de texto da Open AI

A extensão google_ml_integration configura automaticamente as funções de transformação padrão e invoca chamadas para os modelos remotos da OpenAI. Para conferir a lista de modelos da OpenAI com suporte integrado, consulte Modelos com suporte integrado.

O exemplo a seguir adiciona o endpoint do modelo text-embedding-ada-002 da OpenAI. É possível registrar os endpoints do modelo text-embedding-3-small e text-embedding-3-large da OpenAI usando as mesmas etapas e definindo os nomes qualificados específicos dos modelos.

Conecte-se ao banco de dados usando psql.
Crie e ative a extensão google_ml_integration.
Adicione a chave da API OpenAI como um secret ao Secret Manager para autenticação.
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.
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.

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. Todos os endpoints de modelo hospedados de forma personalizada são compatíveis, independentemente de onde 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:

Conecte-se ao seu banco de dados usando psql.
Crie e ative a extensão google_ml_integration.
Opcional: adicione a chave de API como um secret ao Secret Manager para autenticação.
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.
Observação: o Secret Manager gera um cabeçalho Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER para autenticação por padrão. Se esse formato corresponder ao formato do token de portador de autorização do endpoint do modelo, não será necessário gerar cabeçalhos de autenticação usando a função de geração de cabeçalhos.

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

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. Verifique se o endpoint do modelo pode ser acessado por um endereço IP interno. O gerenciamento de endpoints de modelo não é compatível com endereços IP públicos.
- 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 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, Anthropic ou qualquer outro. Esta seção mostra exemplos para registrar um endpoint de modelo genérico hospedado no Hugging Face, um modelo gemini-pro genérico do Model Garden da Vertex AI e o endpoint do modelo claude-haiku.

É 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 URLs de solicitação.

Para mais informações sobre modelos genéricos pré-registrados e modelos com suporte integrado, consulte Modelos compatíveis.

Modelo do Gemini

Como alguns modelos gemini-pro são pré-registrados, é possível chamar diretamente o ID do modelo para invocar previsões.

O exemplo a seguir usa o endpoint de modelo gemini-1.5-pro:generateContent do Model Garden da Vertex AI.

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

Invocar previsões usando o ID do modelo pré-registrado:

SELECT
    json_array_elements(
    google_ml.predict_row(
        model_id => 'gemini-1.5-pro:generateContent',
        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';

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.

Conecte-se ao banco de dados usando psql.
Crie e ative a extensão google_ml_integration.
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.
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.
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 => 'hugging_face',
    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 genérico da Anthropic

O exemplo a seguir adiciona o endpoint do modelo claude-3-opus-20240229. O gerenciamento de endpoint do modelo fornece a função de cabeçalho necessária para registrar modelos antropizados.

Conecte-se ao banco de dados usando psql.
Crie e ative a extensão google_ml_integration.
Secret Manager
1. Adicione o token do portador como um secret ao Secret Manager para autenticação.
2. 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.
3. Chame a função de criação de modelo para registrar o endpoint do modelo claude-3-opus-20240229.
  CALL google_ml.create_model( model_id => 'MODEL_ID', model_provider => 'anthropic', model_request_url => 'REQUEST_URL', model_auth_type => 'secret_manager', model_auth_id => 'SECRET_ID', generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');
  Substitua:
  - MODEL_ID: um ID exclusivo para o endpoint do modelo que você define, por exemplo, anthropic-opus. 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.anthropic.com/v1/messages.
Cabeçalho do Auth
1. Use a função de geração de cabeçalho padrão google_ml.anthropic_claude_header_gen_fn ou crie uma função de geração de cabeçalho.
  CREATE OR REPLACE FUNCTION anthropic_sample_header_gen_fn(model_id VARCHAR(100), request_body JSON) RETURNS JSON LANGUAGE plpgsql AS $$ #variable_conflict use_variable BEGIN RETURN json_build_object('x-api-key', 'ANTHROPIC_API_KEY', 'anthropic-version', 'ANTHROPIC_VERSION')::JSON; END; $$;
  Substitua:
  - ANTHROPIC_API_KEY: a chave de API anthropic.
  - ANTHROPIC_VERSION (opcional): a versão específica do modelo que você quer usar, por exemplo, 2023-06-01.
2. Chame a função de criação de modelo para registrar o endpoint do modelo claude-3-opus-20240229.
  CALL google_ml.create_model( model_id => 'MODEL_ID', model_provider => 'anthropic', model_request_url => 'REQUEST_URL', generate_headers_fn => 'google_ml.anthropic_claude_header_gen_fn');
  Substitua:
  - MODEL_ID: um ID exclusivo para o endpoint do modelo que você define, por exemplo, anthropic-opus. 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.anthropic.com/v1/messages.

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

A seguir

Saiba mais sobre a referência de gerenciamento de endpoints de modelos
Use modelos de exemplo para registrar endpoints de modelos