Share via

Chamar a API de Análise de Imagem 4.0

  • Artigo

Este artigo demonstra como chamar a API de Análise de Imagem 4.0 para retornar informações sobre os recursos visuais de uma imagem. Ele também mostra como analisar as informações retornadas.

Pré-requisitos

Este guia pressupõe que você seguiu as etapas mencionadas na página de início rápido. Isso significa:

Criar e autenticar o cliente

Para se autenticar no serviço de Análise de Imagem, você precisa de uma chave de Pesquisa Visual Computacional e um URL do ponto de extremidade. Este guia pressupõe que você definiu as variáveis de ambiente VISION_KEY e VISION_ENDPOINT com sua chave e ponto de extremidade.

Dica

Não inclua a chave diretamente no código e nunca a divulgue publicamente. Confira o artigo de segurança dos serviços de IA do Azure para obter mais opções de autenticação como o Azure Key Vault.

Comece criando um objeto ImageAnalysisClient. Por exemplo:

string endpoint = Environment.GetEnvironmentVariable("VISION_ENDPOINT");
string key = Environment.GetEnvironmentVariable("VISION_KEY");

// Create an Image Analysis client.
ImageAnalysisClient client = new ImageAnalysisClient(
    new Uri(endpoint),
    new AzureKeyCredential(key));

Selecione a imagem a ser analisada

Você pode selecionar uma imagem fornecendo uma URL de imagem acessível publicamente ou passando dados binários para o SDK. Consulte Requisitos de imagem para obter formatos de imagem com suporte.

URL da imagem

Crie um objeto Uri para a imagem que você deseja analisar.

Uri imageURL = new Uri("https://aka.ms/azsdk/image-analysis/sample.jpg");

Buffer de imagem

Como alternativa, você pode passar os dados da imagem para o SDK por meio de um objeto BinaryData. Por exemplo, leia a partir de um arquivo de imagem local que você deseja analisar.

using FileStream stream = new FileStream("sample.jpg", FileMode.Open);
BinaryData imageData = BinaryData.FromStream(stream);

Selecionar recursos visuais

A API de Análise 4.0 oferece acesso a todos os recursos de análise de imagem do serviço. Escolha quais operações fazer com base em seu próprio caso de uso. Confira a visão geral de uma descrição de cada recurso. O exemplo nesta seção adiciona todos os recursos visuais disponíveis, mas para uso prático você provavelmente precisa de menos.

Importante

Os recursos visuais Captions e DenseCaptions só têm suporte nas seguintes regiões do Azure: Leste dos EUA, França Central, Coreia Central, Norte da Europa, Sudeste Asiático, Oeste da Europa, Oeste dos EUA.

VisualFeatures visualFeatures =
    VisualFeatures.Caption |
    VisualFeatures.DenseCaptions |
    VisualFeatures.Objects |
    VisualFeatures.Read |
    VisualFeatures.Tags |
    VisualFeatures.People |
    VisualFeatures.SmartCrops;

Selecionar as opções de análise

Use um objeto ImageAnalysisOptions para especificar várias opções para a chamada à API Analisar.

  • Idioma: você pode especificar o idioma dos dados retornados. O idioma é opcional, com o padrão sendo inglês. Consulte Suporte ao idioma para obter uma lista dos códigos de idioma suportados e quais recursos visuais são compatíveis com cada idioma.
  • Legendas neutras de gênero: se você estiver extraindo legendas ou legendas densas (usando VisualFeatures.Caption ou VisualFeatures.DenseCaptions), você pode pedir legendas neutras de gênero. Legendas neutras de gênero são opcionais, com o padrão sendo legendas de gênero. Por exemplo, em inglês, quando você seleciona legendas neutras de gênero, termos como mulher ou homem são substituídos por pessoa e menino ou menina são substituídos por criança.
  • Taxa de proporção de corte: uma taxa de proporção é calculada dividindo a largura da cultura de destino pela altura. Os valores com suporte são de 0,75 a 1,8 (inclusive). Definir essa propriedade só é relevante quando VisualFeatures.SmartCrops foi selecionado como parte da lista de recursos visuais. Se você selecionar VisualFeatures.SmartCrops mas não especificar proporções, o serviço retornará uma sugestão de corte com uma taxa de proporção que achar adequada. Nesse caso, a taxa de proporção está entre 0,5 e 2,0 (inclusive).
ImageAnalysisOptions options = new ImageAnalysisOptions { 
    GenderNeutralCaption = true,
    Language = "en",
    SmartCropsAspectRatios = new float[] { 0.9F, 1.33F }};

Chamar a API de Análise

Esta seção mostra como fazer uma chamada de análise para o serviço.

Chame o método Analisar no objeto ImageAnalysisClient, conforme mostrado aqui. Essa chamada é síncrona e será bloqueada até que o serviço retorne os resultados ou ocorra um erro. Como alternativa, você pode chamar o método AnalyzeAsync sem bloqueio.

Use os objetos de entrada criados nas seções acima. Para analisar de um buffer de imagem em vez de URL, substitua imageURL na chamada de método pela variável imageData.

ImageAnalysisResult result = client.Analyze(
    imageURL,
    visualFeatures,
    options);

Obter resultados do serviço

O código a seguir mostra como analisar os resultados das várias operações de Análise.

Console.WriteLine("Image analysis results:");

// Print caption results to the console
Console.WriteLine(" Caption:");
Console.WriteLine($"   '{result.Caption.Text}', Confidence {result.Caption.Confidence:F4}");

// Print dense caption results to the console
Console.WriteLine(" Dense Captions:");
foreach (DenseCaption denseCaption in result.DenseCaptions.Values)
{
    Console.WriteLine($"   '{denseCaption.Text}', Confidence {denseCaption.Confidence:F4}, Bounding box {denseCaption.BoundingBox}");
}

