Configuration de l'environnement Python pour SageMaker

La plupart des défaillances de déploiement SageMaker qui ressemblent à des problèmes AWS sont en réalité des problèmes d'environnement Python : mauvaise version de Python, résolution de dépendances cassée, SDK obsolète qui ne connaît pas l'API actuelle. Cette skill rend la configuration d'env ennuyeuse et correcte.

Règles fondamentales

1. Ne jamais utiliser le Python système. Toujours travailler à l'intérieur d'un environnement isolé.
2. Épinglez la version de Python, pas les versions des packages. Utilisez 3.10, 3.11 ou 3.12. Évitez 3.13+ — les bibliothèques ML traînent en matière de disponibilité des wheels et la résolution des dépendances casse de façon confuse.
3. Installez la dernière version de chaque package. Ne pas épingler défensivement boto3 ou awscli. Les versions plus récentes ont des surfaces d'API actuelles et des correctifs de sécurité. Épinglez seulement si l'utilisateur demande explicitement une version spécifique.
4. Vérifiez les versions installées correctement. Utilisez importlib.metadata.version("package-name"), jamais module.__version__. Ce dernier est incohérent d'un package à l'autre.
5. Les scripts fournis utilisent boto3 directement. Le SageMaker Python SDK est une alternative valide — voir « boto3 vs le SageMaker SDK » ci-dessous.

boto3 vs le SageMaker SDK

Les scripts de déploiement fournis (deploy.py, deploy_async.py, teardown.py) utilisent boto3 directement et lisent les URIs d'images dans le catalogue des conteneurs d'apprentissage profond publiés par AWS. Cela correspond au design aux étapes explicites du workflow — chaque skill produit une valeur concrète (région, ARN du rôle, URI de l'image) que le suivant consomme — et boto3 est le client API stable sous-jacent.

Le SageMaker Python SDK (v3) peut être utilisé quand l'utilisateur le préfère ou que son projet l'utilise déjà. Depuis le PR #5960 (juin 2026), ModelBuilder achemine automatiquement les modèles HuggingFace vers les conteneurs actuels (text-generation → HuggingFace vLLM, multimodal → vLLM-Omni, embeddings → TEI). N'évitez pas le SDK pour des problèmes d'image obsolète ou de mauvais conteneur — cet acheminement est corrigé.

Deux cas spécifiques du SDK qui nécessitent encore de l'attention :

• Rerankers génératifs : le SDK achemine la tâche text-ranking à TEI inconditionnellement, ce qui est incorrect pour les rerankers causal-LM comme Qwen3-Reranker — ceux-ci ont besoin de vLLM (voir hf-cloud-serving-image-selection). Passez le conteneur explicitement pour ces modèles.
• Identifiants de rôle supposé SSO : v3 a eu des régressions de résolution des identifiants dans ModelTrainer / FrameworkProcessor sous les profils SSO. Si les appels du SDK échouent avec des erreurs d'identifiants tandis que aws sts get-caller-identity réussit dans le même shell, suspectez cela plutôt que votre configuration AWS.

Si vous utilisez le SDK, installez-le dans l'env isolé comme tout le reste (.venv/bin/python -m pip install sagemaker). Les scripts fournis ne le nécessitent pas.

Comment mettre en place

Le chemin le plus rapide est le script fourni — c'est du Python, donc il s'exécute de la même façon sur Windows, macOS et Linux :

python3 scripts/setup_env.py        # macOS / Linux
python  scripts/setup_env.py        # Windows (PowerShell / cmd)

Ce script détecte uv et l'utilise s'il est disponible (plus rapide), revient à la méthode stdlib venv, crée .venv/ avec Python 3.12 (remplacer : python3 setup_env.py .venv 3.11), refuse les versions de Python non supportées, installe à partir du fichier requirements.txt fourni, et est idempotent. Il affiche aussi le bon chemin d'interpréteur pour l'OS hôte (voir ci-dessous).

Équivalent manuel :

# Préféré : uv
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python --upgrade boto3 awscli   # Windows : .venv\Scripts\python.exe

# Fallback : stdlib venv
python3.12 -m venv .venv
.venv/bin/python -m pip install --upgrade pip boto3 awscli

Après la mise en place, invoquez explicitement le Python de l'env plutôt que d'activer la venv. Le chemin d'interpréteur diffère selon la plateforme :

.venv/bin/python deploy.py            # macOS / Linux
.venv\Scripts\python.exe deploy.py    # Windows

Cela fonctionne de la même façon dans les scripts, les shells interactifs et les appels d'outils d'agent. Le reste de cette skill écrit .venv/bin/python par souci de concision — sur Windows remplacez par .venv\Scripts\python.exe.

Vérification

.venv/bin/python scripts/check_versions.py

Affiche les versions de boto3, botocore, awscli. Utilise importlib.metadata.version() donc cela fonctionne sur tous les packages, y compris ceux sans __version__. Passez des noms arbitraires : ... check_versions.py transformers huggingface_hub.

Extras spécifiques au déploiement

Le fichier requirements.txt par défaut couvre l'orchestration SageMaker. Certains déploiements ont besoin d'extras (huggingface_hub pour l'inspection de modèles, transformers pour la validation de tokenizer). Ajoutez-les à un fichier requirements spécifique au déploiement dans le projet, installez avec le Python de l'env, n'épinglez pas sauf s'il y a une raison.

Pièges courants

Erreurs de résolution pip install mystérieuses Presque toujours Python 3.13+ essayant d'installer des packages sans wheels encore, ou installer dans un Python système pollué. Recréez à 3.12 : supprimez .venv et relancez python3 setup_env.py .venv 3.12 (le script recrée l'env quand la version ne correspond pas, donc vous pouvez aussi simplement le relancer).

pip install a réussi mais le script dit « module not found » Vous avez installé dans un interpréteur différent de celui qui exécute le script. Invoquez toujours Python explicitement : .venv/bin/python -m pip install ... et .venv/bin/python deploy.py.

Les one-liners python -c "..." inline échouent dans PowerShell Les règles de guillemets de PowerShell malmènent les guillemets imbriqués/échappés dans le Python inline. Ne déboguez pas le guillemeting — écrivez le snippet dans un petit fichier .py et exécutez-le. (Tous les helpers fournis sont des fichiers pour exactement cette raison.)

L'appel boto3 échoue avec « unknown parameter » Votre boto3 est plus ancien que la surface d'API. Mettez à jour avec .venv/bin/python -m pip install --upgrade boto3. Ne rétrogradez pas le script pour correspondre à une ancienne version.

sagemaker (le SDK) installé mais les scripts fournis échouent Les scripts fournis n'utilisent pas le SDK — ils ont seulement besoin de boto3/awscli du fichier requirements.txt. Installer sagemaker à côté est inoffensif, mais cela ne remplace pas l'installation des requirements.