搭配 Run:ai Model Streamer 使用雲端儲存分散式加速器 (預覽)

Run:ai Model Streamer 會同時讀取模型張量並將其串流至 GPU 記憶體,同時將儲存體讀取與 CPU 到 GPU 的傳輸重疊進行。 此功能可縮短模型載入時間,並減少推論伺服器啟動與水平擴充時 GPU 閒置時間。利用此功能將 Azure Blob 儲存體 的 SafeTensors 模型載入 vLLM,因為它支援直接物件儲存載入,並與 vLLM 的模型載入器整合。 關於上游整合,請參見 使用 Run:ai Model Streamer 載入模型。

使用雲端儲存分散式加速器 (DACS),此載入路徑也能重複使用不同工作負載所快取的模型資料。 vLLM 使用 Run:ai 的 Azure 後端來載入 DACS 原生客戶端函式庫。 讀取會讀取快取資料,或從 Blob 儲存體 擷取缺少的資料。

本文使用 Run:ai Model Streamer 0.17.3、公開的 dacs-client==0.1.0 套件,以及 v0.1.0 伺服器組建。 主要程序會在您的工作負載映像中安裝相依性。 它不需要另外的 DACS 用戶端映像檔或 Kubernetes ImageVolume 支援。

在使用本文前,請先完成 AKS 上雲端儲存的分散式加速器快速入門。 若想提供 DACS 用戶端函式庫而不需重建您的工作負載映像檔,請參考 使用 ImageVolume 掛載 DACS 用戶端函式庫 的說明。

Prerequisites

  • 一個現有的 DACS 部署及其發現服務主機名稱。
  • 一個 AKS GPU 節點池,搭配相容的 NVIDIA 驅動程式、裝置外掛,以及足夠供你的模型使用的 GPU 記憶體。 以下範例使用 bfloat16,需要相容的 GPU。
  • 若要使用工作負載身分識別驗證,需有已啟用 OIDC 簽發者和 Microsoft Entra 工作負載 ID 的 AKS 叢集。 請參閱在 AKS 叢集上啟用 OIDC 發行者和 Microsoft Entra 工作負載 ID。
  • 一個相容的 GPU vLLM 映像檔,以及使用 glibc 2.35 或更新版本的 Linux 環境。 使用和你的應用程式相同的 Python 環境。
  • 一個用於模型檔案的私人 Blob 容器。
  • 具備模型容器上 Storage Blob Data Contributor 角色的獨立上傳使用者或受控識別。
  • 在模型容器上具有儲存體 Blob 資料讀取者角色的推論身分識別。 在 配置 Blob 認證中設定一種方法。
  • 建立並推送你的工作負載映像檔的權限,以及讓 AKS 拉取該映像檔的權限。
  • 若需要上傳模型,請在你的準備機器上安裝 Azure CLI、AzCopy v10 和 Hugging Face CLI。

模型準備不需要 GPU。 你也可以在 CPU 節點上使用相容的應用程式映像檔,檢查套件安裝、原生函式庫載入,以及 Blob 驗證。 這些檢查並不能驗證 GPU 排程、記憶體容量配置或推論。

將模型檔案上傳到 Blob 儲存體

如果完整模型已經在你的私人容器中,請跳過這部分。 進行冷快取測試時,請使用您尚未透過 DACS 讀取過的模型前置詞。

此程序使用上傳者身份,而非推論身份。 關於容器範圍的角色指派,請參見「指派 Azure 角色以存取 Blob 資料」。 Azure control-plane Owner 或 Contributor 本身不會透過 Microsoft Entra ID 授予 Blob 資料存取權限。

下載模型

以下範例下載了固定修訂版本的 SmolLM2-135M-Instruct 推論檔案。 其模型卡上標示授權為 Apache-2.0。 安裝 Hugging Face CLI,然後執行:

