SDK di Visione artificiale di Servizi cognitivi di Azure per Python

  • Articolo

Il servizio Visione artificiale consente agli sviluppatori di accedere ad algoritmi avanzati per l'elaborazione delle immagini e la restituzione delle informazioni. Gli algoritmi di Visione artificiale analizzano il contenuto di un'immagine in diversi modi, in base alle caratteristiche visive a cui si è interessati.

È possibile usare Visione artificiale in un'applicazione per:

  • Analizzare le immagini per ottenere informazioni dettagliate
  • Estrarre testo dalle immagini
  • Generare anteprime

Per altre informazioni, vedere:

Prerequisiti

Se è necessario un account API Visione artificiale, è possibile crearne uno con questo comando dell'interfaccia della riga di comando di Azure:

RES_REGION=westeurope
RES_GROUP=<resourcegroup-name>
ACCT_NAME=<computervision-account-name>

az cognitiveservices account create \
    --resource-group $RES_GROUP \
    --name $ACCT_NAME \
    --location $RES_REGION \
    --kind ComputerVision \
    --sku S1 \
    --yes

Installazione

Installare l'SDK di Visione artificiale di Servizi cognitivi di Azure con pip. Facoltativamente, eseguire l'installazione in un ambiente virtuale.

Configurare un ambiente virtuale (facoltativo)

Nonostante non sia obbligatorio, è possibile mantenere gli ambienti del sistema di base e degli SDK di Azure isolati tra loro usando un ambiente virtuale. Eseguire questi comandi per configurare un ambiente virtuale con venv, ad esempio cogsrv-vision-env, e quindi passare a tale ambiente:

python3 -m venv cogsrv-vision-env
source cogsrv-vision-env/bin/activate

Installare l'SDK

Installare il pacchetto dell'SDK di Visione artificiale di Servizi cognitivi di Azure per Python con pip:

pip install azure-cognitiveservices-vision-computervision

Autenticazione

Dopo aver creato la risorsa Visione artificiale, per creare un'istanza dell'oggetto client sono necessarie l'area e una delle chiavi dell'account di tale risorsa.

Usare questi valori per la creazione dell'istanza dell'oggetto client ComputerVisionClient.

Ottenere le credenziali

Usare il frammento seguente dell'interfaccia della riga di comando di Azure per popolare due variabili di ambiente con l'area e una delle chiavi dell'account Visione artificiale. Questi valori sono disponibili anche nel portale di Azure. Il frammento è presentato nel formato per la shell Bash.

RES_GROUP=<resourcegroup-name>
ACCT_NAME=<computervision-account-name>

export ACCOUNT_REGION=$(az cognitiveservices account show \
    --resource-group $RES_GROUP \
    --name $ACCT_NAME \
    --query location \
    --output tsv)

export ACCOUNT_KEY=$(az cognitiveservices account keys list \
    --resource-group $RES_GROUP \
    --name $ACCT_NAME \
    --query key1 \
    --output tsv)

Creare il client

Dopo aver popolato le ACCOUNT_REGION variabili di ambiente e ACCOUNT_KEY , è possibile creare l'oggetto client ComputerVisionClient .

from azure.cognitiveservices.vision.computervision import ComputerVisionClient
from azure.cognitiveservices.vision.computervision.models import VisualFeatureTypes
from msrest.authentication import CognitiveServicesCredentials

import os
region = os.environ['ACCOUNT_REGION']
key = os.environ['ACCOUNT_KEY']

credentials = CognitiveServicesCredentials(key)
client = ComputerVisionClient(
    endpoint="https://" + region + ".api.cognitive.microsoft.com/",
    credentials=credentials
)

Utilizzo

Dopo aver inizializzato un oggetto client ComputerVisionClient , è possibile:

  • Analizzare un'immagine: è possibile analizzare un'immagine per determinate funzionalità, ad esempio visi, colori, tag.
  • Genera anteprime: creare un'immagine JPEG personalizzata da usare come anteprima dell'immagine originale.
  • Ottenere la descrizione di un'immagine: ottenere una descrizione dell'immagine in base al relativo dominio soggetto.

Per altre informazioni sul servizio, vedere Informazioni su Visione artificiale.

Esempio

Le sezioni seguenti contengono diversi frammenti di codice relativi ad alcune delle attività più comuni di Visione artificiale:

Analizzare un'immagine

È possibile analizzare un'immagine per individuare determinate caratteristiche con analyze_image. Usare la proprietà visual_features per impostare i tipi di analisi da eseguire sull'immagine. I valori comuni sono VisualFeatureTypes.tags e VisualFeatureTypes.description.

url = "https://upload.wikimedia.org/wikipedia/commons/thumb/1/12/Broadway_and_Times_Square_by_night.jpg/450px-Broadway_and_Times_Square_by_night.jpg"

image_analysis = client.analyze_image(url,visual_features=[VisualFeatureTypes.tags])

for tag in image_analysis.tags:
    print(tag)

Ottenere l'elenco dei domini soggetto

Esaminare i domini soggetto usati per analizzare l'immagine con list_models. Questi nomi di dominio verranno usati per analizzare un'immagine in base al dominio. Un esempio di dominio è landmarks.

models = client.list_models()

