#Install Alauda Hyperflux

#Download package and upload to cluster

You can download the app named 'Alauda Hyperflux' from the Marketplace on the Customer Portal website. The downloaded package is a tarball file named alauda-hyperflux-<version>.tar.gz.

Download the violet command line tool if it is not present on the machine:

1. Log into the ACP Web Console and switch to the Administrator view.
2. In Marketplace / Upload Packages, click Download Packaging and Listing Tool.
3. Select the right OS/CPU arch, and click Download.
4. Run chmod +x ${PATH_TO_THE_VIOLET_TOOL} to make the tool executable.

Save the following script in upload.sh, then edit the file to fill in the correct configuration values according to the comments.

#!/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[@]}

#Prepare your LLM and rerank service

Before installing Alauda Hyperflux, you need to prepare an LLM service for Alauda Hyperflux to use. You can use Azure OpenAI service, or deploy an On-Premise LLM service like vllm using Alauda AI.

You will use the LLM service endpoint, model name and API key in the Alauda Hyperflux installation step.

Optionally, if you want to enable the rerank feature in Alauda Hyperflux, you also need to prepare a rerank service that supports Cohere Reranker API v2.

NOTE: The knowledge base is initialized automatically from a built-in database dump file selected during installation. Manually preparing and importing a database dump file is no longer needed (it was only required for v1.2.0).

#Install Alauda Hyperflux cluster plugin

Go to Administrator / Marketplace / Cluster Plugins page, select "global" cluster from the cluster dropdown list, then find the Alauda Hyperflux plugin and click Install.

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

Fill in the configurations below:

#Knowledge base and databases

• Built-in KnowledgeBase File: the built-in database dump file used to initialize the knowledge base on first startup. Select the file matching your ACP version, e.g. docvec_gte_acp_4_3_<date>.dump for ACP 4.3.
• Enable builtin PGVector:
  • Enabled: a single PostgreSQL (with pgvector) instance will be installed in the cluster for Alauda Hyperflux to use. You need to set:
    • PGVector Storage Size: the storage size for PostgreSQL data, e.g. 10Gi.
    • PGVector StorageClass name: Kubernetes storage class name, e.g. sc-topolvm.
  • Disabled: provide the connection info of an external PostgreSQL (pgvector extension required) via a secret, and fill the secret name in pg database secret name:

    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: the PostgreSQL database name for storing conversation history.
• PG collection name: the collection name for storing document vectors. MUST be the same as the selected built-in knowledge base file name without the .dump suffix.
• Enable builtin Redis: Redis is used by the rate limiter and caching.
  • Enabled: a single Redis instance will be installed in the cluster.
  • Disabled: provide the connection info of an external Redis via a secret, and fill the secret name in redis database secret name:

    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 service

• LLM Model type: azure (Azure OpenAI) or openai (OpenAI-compatible API, e.g. vllm).
• LLM Base URL: the base URL for LLM API calls. When using an On-Premise deployment of LLM service like vllm, the URL should look like http://<your-vllm-host>:<port>/v1.
• LLM Model Name: the model name for LLM API calls.
• Use an existing credentials Secret:
  • Disabled (default): enter the API keys directly in the form below; a secret is created automatically.
    • LLM API Key: the API key for LLM API calls.
    • Cohere Reranker API key: shown when the reranker is enabled.
  • Enabled: reference a pre-existing secret in Existing credentials Secret. The secret must contain the keys llm-api-key, cohere-api-key and api-key.
• Azure API Version (Azure only): the Azure OpenAI API version, e.g. 2024-12-01-preview.
• Azure Deployment Name (Azure only): the Azure OpenAI deployment name.
• Model Context Window (Optional): context window size of the LLM model (e.g. 128000). Leave empty to auto-detect by model name.

#Reranker (Optional)

• Enable Reranker: whether to enable the reranking feature, which improves the relevance of retrieved documents. Only Cohere Reranker API is supported currently. Set below values if enabled:
  • Cohere Reranker BaseUrl: the base URL for Cohere Reranker API calls.
  • Cohere Reranker Model: the model name for Cohere Reranker API calls, e.g. rerank-v3.5.
  • Cohere Reranker API key: the API key for Cohere Reranker API calls (hidden when using an existing credentials secret).

#Agent tools (MCP)

• Expose MCP: whether to access the built-in MCP server via Ingress.
• Tool Approval Strategy: decide which agent tool calls require human approval:
  • disabled (default): write tools are filtered out of the LLM tool set, so the LLM cannot call them at all.
  • tool_annotations: write tools (MCP readOnlyHint=false) require interactive approval.
  • always: every tool call requires interactive approval.
  • never: no approval, the LLM can call any tool unattended. Use with caution in production.
• Expose as MCP Server: expose Alauda Hyperflux itself as an MCP server at /mcp, so IDEs and agents can call it as a tool. Read operations are always allowed; write actions require interactive approval. Default off. See Use Hyperflux as an MCP Server in Your IDE.
  • MCP Write-Approval Timeout (s): max seconds to wait for a write-approval response before treating it as a decline. Default 300.
• Extra MCP Servers ConfigMaps (Optional): names of ConfigMaps (in the plugin namespace) holding extra MCP server definitions; each ConfigMap's *.yaml/*.yml/*.json entries are scanned at startup. See Configure External MCP Servers.

#Skills

• Enable Skills: auto-load admin-configured procedural skills (mounted from ConfigMaps) when a query matches.
  • Skills Match Threshold: cosine threshold (0-1) for matching a query to a skill. Higher is stricter. Default 0.35.
  • Skills ConfigMaps (Optional): names of ConfigMaps (in the plugin namespace) whose *.md entries are loaded as skills. See Create Custom Skills.

#Rate and quota limits

• Enable Rate Limiter: whether to enable per-user rate limiting and daily token quotas. Set below values if enabled:
  • Max Requests Per Minute (RPM): default 5.
  • RPM Window Time (Minute): default 5.
  • Max Total Tokens Per Day: default 1000000.
  • Max Input Tokens Per Day: default 200000.
  • Max Output Tokens Per Day: default 1000000.

#RAG tuning

The defaults work for most cases; adjust only if needed.

• Total Search K: total number of search results to retrieve from the knowledge base. Default 20.
• RAG Similarity Threshold: similarity threshold for retrieving relevant documents. Default 0.8.
• Cohere Reranker Top N: number of top documents to keep after reranking. Default 6.
• Max History Number: number of previous interactions to retain in chat history. Default 1.

#Other settings

• Node Selector (Optional): set the node label key/value terms for Alauda Hyperflux pods if needed.
• Admin Users: comma-separated admin user names, e.g. admin@cpaas.io,user1. Admin users can manage audit logs in Alauda Hyperflux.
• Extra CA ConfigMaps (Optional): names of ConfigMaps (in the plugin namespace) holding internal / self-signed CA certificates (PEM). The certificates are appended to the outbound TLS trust bundle, so LLM / MCP / reranker endpoints using such certificates can be accessed. See Configure TLS.

Click Install to start installation.

#Verify the installation

The knowledge base is initialized automatically on the first startup: an init container creates the databases and restores the selected built-in dump file. This may take a few minutes.

Check that the pods are running:

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

Once the smart-doc pod is ready, open the ACP Web Console and the Alauda Hyperflux chat panel is available.

#Troubleshooting

If the chat interface fails to respond, you can check the Alauda Hyperflux pod logs for troubleshooting:

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

In most cases, the issue is caused by incorrect LLM service configurations, or Cohere API configurations when rerank is enabled. Check the error messages in the logs to fix the configuration issues.