Configurar uma extensão para chamar um serviço do Google

As extensões de serviço permitem que os balanceadores de carga de aplicativo compatíveis configurem extensões usando frases de destaque para serviços do Google. Nesta página, mostramos como configurar essas extensões.

Para uma visão geral, consulte Integração com os Serviços do Google.

Configurar uma extensão de tráfego para chamar o serviço Model Armor

É possível configurar uma extensão de tráfego para chamar o Model Armor e aplicar políticas de segurança de maneira uniforme no tráfego de inferência de IA generativa para balanceadores de carga de aplicativo, incluindo o GKE Inference Gateway.

Uma extensão de tráfego agrupa serviços de extensão relacionados em uma ou mais cadeias. É possível configurar plug-ins e indicadores na mesma cadeia de extensão. Cada cadeia de extensão seleciona o tráfego em que vai agir usando condições de correspondência da Common Expression Language (CEL). O balanceador de carga avalia uma solicitação em relação à condição de correspondência de cada cadeia de maneira sequencial. Quando uma solicitação corresponde às condições definidas por uma cadeia, todas as extensões na cadeia agem na solicitação. Apenas uma cadeia corresponde a uma determinada solicitação.

Cada extensão em uma cadeia pode ter o próprio conjunto de eventos compatíveis. As modificações feitas por uma extensão no conteúdo de solicitação e resposta ficam visíveis para as outras extensões na cadeia. Para extensões configuradas para oferecer suporte a eventos de resposta, a sequência de extensões é invertida no caminho de resposta.

A extensão de tráfego se conecta a uma regra de encaminhamento de balanceador de carga criada usando o gateway de inferência. Depois de configurar o recurso, as solicitações correspondentes são enviadas ao serviço Model Armor.

Antes de começar

Identifique um projeto adequado em que você tenha um papel de proprietário ou editor ou os seguintes papéis do IAM do Compute Engine:
- Para criar instâncias: Administrador de instâncias do Compute (v1) (roles/compute.instanceAdmin.v1)
- Para criar componentes do Cloud Load Balancing: Administrador de rede do Compute (roles/compute.networkAdmin)
Ativar as APIs necessárias
Console
1. No console do Google Cloud , acesse a página Ativar acesso às APIs.
  
  Acessar "Ativar o acesso às APIs"
2. Siga as instruções para ativar as APIs necessárias, incluindo a API Compute Engine, a API Model Armor e a API Network Services.
gcloud
Use o comando gcloud services enable:
```
gcloud services enable compute.googleapis.com modelarmor.googleapis.com networkservices.googleapis.com
```
Crie os modelos do Model Armor necessários.
Configure sua infraestrutura do Google Kubernetes Engine implantando um gateway de inferência. Teste enviando uma solicitação de inferência.

Sujeitos a algumas limitações, os seguintes endpoints da API OpenAI são compatíveis: Assistants, Chat Completions, Completions (legado), Messages e Threads.

Limitações ao configurar um endpoint de API OpenAI

Ao configurar um endpoint de API OpenAI para sua infraestrutura do GKE, considere as seguintes limitações relacionadas à limpeza de comandos e respostas:

Respostas da API Streaming não são compatíveis com nenhuma API. Se você usa uma combinação de APIs de streaming e não streaming, ao configurar a extensão de tráfego, defina failOpen como true. O Model Armor higieniza as respostas sem streaming e ignora as respostas com streaming.
Ao higienizar comandos e respostas, apenas as seguintes operações são compatíveis:
- Assistants API: Create, Delete, List, Modify e Retrieve
- API Chat Completions: Create, Delete, Get Chat Completion, Get Chat Message, List e Update
- API Completions (legada): Create
- API Messages: Create, Delete, List, Modify e Retrieve
- API Threads: Create, Delete, Modify e Retrieve
Para chamadas de API que retornam várias opções na resposta (como POST https://api.openai.com/v1/chat/completions), apenas o primeiro item na lista de opções é higienizado.

Configurar a extensão de trânsito

Verifique o comportamento antes da configuração da extensão enviando uma solicitação de inferência ao balanceador de carga e especificando o endereço IP exposto dele:

curl -v http://${IP}/v1/chat/completions
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
  -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
       "messages": [
          {
            "role": "user",
            "content": "Can you remember my ITIN: 123-45-6789"
          }
        ],
       "max_tokens": 250,
       "temperature": 0.1}'

