Requisitos para fazer inferências usando um contêiner personalizado

Para usar um contêiner personalizado para disponibilizar inferências de um modelo treinado personalizado, forneça à Gemini Enterprise Agent Platform uma imagem do contêiner do Docker que execute um servidor HTTP. Este documento descreve os requisitos que uma imagem do contêiner precisa atender para ser compatível com a Gemini Enterprise Agent Platform. O documento também descreve como a Agent Platform interage com o contêiner personalizado quando ele é executado. Em outras palavras, este documento descreve o que você precisa considerar ao projetar uma imagem de contêiner para usar com a plataforma de agentes.

Se quiser saber como usar uma imagem de contêiner personalizado para exibir inferências, leia Como usar um contêiner personalizado.

Requisitos de imagem do contêiner

Digamos que a imagem do contêiner do Docker seja executada como um contêiner. Nesse caso, o contêiner precisa executar um servidor HTTP. Especificamente, o contêiner precisa detectar e responder a verificações de atividade, verificações de integridade e solicitações de inferência. As subseções a seguir descrevem esses requisitos em detalhes.

É possível implementar o servidor HTTP de várias formas, com qualquer linguagem de programação, desde que atenda aos requisitos desta seção. Por exemplo, é possível gravar um servidor HTTP personalizado com um framework da Web, como Flask, ou usar um software de veiculação de machine learning (ML) que executa um servidor HTTP, como TensorFlow Serving, TorchServe ou KServe Python Serve.

Executar o servidor HTTP

É possível executar um servidor HTTP com uma instrução ENTRYPOINT, uma instrução CMD ou ambas no Dockerfile que você usa para criar a imagem do contêiner. Leia sobre a interação entre CMD e ENTRYPOINT.

Como alternativa, você pode especificar os campos containerSpec.command e containerSpec.args ao criar seu recurso Model para modificar sua imagem de contêiner ENTRYPOINT e CMD, respectivamente. Especificar um desses campos permite usar uma imagem de contêiner que não atenderia aos requisitos devido a um ENTRYPOINT ou CMD incompatível (ou inexistente).

Determine o comando que será executado quando o contêiner for iniciado. Certifique-se de que essa instrução ENTRYPOINT seja executada indefinidamente, seja ela qual for. Por exemplo, não execute um comando que inicie um servidor HTTP em segundo plano e depois saia. Se você fizer isso, o contêiner será encerrado imediatamente depois que começar a ser executado.

O servidor HTTP precisa detectar solicitações no 0.0.0.0, em uma porta de sua escolha. Ao criar um Model, especifique essa porta no campo containerSpec.ports. Para saber como o contêiner pode acessar esse valor, leia a seção deste documento sobre a variável de ambiente AIP_HTTP_PORT.

Verificações de atividade

O Agent Platform realiza uma verificação de atividade quando o contêiner é iniciado para garantir que o servidor esteja em execução. Quando você implanta um modelo treinado personalizado em um Endpoint recurso, Agent Platform usa uma sondagem de ativação TCP para tentar estabelecer uma conexão TCP com seu contêiner na porta configurada. A sondagem faz até 4 tentativas de estabelecer uma conexão, aguardando 10 segundos após cada falha. Se a sondagem ainda não tiver estabelecido uma conexão, a Agent Platform reiniciará o contêiner.

O servidor HTTP não precisa executar nenhum comportamento especial para processar essas verificações. Enquanto estiver detectando solicitações na porta configurada, a sondagem de atividade poderá fazer uma conexão.

Verificações de integridade

Também é possível especificar startup_probe ou health_probe.

A sondagem de inicialização verifica se o aplicativo do contêiner foi iniciado. Se a sondagem de inicialização não for fornecida, não haverá sondagem de inicialização e as verificações de integridade começarão imediatamente. Se a sondagem de inicialização for fornecida, as verificações de integridade não serão realizadas até que a sondagem de inicialização seja bem-sucedida.

Aplicativos legados que podem exigir mais tempo na primeira inicialização precisam configurar uma sondagem de inicialização. Por exemplo, se o aplicativo precisar copiar os artefatos do modelo de uma fonte externa, uma sondagem de inicialização precisará ser configurada para retornar sucesso quando essa inicialização for concluída.

