Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
L’accélérateur distribué pour stockage cloud (DACS) fournit un client Python natif pour lire les données Azure Blob via le cache distribué.
Terminez l’article Prise en main de l’accélérateur distribué pour le stockage cloud sur AKS avant d’utiliser cet article.
Installer le client Python natif
Installez le package depuis PyPI dans votre image de charge de travail :
python3 -m pip install "dacs-client==0.1.0"
Si vous mettez à jour une charge de travail existante, modifiez la version du package fixée dans la définition de génération de son image, régénérez et envoyez l’image, puis redéployez les pods de la charge de travail avec l’image mise à jour. Installer le package localement ne met pas à jour les conteneurs en cours d’exécution. Pour les commandes de construction et de push d’image, voir Ajouter le client à une image de workload.
Le paquet nécessite Python 3.8 ou plus récent ainsi qu’un environnement Linux avec glibc 2.35 ou une version plus récente. Il propose des wheels autonomes manylinux_2_35 pour x86-64 et arm64, incluant la bibliothèque native et ses dépendances de bibliothèque partagée. La azure-identity dépendance s’installe automatiquement.
Le quickstart utilise Python 3.12 sur python:3.12-slim-bookworm avec des nœuds x86-64.
Vérifiez l’installation à l’intérieur du conteneur de charge de travail :
python3 -c "import importlib.metadata; import py_dacs_client; print(importlib.metadata.version('dacs-client'))"
La commande doit imprimer 0.1.0. Le nom de la distribution est dacs-client, mais le nom d’importation Python est py_dacs_client.
Configurer le client
Définissez les deux variables de découverte de cache sur chaque pod utilisant un accélérateur distribué pour le stockage cloud :
env:
- name: CACHE_DISCOVERY_URL
value: <discovery-service-hostname>
- name: CACHE_SERVER_PORT
value: "9065"
Important
Les deux variables sont nécessaires. Si l’un des deux manque, le client enregistre Cache not configured. Working in Remote Blob mode only. et accède directement à Stockage Blob Azure. L’opération peut réussir sans utiliser le cache.
Utilisez le nom d’hôte du service de découverte pour votre ressource et espace de noms Cache, par exemple, cache-sample-discovery.<namespace>.svc.cluster.local, avec le port 9065.
Configurez l’authentification Blob avant de créer le client. L’exemple suivant utilise l’identité gérée de kubelet AKS via le Service de métadonnées d’instance (IMDS) du nœud, et non l’identité fédérée de la charge de travail AKS. Définissez AZURE_CLIENT_ID sur l’ID client de l’identité kubelet :
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"
Le Pod doit pouvoir atteindre IMDS. Pour cette configuration cliente native, MSI_SECRET est un marqueur de compatibilité non vide obligatoire, et non un véritable secret ou une information d’identification. Ne mettez pas d’informations d’identification dans cette valeur. Ces paramètres sont spécifiques à cette intégration ; ne les copiez pas dans la configuration d’authentification Run :ai.
Pour l’inférence en lecture seule, attribuez à l’identité kubelet le rôle Lecteur des données Blob du stockage, dont l’étendue est limitée au conteneur de modèles. Voir Accorder un accès en lecture aux données du modèle. Utilisez Storage Blob Data Contributor uniquement lorsque l’application doit écrire des données. La permission d’écriture d’un téléverseur séparé n’est pas nécessaire pour les lectures à l’exécution.
Utilisez ce format de chemin canonique :
az://<account>.blob.core.windows.net/<container>/<path>
La couche native lit la configuration lorsque le premier client est créé dans un processus. Configurez l’environnement et les paramètres du client avant de créer ce client. Les clients initialisés ultérieurement ne modifient pas la configuration native déjà en vigueur.
Comprendre les défauts de cache et les lectures simultanées
Lorsque plusieurs clients demandent les mêmes données manquantes en même temps, chaque client peut récupérer indépendamment les données depuis Stockage Blob Azure. La population coordonnée du cache froid n’est pas disponible dans cet aperçu.
La population du cache est asynchrone. Une lecture peut se terminer avant que ses données ne soient disponibles depuis le cache, donc deux lectures immédiates peuvent toutes deux rater même lorsque les octets retournés correspondent.
Avant les opérations de mise à l’échelle synchronisées de grande ampleur, préchargez les blobs de modèles sélectionnés via DACS, avant de démarrer les réplicas d’inférence. Suivez les instructions de la section Précharger les données de modèle avant le déploiement pour créer un pod dédié au préchargement, exécuter les commandes de lecture et vérifier le déploiement.
Une lecture réussie peut résulter d’un mécanisme de repli vers le stockage Blob Azure. Pour vérifier que les lectures utilisent DACS :
- Avant de lire, enregistrez
cache_server_request_counter{request_type="Download",status="Success"}, cumulée sur l’ensemble des pods du serveur de cache de votre ressource Cache. Les valeurs des étiquettes respectent la casse. - Lis la même plage de blob à répétition avec un délai entre les lectures. Le guide de démarrage rapide utilise cinq lectures espacées d’une seconde ; cette séquence ne garantit pas que le remplissage du cache soit terminé. Vérifiez que le nombre de téléchargements réussis (`Download`) sur le serveur augmente et que le client signale des accès réussis au cache. Vérifiez le nombre d’octets renvoyés et les sommes de contrôle pour garantir l’intégrité des données ; des temps d’exécution plus courts ne constituent pas à eux seuls une preuve de mise en cache.
- Mettez en corrélation les métriques du client et du serveur avec la télémétrie d’Azure Blob pour distinguer le trafic du cache des lectures effectuées à partir du stockage d’origine et des opérations de repli.
Pour les commandes visant à collecter les métriques clients et les compteurs serveur, voir Vérifier le chemin de requête DACS.
Utilisez le client natif
Le client natif fournit des méthodes asynchrones et des équivalents synchrones. Il lit les données dans des mémoires tampons natives préallouées. Définissez MODEL_PATH sur le chemin az:// canonique d’un fragment de modèle existant avant d’exécuter l’exemple suivant, qui lit jusqu’aux 4 premiers Mio :
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())
Les méthodes de lecture courantes incluent :
| Méthode asynchrone | Méthode synchrone | Description |
|---|---|---|
get_file_size(path) |
get_file_size_sync(path) |
Obtenez la taille du blob en octets. |
get_file_stat(path) |
get_file_stat_sync(path) |
Obtenir les métadonnées du fichier de modèle. |
read_blob(path, buffer, size, offset) |
read_blob_sync(...) |
Lisez une plage d’octets dans un tampon préalloué. |
list_dir(path) |
list_dir_sync(path) |
Lister les entrées du répertoire. |
get_file_handle(path, flags) |
get_file_handle_sync(...) |
Ouvrir un handle réutilisable. |
release_file_handle(handle) |
release_file_handle_sync(handle) |
Fermer un handle réutilisable. |
shutdown() |
shutdown_sync() |
Libérez les connexions et émettez les indicateurs finaux. |
La méthode asynchrone list_dir(path) renvoie un itérateur ; utilisez async for pour consommer les entrées de répertoire.
Utilisez des lectures par plage pour les formats de modèle qui ne nécessitent pas chaque octet. L’accélérateur distribué pour le stockage cloud stocke uniquement les blocs qui couvrent les plages demandées.
Optimiser les performances en lecture
Ajustez la concurrence de lecture de l’application et la taille de la plage d’octets demandée ensemble. Les meilleurs réglages dépendent de votre modèle d’accès, des limites de processeur et de mémoire du pod, de la bande passante réseau entre le client et le nœud de cache, et du fait que les lectures sont satisfaites par le cache ou basculent sur le Stockage Blob.
Utilisez les valeurs de cette section comme points de départ pour des benchmarks de charge de travail, pas pour des recommandations de performance garanties. Mesurez leur effet avec votre propre charge de travail avant de déployer des changements.
Ajuster la concurrence
La concurrence correspond au nombre de lectures que votre application maintient en cours. Une boucle qui attend chaque read_blob appel avant de commencer le suivant est séquentielle, même lorsqu’elle utilise l’API asynchrone.
- Émettez simultanément des lectures indépendantes de la plage d’octets ou des blobs. Limitez le nombre de lectures actives à un
asyncio.Semaphoreou à un nombre fixe de tâches worker. Ne créez pas une tâche pour chaque plage d’un grand jeu de données en même temps. - Commencez par une petite limite, comme quatre lectures simultanées, et comparez-la avec huit et seize. Augmentez le niveau de concurrence uniquement tant que le débit s’améliore, sans entraîner de latence, de consommation mémoire, d’erreurs ou de limitation du débit à des niveaux inacceptables.
- Le client natif accepte un objet
concurrent.futures.Executorvia le paramètreexecutorde son constructeur. Pour contrôler explicitement le pool de threads Python, passez unThreadPoolExecutor, par exemple,DACSCacheClient(executor=ThreadPoolExecutor(max_workers=8)). Conservez une référence à l’executor, gardez-la active jusqu’à la fin de toutes les lectures, puis éteignez-la après avoir appeléawait client.shutdown(). - Un pool de threads plus grand ne rend pas des appels séquentiels concurrents. Liez les tâches applicatives ainsi que les workers d’exécution, et utilisez un tampon séparé pour chaque lecture active.
Tenez compte de la concurrence entre tous les processus de travail et les pods. Augmenter la concurrence de chaque pod lors d’un scale-out peut surcharger les mêmes nœuds de cache ou augmenter les téléchargements de Blob en double lors des ratés de cache à froid.
Configurer la taille des blocs de cache
Définissez SI_streamingChunkSize en octets sur les pods d’application pour configurer la taille des blocs de cache. Par exemple, le réglage suivant utilise des chunks de 3 Mio :
env:
- name: SI_streamingChunkSize
value: "3145728"
Définissez cette variable avant de créer le premier client dans un processus. Redémarrez les pods d’application après les avoir modifiés.
La taille par défaut du bloc de cache est de 32 Mio. L’argument size de read_blob(path, buffer, size, offset) spécifie la plage d’octets demandée par l’application, et non la taille du bloc de cache.
| Modèle d’accès | Recommandations relatives à la lecture des données par les applications |
|---|---|
| Lectures séquentielles de modèles volumineux | Comparez les plus grands blocs de cache, les tailles de plage demandées et la concurrence limitée. Modifiez un paramètre à la fois. |
| Petites ou aléatoires opérations de lecture | Demandez uniquement les octets dont l’application a besoin. Comparez des blocs de cache de plus petite taille afin de réduire la quantité de données récupérées en dehors de la plage demandée. |
| Caches à capacité limitée | Mesurez l’occupation du cache et le comportement d’éviction plutôt que d’estimer l’utilisation du cache uniquement à partir de la taille des mémoires tampons de lecture de l’application. |
L'application budgétaire lit les tampons séparément des chunks de cache. Par exemple, huit requêtes simultanées de 4 Mio read_blob nécessitent une capacité du tampon de lecture de l’application de 32 Mio, quelle que soit la taille configurée du bloc de cache. Réservez de la mémoire pod supplémentaire pour les allocations native-client, le travail en file d’attente, les objets Python et le traitement de modèles. N’acquérez les mémoires tampons qu’après avoir respecté la limite de concurrence, et libérez chaque mémoire tampon dans un bloc finally.
Warning
BoundedBufferManager(max_memory_limit=...) Limite la capacité de lecture tampon de l’application, pas la mémoire totale du client ni la mise en mémoire tampon native du téléversement. Dans 0.1.0, le budget par défaut du tampon d’envoi asynchrone du client natif est de 400 Gio. Ce budget n’est ni une préallocation ni une limite sûre de mémoire Pod. De grandes lectures depuis un cache froid peuvent épuiser un Pod plus petit. Pour les charges de travail limitées en mémoire, testez la population synchrone (SI_cacheEnableSyncUpload=true) ou un budget d’upload asynchrone borné (SI_cacheMaxUploadBufferSizePerProcessGB). Définissez ces valeurs avant de créer le premier client, et prévoyez les tampons natifs séparément des tampons de lecture d’application et du traitement du modèle.
Mesurer avant d’augmenter les limites
- Établissez une base de référence avec un jeu de données fixe, un nombre fixe de pods et des limites de ressources. Mesurez le débit, la latence de lecture, l’utilisation du processeur, de la mémoire et du réseau.
- Mesurez séparément les lectures du cache froid et du cache chaud. Examinez
cache_server_request_counteret la télémétrie d’Azure Blob pour distinguer le trafic du cache des opérations de repli avec accès direct au stockage Blob. - Modifiez un seul paramètre à la fois : le niveau de concurrence, la taille des lectures de l’application ou la taille des blocs de cache. Gardez le jeu de données et les autres paramètres cohérents lors de la comparaison des résultats.
- Arrêtez d’augmenter un réglage lorsque le débit stagne ou que la latence, la pression des ressources, les erreurs ou le blob throttling augmentent.
Pour les observations côté cache, voir Surveiller l’accélérateur distribué pour le stockage cloud.
Gérer les erreurs
Toutes les exceptions DACS découlent de 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 | Signification |
|---|---|
DACSNotFoundError |
Le chemin ou le répertoire Blob n’existe pas. |
DACSExistsError |
Une application tente d’écrire sur un blob existant sans activer l’écrasement. |
DACSAuthenticationError |
Les informations d’identification sont manquantes ou non valides. |
DACSPermissionError |
L’identité n’a pas le rôle Blob requis. |
DACSTimeoutError |
Une opération de cache ou de Blob a expiré. |
DACSNetworkError |
Le serveur de cache ou le point de terminaison Blob est inaccessible. |
DACSInvalidInputError |
Un chemin ou un argument est mal formé. |
OperationNotSupportedError |
L’API demandée n’est pas encore implémentée. |
Contrôler la journalisation
Le client dispose de contrôles de journalisation séparés pour les couches Python et native. Réglez les deux variables pour supprimer la sortie verbeuse des deux couches :
env:
- name: DACS_DATA_LOG_LEVEL
value: WARNING
- name: STORAGE_LOG_LEVEL
value: WARNING
DACS_DATA_LOG_LEVELcontrôle la journalisation Python.
STORAGE_LOG_LEVEL contrôle la journalisation native du client.