IBM Bob

Operações e solução de problemas

Monitore, mantenha e solucione problemas de implantações do Model Gateway, incluindo atualizações de configuração do modelo, rotação de credenciais, monitoramento de integridade, coleta de logs e resolução de problemas comuns de conectividade e autenticação.

Após a implantação, o gerenciamento operacional contínuo do Model Gateway ajuda a garantir acesso confiável aos modelos de IA configurados e minimiza as interrupções do serviço. Os administradores podem revisar configurações de modelo ativas, atualizar credenciais de provedores, rotacionar segredos, monitorar a integridade do gateway e coletar informações de diagnóstico quando ocorrem problemas.

Visualizando modelos configurados

Há dois níveis para visualizar modelos — o que está na configuração e o que bob-inference efetivamente carregou em runtime.
  • Nível de configuração — recupere a configuração atual do model gateway a partir do ConfigMap de inferência: 
    oc get cm bob-inference-config -n <bob-namespace> -o yaml | yq '.data."config.yaml"'
    •
  • Nível de runtime — o que bob-inference registrou e está ativamente roteando: consulte o endpoint /v1/models diretamente (consulte Validar a conectividade do modelo).
    •
Nota:

O endpoint de runtime /v1/models lista apenas modelos onde exposed: true. O arquivo de configuração é a única forma de ver o conjunto completo de modelos configurados.

Atualizando credenciais de provedores

As credenciais são montadas como variáveis de ambiente a partir de bob.modelGateway.secrets. Atualizá-las é uma operação em duas etapas — atualizar o valor do secret e depois reiniciar o Inference Service para usar a nova montagem.

Atualizar o secret

Edite o CR Bob e aplique o novo valor:

oc edit bob <instance-name> -n <bob-namespace>
# Update the value under bob.modelGateway.secrets

Reiniciar o Inference Service

Reinicie o Inference Service para que o novo secret seja montado:

oc rollout restart deploy/inference-service -n <bob-namespace>
oc rollout status deploy/inference-service -n <bob-namespace>
Aviso:

O pod do Inference Service deve ser reiniciado após qualquer atualização de secret. As alterações na configuração do modelo (adicionar ou remover modelos, alterar base_url) e as alterações de secret podem ser agrupadas em uma única atualização do CR seguida de uma reinicialização.

Rotacionando segredos

A rotação de segredos segue o mesmo padrão de uma atualização de credenciais, com cuidado adicional quanto ao timing para evitar downtime.

Sequência de rotação com zero downtime recomendada:
  1. Atualize bob.modelGateway.secrets com o novo valor de credencial.
    2.
  2. Reinicie o Inference Service: oc rollout restart deploy/inference-service -n <bob-namespace>.
    3.
  3. Confirme que a nova credencial está funcionando usando o teste de inferência de Verificação pós-instalação.
    4.
  4. Revogue a credencial antiga no lado do provedor somente após o pod ser confirmado como saudável.
    5.

Notas específicas do provedor:
  • openai_compatible / chaves de API — a nova chave entra em vigor imediatamente na reinicialização. É seguro revogar a chave antiga após o pod estar saudável.
    •
  • bedrock — certifique-se de que a nova chave de acesso IAM esteja ativa na AWS antes de reiniciar. A propagação do IAM pode levar alguns segundos.
    •
  • vertex — gere e codifique em base64 a nova chave de conta de serviço, atualize o secret, reinicie e verifique, depois exclua a chave antiga no GCP.
    •
  • ca_cert_pem — para renovação de certificado, verifique se o novo certificado não está expirado antes de aplicar. Consulte Validação de certificado TLS.
    •

Monitorando a integridade do gateway

Contagem de reinicializações do pod — um número crescente de reinicializações é um sinal precoce de uma falha de inicialização recorrente (montagem de secret inválida, erro de análise de configuração):

 
oc get pods -n <bob-namespace> -l app=bob-inference \
  -o custom-columns='NAME:.metadata.name,RESTARTS:.status.containerStatuses[0].restartCount'