A sondagem de integridade verifica se um contêiner está pronto para aceitar tráfego. Se a sondagem de integridade não for fornecida, a plataforma de agentes usará as verificações de integridade padrão, conforme descrito neste link.

Os aplicativos legados que não retornam 200 OK para indicar que o modelo está carregado e pronto para aceitar tráfego precisam configurar uma sondagem de integridade. Por exemplo, um aplicativo pode retornar 200 OK para indicar êxito mesmo que o status real de carregamento do modelo no corpo da resposta indique que o modelo pode não estar carregado e, assim, não estar pronto para aceitar tráfego. Nesse caso, uma sondagem de integridade precisa ser configurada para retornar êxito somente quando o modelo estiver carregado e pronto para disponibilizar tráfego.

Para executar uma sondagem, a Agent Platform executa o comando exec especificado no contêiner de destino. Se o comando for bem-sucedido, ele retornará 0 e o contêiner será considerado ativo e íntegro.

Verificações de integridade padrão

Por padrão, o Agent Platform executa de maneira intermitente verificações de integridade no servidor HTTP durante a execução para garantir que ele esteja pronto para processar as solicitações de inferência. O serviço usa uma sondagem de integridade para enviar solicitações HTTP GET a um caminho de verificação de integridade configurável no seu servidor. Especifique este caminho no campo containerSpec.healthRoute ao criar um Model. Para saber como o contêiner pode acessar esse valor, leia a seção deste documento sobre a variável de ambiente AIP_HEALTH_ROUTE.

Configure o servidor HTTP para responder a cada solicitação de verificação de integridade da seguinte maneira:

  • Se o servidor estiver pronto para processar solicitações de inferência,responda à solicitação de verificação de integridade dentro de 10 segundos com o código de status 200 OK. O conteúdo do corpo da resposta não importa. Ele é ignorado pela Agent Platform.

    Essa resposta significa que o servidor está íntegro.

  • Se o servidor não estiver pronto para processar solicitações de inferência , não responda à solicitação de verificação de integridade em 10 segundos nem com qualquer código de status exceto 200 OK. Por exemplo, responda com o código de status 503 Service Unavailable.

    Esta resposta (ou a falta de uma resposta) significa que o servidor não está íntegro.

Se a sondagem de integridade receber uma resposta não íntegra do servidor, incluindo a falta de resposta em 10 segundos, ela enviará até 3 verificações de integridade extras em intervalos de 10 segundos. Durante esse período, a Agent Platform ainda considerará o servidor íntegro. Se a sondagem receber uma resposta íntegra para qualquer uma dessas verificações, a sondagem retornará imediatamente para a programação intermitente das verificações de integridade. No entanto, se a sondagem receber quatro respostas consecutivas não íntegras, a Agent Platform interromperá o roteamento do tráfego de inferência para o contêiner. Se o recurso DeployedModel for escalonado para usar vários nós de inferência, a Agent Platform encaminhará as solicitações de inferência a outros contêineres íntegros.

A Agent Platform não reinicia o contêiner. Em vez disso, a sondagem de integridade continua enviando solicitações intermitentes de verificação de integridade ao servidor não íntegro. Se receber uma resposta íntegra, ele marcará esse contêiner como íntegro e começará a rotear o tráfego de inferência para ele novamente.

Orientação prática

Em alguns casos, é suficiente que o servidor HTTP no contêiner sempre responda com o código de status 200 OK às verificações de integridade. Se o contêiner carregar recursos antes de iniciar o servidor, ele não estará íntegro durante o período de inicialização e durante qualquer período em que o servidor HTTP falhar. Em todos os outros momentos, ele responderá como íntegro.

Para uma configuração mais sofisticada, convém projetar propositalmente o servidor HTTP para responder às verificações de integridade com um status não íntegro em determinados momentos. Por exemplo, convém bloquear o tráfego de inferência em um nó por um período para que o contêiner possa realizar a manutenção.

Solicitações de inferência

