#安装 Alauda Hyperflux

#下载软件包并上传到集群

你可以从 Customer Portal 网站上的 Marketplace 下载名为 Alauda Hyperflux 的应用。 下载后的软件包是一个名为 alauda-hyperflux-<version>.tar.gz 的 tarball 文件。

如果机器上没有 violet 命令行工具，请下载它：

1. 登录 ACP Web Console，并切换到 Administrator 视图。
2. 在 Marketplace / Upload Packages 中，点击 Download Packaging and Listing Tool。
3. 选择正确的 OS/CPU arch，然后点击 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 服务

在安装 Alauda Hyperflux 之前，你需要先准备一个供 Alauda Hyperflux 使用的 LLM 服务。 你可以使用 Azure OpenAI service，或者通过 Alauda AI 部署一个本地（On-Premise）LLM service，例如 vLLM。

在 Alauda Hyperflux 的安装步骤中，你将使用 LLM service endpoint、model name 和 API key。

如果你希望启用 Alauda Hyperflux 中的 rerank 功能，还需要准备一个支持 Cohere Reranker API v2 的 rerank service。关于如何使用 Alauda AI + vLLM 部署该服务的一种方式，请参见 Setup On-Premise Reranker Service。

NOTE: 从 v1.4.0 开始，内置的 knowledge-base dump 文件已随 plugin package 一并提供——你不再需要单独下载它，早期版本中的手动 pg_restore 步骤也已移除。init container 会在首次启动时自动恢复所选 dump。如果你想使用自己的内部文档来添加或替换随附的 corpus，请参见 Build a Custom Knowledge Base。

#安装 Alauda Hyperflux 集群插件

进入 Administrator / Marketplace / Cluster Plugins 页面， 从 cluster 下拉列表中选择 "global" cluster， 然后找到 Alauda Hyperflux plugin 并点击 Install。

NOTE: Alauda Hyperflux 必须安装在 Global cluster 中。

安装表单按主题分组如下。必填字段标记为 (required)。

#Database

• Enable builtin PGVector — 启用后，chart 会为 Alauda Hyperflux 提供一个单独的 PostgreSQL + ParadeDB 实例。设置：

  • PGVector Storage Size — PostgreSQL PVC 的存储大小，例如 10Gi。
  • PGVector StorageClass name — PVC 使用的 Kubernetes storage class，例如 sc-topolvm。

• 当禁用时，请改为创建一个 Secret（通过 pg database secret name 引用），其中包含外部 PostgreSQL 的连接信息。Hyperflux 在同一实例上使用三个逻辑数据库——docvec_sys_kb（内置产品知识库）、docvec_user_kb（用户上传的知识库）以及聊天历史数据库（默认 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>"

  然后在 pg database secret name 中输入 secret 名称。

• PG database name — 聊天历史数据库名称（默认 docvec）。如果缺失，会在首次启动时创建。

• PG collection name — 服务从 docvec_sys_kb 读取时使用的 LangChain PGVector collection 名称。它必须与所选 Built-in KnowledgeBase File 的内部 collection 名称一致；按照约定，该名称就是去掉 .dump 后缀的 dump 文件名。默认值 docvec_gte_acp_4_3_20260508 与默认 dump 匹配，因此除非你在下方选择了非默认的内置 dump，或者 (b) 部署了通过 Build a Custom Knowledge Base 构建的自定义 KB，否则请保持不变——在这两种情况下，都应将其设置为对应 dump 文件名去掉 .dump 后缀。

• Built-in KnowledgeBase File — 选择首次启动时要恢复的内置 dump。每个 dump 都是采集自特定 ACP release 的 Alauda Container Platform (ACP) 产品文档知识库，并全部使用 gte-multilingual-base model 进行嵌入。请选择与你运行的 ACP 版本匹配的条目；默认值为最新版本。可选项包括：

  • docvec_gte_acp_4_1_20260508.dump — ACP 4.1 documentation corpus。
  • docvec_gte_acp_4_2_20260508.dump — ACP 4.2 documentation corpus。
  • docvec_gte_acp_4_3_20260508.dump（默认）— ACP 4.3 documentation corpus（最新）。

  NOTE: 首次启动时的恢复会按原样加载 dump，并保留其内部 collection 名称。如果你选择的 dump 不是默认值，你必须同时将 PG collection name 设置为该 dump 文件名去掉 .dump 后缀（例如 docvec_gte_acp_4_1_20260508），否则服务会查询一个不存在的 collection，检索结果将为空。

• Enable builtin Redis — 启用后，chart 会提供一个单独的 Redis 实例供 rate limiter 使用。禁用时，请在 redis database secret name 中提供 Redis 凭据 secret。

