雲端儲存分散式加速器(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:
- 在讀取前,請先記錄
cache_server_request_counter{request_type="Download",status="Success"},針對您的快取資源,跨所有快取伺服器 Pod 進行加總。 標籤值是區分大小寫的。 - 重複讀取同一個 blob 範圍,並在每次讀取之間加入延遲。 本快速入門使用五次讀取,每次間隔一秒;此順序不保證填入已完成。 確認伺服器成功下載次數有增加,且客戶端有回報快取命中。 檢查回傳的位元組數和校驗和是否符合資料完整性;僅憑較快的時序並不能證明有使用快取。
- 將用戶端及伺服器計量與 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)。 在建立第一個用戶端前設定這些值,並將原生緩衝區與應用程式讀取緩衝區及模型處理分開編列預算。
在提高限制前先進行測量
- 以固定的資料集、Pod 數量和資源限制建立基準。 測量吞吐量、讀取延遲、CPU、記憶體及網路使用率。
- 分別對冷快取與暖快取進行基準測試。 檢查
cache_server_request_counter和 Azure Blob 遙測資料,以區分快取流量與直接 Blob 後援。 - 一次只更改一個設定:並行度、應用程式讀取大小或快取區塊大小。 比較結果時,請保持資料集和其他設定一致。
- 當吞吐量停滯,或延遲、資源壓力、錯誤或 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 會控制原生用戶端記錄。