Há dois padrões para configurar rotas para o servidor de modelos. Um definido pela Gemini Enterprise Agent Platform (/predict) e o outro que permite personalização completa para que você possa simplesmente inserir o servidor de modelos de sua escolha (/invoke).

Rota /predict definida pela Vertex

Quando um cliente envia uma projects.locations.endpoints.predict solicitação à Agent Platform API, a Agent Platform encaminha esta solicitação como uma solicitação HTTP POST para um caminho de inferência configurável no seu servidor. Especifique este caminho no containerSpec.predictRoute campo ao criar um Model. Para saber como o contêiner pode acessar esse valor, leia a seção deste documento sobre a variável de ambiente AIP_PREDICT_ROUTE.

Requisitos de solicitação

Se o modelo for implantado em um endpoint público compartilhado, cada solicitação de inferência precisará ter 1,5 MB ou menos. O servidor HTTP precisa aceitar solicitações de inferência que tenham o cabeçalho HTTP Content-Type: application/json e os corpos JSON com o seguinte formato:

{
  "instances": INSTANCES,
  "parameters": PARAMETERS
}

Nessas solicitações:

  • INSTANCES é uma matriz de um ou mais valores JSON de qualquer tipo. Cada valor representa uma instância em que você está fornecendo uma inferência.

  • PARAMETERS é um objeto JSON que contém qualquer parâmetro que seu contêiner exige para ajudar a disponibilizar inferências nas instâncias. A Agent Platform considera o campo parameters opcional, portanto, é possível projetar o contêiner para exigi-lo, usá-lo apenas quando fornecido ou ignorá-lo.

Saiba mais sobre os requisitos do corpo da solicitação.

Requisitos de resposta

Se o modelo for implantado em um endpoint público compartilhado, cada resposta de inferência precisará ter 1,5 MB ou menos. O servidor HTTP precisa enviar respostas com corpos JSON que atendam ao seguinte formato:

{
  "predictions": INFERENCES
}

Nessas respostas, substitua INFERENCES por uma matriz de valores JSON que representam as inferências geradas pelo contêiner para cada INSTANCES na solicitação correspondente.

Depois que o servidor HTTP enviar essa resposta, a Agent Platform adicionará um deployedModelId campo à resposta antes de retorná-la ao cliente. Esse campo especifica qual DeployedModel em um Endpoint está enviando a resposta. Saiba mais sobre o formato do corpo da resposta.

Rotas de inferência personalizadas

Se o servidor de modelos implementar várias rotas de inferência, recomendamos usar a API Invoke para acessar várias rotas de inferência. A API Invoke pode ser ativada durante o upload do modelo definindo o campo Model.containerSpec.invokeRoutePrefix como "/*". Depois de implantada, uma solicitação HTTP para a rota /invoke/foo/bar será encaminhada como para o caminho /foo/bar do servidor de modelos. Para saber mais detalhes, leia Como usar rotas personalizadas arbitrárias.

Requisitos de publicação de imagens de contêiner

É preciso enviar a imagem do contêiner ao Artifact Registry para usá-la com a Agent Platform. Saiba como enviar uma imagem de contêiner para o Artifact Registry.

Especificamente, é necessário enviar a imagem do contêiner a um repositório que atenda aos seguintes requisitos de local e permissões.

Local

Quando você usa o Artifact Registry, o repositório precisa usar uma região que corresponda ao endpoint regional em que você planeja criar um Model. Por exemplo, se você planeja criar um Model no endpoint us-central1-aiplatform.googleapis.com, o nome completo da imagem do contêiner precisa começar com us-central1-docker.pkg.dev/. Não use um repositório multirregional para sua imagem de contêiner.

Permissões

A Agent Platform precisa ter permissão para extrair a imagem do contêiner quando você cria um Model. Especificamente, o agente de serviço da Agent Platform do seu projeto precisa ter as permissões do papel de leitor do Artifact Registry (roles/artifactregistry.reader) para o repositório da imagem do contêiner.

A Agent Platform usa o agente de serviço da Agent Platform para que seu projeto interaja com outros Google Cloud serviços. Essa conta de serviço tem o endereço de e-mail service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com, em que PROJECT_NUMBER é substituído pelo número do projeto da Agent Platform.