// Print object detection results to the console
Console.WriteLine(" Objects:");
foreach (DetectedObject detectedObject in result.Objects.Values)
{
    Console.WriteLine($"   '{detectedObject.Tags.First().Name}', Bounding box {detectedObject.BoundingBox.ToString()}");
}

// Print text (OCR) analysis results to the console
Console.WriteLine(" Read:");
foreach (DetectedTextBlock block in result.Read.Blocks)
    foreach (DetectedTextLine line in block.Lines)
    {
        Console.WriteLine($"   Line: '{line.Text}', Bounding Polygon: [{string.Join(" ", line.BoundingPolygon)}]");
        foreach (DetectedTextWord word in line.Words)
        {
            Console.WriteLine($"     Word: '{word.Text}', Confidence {word.Confidence.ToString("#.####")}, Bounding Polygon: [{string.Join(" ", word.BoundingPolygon)}]");
        }
    }

// Print tags results to the console
Console.WriteLine(" Tags:");
foreach (DetectedTag tag in result.Tags.Values)
{
    Console.WriteLine($"   '{tag.Name}', Confidence {tag.Confidence:F4}");
}

// Print people detection results to the console
Console.WriteLine(" People:");
foreach (DetectedPerson person in result.People.Values)
{
    Console.WriteLine($"   Person: Bounding box {person.BoundingBox.ToString()}, Confidence {person.Confidence:F4}");
}

// Print smart-crops analysis results to the console
Console.WriteLine(" SmartCrops:");
foreach (CropRegion cropRegion in result.SmartCrops.Values)
{
    Console.WriteLine($"   Aspect ratio: {cropRegion.AspectRatio}, Bounding box: {cropRegion.BoundingBox}");
}

// Print metadata
Console.WriteLine(" Metadata:");
Console.WriteLine($"   Model: {result.ModelVersion}");
Console.WriteLine($"   Image width: {result.Metadata.Width}");
Console.WriteLine($"   Image hight: {result.Metadata.Height}");

Solução de problemas

Tratamento de exceções

Quando você interage com a Análise de Imagem usando o SDK do .NET, qualquer resposta do serviço que não tenha um código de status (êxito) 200 resulta em uma exceção sendo gerada. Por exemplo, se você tentar analisar uma imagem que não está acessível devido a uma URL quebrada, um status 400 será retornado, indicando uma solicitação incorreta e uma exceção correspondente será gerada.

No trecho de código a seguir, os erros são tratados normalmente capturando a exceção e exibindo informações adicionais sobre o erro.

var imageUrl = new Uri("https://some-host-name.com/non-existing-image.jpg");

try
{
    var result = client.Analyze(imageUrl, VisualFeatures.Caption);
}
catch (RequestFailedException e)
{
    if (e.Status != 200)
    {
        Console.WriteLine("Error analyzing image.");
        Console.WriteLine($"HTTP status code {e.Status}: {e.Message}");
    }
    else
    {
        throw;
    }
}

Saiba mais sobre como habilitar o registro em log do SDK aqui.

Pré-requisitos

Este guia pressupõe que você seguiu as etapas mencionadas no início rápido. Isso significa:

Criar e autenticar o cliente

Para se autenticar no serviço de Análise de Imagem, você precisa de uma chave de Pesquisa Visual Computacional e um URL do ponto de extremidade. Este guia pressupõe que você definiu as variáveis de ambiente VISION_KEY e VISION_ENDPOINT com sua chave e ponto de extremidade.

Dica

Não inclua a chave diretamente no código e nunca a divulgue publicamente. Confira o artigo de segurança dos serviços de IA do Azure para obter mais opções de autenticação como o Azure Key Vault.

Comece criando um objeto ImageAnalysisClient usando um dos construtores. Por exemplo:

client = ImageAnalysisClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(key)
)

Selecione a imagem a ser analisada

Você pode selecionar uma imagem fornecendo uma URL de imagem acessível publicamente ou lendo dados de imagem no buffer de entrada do SDK. Consulte Requisitos de imagem para obter formatos de imagem com suporte.

URL da imagem

Você pode usar a seguinte URL de imagem de exemplo.

# Define image URL
image_url = "https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png"

Buffer de imagem

Como alternativa, você pode passar a imagem como objeto de bytes. Por exemplo, leia a partir de um arquivo de imagem local que você deseja analisar.

# Load image to analyze into a 'bytes' object
with open("sample.jpg", "rb") as f:
    image_data = f.read()

Selecionar recursos visuais

A API de Análise 4.0 oferece acesso a todos os recursos de análise de imagem do serviço. Escolha quais operações fazer com base em seu próprio caso de uso. Confira a visão geral de uma descrição de cada recurso. O exemplo nesta seção adiciona todos os recursos visuais disponíveis, mas para uso prático você provavelmente precisa de menos.

visual_features =[
        VisualFeatures.TAGS,
        VisualFeatures.OBJECTS,
        VisualFeatures.CAPTION,
        VisualFeatures.DENSE_CAPTIONS,
        VisualFeatures.READ,
        VisualFeatures.SMART_CROPS,
        VisualFeatures.PEOPLE,
    ]

Chamar o método analyze_from_url com opções

O código a seguir chama o método analyze_from_url no cliente com os recursos selecionados acima e opções adicionais, definidas abaixo. Para analisar a partir de um buffer de imagem em vez de URL, chame o método analyze em vez disso, com image_data=image_data como o primeiro argumento.

# Analyze all visual features from an image stream. This will be a synchronously (blocking) call.
result = client.analyze_from_url(
    image_url=image_url,
    visual_features=visual_features,
    smart_crops_aspect_ratios=[0.9, 1.33],
    gender_neutral_caption=True,
    language="en"
)

Selecionar proporções de corte inteligente

