Бөлісу құралы:

Вызов API анализа изображений 4.0

  • Мақала

В этой статье показано, как вызвать API анализа изображений 4.0 для возврата сведений о визуальных функциях изображения. В нем также показано, как проанализировать возвращаемые сведения.

Необходимые компоненты

В этом руководстве предполагается, что вы выполнили действия, описанные на странице краткого руководства . Это означает следующее:

  • Вы создали ресурс Компьютерное зрение и получили URL-адрес ключа и конечной точки.
  • У вас установлен соответствующий пакет SDK, и у вас есть работающее приложение быстрого запуска . Это краткое руководство можно изменить на основе примеров кода.

Создание и проверка подлинности клиента

Для проверки подлинности в службе "Анализ изображений" требуется URL-адрес Компьютерное зрение ключа и конечной точки. В этом руководстве предполагается, что вы определили переменные VISION_KEY среды и VISION_ENDPOINT с помощью ключа и конечной точки.

Внимание

Если вы используете ключ API, сохраните его в другом месте, например в Azure Key Vault. Не включайте ключ API непосредственно в код и никогда не публикуйте его.

Дополнительные сведения о безопасности служб ИИ см. в статье "Проверка подлинности запросов к службам ИИ Azure".

Начните с создания объекта ImageAnalysisClient . Например:

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

Выбор изображения для анализа

Вы можете выбрать изображение, предоставив общедоступный URL-адрес образа или передав двоичные данные в пакет SDK. См . требования к изображениям для поддерживаемых форматов изображений.

URL-адрес изображения

Создайте объект URI для изображения, который требуется проанализировать.

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

Буфер изображения

Кроме того, можно передать данные изображения в пакет SDK через объект BinaryData . Например, чтение из локального файла образа, который требуется проанализировать.

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

Выбор визуальных компонентов

API Analysis 4.0 предоставляет доступ ко всем функциям анализа изображений службы. Выберите, какие операции следует выполнять в зависимости от вашего сценария. Общие сведения о каждой функции см. в обзоре. Пример в этом разделе добавляет все доступные визуальные функции, но для практического использования, скорее всего, потребуется меньше.

Внимание

Визуальные функции Captions и DenseCaptions поддерживаются только в определенных регионах Azure: см. сведения о доступности регионов.

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

Выбор параметров анализа

Используйте объект ImageAnalysisOptions, чтобы указать различные параметры вызова API анализа изображений.

  • Язык: можно указать язык возвращаемых данных. Язык необязателен, при этом по умолчанию используется английский язык. Ознакомьтесь со списком поддерживаемых языковых кодов и визуальными функциями, поддерживаемыми для каждого языка.
  • Заголовки на гендерной нейтральной основе: если вы извлекаете подписи или плотные подписи (используя VisualFeatures.Captions или VisualFeatures.DenseCaptions), вы можете попросить пол нейтральных подписей. Заголовки с гендерной нейтральной стороны являются необязательными, при этом по умолчанию по умолчанию используются заголовки с полом. Например, на английском языке при выборе заголовков с гендерной нейтральной точки зрения термины, такие как женщина или мужчина, заменяются человеком, а мальчик или девушка заменяются ребенком.
  • Соотношение аспектов обрезки: пропорции вычисляются путем деления целевой ширины обрезки на высоту. Поддерживаемые значения : от 0,75 до 1,8 (включительно). Установка этого свойства относится только к выбору VisualFeatures.SmartCrops в качестве части списка визуальных функций. Если выбрать VisualFeatures.SmartCrops , но не указывать пропорции, служба возвращает одно предложение обрезки с пропорциями, которые он видит. В этом случае пропорция составляет от 0,5 до 2,0 (включительно).
ImageAnalysisOptions options = new ImageAnalysisOptions { 
    GenderNeutralCaption = true,
    Language = "en",
    SmartCropsAspectRatios = new float[] { 0.9F, 1.33F }};

Вызов API анализа

В этом разделе показано, как выполнить вызов анализа к службе.

Вызовите метод Analysis для объекта ImageAnalysisClient, как показано здесь. Вызов синхронный и блокирует выполнение до тех пор, пока служба не вернет результаты или произошла ошибка. Кроме того, можно вызвать неблокирующий метод AnalyzeAsync .