Se você enviou a imagem do contêiner para o mesmo Google Cloud projeto em que está usando a Agent Platform, não é necessário configurar nenhuma permissão. As permissões padrão concedidas ao agente de serviço do Agent Platform são suficientes.

Por outro lado, se você enviou a imagem do contêiner para um Google Cloud projeto diferente do que está usando a plataforma de agentes, você deve conceder o papel de leitor do Artifact Registry para o repositório do Artifact Registry ao agente de serviço da plataforma de agentes.

Acessar artefatos de modelos

Quando você cria um modelo personalizado Model sem um contêiner personalizado, você precisa especificar o URI de um diretório do Cloud Storage com artefatos de modelo como o campoartifactUri. Ao criar um Model com um contêiner personalizado, o fornecimento de artefatos de modelo no Cloud Storage é opcional.

Se a imagem do contêiner incluir os artefatos de modelo que você precisa para disponibilizar inferências, não será necessário carregar arquivos do Cloud Storage. No entanto, se você fornecer artefatos de modelo especificando o campo artifactUri, o contêiner precisará carregar esses artefatos quando começar a ser executado. Quando a Agent Platform inicia o contêiner, ela define a variável de ambiente AIP_STORAGE_URI como um URI do Cloud Storage que começa com gs://. A instrução ENTRYPOINT do contêiner pode fazer o download do diretório especificado por esse URI a fim de acessar os artefatos de modelo.

Lembre-se que o valor da variável de ambiente AIP_STORAGE_URI não é idêntico ao URI do Cloud Storage especificado no campo artifactUri ao criar o Model. Em vez disso, AIP_STORAGE_URI aponta para uma cópia do diretório de artefatos de modelo em um bucket do Cloud Storage diferente, que o Agent Platform gerencia. O Agent Platform preenche esse diretório quando você cria um Model. Não é possível atualizar o conteúdo do diretório. Se você quiser usar os novos artefatos de modelo, crie um novo Model.

A conta de serviço que seu contêiner usa por padrão tem permissão para ler esse URI.

Por outro lado, se você especificar uma conta de serviço personalizada ao implantar o Model em um Endpoint, a Agent Platform concederá automaticamente a conta de serviço especificada o papel Leitor de objetos do Storage (roles/storage.objectViewer) para o bucket do Cloud Storage do URI.

Use qualquer biblioteca compatível com o Application Default Credentials (ADC) para carregar os artefatos de modelo. Não será necessário configurar explicitamente a autenticação.

Variáveis de ambiente disponíveis no contêiner

Durante a execução, a instrução ENTRYPOINT do contêiner pode referir-se a variáveis de ambiente que você configurou manualmente, bem como às definidas automaticamente pela Agent Platform. Nesta seção, descrevemos cada maneira de definir variáveis de ambiente e fornecemos detalhes sobre as variáveis definidas automaticamente pela Agent Platform.

Variáveis definidas na imagem do contêiner

Para definir variáveis de ambiente ao criar a imagem do contêiner, use a instrução ENV do Docker. Não defina variáveis de ambiente que comecem com o prefixo AIP_.

A instrução ENTRYPOINT do contêiner pode usar essas variáveis de ambiente, mas não é possível se referir a elas em nenhum dos campos de API do Modelfields.

Variáveis definidas pela Agent Platform

Quando a Agent Platform começa a executar o contêiner, ela define as variáveis de ambiente a seguir no ambiente de contêiner. Cada variável começa com o prefixo AIP_. Não defina manualmente variáveis de ambiente que usem esse prefixo.

A instrução ENTRYPOINT do contêiner pode acessar essas variáveis. Para saber quais campos da API do Agent Platform também podem referenciar essas variáveis, leia a referência da API para ModelContainerSpec.

