Partilhar 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. Isto significa:

  • Você criou um recurso de Visão Computacional e obteve uma chave e um URL de ponto final.
  • Você tem o pacote SDK apropriado instalado e tem um aplicativo de início rápido em execução. Você pode modificar este aplicativo de início rápido com base em exemplos de código aqui.

Criar e autenticar o cliente

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

Importante

Se você usar uma chave de API, armazene-a com segurança em outro lugar, como no Cofre de Chaves do Azure. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente.

Para obter mais informações sobre segurança de serviços de IA, consulte Autenticar solicitações para serviços de IA do Azure.

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 analisar

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 formatos de imagem suportados.

URL de 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 do Analysis 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. Consulte a visão geral para obter 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 Captions visuais e DenseCaptions são suportados apenas em determinadas regiões do Azure: consulte Disponibilidade da região

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

Selecionar opções de análise

Use um objeto ImageAnalysisOptions para especificar várias opções para a chamada da API Analyze Image.

  • Idioma: Você pode especificar o idioma dos dados retornados. O idioma é opcional, com o padrão sendo o inglês. Consulte Suporte a idiomas para obter uma lista de códigos de idiomas suportados e quais recursos visuais são suportados para cada idioma.
  • Legendas neutras em termos de género: se estiver a extrair legendas ou legendas densas (utilizando VisualFeatures.Caption ou VisualFeatures.DenseCaptions), pode pedir legendas neutras em termos de género. As legendas neutras em termos de género são opcionais, sendo o predefinido as 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.
  • Proporção do corte: um índice de aspeto é calculado dividindo a largura do corte alvo pela altura. Os valores suportados são de 0,75 a 1,8 (inclusive). A definição dessa 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 proporção adequada. Neste caso, a 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 Analyze no objeto ImageAnalysisClient, conforme mostrado aqui. A chamada é síncrona e bloqueia a execução 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 a partir de um buffer de imagem em vez de URL, substitua imageURL na chamada de método pela imageData variável.

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 Analyze.

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}");

Resolução de Problemas

Processamento 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 200 código de status (bem-sucedido) resulta em uma exceção sendo lançada. Por exemplo, se você tentar analisar uma imagem que não está acessível devido a uma URL quebrada, um 400 status será retornado, indicando uma solicitação incorreta, e uma exceção correspondente será lançada.

No trecho 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;
    }
}

Você pode saber mais sobre como habilitar o log do SDK aqui.

Pré-requisitos

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

Criar e autenticar o cliente

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

Importante

Se você usar uma chave de API, armazene-a com segurança em outro lugar, como no Cofre de Chaves do Azure. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente.

Para obter mais informações sobre segurança de serviços de IA, consulte Autenticar solicitações para serviços de IA do Azure.

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

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

Selecione a imagem a analisar

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 formatos de imagem suportados.

URL de Imagem

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

# 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 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 do Analysis 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. Consulte a visão geral para obter 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ão suportados apenas em determinadas regiões do Azure. Consulte Disponibilidade da região.

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

Chame 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 outras opções, 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 inteligentes

Uma proporção é calculada dividindo a largura da safra alvo pela altura. Os valores suportados são de 0,75 a 1,8 (inclusive). A definição dessa propriedade só é relevante quando VisualFeatures.SMART_CROPS foi selecionada 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 proporção que considerar adequada. Neste caso, a proporção está entre 0,5 e 2,0 (inclusive).

Selecionar legendas neutras em termos de género

Se você estiver extraindo legendas ou legendas densas (usando VisualFeatures.CAPTION ou VisualFeatures.DENSE_CAPTIONS), poderá pedir legendas neutras em termos de gênero. As legendas neutras em termos de género são opcionais, sendo o predefinido as 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 línguas

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

Obter resultados do serviço

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

# 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}")

Resolução de Problemas

Exceções

Os analyze métodos geram uma exceção HttpResponseError para uma resposta de código de status HTTP sem êxito do serviço. A exceção é o código de status_code status da resposta HTTP. A exceção error.message 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 fornece um 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.

Registo

O cliente usa a biblioteca de log Python padrão. O SDK registra detalhes de solicitação e resposta HTTP, o que pode ser útil na solução de problemas. Para fazer login 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 as cargas úteis de solicitação e resposta. Para criar logs sem redação, defina o argumento logging_enable = True do método ao criar ImageAnalysisCliento , ou quando chamar analyze o 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 logging.DEBUG de log. 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. Isto significa:

  • Você criou um recurso de Visão Computacional e obteve uma chave e um URL de ponto final.
  • Você tem o pacote SDK apropriado instalado e tem um aplicativo de início rápido em execução. Você pode modificar este aplicativo de início rápido com base em exemplos de código aqui.

Criar e autenticar o cliente

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

Importante

Se você usar uma chave de API, armazene-a com segurança em outro lugar, como no Cofre de Chaves do Azure. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente.

