Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 os 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 frases de destaque na mesma cadeia de extensão. Cada cadeia de extensão seleciona o tráfego em que vai atuar usando Common Expression Language (CEL) condições de correspondência. 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 atuam 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 da solicitação e da resposta ficam visíveis para as extensões restantes 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 é anexada a uma regra de encaminhamento do balanceador de carga criada usando o Inference Gateway. 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 do projeto ou os seguintes papéis do IAM do Compute Engine:
- Para criar instâncias: Administrador da instância 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 Google Cloud console do, acesse a página Ativar acesso às APIs.
  
  Acessar Ativar acesso às APIs
2. Siga as instruções para ativar as APIs necessárias, que incluem 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 Inference Gateway. Teste-o enviando uma solicitação de inferência.

Sujeito 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 à higienização de comandos e respostas:

As respostas da API Streaming não são compatíveis com nenhuma API. O Model Armor higieniza as respostas sem streaming e ignora as respostas de streaming.
Ao higienizar comandos e respostas, apenas as seguintes operações são compatíveis. Qualquer outra operação é ignorada e permitida sem higienização:
- API Assistants: Create, Delete, List, Modify e Retrieve
- API Chat Completions: Create, Delete, Get Chat Completion, Get Chat Message, List e Update
- API Completions (legado): Create
- API Messages: Create, Delete, List, Modify e Retrieve
- API Responses: Create, Delete e Get
- 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áfego

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

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 que contenham dados sensíveis, configure uma extensão de tráfego.
Console
1. No Google Cloud console, acesse a página Service Extensions.
  
  Acessar Extensões de serviço
2. Clique em Criar extensão. Um assistente é aberto para orientar você nas etapas iniciais.
3. Para o produto, selecione Balanceamento de carga. Em seguida, clique em Continuar. Uma lista de balanceadores de carga de aplicativo compatíveis será exibida.
4. Selecione um tipo de balanceador de carga.
5. Especifique a região como us-central1. Clique em Continuar.
6. Para o 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 podem ser editadas.
8. Na seção Noções básicas, faça o seguinte:
  
  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.
  
  Opcional: insira uma breve descrição sobre a extensão usando até 1.024 caracteres.
9. Opcional: na seção Marcadores, clique em Adicionar marcador. 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 marcador. É possível adicionar no máximo 64 pares de chave-valor.
  
  Para mais informações sobre marcadores, consulte Criar e atualizar marcadores para projetos.
10. 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 que já estão associadas a outra extensão não podem ser selecionadas e aparecem como indisponíveis.
11. Em Extensão, para adicionar uma extensão a ser executada para uma solicitação correspondente, faça o seguinte:
  
  Para corresponder a solicitações para as quais 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 de sintaxe ou consulte Referência da linguagem do matcher CEL.
  
  Adicione uma ou mais extensões a serem executadas para uma solicitação correspondente.
  
  Para cada extensão, em Extensões, faça o seguinte e clique em Concluído:
  
  Em Tipo de programabilidade, selecione Serviços do Google e em seguida, selecione um endpoint de serviço do Model Armor, por exemplo, modelarmor.us-central1.rep.googleapis.com.
  
  Em Tempo limite, especifique um valor entre 10 e 1.000 milissegundos após o qual uma mensagem no fluxo 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 para a 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 expirar ou falhar e você quiser que o processamento de solicitação ou resposta continue, em Falha aberta, selecione Ativado. As extensões subsequentes na cadeia também são executadas.
  
  Por padrão, a opção Falha aberta não está selecionada. Nesse caso, quando ocorre um erro, o processamento de solicitação ou 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 Falha aberta, especialmente 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 a serem usados para verificar comandos e respostas correspondentes a modelos específicos.
  
  Em Chave, especifique model_armor_settings. Em Valor, especifique os modelos como uma string JSON, como a seguinte:
  
  [{ "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 conforme 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 para o modelo a ser usado
  
  PROMPT_TEMPLATE: o modelo de comando para o modelo a ser usado
  
  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 verificar o tráfego de comandos ou 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.
  
  Se você quiser especificar mais de uma extensão ou cadeias de extensão em vez de uma única extensão, clique no botão Mudar para o modo avançado no final do formulário e especifique as extensões e cadeias necessárias. As extensões são executadas na sequência em que estão listadas.
  
  Especifique nomes exclusivos para cada extensão e cadeia de extensão. Os nomes precisam 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.
12. Clique em Criar extensão.
gcloud
1. Defina a frase de destaque em um arquivo YAML e associe-a à 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 para associar à extensão. Escolha uma regra de encaminhamento gerada como parte da implantação do Inference Gateway.
  
  As regras de encaminhamento que já estão associadas a outra extensão não podem ser selecionadas e aparecem como indisponíveis.
  
  MODEL_NAME: o nome do modelo conforme 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 para o modelo a ser usado
  
  PROMPT_TEMPLATE: o modelo de comando para o modelo a ser usado
  
  No campo metadata, especifique as configurações e os modelos do Model Armor a serem usados ao verificar 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 verificar o tráfego de comandos ou 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 gcloud service-extensions lb-traffic-extensions import comando com os seguintes valores de amostra.
  
  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 à 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 o Inference Gateway 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 conforme 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 para o modelo a ser usado
  
  PROMPT_TEMPLATE: o modelo de comando para o modelo a ser usado
  
  No campo metadata, especifique as configurações e os modelos do Model Armor a serem usados ao verificar 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 verificar o tráfego de comandos ou 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 Inference Gateway ao serviço Model Armor.
  
  kubectl apply -f traffic_callout_service.yaml

Conceda os papéis necessários à conta de serviço do Service Extensions. Use o gcloud projects add-iam-policy-binding comando:

gcloud projects add-iam-policy-binding LB_PROJECT_NUMBER \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/container.admin
gcloud projects add-iam-policy-binding LB_PROJECT_NUMBER \
    --member=serviceAccount:service-LB_PROJECT_NUMBER@gcp-sa-dep.iam.gserviceaccount.com \
    --role=roles/modelarmor.calloutUser
gcloud projects add-iam-policy-binding LB_PROJECT_NUMBER \
    --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 em Google Cloud console para 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 Análise de registros. No painel de consulta, dependendo da configuração do Inference Gateway, filtre pelo tipo de recurso do balanceador de carga apropriado.

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 realizar 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.