Nome da variável Valor padrão Como configurar o valor Detalhes
AIP_ACCELERATOR_TYPE Não definido Ao implantar um Model como um DeployedModel em um recurso Endpoint, defina o campo dedicatedResources.machineSpec.acceleratorType. Se for aplicável, essa variável especificará o tipo de acelerador usado pela instância da máquina virtual (VM) em que o contêiner está sendo executado.
AIP_DEPLOYED_MODEL_ID Uma string de dígitos identificando o DeployedModel em que o Model deste contêiner foi implantado. Não configurável Esse valor é o campo id do DeployedModel.
AIP_ENDPOINT_ID Uma string de dígitos identificando o Endpoint em que o Model do contêiner foi implantado. Não configurável Esse valor é o último segmento do campo name da Endpoint (depois de endpoints/).
AIP_FRAMEWORK CUSTOM_CONTAINER Não configurável
AIP_HEALTH_ROUTE /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL

Nesta string, substitua ENDPOINT pelo valor da variável AIP_ENDPOINT_ID e substitua DEPLOYED_MODEL pelo valor da variável AIP_DEPLOYED_MODEL_ID.		 Ao criar um Model, defina o containerSpec.healthRoute campo. Essas variáveis especificam o caminho HTTP no contêiner que a Agent Platform envia verificações de integridade para.
AIP_HTTP_PORT 8080 Ao criar um Model, defina o campo containerSpec.ports. A primeira entrada neste campo se torna o valor de AIP_HTTP_PORT. A Agent Platform envia verificações de atividade e integridade e solicitações de inferência a essa porta no contêiner. O servidor HTTP do seu contêiner precisa detectar solicitações nessa porta.
AIP_MACHINE_TYPE Nenhum padrão. Precisa ser configurado. Ao implantar um Model como um DeployedModel em um recurso Endpoint, defina o campo dedicatedResources.machineSpec.machineType. Essa variável especifica o tipo de VM em que o contêiner está sendo executado.
AIP_MODE PREDICTION Não configurável Essa variável significa que o contêiner está em execução na Agent Platform para disponibilizar inferências on-line. É possível usar essa variável de ambiente para adicionar lógica personalizada ao seu contêiner, para que ele possa ser executada em vários ambientes de computação. Porém, use apenas caminhos de código específicos quando executá-lo na Agent Platform.
AIP_MODE_VERSION 1.0.0 Não configurável Essa variável significa a versão dos requisitos do contêiner personalizado (este documento) que a Agent Platform espera que sejam atendidos pelo contêiner. Este documento é atualizado de acordo com o controle de versões semântico.
AIP_MODEL_NAME Valor da variável AIP_ENDPOINT_ID. Não configurável Consulte a linha AIP_ENDPOINT_ID. Essa variável existe por motivos de compatibilidade.
AIP_PREDICT_ROUTE /v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict

Nesta string, substitua ENDPOINT pelo valor da variável AIP_ENDPOINT_ID e substitua DEPLOYED_MODEL pelo valor da variável AIP_DEPLOYED_MODEL_ID.		 Ao criar um Model, defina o containerSpec.predictRoute campo. Essa variável especifica o caminho HTTP no contêiner para o qual a Agent Platform encaminha solicitações de inferência.
AIP_PROJECT_NUMBER O número doprojeto em que você está usando a Agent Platform. Google Cloud Não configurável
AIP_STORAGE_URI
  • Se você não definir o campo artifactUri ao criar um Model: uma string vazia
  • Se você definir o campo artifactUri ao criar um Model: um URI do Cloud Storage (começando com gs://) que especifica um diretório em um bucket gerenciado pela Agent Platform
 Não configurável Essa variável especifica o diretório que contém uma cópia dos artefatos de modelo, se aplicável.
AIP_VERSION_NAME Valor da variável AIP_DEPLOYED_MODEL_ID. Não configurável Consulte a linha AIP_DEPLOYED_MODEL_ID. Essa variável existe por motivos de compatibilidade.

Variáveis definidas no recurso Model

Ao criar um Model, é possível definir mais variáveis de ambiente no campo containerSpec.env.

A instrução ENTRYPOINT do contêiner pode acessar essas variáveis. Para saber quais campos da API do Agent Platform também podem referenciar essas variáveis, leia a referência da API para ModelContainerSpec.

A seguir