安装前配置

准备 GitLab 服务(可选)

基于 GitLab 的模型存储已弃用。除非你仍计划使用旧版基于 GitLab 的 Model Management 工作流,否则在安装新的 Alauda AI 时无需准备 GitLab。

WARNING

基于 GitLab 的模型存储已弃用。该功能目前仅为兼容性保留,计划在未来的 Alauda AI 版本中移除。对于内置模型和新的模型交付工作流,请改用带有 OCI 模型制品的 Model Catalog。

部署选项

1. GitLab 服务要求

无论采用哪种部署方式,所有 GitLab 实例都必须满足以下要求:

  • 版本:必须为 v15 或更高版本。
  • 协议:必须使用 HTTPS。有关设置说明,请参阅 配置 HTTPS。
  • Git LFS:必须启用。有关设置说明,请参阅 使用 LFS 管理大文件。
  • 托管方式:必须为自托管(不支持公有云托管的 GitLab 服务)。
  • 访问令牌:禁用访问令牌的过期日期。

2. 使用平台提供的插件

使用 “Alauda Build of GitLab” 插件部署新的 GitLab 服务。
有关说明,请参阅:部署 Alauda Build of GitLab。

3. 使用你自己的 GitLab 服务

或者,你也可以使用自管理的 GitLab 实例,但它必须满足上述 GitLab 服务要求。

GitLab 配置

如果你仍在使用旧版基于 GitLab 的工作流,请在获取服务后执行以下 GitLab 配置步骤。

1. 禁用访问令牌的过期日期

如果 GitLab 运行的是 v17.0 或更高版本,则需要禁用访问令牌的过期日期。

WARNING

如果访问令牌的过期日期一直保持启用状态,我们就必须至少每年手动刷新一次管理员令牌,否则 Alauda AI 可能会停止正常工作。

要为新的访问令牌禁用过期日期:

  1. 在左侧边栏底部,选择 Admin。
  2. 选择 Settings > General。
  3. 展开 Account and limit。
  4. 取消勾选 Personal / Project / Group access token expiration 复选框。
  5. 选择 Save changes。

2. 生成新令牌

为管理员生成 impersonation token:

  1. 在左侧边栏底部,选择 Admin。
  2. 选择 Overview > Users。
  3. 选择管理员用户(例如 Administrator)。
  4. 在顶部导航栏中,选择 Impersonation Tokens。
  5. 选择 Add new token。
  6. 在弹出的表单中:
    1. 为 Alauda AI 输入一个 Token name(例如 aml-root)。
    2. 删除 Expiration Date(选择 “x” 图标以移除过期日期)。
    3. 在 Select scopes 中勾选所有作用域(尤其是 api 作用域)。
  7. 选择 Create impersonation token。
  8. 将新生成的令牌保存到 Your new impersonation token 下,后续需要使用它。
WARNING

请务必保存新生成的令牌——你将无法再次访问它。

3. 为管理员令牌创建 Kubernetes Secret

然后,我们在 cpaas-system 命名空间下创建一个名为 aml-gitlab-admin-token 的 gitlab 管理员令牌 Secret:

# Please replace ${TOKEN} with real token saved previously
kubectl create secret generic aml-gitlab-admin-token \
  --from-literal="password=${TOKEN}" \
  -n cpaas-system
  1. 创建一个名为 aml-gitlab-admin-token 的 gitlab 管理员令牌 Secret
  2. 令牌保存在 password 键下,请将 ${TOKEN} 替换为之前保存的真实令牌。
  3. 该 Secret 创建在 cpaas-system 命名空间下。

准备 Harbor 服务

如果你计划使用 Model Catalog 功能,请在安装 Alauda AI 之前准备一个 Alauda Build of Harbor 服务。该镜像仓库必须满足以下要求:

  • 以生产模式运行。生产环境部署请使用 HTTPS。
  • 允许推理集群节点在无需镜像拉取凭据的情况下拉取 Model Catalog 镜像。

如果你无法在目标环境中部署 HTTPS 镜像仓库,也可以将 HTTP 镜像仓库作为备用方案,但在部署模型之前必须先配置推理集群的容器运行时。有关详细的 containerd 配置,会在创建 Alauda AI 实例时设置 Model OCI Registry Address 的过程中说明。

有关安装步骤,请参阅 部署 Alauda Build of Harbor。

常见问题(FAQ)

1. 如何优化 GitLab 18.5 及更高版本对大 LFS 对象的配置?

问题:
当向 GitLab 18.5 及更高版本推送大型 LFS 对象时,可能会遇到 HTTP 413 错误。对于 AI 模型管理,通常需要通过 LFS 上传大型模型文件,这些文件会超过 Nginx ingress controller 中默认的 proxy-body-size 限制(通常为 512M)。

