在 Oracle 云基础设施上部署生产就绪型 NVIDIA AI-Q Blueprint

在过去两年中，AI 智能体发生了巨大变化。第一个问题一次只能回答一个问题。接下来是多轮聊天，模型可以在会议中保留一些上下文。如今，我们拥有长距智能体。系统可以规划多个步骤、在子智能体之间分配工作、在长期任务中保持上下文，以及在安全的沙盒中运行工具。

NVIDIA AI-Q Blueprint 是此类智能体的开源参考。它基于 LangChain Deep Agents 和 NVIDIA NeMo Agent Toolkit 构建。您可以将其用于快速引用答案，或用于包含来源的更长的研究报告。

本文将介绍如何使用 Terraform 在 Oracle Cloud Infrastructure (OCI) 上部署 AI-Q 2.0 以创建 OCI 资源，并使用 Helm 在 OKE 上安装工作负载。最后，您将在自己的 OCI 租户中拥有一个正在运行的 AI-Q 端点，并且有一条命令可以在完成后将其全部关闭。

受众： 熟悉 Kubernetes、Terraform 和 shell 的开发者和平台工程师，以及希望在 OCI (而非笔记本电脑) 上运行 AI-Q 的开发者和平台工程师。

您将学到的内容： AI-Q 的多智能体架构如何映射到 OCI 服务，以及从头到尾调配、部署和打开蓝图的确切命令。

有关多智能体架构（如意图路由器、浅层研究智能体、深度智能体、规划子智能体、研究人员子智能体）的更多背景信息，请参阅AI-Q产品页面和NeMo Agent Toolkit文档。

预备知识

确保您拥有：

• OCI 租户访问权限，您可以部署在一个分区中，并且有足够的服务限制：
  • OKE：一个增强型集群和一个节点池
  • 块容量：至少 10 GB (由 OKE CSI 驱动为集群内的 PostgreSQL 动态调配)
  • 负载均衡器：一个灵活的
  • 库：一个库和秘密库
• API 密钥：
  • 来自 build.nvidia.com 的 NGC API 密钥 (格式为 nvapi-…) 用作 NVIDIA 推理密钥，并对 NGC 容器注册表 (nvcr.io) 进行身份验证。
  • tavily.com 上的 tavily API 密钥，格式为 tavily.com tvly-…。
• 本地工具： terraform 1.5 或更高版本、kubectl 1.28 或更高版本、helm 3.x 或更高版本、使用 API 签名密钥设置的 oci CLI
• 了解 Kubernetes、Helm 图表、Terraform 和 shell 的一些基本知识。 拥有 LangChain 或 NeMo Agent Toolkit 的经验很棒，但不是必需的。

架构概述

AI-Q 采用多智能体设计。意图路由器会读取每个用户查询，并将其发送到正确的工作流。

该蓝图旨在实现可扩展性。每个层 (模型、工具、RAG 后端、子代理、评估器) 都可以通过 YAML 配置或 NeMo Agent Toolkit 插件系统进行交换。我们将在本系列的第 2 和第 3 部分中使用这种可扩展性。

OCI 部署架构

此部署使用 Terraform 作为 OCI 资源，并使用 Helm 作为 Kubernetes 工作负载。这样可以在基础架构和应用程序之间进行清晰划分，一个 terraform destroy 就足以在之后删除所有内容。

图 2. OCI 上的 AI-Q 部署。Terraform 会创建 VCN、OKE 集群、负载均衡器和 Vault。Helm 会在 OKE 上安装 AI-Q 后端、前端和 PostgreSQL 工作负载。

Helm 图表在 OKE 上安装了三个工作负载：

• 后端 (aiq-backend) ：基于 FastAPI 的代理服务器，运行 AI-Q 工作流。
• 前端 (aiq-frontend) ：在 NodePort 30080 上公开的 next.js Web UI。
• PostgreSQL (aiq-postgres) ：用于作业存储、检查点和摘要的集群内数据库。

部署步骤

