#安装 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 架构，然后单击 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 the Alauda Hyperflux plugin package to the `global` cluster
# (Alauda Hyperflux MUST be installed in the `global` cluster)
violet push \
    ${PACKAGE_FILE} \
    --platform-address=${PLATFORM_ADDRESS} \
    --platform-username=${PLATFORM_ADMIN_USER} \
    --platform-password=${PLATFORM_ADMIN_PASSWORD} \
    --clusters=global \
    ${VIOLET_EXTRA_ARGS[@]}

#准备您的 LLM 和 rerank 服务

在安装 Alauda Hyperflux 之前，您需要先准备一个供 Alauda Hyperflux 使用的 LLM 服务。 您可以使用 Azure OpenAI service，或者使用 Alauda AI 部署一个本地的 LLM 服务，例如 vllm。

在 Alauda Hyperflux 的安装步骤中，您将使用 LLM 服务 endpoint、模型名称和 API key。

如果您希望在 Alauda Hyperflux 中启用 rerank 功能，还需要准备一个支持 Cohere Reranker API v2 的 rerank 服务。

注意： 知识库会在安装过程中从一个内置的数据库 dump 文件自动初始化。 不再需要手动准备和导入数据库 dump 文件（这仅在 v1.2.0 中需要）。

#安装 Alauda Hyperflux 集群插件

进入 Administrator / Marketplace / Cluster Plugins 页面， 在 cluster 下拉列表中选择 "global" 集群， 然后找到 Alauda Hyperflux 插件并单击 Install。

注意： 必须将 Alauda Hyperflux 安装在 global 集群中。

填写以下配置：

#知识库和数据库

• 内置 KnowledgeBase 文件：用于在首次启动时初始化知识库的内置数据库 dump 文件。请选择与您的 ACP 版本匹配的文件，例如 ACP 4.3 对应 docvec_gte_acp_4_3_<date>.dump。
• 启用内置 PGVector：
  • 启用：将在集群中安装一个供 Alauda Hyperflux 使用的单个 PostgreSQL（带 pgvector）实例。您需要设置：
    • PGVector 存储大小：PostgreSQL 数据的存储大小，例如 10Gi。
    • PGVector StorageClass 名称：Kubernetes storage class 名称，例如 sc-topolvm。
  • 禁用：通过 secret 提供外部 PostgreSQL（需要 pgvector extension）的连接信息， 并在 pg database secret name 中填写该 secret 名称：

    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 name：用于存储对话历史的 PostgreSQL 数据库名称。
• PG collection name：用于存储文档向量的 collection 名称。 必须与所选内置知识库文件名去掉 .dump 后的名称完全一致。
• 启用内置 Redis：Redis 供 rate limiter 和缓存使用。
  • 启用：将在集群中安装一个单独的 Redis 实例。
  • 禁用：通过 secret 提供外部 Redis 的连接信息， 并在 redis database secret name 中填写该 secret 名称：

    apiVersion: v1
    kind: Secret
    metadata:
      name: redis-secret
      namespace: cpaas-system
    type: Opaque
    stringData:
      REDIS_HOST: <your-redis-host>
      REDIS_PORT: <your-redis-port>
      REDIS_PASSWORD: <your-redis-password>
      REDIS_DB: "0"

#LLM 服务

• LLM Model type：azure（Azure OpenAI）或 openai（兼容 OpenAI API，例如 vllm）。
• LLM Base URL：LLM API 调用的基础 URL。使用本地部署的 LLM 服务 （例如 vllm）时，URL 应类似于 http://<your-vllm-host>:<port>/v1。
• LLM Model Name：LLM API 调用使用的模型名称。
• Use an existing credentials Secret：
  • 禁用（默认）：直接在下方表单中输入 API key；系统会自动创建一个 secret。
    • LLM API Key：LLM API 调用所用的 API key。
    • Cohere Reranker API key：启用 reranker 时显示。
  • 启用：在 Existing credentials Secret 中引用一个已存在的 secret。 该 secret 必须包含 llm-api-key、cohere-api-key 和 api-key 这几个键。
• Azure API Version（仅 Azure）：Azure OpenAI API 版本，例如 2024-12-01-preview。
• Azure Deployment Name（仅 Azure）：Azure OpenAI deployment 名称。
• Model Context Window（可选）：LLM 模型的上下文窗口大小（例如 128000）。 留空则按模型名称自动检测。

#Reranker（可选）

