安装 Alauda AI

Alauda AI 现已提供灵活的部署选项。从 Alauda AI 1.4 开始，Knative 能力作为可选功能提供，如果不需要，可以采用更精简的安装方式。

首先，您需要部署 Alauda AI Operator。这是所有 Alauda AI 产品的核心引擎。默认情况下，它为推理后端使用 KServe Standard 模式，这种模式尤其推荐用于资源密集型生成式工作负载。该模式提供了一种直接的模型部署方式，并借助 Kubernetes 的基础功能提供了强大且可定制的部署能力。

如果您的使用场景需要 Knative 功能，例如用于成本优化的 按需缩容到 0 等高级特性，您可以选择安装 Knative Operator。该 operator 不属于默认安装内容，可随时添加以启用 Knative 功能。

INFO

推荐的部署选项：对于生成式推理工作负载，推荐使用 Standard 方式（以前称为 RawKubernetes Deployment），因为它可以对资源分配和扩缩容提供最大的控制能力。

下载

Operator 组件：

Alauda AI Operator

Alauda AI Operator 是驱动 Alauda AI 产品的主引擎。它聚焦于两个核心功能：模型管理和推理服务，并提供一个可轻松扩展的灵活框架。

下载包：aml-operator.xxx.tgz
Knative Operator

Knative Operator 提供 serverless 模型推理。

下载包：knative-operator.ALL.v1.x.x-yymmdd.tgz

INFO

您可以从 Customer Portal 网站上的 Marketplace 下载名为 'Alauda AI' 和 'Knative Operator' 的应用。

上传

我们需要将 Alauda AI 和 Knative Operator 都上传到将要使用 Alauda AI 的集群中。

下载 violet 工具

首先，如果机器上还没有 violet 工具，我们需要先下载它。

单击 Marketplace / 上架软件包。
单击 Download Packaging and Listing Tool。
在 Execution Environment 下找到正确的 OS / CPU architecture。
单击 Download 下载 violet 工具。
运行 chmod +x ${PATH_TO_THE_VIOLET_TOOL} 使该工具可执行。

上传软件包

先将以下脚本保存为 uploading-ai-cluster-packages.sh，然后阅读下面的注释，更新该脚本中的环境变量以进行配置。

uploading-ai-cluster-packages.sh

#!/usr/bin/env bash
export PLATFORM_ADDRESS=https://platform-address  
export PLATFORM_ADMIN_USER=<admin>
export PLATFORM_ADMIN_PASSWORD=<admin-password>
export CLUSTER=<cluster-name>

export AI_CLUSTER_OPERATOR_NAME=<path-to-aml-operator-tarball>
export KNATIVE_OPERATOR_PKG_NAME=<path-to-knative-operator-tarball>

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

# Push **Knative Operator** package to destination cluster
violet push \
    ${KNATIVE_OPERATOR_PKG_NAME} \
    --platform-address=${PLATFORM_ADDRESS} \
    --platform-username=${PLATFORM_ADMIN_USER} \
    --platform-password=${PLATFORM_ADMIN_PASSWORD} \
    --clusters=${CLUSTER} \
    ${VIOLET_EXTRA_ARGS[@]}

${PLATFORM_ADDRESS} 是您的 ACP 平台地址。
${PLATFORM_ADMIN_USER} 是 ACP 平台管理员的用户名。
${PLATFORM_ADMIN_PASSWORD} 是 ACP 平台管理员的密码。
${CLUSTER} 是要安装 Alauda AI 组件的集群名称。
${AI_CLUSTER_OPERATOR_NAME} 是 Alauda AI Cluster Operator 软件包 tarball 的路径。
${KNATIVE_OPERATOR_PKG_NAME} 是 Knative Operator 软件包 tarball 的路径。
${REGISTRY_ADDRESS} 是外部 registry 的地址。
${REGISTRY_USERNAME} 是外部 registry 的用户名。
${REGISTRY_PASSWORD} 是外部 registry 的密码。

配置完成后，执行脚本文件 bash ./uploading-ai-cluster-packages.sh，以上传 Alauda AI 和 Knative Operator。

安装 Alauda AI Operator

操作步骤

在 Administrator 视图中：

单击 Marketplace / OperatorHub。
在控制台顶部，从 Cluster 下拉列表中选择您要安装 Alauda AI 的目标集群。
选择 Alauda AI，然后单击 Install。