MODEL_ID="HuggingFaceTB/SmolLM2-135M-Instruct"
MODEL_REVISION="12fd25f77366fa6b3b4b768ec3050bf629380bac"
MODEL_DIR="$PWD/models/SmolLM2-135M-Instruct-$MODEL_REVISION"

hf download "$MODEL_ID" \
  config.json generation_config.json model.safetensors \
  tokenizer.json tokenizer_config.json special_tokens_map.json \
  vocab.json merges.txt README.md \
  --revision "$MODEL_REVISION" \
  --local-dir "$MODEL_DIR"

可選擇使用目前 CLI 的 hf cache verify 指令,驗證下載的檔案是否與 Hub 的校驗和相符:

hf cache verify "$MODEL_ID" \
  --revision "$MODEL_REVISION" \
  --local-dir "$MODEL_DIR"

由於此下載僅選擇推論檔案,驗證可報告遺失的儲存庫檔案,如未使用的模型變體。 它也能回報額外的本地 Hugging Face 下載元資料。 這些訊息不是檢查碼錯誤。 在上傳前調查意外檔案或校驗碼不符。

對於其他模型,包含所有 SafeTensor 碎片、任何權重索引、模型與生成設定、分詞器檔案,以及適用的授權與歸因檔案。 保留所需的目錄結構。 不要暫存不相關的 ONNX 變體、訓練檢查點、優化器檔案或憑證。

使用 AzCopy 上傳

安裝 AzCopy v10。 透過 Azure CLI 以上傳使用者身份登入,然後將本地目錄的內容複製到新的 Blob 前綴:

TENANT_ID="<tenant-id>"
STORAGE_ACCOUNT="<storage-account>"
CONTAINER="<container>"
RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)"
MODEL_PREFIX="models/SmolLM2-135M-Instruct-${MODEL_REVISION}-${RUN_ID}"
MODEL_URL="https://${STORAGE_ACCOUNT}.blob.core.windows.net/${CONTAINER}/${MODEL_PREFIX}"

az login --tenant "$TENANT_ID"
export AZCOPY_AUTO_LOGIN_TYPE=AZCLI
export AZCOPY_TENANT_ID="$TENANT_ID"

azcopy copy "$MODEL_DIR/*" "$MODEL_URL" \
  --recursive=true \
  --overwrite=false \
  --exclude-path ".cache;.git"

azcopy list "$MODEL_URL"

加引號的萬用字元會直接將目錄內容複製到前綴中,且不新增本機目錄層級。 排除項目不包含下載和 Git 元資料。 只有在 AzCopy 報告沒有傳輸失敗且目的地包含所有所需檔案後,才繼續。 欲了解更多資訊,請參閱使用 AzCopy 上傳目錄內容及使用 Azure CLI 授權 AzCopy。

對於在 Azure 虛擬機器上執行的上傳程式,你可以改為使用受控識別來授權 AzCopy。 容器保持私密,並在準備後移除臨時上傳者角色分配。 留出時間讓新角色分配得以傳播;不要透過加入儲存金鑰或用戶端秘密來繞過授權錯誤。

記錄模型修訂版和 Blob 版本或 ETag。 Run:ai 模型的位置是 az://<container>/<model-prefix>。 在冷載入和熱載入之間,保持這些檔案不變。 如果再做一次冷測試,可以用另一個新的前綴,而不是直接從共用快取中移除資料。

在不使用 ImageVolume 的情況下準備工作負載映像檔

請在建置映像時安裝相依性,不要在 Pod 啟動時安裝。 保留你現有的應用程式、基礎映像和進入點。 使用應用程式的套件管理器及需求或約束工作流程來保留相容的相依性,包括 Torch、CUDA 和 NumPy。

使用支援 GPU 的 vLLM 映像檔,搭配與 GPU 節點及 NVIDIA 驅動相容的 Torch 和 CUDA 版本。 在新增相依性前,請先檢查映像檔已安裝的 Run:ai 核心和 Azure 後端套件;並非每個 vLLM 映像都包含 Azure 後端。

