Resolver problemas de implantação de um agente

Neste documento, mostramos como resolver erros que podem ocorrer ao implantar um agente.

Erros no modelo predefinido

Ao encontrar erros no modelo LangchainAgent durante a implantação, isso pode ser devido a um dos problemas nesta seção.

Erros internos do servidor

Problema:

Você recebe uma mensagem de erro semelhante a esta:

InternalServerError: 500 Revision XXX is not ready and cannot serve traffic.

Infelizmente, esse é um erro geral relacionado a problemas com o contêiner no ambiente de execução, e a causa possível pode consistir em muitos erros diferentes.

Causas possíveis:

  • Estado sujo em LangchainAgent. Isso pode acontecer quando .set_up() é chamado em um LangchainAgent antes da implantação do agente.
  • Versões de pacote inconsistentes. Isso pode acontecer quando os pacotes instalados no ambiente de desenvolvimento são diferentes daqueles instalados no ambiente remoto no Vertex AI Agent Engine.

Soluções recomendadas:

  • Estado sujo em LangchainAgent. Crie outra instância de LangchainAgent ou remova agent.set_up() do código antes de implantar o agente.
  • Especificações de pacote inconsistentes. Consulte a seção sobre como solucionar problemas de erros de serialização.

Erros de serialização

Em geral, é importante garantir que os ambientes "local" e "remoto" estejam sincronizados ao implantar o agente. Para isso, especifique requirements= ao implantar o agente.

Quando erros ocorrem na serialização (erros relacionados a pickle ou pickling são sinônimos de erros de serialização), isso pode ser devido a um dos problemas descritos nesta seção.

Versão do Pydantic

Problema:

Você recebe uma mensagem de erro semelhante a esta:

PicklingError: Can't pickle <cyfunction str_validator at 0x7ca030133d30>: it's
not the same object as pydantic.validators.str_validator

Possível causa:

Isso pode acontecer quando a versão do pacote pydantic é anterior à 2.6.4. Para verificar a versão em uso, execute o seguinte comando no terminal:

pip show pydantic

Solução recomendada:

Atualize o pacote executando o seguinte comando no terminal:

pip install pydantic --upgrade

Execute o seguinte comando no terminal para verificar se você está usando a versão 2.6.4 ou mais recente:

pip show pydantic

No caso de uma instância de notebook (por exemplo, Jupyter, Colab ou Workbench), talvez seja necessário reiniciar o ambiente de execução para usar os pacotes atualizados.

Versão do Cloudpickle

Problema:

Você recebe uma mensagem de erro semelhante a esta:

AttributeError: Can't get attribute '_class_setstate' on <module 'cloudpickle.cloudpickle'
from '/usr/local/lib/python3.10/site-packages/cloudpickle/cloudpickle.py'>

Possível causa:

Isso pode acontecer quando a versão do pacote cloudpickle é diferente nos ambientes de desenvolvimento e de implantação. Para verificar qual versão você está usando no ambiente de desenvolvimento, execute o seguinte comando no terminal:

pip show cloudpickle

Solução recomendada:

Implante a mesma versão do Cloudpickle nos dois ambientes, como o ambiente de desenvolvimento local e o agente implantado remotamente, especificando requirements= ao implantar o agente.

Erros internos do servidor

Problema:

Você recebe uma mensagem de erro semelhante a esta:

InternalServerError: 500 Revision XXX is not ready and cannot serve traffic.

Possível causa:

Isso pode acontecer quando sys_version= é diferente do ambiente de desenvolvimento ao implantar o agente.

Solução recomendada:

Depois de implantar o agente, considere remover sys_version= dos argumentos de entrada. Se você ainda tiver problemas, envie um relatório de bug.

Erros de bucket do Cloud Storage

Em caso de erros no bucket de preparação do Cloud Storage usado no momento da implantação para coletar e fazer upload do agente, isso pode ser devido a um dos seguintes problemas:

Erros de permissão

Solução recomendada:

Para usar um bucket atual: verifique se o principal autenticado para usar a Vertex AI (você ou uma conta de serviço) tem acesso Storage Admin ao bucket e conceda permissões à conta de serviço.

Como alternativa, é possível especificar um novo bucket ao implantar o agente e o SDK vai criar o bucket com as permissões necessárias.

Se você ainda tiver problemas, envie um relatório de bug.

O subdiretório do bucket do Cloud Storage não foi criado

Problema:

Você recebe uma mensagem de erro semelhante a esta:

