Esta página foi traduzida pela API Cloud Translation.

Definir permissões para funções de IA generativa que chamam LLMs da Vertex AI

Neste documento, mostramos como configurar permissões para executar consultas de IA generativa. As consultas de IA generativa contêm funções AI.* que chamam modelos de base na Vertex AI, por exemplo, AI.GENERATE.

Há duas maneiras de configurar permissões para executar consultas que usam funções AI.*:

Executar a consulta usando suas credenciais de usuário final
Criar uma conexão do BigQuery ML para executar a consulta usando uma conta de serviço

Na maioria dos casos, é possível usar as credenciais do usuário final e deixar o argumento CONNECTION em branco. Se o job de consulta for executado por 48 horas ou mais, use uma conexão do BigQuery e inclua-a no argumento CONNECTION.

Executar consultas de IA generativa com credenciais de usuário final

Para executar consultas de IA generativa usando credenciais de usuário final, configure as permissões necessárias usando o console do Google Cloud . Se você for o proprietário do projeto, já terá todas as permissões necessárias e não precisará fazer nada.

Funções exigidas

Para receber as permissões necessárias para executar um job de consulta que chama um modelo da Vertex AI, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Executar jobs de consulta: Usuário de jobs do BigQuery (roles/bigquery.jobUser)
Acessar um modelo de base na Vertex AI: Usuário da Vertex AI (roles/aiplatform.user)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Conceder as funções necessárias ao usuário ou grupo

É possível usar o console Google Cloud para conceder os papéis necessários a um principal. O principal é o usuário ou grupo que executa a consulta que usa funções AI.* para chamar um modelo de fundação da Vertex AI.

No console do Google Cloud , acesse a página IAM.

Acessar IAM
Selecione o projeto.
Para conceder papéis a um principal:
1. Acesse a página IAM e administrador.
  
  Acessar IAM e administrador
2. Clique em CONCEDER ACESSO.
  
  A caixa de diálogo Adicionar principais é aberta.
3. No campo Novos principais, insira o identificador principal— por exemplo, my-user@example.com ou //iam.googleapis.com/locations/global/workforcePools/example-pool/group/example-group@example.com.
4. Na seção Atribuir papéis, em Selecionar um papel, clique na seta suspensa.
5. Pesquise e selecione o papel Usuário da Vertex AI.
6. Clique em Adicionar outro papel.
7. Na seção Atribuir papéis, em Selecionar um papel, clique na seta suspensa.
8. Procure ou navegue até o papel Usuário de jobs do BigQuery e selecione-o.
9. Clique em Salvar.

Para modificar papéis de um principal que já tem papéis no projeto, consulte Conceder papéis adicionais ao mesmo principal.

Para informações sobre outros métodos de concessão de papéis no nível do projeto a um principal, consulte Conceder ou revogar vários papéis do IAM de maneira programática.

Executar consultas de IA generativa com uma conexão do BigQuery

Para executar consultas de IA generativa usando uma conexão, crie a conexão e conceda acesso à conta de serviço criada por ela.

Crie uma conexão

É possível configurar uma conexão de recursos do Cloud para executar todas as consultas de IA generativa que contêm funções AI.*. Ao criar uma conexão, você concede permissões para executar consultas em uma conta de serviço.

Selecione uma das seguintes opções:

Console

Acessar a página do BigQuery.

Acessar o BigQuery
No painel à esquerda, clique em Explorer:

Se você não vir o painel à esquerda, clique em Expandir painel esquerdo para abrir o painel.
No painel Explorer, expanda o nome do projeto e clique em Conexões.
Na página Conexões, clique em Criar conexão.
Em Tipo de conexão, escolha Modelos remotos da Vertex AI, funções remotas, BigLake e Spanner (recurso do Cloud).
No campo ID da conexão, insira um nome para a conexão.
Em Tipo de local, selecione um local para sua conexão. A conexão precisa estar alocada com seus outros recursos, como conjuntos de dados.
Clique em Criar conexão.
Clique em Ir para conexão.
No painel Informações da conexão, copie o ID da conta de serviço para usar em uma etapa posterior.

bq

Em um ambiente de linha de comando, crie uma conexão:
```
bq mk --connection --location=REGION --project_id=PROJECT_ID \
    --connection_type=CLOUD_RESOURCE CONNECTION_ID
```
O parâmetro --project_id substitui o projeto padrão.

Substitua:
- REGION: sua região de conexão
- PROJECT_ID: o ID do projeto do Google Cloud
- CONNECTION_ID: um ID para sua conexão
Quando você cria um recurso de conexão, o BigQuery cria uma conta de serviço do sistema exclusiva e a associa à conexão.

Solução de problemas: se você receber o seguinte erro de conexão, atualize o SDK Google Cloud:
```
Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
```

Recupere e copie o ID da conta de serviço para uso em uma etapa posterior:

bq show --connection PROJECT_ID.REGION.CONNECTION_ID

O resultado será assim:

name                          properties
1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel.iam.gserviceaccount.com"}

Terraform

Use o recurso google_bigquery_connection.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

O exemplo a seguir cria uma conexão de recurso do Google Cloud chamada my_cloud_resource_connection na região US:


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

Para aplicar a configuração do Terraform em um projeto Google Cloud , siga as etapas nas seções a seguir.

Preparar o Cloud Shell

Inicie o Cloud Shell.
Defina o projeto Google Cloud padrão em que você quer aplicar as configurações do Terraform.

Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

Copie o exemplo de código no main.tf recém-criado.

Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.
Revise e modifique os parâmetros de amostra para aplicar ao seu ambiente.
Salve as alterações.
Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.
```
terraform init
```
Opcionalmente, para usar a versão mais recente do provedor do Google, inclua a opção -upgrade:
```
terraform init -upgrade
```

Aplique as alterações

Revise a configuração e verifique se os recursos que o Terraform vai criar ou atualizar correspondem às suas expectativas:
```
terraform plan
```
Faça as correções necessárias na configuração.
Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:
```
terraform apply
```
Aguarde até que o Terraform exiba a mensagem "Apply complete!".
Abra seu Google Cloud projeto para conferir os resultados. No console do Google Cloud , navegue até seus recursos na interface para verificar se foram criados ou atualizados pelo Terraform.

Para mais informações, consulte Criar e configurar uma conexão de recursos do Cloud.

Conceder acesso à conta de serviço

Para executar consultas que usam funções generativas AI.* que chamam modelos da Vertex AI, conceda as permissões adequadas à conta de serviço criada quando você criou a conexão. Para executar funções que chamam um modelo de fundação da Vertex AI, é necessário ter a função de usuário da Vertex AI (roles/aiplatform.user).