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

Nesta página, descrevemos como invocar previsões ou gerar incorporações usando um modelo e, em seguida, registrar o endpoint do modelo com o gerenciamento de endpoints de modelo.

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

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 de banco de dados, consulte Configurar flags de banco de dados.
Conecte-se à instância principal usando um psql cliente ou o Cloud SQL Studio.
Execute o comando a seguir para garantir que a extensão google_ml_integration esteja 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 do PostgreSQL que não seja superadministrador 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 é superusuário.

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 em Google Cloud.

Configurar a autenticação para a Vertex AI

Para usar os endpoints de modelo da Vertex AI do Google, adicione 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

Nesta seção, explicamos como configurar a autenticação se você estiver usando o Secret Manager. Para todos os modelos, exceto os endpoints de modelo da Vertex AI, é possível armazenar chaves de API ou tokens de acesso 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 autenticação, não conclua as etapas desta seção.

Para criar e usar uma chave de API ou um token de autenticação, siga estas etapas:

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

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 gerenciamento de endpoints de modelo.

Modelos de embedding da Vertex AI

O gerenciamento de endpoints de 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 do modelo textembedding-gecko e textembedding-gecko@001 são pré-registrados com o gerenciamento de endpoints de modelo, é possível usar qualquer um deles diretamente como o ID do modelo. Para esses modelos, a extensão configura automaticamente 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 incorporação de texto hospedados de forma personalizada

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

Para adicionar endpoints de modelos de incorporação de texto hospedados de forma personalizada, é necessário criar funções de transformação e, opcionalmente, cabeçalhos HTTP personalizados. Por outro lado, adicionar endpoints de modelo genérico hospedados de forma personalizada envolve gerar cabeçalhos HTTP personalizados e definir o URL de 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 está hospedado em 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 posteriormente 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 Google Cloud projeto.
- VERSION_NUMBER: o número da versão do ID do secret.
Observação: por padrão, o Secret Manager gera um cabeçalho Authorization: Bearer SECRET_VALUE_FROM_SECRET_MANAGER para autenticação. Se esse formato corresponder ao formato do token de autenticaçã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çalho.

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

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 é referenciado para metadados que o endpoint do modelo precisa gerar incorporações ou invocar previsões.
- REQUEST_URL: obrigatório. O endpoint específico do modelo ao adicionar embeddings de texto personalizados 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 aceita 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 do secret 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ó é compatível com endpoints de modelo disponíveis no Model Garden da Vertex AI e endpoints de modelo hospedados em redes dentro de 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 modelo.