A solicitação gera um código de status HTTP 200 OK, embora dados sensíveis tenham sido enviados ao LLM.

Para que o Model Armor bloqueie comandos com dados sensíveis, configure uma extensão de tráfego.
Console
1. No console do Google Cloud , acesse a página Extensões de serviço.
  
  Acessar Extensões de serviço
2. Clique em Criar extensão. Um assistente vai abrir para orientar você nas etapas iniciais.
3. Para o produto, selecione Load Balancing. Em seguida, clique em Continuar. Uma lista de balanceadores de carga de aplicativo compatíveis aparece.
4. Selecione um tipo de balanceador de carga.
5. Especifique a região como us-central1. Clique em Continuar.
6. No tipo de extensão, selecione Extensões de tráfego e clique em Continuar.
7. Para abrir o formulário Criar extensão, clique em Continuar. No formulário Criar extensão, observe que as seleções anteriores não são editáveis.
8. Na seção Noções básicas, faça o seguinte:
  1. Especifique um nome exclusivo para a extensão.
    
    O nome precisa começar com uma letra minúscula seguida por até 62 letras minúsculas, números ou hifens e não pode terminar com um hífen.
  2. Opcional: digite uma breve descrição sobre a extensão usando até 1.024 caracteres.
  3. Opcional: na seção Rótulos, clique em Adicionar rótulo. Em seguida, na linha que aparece, faça o seguinte:
    
    Em Chave, insira um nome de chave.
    
    Em Valor, insira um valor para a chave.
    
    Para adicionar mais pares de chave-valor, clique em Adicionar rótulo. É possível adicionar no máximo 64 pares de chave-valor.
    
    Para mais informações sobre rótulos, consulte Criar e atualizar rótulos para projetos.
