Esta página foi traduzida pela API Cloud Translation.

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

MySQL | PostgreSQL | SQL Server

Esta página descreve como invocar previsões ou gerar embeddings usando um modelo e, em seguida, registrar 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 começar

Se o endpoint do modelo exigir autenticação, ative a extensão google_ml_integration.
Com base no provedor do modelo, configure a autenticação.
Use o nome de usuário padrão postgres para acessar o banco de dados.

Ativar a extensão

Defina a flag do banco de dados google_ml_integration.enable_model_support como on para sua instância. Para mais informações sobre como definir flags do banco de dados, consulte Configurar flags do banco de dados.
Conecte-se à instância principal usando um cliente psql ou o Cloud SQL Studio.
Execute o comando a seguir para garantir que a extensão google_ml_integration seja atualizada para a versão 1.4.2:
```
    ALTER EXTENSION google_ml_integration UPDATE TO '1.4.2'
```
Adicione a extensão google_ml_integration versão 1.4.2 usando psql:
```
  CREATE EXTENSION google_ml_integration VERSION '1.4.2';
```
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.

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 hospedados no Google Cloud.

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 Cloud SQL 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 o Cloud SQL à Vertex AI.

Configurar a autenticação para modelos hospedados de forma personalizada

Esta seção explica como configurar a autenticação se você estiver usando o Secret Manager. Para todos os modelos, exceto os endpoints de modelos da Vertex AI, é possível armazenar chaves de API ou tokens de portador no Secret Manager.

Se o endpoint do modelo não processar a autenticação pelo Secret Manager, esta seção será opcional. 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, não conclua as etapas desta seção.

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

Crie um 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().
Conceda permissões à instância do Cloud SQL para acessar o secret.
```
  gcloud secrets add-iam-policy-binding SECRET_ID \
      --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
      --role="roles/secretmanager.secretAccessor"
```
Substitua:
- SECRET_ID: o ID do secret no Secret Manager.
- SERVICE_ACCOUNT_EMAIL: o endereço de e-mail da conta de serviço do Cloud SQL baseada no IAM. Para encontrar esse endereço de e-mail, use o comando gcloud sql instances describe INSTANCE_NAME e substitua INSTANCE_NAME pelo nome da instância. O valor que aparece ao lado do parâmetro serviceAccountEmailAddress é o endereço de e-mail.

Modelos de embedding de texto com suporte integrado

Esta seção mostra como registrar endpoints de modelo para o gerenciamento de endpoints de modelo.

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 os IDs de endpoint dos modelos textembedding-gecko e textembedding-gecko@001 estão pré-registrados com o gerenciamento de endpoint de modelo, é possível usar qualquer um deles diretamente como o ID do modelo. Para esses modelos, a extensão configura automaticamente as funções de transformação padrão.

Verifique se a instância do Cloud SQL e o modelo da Vertex AI que você está consultando estão na mesma região.

Para registrar o endpoint do modelo textembedding-gecko@002, chame a função create_model:

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

Modelos de embedding de texto hospedados de forma personalizada

Esta seção mostra como registrar endpoints de modelos personalizados hospedados em redes no Google Cloud.

Adicionar endpoints de modelos de embedding de texto hospedados de forma personalizada envolve a criação de funções de transformação e, opcionalmente, de cabeçalhos HTTP personalizados. Por outro lado, a adição de endpoints de modelos genéricos hospedados de forma personalizada envolve a geração opcional de cabeçalhos HTTP personalizados e a definição do URL da solicitação do modelo.

O exemplo a seguir adiciona o endpoint do modelo de incorporação de texto custom-embedding-model hospedado pelo Cymbal, que é hospedado no Google Cloud. 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:

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 seu projeto do 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 do 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 externo.
- 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 um endpoint de 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 hospedado no Google Cloud.

O Cloud SQL só oferece suporte a endpoints de modelo disponíveis no Grupo de modelos da Vertex AI e endpoints de modelo hospedados em redes no Google Cloud.

Modelo do Gemini

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

Para registrar o endpoint do modelo gemini-1.0-pro, chame a função create model:

```sql
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 => 'cloudsql_service_agent_iam');
```

Replace the following:
* <code><var>MODEL_ID</var></code>: a unique ID for the model endpoint that you define (for example,<br> `gemini-1`). This model ID is referenced for metadata that the model endpoint needs to generate embeddings or invoke predictions.
* <code><var>PROJECT_ID</var></code>: the ID of your Google Cloud project.

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.