Script di immissione avanzati

SI APPLICA A:Azure Machine Learning SDK v1 per Python

Importante

Questo articolo fornisce informazioni sull'uso di Azure Machine Learning SDK v1. SDK v1 è deprecato a partire dal 31 marzo 2025. Il supporto per questo terminerà il 30 giugno 2026. È possibile installare e usare l'SDK v1 fino a tale data. I flussi di lavoro esistenti che usano SDK v1 continueranno a funzionare dopo la data di fine del supporto. Tuttavia, potrebbero essere esposti a rischi per la sicurezza o a modifiche di rilievo nel caso di cambiamenti dell'architettura del prodotto.

È consigliabile passare all'SDK v2 prima del 30 giugno 2026. Per altre informazioni su SDK v2, vedere Che cos'è l'interfaccia della riga di comando di Azure Machine Learning e Python SDK v2? e il Riferimento SDK v2.

Questo articolo illustra come scrivere script di immissione per casi d'uso specializzati in Azure Machine Learning. Uno script di immissione, detto anche script di assegnazione dei punteggi, accetta le richieste, usa un modello per assegnare un punteggio ai dati e restituisce una risposta.

Prerequisiti

Modello di Machine Learning addestrato che vuoi distribuire con Azure Machine Learning. Per altre informazioni sulla distribuzione del modello, vedere Distribuire modelli di Machine Learning in Azure.

Generare automaticamente uno schema di Swagger

Per generare automaticamente uno schema per il servizio Web, fornire un esempio dell'input o dell'output nel costruttore per uno degli oggetti di tipo definiti. Il tipo e l'esempio vengono usati per creare automaticamente lo schema. Azure Machine Learning crea quindi una specifica OpenAPI (in precedenza una specifica Swagger) per il servizio Web durante la distribuzione.

Avviso

Non usare dati sensibili o privati per l'input o l'output di esempio. In Azure Machine Learning la pagina Swagger per l'inferenza espone i dati di esempio.

Sono attualmente supportati i tipi seguenti:

pandas
numpy
pyspark
Oggetto Python standard

Per usare la generazione di schemi, includere nel file delle dipendenze il pacchetto open source inference-schema versione 1.1.0 o successiva. Per altre informazioni su questo pacchetto, vedere InferenceSchema in GitHub. Per generare Swagger conforme per l'utilizzo automatizzato del servizio Web, la run funzione nello script di assegnazione dei punteggi deve soddisfare le condizioni seguenti:

Il primo parametro deve avere il tipo StandardPythonParameterType, essere denominato Inputse annidato.
Deve essere presente un secondo parametro facoltativo di tipo StandardPythonParameterType denominato GlobalParameters.
La funzione deve restituire un dizionario di tipo StandardPythonParameterType denominato Results e annidato.

Definire i formati di esempio di input e output nelle variabili sample_input e sample_output, che rappresentano i formati di richiesta e risposta per il servizio Web. Usare questi esempi negli elementi Decorator di funzione di input e output nella funzione run. Nell'esempio scikit-learn riportato nella sezione seguente viene utilizzata la generazione dello schema.

Endpoint compatibile con Power BI

Nell'esempio seguente viene illustrato come definire la run funzione in base alle istruzioni riportate nella sezione precedente. È possibile usare questo script quando si usa il servizio Web distribuito da 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

Suggerimento

Il valore restituito dallo script può essere qualsiasi oggetto Python serializzabile in JSON. Ad esempio, se il modello restituisce un dataframe Pandas contenente più colonne, è possibile utilizzare un decoratore di output simile a questo esempio di codice:

output_sample = pd.DataFrame(data=[{"a1": 5, "a2": 6}])
@output_schema(PandasParameterType(output_sample))
...
result = model.predict(data)
return result

Dati binari (immagine)

Se il modello accetta dati binari, ad esempio un'immagine, è necessario modificare il file score.py usato dalla distribuzione in modo che accetti richieste HTTP non elaborate. Per accettare dati non elaborati, usare la classe AMLRequest nello script di immissione e aggiungere l'elemento Decorator @rawhttp alla funzione run.

Lo script di score.py seguente accetta dati binari:

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)

Importante

La classe AMLRequest si trova nello spazio dei nomi azureml.contrib. Le entità in questo spazio dei nomi sono in versione di anteprima. Cambiano frequentemente mentre il servizio subisce miglioramenti. Microsoft non offre supporto completo per queste entità.

Se è necessario testare il codice che usa questa classe nell'ambiente di sviluppo locale, è possibile installare i componenti usando il comando seguente:

pip install azureml-contrib-services

Nota

Non è consigliabile usare 500 come codice di stato personalizzato. Il codice di stato sul lato router di inferenza di Azure Machine Learning (azureml-fe) viene riscritto in 502.