for x in models.models_property:
    print(x)

Analizzare un'immagine in base al dominio

È possibile analizzare un'immagine in base al dominio soggetto con analyze_image_by_domain. Ottenere l'elenco dei domini soggetto supportati per usare il nome di dominio corretto.

domain = "landmarks"
url = "https://images.pexels.com/photos/338515/pexels-photo-338515.jpeg"
language = "en"

analysis = client.analyze_image_by_domain(domain, url, language)

for landmark in analysis.result["landmarks"]:
    print(landmark["name"])
    print(landmark["confidence"])

Ottenere la descrizione testuale di un'immagine

È possibile ottenere una descrizione testuale di un'immagine, in base alla lingua, con describe_image. Se si esegue l'analisi del testo per le parole chiave associate all'immagine, richiedere diverse descrizioni con la proprietà max_description. Gli esempi di descrizione testuale dell'immagine seguente includono a train crossing a bridge over a body of water, a large bridge over a body of water e a train crossing a bridge over a large body of water.

domain = "landmarks"
url = "http://www.public-domain-photos.com/free-stock-photos-4/travel/san-francisco/golden-gate-bridge-in-san-francisco.jpg"
language = "en"
max_descriptions = 3

analysis = client.describe_image(url, max_descriptions, language)

for caption in analysis.captions:
    print(caption.text)
    print(caption.confidence)

Ottenere testo da un'immagine

È possibile ottenere qualsiasi testo stampato o scritto a mano da un'immagine. A questo scopo sono necessarie due chiamate all'SDK: read e get_read_result. La chiamata a lettura è asincrona. Nei risultati della chiamata get_read_result è necessario verificare se la prima chiamata è stata completata prima OperationStatusCodes di estrarre i dati di testo. I risultati includono sia il testo sia le coordinate del rettangolo di selezione per il testo.

# import models
from azure.cognitiveservices.vision.computervision.models import OperationStatusCodes

url = "https://github.com/Azure-Samples/cognitive-services-python-sdk-samples/raw/master/samples/vision/images/make_things_happen.jpg"
raw = True
numberOfCharsInOperationId = 36

# SDK call
rawHttpResponse = client.read(url, language="en", raw=True)

# Get ID from returned headers
operationLocation = rawHttpResponse.headers["Operation-Location"]
idLocation = len(operationLocation) - numberOfCharsInOperationId
operationId = operationLocation[idLocation:]

# SDK call
result = client.get_read_result(operationId)

# Get data
if result.status == OperationStatusCodes.succeeded:

    for line in result.analyze_result.read_results[0].lines:
        print(line.text)
        print(line.bounding_box)

Generare un'anteprima

È possibile generare un'anteprima in formato JPG di un'immagine con generate_thumbnail. L'anteprima non deve necessariamente avere le stesse proporzioni dell'immagine originale.

Questo esempio usa il pacchetto Pillow per salvare la nuova immagine di anteprima in locale.

from PIL import Image
import io

width = 50
height = 50
url = "http://www.public-domain-photos.com/free-stock-photos-4/travel/san-francisco/golden-gate-bridge-in-san-francisco.jpg"

thumbnail = client.generate_thumbnail(width, height, url)

for x in thumbnail:
    image = Image.open(io.BytesIO(x))

image.save('thumbnail.jpg')

Risoluzione dei problemi

Generale

Quando si interagisce con l'oggetto client ComputerVisionClient usando l'SDK per Python, per la restituzione degli errori viene usata la classe ComputerVisionErrorException. Gli errori restituiti dal servizio corrispondono agli stessi codici di stato HTTP restituiti per le richieste di API REST.

Se si prova ad analizzare un'immagine con una chiave non valida, ad esempio, viene restituito un errore 401. Nel frammento di codice seguente l'errore viene gestito normalmente rilevando l'eccezione e visualizzando informazioni aggiuntive sull'errore.


domain = "landmarks"
url = "http://www.public-domain-photos.com/free-stock-photos-4/travel/san-francisco/golden-gate-bridge-in-san-francisco.jpg"
language = "en"
max_descriptions = 3

try:
    analysis = client.describe_image(url, max_descriptions, language)

    for caption in analysis.captions:
        print(caption.text)
        print(caption.confidence)
except HTTPFailure as e:
    if e.status_code == 401:
        print("Error unauthorized. Make sure your key and region are correct.")
    else:
        raise

Gestire gli errori temporanei con nuovi tentativi

Mentre si usa il client ComputerVisionClient, potrebbero verificarsi errori temporanei causati dai limiti di frequenza applicati dal servizio o altri problemi temporanei come interruzioni della rete. Per informazioni sulla gestione di questi tipi di errori, vedere Modello di ripetizione dei tentativi nella guida Modelli di progettazione cloud e l'articolo correlato Modello a interruttore.

Passaggi successivi

Altro codice di esempio

Diversi esempi per l'SDK di Visione artificiale per Python sono disponibili nel repository GitHub dell'SDK. Questi esempi offrono codice di esempio per altri scenari comuni correlati all'uso di Visione artificiale:

Documentazione aggiuntiva

Per informazioni più complete sul servizio Visione artificiale, vedere la documentazione su Visione artificiale di Azure in docs.microsoft.com.