Uma taxa de proporção é calculada dividindo a largura da cultura de destino pela altura. Os valores com suporte são de 0,75 a 1,8 (inclusive). Definir essa propriedade só é relevante quando VisualFeatures.SMART_CROPS foi selecionado como parte da lista de recursos visuais. Se você selecionar VisualFeatures.SMART_CROPS mas não especificar proporções, o serviço retornará uma sugestão de corte com uma taxa de proporção que achar adequada. Nesse caso, a taxa de proporção está entre 0,5 e 2,0 (inclusive).

Selecionar legendas neutras de gênero

Se você estiver extraindo legendas ou legendas densas (usando VisualFeatures.CAPTION ou VisualFeatures.DENSE_CAPTIONS), você pode pedir legendas neutras de gênero. Legendas neutras de gênero são opcionais, com o padrão sendo legendas de gênero. Por exemplo, em inglês, quando você seleciona legendas neutras de gênero, termos como mulher ou homem são substituídos por pessoa e menino ou menina são substituídos por criança.

Especificar idiomas

Você pode especificar o idioma dos dados retornados. O idioma é opcional, com o padrão sendo inglês. Consulte Suporte ao idioma para obter uma lista dos códigos de idioma suportados e quais recursos visuais são compatíveis com cada idioma.

Obter resultados do serviço

O código a seguir mostra como analisar os resultados de operações analyze_from_url ou analyze.

# Print all analysis results to the console
print("Image analysis results:")

if result.caption is not None:
    print(" Caption:")
    print(f"   '{result.caption.text}', Confidence {result.caption.confidence:.4f}")

if result.dense_captions is not None:
    print(" Dense Captions:")
    for caption in result.dense_captions.list:
        print(f"   '{caption.text}', {caption.bounding_box}, Confidence: {caption.confidence:.4f}")

if result.read is not None:
    print(" Read:")
    for line in result.read.blocks[0].lines:
        print(f"   Line: '{line.text}', Bounding box {line.bounding_polygon}")
        for word in line.words:
            print(f"     Word: '{word.text}', Bounding polygon {word.bounding_polygon}, Confidence {word.confidence:.4f}")

if result.tags is not None:
    print(" Tags:")
    for tag in result.tags.list:
        print(f"   '{tag.name}', Confidence {tag.confidence:.4f}")

if result.objects is not None:
    print(" Objects:")
    for object in result.objects.list:
        print(f"   '{object.tags[0].name}', {object.bounding_box}, Confidence: {object.tags[0].confidence:.4f}")

if result.people is not None:
    print(" People:")
    for person in result.people.list:
        print(f"   {person.bounding_box}, Confidence {person.confidence:.4f}")

if result.smart_crops is not None:
    print(" Smart Cropping:")
    for smart_crop in result.smart_crops.list:
        print(f"   Aspect ratio {smart_crop.aspect_ratio}: Smart crop {smart_crop.bounding_box}")

print(f" Image height: {result.metadata.height}")
print(f" Image width: {result.metadata.width}")
print(f" Model version: {result.model_version}")

Solução de problemas

Exceções

Os métodos analyze geram uma exceção HttpResponseError para uma resposta de código de status HTTP sem sucesso do serviço. O status_code da exceção é o código de status de resposta HTTP. O error.message da exceção contém uma mensagem detalhada que permite diagnosticar o problema:

try:
    result = client.analyze( ... )
except HttpResponseError as e:
    print(f"Status code: {e.status_code}")
    print(f"Reason: {e.reason}")
    print(f"Message: {e.error.message}")

Por exemplo, quando você fornece uma chave de autenticação errada:

Status code: 401
Reason: PermissionDenied
Message: Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource.

Ou quando você fornece uma URL de imagem que não existe ou não está acessível:

Status code: 400
Reason: Bad Request
Message: The provided image url is not accessible.

Logging

O cliente usa a biblioteca de log do Python padrão. O SDK registra os detalhes de solicitação HTTP e resposta, o que pode ser útil na solução de problemas. Para fazer logon no stdout, adicione o seguinte:

import sys
import logging

# Acquire the logger for this client library. Use 'azure' to affect both
# 'azure.core` and `azure.ai.vision.imageanalysis' libraries.
logger = logging.getLogger("azure")

# Set the desired logging level. logging.INFO or logging.DEBUG are good options.
logger.setLevel(logging.INFO)

# Direct logging output to stdout (the default):
handler = logging.StreamHandler(stream=sys.stdout)
# Or direct logging output to a file:
# handler = logging.FileHandler(filename = 'sample.log')
logger.addHandler(handler)

# Optional: change the default logging format. Here we add a timestamp.
formatter = logging.Formatter("%(asctime)s:%(levelname)s:%(name)s:%(message)s")
handler.setFormatter(formatter)

Por padrão, os logs editam os valores das cadeias de caracteres de consulta de URL, os valores de alguns cabeçalhos de solicitação e resposta HTTP (incluindo Ocp-Apim-Subscription-Key que contém a chave) e os conteúdos de solicitação e resposta. Para criar logs sem edição, defina o argumento do método logging_enable = True quando você criar ImageAnalysisClient, ou quando chamar analyze no cliente.

# Create an Image Analysis client with none redacted log
client = ImageAnalysisClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(key),
    logging_enable=True
)

Nenhum log editado é gerado apenas para o nível de log logging.DEBUG. Certifique-se de proteger nenhum log editado para evitar comprometer a segurança. Para obter mais informações, consulte Configurar o log nas bibliotecas do Azure para Python

Pré-requisitos

Este guia pressupõe que você seguiu as etapas na página de início rápido. Isso significa:

Criar e autenticar o cliente

Para se autenticar com o serviço de Análise de Imagem, você precisa de uma chave da Pesquisa Visual Computacional e uma URL do ponto de extremidade. Este guia pressupõe que você definiu as variáveis de ambiente VISION_KEY e VISION_ENDPOINT com sua chave e ponto de extremidade.

Dica

Não inclua a chave diretamente no código e nunca a divulgue publicamente. Confira o artigo de segurança dos serviços de IA do Azure para obter mais opções de autenticação como o Azure Key Vault.

