Dela via

Anropa API:et för bildanalys 4.0-analys

  • Artikel

Den här artikeln visar hur du anropar API:et för bildanalys 4.0 för att returnera information om en bilds visuella funktioner. Den visar också hur du parsar den returnerade informationen.

Förutsättningar

Den här guiden förutsätter att du har följt stegen som nämns på snabbstartssidan. Detta innebär att:

  • Du har skapat en Visuellt innehåll resurs och fått en nyckel och en slutpunkts-URL.
  • Du har rätt SDK-paket installerat och du har ett snabbstartsprogram som körs. Du kan ändra det här snabbstartsprogrammet baserat på kodexempel här.

Skapa och autentisera klienten

Om du vill autentisera mot tjänsten Bildanalys behöver du en Visuellt innehåll nyckel och slutpunkts-URL. Den här guiden förutsätter att du har definierat miljövariablerna VISION_KEY och VISION_ENDPOINT med din nyckel och slutpunkt.

Viktigt!

Om du använder en API-nyckel lagrar du den på ett säkert sätt någon annanstans, till exempel i Azure Key Vault. Inkludera inte API-nyckeln direkt i koden och publicera den aldrig offentligt.

Mer information om säkerhet för AI-tjänster finns i Autentisera begäranden till Azure AI-tjänster.

Börja med att skapa ett ImageAnalysisClient-objekt . Till exempel:

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älj den bild som ska analyseras

Du kan välja en bild genom att ange en offentligt tillgänglig bild-URL eller genom att skicka binära data till SDK:t. Se Bildkrav för bildformat som stöds.

Bild-URL

Skapa ett URI-objekt för den bild som du vill analysera.

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

Bildbuffert

Du kan också skicka bilddata till SDK via ett BinaryData-objekt . Du kan till exempel läsa från en lokal bildfil som du vill analysera.

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

Välj visuella funktioner

Api:et Analysis 4.0 ger dig åtkomst till alla tjänstens bildanalysfunktioner. Välj vilka åtgärder som ska utföras baserat på ditt eget användningsfall. Se översikten för en beskrivning av varje funktion. Exemplet i det här avsnittet lägger till alla tillgängliga visuella funktioner, men för praktisk användning behöver du förmodligen färre.

Viktigt!

De visuella funktionerna Captions och DenseCaptions stöds endast i vissa Azure-regioner: se Regiontillgänglighet

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

Välj analysalternativ

Använd ett ImageAnalysisOptions-objekt för att ange olika alternativ för API-anropet Analysera bild.

  • Språk: Du kan ange språket för de returnerade data. Språket är valfritt, med standardvärdet engelska. Se Språkstöd för en lista över språkkoder som stöds och vilka visuella funktioner som stöds för varje språk.
  • Könsneutrala bildtexter: Om du extraherar bildtexter eller kompakta bildtexter (med hjälp av VisualFeatures.Caption eller VisualFeatures.DenseCaptions) kan du be om könsneutrala bildtexter. Könsneutrala bildtexter är valfria, där standardvärdet är könsbestämda bildtexter. När du till exempel väljer könsneutrala bildtexter på engelska ersätts termer som kvinna eller man med person och pojke eller flicka ersätts med barn.
  • Beskärningsproportion: Ett proportioner beräknas genom att målgrödbredden divideras med höjden. Värden som stöds är från 0,75 till 1,8 (inklusive). Att ange den här egenskapen är bara relevant när VisualFeatures.SmartCrops valdes som en del av listan över visuella funktioner. Om du väljer VisualFeatures.SmartCrops men inte anger proportioner returnerar tjänsten ett beskärningsförslag med ett proportioner som passar. I det här fallet är proportionerna mellan 0,5 och 2,0 (inklusive).
ImageAnalysisOptions options = new ImageAnalysisOptions { 
    GenderNeutralCaption = true,
    Language = "en",
    SmartCropsAspectRatios = new float[] { 0.9F, 1.33F }};

Anropa ANALYS-API:et

Det här avsnittet visar hur du gör ett analysanrop till tjänsten.

Anropa metoden Analysera på objektet ImageAnalysisClient, som du ser här. Anropet är synkront och blockerar körningen tills tjänsten returnerar resultatet eller ett fel uppstod. Du kan också anropa den icke-blockerande AnalyzeAsync-metoden .