Используйте входные объекты, созданные в приведенных выше разделах. Чтобы проанализировать буфер изображения вместо URL-адреса, замените imageURL вызов метода переменной imageData .

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

Получение результатов из службы

В следующем коде показано, как проанализировать результаты различных операций анализа.

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

Устранение неполадок

Обработка исключений

При взаимодействии с анализом изображений с помощью пакета SDK для .NET любой 200 ответ от службы, у которой нет (успешного) кода состояния, возникает исключение. Например, если вы пытаетесь проанализировать изображение, недоступное из-за сломанного URL-адреса, 400 возвращается состояние, указывающее на неправильный запрос, и возникает соответствующее исключение.

В следующем фрагменте ошибки обрабатываются корректно путем перехвата исключения и отображения дополнительных сведений об ошибке.

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

Дополнительные сведения о включении ведения журнала пакета SDK см. здесь.

Необходимые компоненты

В этом руководстве предполагается, что вы выполнили действия краткого руководства. Это означает следующее:

  • Вы создали ресурс Компьютерное зрение и получили URL-адрес ключа и конечной точки.
  • Вы установили соответствующий пакет SDK и получили рабочее приложение быстрого запуска . Это краткое руководство можно изменить на основе примеров кода.

Создание и проверка подлинности клиента

Для проверки подлинности в службе "Анализ изображений" требуется URL-адрес Компьютерное зрение ключа и конечной точки. В этом руководстве предполагается, что вы определили переменные VISION_KEY среды и VISION_ENDPOINT с помощью ключа и конечной точки.

Внимание

Если вы используете ключ API, сохраните его в другом месте, например в Azure Key Vault. Не включайте ключ API непосредственно в код и никогда не публикуйте его.

Дополнительные сведения о безопасности служб ИИ см. в статье "Проверка подлинности запросов к службам ИИ Azure".

Начните с создания объекта ImageAnalysisClient с помощью одного из конструкторов. Например:

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

Выбор изображения для анализа

Вы можете выбрать изображение, предоставив общедоступный URL-адрес изображения или считывая данные изображения в входной буфер пакета SDK. См . требования к изображениям для поддерживаемых форматов изображений.

URL-адрес изображения

Вы можете использовать следующий пример URL-адреса изображения.

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

Буфер изображения

Кроме того, можно передать изображение в виде объекта байтов . Например, чтение из локального файла образа, который требуется проанализировать.

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

Выбор визуальных компонентов

API Analysis 4.0 предоставляет доступ ко всем функциям анализа изображений службы. Выберите, какие операции следует выполнять в зависимости от вашего сценария. Общие сведения о каждой функции см. в обзоре. Пример в этом разделе добавляет все доступные визуальные функции, но для практического использования, скорее всего, потребуется меньше.

Внимание

Подписи визуальных функций и DenseCaptions поддерживаются только в определенных регионах Azure. См . сведения о доступности региона.

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

Вызов метода analyze_from_url с параметрами

Следующий код вызывает метод analyze_from_url на клиенте с выбранными ранее функциями и другими параметрами, определенными ниже. Чтобы проанализировать буфер изображения вместо URL-адреса, вызовите вместо него метод анализа в image_data=image_data качестве первого аргумента.

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

Выбор пропорций интеллектуальной обрезки

Пропорции вычисляются путем деления целевой ширины обрезки на высоту. Поддерживаемые значения : от 0,75 до 1,8 (включительно). Установка этого свойства имеет значение только при выборе VisualFeatures.SMART_CROPS в составе списка визуальных компонентов. Если выбрать VisualFeatures.SMART_CROPS , но не указывать пропорции, служба возвращает одно предложение обрезки с пропорциями, которые он видит. В этом случае пропорция составляет от 0,5 до 2,0 (включительно).

Выбор заголовков с гендерной нейтральной позицией

Если вы извлекаете подписи или плотные подписи (используя VisualFeatures.CAPTION или VisualFeatures.DENSE_CAPTIONS), вы можете попросить заголовок с гендерной нейтральной стороны. Заголовки с гендерной нейтральной стороны являются необязательными, при этом по умолчанию по умолчанию используются заголовки с полом. Например, на английском языке при выборе заголовков с гендерной нейтральной точки зрения термины, такие как женщина или мужчина, заменяются человеком, а мальчик или девушка заменяются ребенком.

