全部开发文档
选择文档

使用教程

本页目录使用教程1. 概念2. 创建您的第一个堆栈2.1 准备 SSH 密钥对2.2 定义并创建堆栈3. 部署您的第一个 AI 模型连接到您的集群快速开始和测试手动启动和测试4. 自动化管理5. 错误报告、问题和故障排除

使用教程


1. 概念

  • 堆栈/集群: 由 ScaleX 在您的 AWS 账户上管理的 Kubernetes 集群。
    • *每个堆栈/集群都有一个唯一的堆栈 ID。
  • 工作节点组: 具有相同规格和实例类型的工作节点组。
    • *在堆栈/集群中,每个工作节点组都有一个唯一的名称。
  • 工作节点: 集群中作为 Kubernetes 工作节点运行的实例。有几种类型:
    • fixed_od: 一个在堆栈生命周期内不会切换到竞价实例的按需实例。
    • od: 一个动态的按需实例,可能会被 ScaleX 自动切换到竞价实例。
    • spot: 一个可能会被中断的竞价实例。ScaleX 会自动处理中断。
  • nat: 堆栈中为私有子网提供互联网访问的实例。
  • 主节点: Kubernetes 堆栈中运行控制平面的实例。
  • 自动扩展: 应用于工作节点组的功能,可根据工作负载扩展或缩减节点数量。有几种选项:
    • full: 组可以扩展(添加节点)或缩减(删除节点)。
    • up: 组只允许扩展(添加节点)。
    • down: 组只允许缩减(删除节点)。
    • off: 关闭自动扩展。
  • schedule_priority: 当竞价实例失败时,'region' 优先级会更频繁地触发跨可用区迁移,而 'az' 优先级会更频繁地触发竞价实例到按需实例的切换。
  • 高可用性: 通过提供和管理冗余资源,堆栈将更加可靠。

2. 创建您的第一个堆栈

2.1 准备 SSH 密钥对

我们建议使用 OpenSSH 工具来生成 SSH 密钥对。通常,OpenSSH 已预装在您的操作系统中(Windows、macOS 或 GNU/Linux)。

  • 打开终端(在 POSIX 系统上)或命令提示符窗口(在 Windows 上)。
  • 输入命令创建密钥对(非常重要:执行命令前请务必确认当前的终端环境):
    • 在 GNU/Linux 和 macOS 上: ssh-keygen -t rsa -N '' -f ./scalex_ssh_rsa -q
    • 在 Windows CMD 命令提示符中:ssh-keygen -t rsa -N "" -f ./scalex_ssh_rsa -q (请注意 -N 之后是双引号)
    • 在 Windows PowerShell 中:ssh-keygen -t rsa -N '""' -f ./scalex_ssh_rsa -q (请注意 -N 之后是由单引号包裹的双引号)
    • 在 Windows GitBash 等兼容 POSIX 命令格式的环境中,请使用与 GNU/Linux 和 macOS 相同的命令即可
    • 各个参数的解释:
      • -t: 密钥对的类型(算法)。您可以指定 -t rsa (推荐,兼容性好)或 -t ed25519。
      • -N: 指定一个密码短语,请留空。
      • -f: 密钥对输出的路径。
      • -q: 静默模式,无额外输出。
  • 将生成两个文件。如果您使用上面的示例命令,它们将位于您的当前路径中:
    • scalex_ssh_rsa: 私钥。请务必谨慎管理此密钥,切勿将其传输给任何不可信的第三方!
    • scalex_ssh_rsa.pub: 公钥。稍后您可以使用 --pk-file 、--pk-text 或 --pk-b64 命令行参数将它注入到您的集群中。
  • 更改您的私钥的权限。SSH 要求权限模式为 600。
    • 在 Windows 上:右键单击私钥文件 -> 属性 -> 安全 -> 从权限列表中移除其他用户。
    • 在 POSIX 系统(GNU/Linux 或 macOS)上:chmod 600 ./scalex_ssh_rsa。

完成上述步骤后,您的 SSH 密钥对应该就可以使用了。

2.2 定义并创建堆栈

每个堆栈/集群均通过一个 JSON 格式的文件进行预定义。请参考示例文件 cluster_config_ha.json 和 cluster_config_no_ha.json。其中,cluster_config_ha.json 适用于高可用性(High Availability)场景,而 cluster_config_no_ha.json 则适用于非高可用性/基础可用性场景。