Använd indataobjekten som skapades i avsnitten ovan. Om du vill analysera från en bildbuffert i stället för URL ersätter du imageURL i metodanropet med variabeln imageData .

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

Hämta resultat från tjänsten

Följande kod visar hur du parsar resultatet av de olika analysåtgärderna.

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

Felsökning

Hantering av undantag

När du interagerar med bildanalys med hjälp av .NET SDK resulterar alla svar från tjänsten som inte har statuskoden 200 (lyckades) i ett undantag. Om du till exempel försöker analysera en bild som inte är tillgänglig på grund av en bruten URL returneras en 400 status som anger en felaktig begäran och ett motsvarande undantag genereras.

I följande kodfragment hanteras fel på ett korrekt sätt genom att undantaget fångas upp och ytterligare information om felet visas.

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

Du kan läsa mer om hur du aktiverar SDK-loggning här.

Förutsättningar

Den här guiden förutsätter att du har följt stegen i snabbstarten. Detta innebär att:

Skapa och autentisera klienten

Om du vill autentisera mot tjänsten Bildanalys behöver du en Visuellt innehåll nyckel och slutpunkts-URL. Den här guiden förutsätter att du har definierat miljövariablerna VISION_KEY och VISION_ENDPOINT med din nyckel och slutpunkt.

Viktigt!

Om du använder en API-nyckel lagrar du den på ett säkert sätt någon annanstans, till exempel i Azure Key Vault. Inkludera inte API-nyckeln direkt i koden och publicera den aldrig offentligt.

Mer information om säkerhet för AI-tjänster finns i Autentisera begäranden till Azure AI-tjänster.

Börja med att skapa ett ImageAnalysisClient-objekt med någon av konstruktorerna. Till exempel:

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

Välj den bild som ska analyseras

Du kan välja en bild genom att ange en offentligt tillgänglig bild-URL eller genom att läsa bilddata i SDK:ts indatabuffert. Se Bildkrav för bildformat som stöds.

Bild-URL

Du kan använda följande exempelbild-URL.

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

Bildbuffert

Du kan också skicka in bilden som byteobjekt . Du kan till exempel läsa från en lokal bildfil som du vill analysera.

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

Välj visuella funktioner

Api:et Analysis 4.0 ger dig åtkomst till alla tjänstens bildanalysfunktioner. Välj vilka åtgärder som ska utföras baserat på ditt eget användningsfall. Se översikten för en beskrivning av varje funktion. Exemplet i det här avsnittet lägger till alla tillgängliga visuella funktioner, men för praktisk användning behöver du förmodligen färre.

Viktigt!

De visuella funktionerna Captions och DenseCaptions stöds bara i vissa Azure-regioner. Se Regiontillgänglighet.

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

Anropa metoden analyze_from_url med alternativ

Följande kod anropar metoden analyze_from_url på klienten med de funktioner som du har valt ovan och andra alternativ som definieras nedan. Om du vill analysera från en bildbuffert i stället för URL anropar du metoden analysera i stället, med image_data=image_data som det första argumentet.

# 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älj proportioner för smart beskärning

Ett proportioner beräknas genom att målgrödbredden divideras med höjden. Värden som stöds är från 0,75 till 1,8 (inklusive). Att ange den här egenskapen är bara relevant när VisualFeatures.SMART_CROPS har valts som en del av listan över visuella funktioner. Om du väljer VisualFeatures.SMART_CROPS men inte anger proportioner returnerar tjänsten ett beskärningsförslag med ett proportioner som passar. I det här fallet är proportionerna mellan 0,5 och 2,0 (inklusive).

Välj könsneutrala bildtexter

Om du extraherar bildtexter eller kompakta bildtexter (med VisualFeatures.CAPTION eller VisualFeatures.DENSE_CAPTIONS) kan du be om könsneutrala bildtexter. Könsneutrala bildtexter är valfria, där standardvärdet är könsbestämda bildtexter. När du till exempel väljer könsneutrala bildtexter på engelska ersätts termer som kvinna eller man med person och pojke eller flicka ersätts med barn.

Ange språk

Du kan ange språket för de returnerade data. Språket är valfritt, med standardvärdet engelska. Se Språkstöd för en lista över språkkoder som stöds och vilka visuella funktioner som stöds för varje språk.