Comece criando um objeto ImageAnalysisClient. Por exemplo:

String endpoint = System.getenv("VISION_ENDPOINT");
String key = System.getenv("VISION_KEY");

if (endpoint == null || key == null) {
    System.out.println("Missing environment variable 'VISION_ENDPOINT' or 'VISION_KEY'.");
    System.out.println("Set them before running this sample.");
    System.exit(1);
}

// Create a synchronous Image Analysis client.
ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .buildClient();

Selecione a imagem a ser analisada

Você pode selecionar uma imagem fornecendo uma URL de imagem acessível publicamente ou lendo dados de imagem no buffer de entrada do SDK. Consulte Requisitos de imagem para obter formatos de imagem com suporte.

URL da imagem

Crie uma cadeia de caracteres imageUrl para manter a URL acessível publicamente da imagem que você deseja analisar.

String imageUrl = "https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png";

Buffer de imagem

Como alternativa, você pode passar a imagem como buffer de memória usando um objeto BinaryData. Por exemplo, leia a partir de um arquivo de imagem local que você deseja analisar.

BinaryData imageData = BinaryData.fromFile(new File("sample.png").toPath());

Selecionar recursos visuais

A API de Análise 4.0 oferece acesso a todos os recursos de análise de imagem do serviço. Escolha quais operações fazer com base em seu próprio caso de uso. Confira a visão geral de uma descrição de cada recurso. O exemplo nesta seção adiciona todos os recursos visuais disponíveis, mas para uso prático você provavelmente precisa de menos.

Importante

Os recursos visuais Captions e DenseCaptions só têm suporte nas seguintes regiões do Azure: Leste dos EUA, França Central, Coreia Central, Norte da Europa, Sudeste da Ásia, Oeste da Europa, Oeste dos EUA.

// visualFeatures: Select one or more visual features to analyze.
List<VisualFeatures> visualFeatures = Arrays.asList(
            VisualFeatures.SMART_CROPS,
            VisualFeatures.CAPTION,
            VisualFeatures.DENSE_CAPTIONS,
            VisualFeatures.OBJECTS,
            VisualFeatures.PEOPLE,
            VisualFeatures.READ,
            VisualFeatures.TAGS);

Selecionar as opções de análise

Use um objeto ImageAnalysisOptions para especificar várias opções para a chamada à API Analisar.

  • Idioma: você pode especificar o idioma dos dados retornados. O idioma é opcional, com o padrão sendo inglês. Consulte Suporte ao idioma para obter uma lista dos códigos de idioma suportados e quais recursos visuais são compatíveis com cada idioma.
  • Legendas de gênero neutro: se você estiver extraindo legendas ou legendas densas (usando VisualFeatures.CAPTION ou VisualFeatures.DENSE_CAPTIONS), é possível solicitar legendas de gênero neutro. Legendas neutras de gênero são opcionais, com o padrão sendo legendas de gênero. Por exemplo, em inglês, quando você seleciona legendas neutras de gênero, termos como mulher ou homem são substituídos por pessoa e menino ou menina são substituídos por criança.
  • Taxa de proporção de corte: uma taxa de proporção é calculada dividindo a largura da cultura de destino pela altura. Os valores com suporte são de 0,75 a 1,8 (inclusive). Definir essa propriedade só é relevante quando VisualFeatures.SMART_CROPS foi selecionado como parte da lista de recursos visuais. Se você selecionar VisualFeatures.SMART_CROPS mas não especificar proporções, o serviço retornará uma sugestão de corte com uma taxa de proporção que achar adequada. Nesse caso, a taxa de proporção está entre 0,5 e 2,0 (inclusive).
// Specify analysis options (or set `options` to null for defaults)
ImageAnalysisOptions options = new ImageAnalysisOptions()
    .setLanguage("en")
    .setGenderNeutralCaption(true)
    .setSmartCropsAspectRatios(Arrays.asList(0.9, 1.33, 1.78));

Chamar o método analyzeFromUrl

Esta seção mostra como fazer uma chamada de análise para o serviço.

Chame o método analyzeFromUrl no objeto ImageAnalysisClient, conforme mostrado aqui. Essa chamada é síncrona e será bloqueada até que o serviço retorne os resultados ou ocorra um erro. Como alternativa, você pode usar um objeto ImageAnalysisAsyncClient e chamar seu método analyzeFromUrl, que não é de bloqueio.

Para analisar de um buffer de imagem em vez de URL, em vez disso, chame o método analyze e passe imageData como o primeiro argumento.

try {
    // Analyze all visual features from an image URL. This is a synchronous (blocking) call.
    ImageAnalysisResult result = client.analyzeFromUrl(
        imageUrl,
        visualFeatures,
        options);

    printAnalysisResults(result);

} catch (HttpResponseException e) {
    System.out.println("Exception: " + e.getClass().getSimpleName());
    System.out.println("Status code: " + e.getResponse().getStatusCode());
    System.out.println("Message: " + e.getMessage());
} catch (Exception e) {
    System.out.println("Message: " + e.getMessage());
}

Obter resultados do serviço

O código a seguir mostra como analisar os resultados das operações analyzeFromUrl e analyze.

