Volání rozhraní API pro analýzu obrázků 4.0

Požadavky

Tato příručka předpokládá, že jste postupovali podle kroků uvedených na stránce rychlého startu. To znamená:

• Vytvořili jste prostředek Počítačové zpracování obrazu a získali jste adresu URL klíče a koncového bodu.
• Máte nainstalovaný příslušný balíček SDK a máte spuštěnou aplikaci pro rychlý start . Tuto aplikaci pro rychlý start můžete upravit na základě příkladů kódu.

Vytvoření a ověření klienta

K ověření ve službě Image Analysis Service potřebujete Počítačové zpracování obrazu klíč a adresu URL koncového bodu. V této příručce se předpokládá, že jste definovali proměnné VISION_KEY prostředí a VISION_ENDPOINT klíč a koncový bod.

Začněte vytvořením objektu ImageAnalysisClient . Příklad:

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

Výběr obrázku k analýze

Obrázek můžete vybrat tak, že poskytnete veřejně přístupnou adresu URL obrázku nebo předáte binární data sadě SDK. Viz požadavky na image pro podporované formáty obrázků.

Adresa URL obrázku

Vytvořte objekt URI pro obrázek, který chcete analyzovat.

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

Vyrovnávací paměť obrázku

Případně můžete data obrázku předat sadě SDK prostřednictvím objektu BinaryData . Můžete například číst z místního souboru obrázku, který chcete analyzovat.

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

Výběr vizuálních funkcí

Rozhraní API analysis 4.0 poskytuje přístup ke všem funkcím analýzy obrázků služby. Vyberte, které operace se mají provést na základě vašeho vlastního případu použití. V přehledu najdete popis jednotlivých funkcí. Příklad v této části přidá všechny dostupné vizuální funkce, ale pro praktické použití pravděpodobně potřebujete méně.

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

Výběr možností analýzy

Pomocí objektu ImageAnalysisOptions můžete určit různé možnosti volání rozhraní API pro analýzu obrázků.

• Jazyk: Můžete zadat jazyk vrácených dat. Jazyk je volitelný a výchozí angličtina. Seznam podporovaných jazykových kódů a podporovaných vizuálních funkcí pro jednotlivé jazyky najdete v části Podpora jazyků.
• Genderově neutrální titulky: Pokud extrahujete titulky nebo zhuštěné titulky (používáte VisualFeatures.Caption nebo VisualFeatures.DenseCaptions), můžete požádat o genderově neutrální titulky. Genderově neutrální titulky jsou volitelné s výchozími titulky s pohlavím. Například v angličtině, když vyberete genderově neutrální titulky, termíny jako žena nebo muž se nahradí osobou a chlapec nebo dívka se nahradí dítětem.
• Poměr stran oříznutí: Poměr stran se vypočítá tak, že cílovou šířku oříznutí vydělí výškou. Podporované hodnoty jsou od 0,75 do 1,8 (včetně). Nastavení této vlastnosti je relevantní pouze v případě, že bylo vybráno VisualFeatures.SmartCrops jako součást seznamu funkcí vizuálu. Pokud vyberete VisualFeatures.SmartCrops , ale nezadáte poměr stran, vrátí služba jeden návrh oříznutí s poměrem stran, který uvidí. V tomto případě je poměr stran mezi 0,5 a 2,0 (včetně).

ImageAnalysisOptions options = new ImageAnalysisOptions { 
    GenderNeutralCaption = true,
    Language = "en",
    SmartCropsAspectRatios = new float[] { 0.9F, 1.33F }};

Volání rozhraní API pro analýzu

V této části se dozvíte, jak provést volání analýzy do služby.

Volejte metodu Analyze na objektu ImageAnalysisClient , jak je znázorněno zde. Volání je synchronní a blokuje provádění, dokud služba nevrátí výsledky nebo dojde k chybě. Alternativně můžete volat neblokující metodu AnalyzeAsync .

Použijte vstupní objekty vytvořené v předchozích částech. Pokud chcete analyzovat z vyrovnávací paměti obrázku místo adresy URL, nahraďte imageURL ji voláním metody proměnnou imageData .

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