Hämta resultat från tjänsten

Följande kod visar hur du parsar resultatet från analyze_from_url eller analyserar åtgärder.

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

Felsökning

Undantag

Metoderna analyze skapar ett HttpResponseError-undantag för ett HTTP-statuskodsvar som inte lyckas från tjänsten. Undantaget är HTTP-svarsstatuskoden status_code . error.message Undantaget innehåller ett detaljerat meddelande som gör att du kan diagnostisera problemet:

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

När du till exempel anger en fel autentiseringsnyckel:

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.

Eller när du anger en bild-URL som inte finns eller inte är tillgänglig:

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

Loggning

Klienten använder standardbiblioteket för Python-loggning. SDK loggar HTTP-begäran och svarsinformation, vilket kan vara användbart vid felsökning. Om du vill logga till stdout lägger du till följande:

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)

Som standard redigerar loggarna värdena för URL-frågesträngar, värdena för vissa HTTP-begärande- och svarshuvuden (inklusive Ocp-Apim-Subscription-Key, som innehåller nyckeln) och nyttolasten för begäran och svar. Om du vill skapa loggar utan redigering anger du metodargumentet logging_enable = True när du skapar ImageAnalysisClienteller när du anropar analyze klienten.

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

Inga redigerade loggar genereras endast för loggnivå logging.DEBUG . Se till att skydda inga redacted loggar för att undvika att äventyra säkerheten. Mer information finns i Konfigurera loggning i Azure-biblioteken för Python

Förutsättningar

Den här guiden förutsätter att du har följt stegen på snabbstartssidan. Detta innebär att:

  • Du har skapat en Visuellt innehåll resurs och fått en nyckel och en slutpunkts-URL.
  • Du har rätt SDK-paket installerat och du har ett snabbstartsprogram som körs. Du kan ändra det här snabbstartsprogrammet baserat på kodexempel här.

Skapa och autentisera klienten

Om du vill autentisera med tjänsten Bildanalys behöver du en Visuellt innehåll nyckel och slutpunkts-URL. Den här guiden förutsätter att du har definierat miljövariablerna VISION_KEY och VISION_ENDPOINT med din nyckel och slutpunkt.

Viktigt!

Om du använder en API-nyckel lagrar du den på ett säkert sätt någon annanstans, till exempel i Azure Key Vault. Inkludera inte API-nyckeln direkt i koden och publicera den aldrig offentligt.

Mer information om säkerhet för AI-tjänster finns i Autentisera begäranden till Azure AI-tjänster.

Börja med att skapa ett ImageAnalysisClient-objekt . Till exempel:

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älj den bild som ska analyseras

Du kan välja en bild genom att ange en offentligt tillgänglig bild-URL eller genom att läsa bilddata i SDK:ts indatabuffert. Se Bildkrav för bildformat som stöds.

Bild-URL

Skapa en imageUrl sträng för att lagra den offentligt tillgängliga URL:en för den bild som du vill analysera.

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

Bildbuffert

Du kan också skicka bilden som minnesbuffert med hjälp av ett BinaryData-objekt . Du kan till exempel läsa från en lokal bildfil som du vill analysera.

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

Välj visuella funktioner

Api:et Analysis 4.0 ger dig åtkomst till alla tjänstens bildanalysfunktioner. Välj vilka åtgärder som ska utföras baserat på ditt eget användningsfall. Se översikten för en beskrivning av varje funktion. Exemplet i det här avsnittet lägger till alla tillgängliga visuella funktioner, men för praktisk användning behöver du förmodligen färre.

Viktigt!

De visuella funktionerna Captions och DenseCaptions stöds bara i vissa Azure-regioner. Se Regiontillgänglighet.

// 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älj analysalternativ

