SDK di Visione artificiale di Servizi cognitivi di Azure per PythonAzure Cognitive Services Computer Vision SDK for Python

Il servizio Visione artificiale consente agli sviluppatori di accedere ad algoritmi avanzati per l'elaborazione delle immagini e la restituzione delle informazioni.The Computer Vision service provides developers with access to advanced algorithms for processing images and returning information. Gli algoritmi di Visione artificiale analizzano il contenuto di un'immagine in diversi modi, in base alle caratteristiche visive a cui si è interessati.Computer Vision algorithms analyze the content of an image in different ways, depending on the visual features you're interested in.

Per altre informazioni sul servizio, vedere Informazioni su Visione artificiale.For more information about this service, see What is Computer Vision?.

Per altre informazioni, vedere:Looking for more documentation?

PrerequisitiPrerequisites

Se non si ha una sottoscrizione di AzureIf you don't have an Azure Subscription

Creare una chiave gratuita valida 7 giorni con l'esperienza Prova per il servizio Visione artificiale.Create a free key valid for 7 days with the Try It experience for the Computer Vision service. Dopo aver creato la chiave, copiarla insieme al nome dell'endpoint.When the key is created, copy the key and endpoint name. Questa operazione è necessaria per creare il client.You will need this to create the client.

Dopo la creazione della chiave, conservare i valori seguenti:Keep the following after the key is created:

  • Valore della chiave: una stringa di 32 caratteri nel formato xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxKey value: a 32 character string with the format of xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  • Endpoint della chiave: l'URL dell'endpoint di base, https://westcentralus.api.cognitive.microsoft.comKey endpoint: the base endpoint URL, https://westcentralus.api.cognitive.microsoft.com

Se si ha una sottoscrizione di AzureIf you have an Azure Subscription

Il metodo più semplice per creare una risorsa nella sottoscrizione consiste nell'usare il comando seguente dell'interfaccia della riga di comando di Azure.The easiest method to create a resource in your subscription is to use the following Azure CLI command. In questo modo viene creata una chiave di Servizi cognitivi che può essere usata in molti servizi cognitivi.This creates a Cognitive Service key that can be used across many cognitive services. È necessario scegliere il nome del gruppo di risorse esistente, ad esempio "my-cogserv-group", e il nome della nuova risorsa di Visione artificiale, ad esempio "my-computer-vision-resource".You need to choose the existing resource group name, for example, "my-cogserv-group" and the new computer vision resource name, such as "my-computer-vision-resource".

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 CognitiveServices \
    --sku S0 \
    --yes

Installare l'SDKInstall the SDK

Installare il pacchetto dell'SDK di Visione artificiale di Servizi cognitivi di Azure per Python con pip:Install the Azure Cognitive Services Computer Vision SDK for Python package with pip:

pip install azure-cognitiveservices-vision-computervision

AuthenticationAuthentication

Dopo aver creato la risorsa Visione artificiale, per creare un'istanza dell'oggetto client sono necessarie l'endpoint e una delle chiavi dell'account di tale risorsa.Once you create your Computer Vision resource, you need its endpoint, and one of its account keys to instantiate the client object.

Usare questi valori per la creazione dell'istanza dell'oggetto client ComputerVisionClient.Use these values when you create the instance of the ComputerVisionClient client object.

Usare ad esempio il terminale Bash per impostare le variabili di ambiente:For example, use the Bash terminal to set the environment variables:

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

Per gli utenti di sottoscrizioni di Azure, ottenere le credenziali per la chiave e l'endpointFor Azure subscription users, get credentials for key and endpoint

Se non si ricordano la chiave e l'endpoint, è possibile usare il metodo seguente per trovarle.If you do not remember your endpoint and key, you can use the following method to find them. Se è necessario creare un endpoint e un'area, è possibile usare il metodo per i titolari delle sottoscrizioni di Azure o per gli utenti senza una sottoscrizione di Azure.If you need to create a key and endpoint, you can use the method for Azure subscription holders or for users without an Azure subscription.

Usare il frammento di codice seguente dell'interfaccia della riga di comando di Azure per popolare due variabili di ambiente con l'endpoint e una delle chiavi dell'account di Visione artificiale. Questi valori sono disponibili anche nel portale di Azure.Use the Azure CLI snippet below to populate two environment variables with the Computer Vision account endpoint and one of its keys (you can also find these values in the Azure portal). Il frammento è presentato nel formato per la shell Bash.The snippet is formatted for the Bash shell.

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

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

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

Creare il clientCreate client

Ottenere la chiave e l'endpoint dalle variabili di ambiente e quindi creare l'oggetto client ComputerVisionClient.Get the endpoint and key from environment variables then create the ComputerVisionClient client object.

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

# Get endpoint and key from environment variables
import os
endpoint = os.environ['ACCOUNT_ENDPOINT']
key = os.environ['ACCOUNT_KEY']

# Set credentials
credentials = CognitiveServicesCredentials(key)

# Create client
client = ComputerVisionClient(endpoint, credentials)

EsempiExamples

Per eseguire una delle attività seguenti è necessario un oggetto client ComputerVisionClient.You need a ComputerVisionClient client object before using any of the following tasks.

Analizzare un'immagineAnalyze an image