Probes de liveness e readiness — verifique a configuração e o status atual dos probes:

 
oc describe deploy/bob-inference -n <bob-namespace> | grep -A 10 "Liveness\|Readiness"

Verificação periódica de integridade — o endpoint /v1/models serve como uma verificação simples de liveness. Se ele retornar uma lista válida de modelos, o gateway está ativo. Isso pode ser monitorado a partir de uma ferramenta de monitoramento ou um cron job dentro do cluster.

Coletando logs e diagnósticos

Logs para uma janela de tempo específica (mais útil ao investigar um incidente relatado):

 
oc logs -n <bob-namespace> deploy/bob-inference \
  --since-time="2025-01-01T12:00:00Z" > bob-inference.log

Logs de uma instância anterior do pod (se o pod reiniciou e os logs de falha foram perdidos):

 
oc logs -n <bob-namespace> deploy/bob-inference --previous

Bundle de diagnóstico completo para suporte:

 
oc describe pod -n <bob-namespace> -l app=bob-inference >> diagnostics.txt
oc get events -n <bob-namespace> --sort-by='.lastTimestamp' >> diagnostics.txt
oc logs -n <bob-namespace> deploy/bob-inference --since=1h >> diagnostics.txt
Nota:

O bundle de diagnóstico contém nomes de variáveis de ambiente do pod, mas não valores de secret (os secrets são montados, não impressos nos logs). Revise os logs em busca de qualquer saída acidental de credenciais antes de enviar ao suporte.

Solucionando problemas de conectividade e autenticação

Modelo não aparece em /v1/models
  1. Verifique se exposed: false está definido — se sim, este é o comportamento esperado.
    2.
  2. Verifique os logs de inicialização em busca de um erro de registro para aquele model_name.
    3.
  3. Verifique o bloco do provedor — base_url, ID do model e credenciais corretos.
    4.

401 Unauthorized em solicitações de inferência
  1. Confirme se o valor do secret em bob.modelGateway.secrets está correto e atualizado.
    2.
  2. Confirme se a referência env.<VAR> na configuração do modelo corresponde exatamente ao nome da chave do secret (sensível a maiúsculas/minúsculas).
    3.
  3. Reinicie o Inference Service e tente novamente — o secret pode ter sido atualizado sem uma reinicialização.
    4.
  4. Teste a credencial fora de banda. Consulte Validação de autenticação.
    5.

502 Bad Gateway ou connection refused
  1. Confirme se o endpoint do modelo está ativo e acessível a partir do cluster. Consulte Teste de conectividade.
    2.
  2. Verifique problemas com base_url — barras no final, esquema incorreto (http vs https), porta incorreta.
    3.
  3. Verifique se houve mudanças nas políticas de rede que possam ter bloqueado o tráfego de saída desde a instalação.
    4.

certificate signed by unknown authority
  1. Confirme se ca_cert_pem está definido e referencia uma variável de ambiente válida.
    2.
  2. Confirme se a variável de ambiente está presente em bob.modelGateway.secrets.
    3.
  3. Verifique se o certificado não está expirado: openssl x509 -noout -dates.
    4.
  4. Confirme se o certificado cobre o hostname do endpoint verificando os Subject Alternative Names.
    5.

Pod do Inference Service em CrashLoopBackOff
  1. Verifique os logs da instância anterior: oc logs --previous.
    2.
  2. Procure erros de análise de configuração — YAML malformado na configuração do model gateway.
    3.
  3. Procure montagens de secret ausentes na seção Events: oc describe pod.
    4.
  4. Confirme se o YAML da configuração do model gateway é válido antes de reaplicar.
    5.
Como está este tópico?

Nesta página

Visualizando modelos configuradosAtualizando credenciais de provedoresAtualizar o secretReiniciar o Inference ServiceRotacionando segredosMonitorando a integridade do gatewayColetando logs e diagnósticosSolucionando problemas de conectividade e autenticação