9. Em Regras de encaminhamento, selecione uma ou mais regras de encaminhamento para associar à extensão. Escolha uma regra de encaminhamento gerada como parte da implantação do Inference Gateway. As regras de encaminhamento já associadas a outra extensão não podem ser selecionadas e aparecem como indisponíveis.
10. Para Cadeias de extensão, adicione uma ou mais cadeias de extensão para executar em uma solicitação correspondente.
  
  Para adicionar uma cadeia de extensões, faça o seguinte e clique em Concluído:
  - Em Novo nome da cadeia de extensão, especifique um nome exclusivo.
    
    O nome precisa estar em conformidade com a RFC-1034, usar apenas letras minúsculas, números e hifens e ter um comprimento máximo de 63 caracteres. Além disso, o primeiro caractere precisa ser uma letra, e o último, uma letra ou um número.
  - Para corresponder a solicitações em que a cadeia de extensão é executada, em Condição de correspondência, especifique uma expressão da Common Expression Language (CEL), por exemplo, request.path == "/v1/chat/completions".
    
    Para mais informações sobre expressões CEL, clique em Receber ajuda com a sintaxe ou consulte a referência da linguagem de correspondência da CEL.
  - Adicione uma ou mais extensões para executar em uma solicitação correspondente.
    
    Para cada extensão, em Extensões, faça o seguinte e clique em Concluído:
    
    Em Nome da extensão, especifique um nome exclusivo.
    
    O nome precisa estar em conformidade com a RFC-1034, usar apenas letras minúsculas, números e hifens e ter um comprimento máximo de 63 caracteres. Além disso, o primeiro caractere precisa ser uma letra e o último caractere precisa ser uma letra ou um número.
    
    Em Tipo de programabilidade, selecione Serviços do Google e escolha um endpoint de serviço do Model Armor, por exemplo, modelarmor.us-central1.rep.googleapis.com.
    
    Para Tempo limite, especifique um valor entre 10 e 1.000 milissegundos após o qual uma mensagem na transmissão expira. Considere que o Model Armor tem uma latência de aproximadamente 250 milissegundos.
    
    Em Eventos, selecione todos os tipos de eventos HTTP.
    
    Em Encaminhar cabeçalhos, clique em Adicionar cabeçalho e adicione cabeçalhos HTTP para encaminhar à extensão (do cliente ou do back-end). Se um cabeçalho não for especificado, todos os cabeçalhos serão enviados.
    
    Opcional: se a extensão atingir o tempo limite ou falhar e você quiser que o processamento de solicitações ou respostas continue, selecione Ativado em Falha aberta. As extensões subsequentes na cadeia também são executadas.
    
    Por padrão, a opção Falha ao abrir não está selecionada. Nesse caso, quando ocorre um erro, o processamento da solicitação ou da resposta é interrompido. Se os cabeçalhos de resposta não tiverem sido entregues ao cliente downstream, um código de status HTTP 500 genérico será retornado ao cliente. Se os cabeçalhos de resposta tiverem sido entregues, o fluxo HTTP para o cliente será redefinido.
    
    A opção padrão de manter Falha aberta desmarcada é preferível ao priorizar a segurança ou a integridade. Ativar a opção Falha aberta, principalmente para operações não críticas, ajuda a priorizar a disponibilidade.
    
    Em Metadados, clique em Adicionar metadados para especificar os modelos do Model Armor que serão usados para analisar comandos e respostas correspondentes a modelos específicos.
    
    Em Chave, especifique model_armor_settings. Para Value, especifique os modelos como uma string JSON, como esta:
    
    [{ "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" }]
    
    Substitua:
    
    MODEL_NAME: o nome do modelo configurado com o recurso InferenceModel. Por exemplo, meta-llama/Llama-3.1-8B-Instruct
    
    TEMPLATE_PROJECT_ID: o ID do projeto dos modelos do Model Armor
    
    LOCATION: o local do modelo do Model Armor. Por exemplo, us-central1.
    
    RESPONSE_TEMPLATE: o modelo de resposta que o modelo vai usar
    
    PROMPT_TEMPLATE: o modelo de comando a ser usado pelo modelo
    
    Um modelo padrão também pode ser especificado para uso quando uma solicitação não corresponde exatamente a um modelo. Para configurar um modelo padrão, especifique MODEL_NAME como default.
    
    Se você não quiser solicitações na tela ou tráfego de respostas, crie e inclua um modelo de filtro vazio.
    
    O tamanho total de metadata precisa ser menor que 1 KiB. O número total de chaves nos metadados precisa ser menor que 20. O comprimento de cada chave precisa ser menor que 64 caracteres. O comprimento de cada valor precisa ser menor que 1.024 caracteres. Todos os valores precisam ser strings.
    
    Quando uma solicitação é bloqueada, o Model Armor retorna um código de status 403 Forbidden padrão. É possível substituir o status definindo configurações de resposta personalizadas (incluindo um código de status e uma mensagem personalizados) na política de segurança do modelo do Model Armor. Para mais detalhes, consulte TemplateMetadata.