将弹出 Install Alauda AI 窗口。
然后在 Install Alauda AI 窗口中进行操作。
保持 Channel 不变。
检查 Version 是否与您要安装的 Alauda AI 版本一致。
保持 Installation Location 不变，默认应为 aml-operator。
在 Upgrade Strategy 中选择 Manual。
单击 Install。

验证

确认 Alauda AI 磁贴显示以下状态之一：

Installing：正在安装；请等待其变为 Installed。
Installed：安装完成。

安装 Alauda Build of KServe Operator

有关详细的安装步骤，请参见 Alauda Build of KServe 中的安装 KServe。

启用 Knative 功能

Knative 功能是一个可选能力，需要额外部署一个 operator 和一个实例。

WARNING

如果您计划使用 Knative 功能，必须在创建 Alauda AI 实例之前安装 Knative Operator 并创建 Knative Serving 实例，以确保所需的 CRD 在集群中可用。

1. 安装 Knative Operator

INFO

从 Knative Operator 开始，Knative networking layer 切换为 Kourier，因此不再需要安装 Istio。

操作步骤

在 Administrator 视图中：

单击 Marketplace / OperatorHub。
在控制台顶部，从 Cluster 下拉列表中选择您要安装的目标集群。
搜索并选择 Knative Operator，然后单击 Install。

将弹出 Install Knative Operator 窗口。
然后在 Install Knative Operator 窗口中进行操作。
保持 Channel 不变。
检查 Version 是否与您要安装的 Knative Operator 版本一致。
保持 Installation Location 不变。
在 Upgrade Strategy 中选择 Manual。
单击 Install。

验证

确认 Knative Operator 磁贴显示以下状态之一：

Installing：正在安装；请等待其变为 Installed。
Installed：安装完成。

2. 创建 Knative Serving 实例

安装 Knative Operator 后，您需要手动创建 KnativeServing 实例。

操作步骤

创建 knative-serving 命名空间。
kubectl create ns knative-serving
在 Administrator 视图中，导航到 Operators -> Installed Operators。
选择 Knative Operator。
在 Provided APIs 下找到 KnativeServing，然后单击 Create Instance。
切换到 YAML view。
将内容替换为以下 YAML：

单击 Create。

apiVersion: operator.knative.dev/v1beta1
kind: KnativeServing
metadata:
  name: knative-serving
  namespace: knative-serving
spec:
  # For ACP 4.0, use version 1.18.1
  # For ACP 4.1 and above, use version 1.19.6
  version: "1.18.1"
  config:
    deployment:
      registries-skipping-tag-resolving: kind.local,ko.local,dev.local,private-registry
    domain:
      example.com: ""
    features:
      kubernetes.podspec-affinity: enabled
      kubernetes.podspec-hostipc: enabled
      kubernetes.podspec-hostnetwork: enabled
      kubernetes.podspec-init-containers: enabled
      kubernetes.podspec-nodeselector: enabled
      kubernetes.podspec-persistent-volume-claim: enabled
      kubernetes.podspec-persistent-volume-write: enabled
      kubernetes.podspec-securitycontext: enabled
      kubernetes.podspec-tolerations: enabled
      kubernetes.podspec-volumes-emptydir: enabled
      queueproxy.resource-defaults: enabled
    network:
      domain-template: '{{.Name}}.{{.Namespace}}.{{.Domain}}'
      ingress-class: kourier.ingress.networking.knative.dev
  ingress:
    kourier:
      enabled: true

WARNING

对于 ACP 4.0，请使用版本 1.18.1
对于 ACP 4.1 及以上，请使用版本 1.19.6

指定要部署的 Knative Serving 版本。
private-registry 是您的 private registry 地址的占位符。您可以在 Administrator 视图中，单击 Clusters，选择 your cluster，然后在 Basic Info 部分查看 Private Registry 的值。

创建 Alauda AI 实例

安装 Alauda AI Operator（以及可选的 Knative Operator）后，您可以创建一个 Alauda AI 实例。

操作步骤

在 Administrator 视图中：

单击 Marketplace / OperatorHub。
在控制台顶部，从 Cluster 下拉列表中选择您要安装 Alauda AI Operator 的目标集群。
选择 Alauda AI，然后单击 Click。
在 Alauda AI 页面中，单击选项卡里的 All Instances。
单击 Create。

