#Установка Alauda Hyperflux

#Скачивание пакета и загрузка в cluster

Вы можете скачать приложение с названием Alauda Hyperflux из Marketplace на сайте Customer Portal.
Скачанный пакет представляет собой tarball-файл с именем alauda-hyperflux-<version>.tar.gz.

Скачайте командную утилиту violet, если она отсутствует на машине:

1. Войдите в ACP Web Console и переключитесь в представление Administrator.
2. В Marketplace / Upload Packages нажмите Download Packaging and Listing Tool.
3. Выберите правильную ОС/архитектуру CPU и нажмите Download.
4. Выполните chmod +x ${PATH_TO_THE_VIOLET_TOOL}, чтобы сделать инструмент исполняемым.

Сохраните следующий скрипт в upload.sh,
затем отредактируйте файл и заполните корректные значения конфигурации в соответствии с комментариями.

#!/usr/bin/env bash
# Set ACP address and admin user credentials
export PLATFORM_ADDRESS=https://platform-address  
export PLATFORM_ADMIN_USER=<admin>
export PLATFORM_ADMIN_PASSWORD=<admin-password>
# Set the package file to push
export PACKAGE_FILE=alauda-hyperflux-<version>.tar.gz  

VIOLET_EXTRA_ARGS=()
IS_EXTERNAL_REGISTRY=""

# If the image registry type of destination cluster is not platform built-in (external private or public repository).
# Additional configuration is required (uncomment following line):
# IS_EXTERNAL_REGISTRY=true
if [[ "${IS_EXTERNAL_REGISTRY}" == "true" ]]; then
    REGISTRY_ADDRESS=<external-registry-url>
    REGISTRY_USERNAME=<registry-username>
    REGISTRY_PASSWORD=<registry-password>

    VIOLET_EXTRA_ARGS+=(
        --dst-repo "${REGISTRY_ADDRESS}"
        --username "${REGISTRY_USERNAME}"
        --password "${REGISTRY_PASSWORD}"
    )
fi

# Push **Alauda AI Cluster** operator package to destination cluster
violet push \
    ${AI_CLUSTER_OPERATOR_NAME} \
    --platform-address=${PLATFORM_ADDRESS} \
    --platform-username=${PLATFORM_ADMIN_USER} \
    --platform-password=${PLATFORM_ADMIN_PASSWORD} \
    --clusters=${CLUSTER} \
    ${VIOLET_EXTRA_ARGS[@]}

#Подготовьте LLM и rerank service

Перед установкой Alauda Hyperflux необходимо подготовить LLM service, который будет использоваться Alauda Hyperflux.
Вы можете использовать Azure OpenAI service или развернуть On-Premise LLM service, например vLLM, с помощью Alauda AI.

На этапе установки Alauda Hyperflux будут использоваться endpoint LLM service, имя модели и API key.

При необходимости, если вы хотите включить функцию rerank в Alauda Hyperflux, вам также нужно подготовить rerank service, поддерживающий Cohere Reranker API v2. См. Setup On-Premise Reranker Service для одного из способов развертывания этого решения с помощью Alauda AI + vLLM.

NOTE: Начиная с v1.4.0, файл дампа встроенной knowledge-base входит в состав пакета плагина — вам больше не нужно загружать его отдельно, и ручной шаг pg_restore из предыдущих версий больше не требуется. Init- container автоматически восстанавливает выбранный дамп при первом запуске. См. Build a Custom Knowledge Base, если вы хотите добавить или заменить встроенный corpus на собственную внутреннюю документацию.

#Установка cluster plugin Alauda Hyperflux

Перейдите на страницу Administrator / Marketplace / Cluster Plugins,
выберите кластер "global" в выпадающем списке кластеров,
затем найдите plugin Alauda Hyperflux и нажмите Install.

NOTE: Alauda Hyperflux MUST be installed in the Global cluster.

Форма установки ниже сгруппирована по темам. Обязательные поля помечены как (required).

#Database