// Print all analysis results to the console
public static void printAnalysisResults(ImageAnalysisResult result) {

    System.out.println("Image analysis results:");

    if (result.getCaption() != null) {
        System.out.println(" Caption:");
        System.out.println("   \"" + result.getCaption().getText() + "\", Confidence "
            + String.format("%.4f", result.getCaption().getConfidence()));
    }

    if (result.getDenseCaptions() != null) {
        System.out.println(" Dense Captions:");
        for (DenseCaption denseCaption : result.getDenseCaptions().getValues()) {
            System.out.println("   \"" + denseCaption.getText() + "\", Bounding box "
                + denseCaption.getBoundingBox() + ", Confidence " + String.format("%.4f", denseCaption.getConfidence()));
        }
    }

    if (result.getRead() != null) {
        System.out.println(" Read:");
        for (DetectedTextLine line : result.getRead().getBlocks().get(0).getLines()) {
            System.out.println("   Line: '" + line.getText()
                + "', Bounding polygon " + line.getBoundingPolygon());
            for (DetectedTextWord word : line.getWords()) {
                System.out.println("     Word: '" + word.getText()
                    + "', Bounding polygon " + word.getBoundingPolygon()
                    + ", Confidence " + String.format("%.4f", word.getConfidence()));
            }
        }
    }

    if (result.getTags() != null) {
        System.out.println(" Tags:");
        for (DetectedTag tag : result.getTags().getValues()) {
            System.out.println("   \"" + tag.getName() + "\", Confidence " + String.format("%.4f", tag.getConfidence()));
        }
    }

    if (result.getObjects() != null) {
        System.out.println(" Objects:");
        for (DetectedObject detectedObject : result.getObjects().getValues()) {
            System.out.println("   \"" + detectedObject.getTags().get(0).getName() + "\", Bounding box "
                + detectedObject.getBoundingBox() + ", Confidence " + String.format("%.4f", detectedObject.getTags().get(0).getConfidence()));
        }
    }

    if (result.getPeople() != null) {
        System.out.println(" People:");
        for (DetectedPerson person : result.getPeople().getValues()) {
            System.out.println("   Bounding box "
                + person.getBoundingBox() + ", Confidence " + String.format("%.4f", person.getConfidence()));
        }
    }

    if (result.getSmartCrops() != null) {
        System.out.println(" Crop Suggestions:");
        for (CropRegion cropRegion : result.getSmartCrops().getValues()) {
            System.out.println("   Aspect ratio "
                + cropRegion.getAspectRatio() + ": Bounding box " + cropRegion.getBoundingBox());
        }
    }

    System.out.println(" Image height = " + result.getMetadata().getHeight());
    System.out.println(" Image width = " + result.getMetadata().getWidth());
    System.out.println(" Model version = " + result.getModelVersion());
}

Solução de problemas

Exceções

Os métodos analyze geram HttpResponseException quando o serviço responde com um código de status HTTP sem sucesso. O getResponse().getStatusCode() da exceção contém o código de status de resposta HTTP. O getMessage() da exceção contém uma mensagem detalhada que permite diagnosticar o problema:

try {
    ImageAnalysisResult result = client.analyze(...)
} catch (HttpResponseException e) {
    System.out.println("Exception: " + e.getClass().getSimpleName());
    System.out.println("Status code: " + e.getResponse().getStatusCode());
    System.out.println("Message: " + e.getMessage());
} catch (Exception e) {
    System.out.println("Message: " + e.getMessage());
}

Por exemplo, quando você fornece uma chave de autenticação errada:

Exception: ClientAuthenticationException
Status code: 401
Message: Status code 401, "{"error":{"code":"401","message":"Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource."}}"

Ou quando você fornece uma imagem em um formato que não é reconhecido:

Exception: HttpResponseException
Status code: 400
Message: Status code 400, "{"error":{"code":"InvalidRequest","message":"Image format is not valid.","innererror":{"code":"InvalidImageFormat","message":"Input data is not a valid image."}}}"

Habilitar registro em log de solicitação/resposta HTTP

Examinar a solicitação HTTP enviada ou a resposta recebida pela transmissão para o serviço de Análise de Imagem pode ser útil na solução de problemas. A biblioteca de clientes de Análise de Imagem dá suporte a uma estrutura de log de console interna para fins de depuração temporária. Ele também dá suporte a logs mais avançados usando a interface SLF4J. Para obter informações detalhadas, consulte Usar o registro em log no SDK do Azure para Java.

As seções abaixo discutem como habilitar o registro em log do console usando a estrutura interna.

Definindo variáveis de ambiente

Você pode habilitar o registro em log de console de solicitação HTTP e resposta para todo o aplicativo definindo as duas variáveis de ambiente a seguir. Essa alteração afeta todos os clientes do Azure que dão suporte ao registro em log de solicitação e resposta HTTP.

  • Definir variável de ambiente AZURE_LOG_LEVEL como debug
  • Defina a variável de ambiente AZURE_HTTP_LOG_DETAIL_LEVEL como um dos seguintes valores:
Valor Nível de log
none O log de solicitação/resposta HTTP está desabilitado
basic Registra somente URLs, métodos HTTP e tempo para concluir a solicitação.
headers Registra tudo em BASIC, além de todos os cabeçalhos de solicitação e resposta.
body Registra tudo em BASIC, além de todo o corpo da solicitação e da resposta.
body_and_headers Registra tudo em CABEÇALHOS e CORPO.

Definindo httpLogOptions

Para habilitar o registro em log do console de solicitação HTTP e resposta para um único cliente

  • Definir variável de ambiente AZURE_LOG_LEVEL como debug
  • Adicione uma chamada ao httpLogOptions criar o ImageAnalysisClient:
ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
    .buildClient();

A enumeração HttpLogDetailLevel define os níveis de log com suporte.

Por padrão, ao registrar em log, determinados valores de parâmetro de consulta e cabeçalho HTTP são editados. É possível substituir esse padrão especificando quais cabeçalhos e parâmetros de consulta são seguros para registrar em log:

ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS)
        .addAllowedHeaderName("safe-to-log-header-name")
        .addAllowedQueryParamName("safe-to-log-query-parameter-name"))
    .buildClient();

Por exemplo, para obter um log completo não editado da solicitação HTTP, aplique o seguinte:

    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS)
        .addAllowedHeaderName("Ocp-Apim-Subscription-Key")
        .addAllowedQueryParamName("features")
        .addAllowedQueryParamName("language")
        .addAllowedQueryParamName("gender-neutral-caption")
        .addAllowedQueryParamName("smartcrops-aspect-ratios")
        .addAllowedQueryParamName("model-version"))