Определение языков

Вы можете указать язык возвращаемых данных. Язык необязателен, при этом по умолчанию используется английский язык. Ознакомьтесь со списком поддерживаемых языковых кодов и визуальными функциями, поддерживаемыми для каждого языка.

Получение результатов из службы

В следующем коде показано, как анализировать результаты из analyze_from_url или анализировать операции.

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

Устранение неполадок

Исключения

Методы analyze вызывают исключение HttpResponseError для ответа кода состояния HTTP без успеха из службы. status_code Исключение — это код состояния ответа HTTP. error.message Исключение содержит подробное сообщение, позволяющее диагностировать проблему:

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

Например, если указать неправильный ключ проверки подлинности:

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.

Или если указать URL-адрес изображения, который не существует или недоступен:

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

Ведение журнала

Клиент использует стандартную библиотеку ведения журналов Python. Пакет SDK записывает сведения о HTTP-запросе и ответе, которые могут быть полезны при устранении неполадок. Чтобы войти в stdout, добавьте следующее:

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)

По умолчанию журналы регистрируют значения строк запроса URL-адреса, значения некоторых заголовков HTTP-запроса и ответа (включая, в котором содержится ключ), а также Ocp-Apim-Subscription-Keyполезные данные запроса и ответа. Чтобы создать журналы без повторного действия, задайте аргумент logging_enable = True метода при создании ImageAnalysisClientили при вызове analyze клиента.

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

Журналы не создаются только для уровня logging.DEBUG журнала. Не забудьте защитить журналы, не отредактированные, чтобы избежать ущерба безопасности. Дополнительные сведения см. в статье "Настройка ведения журнала в библиотеках Azure для Python"

Необходимые компоненты

В этом руководстве предполагается, что вы выполнили действия на странице краткого руководства . Это означает следующее:

  • Вы создали ресурс Компьютерное зрение и получили URL-адрес ключа и конечной точки.
  • У вас установлен соответствующий пакет SDK, и у вас есть работающее приложение быстрого запуска . Это краткое руководство можно изменить на основе примеров кода.

Создание и проверка подлинности клиента

Для проверки подлинности с помощью службы "Анализ изображений" требуется URL-адрес Компьютерное зрение ключа и конечной точки. В этом руководстве предполагается, что вы определили переменные VISION_KEY среды и VISION_ENDPOINT с помощью ключа и конечной точки.

Внимание

Если вы используете ключ API, сохраните его в другом месте, например в Azure Key Vault. Не включайте ключ API непосредственно в код и никогда не публикуйте его.

Дополнительные сведения о безопасности служб ИИ см. в статье "Проверка подлинности запросов к службам ИИ Azure".

Начните с создания объекта ImageAnalysisClient . Например:

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

Выбор изображения для анализа

Вы можете выбрать изображение, предоставив общедоступный URL-адрес изображения или считывая данные изображения в входной буфер пакета SDK. См . требования к изображениям для поддерживаемых форматов изображений.

URL-адрес изображения

imageUrl Создайте строку для хранения общедоступного URL-адреса изображения, который требуется проанализировать.

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

Буфер изображения

Кроме того, можно передать изображение в качестве буфера памяти с помощью объекта BinaryData . Например, чтение из локального файла образа, который требуется проанализировать.

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

Выбор визуальных компонентов

API Analysis 4.0 предоставляет доступ ко всем функциям анализа изображений службы. Выберите, какие операции следует выполнять в зависимости от вашего сценария. Общие сведения о каждой функции см. в обзоре. Пример в этом разделе добавляет все доступные визуальные функции, но для практического использования, скорее всего, потребуется меньше.

Внимание

Подписи визуальных функций и DenseCaptions поддерживаются только в определенных регионах Azure. См . сведения о доступности региона.

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

Выбор параметров анализа