• Enable builtin PGVector — при включении chart разворачивает один экземпляр PostgreSQL + ParadeDB для Alauda Hyperflux. Укажите:

  • PGVector Storage Size — размер хранилища для PVC PostgreSQL (например, 10Gi).
  • PGVector StorageClass name — storage class Kubernetes для PVC, например sc-topolvm.

• Когда параметр disabled, вместо этого создайте Secret (на который ссылается pg database secret name) с информацией о внешнем подключении PostgreSQL. Hyperflux использует три логические базы данных на одном экземпляре — docvec_sys_kb (встроенная product knowledge base), docvec_user_kb (user-uploaded knowledge base) и базу данных истории чатов (по умолчанию docvec, настраивается через PG database name) — все они создаются автоматически init container, если отсутствуют.

  apiVersion: v1
  kind: Secret
  metadata:
    name: pg-secret
    namespace: cpaas-system
  type: Opaque
  stringData:
    host: <your-pg-host>
    port: <your-pg-port>
    username: <your-pg-username>
    password: <your-pg-password>
    uri: "postgresql+psycopg://<your-pg-username>:<your-pg-password>@<your-pg-host>:<your-pg-port>"

  Затем введите имя Secret в pg database secret name.

• PG database name — имя базы данных истории чатов (по умолчанию docvec). Создается при первом запуске, если отсутствует.

• PG collection name — имя коллекции LangChain PGVector, из которой сервер читает данные из docvec_sys_kb. Оно должно совпадать с внутренним именем коллекции выбранного Built-in KnowledgeBase File; по соглашению это имя файла дампа без суффикса .dump. Значение по умолчанию docvec_gte_acp_4_3_20260508 соответствует дампу по умолчанию, поэтому оставьте его без изменений, если вы либо (a) выбираете ниже нестандартный встроенный дамп, либо (b) разворачиваете пользовательскую KB, созданную с помощью Build a Custom Knowledge Base — в обоих случаях укажите здесь имя соответствующего файла дампа без .dump.

• Built-in KnowledgeBase File — выберите, какой встроенный дамп восстанавливать при первом запуске. Каждый дамп — это knowledge base документации продукта Alauda Container Platform (ACP), собранная для определенного релиза ACP; все они встроены с моделью gte-multilingual-base. Выберите тот, который соответствует используемой версии ACP; по умолчанию выбран самый новый. Селектор предлагает:

  • docvec_gte_acp_4_1_20260508.dump — documentation corpus ACP 4.1.
  • docvec_gte_acp_4_2_20260508.dump — documentation corpus ACP 4.2.
  • docvec_gte_acp_4_3_20260508.dump (default) — documentation corpus ACP 4.3 (latest).

  NOTE: Восстановление при первом запуске загружает дамп как есть и сохраняет его внутреннее имя коллекции. Если вы выберете дамп, отличный от значения по умолчанию, вы должны также указать PG collection name как имя этого дампа без .dump (например, docvec_gte_acp_4_1_20260508), иначе сервер будет выполнять запрос к несуществующей коллекции и retrieval ничего не вернет.

• Enable builtin Redis — при включении chart разворачивает один экземпляр Redis, используемый rate limiter. Когда параметр отключен, укажите Secret с учетными данными Redis в redis database secret name.

#Scheduling

• Node Selector (optional) — закрепляет pod Hyperflux за определенными узлами по label. Добавьте одну или несколько строк; разные ключи label обрабатываются по OR.

#LLM service

• LLM Model type (required) — azure или openai.
• LLM Base URL (required) — базовый URL для вызовов API LLM. Для On-Premise развертывания vLLM используйте http://<your-vllm-host>:<port>/v1.
• LLM Model Name (required) — имя модели, передаваемое в API-вызовах, например gpt-5-mini или qwen2.
• LLM API Key (required) — API key для вызовов LLM API. Хранится как external password.
• Azure API Version — только если LLM Model type = azure, например 2024-12-01-preview.
• Azure Deployment Name — только если LLM Model type = azure, например o4-mini.

#Reranker