Använd ett ImageAnalysisOptions-objekt för att ange olika alternativ för anropet Analysera API.

  • Språk: Du kan ange språket för de returnerade data. Språket är valfritt, med standardvärdet engelska. Se Språkstöd för en lista över språkkoder som stöds och vilka visuella funktioner som stöds för varje språk.
  • Könsneutrala bildtexter: Om du extraherar bildtexter eller kompakta bildtexter (med Hjälp av VisualFeatures.CAPTION eller VisualFeatures.DENSE_CAPTIONS) kan du be om könsneutrala bildtexter. Könsneutrala bildtexter är valfria, där standardvärdet är könsbestämda bildtexter. När du till exempel väljer könsneutrala bildtexter på engelska ersätts termer som kvinna eller man med person och pojke eller flicka ersätts med barn.
  • Beskärningsproportion: Ett proportioner beräknas genom att målgrödbredden divideras med höjden. Värden som stöds är från 0,75 till 1,8 (inklusive). Att ange den här egenskapen är bara relevant när VisualFeatures.SMART_CROPS har valts som en del av listan över visuella funktioner. Om du väljer VisualFeatures.SMART_CROPS men inte anger proportioner returnerar tjänsten ett beskärningsförslag med ett proportioner som passar. I det här fallet är proportionerna mellan 0,5 och 2,0 (inklusive).
// 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));

Anropa metoden analyzeFromUrl

Det här avsnittet visar hur du gör ett analysanrop till tjänsten.

Anropa metoden analyzeFromUrl på objektet ImageAnalysisClient, som du ser här. Anropet är synkront och blockeras tills tjänsten returnerar resultatet eller ett fel uppstod. Du kan också använda ett ImageAnalysisAsyncClient-objekt i stället och anropa dess analyzeFromUrl-metod , som inte blockerar.

Om du vill analysera från en bildbuffert i stället för URL anropar du analysmetoden i stället och skickar in imageData som det första argumentet.

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

Hämta resultat från tjänsten

Följande kod visar hur du parsar resultaten från analysernaFromUrl och analyserar åtgärder.

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

Felsökning

Undantag

Metoderna analyze genererar HttpResponseException när tjänsten svarar med en HTTP-statuskod som inte lyckas. Undantaget innehåller HTTP-svarsstatuskoden getResponse().getStatusCode() . getMessage() Undantaget innehåller ett detaljerat meddelande som gör att du kan diagnostisera problemet:

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

När du till exempel anger en fel autentiseringsnyckel:

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

Eller när du anger en bild i ett format som inte känns igen:

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

Aktivera HTTP-begäran/svarsloggning

Det kan vara användbart att granska http-begäran som skickats eller fått svar via kabeln till tjänsten Bildanalys i felsökningen. Klientbiblioteket för bildanalys stöder ett inbyggt konsolloggningsramverk för tillfällig felsökning. Den stöder också mer avancerad loggning med hjälp av SLF4J-gränssnittet . Detaljerad information finns i Använda loggning i Azure SDK för Java.

I avsnitten nedan beskrivs aktivering av konsolloggning med det inbyggda ramverket.

Genom att ange miljövariabler

Du kan aktivera konsolloggning av HTTP-begäran och -svar för hela programmet genom att ange följande två miljövariabler. Den här ändringen påverkar varje Azure-klient som stöder loggning av HTTP-begäran och -svar.

  • Ange miljövariabel till AZURE_LOG_LEVELdebug
  • Ange miljövariabeln AZURE_HTTP_LOG_DETAIL_LEVEL till något av följande värden:
Värde Loggningsnivå
none HTTP-begäran/svarsloggning är inaktiverad
basic Loggar endast URL:er, HTTP-metoder och tid för att slutföra begäran.
headers Loggar allt i BASIC, plus alla begärande- och svarshuvuden.
body Loggar allt i BASIC, plus alla begärande- och svarstexter.
body_and_headers Loggar allt i HEADERS och BODY.

Genom att ange httpLogOptions

Aktivera konsolloggning av HTTP-begäran och -svar för en enskild klient

  • Ange miljövariabel till AZURE_LOG_LEVELdebug
  • Lägg till ett anrop till httpLogOptions när du ImageAnalysisClientskapar :
ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
    .buildClient();

Uppräkningen HttpLogDetailLevel definierar de loggningsnivåer som stöds.

Som standard redigeras vissa HTTP-huvud- och frågeparametervärden vid loggning. Det går att åsidosätta den här standardinställningen genom att ange vilka rubriker och frågeparametrar som är säkra att logga:

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

Om du till exempel vill hämta en fullständig oreagerad logg för HTTP-begäran använder du följande:

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

Lägg till mer i ovanstående för att få ett http-svar som inte redigerats. När du delar en logg som inte har redigerats kontrollerar du att den inte innehåller hemligheter som din prenumerationsnyckel.