Získání výsledků ze služby

Následující kód ukazuje, jak analyzovat výsledky různých operací Analyzovat.

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

Řešení problému

Ošetření výjimek

Při interakci s analýzou obrázků pomocí sady .NET SDK způsobí vyvolání výjimky jakákoli odpověď ze služby, která nemá 200 stavový kód (úspěch). Pokud se například pokusíte analyzovat obrázek, který není přístupný kvůli poškozené adrese URL, 400 vrátí se stav označující chybný požadavek a vyvolá se odpovídající výjimka.

V následujícím fragmentu kódu se chyby zpracovávají elegantně zachycením výjimky a zobrazením dalších informací o chybě.

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

Další informace o povolení protokolování sady SDK najdete tady.

Požadavky

Tato příručka předpokládá, že jste postupovali podle kroků tohoto rychlého startu. To znamená:

• Vytvořili jste prostředek Počítačové zpracování obrazu a získali jste adresu URL klíče a koncového bodu.
• Nainstalovali jste příslušný balíček sady SDK a máte funkční aplikaci pro rychlý start . Tuto aplikaci pro rychlý start můžete upravit na základě zde uvedených příkladů kódu.

Vytvoření a ověření klienta

K ověření ve službě Image Analysis Service potřebujete Počítačové zpracování obrazu klíč a adresu URL koncového bodu. V této příručce se předpokládá, že jste definovali proměnné VISION_KEY prostředí a VISION_ENDPOINT klíč a koncový bod.

Začněte vytvořením objektu ImageAnalysisClient pomocí jednoho z konstruktorů. Příklad:

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

Výběr obrázku k analýze

Obrázek můžete vybrat tak, že zadáte veřejně přístupnou adresu URL obrázku nebo si přečtete data obrázků do vstupní vyrovnávací paměti sady SDK. Viz požadavky na image pro podporované formáty obrázků.

Adresa URL obrázku

Můžete použít následující adresu URL ukázkového obrázku.

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

Vyrovnávací paměť obrázku

Případně můžete obrázek předat jako objekt bajtů . Můžete například číst z místního souboru obrázku, který chcete analyzovat.

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

Výběr vizuálních funkcí

Rozhraní API analysis 4.0 poskytuje přístup ke všem funkcím analýzy obrázků služby. Vyberte, které operace se mají provést na základě vašeho vlastního případu použití. V přehledu najdete popis jednotlivých funkcí. Příklad v této části přidá všechny dostupné vizuální funkce, ale pro praktické použití pravděpodobně potřebujete méně.

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

Volání metody analyze_from_url s možnostmi

Následující kód volá metodu analyze_from_url na klientovi s funkcemi, které jste vybrali výše, a dalšími možnostmi definovanými níže. Pokud chcete analyzovat z vyrovnávací paměti obrázku místo adresy URL, zavolejte metodu analyzovat místo toho image_data=image_data jako první argument.

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

Výběr inteligentních poměrů stran oříznutí

Poměr stran se vypočítá tak, že vydělí cílovou šířku oříznutí výškou. Podporované hodnoty jsou od 0,75 do 1,8 (včetně). Nastavení této vlastnosti je relevantní pouze v případě, že VisualFeatures.SMART_CROPS byla vybrána jako součást seznamu funkcí vizuálu. Pokud vyberete VisualFeatures.SMART_CROPS , ale nezadáte poměr stran, vrátí služba jeden návrh oříznutí s poměrem stran, který uvidí. V tomto případě je poměr stran mezi 0,5 a 2,0 (včetně).

Výběr genderově neutrálních titulků

Pokud extrahujete titulky nebo zhuštěné titulky (pomocí visualFeatures.CAPTION nebo VisualFeatures.DENSE_CAPTIONS), můžete požádat o genderově neutrální titulky. Genderově neutrální titulky jsou volitelné s výchozími titulky s pohlavím. Například v angličtině, když vyberete genderově neutrální titulky, termíny jako žena nebo muž se nahradí osobou a chlapec nebo dívka se nahradí dítětem.