#调度

• Node Selector (optional) — 通过 label 将 Hyperflux pods 固定到特定节点。可以添加一行或多行；不同的 label key 按 OR 关系进行判断。

#LLM service

• LLM Model type (required) — azure 或 openai。
• LLM Base URL (required) — LLM API 调用的 base URL。对于本地 vLLM 部署，请使用 http://<your-vllm-host>:<port>/v1。
• LLM Model Name (required) — API 调用中传入的 model name，例如 gpt-5-mini 或 qwen2。
• LLM API Key (required) — 用于 LLM API 调用的 API key。会作为外部密码存储。
• Azure API Version — 仅当 LLM Model type = azure 时需要，例如 2024-12-01-preview。
• Azure Deployment Name — 仅当 LLM Model type = azure 时需要，例如 o4-mini。

#Reranker

• Enable Reranker (required) — 启用兼容 Cohere API 的 reranking。它会通过额外一次服务调用提升答案相关性，但会带来一次额外的服务跳转。启用后，设置：
  • Cohere Reranker BaseUrl — reranker service 的 base URL。
  • Cohere Reranker Model — model name。
  • Cohere Reranker API key — API key（对于不强制认证的 vLLM 部署，任何非空值都可用）。

#Agent Mode

• Enable Agent Mode (required) — 启用多步推理，使 agent 可以调用 MCP tools。推荐： 在启用此功能时使用较强的 LLM（≥ GPT-4 / Qwen-72B 级别）；较小的模型可能会陷入循环或误用工具。
• Enable MCP Tools — 加载 ACP MCP tools，以便 agent 读取实时集群状态。仅在启用 Agent Mode 时可用。
• Expose MCP — 通过 Ingress 暴露随附的 acp-mcp-server，以便外部 MCP client（例如 IDE 端的 coding agents）可以访问。仅在启用 Agent Mode 时可用。
• 随附的 acp-mcp-server deployment 本身由 smartdoc.enableMCPServer 控制（默认值为 true）；只要启用 Agent Mode，就请保持开启。

NOTE: 早期版本需要设置 "MCP K8s API Server Address"（即 erebus URL）。该字段已在 v1.4.0 中移除——随附的 acp-mcp-server 现在直接在 global 集群内与集群通信，外部流量则通过 Ingress 路由。

#Retrieval（RAG）调优

• Total Search K (required) — 在 reranking 前从知识库中检索的候选数量，默认 20。
• RAG Similarity Threshold (required) — 保留一个 chunk 所需的最小 cosine similarity，默认 0.8。较低的值会以召回率为代价换取更高的精确率。
• Cohere Reranker Top N (required) — reranking 后送入 LLM 的 top-ranked chunk 数量，默认 6。仅在启用 reranking 时生效。
• Max History Number (required) — 提示词中保留的历史轮次数量，默认 1。
• Model Context Window — LLM 的总上下文窗口大小，单位为 tokens（例如 128000）。留空则按 model name 自动检测；会话历史压缩器会使用该值决定何时总结较早的轮次。

#审计和身份

• Admin Users — 以逗号分隔的用户名列表，这些用户可以在 Alauda Hyperflux 中查看审计日志，例如 admin@cpaas.io,admin。

#Rate limiter

• Enable Rate Limiter (required) — 启用后，将通过 Redis 强制执行按用户的请求频率和每日 token 配额。
• Max Requests Per Minute (RPM) — 每个用户的请求上限，默认 5。
• RPM Window Time (Minute) — 用于 RPM 检查的滑动窗口，默认 5。
• Max Total Tokens Per Day — 每个用户每天输入 + 输出 token 的总上限，默认 1000000。
• Max Input Tokens Per Day — 每个用户每天输入 token 的上限，默认 200000。
• Max Output Tokens Per Day — 每个用户每天输出 token 的上限，默认 1000000。

点击 Install 开始安装。首次启动时，init container 将执行以下操作：

1. 将所选的内置 dump 恢复到 docvec_sys_kb 中（该 dump 已包含 BM25 index）。
2. 如果聊天历史数据库和 docvec_user_kb 不存在，则创建它们。
3. 将 doc_id btree index 和 URL-backfill schema migrations 应用到两个 KB database。

#故障排查

如果聊天界面没有响应，请检查 Alauda Hyperflux pod logs：

# 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 不正确、Azure 的 API version 错误、model name 错误。
• 启用 reranking 时，Cohere API 配置错误。
• init container 未能创建或恢复 system KB database——init 日志行（在 data swap 步骤中以前缀 [upgrade] 标识）会指出失败的步骤。