部署前先解決工作負載映像的相依性衝突。 下一節中的 pip check 這個步驟必須成功完成。 利用你應用程式的相依性限制來維持與其他已安裝套件的相容性。

  1. 如果你的映像檔還沒有相容的 Run:ai 核心和 Azure 後端套件,請在你的 Dockerfile 中加入以下指令:

    RUN python3 -m pip install --no-cache-dir "runai-model-streamer[azure]==0.17.3"
    
  2. 在同一 Python 環境中安裝公開的 DACS 用戶端套件,該套件提供原生用戶端函式庫:

    RUN python3 -m pip install --no-cache-dir "dacs-client==0.1.0" && \
        python3 -m pip check
    

    Run:ai 的 Azure extra 不會安裝 DACS 用戶端函式庫。 如果你的應用程式已經有相容的 Run:ai 套件,只需要安裝 DACS 用戶端套件即可。

  3. 用你現有的 Dockerfile 和建置上下文來建置和推送。 在你的準備機上在 Bash 中執行以下指令。 此範例為 x86-64 節點建置:

    REGISTRY_NAME="<registry-name>"
    REGISTRY_SERVER="$(az acr show --name "$REGISTRY_NAME" --query loginServer --output tsv)"
    WORKLOAD_IMAGE="$REGISTRY_SERVER/workload-runai-dacs:0.17.3-0.1.0"
    
    az acr login --name "$REGISTRY_NAME"
    docker build --platform linux/amd64 -t "$WORKLOAD_IMAGE" .
    docker push "$WORKLOAD_IMAGE"
    
  4. 在同一個 Bash 工作階段中,從已建構的映像解析原生函式庫路徑:

    docker run --rm --entrypoint python3 "$WORKLOAD_IMAGE" \
      -c 'from importlib.metadata import distribution; from pathlib import Path; p=Path(distribution("dacs-client").locate_file("py_dacs_client/libStorageDirect.so")).resolve(); assert p.is_file(), p; print(p)'
    

    設定工作負載時,請使用輸出的絕對路徑。 保留完整的用戶端安裝內容,包括同層目錄中的原生程式庫。

部署時偏好使用不可變的映像摘要。 更新內建客戶端需要重建並重新部署工作負載映像檔。

設定 Blob 認證

使用 AKS 工作負載身份來進行 Blob 認證。 部署範例使用此方法,且將 Storage Blob Data Reader 的範圍限定於模型容器。 推論不需要上傳者的寫入權限。 關於其他認證方法,請參閱 Run:ai Model Streamer 文件中的 Azure 認證。

使用 AKS 工作負載身分識別

部署範例在 runai-dacs 命名空間中使用 runai-reader ServiceAccount。 在部署工作負載前,請完成以下步驟:

  1. 在現有的 AKS 叢集上啟用 OIDC 發行者及 Microsoft Entra 工作負載 ID,如果尚未啟用。

  2. 擷取 OIDC 發行機構的 URL。

  3. 建立受管理身份,或選擇現有身份。

  4. 如果 runai-dacs 命名空間還不存在,就建立它。

    kubectl create namespace runai-dacs
    
  5. 建立一個以該身份的客戶端 ID 標註的 Kubernetes ServiceAccount。

  6. 為精確的命名空間與 ServiceAccount 建立聯合身份認證。 你不需要完成後續的 金鑰保存庫 步驟。

將 Blob 讀取器角色指派給 已與你的應用程式 ServiceAccount 建立同盟關係的受控識別。 如需容器範圍的指派範例,請參閱 Grant read access to model data,以此身分取代快速入門中的 kubelet 身分。

Pod 必須選取該 ServiceAccount,並具有 azure.workload.identity/use: "true" 標籤。 AKS 注入身份設定與投影令牌。 不要手動新增客戶端秘密或儲存帳號金鑰。

