使用教程
本页目录
使用教程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: 静默模式,无额外输出。
- 在 GNU/Linux 和 macOS 上:
- 将生成两个文件。如果您使用上面的示例命令,它们将位于您的当前路径中:
- 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. 错误报告、问题和故障排除
请通过以下方式向我们报告问题:
- 电子邮件:wangzr@cloudsway.com
- 技术支持组