Используйте объект ImageAnalysisOptions, чтобы указать различные параметры вызова API анализа.

  • Язык: можно указать язык возвращаемых данных. Язык необязателен, при этом по умолчанию используется английский язык. Ознакомьтесь со списком поддерживаемых языковых кодов и визуальными функциями, поддерживаемыми для каждого языка.
  • Заголовки с гендерной нейтральной позицией: если вы извлекаете подписи или плотные подписи (используя VisualFeatures.CAPTION или VisualFeatures.DENSE_CAPTIONS), вы можете попросить заголовок с гендерной нейтральной стороны. Заголовки с гендерной нейтральной стороны являются необязательными, при этом по умолчанию по умолчанию используются заголовки с полом. Например, на английском языке при выборе заголовков с гендерной нейтральной точки зрения термины, такие как женщина или мужчина, заменяются человеком, а мальчик или девушка заменяются ребенком.
  • Соотношение аспектов обрезки: пропорции вычисляются путем деления целевой ширины обрезки на высоту. Поддерживаемые значения : от 0,75 до 1,8 (включительно). Установка этого свойства имеет значение только при выборе VisualFeatures.SMART_CROPS в составе списка визуальных компонентов. Если выбрать VisualFeatures.SMART_CROPS , но не указывать пропорции, служба возвращает одно предложение обрезки с пропорциями, которые он видит. В этом случае пропорция составляет от 0,5 до 2,0 (включительно).
// 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));

Вызов метода analyzeFromUrl

В этом разделе показано, как выполнить вызов анализа к службе.

Вызовите метод analysisFromUrl в объекте ImageAnalysisClient, как показано здесь. Вызов синхронный и будет блокироваться до тех пор, пока служба не вернет результаты или произошла ошибка. Кроме того, можно использовать объект ImageAnalysisAsyncClient и вызвать его метод analysisFromUrl , который не блокируется.

Чтобы проанализировать буфер изображения вместо URL-адреса, вызовите вместо него метод анализа и передайте его в imageData качестве первого аргумента.

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

Получение результатов из службы

В следующем коде показано, как проанализировать результаты из операций анализаFromUrl и анализа .

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

Устранение неполадок

Исключения

Методы analyze вызывают httpResponseException , когда служба отвечает с кодом состояния HTTP без успеха. getResponse().getStatusCode() Исключение содержит код состояния ответа HTTP. getMessage() Исключение содержит подробное сообщение, позволяющее диагностировать проблему:

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

Например, если указать неправильный ключ проверки подлинности:

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."}}"

Или если вы предоставляете изображение в формате, который не распознает:

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."}}}"

Включение ведения журнала HTTP-запросов и ответов

Просмотр HTTP-запроса, отправленного или ответа, полученного через проводную службу анализа изображений, может оказаться полезным при устранении неполадок. Клиентская библиотека анализа изображений поддерживает встроенную платформу ведения журнала консоли для временных целей отладки. Он также поддерживает более расширенное ведение журнала с помощью интерфейса SLF4J . Подробные сведения см. в статье "Использование ведения журнала в пакете SDK Azure для Java".

В следующих разделах рассматривается включение ведения журнала консоли с помощью встроенной платформы.

Задав переменные среды

Вы можете включить ведение журнала http-запроса и ответа для всего приложения, задав следующие две переменные среды. Это изменение влияет на каждый клиент Azure, поддерживающий ведение журнала HTTP-запроса и ответа.

  • Задайте для переменной AZURE_LOG_LEVEL среды значение debug
  • Задайте для переменной AZURE_HTTP_LOG_DETAIL_LEVEL среды одно из следующих значений:
Значение Уровень ведения журнала
none Ведение журнала HTTP-запросов и ответов отключено
basic Регистрирует только URL-адреса, методы HTTP и время завершения запроса.
headers Регистрирует все в BASIC, а также все заголовки запросов и ответов.
body Записывает все данные в BASIC, а также весь текст запроса и ответа.
body_and_headers Записывает все данные в заголовки и текст.

Задание httpLogOptions

Включение ведения журнала в консоли HTTP-запроса и ответа для одного клиента

  • Задайте для переменной AZURE_LOG_LEVEL среды значение debug
  • Добавьте вызов httpLogOptions при создании:ImageAnalysisClient
ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
    .buildClient();

Перечисление HttpLogDetailLevel определяет поддерживаемые уровни ведения журнала.

По умолчанию при ведении журнала некоторые значения заголовков HTTP и параметров запроса редактируются. Это можно переопределить по умолчанию, указав, какие заголовки и параметры запроса безопасно регистрировать:

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

Например, чтобы получить полный неотредактируемый журнал HTTP-запроса, примените следующее:

    .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"))

