安装 Alauda AI
Alauda AI 现在提供灵活的部署选项。从 Alauda AI 1.4 开始,Knative 能力成为可选功能,如果不需要,可以使用更简化的安装方式。
首先,您需要部署 Alauda AI Operator。这是所有 Alauda AI 产品的核心引擎。默认情况下,它使用 KServe Standard 模式作为推理后端,特别推荐用于资源密集型生成式工作负载。该模式通过利用 Kubernetes 基础功能,提供了一种直接的模型部署方式,并具备强大且可定制的部署能力。
如果您的使用场景需要 Knative 功能,例如用于成本优化的 按需缩容到零 等高级特性,您可以选择安装 Knative Operator。该 operator 不属于默认安装内容,可在任何时候添加以启用 Knative 功能。
推荐的部署选项:对于生成式推理工作负载,推荐使用 Standard 方式(以前称为 RawKubernetes Deployment),因为它对资源分配和扩缩容具有最高的控制能力。
目录
下载上传安装 Alauda AI Operator安装 Alauda Build of KServe Operator启用 Knative 功能1. 安装 Knative Operator2. 创建 Knative Serving 实例配置 Alauda AI 实例导入 Catalog 内置模型镜像FAQ1. 为 aml-skipper 配置审计输出目录下载
Operator Components:
-
Alauda AI Operator
Alauda AI Operator 是驱动 Alauda AI 产品的主引擎。它聚焦于两个核心功能:模型管理和推理服务,并提供了一个可轻松扩展的灵活框架。
下载包:aml-operator.xxx.tgz
-
Knative Operator
Knative Operator 提供无服务器模型推理。
下载包:knative-operator.ALL.v1.x.x-yymmdd.tgz
您可以从 Customer Portal 网站的 Marketplace 中下载名为 ‘Alauda AI’ 和 ‘Knative Operator’ 的应用。
上传
我们需要将 Alauda AI 和 Knative Operator 都上传到要使用 Alauda AI 的集群中。
下载 violet 工具
首先,如果机器上尚未安装 violet 工具,需要先下载它。
登录 Web Console 并切换到 管理员 视图:
- 点击 Marketplace / Upload Packages。
- 点击 Download Packaging and Listing Tool。
- 在 Execution Environment 下找到正确的 OS / CPU 架构。
- 点击 Download 下载
violet工具。 - 运行
chmod +x ${PATH_TO_THE_VIOLET_TOOL}使该工具可执行。
上传软件包
先将以下脚本保存为 uploading-ai-cluster-packages.sh,然后阅读下方注释,更新该脚本中的环境变量配置。
${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
操作步骤
在 管理员 视图中:
-
点击 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 和一个实例。
如果您计划使用 Knative 功能,必须先安装 Knative Operator 并创建 Knative Serving 实例,再配置 Alauda AI 实例,以确保集群中具备所需的 CRD。
1. 安装 Knative Operator
从 Knative Operator 开始,Knative 网络层切换为 Kourier,因此不再需要安装 Istio。
操作步骤
在 管理员 视图中:
-
点击 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命名空间。 -
在 管理员 视图中,导航到 Operators -> Installed Operators。
-
选择 Knative Operator。
-
在 Provided APIs 下找到 KnativeServing,然后点击 Create Instance。
-
切换到 YAML view。
-
将内容替换为以下 YAML:
-
点击 Create。
- 对于 ACP 4.0,请使用版本 1.18.1
- 对于 ACP 4.1 及以上,请使用版本 1.19.6
-
指定要部署的 Knative Serving 版本。
-
private-registry是您的私有 registry 地址占位符。您可以在 管理员 视图中点击 Clusters,选择your cluster,然后在 Basic Info 区域查看 Private Registry 的值。
配置 Alauda AI 实例
安装 Alauda AI Operator(以及可选的 Knative Operator)后,operator 会自动创建 default AmlCluster 实例。您无需手动创建 default 实例。请根据您的环境检查并更新自动创建的实例。
操作步骤
在 管理员 视图中:
-
点击 Marketplace / OperatorHub。
-
在控制台顶部,从 Cluster 下拉列表中选择要安装 Alauda AI Operator 的目标集群。
-
选择 Alauda AI,然后点击它。
-
在 Alauda AI 页面中,点击选项卡中的 All Instances。
-
等待
defaultAmlCluster实例出现,然后编辑它。 -
从下拉列表中选择 Deploy Flavor:
single-node用于非 HA 部署。ha-cluster用于 HA 集群部署(推荐用于生产环境)。
-
将 KServe Mode 设置为 Managed。
-
在 Domain 字段中输入有效域名。
INFO该域名由 ingress gateway 用于暴露模型服务。 通常建议使用通配符域名,例如 *.example.com。
您可以通过更新 Domain Certificate Type 字段指定以下证书类型:
ProvidedSelfSignedACPDefaultIngress
默认情况下,配置使用
SelfSigned证书类型来保护到集群的 ingress 流量,证书存储在 Domain Certificate Secret 字段中指定的knative-serving-certsecret 内。 -
(可选) 配置自定义 OIDC provider。
默认情况下,Alauda AI 使用 ACP Dex 作为 OIDC provider。在此默认 配置中,
AmlCluster实例不需要额外的spec.oidc配置。如果您希望 Alauda AI 使用其他 OIDC provider,请在该 provider 中注册一个 OAuth2/OIDC client,允许 Alauda AI 回调 URL,然后更新
AmlClusterYAML 中的spec.oidc。回调 URL 为:Alauda AI 从 Alauda AI 安装集群中
kubeflow命名空间里的 Kubernetes Secret 读取 OIDC client secret。 默认 Secret 名称为aml-oidc-secret,Secret key 必须为client-secret。使用您的 OIDC provider 的 client secret 更新该 Secret:然后配置
spec.oidc:如果 provider 在
<issuerURL>/.well-known/openid-configuration提供标准 OIDC discovery 文档,当这些字段未设置时, Alauda AI 会自动从 discovery 中填充redeemURL、jwksURL和profileURL。如果无法使用 discovery,请显式配置这些字段:对于
main.loginURL使用映射后的loginURL值;如果您配置了 secondary endpoint,则对secondary.loginURL使用该值。Keycloak 配置示例:
- 在目标 realm 中创建一个 OpenID Connect client。
- 将 Client ID 设置为
spec.oidc.clientID中使用的值,例如aml。 - 打开 Client authentication。
- 在 Authentication flow 下,选择 Standard flow。
- 打开 Require PKCE,并将 PKCE Method 设置为
S256。 - 将 Valid redirect URIs 设置为
https://<platform-address>/clusters/<cluster-name>/aml/*。 - 从 Keycloak client 的 Credentials 选项卡复制 client secret,并
更新上面显示的
aml-oidc-secretSecret。 - 在 client 的 Client scopes 设置中,将
basic、email和profile设置为 Default,并将其他 scope 设置为 Optional,除非您的 环境明确需要它们。请避免添加较大的 claim mapper,例如 groups、realm roles、client roles、address、phone、offline access 以及其他应用特定的 claims,除非确有需要。过大的 token 可能导致 oauth2-proxy cookie 超过浏览器或 ingress header 的大小限制,从而引发登录循环或 HTTP 431/400 错误。
-
(可选) 如果您希望启用 Knative 功能,请更新
AmlClusterYAML 以引用KnativeServing实例:INFO仅当您已安装 Knative Operator 并在前面的步骤中创建了
KnativeServing实例时才配置此项。如果不使用 Knative 功能,请保持此配置未设置。 -
在 Model Catalog 部分,配置以下参数:
-
Model OCI Registry Address:为 Model Catalog 托管模型 OCI 制品的 registry 地址。该字段没有默认值,必须根据您的环境进行配置。
该 registry 用于存储 Model Catalog 使用的模型 OCI 镜像。请使用 Harbor 或其他启用了 HTTPS 访问的生产模式 OCI registry。Model Catalog 不支持为拉取模型 OCI 镜像配置
imagePullSecret,因此用于 Model Catalog 的 Harbor project 或 repository 必须允许推理集群节点匿名拉取。在 Harbor 中,将存储 Model Catalog 镜像的 project 设置为 Public。如果在目标环境中无法部署支持 HTTPS 的 registry,也可以使用 HTTP registry 作为备用方案。请在部署模型之前,先为推理集群中的每个节点配置容器运行时。对于 containerd,可为 registry 地址添加一个不安全的 registry mirror,例如通过创建
/etc/containerd/certs.d/<registry-host:port>/hosts.toml:然后重启 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。
-
-
如果您计划使用
llm-d或vLLM-ascend,请将 KServe Modelcar UID 设置为0。默认值为1000。这是集群级别的设置,会影响 Alauda AI 安装集群中的所有 Modelcar 工作负载。
-
检查配置并保存
defaultAmlCluster实例。
验证
检查名为 default 的 AmlCluster 资源中的状态字段:
应返回 Ready:
导入 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
推荐的目标是 Harbor。以下示例使用 HTTP Harbor registry。如果您的 Harbor registry 使用 HTTPS,请省略 --plain-http,并将 API URL 从 http:// 改为 https://。
请在已安装 ctr、curl 和 jq 且能够访问 Harbor 的节点上运行这些命令。
首先设置环境变量:
- Harbor registry 端点,不包含 URL scheme。
- Harbor 中的目标 repository 路径,格式为
<project>/<image-name>。例如,mlops/modelcar-qwen3.5-0.8b使用 Harbor projectmlops和 repositorymodelcar-qwen3.5-0.8b。 - OCI archive 中携带的镜像标签。如果您不知道,可使用下面的命令从 tarball 中提取。
- 上一步获得的 OCI archive tarball 路径。
- Harbor 凭据,格式为
user:password。如果您没有这些凭据,请联系您的平台管理员。
该 tarball 通常在 OCI image layout 中包含自己的 tag(例如 v0.1.0)。如有需要,可从 tarball 中提取它:
检查该镜像标签是否已存在于 Harbor 中:
如果 Harbor project 尚不存在,请在推送前创建它:
如果 project 已存在,Harbor 会返回非 2xx 状态码。确认 project 已存在后,请确保其配置为公共 project,然后继续导入和推送。Model Catalog 不支持在部署模型 OCI 镜像时配置 imagePullSecret,因此推理集群节点必须能够匿名拉取这些镜像。
然后执行导入和推送操作:
对每个内置模型 tarball 重复此操作,为每个模型分别调整 $REPO、$TAG 和 $TAR。
--all-platforms 在 import 步骤中至关重要:如果省略它,只会导入节点主机架构对应的内容,随后 push 时会静默遗漏另一平台的 blob。该标志在 push 时不需要——推送多架构 index 会自动推送其引用的所有平台。
验证 Harbor 导入
确认 Harbor 现在可以提供该镜像:
HTTP=200 表示镜像已成功导入到 Harbor。预期输出包括 digest、size、push time、tag 和 platform 信息:
至此,Alauda AI 的核心能力已成功部署。如果您想快速体验该产品,请参阅 快速开始。
FAQ
1. 为 aml-skipper 配置审计输出目录
默认的审计输出路径为主机上的 /cpaas/audit。但是,在某些操作系统中(例如 Alauda OS),主机的根路径是只读的,无法创建 /cpaas 目录。在这种情况下,用户需要修改审计输出路径。
要修改审计输出路径,请更新 AmlCluster 默认资源,并在 spec.values 下添加 amlSkipper.auditLogHostPath.path 配置。例如:
具体路径应与 Alauda Container Platform Log Collector 的采集配置保持一致。