Förutsättningar

Den här guiden förutsätter att du har följt de steg som nämns i snabbstarten. Detta innebär att:

  • Du har skapat en Visuellt innehåll resurs och fått en nyckel och en slutpunkts-URL.
  • Du har rätt SDK-paket installerat och du har ett snabbstartsprogram som körs. Du kan ändra det här snabbstartsprogrammet baserat på kodexemplen här.

Skapa och autentisera klienten

Om du vill autentisera mot tjänsten Bildanalys behöver du en Visuellt innehåll nyckel och slutpunkts-URL. Den här guiden förutsätter att du har definierat miljövariablerna VISION_KEY och VISION_ENDPOINT med din nyckel och slutpunkt.

Viktigt!

Om du använder en API-nyckel lagrar du den på ett säkert sätt någon annanstans, till exempel i Azure Key Vault. Inkludera inte API-nyckeln direkt i koden och publicera den aldrig offentligt.

Mer information om säkerhet för AI-tjänster finns i Autentisera begäranden till Azure AI-tjänster.

Börja med att skapa ett ImageAnalysisClient-objekt . Till exempel:

// 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älj den bild som ska analyseras

Du kan välja en bild genom att ange en offentligt tillgänglig bild-URL eller genom att läsa bilddata i SDK:ts indatabuffert. Se Bildkrav för bildformat som stöds.

Bild-URL

Du kan använda följande exempelbild-URL.

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

Bildbuffert

Du kan också skicka in bilden som en datamatris. Du kan till exempel läsa från en lokal bildfil som du vill analysera.

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

Välj visuella funktioner

Api:et Analysis 4.0 ger dig åtkomst till alla tjänstens bildanalysfunktioner. Välj vilka åtgärder som ska utföras baserat på ditt eget användningsfall. Se Översikt för en beskrivning av varje funktion. Exemplet i det här avsnittet lägger till alla tillgängliga visuella funktioner, men för praktisk användning behöver du förmodligen färre.

Viktigt!

De visuella funktionerna Captions och DenseCaptions stöds bara i vissa Azure-regioner. Se .

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

Anropa Analys-API:et med alternativ

Följande kod anropar API:et Analysera bild med de funktioner som du har valt ovan och andra alternativ som definieras härnäst. Om du vill analysera från en bildbuffert i stället för URL ersätter du imageURL metodanropet med 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älj proportioner för smart beskärning

Ett proportioner beräknas genom att målgrödbredden divideras med höjden. Värden som stöds är från 0,75 till 1,8 (inklusive). Att ange den här egenskapen är bara relevant när VisualFeatures.SmartCrops valdes som en del av listan över visuella funktioner. Om du väljer VisualFeatures.SmartCrops men inte anger proportioner returnerar tjänsten ett beskärningsförslag med ett proportioner som passar. I det här fallet är proportionerna mellan 0,5 och 2,0 (inklusive).

Välj könsneutrala bildtexter

Om du extraherar bildtexter eller kompakta bildtexter (med hjälp av VisualFeatures.Caption eller VisualFeatures.DenseCaptions) kan du be om könsneutrala bildtexter. Könsneutrala bildtexter är valfria, där standardvärdet är könsbestämda bildtexter. När du till exempel väljer könsneutrala bildtexter på engelska ersätts termer som kvinna eller man med person och pojke eller flicka ersätts med barn.

Ange språk

Du kan ange språket för de returnerade data. Språket är valfritt, med standardvärdet engelska. Se Språkstöd för en lista över språkkoder som stöds och vilka visuella funktioner som stöds för varje språk.

Hämta resultat från tjänsten

Följande kod visar hur du parsar resultatet av de olika analysåtgärderna .

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

Felsökning

Loggning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg med HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Du kan också aktivera loggning vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Mer detaljerade anvisningar om hur du aktiverar loggar finns i dokument för @azure/logger-paket.

Förutsättningar

Den här guiden förutsätter att du har följt stegen som nämns på snabbstartssidan. Detta innebär att:

  • Du har skapat en Visuellt innehåll resurs och fått en nyckel och en slutpunkts-URL.
  • Du har gjort ett curl.exe anrop till tjänsten (eller använt ett alternativt verktyg). Du ändrar anropet curl.exe baserat på exemplen här.

