Alauda Hyperflux
  • 简体中文

    • 安装 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. 选择正确的操作系统/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 服务

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

    您将在 Alauda Hyperflux 安装步骤中使用 LLM 服务的端点、模型名称和 API 密钥。

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

    准备数据库转储文件（仅 v1.2.0 版本需要）

    下载与您当前 ACP 版本对应的数据库转储文件，如 docvec_acp_4_1.dump。 安装时必须使用类似 docvec_acp_4_1 的文件名作为数据库名称。

    安装 Alauda Hyperflux 集群插件

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

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

    填写以下配置：

    • 内置 PG 数据库：
      • 启用：将在集群中安装一个单实例 PostgreSQL 供 Alauda Hyperflux 使用。您需要设置：
        • 存储大小：PostgreSQL 数据的存储大小。
        • 存储类名称：Kubernetes 存储类名称，例如 sc-topolvm
      • 禁用：创建以下 secret，提供外部 PostgreSQL 连接信息。 
        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+pg8000://<your-pg-username>:<your-pg-password>@<your-pg-host>:<your-pg-port>"
    • PG 数据库名称：Alauda Hyperflux 使用的数据库名称。必须与数据库转储文件名（去除 .dump 后缀）相同。
    • 节点选择器（可选）：如有需要，为 Alauda Hyperflux pods 设置节点选择器。
    • LLM 模型类型：Azure 或 OpenAI。
    • LLM 基础 URL：LLM API 调用的基础 URL。使用本地部署的 LLM 服务（如 vllm）时，URL 应类似 http://<your-vllm-host>:<port>/v1。
    • 模型名称：LLM API 调用的模型名称。
    • API 密钥：LLM API 调用的 API 密钥。
    • Azure API 版本（可选）：使用 Azure OpenAI 服务时，设置 API 版本。
    • Azure 部署名称（可选）：使用 Azure OpenAI 服务时，设置部署名称。
    • 启用 Rerank：是否启用 Alauda Hyperflux 中使用 Cohere API 的 rerank 功能。启用时设置以下值：
      • Cohere Reranker BaseURL：Cohere Reranker API 调用的基础 URL。
      • Cohere Reranker 模型：Cohere Reranker API 调用的模型名称。
      • Cohere API Key：Cohere Reranker API 调用的 API 密钥。
    • 启用 Agent 模式：是否启用 Agent 模式，利用 MCP 工具获取实时集群信息。
      • 注意： Agent 模式为实验性功能，请谨慎使用。
    • MCP K8s API Server 地址：MCP 集群的 K8s API 服务器地址。
      • 重要： 该 URL 应设置为 erebus 地址，如 https://erebus.cpaas-system:443/kubernetes/<cluster-name>。
      • 重要： cluster-name 应设置为您希望 MCP 工具访问的集群名称。
    • 管理员用户名：以逗号分隔的管理员用户列表。管理员用户可以管理 Alauda Hyperflux 中的审计日志。

    点击 Install 开始安装。

    导入数据库转储初始化知识库（仅 v1.2.0 版本需要）

    Alauda Hyperflux 安装完成后，您需要导入数据库转储文件以初始化知识库。 使用以下命令导入数据库转储文件：

    # Get the PostgreSQL pod name
kubectl -n cpaas-system get pod | grep postgre-vec
# Copy the dump file to the PostgreSQL pod
kubectl -n cpaas-system cp docvec_acp_4_1.dump <postgre-vec-xxx>:/tmp/docvec_acp_4_1.dump
# Temporarily stop the Alauda Hyperflux deployment to avoid connection issues during database import
kubectl -n cpaas-system scale deployment smart-doc --replicas=0
# Exec into the PostgreSQL pod
kubectl -n cpaas-system exec -it <postgre-vec-xxx> -- /bin/bash
# Import the database dump file
# NOTE: change the database name docvec_acp_4_1 to the actual database name
psql -U postgres -W -c "DROP DATABASE docvec_acp_4_1;"
psql -U postgres -W -c "CREATE DATABASE docvec_acp_4_1;"
pg_restore -U postgres -W -d docvec_acp_4_1 /tmp/docvec_acp_4_1.dump
# Enter the password when prompted
# Exit the pod
exit

# Restart the Alauda Hyperflux deployment
kubectl -n cpaas-system scale deployment smart-doc --replicas=1
# execute db_orm.py to re-init database schema
kubectl -n cpaas-system exec -it <smart-doc-xxx> -- python /workspace/db_orm.py

    注意： 使用内置 PostgreSQL 数据库时，默认密码为 alauda-test。

    故障排查

    如果聊天界面无响应，您可以查看 Alauda Hyperflux pod 日志进行排查：

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

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