将弹出 Select Instance Type 窗口。
在 Select Instance Type 窗口中找到 AmlCluster 磁贴，然后单击 Create。

将显示 Create AmlCluster 表单。
Name 保持 default 不变。
从下拉列表中选择 Deploy Flavor：
1. single-node 用于非 HA 部署。
2. ha-cluster 用于 HA 集群部署（生产环境推荐）。
将 KServe Mode 设置为 Managed。
在 Domain 字段中输入一个有效域名。
INFO
该域名由 ingress gateway 用于暴露模型服务。大多数情况下，您会希望使用通配符名称，例如 *.example.com。
您可以通过更新 Domain Certificate Type 字段来指定以下证书类型：
- Provided
- SelfSigned
- ACPDefaultIngress
默认情况下，配置使用 SelfSigned 证书类型来保护到集群的 ingress 流量，证书存储在 Domain Certificate Secret 字段中指定的 knative-serving-cert secret 里。
（可选） 如果您想启用 Knative 功能，请在 Serverless Configuration 部分将 Knative Serving Provider 设置为 Operator。
INFO
如果您在前面的步骤中安装了 Knative Operator 以启用 Serverless 功能，请提供以下参数以完成集成：
- APIVersion: operator.knative.dev/v1beta1
- Kind: KnativeServing
- Name: knative-serving
- Namespace: knative-serving
如果您不使用 Knative 功能，请将 Knative Serving Provider 保持为 Removed（或留空），其余参数保持空白。
在 Gitlab 部分：

WARNING
基于 GitLab 的模型存储已被弃用。它仅保留用于兼容性，并计划在未来的 Alauda AI 版本中移除。对于内置模型和新的模型交付工作流，请改用支持 OCI model artifacts 的 Model Catalog。
1. 在 Base URL 中填写自托管 Gitlab 的 URL。
2. 在 Admin Token Secret Namespace 中填写 cpaas-system。
3. 在 Admin Token Secret Name 中填写 aml-gitlab-admin-token。
在 Model Catalog 部分，配置以下参数：
- Database Password Secret Namespace：包含 Model Catalog 的 PostgreSQL 密码的 secret 所在的命名空间。
- Database Password Secret Name：包含 Model Catalog 的 PostgreSQL 密码的 secret 名称。
  
  请在创建 Alauda AI 实例之前创建该 secret。如果使用以下示例，请将 Database Password Secret Namespace 设置为 aml-operator，并将 Database Password Secret Name 设置为 model-catalog。
  apiVersion: v1 kind: Secret metadata: name: model-catalog namespace: aml-operator stringData: password: <postgres-password> type: Opaque
  1. metadata.name 是 Database Password Secret Name 的值。
  2. metadata.namespace 是 Database Password Secret Namespace 的值。
  3. stringData.password 是明文形式的 PostgreSQL 密码。Kubernetes 在创建 Secret 后会将其存储为 base64 编码的 data.password。
  创建后，保存的 Secret 会有一个 base64 编码的 data.password 字段，例如：
  apiVersion: v1 data: password: cGc= kind: Secret metadata: name: model-catalog namespace: aml-operator type: Opaque
- Model OCI Registry Address：托管 Model Catalog 模型 OCI artifacts 的 registry 地址。默认值为 build-harbor.alauda.cn。
  
  该 registry 存储 Model Catalog 使用的模型 OCI 镜像。请使用 Harbor 或其他启用了 HTTPS 访问的生产模式 OCI registry。Model Catalog 使用的 Harbor project 或 repository 必须允许推理集群节点匿名拉取。
  
  如果在目标环境中无法部署支持 HTTPS 的 registry，可以使用 HTTP registry 作为替代方案。在部署模型之前，请先在推理集群的每个节点上配置容器运行时。对于 containerd，可以为 registry 地址添加不安全 registry mirror，例如通过创建 /etc/containerd/certs.d/<registry-host:port>/hosts.toml：
  server = "http://<registry-host:port>" [host."http://<registry-host:port>"] capabilities = ["pull", "resolve"]
  然后重启 containerd，或通过集群管理系统应用等效的节点运行时配置。此配置必须存在于调度了推理服务 pod 的节点上；否则即使 Model Catalog 能列出模型，pod 的镜像拉取仍会失败。containerd 的具体配置路径可能因 Kubernetes 发行版而异；应用配置后，请验证节点是否可以拉取 Model Catalog 镜像，例如使用 crictl pull <registry-host:port>/<repository>:<tag>。