Добавьте дополнительные сведения в приведенное выше значение, чтобы получить неотредактируемый HTTP-ответ. При совместном использовании неотредактированного журнала убедитесь, что он не содержит секреты, такие как ключ подписки.

Необходимые компоненты

В этом руководстве предполагается, что вы выполнили действия, описанные в кратком руководстве. Это означает следующее:

  • Вы создали ресурс Компьютерное зрение и получили URL-адрес ключа и конечной точки.
  • У вас установлен соответствующий пакет SDK, и у вас есть работающее приложение быстрого запуска . Это краткое руководство можно изменить на основе примеров кода.

Создание и проверка подлинности клиента

Для проверки подлинности в службе "Анализ изображений" требуется URL-адрес Компьютерное зрение ключа и конечной точки. В этом руководстве предполагается, что вы определили переменные VISION_KEY среды и VISION_ENDPOINT с помощью ключа и конечной точки.

Внимание

Если вы используете ключ API, сохраните его в другом месте, например в Azure Key Vault. Не включайте ключ API непосредственно в код и никогда не публикуйте его.

Дополнительные сведения о безопасности служб ИИ см. в статье "Проверка подлинности запросов к службам ИИ Azure".

Начните с создания объекта ImageAnalysisClient . Например:

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

Выбор изображения для анализа

Вы можете выбрать изображение, предоставив общедоступный URL-адрес изображения или считывая данные изображения в входной буфер пакета SDK. См . требования к изображениям для поддерживаемых форматов изображений.

URL-адрес изображения

Вы можете использовать следующий пример URL-адреса изображения.

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

Буфер изображения

Кроме того, можно передать изображение в виде массива данных. Например, чтение из локального файла образа, который требуется проанализировать.

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

Выбор визуальных компонентов

API Analysis 4.0 предоставляет доступ ко всем функциям анализа изображений службы. Выберите, какие операции следует выполнять в зависимости от вашего сценария. Общие сведения о каждой функции см. в разделе "Обзор ". Пример в этом разделе добавляет все доступные визуальные функции, но для практического использования, скорее всего, потребуется меньше.

Внимание

Подписи визуальных функций и DenseCaptions поддерживаются только в определенных регионах Azure. См. раздел .

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

Вызов API анализа с параметрами

Следующий код вызывает API анализа изображений с выбранными выше функциями и другими параметрами, определенными далее. Чтобы проанализировать буфер изображения вместо URL-адреса, замените imageURL вызов метода на 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'
});

Выбор пропорций интеллектуальной обрезки

Пропорции вычисляются путем деления целевой ширины обрезки на высоту. Поддерживаемые значения : от 0,75 до 1,8 (включительно). Установка этого свойства относится только к выбору VisualFeatures.SmartCrops в качестве части списка визуальных функций. Если выбрать VisualFeatures.SmartCrops , но не указывать пропорции, служба возвращает одно предложение обрезки с пропорциями, которые он видит. В этом случае пропорция составляет от 0,5 до 2,0 (включительно).

Выбор заголовков с гендерной нейтральной позицией

Если вы извлекаете подписи или плотные подписи (с помощью VisualFeatures.Captions или VisualFeatures.DenseCaptions), вы можете попросить пол нейтральных подписей. Заголовки с гендерной нейтральной стороны являются необязательными, при этом по умолчанию по умолчанию используются заголовки с полом. Например, на английском языке при выборе заголовков с гендерной нейтральной точки зрения термины, такие как женщина или мужчина, заменяются человеком, а мальчик или девушка заменяются ребенком.

Определение языков

Вы можете указать язык возвращаемых данных. Язык необязателен, при этом по умолчанию используется английский язык. Ознакомьтесь со списком поддерживаемых языковых кодов и визуальными функциями, поддерживаемыми для каждого языка.

Получение результатов из службы

В следующем коде показано, как проанализировать результаты различных операций анализа .

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

Устранение неполадок

Ведение журнала

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. Кроме того, ведение журнала можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

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

setLogLevel("info");

Дополнительные инструкции по включению журналов см. в документации по пакету @azure/loger.

Необходимые компоненты

В этом руководстве предполагается, что вы успешно выполнили действия, описанные на странице быстрого запуска . Это означает следующее:

  • Вы создали ресурс Компьютерное зрение и получили URL-адрес ключа и конечной точки.
  • Вы успешно вызвали curl.exe службу (или использовали альтернативное средство). Вызов изменится curl.exe на основе примеров.