Autentisera mot tjänsten

Om du vill autentisera mot tjänsten Bildanalys behöver du en Visuellt innehåll nyckel och slutpunkts-URL.

Viktigt!

Om du använder en API-nyckel lagrar du den på ett säkert sätt någon annanstans, till exempel i Azure Key Vault. Inkludera inte API-nyckeln direkt i koden och publicera den aldrig offentligt.

Mer information om säkerhet för AI-tjänster finns i Autentisera begäranden till Azure AI-tjänster.

SDK-exemplet förutsätter att du har definierat miljövariablerna VISION_KEY och VISION_ENDPOINT med din nyckel och slutpunkt.

Autentiseringen görs genom att lägga till HTTP-begärandehuvudet Ocp-Apim-Subscription-Key och ange den till din visionsnyckel. Anropet görs till URL:en <endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01, där <endpoint> är din unika slutpunkts-URL för visuellt innehåll. Du lägger till frågesträngar baserat på dina analysalternativ.

Välj den bild som ska analyseras

Koden i den här guiden använder fjärrbilder som refereras till via URL. Du kanske vill prova olika bilder på egen hand för att se den fullständiga funktionen för bildanalysfunktionerna.

Bild-URL

När du analyserar en fjärrbild anger du bildens URL genom att formatera begärandetexten så här: {"url":"https://learn.microsoft.com/azure/cognitive-services/computer-vision/images/windows-kitchen.jpg"}. Innehållstypen ska vara application/json.

Image file

Om du vill analysera en lokal bild placerar du binära bilddata i HTTP-begärandetexten. Innehållstypen ska vara application/octet-stream eller multipart/form-data.

Välj analysalternativ

Välj visuella funktioner när du använder standardmodellen

Api:et Analysis 4.0 ger dig åtkomst till alla tjänstens bildanalysfunktioner. Välj vilka åtgärder som ska utföras baserat på ditt eget användningsfall. Se översikten för en beskrivning av varje funktion. Exemplet i det här avsnittet lägger till alla tillgängliga visuella funktioner, men för praktisk användning behöver du förmodligen färre.

Visuella funktioner "Captions" och "DenseCaptions" stöds endast i vissa Azure-regioner: se Regiontillgänglighet.

Kommentar

REST-API:et använder termerna Smart Crops och Smart Crops Aspect Ratios. SDK använder termerna Beskärningsförslag och Beskärningsproportioner. Båda refererar till samma tjänståtgärd. På samma sätt använder REST-API:et termen Läs för att identifiera text i bilden med hjälp av optisk teckenigenkänning (OCR), medan SDK använder termen Text för samma åtgärd.

Du kan ange vilka funktioner du vill använda genom att ange URL-frågeparametrarna för API:et Analysis 4.0. En parameter kan ha flera värden, avgränsade med kommatecken.

URL-parameter Värde beskrivning
features read Läser den synliga texten i bilden och matar ut den som strukturerade JSON-data.
features caption Beskriver bildinnehållet med en fullständig mening på språk som stöds.
features denseCaptions Genererar detaljerade bildtexter för upp till 10 framträdande bildregioner.
features smartCrops Hittar de rektangelkoordinater som skulle beskära bilden till ett önskat proportioner samtidigt som det intressanta området bevaras.
features objects Identifierar olika objekt i en bild, inklusive den ungefärliga platsen. Argumentet Objekt är endast tillgängligt på engelska.
features tags Taggar bilden med en detaljerad lista med ord som är relaterade till bildinnehållet.
features people Identifierar personer som visas i bilder, inklusive ungefärliga platser.

En ifylld URL kan se ut så här:

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

Ange modellnamn när du använder en anpassad modell

Du kan också göra bildanalys med en anpassad tränad modell. Information om hur du skapar och tränar en modell finns i Skapa en anpassad bildanalysmodell. När din modell har tränats behöver du bara modellens namn. Du behöver inte ange visuella funktioner om du använder en anpassad modell.

Om du vill använda en anpassad modell ska du inte använda frågeparametern funktioner. Ange i stället parametern model-name till namnet på din modell som visas här. Ersätt MyCustomModelName med ditt anpassade modellnamn.

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

Ange språk