- Source of PVC：选择复用现有 PVC 还是创建新的 PVC。使用 CreateNew 可让安装过程创建 PVC。
- StorageClass Name：创建新 PVC 时使用的 StorageClass。
检查以上配置，然后单击 Create。

验证

查看名为 default 的 AmlCluster 资源中的状态字段：

kubectl get amlcluster default

应返回 Ready：

NAME      READY   REASON
default   True    Succeeded

导入 Catalog 的内置模型镜像

Alauda AI 的 Catalog 功能随附一组内置的模型 OCI 镜像，用户可以在 Web Console 中将其作为推理服务进行部署。这些镜像必须先导入到 Model Catalog 配置的 OCI registry 中，Catalog 才能提供这些镜像。如果不执行这一步，安装虽然会成功完成，但之后从 Catalog 部署内置模型时会失败，并报 ImagePullBackOff。

获取 OCI 镜像 tarball

内置模型镜像以 OCI archive tarball（符合 OCI Image Layout Specification 的 .tar 文件）形式交付。每个 tarball 都包含一个模型的多架构镜像（linux/amd64 + linux/arm64）。

您可以从 Customer Portal Marketplace 下载这些 tarball，或者联系您的 Alauda support 代表获取与您 Alauda AI 版本匹配的软件包。

推送到 Harbor

推荐的目标 registry 是 Harbor。下面的示例使用的是 HTTP Harbor registry。如果您的 Harbor registry 使用 HTTPS，请省略 --plain-http，并将 API URL 从 http:// 改为 https://。

请在安装了 ctr、curl 和 jq 且能够访问 Harbor 的节点上运行这些命令。

首先，设置环境变量：

export REG=192.168.140.0:32700                
export REPO=mlops/modelcar-qwen3.5-0.8b       
export TAG=v0.1.0                             
export TAR=./Qwen3.5-0.8B.oci.tar             
export AUTH='user:password'

Harbor registry 端点，不包含 URL scheme。
Harbor 中的目标 repository 路径，格式为 <project>/<image-name>。例如，mlops/modelcar-qwen3.5-0.8b 使用的 Harbor project 是 mlops，repository 是 modelcar-qwen3.5-0.8b。
OCI archive 携带的镜像标签。如果您不知道它，可以使用下面的命令从 tarball 中提取。
上一步获取的 OCI archive tarball 路径。
形式为 user:password 的 Harbor 凭据。如果您没有这些凭据，请联系您的平台管理员。

tarball 通常在 OCI image layout 中携带自己的标签（例如 v0.1.0）。如有需要，可从 tarball 中提取该标签：

export TAG=$(tar -xOf "$TAR" index.json \
  | jq -r '.manifests[0].annotations["org.opencontainers.image.ref.name"]')
echo "$TAG"   # should print something like v0.1.0

检查 Harbor 中是否已经存在该镜像标签：