代码示例
{
    "region": "us-east-2",              # 一个有效的 AWS 区域名称
    "high_availability": {              # 高可用性。您可以将其指定为 'false' 以关闭 HA
        "nat_count": 3,                 # NAT 实例的数量
        "jumpserver_instance_type": {   # jumpserver 配置。您也可以指定实例类型名称
            "cpu_arch": "x86_64",       # jumpserver 搜索项 - CPU 架构
            "cpu_providers": ["amd"],   # jumpserver 搜索项 - CPU 提供商
            "vcpu_count": 2,            # jumpserver 搜索项 - vCPU 数量
            "memory_gb": 4              # jumpserver 搜索项 - RAM(GiB)
        }
    },
    "cni_name": "calico",               # 集群网络插件,仅支持 flannel 和 calico
    "management_nodes": {               # 管理节点配置
        "nat_instance_type": {          # NAT 配置。您也可以指定实例类型名称
            "cpu_arch": "x86_64",
            "cpu_providers": ["amd"],
            "vcpu_count": 2,
            "memory_gb": 4
        },
        "master_instance_type": "c7a.xlarge"  # master 配置。您也可以指定搜索项
    },
    "worker_groups": [                        # 工作节点组,它是一个列表[字典]
        {
            "group_name": "a10_group",        # 组的唯一名称
            "kata_enabled": false,            # 是否安装 Kata 安全容器(需要嵌套虚拟化支持)
            "instance_type": {                # 工作节点配置。您也可以指定实例类型名称
                "cpu_arch": "x86_64",
                "cpu_providers": [],
                "vcpu_count": {
                    "start": 1,
                    "end": 16
                },
                "memory_gb": {
                    "start": 32,
                    "end": 10000
                },
                "mem_per_cpu_gb": {
                    "start": 0,
                    "end": 1000000
                },
                "acc_names": ["a10g"],      # 加速器(GPU)名称
                "acc_count": {              # 每个节点的加速器(GPU)数量
                    "start": 1,
                    "end": 1
                }
            },
            "init_workers": {
                "total_workers": 1,         # 初始总工作节点数
                "od_workers": 1,            # 初始按需工作节点数
                "fixed_workers": 0,         # 固定按需工作节点数
            }
            "schedule_priority": "",        # 可用区优先或区域优先(默认)
            "os_disk_gb": 10,               # OS 卷/磁盘大小
            "container_disk_ini_gb": 20,    # 容器初始卷/磁盘大小
            "container_disk_max_gb": 300,   # 容器最大卷/磁盘大小
            "autoscaling": "full",          # 自动扩展策略
            "od_to_spot": {                 # 按需实例到竞价实例的切换计划
                                            # 您可以指定一个空字典以禁用 od_to_spot
                                            # 或者,您可以指定一个 'copy_from' 从另一个
                                            # 工作节点组复制
                "rate_in_minutes": 15,
                "delay_in_minutes": 15
            }
        },
        {
            "group_name": "cpu_group",
            "instance_type": "c7a.xlarge",
            "init_workers": {
                "total_workers": 1,
                "od_workers": 1,
                "fixed_workers": 0
            }
            "schedule_priority": "",
            "os_disk_gb": 10,
            "container_disk_ini_gb": 20,
            "container_disk_max_gb": 300,
            "autoscaling": "off",
            "od_to_spot": {
                "copy_from": "a10_group"    # 您可以指定一个空字典以禁用 od_to_spot
            }
        }
    ]
}

使用上述 JSON 文件(假设其路径为 /home/my/cluster_config.json),您可以运行以下命令:

./scalex-cmd create --config-file /home/my/cluster_config_ha.json --pk-file ./scalex_ssh_rsa.pub --ssh-private-key-path ./scalex_ssh_rsa --key-name my-first-key.b7dp2u341ig

重要说明:

  • 从最新版本开始,--ssh-private-key-path 参数是必需的
  • ScaleX 将在创建集群之前验证您的公钥和私钥是否匹配
  • 私钥将被安全地复制到 ~/.scalex/ssh_keys/ 以用于集群管理操作
  • 这确保了 ScaleX 可以在执行 scale 命令期间执行远程操作(如 kubectl drain)

如果一切顺利,将生成一个初始堆栈。控制台输出类似于:

代码示例
Checking the ingested request attributes ...
The format of configs is checked and good to go.
Checking the contents of the configs.
Worker group: a10_group will use instance type: g5.xlarge.
Worker group: cpu_group will use instance type: c5a.xlarge.
[*] scalex (scale-x) kubernetes stack started creating ...
Stack id: k8s-lml6uq7wbk5e
...
...
...
Worker group: cpu_group provision summary: spot: 1 | od: 1 | total: 2
Worker group: cpu_group: All planned 2 node(s) provisioned.

Scalex k8s stack summary:
...

Please connect to the cluster: ssh ubuntu@XXX.XXX.XXX.XXX -i /your/private/key
[*] The IP address above is *elastic* and will keep unchanged during the lifecycle of this cluster.

3. 部署您的第一个 AI 模型

注意:在本演示中,我们使用 huggingface 获取演示模型:DeepSeek-R1-Distill-Qwen-7B。如您希望继续按照本教程完成下列步骤,清注册 huggingface 账号并获取一个有效的 Token。

连接到您的集群

使用您的私钥登录到您的集群(公共密钥已注入到主节点,并且 IP 地址已回显):

ssh ubuntu@10.10.10.10 -i /my/private/key

请将示例 IP 地址和示例私钥路径更改为实际值。

