Kthena¶

Kthena 是一個原生於 Kubernetes 的 LLM 推理平臺，它改變了組織在生產環境中部署和管理大型語言模型的方式。它構建於宣告式模型生命週期管理和智慧請求路由之上，為 LLM 推理工作負載提供了高效能和企業級的可伸縮性。

本指南將演示如何在 Kubernetes 上部署生產級的多節點 vLLM 服務。

我們將

安裝所需的元件（Kthena + Volcano）。
透過 Kthena 的 ModelServing CR 部署多節點 vLLM 模型。
驗證部署。

1. 先決條件¶

您需要

一個具有GPU 節點的 Kubernetes 叢集。
具有 cluster-admin 或同等許可權的 kubectl 訪問許可權。
已安裝的Volcano，用於作業排程。
已安裝的Kthena，且 ModelServing CRD 可用。
如果從 Hugging Face Hub 載入模型，則需要有效的Hugging Face 令牌。

1.1 安裝 Volcano¶

helm repo add volcano-sh https://volcano-sh.github.io/helm-charts
helm repo update
helm install volcano volcano-sh/volcano -n volcano-system --create-namespace

這提供了 Kthena 使用的作業排程和網路拓撲功能。

1.2 安裝 Kthena¶

helm install kthena oci://ghcr.io/volcano-sh/charts/kthena --version v0.1.0 --namespace kthena-system --create-namespace

將建立 kthena-system 名稱空間。
Kthena 控制器和 CRD（包括 ModelServing）已安裝並執行正常。

驗證

kubectl get crd | grep modelserving

您應該會看到

modelservings.workload.serving.volcano.sh   ...

2. 多節點 vLLM `ModelServing` 示例¶

Kthena 提供了一個示例清單，用於部署一個執行 Llama 的多節點 vLLM 叢集。概念上，這等同於 vLLM 生產棧的 Helm 部署，但用 ModelServing 來表達。

示例（llama-multinode）的簡化版本如下所示：

spec.replicas: 1 – 一個 ServingGroup（一個邏輯模型部署）。
roles:
- entryTemplate – 定義執行的leader Pod，包括
  - vLLM 的多節點叢集引導指令碼（Ray 叢集）。
  - vLLM 相容 OpenAI 的 API 伺服器。
- workerTemplate – 定義加入 leader 的 Ray 叢集的worker Pod。

示例 YAML 的關鍵點

映象：vllm/vllm-openai:latest（與上游 vLLM 映象匹配）。
命令（leader）

command:
  - sh
  - -c
  - >
    bash /vllm-workspace/examples/online_serving/multi-node-serving.sh leader --ray_cluster_size=2;
    python3 -m vllm.entrypoints.openai.api_server
      --port 8080
      --model meta-llama/Llama-3.1-405B-Instruct
      --tensor-parallel-size 8
      --pipeline-parallel-size 2

命令（worker）

command:
  - sh
  - -c
  - >
    bash /vllm-workspace/examples/online_serving/multi-node-serving.sh worker --ray_address=$(ENTRY_ADDRESS)

3. 透過 Kthena 部署多節點 llama vLLM¶

3.1 準備清單¶

推薦：使用 Secret 而不是原始環境變數

kubectl create secret generic hf-token \
  -n default \
  --from-literal=HUGGING_FACE_HUB_TOKEN='<your-token>'

3.2 應用 `ModelServing`¶

cat  <<EOF | kubectl apply -f -
apiVersion: workload.serving.volcano.sh/v1alpha1
kind: ModelServing
metadata:
  name: llama-multinode
  namespace: default