Určení jazyků

Můžete zadat jazyk vrácených dat. Jazyk je volitelný a výchozí angličtina. Seznam podporovaných jazykových kódů a podporovaných vizuálních funkcí pro jednotlivé jazyky najdete v části Podpora jazyků.

Získání výsledků ze služby

Následující kód ukazuje, jak analyzovat výsledky z analyze_from_url nebo analyzovat operace.

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

Řešení problému

Výjimky

Metody analyze vyvolávají výjimku HttpResponseError pro odpověď stavového kódu HTTP bez úspěchu ze služby. Výjimkou status_code je stavový kód odpovědi HTTP. error.message Výjimka obsahuje podrobnou zprávu, která umožňuje diagnostikovat problém:

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

Pokud například zadáte nesprávný ověřovací klíč:

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.

Nebo když zadáte adresu URL obrázku, která neexistuje nebo není přístupná:

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

Protokolování

Klient používá standardní knihovnu protokolování Pythonu. Sada SDK protokoluje podrobnosti o požadavku HTTP a odpovědi, které můžou být užitečné při řešení potíží. Pokud se chcete přihlásit k stdoutu, přidejte následující:

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)

Ve výchozím nastavení protokoluje redakce hodnot řetězců dotazu ADRESY URL, hodnoty některých hlaviček požadavků HTTP a odpovědí (včetně Ocp-Apim-Subscription-Key, které obsahují klíč) a datových částí požadavku a odpovědi. Pokud chcete vytvořit protokoly bez redakce, nastavte argument logging_enable = True metody při vytváření ImageAnalysisClientnebo při volání analyze klienta.

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

Žádné znovuactované protokoly se generují pouze pro úroveň logging.DEBUG protokolu. Nezapomeňte chránit žádné znovuactované protokoly, abyste se vyhnuli narušení zabezpečení. Další informace najdete v tématu Konfigurace protokolování v knihovnách Azure pro Python.

Požadavky

Tato příručka předpokládá, že jste postupovali na stránce rychlého startu. To znamená:

• Vytvořili jste prostředek Počítačové zpracování obrazu a získali jste adresu URL klíče a koncového bodu.
• Máte nainstalovaný příslušný balíček SDK a máte spuštěnou aplikaci pro rychlý start . Tuto aplikaci pro rychlý start můžete upravit na základě příkladů kódu.

Vytvoření a ověření klienta

K ověření ve službě Image Analysis Service potřebujete Počítačové zpracování obrazu klíč a adresu URL koncového bodu. V této příručce se předpokládá, že jste definovali proměnné VISION_KEY prostředí a VISION_ENDPOINT klíč a koncový bod.

Začněte vytvořením objektu ImageAnalysisClient . Příklad:

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

Výběr obrázku k analýze

Obrázek můžete vybrat tak, že zadáte veřejně přístupnou adresu URL obrázku nebo si přečtete data obrázků do vstupní vyrovnávací paměti sady SDK. Viz požadavky na image pro podporované formáty obrázků.

Adresa URL obrázku

imageUrl Vytvořte řetězec pro uložení veřejně přístupné adresy URL obrázku, který chcete analyzovat.

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

Vyrovnávací paměť obrázku

Alternativně můžete image předat jako vyrovnávací paměť pomocí BinaryData objektu. Můžete například číst z místního souboru obrázku, který chcete analyzovat.

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

Výběr vizuálních funkcí

Rozhraní API analysis 4.0 poskytuje přístup ke všem funkcím analýzy obrázků služby. Vyberte, které operace se mají provést na základě vašeho vlastního případu použití. V přehledu najdete popis jednotlivých funkcí. Příklad v této části přidá všechny dostupné vizuální funkce, ale pro praktické použití pravděpodobně potřebujete méně.

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

Výběr možností analýzy

Pomocí objektu ImageAnalysisOptions určete různé možnosti volání rozhraní API Pro analýzu.