URL="http://$REG/api/v2.0/projects/${REPO%%/*}/repositories/$(printf '%s' "${REPO#*/}" | sed 's|/|%2F|g')/artifacts/$TAG"

HTTP=$(curl -s -u "$AUTH" -o /tmp/harbor-artifact.json -w '%{http_code}' "$URL")

echo "HTTP=$HTTP  URL=$URL"

[ "$HTTP" = 200 ] && jq '{digest, size, push_time, arch: .extra_attrs.architecture, tags: [.tags[].name], platforms: [.references[]?.platform]}' /tmp/harbor-artifact.json \
  || jq -r '.errors[]?.message' /tmp/harbor-artifact.json

如果 Harbor project 还不存在，请在推送前先创建它：

PROJECT="${REPO%%/*}"

curl -s -u "$AUTH" -X POST "http://$REG/api/v2.0/projects" \
  -H 'Content-Type: application/json' \
  -d "{\"project_name\":\"$PROJECT\",\"public\":false}" \
  -w '\nHTTP %{http_code}\n'

如果 project 已存在，Harbor 会返回非 2xx 状态码。确认 project 存在后，继续执行导入和推送。

然后运行导入和推送流程：

# 1. Import into the node's containerd content store.
#    --base-name prepends $REG/$REPO to the tag carried inside the tarball,
#    producing a fully-qualified reference $REG/$REPO:$TAG.
ctr -n k8s.io images import \
  --all-platforms \
  --base-name "$REG/$REPO" \
  "$TAR"

# 2. Verify the import. You should see "$REG/$REPO:$TAG".
ctr -n k8s.io images ls -q | grep "$REPO"

# 3. Push to Harbor. Use --plain-http only for HTTP Harbor.
ctr -n k8s.io images push \
  --plain-http \
  --user "$AUTH" \
  "$REG/$REPO:$TAG"

# 4. Clean up the local reference on the node. Blob data is reclaimed by
#    containerd's garbage collector, leaving no persistent state on the node.
ctr -n k8s.io images rm "$REG/$REPO:$TAG"

对每个内置模型 tarball 重复此流程，并根据每个模型分别调整 $REPO、$TAG 和 $TAR。

INFO

在 import 步骤中，--all-platforms 至关重要：如果省略它，则只会导入节点主机架构对应的内容，随后执行 push 时会静默漏掉其他平台的 blob。push 时不需要该标志——推送多架构索引时会自动推送其引用的所有平台。

验证 Harbor 导入

确认 Harbor 现在可以提供该镜像：

URL="http://$REG/api/v2.0/projects/${REPO%%/*}/repositories/$(printf '%s' "${REPO#*/}" | sed 's|/|%2F|g')/artifacts/$TAG"

HTTP=$(curl -s -u "$AUTH" -o /tmp/harbor-artifact.json -w '%{http_code}' "$URL")

echo "HTTP=$HTTP  URL=$URL"

[ "$HTTP" = 200 ] && jq '{digest, size, push_time, arch: .extra_attrs.architecture, tags: [.tags[].name], platforms: [.references[]?.platform]}' /tmp/harbor-artifact.json \
  || jq -r '.errors[]?.message' /tmp/harbor-artifact.json

HTTP=200 表示镜像已成功导入 Harbor。预期输出包括 digest、size、push time、tag 和 platform 信息：

{
  "digest": "sha256:...",
  "size": 123456789,
  "push_time": "2026-05-06T00:00:00.000Z",
  "arch": "amd64",
  "tags": ["v0.1.0"],
  "platforms": [
    {"architecture": "amd64", "os": "linux"},
    {"architecture": "arm64", "os": "linux"}
  ]
}

现在，Alauda AI 的核心能力已经成功部署完成。如果您想快速体验该产品，请参考快速开始。

FAQ

1. 为 aml-skipper 配置审计输出目录

默认情况下，审计输出路径位于主机上的 /cpaas/audit。但是，在某些操作系统上（例如 MicroOS），主机根路径是只读的，无法创建 /cpaas 目录。在这种情况下，用户需要修改审计输出路径。

要修改审计输出路径，请更新 AmlCluster 默认资源，并在 spec.values 下添加 amlSkipper.auditLogHostPath.path 配置。例如：

apiVersion: amlclusters.aml.dev/v1alpha2
kind: AmlCluster
metadata:
  name: default
  ...
spec:
  ...
  values:
    amlSkipper:
      auditLogHostPath:
        path: /var/lib/audit

NOTE

具体路径应与 Alauda Container Platform Log Collector 的采集配置保持一致。

#安装 Alauda AI

#目录

#下载

#上传

#下载 violet 工具

#上传软件包

#安装 Alauda AI Operator

#操作步骤

#验证

#安装 Alauda Build of KServe Operator

#启用 Knative 功能

#1. 安装 Knative Operator

#操作步骤

#验证

#2. 创建 Knative Serving 实例

#操作步骤

#创建 Alauda AI 实例

#操作步骤

#验证

#导入 Catalog 的内置模型镜像

#获取 OCI 镜像 tarball

#推送到 Harbor

#验证 Harbor 导入

#FAQ

#1. 为 aml-skipper 配置审计输出目录

安装 Alauda AI

目录

下载

上传

下载 violet 工具

上传软件包

安装 Alauda AI Operator

操作步骤

验证

安装 Alauda Build of KServe Operator

启用 Knative 功能

1. 安装 Knative Operator

操作步骤

验证

2. 创建 Knative Serving 实例

操作步骤

创建 Alauda AI 实例

操作步骤

验证

导入 Catalog 的内置模型镜像

获取 OCI 镜像 tarball

推送到 Harbor

验证 Harbor 导入

FAQ

1. 为 aml-skipper 配置审计输出目录