Para obter mais informações sobre segurança de serviços de IA, consulte Autenticar solicitações para serviços de IA do Azure.

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 analisar

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 formatos de imagem suportados.

URL de Imagem

Crie uma imageUrl cadeia de caracteres 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 do Analysis 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. Consulte a visão geral para obter 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ão suportados apenas em determinadas regiões do Azure. Consulte Disponibilidade da região.

// 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 opções de análise

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

  • Idioma: Você pode especificar o idioma dos dados retornados. O idioma é opcional, com o padrão sendo o inglês. Consulte Suporte a idiomas para obter uma lista de códigos de idiomas suportados e quais recursos visuais são suportados para cada idioma.
  • Legendas neutras em termos de género: se estiver a extrair legendas ou legendas densas (utilizando VisualFeatures.CAPTION ou VisualFeatures.DENSE_CAPTIONS), pode pedir legendas neutras em termos de género. As legendas neutras em termos de género são opcionais, sendo o predefinido as 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.
  • Proporção do corte: um índice de aspeto é calculado dividindo a largura do corte alvo pela altura. Os valores suportados são de 0,75 a 1,8 (inclusive). A definição dessa propriedade só é relevante quando VisualFeatures.SMART_CROPS foi selecionada 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 proporção que considerar adequada. Neste caso, a 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. A 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 em vez disso e chamar seu método analyzeFromUrl , que não é bloqueador.

Para analisar a partir de um buffer de imagem em vez de URL, chame o método analyze em vez disso e passe o 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 do analyzeFromUrl e analisar operações.

// 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());
}

Resolução de Problemas

Exceções

Os analyze métodos lançam HttpResponseException quando o serviço responde com um código de status HTTP sem êxito. A exceção contém o código de getResponse().getStatusCode() status da resposta HTTP. A exceção getMessage() 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 o log de solicitação/resposta HTTP

Revisar a solicitação HTTP enviada ou a resposta recebida por fio para o serviço de Análise de Imagem pode ser útil na solução de problemas. A biblioteca de cliente do Image Analysis suporta uma estrutura de log de console interna para fins de depuração temporária. Ele também suporta registro mais avançado usando a interface SLF4J . Para obter informações detalhadas, consulte Usar o log no SDK do Azure para Java.

As seções abaixo abordam a habilitação do registro em log do console usando a estrutura interna.

Definindo variáveis de ambiente

Você pode habilitar o log do console de solicitação e resposta HTTP para todo o seu 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 de solicitações e respostas HTTP.

  • Definir variável AZURE_LOG_LEVEL de ambiente como debug
  • Defina a variável AZURE_HTTP_LOG_DETAIL_LEVEL de ambiente para um dos seguintes valores:
Value Nível de registo
none O registo de pedidos/respostas HTTP está desativado
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 de solicitação e resposta.
body_and_headers Registra tudo em CABEÇALHOS e CORPO.

Definindo httpLogOptions

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

  • Definir variável AZURE_LOG_LEVEL de ambiente 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();

O enum HttpLogDetailLevel define os níveis de log suportados.

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

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. Quando partilhar um registo não redigido, certifique-se de que não contém segredos, como a sua chave de subscrição.

Pré-requisitos

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

  • Você criou um recurso de Visão Computacional e obteve uma chave e um URL de ponto final.
  • Você tem o pacote SDK apropriado instalado e tem um aplicativo de início rápido em execução. Você pode modificar este aplicativo de início rápido com base nos exemplos de código aqui.

Criar e autenticar o cliente

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

Importante

Se você usar uma chave de API, armazene-a com segurança em outro lugar, como no Cofre de Chaves do Azure. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente.

Para obter mais informações sobre segurança de serviços de IA, consulte Autenticar solicitações para serviços de IA do Azure.

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 analisar

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 formatos de imagem suportados.

URL de Imagem

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

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 do Analysis 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. Consulte Visão geral para obter 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ão suportados apenas em determinadas regiões do Azure. Consulte .

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

Chame a API de análise com opções

O código a seguir chama a API Analyze Image com os recursos selecionados acima e outras opções, definidas a seguir. Para analisar a partir 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 inteligentes

Uma proporção é calculada dividindo a largura da safra alvo pela altura. Os valores suportados são de 0,75 a 1,8 (inclusive). A definição dessa 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 proporção adequada. Neste caso, a proporção está entre 0,5 e 2,0 (inclusive).

Selecionar legendas neutras em termos de género

Se você estiver extraindo legendas ou legendas densas (usando VisualFeatures.Caption ou VisualFeatures.DenseCaptions), poderá pedir legendas neutras em termos de gênero. As legendas neutras em termos de género são opcionais, sendo o predefinido as 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 línguas