另外設定映像提取存取權

針對私人 ACR 映像,請依照將用戶端新增至工作負載映像中的說明,設定 kubelet 身分識別的提取權限。 使用 AcrPull 進行經典 RBAC。 針對已啟用 ABAC 的登錄,請使用 Container Registry Repository Reader 並授與適當的存放庫存取權。 請勿對該登錄使用 --attach-acr。

應用程式身份的 blob-read 存取權限並不代表 kubelet 有影像拉取權限。 對於 ImageVolume,拉取存取必須同時涵蓋工作負載與用戶端映像檔,並在適用時包含獨立的映像登錄或儲存庫。

配置並部署工作負載

在啟動 vLLM 前,先設定這四個應用變數。 它們與你驗證方式所提供的身份設定是分開的:

環境變數 Purpose
AZURE_STORAGE_ACCOUNT_NAME 包含該模型的儲存體帳戶。
CACHE_DISCOVERY_URL DACS 發現主機名稱,例如 cache-sample-discovery.<namespace>.svc.cluster.local。
CACHE_SERVER_PORT 快取埠,通常是 9065。
RUNAI_STREAMER_EXPERIMENTAL_AZURE_CACHE_LIB 從你的工作負載映像中解析出絕對的原生函式庫路徑。

Important

快取探索為必要設定。 模型載入可透過在快取未設定時直接讀取 Blob 儲存體 來成功。 使用 Run:ai Azure 後端0.17.3,也請明確指定原生函式庫路徑,而非依賴自動發現。

使用 Run:ai 的模型 URI 格式 az://<container>/<model-prefix>,並透過 AZURE_STORAGE_ACCOUNT_NAME 提供帳戶。 此 URI 格式與原生 Python 用戶端的標準 URI 不同,後者包含帳號主機名稱。

替換以下範例中的佔位符並儲存為 runai-dacs-pod.yaml。 使用你上傳時的模型前綴,以及已建置映像所印出的原生函式庫路徑。 此範例使用工作負載身分識別,且不包含 ImageVolume 或初始化容器:

apiVersion: v1
kind: Pod
metadata:
  name: runai-dacs-vllm
  namespace: runai-dacs
  labels:
    azure.workload.identity/use: "true"
spec:
  serviceAccountName: runai-reader
  restartPolicy: Never
  nodeSelector:
    agentpool: "<gpu-nodepool-name>"
  tolerations:
    - key: nvidia.com/gpu
      operator: Exists
      effect: NoSchedule
  containers:
    - name: vllm
      image: "<workload-image>"
      command: ["vllm", "serve"]
      args:
        - "az://<container>/<model-prefix>"
        - "--load-format"
        - "runai_streamer"
        - "--served-model-name"
        - "cached-model"
        - "--dtype"
        - "bfloat16"
        - "--max-model-len"
        - "1024"
      env:
        - name: AZURE_STORAGE_ACCOUNT_NAME
          value: "<storage-account>"
        - name: CACHE_DISCOVERY_URL
          value: "<cache-discovery-hostname>"
        - name: CACHE_SERVER_PORT
          value: "9065"
        - name: RUNAI_STREAMER_EXPERIMENTAL_AZURE_CACHE_LIB
          value: "<dacs-native-library-path>"
        - name: RUNAI_STREAMER_CHUNK_BYTESIZE
          value: "8388608"
        - name: SI_streamingChunkSize
          value: "8388608"
      resources:
        requests:
          cpu: "4"
          memory: 16Gi
        limits:
          cpu: "4"
          memory: 16Gi
          nvidia.com/gpu: 1
      ports:
        - containerPort: 8000
      readinessProbe:
        httpGet:
          path: /health
          port: 8000
        periodSeconds: 10
        timeoutSeconds: 5
      volumeMounts:
        - name: shm
          mountPath: /dev/shm
  volumes:
    - name: shm
      emptyDir:
        medium: Memory
        sizeLimit: 2Gi