以下内容为 Git LFS 客户端的真实诊断输出;其中的 %!!(string=...) 片段是原始的 Go 格式化产物,可以忽略——请重点关注 HTTP 413 响应,它才是需要处理的错误。

❯ git push origin main
Locking support detected on remote "origin". Consider enabling it with:
  $ git config lfs.https://gitlab-18-5-aml.alaudatech.net/mlops-demo-ai-test/amlmodels/qa.git/info/lfs.locksverify true
LFS: Client error &{%!!(string=https) %!!(string=) %!!(*url.Userinfo=<nil>) %!!(string=gitlab-18-5-aml.alaudatech.net) %!!(string=/mlops-demo-ai-test/amlmodels/qa.git/gitlab-lfs/objects/fdf756fa7fcbe7404d5c60e26bff1a0c8b8aa1f72ced49e7dd0210fe288fb7fe/988097824) %!!(string=) %!!(bool=false) %!!(bool=false) %!!(string=) %!!(string=) %!!(string=)}s(MISSING) from HTTP 413
Uploading LFS objects:   0% (0/1), 0 B | 0 B/s, done.
error: failed to push some refs to 'https://gitlab-18-5-aml.alaudatech.net/mlops-demo-ai-test/amlmodels/qa.git'

解决方案:
为处理大文件上传并提升整体性能,请通过 spec.helmValues.gitlab.webservice.ingress 配置 GitLab webservice ingress 的请求体大小和读取超时,并通过 GitLab 服务上的注解配置其余 Nginx Ingress 行为。

Webservice Ingress 设置

在 spec.helmValues.gitlab.webservice.ingress 下配置以下字段:

字段推荐值描述
proxyBodySize"0"禁用客户端请求体大小限制,允许通过 Git LFS 上传大型 AI 模型。
proxyReadTimeout"3600"将从代理服务器读取响应的超时时间(秒)提高到 1 小时,避免在长时间运行的操作期间发生超时。

Ingress 注解参数

以下是推荐的 Ingress 注解及其功能:

参数推荐值描述
nginx.ingress.kubernetes.io/proxy-buffering"off"禁用代理缓冲,提升大请求的响应速度,并允许数据直接流式传输到客户端/服务器。
nginx.ingress.kubernetes.io/proxy-request-buffering"off"禁用客户端请求体缓冲,直接将数据传递给上游服务器,从而减少 ingress controller 的内存使用。
nginx.ingress.kubernetes.io/proxy-send-timeout"3600"将向代理服务器发送请求的超时时间(秒)提高到 1 小时,以支持持续较长时间的上传。

配置步骤

你可以通过更新 GitLabOfficial 自定义资源(CR)来应用这些优化。

1. 使用 kubectl patch 命令应用

使用以下命令直接更新 GitLabOfficial CR 中的 GitLab webservice ingress 设置和 ingress 注解:

# Update GitLabOfficial CR with optimized ingress settings
# [!code callout:1,2]
kubectl patch gitlabofficial your-instance-name -n your-instance-namespace --type=merge -p '{
  "spec": {
    "helmValues": {
      "gitlab": {
        "webservice": {
          "ingress": {
            "proxyBodySize": "0",
            "proxyReadTimeout": "3600"
          }
        }
      },
      "global": {
        "ingress": {
          "annotations": {
            "nginx.ingress.kubernetes.io/proxy-buffering": "off",
            "nginx.ingress.kubernetes.io/proxy-request-buffering": "off",
            "nginx.ingress.kubernetes.io/proxy-send-timeout": "3600"
          }
        }
      }
    }
  }
}'
  1. 将 your-instance-name 替换为你的 GitLabOfficial 实例名称(例如,gitlab-aml)。
  2. 将 your-instance-namespace 替换为部署 GitLabOfficial 实例的命名空间(例如,gitlab-system-aml)。

2. YAML 层级参考

作为参考,GitLabOfficial CR 的 spec 中层级结构如下:

apiVersion: operator.alaudadevops.io/v1alpha1
kind: GitLabOfficial
metadata:
  name: gitlab-aml
  namespace: gitlab-system-aml
spec:
  # ... other specs ...
  helmValues:
    gitlab:
      webservice:
        ingress:
          proxyBodySize: "0"
          proxyReadTimeout: "3600"
    global:
      ingress:
        annotations:
          nginx.ingress.kubernetes.io/proxy-buffering: "off"
          nginx.ingress.kubernetes.io/proxy-request-buffering: "off"
          nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
  1. 这些优化可确保 GitLab 18.5 能够通过 Git LFS 无缝处理大型 AI 模型上传,并提升整体数据传输稳定性。
  2. 我们强烈建议在 GitLab 初始部署期间应用这些配置,以避免部署后的运行问题。