È possibile analizzare un'immagine per individuare determinate caratteristiche con analyze_image.You can analyze an image for certain features with analyze_image. Usare la proprietà visual_features per impostare i tipi di analisi da eseguire sull'immagine.Use the visual_features property to set the types of analysis to perform on the image. I valori comuni sono VisualFeatureTypes.tags e VisualFeatureTypes.description.Common values are VisualFeatureTypes.tags and 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 soggettoGet subject domain list

Esaminare i domini soggetto usati per analizzare l'immagine con list_models.Review the subject domains used to analyze your image with list_models. Questi nomi di dominio verranno usati per analizzare un'immagine in base al dominio.These domain names are used when analyzing an image by domain. Un esempio di dominio è landmarks.An example of a domain is landmarks.

models = client.list_models()

for x in models.models_property:
    print(x)

Analizzare un'immagine in base al dominioAnalyze an image by domain

È possibile analizzare un'immagine in base al dominio soggetto con analyze_image_by_domain.You can analyze an image by subject domain with analyze_image_by_domain. Ottenere l'elenco dei domini soggetto supportati per usare il nome di dominio corretto.Get the list of supported subject domains in order to use the correct domain name.

# type of prediction
domain = "landmarks"

# Public domain image of Eiffel tower
url = "https://images.pexels.com/photos/338515/pexels-photo-338515.jpeg"

# English language response
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'immagineGet text description of an image

È possibile ottenere una descrizione testuale di un'immagine, in base alla lingua, con describe_image.You can get a language-based text description of an image with describe_image. Se si esegue l'analisi del testo per le parole chiave associate all'immagine, richiedere diverse descrizioni con la proprietà max_description.Request several descriptions with the max_description property if you are doing text analysis for keywords associated with the image. 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.Examples of a text description for the following image include a train crossing a bridge over a body of water, a large bridge over a body of water, and 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'immagineGet text from image

È possibile ottenere qualsiasi testo stampato o scritto a mano da un'immagine.You can get any handwritten or printed text from an image. A questo scopo sono necessarie due chiamate all'SDK: batch_read_file e get_read_operation_result.This requires two calls to the SDK: batch_read_file and get_read_operation_result. La chiamata a batch_read_file è asincrona.The call to batch_read_file is asynchronous. Prima di estrarre dati di testo, è necessario controllare nei risultati della chiamata a get_read_operation_result se la prima chiamata è stata completata con TextOperationStatusCodes.In the results of the get_read_operation_result call, you need to check if the first call completed with TextOperationStatusCodes before extracting the text data. I risultati includono sia il testo sia le coordinate del rettangolo di selezione per il testo.The results include the text as well as the bounding box coordinates for the text.

# import models
from azure.cognitiveservices.vision.computervision.models import TextOperationStatusCodes
import time

url = "https://azurecomcdn.azureedge.net/cvt-1979217d3d0d31c5c87cbd991bccfee2d184b55eeb4081200012bdaf6a65601a/images/shared/cognitive-services-demos/read-text/read-1-thumbnail.png"
raw = True
custom_headers = None
numberOfCharsInOperationId = 36

# Async SDK call
rawHttpResponse = client.batch_read_file(url, custom_headers,  raw)

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

# SDK call
while True:
    result = client.get_read_operation_result(operationId)
    if result.status not in ['NotStarted', 'Running']:
        break
    time.sleep(1)

# Get data
if result.status == TextOperationStatusCodes.succeeded:
    for textResult in result.recognition_results:
        for line in textResult.lines:
            print(line.text)
            print(line.bounding_box)

Generare un'anteprimaGenerate thumbnail

È possibile generare un'anteprima in formato JPG di un'immagine con generate_thumbnail.You can generate a thumbnail (JPG) of an image with generate_thumbnail. L'anteprima non deve necessariamente avere le stesse proporzioni dell'immagine originale.The thumbnail does not need to be in the same proportions as the original image.

Installare Pillow per usare questo esempio:Install Pillow to use this example:

pip install Pillow

Dopo aver installato Pillow, usare il pacchetto dell'esempio di codice seguente per generare l'immagine di anteprima.Once Pillow is installed, use the package in the following code example to generate the thumbnail image.

# Pillow package
from PIL import Image

# IO package to create local 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 problemiTroubleshooting

GeneraleGeneral

Quando si interagisce con l'oggetto client ComputerVisionClient usando l'SDK per Python, per la restituzione degli errori viene usata la classe ComputerVisionErrorException.When you interact with the ComputerVisionClient client object using the Python SDK, the ComputerVisionErrorException class is used to return errors. Gli errori restituiti dal servizio corrispondono agli stessi codici di stato HTTP restituiti per le richieste di API REST.Errors returned by the service correspond to the same HTTP status codes returned for REST API requests.

Se si prova ad analizzare un'immagine con una chiave non valida, ad esempio, viene restituito un errore 401.For example, if you try to analyze an image with an invalid key, a 401 error is returned. Nel frammento di codice seguente, l'errore viene gestito normalmente rilevando l'eccezione e visualizzando informazioni aggiuntive sull'errore.In the following snippet, the error is handled gracefully by catching the exception and displaying additional information about the error.


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 endpoint are correct.")
    else:
        raise

Gestire gli errori temporanei con nuovi tentativiHandle transient errors with retries

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.While working with the ComputerVisionClient client, you might encounter transient failures caused by rate limits enforced by the service, or other transient problems like network outages. 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.For information about handling these types of failures, see Retry pattern in the Cloud Design Patterns guide, and the related Circuit Breaker pattern.

Passaggi successiviNext steps