Você pode especificar o idioma dos dados retornados. O idioma é opcional, com o padrão sendo o inglês. Consulte Suporte a idiomas para obter uma lista de códigos de idiomas suportados e quais recursos visuais são suportados para 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)}`));
}

Resolução de Problemas

Registo

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

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

setLogLevel("info");

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

Pré-requisitos

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

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

Autenticar no serviço

Para autenticar no serviço de Análise de Imagem, você precisa de uma chave de Visão Computacional e URL de ponto de extremidade.

Importante

Se você usar uma chave de API, armazene-a com segurança em outro lugar, como no Cofre de Chaves do Azure. Não inclua a chave da API diretamente no seu código e nunca a publique publicamente.

Para obter mais informações sobre segurança de serviços de IA, consulte Autenticar solicitações para serviços de IA do Azure.

O exemplo do SDK pressupõe que você definiu as variáveis VISION_KEY de ambiente 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 para sua chave de visão. A chamada é feita para o URL <endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01, onde <endpoint> é o URL exclusivo do seu ponto de extremidade de visão computacional. Você adiciona cadeias de caracteres de consulta com base em suas opções de análise.

Selecione a imagem a analisar

O código neste guia usa imagens remotas referenciadas por URL. Você pode querer experimentar imagens diferentes por conta própria para ver a capacidade completa dos recursos de Análise de Imagem.

URL de Imagem

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

Image file

Para analisar uma imagem local, você colocaria 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 opções de análise

Selecionar recursos visuais ao usar o modelo padrão

A API do Analysis 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. Consulte a visão geral para obter 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ó são suportados em determinadas regiões do Azure: consulte Disponibilidade da região.

Nota

A API REST usa os termos Smart Crops e Smart Crops Aspect Ratios. O SDK usa os termos Sugestões de corte e Proporções de corte. Ambos se referem à mesma operação de serviço. Da mesma forma, a API REST usa o termo Read para detetar texto na imagem usando o Optical Character Recognition (OCR), enquanto o SDK usa o termo Text para a mesma operação.

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

Parâmetro de URL valor Description
features read Lê o texto visível na imagem e o produz como dados JSON estruturados.
features caption Descreve o conteúdo da imagem com uma frase completa em idiomas suportados.
features denseCaptions Gera legendas detalhadas para até 10 regiões de imagem proeminentes.
features smartCrops Localiza as coordenadas do retângulo que cortariam a imagem para uma proporção desejada, preservando a área de interesse.
features objects Deteta vários objetos dentro de uma imagem, incluindo 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 Deteta pessoas que aparecem em imagens, incluindo os locais aproximados.

Um URL preenchido pode ter esta aparência:

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

Definir o nome do modelo ao usar um modelo personalizado

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

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

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

Especificar línguas

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

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

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

Parâmetro de URL valor Description
language en Inglês
language es Espanhol
language ja Japonês
language pt Português
language zh Chinês Simplificado

Um URL preenchido pode ter esta aparência:

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

Selecionar legendas neutras em termos de género

Se estiver a extrair legendas ou legendas densas, pode pedir legendas neutras em termos de género. As legendas neutras em termos de género são opcionais, sendo o predefinido as 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 neutra em termos de género só se aplica quando estiver a utilizar o modelo padrão.

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

Um URL preenchido pode ter esta aparência:

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

Selecionar proporções de corte inteligentes

Uma proporção é calculada dividindo a largura da safra alvo pela altura. Os valores suportados são de 0,75 a 1,8 (inclusive). A definição dessa 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 proporção adequada. Neste caso, a proporção está entre 0,5 e 2,0 (inclusive).

As rações inteligentes de aspeto de corte só se aplicam quando você estiver usando o modelo padrão.

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

Um URL preenchido pode ter esta aparência:

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

Obter resultados do serviço

Obter resultados usando 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 200 resposta HTTP 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 de erro

Em caso de erro, a resposta do serviço Análise de Imagem contém uma carga 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 está uma lista de erros comuns e suas causas. Os itens da 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. Certifique-se de que 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 comprimindo-a e/ou redimensionando-a e reenvie sua solicitação.
    • InvalidRequest - The feature 'Caption' is not supported in this region. O recurso só é suportado em regiões específicas do Azure. Consulte 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, Content-Type deve ser application/json
      • Para dados de imagem binária, 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. Consulte a seção Requisitos de imagem para obter os formatos de imagem suportados.
    • InvalidRequest - Analyze query is invalid
      • NotSupportedVisualFeature - Specified feature type is not valid. Verifique se a cadeia de caracteres de consulta de recursos tem um valor válido.
      • NotSupportedLanguage - The input language is not supported. Verifique se a cadeia de caracteres de consulta de idioma 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 conseguiu encontrar o modelo personalizado com base no nome fornecido pela cadeia de caracteres de model-name consulta.

Próximos passos

  • Explore os artigos conceituais para saber mais sobre cada recurso.
  • Explore os exemplos de código do SDK no GitHub:
  • Consulte a referência da API REST para saber mais sobre a funcionalidade da API.