• Jazyk: Můžete zadat jazyk vrácených dat. Jazyk je volitelný a výchozí angličtina. Seznam podporovaných jazykových kódů a podporovaných vizuálních funkcí pro jednotlivé jazyky najdete v části Podpora jazyků.
• Genderově neutrální titulky: Pokud extrahujete titulky nebo zhuštěné titulky (používáte VisualFeatures.CAPTION nebo VisualFeatures.DENSE_CAPTIONS), můžete požádat o genderově neutrální titulky. Genderově neutrální titulky jsou volitelné s výchozími titulky s pohlavím. Například v angličtině, když vyberete genderově neutrální titulky, termíny jako žena nebo muž se nahradí osobou a chlapec nebo dívka se nahradí dítětem.
• Poměr stran oříznutí: Poměr stran se vypočítá tak, že cílovou šířku oříznutí vydělí výškou. Podporované hodnoty jsou od 0,75 do 1,8 (včetně). Nastavení této vlastnosti je relevantní pouze v případě, že VisualFeatures.SMART_CROPS byla vybrána jako součást seznamu funkcí vizuálu. Pokud vyberete VisualFeatures.SMART_CROPS , ale nezadáte poměr stran, vrátí služba jeden návrh oříznutí s poměrem stran, který uvidí. V tomto případě je poměr stran mezi 0,5 a 2,0 (včetně).

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

Volání metody analyzeFromUrl

V této části se dozvíte, jak provést volání analýzy do služby.

Volání metody analyzeFromUrl u objektu ImageAnalysisClient, jak je znázorněno zde. Volání je synchronní a bude blokovat, dokud služba nevrátí výsledky nebo dojde k chybě. Alternativně můžete místo toho použít objekt ImageAnalysisAsyncClient a volat jeho metodu analyzeFromUrl , která neblokuje.

Pokud chcete analyzovat z vyrovnávací paměti obrázku místo adresy URL, zavolejte místo toho metodu analyze a předejte imageData ji jako první argument.

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

Získání výsledků ze služby

Následující kód ukazuje, jak analyzovat výsledky z analyzeFromUrl a analyzovat operace.

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

Řešení problému

Výjimky

Metody analyze vyvolat HttpResponseException , když služba odpoví stavovým kódem HTTP bez úspěchu. getResponse().getStatusCode() Výjimka obsahuje stavový kód odpovědi HTTP. getMessage() Výjimka obsahuje podrobnou zprávu, která umožňuje diagnostikovat problém:

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

Pokud například zadáte nesprávný ověřovací klíč:

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

Nebo když zadáte obrázek ve formátu, který se nerozpozná:

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

Povolení protokolování požadavků a odpovědí HTTP

Při řešení potíží může být užitečné zkontrolovat odeslaný požadavek HTTP nebo odpověď přijatá přes wire do služby Analýza obrázků. Klientská knihovna Pro analýzu obrázků podporuje integrovanou architekturu protokolování konzoly pro dočasné účely ladění. Podporuje také pokročilejší protokolování pomocí rozhraní SLF4J . Podrobné informace najdete v tématu Použití protokolování v sadě Azure SDK pro Javu.

Následující části popisují povolení protokolování konzoly pomocí integrované architektury.

Nastavením proměnných prostředí

Protokolování konzoly požadavku HTTP a odpovědi pro celou aplikaci můžete povolit nastavením následujících dvou proměnných prostředí. Tato změna má vliv na každého klienta Azure, který podporuje protokolování požadavků HTTP a odpovědí.

• Nastavení proměnné AZURE_LOG_LEVEL prostředí na debug
• Nastavte proměnnou AZURE_HTTP_LOG_DETAIL_LEVEL prostředí na jednu z následujících hodnot:

Nastavením httpLogOptions

Povolení protokolování konzoly požadavku HTTP a odpovědi pro jednoho klienta

• Nastavení proměnné AZURE_LOG_LEVEL prostředí na debug
• Přidání volání při httpLogOptions vytváření ImageAnalysisClient:

ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
    .buildClient();

Enum HttpLogDetailLevel definuje podporované úrovně protokolování.

Ve výchozím nastavení jsou při protokolování upraveny určité hodnoty hlavičky HTTP a parametru dotazu. Toto výchozí nastavení je možné přepsat zadáním hlaviček a parametrů dotazu, které se dají bezpečně protokolovat:

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