這些資源展示的是小型模型,而非30B模型。 保留你工作負載所需的排程、資源、探測、共享記憶體及其他 vLLM 參數。 調整 GPU 數量、張量平行度、模型長度和記憶體大小,針對您的模型。 針對 Deployment 或 StatefulSet,請將 Pod 標籤套用至 spec.template.metadata 下方,並將 Pod 設定套用至 spec.template.spec 下方。

第一次部署會先啟動 vLLM,並在 Pod 準備好前載入模型。 為了進行冷快取比較,請依序完成以下步驟:

  1. 選擇快取尚未讀取的模型資料,例如上傳程序中的全新前綴。 不要從共享快取中移除資料。

  2. 在部署應用程式 Pod 之前,請依 監控雲端儲存的分散式加速器所述,從每個快取伺服器 Pod 擷取基線指標快照。 記錄時間戳記以及每台伺服器的 cache_server_upload_request_size_bytes_sum、 cache_server_download_request_size_bytes_sum、 cache_server_cache_size_bytes。

  3. 部署並檢查已核准的 Pod:

    kubectl apply --dry-run=server -f runai-dacs-pod.yaml
    kubectl apply -f runai-dacs-pod.yaml
    kubectl -n runai-dacs get pod runai-dacs-vllm -o yaml
    kubectl -n runai-dacs wait --for=condition=Ready pod/runai-dacs-vllm --timeout=30m
    

檢查工作負載執行時間

在 vLLM 應用程式容器內執行這個檢查,使用該應用程式的 Python 執行檔。 它驗證的是套件一致性與原生函式庫載入情況,而非 Blob 認證或快取使用情況:

kubectl -n runai-dacs exec -i runai-dacs-vllm -c vllm -- python3 - <<'PY'
import ctypes
import os
import subprocess
import sys
from importlib.metadata import version

for package in (
    "vllm",
    "torch",
    "runai-model-streamer",
    "runai-model-streamer-azure",
):
    print(f"{package}: {version(package)}", flush=True)

subprocess.run([sys.executable, "-m", "pip", "check"], check=True)

path = os.environ["RUNAI_STREAMER_EXPERIMENTAL_AZURE_CACHE_LIB"]
print(f"Checking DACS native library: {path}", flush=True)
library = ctypes.CDLL(path)
print(f"DACS native library loaded: {path}")
PY

先解決錯誤再繼續。 關於 GPU 部署,也請檢查 GPU 可見性與 vLLM 引擎日誌,確認 CUDA 執行及預期模型 dtype 的狀況。 僅僅有準備狀態或函式庫載入成功,並不能證明 GPU 執行或 DACS 快取的使用。

驗證冷快取與暖快取行為

使用在 配置與部署工作負載中收集的部署前指標基線。 部署期間執行的模型載入稱為冷載入。

驗證冷載入

檢查應用程式日誌:

kubectl -n runai-dacs logs runai-dacs-vllm -c vllm

尋找原生 ReadChunk stats 統計資料。 RemoteClient 記錄後備儲存區權重讀取次數;RemoteCache 記錄遠端快取讀取次數。 部分快取在首次載入時的命中是正常的,因為較早的讀取可以填入資料。 GetProperties 快取命中描述的是元資料,而非模型權重命中。

傳送推論請求:

kubectl -n runai-dacs exec -i runai-dacs-vllm -c vllm -- python3 - <<'PY'
import json
import urllib.request

body = json.dumps({
    "model": "cached-model",
    "prompt": "Once upon a time",
    "max_tokens": 16,
    "temperature": 0,
}).encode()
request = urllib.request.Request(
    "http://127.0.0.1:8000/v1/completions", data=body,
    headers={"Content-Type": "application/json"},
)
with urllib.request.urlopen(request, timeout=600) as response:
    result = json.load(response)