11. Clique em Criar extensão.
gcloud
1. Defina o callout em um arquivo YAML e associe-o à regra de encaminhamento gerada ao implantar o Inference Gateway. Use os valores de amostra fornecidos.
  cat >traffic_callout_service.yaml <<EOF name: traffic-ext forwardingRules: - https://www.googleapis.com/compute/v1/projects/LB_PROJECT_ID/regions/us-central1/forwardingRules/FORWARDING_RULE loadBalancingScheme: INTERNAL_MANAGED extensionChains: - name: "chain1-model-armor" matchCondition: celExpression: 'request.path == "/v1/chat/completions"' extensions: - name: extension-chain-1-model-armor service: modelarmor.us-central1.rep.googleapis.com failOpen: true supportedEvents: - REQUEST_HEADERS - REQUEST_BODY - REQUEST_TRAILERS - RESPONSE_HEADERS - RESPONSE_BODY - RESPONSE_TRAILERS timeout: 1s metadata: model_armor_settings: '[ { "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" } ]' EOF
  Substitua:
  - TEMPLATE_PROJECT_ID: o ID do projeto dos modelos do Model Armor
  - LB_PROJECT_ID: o ID do projeto da regra de encaminhamento do balanceador de carga
  - FORWARDING_RULE: uma ou mais regras de encaminhamento a serem associadas à extensão. Escolha uma regra de encaminhamento gerada como parte da implantação do Inference Gateway.
    
    As regras de encaminhamento já associadas a outra extensão não podem ser selecionadas e aparecem como indisponíveis.
  - MODEL_NAME: o nome do modelo configurado com o recurso InferenceModel. Por exemplo, meta-llama/Llama-3.1-8B-Instruct
  - LOCATION: o local do modelo do Model Armor. Por exemplo, us-central1.
  - RESPONSE_TEMPLATE: o modelo de resposta que o modelo vai usar
  - PROMPT_TEMPLATE: o modelo de comando a ser usado pelo modelo
  No campo metadata, especifique as configurações e os modelos do Model Armor a serem usados ao analisar comandos e respostas correspondentes a modelos específicos.
  
  Um modelo padrão também pode ser especificado para uso quando uma solicitação não corresponde exatamente a um modelo. Para configurar um modelo padrão, especifique MODEL_NAME como default.
  
  Se você não quiser solicitações na tela ou tráfego de respostas, crie e inclua um modelo de filtro vazio.
  
  O tamanho total de metadata precisa ser menor que 1 KiB. O número total de chaves nos metadados precisa ser menor que 16. O comprimento de cada chave precisa ser menor que 64 caracteres. O comprimento de cada valor precisa ser menor que 1.024 caracteres. Todos os valores precisam ser strings.
  
  Quando uma solicitação é bloqueada, o Model Armor retorna um código de status 403 Forbidden padrão. É possível substituir o status definindo configurações de resposta personalizadas (incluindo um código de status e uma mensagem personalizados) na política de segurança do modelo do Model Armor. Para mais detalhes, consulte TemplateMetadata.
2. Importe a extensão de tráfego. Use o comando gcloud service-extensions lb-traffic-extensions import com os seguintes valores de exemplo.
  gcloud service-extensions lb-traffic-extensions import traffic-ext \ --source=traffic_callout_service.yaml \ --location=us-central1
kubectl
1. Se você estiver usando uma versão do GKE anterior a v1.32.2-gke.1182001, instale o CRD da extensão de tráfego:
  kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/gke-gateway-api/refs/heads/main/config/crd/networking.gke.io_gcptrafficextensions.yaml