git clone https://github.com/oracle-samples/ai-q.git
cd ai-q/oke-samples/aiq-2.0

总时间：约 20 到 25 分钟。完整参考资料请参见 aiq-2.0/README.md。

第 1 步：配置 Terraform 变量

复制示例文件，并使用您的租户详细信息对其进行编辑：

cd deploy/terraform
cp terraform.tfvars.example terraform.tfvars

至少在 terraform.tfvars 中设置以下变量：

• tenancy_ocid、compartment_id、region (例如 us-chicago-1)
• user_ocid、fingerprint、private_key_path (与您的  ~/.oci/config 值相同)
• db_admin_password，用于引导存储在 OCI Vault 中的集群内 PostgreSQL。
• nvidia_api_key，你的 NVIDIA NGC 密钥从 build.nvidia.com。用于推理以及从 nvcr.io 提取容器镜像。
• tavily_api_key 是 tavily.com 提供的用于网页搜索的 TAVILY 密钥。

第 2 步：创建基础架构

初始化提供程序、查看计划并申请：

terraform init
terraform plan
terraform apply

这大约需要 10 到 15 分钟。Terraform 会创建 VCN、OKE 集群、负载均衡器和 Vault，并使用静态加密的 NGC 和 Davily API 密钥。

检查：terraform output 应显示 oke_cluster_id 和 lb_public_ip 的值。如果其中任一选项为空，则再次运行 terraform apply，可以安全地重复此应用。

截取下一步所需的两个值：

export OKE_CLUSTER_ID="$(terraform output -raw oke_cluster_id)"
export LB_PUBLIC_IP="$(terraform output -raw lb_public_ip)"

第 3 步：安装 NGC Helm 图表中的 AI-Q

图表和容器镜像发布在 NGC 上，因此无需在本地构建任何内容。我们将 kubectl 指向新的 OKE 集群，创建图表使用的机密，然后创建 helm pull 和 helm install。

3a。为 OKE 集群配置 kubectl

# configure kubectl for the OKE cluster

oci ce cluster create-kubeconfig \
  --cluster-id "$OKE_CLUSTER_ID" \
  --file ~/.kube/config \
  --region us-ashburn-1 \
  --token-version 2.0.0 \
  --kube-endpoint PUBLIC_ENDPOINT

# sanity check. nodes should be ready

kubectl get nodes

3b。导出 API 密钥

重复使用您在 terraform.tfvars 中输入的相同 NGC 和 Tabily 密钥。NGC 密钥具有双重功能。它既是推理密钥，也是 nvcr.io 拉取凭据。

export NGC_API_KEY="nvapi-..."         # from build.nvidia.com
export TAVILY_API_KEY="tvly-..."       # from tavily.com
export DB_USER_PASSWORD="<same value as db_admin_password in Step 1>"

3c。创建命名空间和秘密

kubectl create namespace ns-aiq --dry-run=client -o yaml | kubectl apply -f -

# Application credentials (NVIDIA + Tavily inference, Postgres user)
kubectl create secret generic aiq-credentials -n ns-aiq \
  --from-literal=NVIDIA_API_KEY="$NGC_API_KEY" \
  --from-literal=TAVILY_API_KEY="$TAVILY_API_KEY" \
  --from-literal=DB_USER_NAME="aiq" \
  --from-literal=DB_USER_PASSWORD="$DB_USER_PASSWORD"

# Image-pull secret for nvcr.io (NGC container registry)
kubectl create secret docker-registry ngc-secret -n ns-aiq \
  --docker-server=nvcr.io \
  --docker-username='$oauthtoken' \
  --docker-password="$NGC_API_KEY"

3d。从 NGC 提取并安装图表

cd ../helm     # from deploy/terraform to deploy/helm

helm pull https://helm.ngc.nvidia.com/nvidia/blueprint/charts/aiq2-web-2.0.0.tgz \
  --username='$oauthtoken' \
  --password="$NGC_API_KEY"

