搭配 Python 用戶端使用雲端儲存體分散式加速器 (預覽版)

雲端儲存分散式加速器(DACS)提供一個原生的 Python 用戶端,透過分散式快取讀取 Azure Blob 資料。

在使用本文前,請先完成 AKS 上雲端儲存的分散式加速器快速入門。

安裝原生 Python 用戶端

在你的工作負載映像中安裝 PyPI 的套件:

python3 -m pip install "dacs-client==0.1.0"

如果你正在更新現有的工作負載,更新其映像建置定義中的套件固定版本,重建並推送映像檔,並用更新後的映像重新部署工作負載 Pods。 本地安裝套件不會更新正在運行的容器。 關於映像建置與推送指令,請參見 「將客戶端加入工作負載映像」。

該套件需要 Python 3.8 或更新版本,以及具有 glibc 2.35 或更新版本的 Linux 環境。 它為 x86-64 和 arm64 提供自包含的 manylinux_2_35 wheel,包括原生函式庫及其共享函式庫相依性。 azure-identity相依性會自動安裝。

快速入門在 python:3.12-slim-bookworm 上使用 Python 3.12,並採用 x86-64 節點。

確認工作負載容器內的安裝情況:

python3 -c "import importlib.metadata; import py_dacs_client; print(importlib.metadata.version('dacs-client'))"

指令必須列印 0.1.0。 發行版名稱為 dacs-client,但 Python 匯入名稱為 py_dacs_client。

設定用戶端

在每個使用分散式加速器進行雲端儲存的 pod 上設定兩個快取發現變數:

env:
  - name: CACHE_DISCOVERY_URL
    value: <discovery-service-hostname>
  - name: CACHE_SERVER_PORT
    value: "9065"

Important

這兩個變數都是必須的。 如果缺少其中任何一個,客戶端會記錄 Cache not configured. Working in Remote Blob mode only.,並直接存取 Azure Blob 儲存體。 操作可在不使用快取的情況下成功。

使用您的快取資源和命名空間的探索服務主機名稱,例如 cache-sample-discovery.<namespace>.svc.cluster.local,並使用連接埠 9065。

建立用戶端前,先設定 Blob 驗證。 以下範例使用 AKS kubelet 受控識別,透過節點的實例中繼資料服務(IMDS),而非同盟 AKS 工作負載識別。 設定 AZURE_CLIENT_ID 為 kubelet 身份的客戶端 ID:

env:
  - name: AZURE_CLIENT_ID
    value: <kubelet-identity-client-id>
  - name: MSI_ENDPOINT
    value: "http://169.254.169.254/metadata/identity/oauth2/token"
  - name: MSI_SECRET
    value: "required-nonempty-value"

The Pod 必須能連線到 IMDS。 對於這種原生客戶端配置, MSI_SECRET 是必須的非空相容標記,而非真正的秘密或憑證。 請勿將認證放在該值中。 這些設定是針對這個整合的;請不要將它們複製到 Run:ai 認證設定中。

為了只讀推論,將 Kubelet 身份賦予 Storage Blob Data Reader 角色,該角色的作用範圍為模型容器。 請參閱 授予模型資料的讀取權限。 只有當應用程式必須寫入資料時,才使用 Storage Blob Data Contributor 。 在執行階段進行讀取不需要另外的上傳器寫入權限。

使用此正規路徑格式:

az://<account>.blob.core.windows.net/<container>/<path>

原生層在程序中建立第一個用戶端時會讀取設定。 在建立該客戶端之前,先先設定環境和客戶端設定。 後續用戶端不會更改原本已生效的原生設定。

了解快取未命中與同時讀取

當多個用戶端同時請求相同的缺失資料時,每個用戶端可以獨立從 Azure Blob 儲存體 取得資料。 此預覽版不提供協調式冷快取預先填入功能。

快取填入是非同步的。 讀取可能在資料尚未從快取中取得前完成,因此即使回傳的位元組匹配,兩次即時讀取也可能都未命中快取。

在進行大型同步擴展事件前,請先透過 DACS 預熱所選的模型 Blob,再開始推論複本。 請依照部署前預先擷取模型資料中的指示操作,以取得專用暖機 Pod、讀取命令和推出驗證。