Pokud například chcete získat úplný nereaktovaný protokol požadavku HTTP, použijte následující:

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

Pokud chcete získat nereagovanou odpověď HTTP, přidejte do výše uvedeného postupu další informace. Když sdílíte neupravený protokol, ujistěte se, že neobsahuje tajné kódy, jako je klíč předplatného.

Požadavky

Tato příručka předpokládá, že jste postupovali podle kroků uvedených v rychlém startu. To znamená:

• Vytvořili jste prostředek Počítačové zpracování obrazu a získali jste adresu URL klíče a koncového bodu.
• Máte nainstalovaný příslušný balíček SDK a máte spuštěnou aplikaci pro rychlý start . Tuto aplikaci pro rychlý start můžete upravit na základě zde uvedených příkladů kódu.

Vytvoření a ověření klienta

K ověření ve službě Image Analysis Service potřebujete Počítačové zpracování obrazu klíč a adresu URL koncového bodu. V této příručce se předpokládá, že jste definovali proměnné VISION_KEY prostředí a VISION_ENDPOINT klíč a koncový bod.

Začněte vytvořením objektu ImageAnalysisClient . Příklad:

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

Výběr obrázku k analýze

Obrázek můžete vybrat tak, že zadáte veřejně přístupnou adresu URL obrázku nebo si přečtete data obrázků do vstupní vyrovnávací paměti sady SDK. Viz požadavky na image pro podporované formáty obrázků.

Adresa URL obrázku

Můžete použít následující adresu URL ukázkového obrázku.

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

Vyrovnávací paměť obrázku

Alternativně můžete obrázek předat jako datové pole. Můžete například číst z místního souboru obrázku, který chcete analyzovat.

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

Výběr vizuálních funkcí

Rozhraní API analysis 4.0 poskytuje přístup ke všem funkcím analýzy obrázků služby. Vyberte, které operace se mají provést na základě vašeho vlastního případu použití. Popis jednotlivých funkcí najdete v přehledu. Příklad v této části přidá všechny dostupné vizuální funkce, ale pro praktické použití pravděpodobně potřebujete méně.

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

Volání rozhraní API pro analýzu s možnostmi

Následující kód volá rozhraní API pro analýzu obrázků s funkcemi, které jste vybrali výše, a dalšími možnostmi definovanými dále. Chcete-li analyzovat z vyrovnávací paměti obrázku místo adresy URL, nahraďte imageURL volání metody voláním 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'
});

Výběr inteligentních poměrů stran oříznutí

Poměr stran se vypočítá tak, že vydělí cílovou šířku oříznutí výškou. Podporované hodnoty jsou od 0,75 do 1,8 (včetně). Nastavení této vlastnosti je relevantní pouze v případě, že bylo vybráno VisualFeatures.SmartCrops jako součást seznamu funkcí vizuálu. Pokud vyberete VisualFeatures.SmartCrops , ale nezadáte poměr stran, vrátí služba jeden návrh oříznutí s poměrem stran, který uvidí. V tomto případě je poměr stran mezi 0,5 a 2,0 (včetně).

Výběr genderově neutrálních titulků

Pokud extrahujete titulky nebo zhuštěné titulky (pomocí visualFeatures.Caption nebo VisualFeatures.DenseCaptions), můžete požádat o genderově neutrální titulky. Genderově neutrální titulky jsou volitelné s výchozími titulky s pohlavím. Například v angličtině, když vyberete genderově neutrální titulky, termíny jako žena nebo muž se nahradí osobou a chlapec nebo dívka se nahradí dítětem.

Určení jazyků

Můžete zadat jazyk vrácených dat. Jazyk je volitelný a výchozí angličtina. Seznam podporovaných jazykových kódů a podporovaných vizuálních funkcí pro jednotlivé jazyky najdete v části Podpora jazyků.

Získání výsledků ze služby

Následující kód ukazuje, jak analyzovat výsledky různých operací analýzy .

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

Řešení problému

Protokolování