• Enable Reranker：是否启用 reranking 功能，用于提升检索文档的相关性。 当前仅支持 Cohere Reranker API。如果启用，请设置以下值：
  • Cohere Reranker BaseUrl：Cohere Reranker API 调用的基础 URL。
  • Cohere Reranker Model：Cohere Reranker API 调用的模型名称，例如 rerank-v3.5。
  • Cohere Reranker API key：Cohere Reranker API 调用所用的 API key （使用现有 credentials secret 时会隐藏）。

#智能体工具（MCP）

• Expose MCP：是否通过 Ingress 访问内置 MCP server。
• Tool Approval Strategy：决定哪些智能体工具调用需要人工批准：
  • disabled（默认）：写入类工具会从 LLM 工具集中被过滤掉，因此 LLM 根本无法调用它们。
  • tool_annotations：写入类工具（MCP readOnlyHint=false）需要交互式批准。
  • always：每次工具调用都需要交互式批准。
  • never：不需要批准，LLM 可以无人值守地调用任何工具。在生产环境中请谨慎使用。
• Expose as MCP Server：将 Alauda Hyperflux 本身在 /mcp 处暴露为 MCP server，使 IDE 和 智能体可以将其作为工具调用。读操作始终允许；写操作需要交互式批准。默认关闭。参见 在您的 IDE 中将 Hyperflux 作为 MCP Server 使用。
  • MCP Write-Approval Timeout (s)：在将写入审批响应视为拒绝之前等待的最长秒数。默认 300。
• Extra MCP Servers ConfigMaps（可选）：包含额外 MCP server 定义的 ConfigMaps 名称（位于插件 namespace 中）； 启动时会扫描每个 ConfigMap 中的 *.yaml/*.yml/*.json 条目。 参见 配置外部 MCP Servers。

#Skills

• Enable Skills：当查询匹配时，自动加载由管理员配置的过程型 skills（挂载自 ConfigMaps）。
  • Skills Match Threshold：将查询与 skill 匹配时的 cosine 阈值（0-1）。 数值越高越严格。默认 0.35。
  • Skills ConfigMaps（可选）：包含将 *.md 条目作为 skills 加载的 ConfigMaps 名称（位于插件 namespace 中）。 参见 创建自定义 Skills。

#Rate 和 quota 限制

• Enable Rate Limiter：是否启用按用户限流和每日 token 配额。 如果启用，请设置以下值：
  • Max Requests Per Minute (RPM)：默认 5。
  • RPM Window Time (Minute)：默认 5。
  • Max Total Tokens Per Day：默认 1000000。
  • Max Input Tokens Per Day：默认 200000。
  • Max Output Tokens Per Day：默认 1000000。

#RAG 调优

默认值适用于大多数场景；仅在需要时调整。

• Total Search K：从知识库中检索的搜索结果总数。默认 20。
• RAG Similarity Threshold：检索相关文档的相似度阈值。默认 0.8。
• Cohere Reranker Top N：reranking 后保留的前 N 个文档数。默认 6。
• Max History Number：在聊天历史中保留的前序交互次数。默认 1。

#其他设置

• Node Selector（可选）：如有需要，为 Alauda Hyperflux pods 设置 node label 的 key/value 条件。
• Admin Users：以逗号分隔的管理员用户名，例如 admin@cpaas.io,user1。 管理员可以在 Alauda Hyperflux 中管理审计日志。
• Extra CA ConfigMaps（可选）：包含内部 / 自签名 CA 证书（PEM）的 ConfigMaps 名称（位于插件 namespace 中）。 这些证书会追加到出站 TLS trust bundle 中，因此可以访问使用此类证书的 LLM / MCP / reranker endpoint。 参见 配置 TLS。

单击 Install 开始安装。

#验证安装

知识库会在首次启动时自动初始化：init container 会创建数据库并恢复所选的内置 dump 文件。 这可能需要几分钟。

检查 pods 是否正在运行：

kubectl -n cpaas-system get pod | grep smart-doc

当 smart-doc pod 就绪后，打开 ACP Web Console，即可看到 Alauda Hyperflux 聊天图表。

#故障排查

如果聊天界面没有响应，您可以检查 Alauda Hyperflux pod 的日志进行排查：

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

在大多数情况下，问题是由错误的 LLM 服务配置，或者在启用 rerank 时的 Cohere API 配置导致的。 请检查日志中的错误信息以修正配置问题。