成功讀取可以透過 Azure Blob 儲存體 備援來實現。 要驗證讀取作業使用 DACS:

  1. 在讀取前,請先記錄 cache_server_request_counter{request_type="Download",status="Success"},針對您的快取資源,跨所有快取伺服器 Pod 進行加總。 標籤值是區分大小寫的。
  2. 重複讀取同一個 blob 範圍,並在每次讀取之間加入延遲。 本快速入門使用五次讀取,每次間隔一秒;此順序不保證填入已完成。 確認伺服器成功下載次數有增加,且客戶端有回報快取命中。 檢查回傳的位元組數和校驗和是否符合資料完整性;僅憑較快的時序並不能證明有使用快取。
  3. 將用戶端及伺服器計量與 Azure Blob 遙測資料建立關聯,以區分快取流量與來源讀取及後援。

關於收集用戶端計量和伺服器計數器的命令,請參閱確認 DACS 要求路徑。

使用原生用戶端

原生用戶端提供非同步方法與同步對應物。 它會將資料讀入預先配置的原生緩衝區。 在執行以下範例前,先設定 MODEL_PATH 為現有模型分片的規範 az:// 路徑,該範例可讀取至前 4 MiB:

import asyncio
import os

from py_dacs_client.dacs_client import DACSCacheClient
from py_dacs_client.dacs_utils import BoundedBufferManager


async def main():
    path = os.environ["MODEL_PATH"]
    client = DACSCacheClient()
    buffers = BoundedBufferManager(max_memory_limit=64 * 1024 * 1024)

    try:
        size = min(await client.get_file_size(path), 4 * 1024 * 1024)
        if size == 0:
            print("read 0 bytes")
            return

        buffer = await buffers.acquire_buffer(size)
        try:
            bytes_read = await client.read_blob(path, buffer, size, 0)
            print(f"read {bytes_read} bytes")
        finally:
            await buffers.release_buffer(buffer)
    finally:
        await client.shutdown()


asyncio.run(main())

常見的讀取方法包括:

非同步方法 同步方法 Description
get_file_size(path) get_file_size_sync(path) 取得 blob 大小(位元組)。
get_file_stat(path) get_file_stat_sync(path) 取得模型檔案的元資料。
read_blob(path, buffer, size, offset) read_blob_sync(...) 將位元組範圍讀入預先配置的緩衝區。
list_dir(path) list_dir_sync(path) 列出目錄項目。
get_file_handle(path, flags) get_file_handle_sync(...) 開啟可重複使用的處理常式。
release_file_handle(handle) release_file_handle_sync(handle) 關閉可重複使用的處理常式。
shutdown() shutdown_sync() 釋放連線並發出最終指標。

非同步 list_dir(path) 方法回傳一個迭代器;使用 async for 來逐一讀取目錄項目。

對於不需要每個位元組的模型格式,可以用範圍讀取。 雲端儲存的分散式加速器僅儲存涵蓋所要求範圍的區塊。

優化讀取效能

同時調整應用程式讀取並行度與要求的位元組範圍大小。 最佳設定取決於你的存取模式、Pod CPU 和記憶體限制、客戶端與快取節點的網路頻寬,以及讀取是否命中快取或回退到 Blob 儲存體。

本節的數值可作為工作負載基準的起點,而非保證的效能建議。 在部署變更前,先用你自己的工作負載來衡量它們的影響。

調整並行

並行性是指你的應用程式同時進行中的讀取要求數量。 在開始下一次呼叫之前,先等待每一次 read_blob 呼叫完成的迴圈,即使使用非同步 API,也屬於循序執行。

  • 並行核發獨立的位元組範圍或 Blob 讀取。 使用 asyncio.Semaphore 或固定數量的背景工作來限制作用中的讀取數量。 不要同時為大型資料集中的每個範圍建立任務。
  • 先設定一個小的限制,例如四次同時讀取,然後與八和十六次進行比較。 只有在吞吐量提升且不會造成不可接受的延遲、記憶體使用、錯誤或限速的情況下,才增加並行性。
  • 原生客戶端透過其 concurrent.futures.Executor 建構參數接受一個 executor。 要明確控制 Python 執行緒池,可以傳遞一個 ThreadPoolExecutor,例如 DACSCacheClient(executor=ThreadPoolExecutor(max_workers=8))。 保留對執行者的參考,保持其存活直到所有讀取結束,並在呼叫 await client.shutdown() 後將其關閉。
  • 較大的執行緒池不會讓循序呼叫同時進行。 限制應用程式工作以及執行程式背景工作,並為每個作用中的讀取使用獨立的緩衝區。