Il codice di stato viene passato azureml-fe e quindi inviato al client.
Il azureml-fe codice riscrive il 500 restituito dal lato del modello come 502. Il client riceve un codice di 502.
Se il azureml-fe codice stesso restituisce 500, il lato client riceve comunque un codice di 500.

Quando si usa la AMLRequest classe , è possibile accedere solo ai dati pubblicati non elaborati nel file score.py. Non esiste alcun componente lato client. Da un client è possibile pubblicare i dati come di consueto. Ad esempio, il codice Python seguente legge un file di immagine e inserisce i dati:

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)

La condivisione di risorse tra le origini (CORS) consente di richiedere le risorse in una pagina Web da un altro dominio. CORS funziona tramite intestazioni HTTP inviate con la richiesta client e restituite con la risposta del servizio. Per altre informazioni su CORS e sulle intestazioni valide, vedere la voce Cross-origin resource sharing.

Per configurare la distribuzione modello per supportare CORS, usare la classe AMLResponse nello script di immissione. Quando si usa questa classe, è possibile impostare le intestazioni sull'oggetto risposta.

Nell'esempio seguente viene impostata l'intestazione Access-Control-Allow-Origin per la risposta dello script di immissione:

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)

Importante

Se è necessario testare il codice che usa questa classe nell'ambiente di sviluppo locale, è possibile installare i componenti usando il comando seguente:

pip install azureml-contrib-services

Avviso

Azure Machine Learning instrada solo le richieste POST e GET ai contenitori che eseguono il servizio di assegnazione dei punteggi. Gli errori possono verificarsi se i browser utilizzano richieste OPZIONI per emettere richieste preliminari.

Caricare i modelli registrati

Sono disponibili due modalità per individuare i modelli nello script di immissione:

AZUREML_MODEL_DIR: variabile di ambiente contenente il percorso del modello
Model.get_model_path: API che restituisce il percorso del file del modello usando il nome del modello registrato

AZUREML_MODEL_DIR

AZUREML_MODEL_DIR è una variabile di ambiente creata durante la distribuzione del servizio. È possibile usare questa variabile di ambiente per trovare la posizione dei modelli distribuiti.

La tabella seguente descrive i possibili valori di AZUREML_MODEL_DIR per un numero variabile di modelli distribuiti:

Distribuzione	Valore della variabile di ambiente
Modello singolo	Percorso della cartella che contiene il modello.
Modelli multipli	Percorso della cartella che contiene tutti i modelli. I modelli si trovano in base al nome e alla versione in questa cartella nel formato `<model-name>/<version>`.

Durante la registrazione e la distribuzione dei modelli, questi vengono inseriti nel percorso AZUREML_MODEL_DIR e i loro nomi di file originali vengono mantenuti.

Per ottenere il percorso di un file di modello nello script di immissione, combinare la variabile di ambiente con il percorso del file desiderato.

Modello singolo

L'esempio seguente illustra come trovare il percorso quando si dispone di un singolo modello:

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')

Modelli multipli

L'esempio seguente illustra come trovare il percorso quando si dispone di più modelli. In questo scenario vengono registrati due modelli nell'area di lavoro:

my_first_model: questo modello contiene un file, my_first_model.pkl e ha una versione, 1.
my_second_model: questo modello contiene un file, my_second_model.pkl e ha due versioni 1 e 2.

Quando si distribuisce il servizio, entrambi i modelli vengono forniti nell'operazione di distribuzione:

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)

Nell'immagine Docker che ospita il servizio, la AZUREML_MODEL_DIR variabile di ambiente contiene la cartella in cui si trovano i modelli. In questa cartella ogni modello si trova in un percorso di cartella di <model-name>/<version>. In questo percorso è <model-name> il nome del modello registrato ed <version> è la versione del modello. I file che costituiscono il modello registrato vengono archiviati in queste cartelle.

In questo esempio il percorso del primo modello è $AZUREML_MODEL_DIR/my_first_model/1/my_first_model.pkl. Il percorso del secondo modello è $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

Quando si registra un modello, specificare un nome del modello usato per la gestione del modello nel Registro di sistema. Puoi utilizzare questo nome con il Model.get_model_path metodo per ottenere il percorso del file o dei file del modello sul file system locale. Se si registra una cartella o una raccolta di file, questa API restituisce il percorso della cartella che contiene tali file.

Quando si registra un modello, è necessario assegnargli un nome. Il nome corrisponde alla posizione in cui si trova il modello, ovvero in locale o durante la distribuzione del servizio.

Esempi specifici in base al framework

Per altri esempi di script di immissione per casi d'uso specifici di Machine Learning, vedere gli articoli seguenti:

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-10-30

Condividi tramite

Script di immissione avanzati

Prerequisiti

Generare automaticamente uno schema di Swagger

Endpoint compatibile con Power BI

Dati binari (immagine)

Condivisione di risorse fra origini diverse

Caricare i modelli registrati

AZUREML_MODEL_DIR

Modello singolo

Modelli multipli

get_model_path

Esempi specifici in base al framework

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive