监控、维护和排查模型网关部署问题，包括模型配置更新、凭证轮换、健康监控、日志收集以及常见连接和身份验证问题的解决方案。

部署后，对模型网关进行持续的运维管理有助于确保对已配置 AI 模型的可靠访问并最小化服务中断。管理员可以查看活跃的模型配置、更新提供商凭证、轮换 Secret、监控网关健康状况，并在出现问题时收集诊断信息。

查看已配置的模型

查看模型有两个层级——配置中的内容以及 bob-inference 在运行时实际加载的内容。

配置层级 — 从推理 ConfigMap 检索当前模型网关配置：

oc get cm bob-inference-config -n <bob-namespace> -o yaml | yq '.data."config.yaml"'

运行时层级 — bob-inference 已注册并正在主动路由的内容：

oc exec -n <bob-namespace> deploy/bob-gateway -- \
  curl -sk https://bob-inference.<bob-namespace>.svc.cluster.local:7330/v1/model/info | jq .

注意：

运行时 /v1/model/info 端点只列出 exposed: true 的模型。配置文件是查看全部已配置模型的唯一途径。

更新提供商凭证

凭证存储在 config.yaml 中的 bob.modelGateway.secrets 下。使用 bobctl update-model-config --update-secrets 将更新后的凭证推送到集群。

更新凭证

在 config.yaml 的 bob.modelGateway.secrets 下更新凭证。

将更新后的 Secret 推送到集群

bobctl update-model-config --update-secrets

ibm-bob-operator 会自动协调 bob-inference 部署并挂载新的 Secret。

提示：

如果同时更新模型配置文件和凭证，可以使用一条命令同时推送两者：

bobctl update-model-config --model-config ./my-model-config.yaml --update-secrets

轮换 Secret

Secret 轮换遵循与凭证更新相同的模式，但需要额外注意时序以避免停机。

推荐的零停机轮换顺序：

在 config.yaml 中使用新的凭证值更新 bob.modelGateway.secrets。

将新的 Secret 推送到集群：bobctl update-model-config --update-secrets。

重启推理服务以应用新的 Secret：

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

使用安装后验证中的推理测试确认新凭证正常工作。

仅在部署确认健康后，才在提供商侧撤销旧凭证。

提供商特定说明：

openai_compatible / API 密钥 — 更新 Secret 后新密钥立即生效。部署健康后可安全撤销旧密钥。

bedrock — 运行 update-model-config 前确保新 IAM 访问密钥在 AWS 中已激活。IAM 传播可能需要几秒钟。

vertex — 生成并 base64 编码新的服务账号密钥，更新 config.yaml，运行 bobctl update-model-config --update-secrets，验证，然后在 GCP 中删除旧密钥。

ca_cert_pem — 证书续期时，在应用前验证新证书未过期。请参阅 TLS 证书验证。

监控网关健康状况

Pod 重启次数 — 不断上升的重启次数是频繁启动失败（错误的 Secret 挂载、配置解析错误）的早期信号：

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

存活探针和就绪探针 — 检查当前探针配置和状态：

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

定期健康检查 — /v1/model/info 端点可作为简单的存活检查。如果它返回有效的模型列表，网关即处于运行状态。可从集群内部的监控工具或 cron 任务轮询此端点。

收集日志和诊断信息

特定时间窗口的日志（调查已报告事件时最有用）：

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

来自上一个 pod 实例的日志（如果 pod 已重启且故障日志已丢失）：

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

提交给支持团队的完整诊断包：

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

注意：

诊断包包含 pod 环境变量名称，但不包含 Secret 值（Secret 已挂载，不会打印到日志中）。发送给支持团队之前，请检查日志中是否有意外的凭证输出。

排查连接和身份验证问题

模型未出现在 /v1/model/info 中

检查是否设置了 exposed: false——如果是，这是预期行为。

在启动日志中查找该 model_name 的注册错误。

验证提供商块——正确的 base_url、model ID 和凭证。

推理请求返回 401 Unauthorized

确认 bob.modelGateway.secrets 中的 Secret 值正确且为最新。

确认模型配置中的 env.<VAR> 引用与 Secret 密钥名称完全匹配（区分大小写）。

重启推理服务并重试——Secret 可能已更新但未重启。

带外测试凭证。请参阅身份验证验证。

502 Bad Gateway 或 connection refused

确认模型端点处于运行状态且从集群可访问。请参阅连接测试。

检查 base_url 问题——尾部斜杠、错误的方案（http 与 https）、错误的端口。

检查自安装以来可能阻止出站流量的网络策略更改。

certificate signed by unknown authority

确认 ca_cert_pem 已设置并引用了有效的环境变量。

确认该环境变量存在于 bob.modelGateway.secrets 中。

验证证书未过期：openssl x509 -noout -dates。

通过检查主题备用名称确认证书覆盖了端点的主机名。

推理服务 pod 处于 CrashLoopBackOff

检查上一个实例的日志：oc logs --previous。

查找配置解析错误——模型网关配置中格式错误的 YAML。

在 Events 部分查找缺失的 Secret 挂载：oc describe pod。

重新应用之前确认模型网关配置 YAML 有效。

运维与故障排除