Notes
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.
S’APPLIQUE À :
Kit de développement logiciel (SDK) Azure Machine Learning v1 pour Python
Important
Cet article fournit des informations sur l’utilisation du Kit de développement logiciel (SDK) Azure Machine Learning v1. Le SDK v1 est déprécié depuis le 31 mars 2025 et la prise en charge de celui-ci prendra fin le 30 juin 2026. Vous pouvez installer et utiliser le Kit de développement logiciel (SDK) v1 jusqu’à cette date.
Nous vous recommandons de passer au SDK v2 avant le 30 juin 2026. Pour plus d’informations sur le Kit de développement logiciel (SDK) v2, consultez Présentation du Kit de développement logiciel (SDK) Python Azure Machine Learning v2 et référence du Kit de développement logiciel (SDK) v2.
Cet article explique comment écrire des scripts d’entrée pour des cas d’usage spécialisés dans Azure Machine Learning. Un script d’entrée, également appelé script de scoring, accepte les demandes, utilise un modèle pour noter les données et retourne une réponse.
Prérequis
Modèle Machine Learning entraîné que vous envisagez de déployer avec Azure Machine Learning. Pour plus d’informations sur le déploiement de modèles, consultez Déployer des modèles Machine Learning sur Azure.
Générer automatiquement un schéma Swagger
Pour générer automatiquement un schéma pour votre service web, fournissez un exemple d’entrée ou de sortie dans le constructeur pour l’un des objets de type définis. Le type et l’exemple sont utilisés pour créer automatiquement le schéma. Azure Machine Learning crée ensuite une spécification OpenAPI (anciennement une spécification Swagger) pour le service web pendant le déploiement.
Avertissement
N’utilisez pas de données sensibles ou privées pour l’exemple d’entrée ou de sortie. Dans Azure Machine Learning, la page Swagger pour inférence expose les exemples de données.
Les types suivants sont actuellement pris en charge :
pandasnumpypyspark- Objet Python standard
Pour utiliser la génération de schéma, incluez le package open source inference-schema version 1.1.0 ou ultérieure dans votre fichier de dépendances. Pour plus d’informations sur ce package, consultez InferenceSchema sur GitHub. Pour générer un Swagger conforme pour la consommation automatisée de services web, la fonction run de votre script de scoring doit respecter les conditions suivantes :
- Le premier paramètre doit avoir le type
StandardPythonParameterType, être nomméInputset être imbriqué. - Il doit y avoir un deuxième paramètre facultatif de type
StandardPythonParameterTypenomméGlobalParameters. - La fonction doit retourner un dictionnaire de type
StandardPythonParameterTypenomméResultset imbriqué.
Définissez les exemples de formats d’entrée et de sortie dans les variables sample_input et sample_output, qui représentent les formats de requête et de réponse pour le service web. Utilisez ces exemples dans les éléments décoratifs des fonctions d’entrée et de sortie sur la fonction run. L’exemple scikit-learn de la section suivante utilise la génération de schéma.
Point de terminaison compatible Power BI
L’exemple suivant montre comment définir la run fonction en fonction des instructions de la section précédente. Vous pouvez utiliser ce script lorsque vous utilisez votre service web déployé à partir de Power BI.
import os
import json
import pickle
import numpy as np
import pandas as pd
import azureml.train.automl
import joblib
from sklearn.linear_model import Ridge
from inference_schema.schema_decorators import input_schema, output_schema
from inference_schema.parameter_types.standard_py_parameter_type import StandardPythonParameterType
from inference_schema.parameter_types.numpy_parameter_type import NumpyParameterType
from inference_schema.parameter_types.pandas_parameter_type import PandasParameterType
def init():
global model
# Replace the file name if needed.
model_path = os.path.join(os.getenv('AZUREML_MODEL_DIR'), 'sklearn_regression_model.pkl')
# Deserialize the model file back into a sklearn model.
model = joblib.load(model_path)
# Provide three sample inputs for schema generation.
numpy_sample_input = NumpyParameterType(np.array([[1,2,3,4,5,6,7,8,9,10],[10,9,8,7,6,5,4,3,2,1]],dtype='float64'))
pandas_sample_input = PandasParameterType(pd.DataFrame({'name': ['Sarah', 'John'], 'age': [25, 26]}))
standard_sample_input = StandardPythonParameterType(0.0)
# The following sample is a nested input sample. Any item wrapped by `ParameterType` is described by the schema.
sample_input = StandardPythonParameterType({'input1': numpy_sample_input,
'input2': pandas_sample_input,
'input3': standard_sample_input})
sample_global_parameters = StandardPythonParameterType(1.0) # This line is optional.
sample_output = StandardPythonParameterType([1.0, 1.0])
outputs = StandardPythonParameterType({'Results':sample_output}) # "Results" is case sensitive.
@input_schema('Inputs', sample_input)
# "Inputs" is case sensitive.
@input_schema('GlobalParameters', sample_global_parameters)
# The preceding line is optional. "GlobalParameters" is case sensitive.
@output_schema(outputs)
def run(Inputs, GlobalParameters):
# The parameters in the preceding line have to match those in the decorator. "Inputs" and
# "GlobalParameters" are case sensitive.
try:
data = Inputs['input1']
# The data gets converted to the target format.
assert isinstance(data, np.ndarray)
result = model.predict(data)
return result.tolist()
except Exception as e:
error = str(e)
return error
Conseil
La valeur de retour du script peut être n’importe quel objet Python sérialisable au format JSON. Par exemple, si votre modèle retourne un dataframe Pandas qui contient plusieurs colonnes, vous pouvez utiliser un décorateur de sortie similaire au code suivant :
output_sample = pd.DataFrame(data=[{"a1": 5, "a2": 6}])
@output_schema(PandasParameterType(output_sample))
...
result = model.predict(data)
return result
Données binaires (image)
Si votre modèle accepte des données binaires, comme une image, vous devez modifier le fichier score.py que votre déploiement utilise afin qu’il accepte les requêtes HTTP brutes. Pour accepter des données brutes, utilisez la classe AMLRequest dans votre script d’entrée et ajoutez l’ élément décoratif @rawhttp à la fonction run.
Le script score.py suivant accepte les données binaires :
from azureml.contrib.services.aml_request import AMLRequest, rawhttp
from azureml.contrib.services.aml_response import AMLResponse
from PIL import Image
import json
def init():
print("This is init()")
@rawhttp
def run(request):
print("This is run()")
if request.method == 'GET':
# For this example, return the URL for GET requests.
respBody = str.encode(request.full_path)
return AMLResponse(respBody, 200)
elif request.method == 'POST':
file_bytes = request.files["image"]
image = Image.open(file_bytes).convert('RGB')
# For a real-world solution, load the data from the request body
# and send it to the model. Then return the response.
# For demonstration purposes, this example returns the size of the image as the response.
return AMLResponse(json.dumps(image.size), 200)
else:
return AMLResponse("bad request", 500)
Important
La classe AMLRequest se trouve dans l’espace de noms azureml.contrib. Les entités de cet espace de noms sont en aperçu. Ils changent fréquemment pendant que le service subit des améliorations. Microsoft n’offre pas de prise en charge complète de ces entités.
Si vous devez tester le code qui utilise cette classe dans votre environnement de développement local, vous pouvez installer les composants à l’aide de la commande suivante :
pip install azureml-contrib-services
Remarque
Nous vous déconseillons d’utiliser 500 comme code d’état personnalisé. Côté routeurazureml-fe d’inférence Azure Machine Learning, le code d’état est réécrit en 502.
- Le code d’état est transmis
azureml-fe, puis envoyé au client. - Le code
azureml-feréécrit la500retournée du côté modèle en tant que502. Le client reçoit un code de502. - Si le
azureml-fecode lui-même retourne500, le côté client reçoit toujours un code de500.
Lorsque vous utilisez la AMLRequest classe, vous pouvez accéder uniquement aux données brutes publiées dans le fichier score.py. Il n’existe aucun composant côté client. À partir d’un client, vous pouvez publier des données comme d’habitude. Par exemple, le code Python suivant lit un fichier image et publie les données :
import requests
uri = service.scoring_uri
image_path = 'test.jpg'
files = {'image': open(image_path, 'rb').read()}
response = requests.post(uri, files=files)
print(response.json)
Mise en commun de ressources inter-origines
Le partage de ressources inter-origines (CORS) permet aux ressources d’une page web d’être demandées à partir d’un autre domaine. CORS fonctionne via des en-têtes HTTP envoyés avec la requête cliente et retournés avec la réponse du service. Pour plus d'informations sur CORS et les en-têtes valides, consultez Partage de ressources inter-origines.
Pour configurer que votre modèle de déploiement prend en charge le partage des ressources Cross-Origin, utilisez la classe AMLResponse dans votre script d’entrée. Lorsque vous utilisez cette classe, vous pouvez définir les en-têtes sur l’objet réponse.
L’exemple suivant définit l’en-tête Access-Control-Allow-Origin de la réponse à partir du script d’entrée :
from azureml.contrib.services.aml_request import AMLRequest, rawhttp
from azureml.contrib.services.aml_response import AMLResponse
def init():
print("This is init()")
@rawhttp
def run(request):
print("This is run()")
print("Request: [{0}]".format(request))
if request.method == 'GET':
# For this example, just return the URL for GET.
# For a real-world solution, you would load the data from URL params or headers
# and send it to the model. Then return the response.
respBody = str.encode(request.full_path)
resp = AMLResponse(respBody, 200)
resp.headers["Allow"] = "OPTIONS, GET, POST"
resp.headers["Access-Control-Allow-Methods"] = "OPTIONS, GET, POST"
resp.headers['Access-Control-Allow-Origin'] = "http://www.example.com"
resp.headers['Access-Control-Allow-Headers'] = "*"
return resp
elif request.method == 'POST':
reqBody = request.get_data(False)
# For a real-world solution, you would load the data from reqBody
# and send it to the model. Then return the response.
resp = AMLResponse(reqBody, 200)
resp.headers["Allow"] = "OPTIONS, GET, POST"
resp.headers["Access-Control-Allow-Methods"] = "OPTIONS, GET, POST"
resp.headers['Access-Control-Allow-Origin'] = "http://www.example.com"
resp.headers['Access-Control-Allow-Headers'] = "*"
return resp
elif request.method == 'OPTIONS':
resp = AMLResponse("", 200)
resp.headers["Allow"] = "OPTIONS, GET, POST"
resp.headers["Access-Control-Allow-Methods"] = "OPTIONS, GET, POST"
resp.headers['Access-Control-Allow-Origin'] = "http://www.example.com"
resp.headers['Access-Control-Allow-Headers'] = "*"
return resp
else:
return AMLResponse("bad request", 400)
Important
La classe AMLRequest se trouve dans l’espace de noms azureml.contrib. Les entités de cet espace de noms sont en aperçu. Ils changent fréquemment pendant que le service subit des améliorations. Microsoft n’offre pas de prise en charge complète de ces entités.
Si vous devez tester le code qui utilise cette classe dans votre environnement de développement local, vous pouvez installer les composants à l’aide de la commande suivante :
pip install azureml-contrib-services
Avertissement
Azure Machine Learning achemine uniquement les requêtes POST et GET vers les conteneurs qui exécutent le service de scoring. Les erreurs peuvent se produire si les navigateurs utilisent des requêtes OPTIONS pour émettre des demandes préliminaires.
Charger les modèles inscrits
Il existe deux façons de localiser les modèles dans votre script d’entrée :
AZUREML_MODEL_DIR: variable d’environnement qui contient le chemin d’accès à l’emplacement du modèleModel.get_model_path: API qui retourne le chemin d’accès au fichier de modèle à l’aide du nom du modèle inscrit
AZUREML_MODEL_DIR
AZUREML_MODEL_DIR est une variable d’environnement créée pendant le déploiement du service. Vous pouvez utiliser cette variable d’environnement pour rechercher l’emplacement des modèles déployés.
Le tableau suivant décrit les valeurs possibles de AZUREML_MODEL_DIR pour un nombre variable de modèles déployés :
| Déploiement | Valeur de la variable d’environnement |
|---|---|
| Modèle unique | Chemin d’accès au dossier qui contient le modèle. |
| Modèles multiples | Chemin d’accès au dossier qui contient tous les modèles. Les modèles se trouvent par nom et version dans ce dossier au format <model-name>/<version>. |
Pendant l’inscription et le déploiement du modèle, les modèles sont placés dans le AZUREML_MODEL_DIR chemin d’accès, et leurs noms de fichiers d’origine sont conservés.
Pour obtenir le chemin d'accès à un fichier modèle dans votre script d'entrée, combinez la variable d'environnement avec le chemin du fichier que vous recherchez.
Modèle unique
L’exemple suivant montre comment trouver le chemin d’accès lorsque vous disposez d’un modèle unique :
import os
# In the following example, the model is a file.
model_path = os.path.join(os.getenv('AZUREML_MODEL_DIR'), 'sklearn_regression_model.pkl')
# In the following example, the model is a folder that contains a file.
file_path = os.path.join(os.getenv('AZUREML_MODEL_DIR'), 'my_model_folder', 'sklearn_regression_model.pkl')
Modèles multiples
L’exemple suivant montre comment trouver le chemin d’accès lorsque vous avez plusieurs modèles. Dans ce scénario, deux modèles sont inscrits auprès de l’espace de travail :
my_first_model: ce modèle contient un fichier, my_first_model.pkl et a une version.1my_second_model: ce modèle contient un fichier, my_second_model.pkl, et a deux versions,1et2.
Lorsque vous déployez le service, vous fournissez les deux modèles dans l’opération de déploiement :
from azureml.core import Workspace, Model
# Get a handle to the workspace.
ws = Workspace.from_config()
first_model = Model(ws, name="my_first_model", version=1)
second_model = Model(ws, name="my_second_model", version=2)
service = Model.deploy(ws, "myservice", [first_model, second_model], inference_config, deployment_config)
Dans l’image Docker qui héberge le service, la AZUREML_MODEL_DIR variable d’environnement contient le dossier où se trouvent les modèles. Dans ce dossier, chaque modèle est situé dans un chemin de dossier de <model-name>/<version>. Dans ce chemin, <model-name> il s’agit du nom du modèle inscrit et <version> de la version du modèle. Les fichiers qui composent le modèle inscrit sont stockés dans ces dossiers.
Dans cet exemple, le chemin d’accès du premier modèle est $AZUREML_MODEL_DIR/my_first_model/1/my_first_model.pkl. Le chemin du second modèle est $AZUREML_MODEL_DIR/my_second_model/2/my_second_model.pkl.
# In the following example, the model is a file, and the deployment contains multiple models.
first_model_name = 'my_first_model'
first_model_version = '1'
first_model_path = os.path.join(os.getenv('AZUREML_MODEL_DIR'), first_model_name, first_model_version, 'my_first_model.pkl')
second_model_name = 'my_second_model'
second_model_version = '2'
second_model_path = os.path.join(os.getenv('AZUREML_MODEL_DIR'), second_model_name, second_model_version, 'my_second_model.pkl')
get_model_path
Quand vous inscrivez un modèle, vous fournissez un nom de modèle qui est utilisé pour gérer le modèle dans le Registre. Vous utilisez ce nom avec la méthode Model.get_model_path pour récupérer le chemin d’accès du fichier ou des fichiers de modèle sur le système de fichiers local. Si vous inscrivez un dossier ou une collection de fichiers, cette API retourne le chemin d’accès du dossier qui contient ces fichiers.
Quand vous inscrivez un modèle, vous lui donnez un nom. Le nom correspond à l’endroit où le modèle est placé, localement ou durant le déploiement du service.
Exemples spécifiques de l’infrastructure
Pour plus d’exemples de script d’entrée pour des cas d’usage spécifiques de Machine Learning, consultez les articles suivants :