本地AI Agent迁移至OpenShift生产化实战

一、核心概述

本教程展示了如何将本地运行的 AI Agent（集成计算器、网页搜索、GitHub MCP 三大工具）从个人笔记本迁移到 Red Hat OpenShift AI 集群，实现真正的多用户并发与生产级部署。核心思路是：保持 Agent 代码不变，仅替换模型服务（从 Ollama 本地切换到 vLLM）并将整个系统容器化、部署到 OpenShift。这样既能利用 vLLM 的高并发推理能力，又能通过 OpenShift AI 的模型管理、API Key 鉴权、日志可视化等企业特性，实现安全、可扩展的 AI 服务。

二、实操步骤与核心流程详解

1. 准备模型服务（vLLM）

1. 登录 OpenShift 控制台，进入 AI Hub → Models。
2. 选择 "Add Model"，在 Model Source 中填入 HuggingFace 模型 URI（如 huggingface://Qwen/Qwen3-7B），支持多种存储后端。
3. 配置硬件（GPU/CPU）和运行时（Python 3.11 + vLLM），点击 Deploy。
4. 部署完成后，记录 内部访问 URL、外部访问 URL 与 API Key，后续将在 .env 中使用。

2. 修改 Agent 配置

• 打开项目根目录的 .env 文件，将原先指向本地 Ollama 的地址改为 OpenShift 提供的 vLLM URL，例如：

  MODEL_ENDPOINT=https://vllm-cluster.example.com/v1/chat/completions
  MODEL_API_KEY=xxxxxxxxxxxx
  MODEL_ID=qwen3-7b-vllm
  

• 这一步是唯一的代码改动，业务逻辑保持不变。

3. 容器化 Agent

1. 登录 OpenShift 集群：在 OpenShift 控制台获取 oc login 命令，粘贴到终端完成身份验证。
2. 构建镜像（支持 Podman 或 Docker）：

   podman build -t quay.io/<your-namespace>/ai-agent:latest .
   

3. 推送镜像到内部镜像仓库：

   podman push quay.io/<your-namespace>/ai-agent:latest
   

4. 项目已提供 Makefile，可一键完成构建、推送与部署：

   make build   # 构建镜像
   make push    # 推送至镜像仓库
   make deploy  # 使用 OpenShift YAML 部署 Pod
   

4. 部署到 OpenShift

• make deploy 会创建一个 Deployment、Service 与 Route，使 Agent 与模型服务在同一命名空间内相互调用。
• 部署成功后，可在 OpenShift 控制台的 Workloads → Pods 查看 Pod 状态，确保 ai-agent 与 vllm-model 均处于 Running。

5. 功能验证

• 通过 OpenShift AI 提供的 Playground（或直接调用外部 URL）发送请求，测试三大工具：
  1. 网页搜索：输入查询词，Agent 调用自定义搜索工具返回结果。
  2. 数学计算：发送算式，Calculator 返回精确答案。
  3. GitHub MCP：读取、创建 Issue，验证 Agent 能在集群内成功调用 GitHub API。
• 所有日志均可在 OpenShift AI 的 Observability → Logs 中实时查看，便于调试与审计。

三、实战技巧与核心小结

• 保持代码不变：通过环境变量切换模型端点，实现“一次编码，多处运行”。
• vLLM 并发优势：相较于 Ollama，vLLM 在同一模型上支持数十甚至上百并发请求，适合团队协作。
• 安全建议：
  • 为 Agent Pod 设置 ResourceQuota 与 LimitRange，防止单实例占满节点资源。
  • 使用 OpenShift RBAC 为不同团队分配独立的 ServiceAccount，限制对模型 API Key 的访问范围。
  • 开启 NetworkPolicy，仅允许 Agent 与 vLLM、GitHub MCP 之间的网络流量。
• CI/CD 集成：将 make build/push/deploy 写入 GitHub Actions，实现代码提交即自动部署到测试或生产环境。
• 监控与告警：利用 OpenShift Prometheus 与 Grafana 监控模型推理 latency、Pod CPU/Memory 使用率，及时发现性能瓶颈。

核心结论：只需修改配置、容器化并利用 OpenShift AI 的模型服务与平台能力，即可把本地 AI Agent 快速升级为企业级、可扩展、可监控的生产服务，为团队协作与业务落地提供坚实基础。