spec:
  schedulerName: volcano
  replicas: 1  # group replicas
  template:
    restartGracePeriodSeconds: 60
    gangPolicy:
      minRoleReplicas:
        405b: 1
    roles:
      - name: 405b
        replicas: 2
        entryTemplate:
          spec:
            containers:
              - name: leader
                image: vllm/vllm-openai:latest
                env:
                  - name: HUGGING_FACE_HUB_TOKEN
                    valueFrom:
                      secretKeyRef:
                        name: hf-token
                        key: HUGGING_FACE_HUB_TOKEN
                command:
                  - sh
                  - -c
                  - "bash /vllm-workspace/examples/online_serving/multi-node-serving.sh leader --ray_cluster_size=2; 
                    python3 -m vllm.entrypoints.openai.api_server --port 8080 --model meta-llama/Llama-3.1-405B-Instruct --tensor-parallel-size 8 --pipeline-parallel-size 2"
                resources:
                  limits:
                    nvidia.com/gpu: "8"
                    memory: 1124Gi
                    ephemeral-storage: 800Gi
                  requests:
                    ephemeral-storage: 800Gi
                    cpu: 125
                ports:
                  - containerPort: 8080
                readinessProbe:
                  tcpSocket:
                    port: 8080
                  initialDelaySeconds: 15
                  periodSeconds: 10
                volumeMounts:
                  - mountPath: /dev/shm
                    name: dshm
            volumes:
            - name: dshm
              emptyDir:
                medium: Memory
                sizeLimit: 15Gi
        workerReplicas: 1
        workerTemplate:
          spec:
            containers:
              - name: worker
                image: vllm/vllm-openai:latest
                command:
                  - sh
                  - -c
                  - "bash /vllm-workspace/examples/online_serving/multi-node-serving.sh worker --ray_address=$(ENTRY_ADDRESS)"
                resources:
                  limits:
                    nvidia.com/gpu: "8"
                    memory: 1124Gi
                    ephemeral-storage: 800Gi
                  requests:
                    ephemeral-storage: 800Gi
                    cpu: 125
                env:
                  - name: HUGGING_FACE_HUB_TOKEN
                    valueFrom:
                      secretKeyRef:
                        name: hf-token
                        key: HUGGING_FACE_HUB_TOKEN
                volumeMounts:
                  - mountPath: /dev/shm
                    name: dshm   
            volumes:
            - name: dshm
              emptyDir:
                medium: Memory
                sizeLimit: 15Gi
EOF

Kthena 將會

建立一個 ModelServing 物件。
為 Volcano 作業排程派生一個 PodGroup。
為每個 ServingGroup 和 Role 建立 leader 和 worker Pod。

4. 驗證部署¶

4.1 檢查 ModelServing 狀態¶

使用 Kthena 文件中的程式碼片段

kubectl get modelserving -oyaml | grep status -A 10

您應該會看到類似以下內容：

status:
  availableReplicas: 1
  conditions:
    - type: Available
      status: "True"
      reason: AllGroupsReady
      message: All Serving groups are ready
    - type: Progressing
      status: "False"
      ...
  replicas: 1
  updatedReplicas: 1

4.2 檢查 Pod¶

列出您的部署的 Pod

kubectl get pod -owide -l modelserving.volcano.sh/name=llama-multinode

示例輸出（來自文件）

NAMESPACE   NAME                          READY   STATUS    RESTARTS   AGE   IP            NODE           ...
default     llama-multinode-0-405b-0-0    1/1     Running   0          15m   10.244.0.56   192.168.5.12   ...
default     llama-multinode-0-405b-0-1    1/1     Running   0          15m   10.244.0.58   192.168.5.43   ...
default     llama-multinode-0-405b-1-0    1/1     Running   0          15m   10.244.0.57   192.168.5.58   ...
default     llama-multinode-0-405b-1-1    1/1     Running   0          15m   10.244.0.53   192.168.5.36   ...

Pod 名稱模式

llama-multinode-<group-idx>-<role-name>-<replica-idx>-<ordinal>.

第一個數字表示 ServingGroup。第二個數字（405b）是 Role。剩餘的索引標識了該角色中的 Pod。

6. 訪問 vLLM 相容 OpenAI API¶

透過 Service 暴露入口

apiVersion: v1
kind: Service
metadata:
  name: llama-multinode-openai
  namespace: default
spec:
  selector:
    modelserving.volcano.sh/name: llama-multinode
    modelserving.volcano.sh/entry: "true"
    # optionally further narrow to leader role if you label it
  ports:
    - name: http
      port: 80
      targetPort: 8080
  type: ClusterIP

從您的本地機器埠轉發

kubectl port-forward svc/llama-multinode-openai 30080:80 -n default

然後

列出模型

curl -s https://:30080/v1/models

傳送一個完成請求（映象 vLLM 生產棧文件）

curl -X POST https://:30080/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.1-405B-Instruct",
    "prompt": "Once upon a time,",
    "max_tokens": 10
  }'

您應該會收到來自 vLLM 的 OpenAI 風格的響應。

7. 清理¶

要刪除部署及其資源

kubectl delete modelserving llama-multinode -n default

如果您不再需要整個堆疊

helm uninstall kthena -n kthena-system   # or your Kthena release name
helm uninstall volcano -n volcano-system