print(json.dumps(result, indent=2))
assert result["choices"][0]["text"].strip()
assert result["usage"]["completion_tokens"] > 0
PY

確認冷載入時後端存放區的讀取次數不為零。 在檢查非同步快取填入情況時,請讓應用程式 Pod 持續執行:

  1. 每 10 秒從所選快取資源的每個快取伺服器 Pod 中抽取 cache_server_upload_request_size_bytes_sum 和 cache_server_cache_size_bytes,最多可持續五分鐘。 使用 metrics 端點程序。 使用最新樣本,不要重複使用已儲存的抓取結果。
  2. 將樣本與部署前基準比較。 要求這些伺服器整體的上傳位元組總數和快取位元組總數增加。 不要要求每台伺服器都接收資料。
  3. 在總上傳量增加後,等待每台伺服器的上傳位元組計數器連續三個取樣區間保持不變。 確認比較過程中沒有伺服器重啟或計數器重置。
  4. 將最後的樣本存為冷後快照,包含來自每台伺服器的 cache_server_download_request_size_bytes_sum,作為暖載入的基準。

如果五分鐘內這些條件都沒達成,就停止比較,而不是把快取視為已預熱。 在重試前檢查用戶端上傳錯誤、快取伺服器健康狀況及當前流量。 較大的模型可能需要更長的觀察窗口。 缺失的指標或抓取失敗,並不表示值為零,也不是上傳已完成的證據。

穩定計數器是準備狀態的信號,而非證明每個模型區塊都已快取。 共用快取的流量也可能導致數值無法趨於穩定,或造成數值增加。 請盡可能選擇流量較少的時段進行驗證,並務必執行下列全新 Pod 的暖讀取檢查,以確認分散式快取的重複使用情形。

在全新 Pod 中驗證暖載入

儲存冷記錄和 pod 的 UID。 僅用相同的模型檔案、快取端點、函式庫和區塊大小重建應用程式 Pod:

kubectl -n runai-dacs logs runai-dacs-vllm -c vllm > runai-cold.log
kubectl -n runai-dacs get pod runai-dacs-vllm -o jsonpath='{.metadata.uid}' > runai-cold.uid
kubectl -n runai-dacs delete pod runai-dacs-vllm --wait=true
kubectl apply -f runai-dacs-pod.yaml
kubectl -n runai-dacs wait --for=condition=Ready pod/runai-dacs-vllm --timeout=30m
kubectl -n runai-dacs get pod runai-dacs-vllm -o jsonpath='{.metadata.uid}' > runai-warm.uid
kubectl -n runai-dacs logs runai-dacs-vllm -c vllm > runai-warm.log

再次執行執行階段檢查和推論要求。 接著,從每個快取伺服器擷取暖機後的指標快照。 確認不同的 Pod UID、較高的遠端來源快取命中率,以及較少的後端儲存體讀取次數。 將 cache_server_download_request_size_bytes_sum 與冷載入後的快照進行比較,以佐證暖快取讀取情形。 使用全新處理程序,可避免將本機記憶體內的預先擷取誤認為分散式快取命中。

遠端來源的命中率為 RemoteCache / (RemoteCache + RemoteClient),不包含本地預取。 使用每個原生程序、掛載和區塊大小的最新累積快照;不要將週期性取樣加總。 排除因快取伺服器重啟或計數器重置而受影響的測量值。 共享伺服器計數器可佐證應用程式日誌,但不會將所有流量歸因於單一工作負載。

即使暖載入的權重讀取計數器顯示後端存放區讀取次數為零,中繼資料作業仍可能連線至 Blob 儲存體。

使用 ImageVolume 掛載 DACS 用戶端函式庫

只有當節點執行階段支援 ImageVolume,並且你有使用公開 DACS wheel 套件建置的可拉取用戶端映像時,才使用此替代方案。 不要假設擬議的 MCR 映像或標籤已經發布。 若沒有合適的用戶端映像,請使用上一節的工作負載映像程序。