高可用性集群的重要提示: ssh ubuntu@10.10.10.10 -i /my/private/key 将登录到 jumpserver。 登录到 jumpserver 后,请运行: ssh master-xxxxxxx -i /etc/scalex/ubuntu-ssh 跳转到任意 master 节点。master 节点已自动记录到 jumpserver 的 /etc/hosts 中。

快速开始和测试

集群已经在 master 节点上内置了一个演示,用于部署和测试 DeepSeek-R1-Distill-Qwen-7B,您可以运行:

ubuntu@master:~$ sudo /home/ubuntu/scalex-examples/demo_deepseek.py YOUR_HUGGING_FACE_TOKEN

请将示例令牌字符串 YOUR_HUGGING_FACE_TOKEN 更改为实际有效的令牌

手动启动和测试

创建命名空间

首先,您可以创建一个命名空间:

kubectl create namespace deepseek

导入 Huggingface 令牌

将 huggingface 令牌导入到命名空间 deepseek:

kubectl create secret generic huggingface-token --from-literal=HF_TOKEN=hf_xxx.... -n deepseek

请将示例令牌字符串 hf_xxx.... 更改为实际有效的令牌

部署模型

接下来,请在主节点上创建一个 YAML 文件(deepseek.yaml)以部署 DeepSeek-R1-Distill-Qwen-7B。此 YAML 模板将在您的集群中创建一个 3 个副本的部署。

代码示例
apiVersion: apps/v1  
kind: Deployment  
metadata:  
  name: deepseek-deployment  
  namespace: deepseek  
  labels:  
    app: deepseek  
spec:  
  replicas: 3
  selector:  
    matchLabels:  
      app: deepseek  
  template:  
    metadata:  
      labels:  
        app: deepseek  
    spec:  
      tolerations:  
        - key: "nvidia.com/gpu"  
          operator: "Exists"  
          effect: "NoSchedule"  
      volumes:  
      - name: cache-volume  
        hostPath:  
          path: /tmp/deepseek  
          type: DirectoryOrCreate  
      - name: shm  
        emptyDir:  
          medium: Memory  
          sizeLimit: "2Gi"  
      containers:  
      - name: deepseek  
        image: vllm/vllm-openai:latest  
        command: ["/bin/sh", "-c"]  
        args: [  
          "vllm serve deepseek-ai/DeepSeek-R1-Distill-Qwen-7B  --trust-remote-code --max_model_len 2048"  
        ]  
        env:
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: huggingface-token
              key: HF_TOKEN
        ports:  
        - containerPort: 8000  
        resources:  
          requests:  
            nvidia.com/gpu: "1"  
          limits:  
            nvidia.com/gpu: "1"  
        volumeMounts:  
        - mountPath: /root/.cache/huggingface  
          name: cache-volume  
        - name: shm  
          mountPath: /dev/shm  
---  
apiVersion: v1  
kind: Service  
metadata:  
  name: deepseek-svc  
  namespace: deepseek  
spec:  
  ports:  
  - name: http  
    port: 80  
    protocol: TCP  
    targetPort: 8000
  selector:  
    app: deepseek  
  type: ClusterIP

请根据您的实际堆栈配置调整内容。

接下来,请运行 kubectl apply -f deepseek.yaml。Pod 将被调度到工作节点上。

测试您的模型

通过以下命令暴露服务:kubectl port-forward svc/deepseek-svc -n deepseek 8080:80

使用 cURL 测试服务:

curl http://localhost:8080/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"deepseek-ai/DeepSeek-R1-Distill-Qwen-7B", "messages": [{"role":"system","content":"You are a helpful assistant."}, {"role":"user","content":"Who created Unix?"}]}'

如果一切顺利,您将从本地模型 deepseek-ai/DeepSeek-R1-Distill-Qwen-7B 收到响应/输出。

4. 自动化管理

ScaleX 集群是完全动态和完全托管的。这意味着,您无需在以下情况下管理资源:

  • 竞价实例在任何时候被中断
  • 竞价实例可用于替换高价的按需实例
  • 新部署被调度但当前资源不足
  • 部署被删除并使一些工作节点闲置

因此,您可以专注于您的应用程序、部署以及其他工作负载,ScaleX 旨在自动处理所有维护工作。为实现这一目标,ScaleX 在您的堆栈下运行多个低成本的 AWS 服务,它们是:

  • Lambda 函数
  • AWS EventBridge 规则
  • CloudWatch 日志
  • AWS EventBridge 调度
  • S3 存储桶

请注意,这些服务可能会产生额外的少量费用。有关计费和费用的详细信息,请参阅 AWS 官方网站。

5. 错误报告、问题和故障排除

请通过以下方式向我们报告问题:

您的 AI 之旅,从这里启航

作为专为开发者与企业打造的前沿 AI 基础设施,
我们将为您提供完善的 AI 基础设施与专业指导,助力打造最适合您业务的完美解决方案。

联系我们