NotFound: 404 Can not copy from \"gs://[LOCATION]-*/agent_engine/agent_engine.pkl\" to \"gs://*/code.pkl\", check if the source object and target bucket exist.

O erro 404 ocorre quando o sistema tenta fazer uma cópia em uma pasta que não existe.

Possível causa:

Isso provavelmente se deve a um problema com a interpolação de strings em versões de google-cloud-aiplatform anteriores à 1.49.0. Isso foi corrigido em versões mais recentes. Para verificar qual versão de google-cloud-aiplatform você está usando, execute o seguinte comando no terminal:

pip show google-cloud-aiplatform

Solução recomendada:

Atualize o pacote executando o seguinte comando no terminal:

pip install google-cloud-aiplatform --upgrade

Verifique se você está usando a versão 1.49.0 ou mais recente de google-cloud-aiplatform executando o seguinte comando no terminal:

pip show google-cloud-aiplatform

No caso de uma instância de notebook (por exemplo, Jupyter, Colab ou Workbench), talvez seja necessário reiniciar o ambiente de execução para usar os pacotes atualizados.

Erros de violação do VPC-SC

Se você estiver com problemas com o VPC-SC, um dos seguintes problemas pode ser a causa:

Erros de permissão

Problema:

Você recebe uma mensagem de erro semelhante a esta:

Reasoning Engine instance REASONING_ENGINE_ID failed to start and cannot serve traffic.

ou

Request is prohibited by organization's policy.

Possível causa:

Isso provavelmente é causado pela falta de regras de entrada obrigatórias no perímetro da VPC-SC.

Solução recomendada:

Se você usar o Vertex AI Agent Engine em um ambiente do VPC-SC, será necessário criar uma regra de entrada no perímetro para permitir a entrada do agente de serviço do Reasoning Engine (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) no serviço storage.googleapis.com e no serviço artifactregistry.googleapis.com.

Erros de conta de serviço personalizada

Se você estiver com problemas nas contas de serviço, um dos seguintes problemas pode ser a causa:

Agir como conta de serviço

Problema:

Você recebe uma mensagem de erro semelhante a esta:

You do not have permission to act as service_account.

Possível causa:

Talvez você não tenha a permissão iam.serviceAccounts.actAs na conta de serviço personalizada usada para implantação. Em um sistema multiagente com várias contas de serviço personalizadas, um autor ou implantador de agente pode atuar como algumas das contas de serviço. Se você estiver usando a conta de serviço errada, esse erro é o comportamento esperado.

Além disso, esse erro pode ocorrer se a conta de serviço personalizada estiver em um projeto diferente daquele em que você implanta o agente, e a política da organização iam.disableCrossProjectServiceAccountUsage estiver aplicada no projeto da conta de serviço.

Consulte Conta de serviço personalizada entre projetos para conferir a lista completa de configurações necessárias para esse cenário.

Solução recomendada:

Verifique se você está usando a conta de serviço correta. Verifique se você tem o papel de Usuário da conta de serviço (roles/iam.serviceAccountUser) nessa conta de serviço. Se não for o caso, peça ao administrador para conceder a função a essa conta de serviço.

Se você estiver no cenário entre projetos, verifique se o projeto da conta de serviço tem a política da organização iam.disableCrossProjectServiceAccountUsage aplicada. Se for esse o caso, peça para o administrador desativar a política.

Servidor de metadados indisponível

Problema:

Você recebe uma mensagem de erro semelhante a esta:

ServiceUnavailable: 503 Getting metadata from plugin failed with error

ou

Compute Engine Metadata server unavailable due to : Could not fetch URI /computeMetadata/v1/instance/service-accounts/default/token

Possível causa:

Isso pode acontecer se a conta de serviço personalizada e o agente estiverem em projetos diferentes e o agente de serviço do mecanismo de inferência do AI Platform não tiver a permissão iam.serviceAccounts.getAccessToken na conta de serviço personalizada.

Consulte Conta de serviço personalizada entre projetos para conferir a lista completa de configurações necessárias para esse cenário.

Solução recomendada:

Peça ao administrador para conceder ao agente de serviço do mecanismo de raciocínio do AI Platform do projeto do agente o papel de Criador de token da conta de serviço (roles/iam.serviceAccountTokenCreator) na conta de serviço personalizada.

O agente de serviço do mecanismo de inferência do AI Platform precisa estar no mesmo projeto usado para implantar o agente. A vinculação do IAM da concessão de função precisa estar no projeto em que a conta de serviço personalizada reside.

Recursos de suporte

Se o problema ainda não for resolvido, consulte nosso guia de suporte para receber ajuda.