За последние два года ландшафт искусственного интеллекта претерпел радикальные изменения. Мы перешли от простых чат-ботов, способных ответить на один вопрос за раз, к сложным многошаговым системам, которые могут планировать, распределять задачи между под-агентами и безопасно использовать инструменты в изолированных средах. Сегодня мы живем в эпоху агентов с долгосрочным горизонтом планирования (long-horizon agents). Эти системы не просто генерируют текст; они выполняют исследования, сохраняют контекст на протяжении сложных задач и интегрируются с внешними данными.
Одним из ключевых решений в этой области является NVIDIA AI-Q Blueprint. Это открытый эталонный проект, построенный на базе LangChain Deep Agents и NVIDIA NeMo Agent Toolkit. Он предназначен для создания как быстрых ответов с цитированием, так и глубоких исследовательских отчетов с источниками. В этой статье мы подробно разберем, как развернуть AI-Q 2.0 в среде Oracle Cloud Infrastructure (OCI), используя Terraform для управления инфраструктурой и Helm для установки рабочих нагрузок в Kubernetes (OKE).
Этот материал предназначен для разработчиков и инженеров платформ, которые уже знакомы с Kubernetes, Terraform и командной строкой, но хотят перейти от локальных экспериментов к production-развертыванию в облаке. Мы пройдем весь путь: от подготовки окружения до запуска первого запроса к агенту, а также разберем типичные ошибки и лучшие практики.
01Архитектура NVIDIA AI-Q: От намерения к действию
Чтобы понять, как работает AI-Q, необходимо рассмотреть его многоагентную архитектуру. В основе системы лежит Intent Router (маршрутизатор намерений). Этот компонент анализирует запрос пользователя и определяет, какой рабочий процесс следует запустить. Архитектура спроектирована так, чтобы быть расширяемой: каждый слой — модели, инструменты, бэкенды RAG, под-агенты и оценщики — может быть заменен через конфигурацию YAML или систему плагинов NeMo Agent Toolkit.
Существует два основных пути обработки запроса:
- Shallow Research Agent (Поверхностный исследователь): Используется для быстрых ответов. Этот агент выполняет поиск с ограниченным набором инструментов, обеспечивая низкую задержку.
- Deep Agent (Глубокий агент): Предназначен для сложных задач. Он состоит из двух под-агентов: Planning sub-agent (планировщик) и Researcher sub-agent (исследователь). Они совместно используют слой файловой системы и запускают навыки (skills) в безопасных песочницах. Это позволяет агенту проводить многошаговые исследования, сохранять промежуточные результаты и возвращать структурированный отчет.
Такая архитектура позволяет системе адаптироваться под сложность запроса. Простой вопрос «Какова погода в Москве?» будет обработан поверхностным агентом, в то время как запрос «Сравните топ-3 открытых исследовательских агентов по баллу бенчмарка и стоимости» активирует глубокий агент, который проведет анализ, соберет данные из нескольких источников и синтезирует ответ.
02Инфраструктура Oracle Cloud: Связка Terraform и OKE
Развертывание AI-Q на OCI требует четкого разделения между инфраструктурой (IaC) и приложениями. Для этого используется связка Terraform и Helm. Terraform отвечает за создание сетевых ресурсов, кластера Kubernetes (OKE), балансировщика нагрузки и хранилища секретов. Helm, в свою очередь, устанавливает сами рабочие нагрузки (backend, frontend, база данных) внутрь кластера.
Ключевые ресурсы, которые создаются через Terraform, включают:
- VCN, подсети и шлюзы: Обеспечивают сетевую изоляцию с публичными и приватными подсетями для OKE.
- OKE Cluster + Node Pool: Используется Enhanced cluster с CNI, нативным для VCN, что обеспечивает высокую производительность и безопасность сетевого трафика.
- OCI Load Balancer: Создает публичный HTTP-вход (порт 80), который перенаправляет трафик на NodePort 30080 внутри кластера.
- OCI Vault + Secrets: Используется для безопасного хранения API-ключей (NVIDIA NGC, Tavily) и паролей базы данных с шифрованием AES-256.
Такой подход позволяет легко уничтожить всю инфраструктуру одной командой terraform destroy, что критически важно для контроля затрат при экспериментальной разработке.
03Подготовка окружения: Требования и зависимости
Перед началом развертывания необходимо убедиться, что у вас есть доступ к OCI-тенанту с достаточными квотами. Ниже приведен полный список необходимых ресурсов и инструментов.
Квоты OCI
- OKE: Один кластер Enhanced и один пул нод.
- Block Volume: Как минимум 10 ГБ (динамически выделяются CSI-драйвером OKE для PostgreSQL).
- Load Balancer: Один гибкий балансировщик нагрузки (flexible).
- Vault: Один хранилище секретов (vault) и секреты.
API-ключи
- NGC API Key: Получается на
build.nvidia.com. Формат:nvapi-.... Этот ключ используется как для инференса моделей NVIDIA, так и для аутентификации в реестре контейнеров NGC (nvcr.io). - Tavily API Key: Получается на
tavily.com. Формат:tvly-.... Используется для веб-поиска.
Локальные инструменты
- Terraform: Версия 1.5 или новее.
- kubectl: Версия 1.28 или новее.
- Helm: Версия 3.x или новее.
- OCI CLI: Настроенный с использованием вашего API-ключа подписи.
04Пошаговое развертывание: От кода к работающему агенту
Общее время развертывания составляет около 20–25 минут. Весь процесс можно разделить на четыре основных этапа. Начнем с клонирования репозитория и перехода в нужную директорию:
git clone https://github.com/oracle-samples/ai-q.git
cd ai-q/oke-samples/aiq-2.0Шаг 1: Конфигурация Terraform
Сначала необходимо настроить переменные 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: Пароль для инициализации встроенной PostgreSQL, который будет сохранен в OCI Vault.nvidia_api_key: Ваш ключ NGC.tavily_api_key: Ваш ключ Tavily.
Шаг 2: Создание инфраструктуры
Инициализируйте провайдеры, проверьте план и примените изменения:
terraform init
terraform plan
terraform applyЭтот процесс занимает 10–15 минут. Terraform создаст VCN, кластер OKE, Load Balancer и Vault. После завершения проверьте вывод:
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: Установка AI-Q через Helm
Теперь, когда инфраструктура готова, нужно установить рабочие нагрузки в Kubernetes. Чарт и образы контейнеров публикуются в NGC, поэтому локальная сборка не требуется.
3a. Настройка kubectl:
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
kubectl get nodesКоманда kubectl get nodes должна показать, что ноды готовы (Ready).
3b. Экспорт API-ключей:
export NGC_API_KEY="nvapi-..." # из build.nvidia.com
export TAVILY_API_KEY="tvly-..." # из tavily.com
export DB_USER_PASSWORD="" 3c. Создание namespace и секретов:
kubectl create namespace ns-aiq --dry-run=client -o yaml | kubectl apply -f -
# Приложения (NVIDIA + Tavily, Postgres)
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"
# Секрет для pull образов из nvcr.io
kubectl create secret docker-registry ngc-secret -n ns-aiq \
--docker-server=nvcr.io \
--docker-username='$oauthtoken' \
--docker-password="$NGC_API_KEY"3d. Установка чарта:
cd ../helm # из deploy/terraform в 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Оверлей values-oci-ngc.yaml минималистичен: он привязывает фронтенд к NodePort 30080 (порт, который проверяет Load Balancer) и указывает имя секрета для образов. Остальные настройки (репозитории образов, SQL-скрипты инициализации PostgreSQL, динамически выделенный PVC объемом 10 ГБ) берутся из дефолтов чарта.
Проверьте статус подов:
kubectl get pods -n ns-aiqЧерез 3–5 минут вы должны увидеть поды aiq-backend, aiq-frontend и aiq-postgres в состоянии Running.
Шаг 4: Запуск AI-Q
IP-адрес балансировщика нагрузки уже сохранен в переменной окружения. Откройте его в браузере:
echo "http://$LB_PUBLIC_IP"Вы должны увидеть веб-интерфейс AI-Q. Попробуйте простой вопрос, например, «What is the NeMo Agent Toolkit?», чтобы проверить маршрутизацию. Затем попробуйте более сложный запрос, например, «Compare the top three open-source deep-research agents by benchmark score and cost», чтобы активировать глубокого агента.
05Устранение неполадок и лучшие практики
Даже при тщательном следовании инструкциям могут возникнуть проблемы. Вот типичные сценарии и способы их решения.
Ошибка квот при создании OKE
Если terraform apply завершается ошибкой квоты, проверьте лимиты вашего компартмента на «Cluster count» и «Node count». Если лимит исчерпан, запросите увеличение квоты в OCI.
Pods stuck in ImagePullBackOff
Если поды не могут запустить образы, проверьте, был ли создан секрет для pull образов (kubectl get secret -n ns-aiq) и корректен ли NGC_API_KEY. Для обновления ключа удалите секрет и создайте его заново, затем выполните перезапуск деплоймента:
kubectl rollout restart deployment -n ns-aiq aiq-backend aiq-frontendPostgres pod stays in Pending
Если под PostgreSQL завис в состоянии Pending более чем на 2 минуты, возможно, PVC не был динамически выделен. Выполните kubectl describe pvc -n ns-aiq. Частые причины: не запущен CSI-драйвер OKE, отсутствует StorageClass по умолчанию или не хватает квоты на Block Volume. Проверьте классы хранилища через kubectl get sc и лимиты компартмента.
Load Balancer IP возвращается как null
OCI может потребоваться несколько минут после создания Terraform для завершения настройки LB. Выполните terraform refresh, а затем снова terraform output lb_public_ip.
Frontend loads but queries return 500
Посмотрите логи бэкенда: kubectl logs -n ns-aiq deploy/aiq-backend. Самая частая причина — неверный или отсутствующий NVIDIA_API_KEY или TAVILY_API_KEY в секрете aiq-credentials, созданном на шаге 3c.
06Что это значит на практике
Развертывание NVIDIA AI-Q на Oracle Cloud Infrastructure демонстрирует зрелость подхода к созданию AI-агентов. Это не просто демонстрация кода, а полноценная production-архитектура, которая учитывает безопасность (через OCI Vault), масштабируемость (через OKE) и гибкость (через Helm и YAML-конфигурацию).
Для разработчиков это означает возможность быстро прототипировать сложные агенты, не тратя время на настройку инфраструктуры. Для бизнеса — это путь к созданию масштабируемых AI-решений, которые можно легко адаптировать под меняющиеся требования, просто меняя конфигурацию, а не переписывая код. Экспериментируйте, делитесь своими решениями на NVIDIA Developer Forum и используйте эту платформу для создания следующего поколения интеллектуальных систем.
Источник: NVIDIA Developer ↗