你的 GPU vLLM 映像檔必須已經包含相容的 Run:ai 核心和 Azure 套件。 你不需要在其 Python 環境中安裝 DACS 用戶端套件,因為映像檔磁碟區提供原生用戶端函式庫。

請按如下方式調整這個 pod 範例:

  1. 保留你現有相容的 vLLM 映像檔,不要重建它來安裝 DACS 用戶端函式庫。

  2. 新增唯讀用戶端映像磁碟區並掛載:

    # Add to spec.volumes.
    - name: dacs-client
      image:
        reference: "<accessible-client-image>"
        pullPolicy: IfNotPresent
    
    # Add to the vLLM container's volumeMounts.
    - name: dacs-client
      mountPath: /opt/cache-client
      readOnly: true
    
  3. 根據該圖片的實際佈局,將 RUNAI_STREAMER_EXPERIMENTAL_AZURE_CACHE_LIB 設為 /opt/cache-client 下 libStorageDirect.so 的絕對路徑。 保留同層目錄中的原生相依性。

  4. 部署並確認影像卷與唯讀掛載仍保留在 live Pod 規格中。 確認檔案是否存在,然後執行相同的應用程式容器執行環境和冷啟動/暖啟動檢查。

部分較舊的叢集可從已接受的 Pod 中移除不支援的映像檔磁碟區欄位和掛載。 僅確認 Kubernetes 版本及執行伺服器端試執行並不足夠。 不要在已掛載的用戶端旁邊安裝或預載衝突版本的 DACS 用戶端函式庫;絕對函式庫路徑無法隔離其原生相依命名空間。

優化讀取效能

為什麼要調整區塊大小? 模型具有不同的張量大小和讀取模式,因此單一區塊大小可能無法對每個模型都提供最佳的模型載入效能表現。 過大的區塊會擷取超出單次讀取所需的資料,並增加緩衝需求。 過小的區塊會增加請求次數和每次請求的額外負擔。 選擇適合模型中常見張量的大小,可平衡這些成本、提高有效權重讀取輸送量,並縮短模型載入時間,包括從 DACS 進行暖載入的時間。 請將以下建議視為起點,並分別測量冷載入時間與暖載入時間。 效益取決於模型、載入器並行性,以及儲存與網路效能。

請依照以下模型專屬建議選擇區塊大小。 對於其他模型,請如下一節所述檢查張量中繼資料,若無法進行中繼資料檢查,則使用 32 MiB 。

模型 建議的區塊大小 以位元組為單位的值
qwen3-coder-30b-a3b-instruct 3 MiB 3145728
gpt-oss-20b 2 MiB 2097152
deepseek-r1-0528 14 MiB 14680064
deepseek-v3-0324 14 MiB 14680064
phi-2 2 MiB 2097152
mistral-small-4-119b-2603-nvfp4 2 MiB 2097152
ministral-3-3b-instruct-2512 2 MiB 2097152
ministral-3-3b-instruct (別名) 2 MiB 2097152
ministral-3-8b-instruct-2512 2 MiB 2097152
ministral-3-8b-instruct (別名) 2 MiB 2097152
ministral-3-14b-instruct-2512 2 MiB 2097152
ministral-3-14b-instruct (別名) 2 MiB 2097152
當無法檢查元資料時的備用方案 32 MiB 33554432

為另一個模型選擇區塊大小

使用 Safetensors 中繼資料檢視器或標頭檢查工具,在不載入張量內容的情況下,檢查所有模型分區:

  1. 求出每個張量儲存的位元組大小:即其結束資料偏移減去起始偏移量。 排除該 __metadata__ 條目。
  2. 在計算發生次數前,將所有超過 32 MiB 的大小視為 32 MiB 。
  3. 選擇所有分片中出現頻率最高的大小。 如果多個尺寸出現頻率相同,選擇較大的那個。
  4. 如果選擇的大小低於 2 MiB,則使用 2 MiB。