2. Defina a extensão em um arquivo YAML. Esse recurso personalizado vincula seu gateway de inferência ao serviço Model Armor. Use os valores de amostra fornecidos.
  cat >traffic_callout_service.yaml <<EOF apiVersion: networking.gke.io/v1 kind: GCPTrafficExtension metadata: name: traffic-ext spec: targetRefs: - group: "gateway.networking.k8s.io" kind: Gateway name: inference-gateway extensionChains: - name: "chain1-model-armor" matchCondition: celExpressions: - celMatcher: 'request.path == "/v1/chat/completions"' extensions: - name: extension-chain-1-model-armor googleAPIServiceName: modelarmor.us-central1.rep.googleapis.com failOpen: true supportedEvents: - RequestHeaders - RequestBody - RequestTrailers - ResponseHeaders - ResponseBody - ResponseTrailers timeout: 1s metadata: model_armor_settings: '[ { "model": "MODEL_NAME", "model_response_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/RESPONSE_TEMPLATE", "user_prompt_template_id": "projects/TEMPLATE_PROJECT_ID/locations/LOCATION/templates/PROMPT_TEMPLATE" } ]' EOF
  Substitua:
  - MODEL_NAME: o nome do modelo configurado com o recurso InferenceModel. Por exemplo, meta-llama/Llama-3.1-8B-Instruct
  - TEMPLATE_PROJECT_ID: o ID do projeto dos modelos do Model Armor
  - LOCATION: o local do modelo do Model Armor. Por exemplo, us-central1.
  - RESPONSE_TEMPLATE: o modelo de resposta que o modelo vai usar
  - PROMPT_TEMPLATE: o modelo de comando a ser usado pelo modelo
  No campo metadata, especifique as configurações e os modelos do Model Armor a serem usados ao analisar comandos e respostas correspondentes a modelos específicos.
  
  Um modelo padrão também pode ser especificado para uso quando uma solicitação não corresponde exatamente a um modelo. Para configurar um modelo padrão, especifique MODEL_NAME como default.
  
  Se você não quiser solicitações na tela ou tráfego de respostas, crie e inclua um modelo de filtro vazio.
  
  O tamanho total de metadata precisa ser menor que 1 KiB. O número total de chaves nos metadados precisa ser menor que 16. O comprimento de cada chave precisa ser menor que 64 caracteres. O comprimento de cada valor precisa ser menor que 1.024 caracteres. Todos os valores precisam ser strings.
  
  Quando uma solicitação é bloqueada, o Model Armor retorna um código de status 403 Forbidden padrão. É possível substituir o status definindo configurações de resposta personalizadas (incluindo um código de status e uma mensagem personalizados) na política de segurança do modelo do Model Armor. Para mais detalhes, consulte TemplateMetadata.
3. Aplique a configuração definida no arquivo traffic_callout_service.yaml ao cluster do GKE. Esse comando cria o recurso GCPTrafficExtension, que vincula o Gateway de inferência ao serviço Model Armor.
  kubectl apply -f traffic_callout_service.yaml

Conceda os papéis necessários à conta de serviço das extensões de serviço. Use o comando gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/container.admin
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/serviceusage.serviceUsageConsumer
gcloud projects add-iam-policy-binding TEMPLATE_PROJECT_ID \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.user

Substitua:

TEMPLATE_PROJECT_ID: o ID do projeto dos modelos do Model Armor
LB_PROJECT_NUMBER: o número do projeto do balanceador de carga

Esses valores estão listados no painel Informações do projeto no console doGoogle Cloud do seu projeto.

Para verificar se a extensão de tráfego funciona conforme o esperado, execute o mesmo comando curl:

curl -v http://${IP}/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H 'Authorization: Bearer $(gcloud auth print-access-token)' \
  -d '{"model": "meta-llama/Llama-3.1-8B-Instruct",
       "messages": [
          {
            "role": "user",
            "content": "Can you remember my ITIN: 123-45-6789"
          }
        ],
       "max_tokens": 250,
       "temperature": 0.1}'
  ```

Com a extensão de serviço configurada, uma solicitação com dados sensíveis gera um código de status HTTP 403 Forbidden, registra uma mensagem de erro conforme configurado no modelo e fecha a conexão.

Quando a solicitação é segura, ela gera um código de status HTTP 200 OK e retorna a resposta do LLM ao usuário.

Para monitorar o comportamento da extensão, use o Explorador de registros. No painel de consultas, dependendo da configuração do Inference Gateway, filtre pelo tipo de recurso do balanceador de carga adequado.

As entradas de registro do balanceador de carga de aplicativo contêm informações que ajudam a depurar o tráfego HTTP ou HTTPS.

Para fazer uma análise mais detalhada das avaliações de segurança, ative o registro de auditoria do Model Armor.

A seguir

Gerenciar extensões

Configurar uma extensão para chamar um serviço do Google Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.