將所有工作程序與 pod 的並行性納入考量。 在擴展過程中增加各 pod 的並行性,可能會讓同一快取節點過載,或在冷快取未命中時增加重複的 Blob 下載次數。

設定快取區塊大小

在應用程式 Pod 上,將 SI_streamingChunkSize 設為位元組值,以設定快取區塊大小。 例如,以下設定使用 3-MiB 區塊:

env:
  - name: SI_streamingChunkSize
    value: "3145728"

在建立第一個客戶端之前,先設定這個變數。 變更後重新啟動應用程式 Pod。

預設快取區塊大小為 32 MiB。 read_blob(path, buffer, size, offset) 的 size 參數指定應用程式請求的位元組範圍,而非快取區塊大小。

存取模式 應用程式讀取指引
大型循序模型讀取 比較較大的快取區塊、請求範圍大小與有界並行。 一次只調整一個設定。
小型或隨機讀取 僅要求應用程式所需的位元組。 比較較小的快取區塊,以減少超出請求範圍的資料擷取。
容量受限快取 衡量快取佔用率與淘汰行為,而非僅根據應用程式讀取緩衝區大小來估算快取使用情況。

將應用程式讀取緩衝區與快取區塊分開編列預算。 例如,八個並行的 4-MiB read_blob 請求需要 32 MiB 的應用程式讀取緩衝區容量,無論設定的快取區塊大小為何。 保留額外的 Pod 記憶體,用於原生用戶端配置、佇列中的工作、Python 物件及模型處理。 只有在進入並發限制後才取得緩衝區,並在 finally 區塊中釋放每個緩衝區。

Warning

BoundedBufferManager(max_memory_limit=...) 限制的是應用程式的讀取緩衝區容量,但不是總客戶端記憶體或原生上傳緩衝區。 在 0.1.0中,原生用戶端的預設非同步上傳緩衝區預算為 400 GiB。 此預算不是預先配置,也不是安全的 Pod 記憶體限制。 大量冷快取讀取作業可能會耗盡較小 Pod 的資源。 對於記憶體受限的工作負載,測試同步填入(SI_cacheEnableSyncUpload=true)或有界非同步上傳預算(SI_cacheMaxUploadBufferSizePerProcessGB)。 在建立第一個用戶端前設定這些值,並將原生緩衝區與應用程式讀取緩衝區及模型處理分開編列預算。

在提高限制前先進行測量

  1. 以固定的資料集、Pod 數量和資源限制建立基準。 測量吞吐量、讀取延遲、CPU、記憶體及網路使用率。
  2. 分別對冷快取與暖快取進行基準測試。 檢查 cache_server_request_counter 和 Azure Blob 遙測資料,以區分快取流量與直接 Blob 後援。
  3. 一次只更改一個設定:並行度、應用程式讀取大小或快取區塊大小。 比較結果時,請保持資料集和其他設定一致。
  4. 當吞吐量停滯,或延遲、資源壓力、錯誤或 Blob 限制增加時,停止提高某項設定。

關於快取端觀察,請參見 監控雲端儲存的分散式加速器。

處理錯誤

所有 DACS 例外皆源自 DACSError:

from py_dacs_client import DACSError, DACSNotFoundError

try:
    load_model_data()
except DACSNotFoundError:
    handle_missing_model()
except DACSError as error:
    handle_cache_or_storage_error(error)
Exception Meaning
DACSNotFoundError Blob 路徑或目錄不存在。
DACSExistsError 應用程式嘗試在未啟用覆寫的情況下寫入現有的 blob。
DACSAuthenticationError 憑證缺失或無效。
DACSPermissionError 此身分識別缺少所需的 Blob 角色。
DACSTimeoutError 快取或 Blob 操作逾時。
DACSNetworkError 快取伺服器或 Blob 端點無法存取。
DACSInvalidInputError 路徑或引數格式不正確。
OperationNotSupportedError 請求的 API 還沒實作。

控制記錄

客戶端針對 Python 層和原生層設有獨立的日誌控制。 將兩個變數設定為抑制兩層冗長輸出:

env:
  - name: DACS_DATA_LOG_LEVEL
    value: WARNING
  - name: STORAGE_LOG_LEVEL
    value: WARNING

DACS_DATA_LOG_LEVEL控制 Python 日誌。 STORAGE_LOG_LEVEL 會控制原生用戶端記錄。

下一步