Проверка подлинности в службе

Для проверки подлинности в службе "Анализ изображений" требуется URL-адрес Компьютерное зрение ключа и конечной точки.

Внимание

Если вы используете ключ API, сохраните его в другом месте, например в Azure Key Vault. Не включайте ключ API непосредственно в код и никогда не публикуйте его.

Дополнительные сведения о безопасности служб ИИ см. в статье "Проверка подлинности запросов к службам ИИ Azure".

В примере пакета SDK предполагается, что вы определили переменные VISION_KEY среды и VISION_ENDPOINT ключ и конечную точку.

Проверка подлинности выполняется путем добавления заголовка HTTP-запроса Ocp-Apim-Subscription-Key и его настройки в ключ визуального распознавания. Вызов выполняется по URL-адресу, где <endpoint> находится уникальный URL-адрес <endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01конечной точки компьютерного зрения. Строки запроса добавляются на основе параметров анализа.

Выбор изображения для анализа

В коде этого руководства используются удаленные изображения, доступные по URL-адресам. Вы можете использовать другие изображения, чтобы опробовать все возможности функций анализа изображений.

URL-адрес изображения

При анализе удаленного изображения укажите в тексте запроса его URL-адрес в следующем формате: {"url":"https://learn.microsoft.com/azure/cognitive-services/computer-vision/images/windows-kitchen.jpg"}. Тип контента должен бытьapplication/json.

Файл изображения

Для анализа локального изображения поместите его двоичные данные в текст HTTP-запроса. Тип контента должен быть application/octet-stream или multipart/form-data.

Выбор параметров анализа

Выбор визуальных функций при использовании стандартной модели

API Analysis 4.0 предоставляет доступ ко всем функциям анализа изображений службы. Выберите, какие операции следует выполнять в зависимости от вашего сценария. Общие сведения о каждой функции см. в обзоре. Пример в этом разделе добавляет все доступные визуальные функции, но для практического использования, скорее всего, потребуется меньше.

Визуальные функции "Субтитры" и "DenseCaptions" поддерживаются только в определенных регионах Azure: см . сведения о доступности регионов.

Примечание.

REST API использует термины "Умные культуры" и "Интеллектуальные пропорции сельскохозяйственных культур". Пакет SDK использует термины "Предложения обрезки " и "Обрезка пропорций". Они оба относятся к одной и той же операции службы. Аналогичным образом REST API использует термин Read для обнаружения текста на изображении с помощью оптического распознавания символов (OCR), в то время как пакет SDK использует термин Text для той же операции.

Вы можете указать, какие функции вы хотите использовать, задав параметры запроса URL-адреса API Analysis 4.0. Параметр может иметь несколько значений, разделенных запятыми.

Параметр URL-адреса значение Описание
features read Считывает видимый текст на изображении и выводит его в виде структурированных данных JSON.
features caption Описывает содержимое изображения с полным предложением на поддерживаемых языках.
features denseCaptions Создает подробные заголовки для до 10 видных областей изображений.
features smartCrops Находит координаты прямоугольника, которые обрезают изображение до требуемого пропорции, сохраняя интересующую область.
features objects Обнаруживает различные объекты в изображении, включая приблизительное расположение. Аргумент Objects доступен только на английском языке.
features tags Теги изображения с подробным списком слов, связанных с содержимым изображения.
features people Обнаруживает людей, отображаемых на изображениях, включая приблизительные расположения.

Заполненный URL-адрес будет выглядеть примерно так:

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

Задание имени модели при использовании пользовательской модели

Вы также можете выполнять анализ изображений с помощью пользовательской обученной модели. Сведения о создании и обучении модели см. в статье "Создание пользовательской модели анализа изображений". Когда модель обучена, все, что вам нужно, — это имя модели. Если вы используете пользовательскую модель, вам не нужно указывать визуальные функции.

Чтобы использовать пользовательскую модель, не используйте параметр запроса функций. Вместо этого задайте model-name для параметра имя модели, как показано здесь. Замените MyCustomModelName имя пользовательской модели.

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

Определение языков