• Enable Reranker (required) — включает reranking, совместимый с Cohere API. Повышает релевантность ответов ценой одного дополнительного перехода к service. При включении укажите:
  • Cohere Reranker BaseUrl — базовый URL reranker service.
  • Cohere Reranker Model — имя модели.
  • Cohere Reranker API key — API key (для развертываний vLLM без проверки auth подойдет любое непустое значение).

#Agent Mode

• Enable Agent Mode (required) — включает многошаговое рассуждение, чтобы agent мог вызывать MCP tools. Рекомендуется: использовать мощный LLM (класса ≥ GPT-4 / Qwen-72B), когда эта опция включена; более маленькие модели могут зацикливаться или неправильно использовать tools.
• Enable MCP Tools — загружает ACP MCP tools, чтобы agent мог читать текущее состояние cluster. Доступно только когда включен Agent Mode.
• Expose MCP — публикует встроенный acp-mcp-server через Ingress, чтобы внешние MCP clients (например, coding agents на стороне IDE) могли подключаться к нему. Доступно только когда включен Agent Mode.
• Сам deployment встроенного acp-mcp-server управляется параметром smartdoc.enableMCPServer (по умолчанию true); оставляйте его включенным, когда включен Agent Mode.

NOTE: В более ранних версиях требовалось задавать "MCP K8s API Server Address" (URL erebus). Это поле было удалено в v1.4.0 — теперь встроенный acp-mcp-server обращается к cluster напрямую внутри global cluster, а внешний трафик маршрутизируется через Ingress.

#Настройка Retrieval (RAG)

• Total Search K (required) — количество кандидатов, которые нужно получить из knowledge base перед reranking, по умолчанию 20.
• RAG Similarity Threshold (required) — минимальная cosine similarity для сохранения chunk, по умолчанию 0.8. Более низкие значения повышают recall за счет precision.
• Cohere Reranker Top N (required) — количество chunk с самым высоким рейтингом, передаваемых в LLM после reranking, по умолчанию 6. Применяется только при включенном reranking.
• Max History Number (required) — количество предыдущих ходов, сохраняемых в prompt, по умолчанию 1.
• Model Context Window — общий размер context window LLM в token (например, 128000). Оставьте пустым, чтобы определить его автоматически по имени модели; compressor истории диалога использует это значение, чтобы понять, когда нужно суммировать более старые ходы.

#Audit and identity

• Admin Users — список usernames, разделенных запятыми, которые могут просматривать audit logs в Alauda Hyperflux, например admin@cpaas.io,admin.

#Rate limiter

• Enable Rate Limiter (required) — при включении ограничивается частота запросов для каждого пользователя и дневные квоты token через Redis.
• Max Requests Per Minute (RPM) — лимит запросов на пользователя, по умолчанию 5.
• RPM Window Time (Minute) — скользящее окно для проверки RPM, по умолчанию 5.
• Max Total Tokens Per Day — суммарный лимит input + output token на пользователя, по умолчанию 1000000.
• Max Input Tokens Per Day — лимит input token на пользователя, по умолчанию 200000.
• Max Output Tokens Per Day — лимит output token на пользователя, по умолчанию 1000000.

Нажмите Install, чтобы начать установку. При первом запуске init container выполнит:

1. Восстановит выбранный встроенный дамп в docvec_sys_kb (дамп уже содержит индекс BM25).
2. Создаст базу данных истории чатов и docvec_user_kb, если они не существуют.
3. Применит индекс btree для doc_id и миграции схемы URL-backfill к обеим базам знаний.

#Устранение неполадок

Если интерфейс чата не отвечает, проверьте logs pod Alauda Hyperflux:

# Server
kubectl -n cpaas-system logs -l app=smart-doc -c serve

# Init container (first-start KB bootstrap and upgrade-time KB swap)
kubectl -n cpaas-system logs -l app=smart-doc -c init-database

Большинство проблем вызвано следующими причинами:

• Неверная конфигурация LLM service — неправильный base URL, неверная версия API для Azure, неправильное имя модели.
• Неверная конфигурация Cohere API при включенном reranking.
• Неудачная попытка init container создать или восстановить базу данных system KB — строки лога init (с префиксом [upgrade] для шага data swap) указывают на проблемный шаг.