Adicione mais ao acima para obter uma resposta HTTP não editada. Ao compartilhar um log não editado, verifique se ele não contém segredos, como sua chave de assinatura.

Pré-requisitos

Este guia pressupõe que você seguiu as etapas mencionadas no início rápido. Isso significa:

Criar e autenticar o cliente

Para se autenticar no serviço de Análise de Imagem, você precisa de uma chave de Pesquisa Visual Computacional e um URL do ponto de extremidade. Este guia pressupõe que você definiu as variáveis de ambiente VISION_KEY e VISION_ENDPOINT com sua chave e ponto de extremidade.

Dica

Não inclua a chave diretamente no código e nunca a divulgue publicamente. Confira o artigo de segurança dos serviços de IA do Azure para obter mais opções de autenticação como o Azure Key Vault.

Comece criando um objeto ImageAnalysisClient. Por exemplo:

// Load the .env file if it exists
require("dotenv").config();

const endpoint = process.env['VISION_ENDPOINT'] || '<your_endpoint>';
const key = process.env['VISION_KEY'] || '<your_key>';

const credential = new AzureKeyCredential(key);
const client = createClient(endpoint, credential);

Selecione a imagem a ser analisada

Você pode selecionar uma imagem fornecendo uma URL de imagem acessível publicamente ou lendo dados de imagem no buffer de entrada do SDK. Consulte Requisitos de imagem para obter formatos de imagem com suporte.

URL da imagem

Você pode usar a seguinte URL de imagem de exemplo.

const imageUrl = 'https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png';

Buffer de imagem

Como alternativa, você pode passar a imagem como uma matriz de dados. Por exemplo, leia a partir de um arquivo de imagem local que você deseja analisar.

const imagePath = '../sample.jpg';
const imageData = fs.readFileSync(imagePath);

Selecionar recursos visuais

A API de Análise 4.0 oferece acesso a todos os recursos de análise de imagem do serviço. Escolha quais operações fazer com base em seu próprio caso de uso. Confira a visão geral de uma descrição de cada recurso. O exemplo nesta seção adiciona todos os recursos visuais disponíveis, mas para uso prático você provavelmente precisa de menos.

const features = [
  'Caption',
  'DenseCaptions',
  'Objects',
  'People',
  'Read',
  'SmartCrops',
  'Tags'
];

Chamar a API de Análise com opções

O código a seguir chama a API de análise com os recursos que você selecionou acima e opções adicionais, definidas abaixo. Para analisar de um buffer de imagem em vez de URL, substitua imageURL na chamada de método por imageData.

const result = await client.path('/imageanalysis:analyze').post({
  body: {
      url: imageUrl
  },
  queryParameters: {
      features: features,
      'language': 'en',
      'gender-neutral-captions': 'true',
      'smartCrops-aspect-ratios': [0.9, 1.33]
  },
  contentType: 'application/json'
});

Selecionar proporções de corte inteligente

Uma taxa de proporção é calculada dividindo a largura da cultura de destino pela altura. Os valores com suporte são de 0,75 a 1,8 (inclusive). Definir essa propriedade só é relevante quando VisualFeatures.SmartCrops foi selecionado como parte da lista de recursos visuais. Se você selecionar VisualFeatures.SmartCrops mas não especificar proporções, o serviço retornará uma sugestão de corte com uma taxa de proporção que achar adequada. Nesse caso, a taxa de proporção está entre 0,5 e 2,0 (inclusive).

Selecionar legendas neutras de gênero

Se você estiver extraindo legendas ou legendas densas (usando VisualFeatures.Caption ou VisualFeatures.DenseCaptions), poderá pedir legendas neutras de gênero. Legendas neutras de gênero são opcionais, com o padrão sendo legendas de gênero. Por exemplo, em inglês, quando você seleciona legendas neutras de gênero, termos como mulher ou homem são substituídos por pessoa e menino ou menina são substituídos por criança.

Especificar idiomas

Você pode especificar o idioma dos dados retornados. O idioma é opcional, com o padrão sendo inglês. Consulte Suporte ao idioma para obter uma lista dos códigos de idioma suportados e quais recursos visuais são compatíveis com cada idioma.

Obter resultados do serviço

O código a seguir mostra como analisar os resultados das várias operações de análise.

const iaResult = result.body;

console.log(`Model Version: ${iaResult.modelVersion}`);
console.log(`Image Metadata: ${JSON.stringify(iaResult.metadata)}`);
if (iaResult.captionResult) {
  console.log(`Caption: ${iaResult.captionResult.text} (confidence: ${iaResult.captionResult.confidence})`);
}
if (iaResult.denseCaptionsResult) {
  iaResult.denseCaptionsResult.values.forEach(denseCaption => console.log(`Dense Caption: ${JSON.stringify(denseCaption)}`));
}
if (iaResult.objectsResult) {
  iaResult.objectsResult.values.forEach(object => console.log(`Object: ${JSON.stringify(object)}`));
}
if (iaResult.peopleResult) {
  iaResult.peopleResult.values.forEach(person => console.log(`Person: ${JSON.stringify(person)}`));
}
if (iaResult.readResult) {
  iaResult.readResult.blocks.forEach(block => console.log(`Text Block: ${JSON.stringify(block)}`));
}
if (iaResult.smartCropsResult) {
  iaResult.smartCropsResult.values.forEach(smartCrop => console.log(`Smart Crop: ${JSON.stringify(smartCrop)}`));
}
if (iaResult.tagsResult) {
  iaResult.tagsResult.values.forEach(tag => console.log(`Tag: ${JSON.stringify(tag)}`));
}

Solução de problemas

Logging

A habilitação do log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o log pode ser habilitado no runtime chamando setLogLevel em @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, veja os documentos do pacote @azure/logger.

Pré-requisitos