helm upgrade --install aiq aiq2-web-2.0.0.tgz \
  -n ns-aiq \
  --wait --timeout 10m \
  -f values-oci-ngc.yaml

OCI overlay (values-oci-ngc.yaml) 有意地设计得很小，它只将前端服务固定到 NodePort 30080 ( OCI 负载均衡器健康检查端口) ，并命名为 ngc-secret image-pull secret。图像资源库、Postgres init SQL 和动态置备的 10 Gi 块卷 PVC 都来自图表本身的默认设置。

检查：3 到 5 分钟后，kubectl get pods -n ns-aiq 应在 Running 状态下显示 aiq-backend、aiq-frontend 和 aiq-postgres Pod。

第 4 步：开放 AI-Q

在步骤 2 中，您的 shell 中已包含 LB IP：

echo "http://$LB_PUBLIC_IP"

如果您此后打开了新 shell，请从 Terraform 中重新导出：

cd ../terraform

export LB_PUBLIC_IP="$(terraform output -raw lb_public_ip)"

echo "http://$LB_PUBLIC_IP"

在浏览器中打开 http://<lb_public_ip>。您应能看到 AI-Q 前端。

先尝试一个简单的问题，例如“什么是 NeMo Agent Toolkit？”以确认路由是否有效。然后尝试更深入的方法，例如“按基准分数和成本比较排名前三的开源深度研究智能体”，以了解深度智能体的实际应用。

故障排除

• terraform apply 在创建 OKE 时失败，并出现配额错误。请查看舱室的服务限制，了解“集群数量”和“节点数量”，如果需要，还可以要求提供更多的配额。
• Pod 卡在 ImagePullBackOff 中。在第 3c 步中运行 kubectl create secret docker-registry ngc-secret 命令时，检查是否已创建图像提取密钥 (kubectl get secret -n ns-aiq) ，以及您的 NGC_API_KEY 是否正确。如要旋转，请先删除密钥并重新创建，然后再选择 kubectl rollout restart deployment -n ns-aiq aiq-backend aiq-frontend。
• postgres Pod 在 Pending 中停留 2 分钟以上。未动态调配块状体积的 PVC。运行 kubectl describe pvc -n ns-aiq。典型的原因是 OKE CSI 驱动未运行、默认的 StorageClass 缺失或块卷配额不足。使用 kubectl get sc 和舱室的块卷服务限制检查存储类，检查存储类。
• 负载均衡器 IP 返回为 null。OCI 可能需要一到两分钟才能完成 LB，在 Terraform 之后。再次运行 terraform refresh，然后再次运行 terraform output lb_public_ip。
• 前端加载，但查询返回 500。看看 kubectl logs -n ns-aiq deploy/aiq-backend。最常见的原因是您在第 3c 步创建的 aiq-credentials 密钥中的 NVIDIA_API_KEY 或 TAVILY_API_KEY 错误或缺失。

了解详情

现在，您已在 OCI 上部署了一个有效的 AI-Q 2.0，并且有一条命令 (terraform destroy) 可在完成后将其彻底删除。在进一步操作时，请记住以下几点：

• 成本：OKE 节点池和负载均衡器在运行时会不断计算成本。在实验之间销毁堆栈，或将节点池缩小到零。
• 机密: Terraform 在调配时 (用于审核和灾难恢复) 将 NGC 和 Tabily 密钥存储在 OCI Vault 中，但运行中的 Pod 会从您在第 3c 步中创建的 aiq-credentials Kubernetes 机密中读取这些密钥。若要旋转，请删除并使用新值重新创建该密钥，然后选择 kubectl rollout restart deployment -n ns-aiq aiq-backend。单独编辑 terraform.tfvars 无法到达 POD。
• 可扩展性： 您刚刚部署的所有内容均由 YAML 和 NeMo Agent Toolkit 插件系统驱动。交换 LLM、添加子代理或插入新的 RAG 后端是配置更改，而非重写。

克隆 OCI 资源库中的 AI-Q 并在 NVIDIA 开发者论坛 上分享您构建的解决方案和解决的问题。