例如,若套用上限後最常出現的是 3 MiB 的張量,請使用 3 MiB (3145728 位元組)。 若無法進行元資料檢查,則使用 32 MiB(33554432位元組)。

設定應用程式

在應用程式容器環境中,將 RUNAI_STREAMER_CHUNK_BYTESIZE 和 SI_streamingChunkSize 都設定為產生的位元組值。 例如,若建議值為 3 MiB:

env:
  - name: RUNAI_STREAMER_CHUNK_BYTESIZE
    value: "3145728"
  - name: SI_streamingChunkSize
    value: "3145728"

請明確設定這些值;表格描述的是建議,而非自動偵測模型或內建預設值。 變更後,請重新建立應用程式 Pod;快取伺服器不需要重新啟動。 共用快取資料的讀取器和資料填入作業應使用相同的區塊大小。

Run:ai 的讀取大小和原生快取區塊大小是分開的控制項,且在上面一起設定。 用你的工作負載來做基準測試,並分別調整載入器並行性。 分別比較冷負載和熱負載。 改變快取區塊大小會產生不同的快取金鑰,並可能暫時增加快取占用量。 一次只更改一個設定,並測量載入時間、原生計數器、快取指標、CPU、GPU 與主機記憶體,以及網路使用情況。 僅靠張量對齊並不保證效能更好。

Warning

公開原生用戶端在 0.1.0 版中的預設非同步上傳緩衝區預算為 400 GiB。 它不是預先配置,也不是 Safe Pod 記憶體限制。 大型模型的冷快取填入作業可能耗盡較小 Pod 的記憶體。 對於記憶體受限的工作負載,測試同步填入(SI_cacheEnableSyncUpload=true)或有界非同步上傳預算(SI_cacheMaxUploadBufferSizePerProcessGB)。 請分別為模型暫存、原生上傳/預先擷取緩衝區、GPU 記憶體和 /dev/shm 規劃資源預算。 這些防護措施是針對工作負載的可選設定,而非小模型範例的額外要求。

Troubleshoot

徵兆 支票
映像提取失敗 Kubelet 拉取權限、映像登錄權限模式、映像摘要和網路存取。
原生函式庫無法載入 應用 Python 環境、明確路徑、glibc 相容性,以及姊妹原生函式庫。
Blob 授權失敗 選擇身分識別、讀者角色、角色傳播、聯盟與 Pod 標籤。 至於其他認證方式,請參考前面連結的 Azure 上游認證指引。
模型載入時沒有快取流量 兩項探索設定、提供者載入、DNS/網路連線能力,以及原生資料讀取計數器。
熱載入仍會讀取 Blob 資料 資料填入完成情形、Blob 版本、區塊大小是否相符、資料收回情形,以及部分讀取。
找不到 ImageVolume Live Pod 欄位與節點/執行時支援;若無法使用,請使用內建方法。
Pod 因記憶體不足 (OOM) 而遭終止 模型與暫存記憶體、原生緩衝區、GPU/KV 快取大小,以及 /dev/shm。

若要進行獨立的直接 Blob 比較,請設定 RUNAI_STREAMER_EXPERIMENTAL_AZURE_CACHE_ENABLED=0 並重建一個測試 Pod。 將它設為 1 反而會讓提供者載入失敗時啟動失敗,而非靜默回退。 這兩種設定都無法證明快取命中;檢查資料讀取計數器。

清理這個範例

如果你建立了獨立的範例 Pod,完成後請刪除:

kubectl -n runai-dacs delete pod runai-dacs-vllm --wait=true

只移除你為此範例建立且不再需要的模型前綴、圖片、身分識別、同盟、命名空間和角色指派。 不要刪除現有的共享快取或身份。 保留的模型資料現在已暖起;使用全新前綴進行另一次冷快取驗證。

下一步