Este guia pressupõe que você seguiu corretamente as etapas mencionadas na página de início rápido. Isso significa:

  • Você criou um recurso de Pesquisa Visual Computacional e obteve uma chave e um URL do ponto de extremidade.
  • Você fez uma chamada curl.exe para o serviço com sucesso (ou usou uma ferramenta alternativa). Você modifica a chamada curl.exe com base nos exemplos aqui.

Autenticar-se no serviço

Para se autenticar no serviço de Análise de Imagem, você precisa de uma chave de Pesquisa Visual Computacional e um URL do ponto de extremidade.

Dica

Não inclua a chave diretamente no código e nunca a divulgue publicamente. Confira o artigo de segurança dos serviços de IA do Azure para obter mais opções de autenticação como o Azure Key Vault.

O exemplo do SDK pressupõe que você definiu as variáveis de ambiente VISION_KEY e VISION_ENDPOINT com sua chave e ponto de extremidade.

A autenticação é feita adicionando o cabeçalho de solicitação HTTP Ocp-Apim-Subscription-Key e definindo-o como sua chave de visão. A chamada é feita para a URL <endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01, em que <endpoint> é a URL exclusiva do ponto de extremidade da pesquisa visual computacional. Você adiciona cadeias de caracteres de consulta com base em suas opções de análise.

Selecione a imagem a ser analisada

O código neste guia usa imagens remotas referenciadas por URL. Talvez você queira experimentar imagens diferentes por conta própria para ver toda a funcionalidade dos recursos de Análise de Imagem.

Ao analisar uma imagem remota, especifique a URL da imagem formatando o corpo da solicitação como este: {"url":"https://learn.microsoft.com/azure/cognitive-services/computer-vision/images/windows-kitchen.jpg"}. O Content-Type deve ser application/json.

Para analisar uma imagem local, coloque os dados da imagem binária no corpo da solicitação HTTP. O Content-Type deve ser application/octet-stream ou multipart/form-data.

Selecionar as opções de análise

Selecionar recursos visuais ao utilizar o modelo padrão

A API de Análise 4.0 oferece acesso a todos os recursos de análise de imagem do serviço. Escolha quais operações fazer com base em seu próprio caso de uso. Confira a visão geral de uma descrição de cada recurso. O exemplo nesta seção adiciona todos os recursos visuais disponíveis, mas para uso prático, você provavelmente precisa de menos.

Os recursos visuais "Captions" e "DenseCaptions" são compatíveis apenas com as seguintes regiões do Azure: Leste dos EUA, França Central, Coreia Central, Norte da Europa, Sudeste da Ásia, Oeste da Europa, Oeste dos EUA.

Observação

A API REST usa os termos Cortes Inteligentes e Taxas de Proporção de Cortes Inteligentes. O SDK usa os termos Sugestões de Corte e Taxas de Proporção de Corte. Ambos se referem a mesma operação de serviço. Da mesma forma, a API REST usa o termo Leitura para detectar texto na imagem usando o Reconhecimento Óptico de Caracteres (OCR), enquanto o SDK usa o termo Texto para a mesma operação.

Você pode especificar os recursos que deseja usar definindo os parâmetros de consulta de URL da API de Análise 4.0. Um parâmetro pode ter vários valores, separados por vírgulas.

Parâmetro da URL Valor Descrição
features read Lê o texto visível na imagem e o gera como dados JSON estruturados.
features caption Descreve o conteúdo da imagem com uma frase completa nos idiomas com suporte.
features denseCaptions Gera legendas detalhadas para até 10 regiões proeminentes de imagem.
features smartCrops Localiza as coordenadas do retângulo que cortariam a imagem para uma taxa de proporção desejada, preservando a área de interesse.
features objects Detecta vários objetos dentro de uma imagem, inclusive a localização aproximada. O argumento Objects só está disponível em inglês.
features tags Marca a imagem com uma lista detalhada de palavras relacionadas ao conteúdo da imagem.
features people Detecta pessoas que aparecem em imagens, incluindo os locais aproximados.

Uma URL preenchida pode se parecer com isto:

<endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01&features=tags,read,caption,denseCaptions,smartCrops,objects,people

Defina o nome do modelo ao utilizar um modelo personalizado

Você também pode fazer análise de imagem com um modelo personalizado treinado. Para criar e treinar um modelo, consulte Criar um modelo de Análise de Imagem personalizado. Uma vez que seu modelo é treinado, tudo o que você precisa é o nome do modelo. Você não precisa especificar recursos visuais se usar um modelo personalizado.

Para usar um modelo personalizado, não utilize o parâmetro de consulta de recursos. Em vez disso, defina o parâmetro model-name como o nome do modelo, conforme mostrado aqui. Substitua MyCustomModelName pelo nome do modelo personalizado.

<endpoint>/computervision/imageanalysis:analyze?api-version=2023-02-01&model-name=MyCustomModelName

Especificar idiomas

Você pode especificar o idioma dos dados retornados. O idioma é opcional, com o padrão sendo inglês. Consulte Suporte ao idioma para obter uma lista dos códigos de idioma suportados e quais recursos visuais são compatíveis com cada idioma.

A opção de idioma só se aplica quando você está usando o modelo padrão.

O parâmetro de consulta da URL a seguir especifica o idioma. O valor padrão é en.

Parâmetro da URL Valor Descrição
language en Inglês
language es Espanhol
language ja Japonês
language pt Português
language zh Chinês simplificado

Uma URL preenchida pode se parecer com isto:

<endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01&features=caption&language=en

Selecionar legendas neutras de gênero

Se você estiver extraindo legendas ou legendas densas, poderá pedir legendas neutras de gênero. Legendas neutras de gênero são opcionais, com o padrão sendo legendas de gênero. Por exemplo, em inglês, quando você seleciona legendas neutras de gênero, termos como mulher ou homem são substituídos por pessoa e menino ou menina são substituídos por criança.