Povolení protokolování může pomoct odhalit užitečné informace o chybách. Pokud chcete zobrazit protokol požadavků HTTP a odpovědí, nastavte proměnnou AZURE_LOG_LEVEL prostředí na infohodnotu . Případně můžete protokolování povolit za běhu voláním setLogLevel příkazu @azure/logger:

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

setLogLevel("info");

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k @azure/protokolovacímu balíčku.

Požadavky

Tato příručka předpokládá, že jste úspěšně postupovali podle kroků uvedených na stránce rychlého startu. To znamená:

• Vytvořili jste prostředek Počítačové zpracování obrazu a získali jste adresu URL klíče a koncového bodu.
• Úspěšně jste provedli curl.exe volání služby (nebo jste použili alternativní nástroj). Volání upravíte curl.exe na základě zde uvedených příkladů.

Ověření vůči službě

K ověření ve službě Image Analysis Service potřebujete Počítačové zpracování obrazu klíč a adresu URL koncového bodu.

Příklad sady SDK předpokládá, že jste definovali proměnné VISION_KEY prostředí a VISION_ENDPOINT klíč a koncový bod.

Ověřování se provádí přidáním hlavičky požadavku HTTP Ocp-Apim-Subscription-Key a jeho nastavením na klíč zpracování obrazu. Volání se provede na adresu URL <endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01, kde <endpoint> je vaše jedinečná adresa URL koncového bodu počítačového zpracování obrazu. Řetězce dotazů přidáte na základě možností analýzy.

Výběr obrázku k analýze

Kód v této příručce používá vzdálené obrázky, na které odkazuje adresa URL. Možná si budete chtít vyzkoušet různé obrázky, abyste viděli všechny funkce analýzy obrázků.

Adresa URL obrázku

Při analýze vzdáleného obrázku zadáte adresu URL obrázku tak, že naformátujete text požadavku takto: {"url":"https://video2.skills-academy.com/azure/cognitive-services/computer-vision/images/windows-kitchen.jpg"}. Typ obsahu by měl být application/json.

Image file

Pokud chcete analyzovat místní obrázek, vložte data binárního obrázku do textu požadavku HTTP. Typ obsahu by měl být application/octet-stream nebo multipart/form-data.

Výběr možností analýzy

Výběr vizuálních funkcí při použití standardního modelu

Rozhraní API analysis 4.0 poskytuje přístup ke všem funkcím analýzy obrázků služby. Vyberte, které operace se mají provést na základě vašeho vlastního případu použití. V přehledu najdete popis jednotlivých funkcí. Příklad v této části přidá všechny dostupné vizuální funkce, ale pro praktické použití pravděpodobně potřebujete méně.

Vizuální funkce Captions a DenseCaptions se podporují jenom v určitých oblastech Azure: viz Dostupnost oblastí.

Můžete určit, které funkce chcete použít, nastavením parametrů dotazu adresy URL rozhraní API analysis 4.0. Parametr může mít více hodnot oddělených čárkami.

Vyplněná adresa URL může vypadat takto:

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

Nastavení názvu modelu při použití vlastního modelu

Analýzu obrázků můžete provést také pomocí vlastního natrénovaného modelu. Pokud chcete vytvořit a vytrénovat model, přečtěte si téma Vytvoření vlastního modelu analýzy obrázků. Po vytrénování modelu stačí jen název modelu. Pokud používáte vlastní model, nemusíte zadávat vizuální funkce.

Pokud chcete použít vlastní model, nepoužívejte parametr dotazu funkcí. Místo toho nastavte model-name parametr na název modelu, jak je znázorněno zde. Nahraďte MyCustomModelName vlastním názvem modelu.

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

Určení jazyků

Můžete zadat jazyk vrácených dat. Jazyk je volitelný a výchozí angličtina. Seznam podporovaných jazykových kódů a podporovaných vizuálních funkcí pro jednotlivé jazyky najdete v části Podpora jazyků.

Jazyková možnost platí jenom v případech, kdy používáte standardní model.

Následující parametr dotazu adresy URL určuje jazyk. Výchozí hodnota je en.