Du kan ange språket för de returnerade data. Språket är valfritt, med standardvärdet engelska. Se Språkstöd för en lista över språkkoder som stöds och vilka visuella funktioner som stöds för varje språk.

Språkalternativet gäller endast när du använder standardmodellen.

Följande URL-frågeparameter anger språket. Standardvärdet är en.

URL-parameter Värde beskrivning
language en Engelska
language es Spanska
language ja Japanska
language pt Portugisiska
language zh Förenklad kinesiska

En ifylld URL kan se ut så här:

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

Välj könsneutrala bildtexter

Om du extraherar bildtexter eller kompakta bildtexter kan du be om könsneutrala bildtexter. Könsneutrala bildtexter är valfria, där standardvärdet är könsbestämda bildtexter. När du till exempel väljer könsneutrala bildtexter på engelska ersätts termer som kvinna eller man med person och pojke eller flicka ersätts med barn.

Alternativet för könsneutral bildtext gäller endast när du använder standardmodellen.

Lägg till den valfria frågesträngen gender-neutral-caption med värden true eller false (standardvärdet).

En ifylld URL kan se ut så här:

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

Välj proportioner för smart beskärning

Ett proportioner beräknas genom att målgrödbredden divideras med höjden. Värden som stöds är från 0,75 till 1,8 (inklusive). Att ange den här egenskapen är bara relevant när VisualFeatures.SmartCrops valdes som en del av listan över visuella funktioner. Om du väljer VisualFeatures.SmartCrops men inte anger proportioner returnerar tjänsten ett beskärningsförslag med ett proportioner som passar. I det här fallet är proportionerna mellan 0,5 och 2,0 (inklusive).

Smart beskärningsaspektransoneringar gäller endast när du använder standardmodellen.

Lägg till den valfria frågesträngen smartcrops-aspect-ratios, med ett eller flera proportioner avgränsade med ett kommatecken.

En ifylld URL kan se ut så här:

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

Hämta resultat från tjänsten

Hämta resultat med hjälp av standardmodellen

Det här avsnittet visar hur du gör ett analysanrop till tjänsten med hjälp av standardmodellen och hämtar resultaten.

Tjänsten returnerar ett 200 HTTP-svar och brödtexten innehåller returnerade data i form av en JSON-sträng. Följande text är ett exempel på ett JSON-svar.

{
    "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
        }
      ]
    }
  }

Felkoder

Vid fel innehåller svaret från tjänsten Bildanalys en JSON-nyttolast som innehåller en felkod och ett felmeddelande. Den kan också innehålla annan information i form av och inre felkod och meddelande. Till exempel:

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

Följande är en lista över vanliga fel och deras orsaker. Listobjekt visas i följande format:

  • HTTP-svarskod
    • Felkod och meddelande i JSON-svaret
      • [Valfritt] Inre felkod och meddelande i JSON-svaret

Lista över vanliga fel:

  • 400 Bad Request
    • InvalidRequest - Image URL is badly formatted or not accessible. Kontrollera att bild-URL:en är giltig och offentligt tillgänglig.
    • InvalidRequest - The image size is not allowed to be zero or larger than 20971520 bytes. Minska storleken på bilden genom att komprimera den och/eller ändra storlek och skicka din begäran igen.
    • InvalidRequest - The feature 'Caption' is not supported in this region. Funktionen stöds endast i specifika Azure-regioner. Se Krav för snabbstart för listan över Azure-regioner som stöds.
    • InvalidRequest - The provided image content type ... is not supported. HTTP-huvudets innehållstyp i begäran är inte en tillåten typ:
      • För en bild-URL ska innehållstyp vara application/json
      • För binära bilddata ska Innehållstyp vara application/octet-stream eller multipart/form-data
    • InvalidRequest - Either 'features' or 'model-name' needs to be specified in the query parameter.
    • InvalidRequest - Image format is not valid
    • InvalidRequest - Analyze query is invalid
      • NotSupportedVisualFeature - Specified feature type is not valid. Kontrollera att frågesträngen för funktioner har ett giltigt värde.
      • NotSupportedLanguage - The input language is not supported. Kontrollera att språkfrågesträngen har ett giltigt värde för den valda visuella funktionen, baserat på följande tabell.
      • 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. Det gick inte att hitta den anpassade modellen baserat på namnet som tillhandahålls av frågesträngen model-name .

Nästa steg