A opção de legenda de gênero neutro só se aplica quando você está usando o modelo padrão.

Adicione a cadeia de caracteres de consulta opcional gender-neutral-caption com valores true ou false (o padrão).

Uma URL preenchida pode se parecer com isto:

<endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01&features=caption&gender-neutral-caption=true

Selecionar proporções de corte inteligente

Uma taxa de proporção é calculada dividindo a largura da cultura de destino pela altura. Os valores com suporte são de 0,75 a 1,8 (inclusive). Definir essa propriedade só é relevante quando VisualFeatures.SmartCrops foi selecionado como parte da lista de recursos visuais. Se você selecionar VisualFeatures.SmartCrops mas não especificar proporções, o serviço retornará uma sugestão de corte com uma taxa de proporção que achar adequada. Nesse caso, a taxa de proporção está entre 0,5 e 2,0 (inclusive).

As taxas de proporção de corte inteligente só se aplicam quando você está usando o modelo padrão.

Adicione a cadeia de caracteres de consulta opcional smartcrops-aspect-ratios, com uma ou mais proporções separadas por uma vírgula.

Uma URL preenchida pode se parecer com isto:

<endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01&features=smartCrops&smartcrops-aspect-ratios=0.8,1.2

Obter resultados do serviço

Obtenha resultados utilizando o modelo padrão

Esta seção mostra como fazer uma chamada de análise para o serviço usando o modelo padrão e obter os resultados.

O serviço retorna uma resposta HTTP 200 e o corpo contém os dados retornados na forma de uma cadeia de caracteres JSON. O texto a seguir é um exemplo de uma resposta JSON.

{
    "modelVersion": "string",
    "captionResult": {
      "text": "string",
      "confidence": 0.0
    },
    "denseCaptionsResult": {
      "values": [
        {
          "text": "string",
          "confidence": 0.0,
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          }
        }
      ]
    },
    "metadata": {
      "width": 0,
      "height": 0
    },
    "tagsResult": {
      "values": [
        {
          "name": "string",
          "confidence": 0.0
        }
      ]
    },
    "objectsResult": {
      "values": [
        {
          "id": "string",
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          },
          "tags": [
            {
              "name": "string",
              "confidence": 0.0
            }
          ]
        }
      ]
    },
    "readResult": {
      "blocks": [
        {
          "lines": [
            {
              "text": "string",
              "boundingPolygon": [
                {
                  "x": 0,
                  "y": 0
                },
                {
                    "x": 0,
                    "y": 0
                },
                {
                    "x": 0,
                    "y": 0
                },
                {
                    "x": 0,
                    "y": 0
                }
              ],
              "words": [
                {
                  "text": "string",
                  "boundingPolygon": [
                    {
                        "x": 0,
                        "y": 0
                    },
                    {
                        "x": 0,
                        "y": 0
                    },
                    {
                        "x": 0,
                        "y": 0
                    },
                    {
                        "x": 0,
                        "y": 0
                    }
                  ],
                  "confidence": 0.0
                }
              ]
            }
          ]
        }
      ]
    },
    "smartCropsResult": {
      "values": [
        {
          "aspectRatio": 0.0,
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          }
        }
      ]
    },
    "peopleResult": {
      "values": [
        {
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          },
          "confidence": 0.0
        }
      ]
    }
  }

Códigos do Erro

Em caso de erro, a resposta do serviço de Análise de Imagem contém um conteúdo JSON que inclui um código de erro e uma mensagem de erro. Também pode incluir outros detalhes na forma de código de erro interno e mensagem. Por exemplo:

{
    "error":
    {
        "code": "InvalidRequest",
        "message": "Analyze query is invalid.",
        "innererror":
        {
            "code": "NotSupportedVisualFeature",
            "message": "Specified feature type is not valid"
        }
    }
}

A seguir há uma lista de erros comuns e suas causas. Os itens de lista são apresentados no seguinte formato:

  • Código de resposta HTTP
    • Código de erro e mensagem na resposta JSON
      • [Opcional] Código de erro interno e mensagem na resposta JSON

Lista de erros comuns:

  • 400 Bad Request
    • InvalidRequest - Image URL is badly formatted or not accessible. Verifique se o URL da imagem é válido e acessível publicamente.
    • InvalidRequest - The image size is not allowed to be zero or larger than 20971520 bytes. Reduza o tamanho da imagem compactando-a e/ou redimensionando e reenvie sua solicitação.
    • InvalidRequest - The feature 'Caption' is not supported in this region. O recurso só tem suporte em regiões específicas do Azure. Confira Pré-requisitos de início rápido para obter a lista de regiões do Azure com suporte.
    • InvalidRequest - The provided image content type ... is not supported. O cabeçalho HTTP Content-Type na solicitação não é um tipo permitido:
      • Para um URL de imagem, o Content-Type deve ser application/json
      • Para dados de imagem binários, o Content-Type deve ser application/octet-stream ou multipart/form-data
    • InvalidRequest - Either 'features' or 'model-name' needs to be specified in the query parameter.
    • InvalidRequest - Image format is not valid
      • InvalidImageFormat - Image format is not valid. Confira a seção Requisitos de imagem para obter formatos de imagem com suporte.
    • InvalidRequest - Analyze query is invalid
      • NotSupportedVisualFeature - Specified feature type is not valid. Verifique se a cadeia de caracteres de consulta features tem um valor válido.
      • NotSupportedLanguage - The input language is not supported. Verifique se a cadeia de caracteres de consulta language tem um valor válido para o recurso visual selecionado, com base na tabela a seguir.
      • BadArgument - 'smartcrops-aspect-ratios' aspect ratio is not in allowed range [0.75 to 1.8]
  • 401 PermissionDenied
    • 401 - Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource.
  • 404 Resource Not Found
    • 404 - Resource not found. O serviço não pôde localizar o modelo personalizado com base no nome fornecido pela cadeia de caracteres de consulta model-name.

Próximas etapas