Вы можете указать язык возвращаемых данных. Язык необязателен, при этом по умолчанию используется английский язык. Ознакомьтесь со списком поддерживаемых языковых кодов и визуальными функциями, поддерживаемыми для каждого языка.

Параметр языка применяется только при использовании стандартной модели.

Следующий параметр URL-запроса определяет язык. Значение по умолчанию — en.

Параметр URL-адреса значение Описание
language en Английский
language es Испанский
language ja Японский
language pt Португальский
language zh Упрощенный китайский

Заполненный URL-адрес будет выглядеть примерно так:

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

Выбор заголовков с гендерной нейтральной позицией

Если вы извлекаете подписи или плотные подписи, вы можете попросить пол нейтральных подписей. Заголовки с гендерной нейтральной стороны являются необязательными, при этом по умолчанию по умолчанию используются заголовки с полом. Например, на английском языке при выборе заголовков с гендерной нейтральной точки зрения термины, такие как женщина или мужчина, заменяются человеком, а мальчик или девушка заменяются ребенком.

Параметр заголовка с гендерной нейтральной позицией применяется только при использовании стандартной модели.

Добавьте необязательную строку gender-neutral-caption запроса со значениями true или false (по умолчанию).

Заполненный URL-адрес будет выглядеть примерно так:

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

Выбор пропорций интеллектуальной обрезки

Пропорции вычисляются путем деления целевой ширины обрезки на высоту. Поддерживаемые значения : от 0,75 до 1,8 (включительно). Установка этого свойства относится только к выбору VisualFeatures.SmartCrops в качестве части списка визуальных функций. Если выбрать VisualFeatures.SmartCrops , но не указывать пропорции, служба возвращает одно предложение обрезки с пропорциями, которые он видит. В этом случае пропорция составляет от 0,5 до 2,0 (включительно).

Интеллектуальные обрезки пропорций применяются только при использовании стандартной модели.

Добавьте необязательную строку smartcrops-aspect-ratiosзапроса с одним или несколькими пропорциями, разделенными запятой.

Заполненный URL-адрес будет выглядеть примерно так:

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

Получение результатов из службы

Получение результатов с помощью стандартной модели

В этом разделе показано, как выполнить вызов анализа к службе с помощью стандартной модели и получить результаты.

Служба возвращает ответ HTTP 200, текст которого содержит запрошенные данные в формате строки JSON. Ниже приведен пример ответа в формате 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
        }
      ]
    }
  }

Коды ошибок

При ошибке ответ службы анализа изображений содержит полезные данные JSON, содержащие код ошибки и сообщение об ошибке. Он также может содержать другие сведения в виде кода и сообщения внутренней ошибки. Например:

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

Ниже приведен список распространенных ошибок и их причин. Элементы списка представлены в следующем формате:

  • Код ответа HTTP
    • Код ошибки и сообщение в ответе JSON
      • [Необязательно] Код внутренней ошибки и сообщение в ответе JSON

Список распространенных ошибок:

  • 400 Bad Request
    • InvalidRequest - Image URL is badly formatted or not accessible. Убедитесь, что URL-адрес изображения является допустимым и общедоступным.
    • InvalidRequest - The image size is not allowed to be zero or larger than 20971520 bytes. Уменьшите размер изображения, сжимая его и /или изменяя размер, и повторно отправьте запрос.
    • InvalidRequest - The feature 'Caption' is not supported in this region. Эта функция поддерживается только в определенных регионах Azure. Дополнительные сведения о списке поддерживаемых регионов Azure см. в кратком руководстве.
    • InvalidRequest - The provided image content type ... is not supported. Тип контента заголовка HTTP в запросе не является допустимым типом:
      • Для URL-адреса изображения должен быть тип контентаapplication/json
      • Для данных двоичного изображения должен быть application/octet-stream или тип контента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. См. раздел "Требования к изображениям " для поддерживаемых форматов изображений.
    • InvalidRequest - Analyze query is invalid
      • NotSupportedVisualFeature - Specified feature type is not valid. Убедитесь, что строка запроса функций имеет допустимое значение.
      • NotSupportedLanguage - The input language is not supported. Убедитесь, что строка запроса языка имеет допустимое значение для выбранной визуальной функции на основе следующей таблицы.
      • 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. Служба не могла найти пользовательскую модель на основе имени, предоставленного model-name строкой запроса.

Следующие шаги