Vyplněná adresa URL může vypadat takto:

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

Výběr genderově neutrálních titulků

Pokud extrahujete titulky nebo zhuštěné titulky, můžete požádat o genderově neutrální titulky. Genderově neutrální titulky jsou volitelné s výchozími titulky s pohlavím. Například v angličtině, když vyberete genderově neutrální titulky, termíny jako žena nebo muž se nahradí osobou a chlapec nebo dívka se nahradí dítětem.

Možnost genderově neutrálního titulku platí jenom v případech, kdy používáte standardní model.

Přidejte volitelný řetězec gender-neutral-caption dotazu s hodnotami true nebo false (výchozí).

Vyplněná adresa URL může vypadat takto:

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

Výběr inteligentních poměrů stran oříznutí

Poměr stran se vypočítá tak, že vydělí cílovou šířku oříznutí výškou. Podporované hodnoty jsou od 0,75 do 1,8 (včetně). Nastavení této vlastnosti je relevantní pouze v případě, že bylo vybráno VisualFeatures.SmartCrops jako součást seznamu funkcí vizuálu. Pokud vyberete VisualFeatures.SmartCrops , ale nezadáte poměr stran, vrátí služba jeden návrh oříznutí s poměrem stran, který uvidí. V tomto případě je poměr stran mezi 0,5 a 2,0 (včetně).

Poměry stran inteligentního oříznutí platí jenom v případech, kdy používáte standardní model.

Přidejte volitelný řetězec smartcrops-aspect-ratiosdotazu s jedním nebo více poměry stran odděleným čárkou.

Vyplněná adresa URL může vypadat takto:

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

Získání výsledků ze služby

Získání výsledků pomocí standardního modelu

V této části se dozvíte, jak provést volání analýzy do služby pomocí standardního modelu a získat výsledky.

Služba vrátí 200 odpověď HTTP a tělo obsahuje vrácená data ve formě řetězce JSON. Následující text je příkladem odpovědi 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
        }
      ]
    }
  }

Kódy chyb

V případě chyby obsahuje odpověď služby Analýza obrázků dat datOVOU část JSON, která obsahuje kód chyby a chybovou zprávu. Může také obsahovat další podrobnosti ve formě a vnitřní kód chyby a zprávy. Příklad:

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

Následuje seznam běžných chyb a jejich příčin. Položky seznamu jsou uvedeny v následujícím formátu:

• Kód odpovědi HTTP
  • Kód chyby a zpráva v odpovědi JSON
    • [Volitelné] Vnitřní kód chyby a zpráva v odpovědi JSON

Seznam běžných chyb:

• 400 Bad Request
  • InvalidRequest - Image URL is badly formatted or not accessible. Ujistěte se, že adresa URL obrázku je platná a veřejně přístupná.
  • InvalidRequest - The image size is not allowed to be zero or larger than 20971520 bytes. Zmenšete velikost obrázku tím, že ho zkomprimujte nebo zmenšete a znovu odešlete požadavek.
  • InvalidRequest - The feature 'Caption' is not supported in this region. Tato funkce se podporuje jenom v konkrétních oblastech Azure. Seznam podporovaných oblastí Azure najdete v požadavcích pro rychlý start.
  • InvalidRequest - The provided image content type ... is not supported. Typ obsahu hlavičky HTTP v požadavku není povolený typ:
    • Adresa URL obrázku by měla být typu obsahu. application/json
    • Pro data binárního obrázku by měl být application/octet-stream typ obsahu nebomultipart/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. Podporované formáty obrázků najdete v části Požadavky na image.
  • InvalidRequest - Analyze query is invalid
    • NotSupportedVisualFeature - Specified feature type is not valid. Ujistěte se, že řetězec dotazu funkcí má platnou hodnotu.
    • NotSupportedLanguage - The input language is not supported. Ujistěte se, že řetězec dotazu jazyka má platnou hodnotu pro vybranou vizuální funkci na základě následující tabulky.
    • 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. Služba nemohla najít vlastní model založený na názvu zadaném řetězcem model-name dotazu.