Aufrufen der Analyse-API für Bildanalyse 4.0

  • Artikel

In diesem Artikel wird veranschaulicht, wie Sie die Bildanalyse 4.0-API aufrufen, um Informationen zu den visuellen Features eines Bilds zurückzugeben. Außerdem wird gezeigt, wie Sie die zurückgegebenen Informationen parsen.

Voraussetzungen

In diesem Leitfaden wird davon ausgegangen, dass Sie die auf der Schnellstartseite beschriebenen Schritte ausgeführt haben. Das bedeutet:

  • Sie haben eine Ressource für maschinelles Sehen erstellt und einen Schlüssel sowie eine Endpunkt-URL erhalten.
  • Sie haben das entsprechende SDK-Paket installiert, und Sie führen eine Anwendung aus dem Schnellstart aus. Sie können diese Schnellstartanwendung anhand der hier gezeigten Codebeispiele ändern.

Erstellen und Authentifizieren des Clients

Um sich beim Bildanalysedienst zu authentifizieren, benötigen Sie einen Schlüssel für maschinelles Sehen und eine Endpunkt-URL. In diesem Leitfaden wird davon ausgegangen, dass Sie die Umgebungsvariablen VISION_KEY und VISION_ENDPOINT mit Ihrem Schlüssel und Endpunkt definiert haben.

Tipp

Fügen Sie den Schlüssel nicht direkt in Ihren Code ein, und machen Sie ihn nicht öffentlich. Im Artikel zur Azure KI Services-Sicherheit finden Sie weitere Authentifizierungsoptionen, wie zum Beispiel Azure Key Vault.

Erstellen Sie zunächst ein ImageAnalysisClient-Objekt. Beispiel:

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

Wählen des zu analysierenden Bilds

Sie können ein Bild auswählen, indem Sie eine öffentlich zugängliche Bild-URL angeben oder Binärdaten an das SDK übergeben. Informationen zu unterstützten Bildformaten finden Sie unter Bildanforderungen.

Bild-URL

Erstellen Sie ein URI-Objekt für das Bild, das Sie analysieren möchten.

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

Bildpuffer

Alternativ können Sie die Bilddaten über ein BinaryData-Objekt an das SDK übergeben. Lesen Sie beispielsweise aus einer lokalen Bilddatei, die Sie analysieren möchten.

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

Auswählen visueller Merkmale

Die Analyse 4.0-API gibt Ihnen Zugriff auf alle Bildanalysefunktionen des Diensts. Wählen Sie ausgehend von Ihrem eigenen Anwendungsfall aus, welche Vorgänge ausgeführt werden sollen. Eine Beschreibung der einzelnen Features finden Sie in der Übersicht. Im Beispiel in diesem Abschnitt werden alle verfügbaren Features für Visuals hinzugefügt, aber für die praktische Nutzung benötigen Sie wahrscheinlich weniger.

Wichtig

Die visuellen Features Captions und DenseCaptions werden nur in den folgenden Azure-Regionen unterstützt: „USA, Osten“, „Frankreich, Mitte“, „Südkorea, Mitte“, „Europa, Norden“, „Asien, Südosten“, „Europa, Westen“, „USA, Westen“.

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

Auswählen von Analyseoptionen

Verwenden Sie ein ImageAnalysisOptions-Objekt, um verschiedene Optionen für den Analyse-API-Aufruf anzugeben.

  • Sprache: Sie können die Sprache der zurückgegebenen Daten angeben. Die Sprache ist optional, wobei die Standardeinstellung Englisch ist. Unter Sprachunterstützung finden Sie eine Liste der unterstützten Sprachcodes und welche visuellen Features für jede Sprache unterstützt werden.
  • Geschlechtsneutrale Beschriftungen: Wenn Sie Beschriftungen oder dichte Beschriftungen extrahieren (mithilfe von VisualFeatures.Caption oder VisualFeatures.DenseCaptions), können Sie geschlechtsneutrale Beschriftungen anfordern. Geschlechtsneutrale Beschriftungen sind optional, wobei geschlechtsspezifische Beschriftungen die Standardeinstellung sind. Wenn Sie beispielsweise auf Englisch geschlechtsneutrale Beschriftungen auswählen, werden Begriffe wie women oder man durch person und boy oder girl durch child ersetzt.
  • Seitenverhältnis für Zuschnitt: Ein Seitenverhältnis wird berechnet, indem die Zielzuschnittbreite durch die Höhe dividiert wird. Die unterstützten Werte liegen zwischen (einschließlich) 0,75 und 1,8. Das Festlegen dieser Eigenschaft ist nur relevant, wenn VisualFeatures.SmartCrops als Teil der visuellen Featureliste ausgewählt wurde. Wenn Sie VisualFeatures.SmartCrops auswählen, aber keine Seitenverhältnisse angeben, gibt der Dienst einen Zuschnittvorschlag mit einem Seitenverhältnis zurück, das ihm geeignet erscheint. In diesem Fall liegt das Seitenverhältnis zwischen (einschließlich) 0,5 und 2,0.
ImageAnalysisOptions options = new ImageAnalysisOptions { 
    GenderNeutralCaption = true,
    Language = "en",
    SmartCropsAspectRatios = new float[] { 0.9F, 1.33F }};

Aufrufen der Bildanalyse-API

In diesem Abschnitt erfahren Sie, wie Sie einen Analyseaufruf für den Dienst ausführen.

Rufen Sie die Analyze-Methode für das ImageAnalysisClient-Objekt auf, wie hier gezeigt. Der Aufruf ist synchron, und er wird blockiert, bis der Dienst die Ergebnisse zurückgibt oder ein Fehler aufgetreten ist. Alternativ können Sie die nicht blockierende AnalyzeAsync-Methode aufrufen.

Verwenden Sie die in den obigen Abschnitten erstellten Eingabeobjekte. Um aus einem Bildpuffer anstelle einer URL zu analysieren, ersetzen Sie imageURL im Methodenaufruf durch die Variable imageData.

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

Abrufen von Ergebnissen aus dem Dienst

Der folgende Code zeigt, wie Sie die Ergebnisse der verschiedenen Analysevorgänge analysieren.

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

Problembehandlung

Ausnahmebehandlung

Wenn Sie mit der Bildanalyse mithilfe des .NET SDK interagieren, führt jede Antwort des Diensts, die keinen (Erfolgs-)Statuscode 200 aufweist, zu einer Ausnahme, die ausgelöst wird. Wenn Sie beispielsweise versuchen, ein Bild zu analysieren, auf das aufgrund einer fehlerhaften URL nicht zugegriffen werden kann, wird ein Statuscode 400 zurückgegeben, der eine ungültige Anforderung angibt, und eine entsprechende Ausnahme wird ausgelöst.

Im folgenden Codeschnipsel werden Fehler ordnungsgemäß behandelt, indem die Ausnahme abgefangen wird und zusätzliche Fehlerinformationen angezeigt werden.

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

Weitere Informationen zum Aktivieren der SDK-Protokollierung finden Sie hier.

Voraussetzungen

In diesem Leitfaden wird davon ausgegangen, dass Sie die im Schnellstart beschriebenen Schritte ausgeführt haben. Das bedeutet:

  • Sie haben eine Ressource für maschinelles Sehen erstellt und einen Schlüssel sowie eine Endpunkt-URL erhalten.
  • Sie haben das entsprechende SDK-Paket installiert, und Sie führen eine Anwendung aus dem Schnellstart aus. Sie können diese Schnellstartanwendung anhand der hier gezeigten Codebeispiele ändern.

Erstellen und Authentifizieren des Clients

Um sich beim Bildanalysedienst zu authentifizieren, benötigen Sie einen Schlüssel für maschinelles Sehen und eine Endpunkt-URL. In diesem Leitfaden wird davon ausgegangen, dass Sie die Umgebungsvariablen VISION_KEY und VISION_ENDPOINT mit Ihrem Schlüssel und Endpunkt definiert haben.

Tipp

Fügen Sie den Schlüssel nicht direkt in Ihren Code ein, und machen Sie ihn nicht öffentlich. Im Artikel zur Azure KI Services-Sicherheit finden Sie weitere Authentifizierungsoptionen, wie zum Beispiel Azure Key Vault.

Erstellen Sie zunächst ein ImageAnalysisClient-Objekt mit einem der Konstruktoren. Beispiel:

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

Wählen des zu analysierenden Bilds

Sie können ein Bild auswählen, indem Sie eine öffentlich zugängliche Bild-URL angeben oder Bilddaten in den Eingabepuffer des SDK lesen. Informationen zu unterstützten Bildformaten finden Sie unter Bildanforderungen.

Bild-URL

Sie können die folgende Beispielbild-URL verwenden.

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

Bildpuffer

Alternativ können Sie das Bild als Byte-Objekt übergeben. Lesen Sie beispielsweise aus einer lokalen Bilddatei, die Sie analysieren möchten.

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

Auswählen visueller Merkmale

Die Analyse 4.0-API gibt Ihnen Zugriff auf alle Bildanalysefunktionen des Diensts. Wählen Sie ausgehend von Ihrem eigenen Anwendungsfall aus, welche Vorgänge ausgeführt werden sollen. Eine Beschreibung der einzelnen Features finden Sie in der Übersicht. Im Beispiel in diesem Abschnitt werden alle verfügbaren Features für Visuals hinzugefügt, aber für die praktische Nutzung benötigen Sie wahrscheinlich weniger.

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

Aufrufen der analyze_from_url-Methode mit Optionen

Der folgende Code ruft die analyze_from_url-Methode auf dem Client mit den oben ausgewählten Features und den unten definierten zusätzlichen Optionen auf. Rufen Sie zum Analysieren aus einem Bildpuffer anstelle der URL die Methode analyze mit image_data=image_data als erstes Argument auf.

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

Auswählen von Seitenverhältnissen für intelligentes Zuschneiden

Ein Seitenverhältnis wird berechnet, indem die Zielzuschnittbreite durch die Höhe dividiert wird. Die unterstützten Werte liegen zwischen (einschließlich) 0,75 und 1,8. Das Festlegen dieser Eigenschaft ist nur relevant, wenn VisualFeatures.SMART_CROPS als Teil der visuellen Featureliste ausgewählt wurde. Wenn Sie VisualFeatures.SMART_CROPS auswählen, aber keine Seitenverhältnisse angeben, gibt der Dienst einen Zuschnittvorschlag mit einem Seitenverhältnis zurück, das ihm geeignet erscheint. In diesem Fall liegt das Seitenverhältnis zwischen (einschließlich) 0,5 und 2,0.

Auswählen geschlechtsneutraler Beschriftungen

Wenn Sie Beschriftungen oder dichte Beschriftungen extrahieren (mithilfe von VisualFeatures.CAPTION oder VisualFeatures.DENSE_CAPTIONS), können Sie geschlechtsneutrale Beschriftungen anfordern. Geschlechtsneutrale Beschriftungen sind optional, wobei geschlechtsspezifische Beschriftungen die Standardeinstellung sind. Wenn Sie beispielsweise auf Englisch geschlechtsneutrale Beschriftungen auswählen, werden Begriffe wie women oder man durch person und boy oder girl durch child ersetzt.

Angeben von Sprachen

Sie können die Sprache der zurückgegebenen Daten angeben. Die Sprache ist optional, wobei die Standardeinstellung Englisch ist. Unter Sprachunterstützung finden Sie eine Liste der unterstützten Sprachcodes und welche visuellen Features für jede Sprache unterstützt werden.

Abrufen von Ergebnissen aus dem Dienst

Der folgende Code zeigt, wie Sie die Ergebnisse der Vorgänge analyze_from_url oder analyze analysieren.

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

Problembehandlung

Ausnahmen

Die analyze-Methoden lösen eine HttpResponseError-Ausnahme für eine nicht erfolgreiche HTTP-Statuscodeantwort des Diensts aus. status_code der Ausnahme ist der HTTP-Antwortstatuscode. error.message der Ausnahme enthält eine detaillierte Meldung, mit der Sie das Problem diagnostizieren können:

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

Wenn Sie beispielsweise einen falschen Authentifizierungsschlüssel angeben:

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.

Oder wenn Sie eine Bild-URL angeben, die nicht existiert oder auf die nicht zugegriffen werden kann:

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

Logging

Dieser Client verwendet die standardmäßige Protokollierungsbibliothek von Python. Das SDK protokolliert HTTP-Anforderungs- und Antwortdetails, die bei der Problembehandlung hilfreich sein können. Um sich bei stdout anzumelden, fügen Sie Folgendes hinzu:

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)

Standardmäßig bearbeiten Protokolle die Werte von URL-Abfragezeichenfolgen, die Werte einiger HTTP-Anforderungs- und -Antwortheader (einschließlich des Ocp-Apim-Subscription-Key-Headers, der den Schlüssel enthält) und die Anforderungs- und Antwortnutzdaten. Wenn Sie Protokolle ohne Bearbeitung erstellen möchten, legen Sie das Methodenargument logging_enable = True fest, wenn Sie ImageAnalysisClient erstellen oder wenn Sie analyze auf dem Client aufrufen.

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

Es werden keine bearbeiteten Protokolle für die Protokollebene logging.DEBUG generiert. Stellen Sie sicher, nicht bearbeitete Protokolle zu schützen, um eine Beeinträchtigung der Sicherheit zu vermeiden. Weitere Informationen finden Sie unter Konfigurieren der Protokollierung in den Azure-Bibliotheken für Python

Voraussetzungen

In diesem Leitfaden wird davon ausgegangen, dass Sie die Schritte auf der Schnellstartseite ausgeführt haben. Das bedeutet:

  • Sie haben eine Ressource für maschinelles Sehen erstellt und einen Schlüssel sowie eine Endpunkt-URL erhalten.
  • Sie haben das entsprechende SDK-Paket installiert, und Sie führen eine Anwendung aus dem Schnellstart aus. Sie können diese Schnellstartanwendung anhand der hier gezeigten Codebeispiele ändern.

Erstellen und Authentifizieren des Clients

Um sich beim Bildanalysedienst zu authentifizieren, benötigen Sie einen Schlüssel für maschinelles Sehen und eine Endpunkt-URL. In diesem Leitfaden wird davon ausgegangen, dass Sie die Umgebungsvariablen VISION_KEY und VISION_ENDPOINT mit Ihrem Schlüssel und Endpunkt definiert haben.

Tipp

Fügen Sie den Schlüssel nicht direkt in Ihren Code ein, und machen Sie ihn nicht öffentlich. Im Artikel zur Azure KI Services-Sicherheit finden Sie weitere Authentifizierungsoptionen, wie zum Beispiel Azure Key Vault.

Erstellen Sie zunächst ein ImageAnalysisClient-Objekt. Beispiel:

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

Wählen des zu analysierenden Bilds

Sie können ein Bild auswählen, indem Sie eine öffentlich zugängliche Bild-URL angeben oder Bilddaten in den Eingabepuffer des SDK lesen. Informationen zu unterstützten Bildformaten finden Sie unter Bildanforderungen.

Bild-URL

Erstellen Sie eine imageUrl-Zeichenfolge, um die öffentlich zugängliche URL des zu analysierenden Bilds zu enthalten.

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

Bildpuffer

Alternativ können Sie das Bild als Speicherpuffer mithilfe eines BinaryData-Objekts übergeben. Lesen Sie beispielsweise aus einer lokalen Bilddatei, die Sie analysieren möchten.

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

Auswählen visueller Merkmale

Die Analyse 4.0-API gibt Ihnen Zugriff auf alle Bildanalysefunktionen des Diensts. Wählen Sie ausgehend von Ihrem eigenen Anwendungsfall aus, welche Vorgänge ausgeführt werden sollen. Eine Beschreibung der einzelnen Features finden Sie in der Übersicht. Im Beispiel in diesem Abschnitt werden alle verfügbaren Features für Visuals hinzugefügt, aber für die praktische Nutzung benötigen Sie wahrscheinlich weniger.

Wichtig

Die Features Captions und DenseCaptions für Visuals werden nur in den folgenden Azure-Regionen unterstützt: „USA, Osten“, „Frankreich, Mitte“, „Südkorea, Mitte“, „Europa, Norden“, „Asien, Südosten“, „Europa, Westen“, „USA, Westen“.

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

Auswählen von Analyseoptionen

Verwenden Sie ein ImageAnalysisOptions-Objekt, um verschiedene Optionen für den Analyse-API-Aufruf anzugeben.

  • Sprache: Sie können die Sprache der zurückgegebenen Daten angeben. Die Sprache ist optional, wobei die Standardeinstellung Englisch ist. Unter Sprachunterstützung finden Sie eine Liste der unterstützten Sprachcodes und welche visuellen Features für jede Sprache unterstützt werden.
  • Geschlechtsneutrale Beschriftungen: Wenn Sie Beschriftungen oder dichte Beschriftungen extrahieren (mithilfe von VisualFeatures.CAPTION oder VisualFeatures.DENSE_CAPTIONS), können Sie geschlechtsneutrale Beschriftungen anfordern. Geschlechtsneutrale Beschriftungen sind optional, wobei geschlechtsspezifische Beschriftungen die Standardeinstellung sind. Wenn Sie beispielsweise auf Englisch geschlechtsneutrale Beschriftungen auswählen, werden Begriffe wie women oder man durch person und boy oder girl durch child ersetzt.
  • Seitenverhältnis für Zuschnitt: Ein Seitenverhältnis wird berechnet, indem die Zielzuschnittbreite durch die Höhe dividiert wird. Die unterstützten Werte liegen zwischen (einschließlich) 0,75 und 1,8. Das Festlegen dieser Eigenschaft ist nur relevant, wenn VisualFeatures.SMART_CROPS als Teil der visuellen Featureliste ausgewählt wurde. Wenn Sie VisualFeatures.SMART_CROPS auswählen, aber keine Seitenverhältnisse angeben, gibt der Dienst einen Zuschnittvorschlag mit einem Seitenverhältnis zurück, das ihm geeignet erscheint. In diesem Fall liegt das Seitenverhältnis zwischen (einschließlich) 0,5 und 2,0.
// Specify analysis options (or set `options` to null for defaults)
ImageAnalysisOptions options = new ImageAnalysisOptions()
    .setLanguage("en")
    .setGenderNeutralCaption(true)
    .setSmartCropsAspectRatios(Arrays.asList(0.9, 1.33, 1.78));

Aufrufen der analyzeFromUrl-Methode

In diesem Abschnitt erfahren Sie, wie Sie einen Analyseaufruf für den Dienst ausführen.

Rufen Sie die analyzeFromUrl-Methode für das ImageAnalysisClient-Objekt auf, wie hier gezeigt. Der Aufruf ist synchron, und er wird blockiert, bis der Dienst die Ergebnisse zurückgibt oder ein Fehler aufgetreten ist. Alternativ können Sie stattdessen ein ImageAnalysisAsyncClient-Objekt verwenden und dessen analyzeFromUrl-Methode aufrufen, die nicht blockierend ist.

Rufen Sie zum Analysieren aus einem Bildpuffer anstelle der URL die Methode analyze auf, und übergeben Sie sie in den imageData als erstes 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());
}

Abrufen von Ergebnissen aus dem Dienst

Der folgende Code zeigt, wie Sie die Ergebnisse der Vorgänge analyzeFromUrl oder analyze analysieren.

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

Problembehandlung

Ausnahmen

Die analyze-Methoden lösen HttpResponseException aus, wenn der Dienst mit einem nicht erfolgreichen HTTP-Statuscode antwortet. getResponse().getStatusCode() der Ausnahme enthält den HTTP-Antwortstatuscode. getMessage() der Ausnahme enthält eine detaillierte Meldung, mit der Sie das Problem diagnostizieren können:

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

Wenn Sie beispielsweise einen falschen Authentifizierungsschlüssel angeben:

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

Oder wenn Sie ein Bild in einem Format bereitstellen, das nicht erkannt wird:

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

Aktivieren der Protokollierung von HTTP-Anforderungen/-Antworten

Das Überprüfen der über die Verbindung mit dem Bildanalysedienst gesendeten HTTP-Anforderung oder empfangenen HTTP-Antwort kann bei der Problembehandlung hilfreich sein. Die Bildanalyse-Clientbibliothek unterstützt ein integriertes Konsolenprotokollierungs-Framework für temporäre Debuggingzwecke. Sie unterstützt auch die erweiterte Protokollierung mithilfe der SLF4J--Schnittstelle. Weitere Informationen finden Sie unter Verwenden der Protokollierung im Azure SDK für Java.

In den folgenden Abschnitten wird die Aktivierung der Konsolenprotokollierung mithilfe des integrierten Frameworks erläutert.

Durch Festlegen von Umgebungsvariablen

Sie können die Konsolenprotokollierung von HTTP-Anforderungen und -Antworten für die gesamte Anwendung aktivieren, indem Sie die folgenden beiden Umgebungsvariablen festlegen. Diese Änderung wirkt sich auf jeden Azure-Client aus, der die Protokollierung von HTTP-Anforderungen und -Antworten unterstützt.

  • Legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf debug fest
  • Legen Sie die Umgebungsvariable AZURE_HTTP_LOG_DETAIL_LEVEL auf einen der folgenden Werte fest:
Wert Protokolliergrad
none Protokollierung von HTTP-Anforderungen/-Antworten ist deaktiviert
basic Protokolliert nur URLs, HTTP-Methoden und die Zeit bis zum Abschluss der Anforderung.
headers Protokolliert alles in BASIC sowie alle Anforderungs- und Antwortheader.
body Protokolliert alles in BASIC sowie den gesamten Anforderungs- und Antworttext.
body_and_headers Protokolliert alles in HEADERS und BODY.

Durch Festlegen von httpLogOptions

So aktivieren Sie die Konsolenprotokollierung von HTTP-Anforderungen und -Antworten für einen einzelnen Client

  • Legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf debug fest
  • Fügen Sie beim Erstellen von ImageAnalysisClient einen Aufruf zu httpLogOptions hinzu:
ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
    .buildClient();

Die Enumeration HttpLogDetailLevel definiert die unterstützten Protokollierungsgrade.

Bei der Protokollierung werden standardmäßig bestimmte HTTP-Header- und -Abfrageparameterwerte bearbeitet. Sie können diese Standardeinstellung überschreiben, indem Sie angeben, welche Header- und Abfrageparameter sicher protokolliert werden können:

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

Um beispielsweise ein vollständiges, nicht bearbeitetes Protokoll der HTTP-Anforderung abzurufen, wenden Sie Folgendes an:

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

Fügen Sie oben mehr hinzu, um eine nicht bearbeitete HTTP-Antwort abzurufen. Wenn Sie ein nicht bearbeitetes Protokoll freigeben, stellen Sie sicher, dass es keine Geheimnisse wie Ihren Abonnementschlüssel enthält.

Voraussetzungen

In diesem Leitfaden wird davon ausgegangen, dass Sie die im Schnellstart beschriebenen Schritte ausgeführt haben. Das bedeutet:

  • Sie haben eine Ressource für maschinelles Sehen erstellt und einen Schlüssel sowie eine Endpunkt-URL erhalten.
  • Sie haben das entsprechende SDK-Paket installiert, und Sie führen eine Anwendung aus dem Schnellstart aus. Sie können diese Schnellstartanwendung anhand der hier gezeigten Codebeispiele ändern.

Erstellen und Authentifizieren des Clients

Um sich beim Bildanalysedienst zu authentifizieren, benötigen Sie einen Schlüssel für maschinelles Sehen und eine Endpunkt-URL. In diesem Leitfaden wird davon ausgegangen, dass Sie die Umgebungsvariablen VISION_KEY und VISION_ENDPOINT mit Ihrem Schlüssel und Endpunkt definiert haben.

Tipp

Fügen Sie den Schlüssel nicht direkt in Ihren Code ein, und machen Sie ihn nicht öffentlich. Im Artikel zur Azure KI Services-Sicherheit finden Sie weitere Authentifizierungsoptionen, wie zum Beispiel Azure Key Vault.

Erstellen Sie zunächst ein ImageAnalysisClient-Objekt. Beispiel:

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

Wählen des zu analysierenden Bilds

Sie können ein Bild auswählen, indem Sie eine öffentlich zugängliche Bild-URL angeben oder Bilddaten in den Eingabepuffer des SDK lesen. Informationen zu unterstützten Bildformaten finden Sie unter Bildanforderungen.

Bild-URL

Sie können die folgende Beispielbild-URL verwenden.

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

Bildpuffer

Alternativ können Sie das Bild als Datenarray übergeben. Lesen Sie beispielsweise aus einer lokalen Bilddatei, die Sie analysieren möchten.

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

Auswählen visueller Merkmale

Die Analyse 4.0-API gibt Ihnen Zugriff auf alle Bildanalysefunktionen des Diensts. Wählen Sie ausgehend von Ihrem eigenen Anwendungsfall aus, welche Vorgänge ausgeführt werden sollen. Eine Beschreibung der einzelnen Features finden Sie in der Übersicht. Im Beispiel in diesem Abschnitt werden alle verfügbaren Features für Visuals hinzugefügt, aber für die praktische Nutzung benötigen Sie wahrscheinlich weniger.

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

Aufrufen der Bildanalyse-API mit Optionen

Der folgende Code ruft die Analyse-API mit den oben ausgewählten Features und den unten definierten zusätzlichen Optionen auf. Um aus einem Bildpuffer anstelle einer URL zu analysieren, ersetzen Sie imageURL im Methodenaufruf durch 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'
});

Auswählen von Seitenverhältnissen für intelligentes Zuschneiden

Ein Seitenverhältnis wird berechnet, indem die Zielzuschnittbreite durch die Höhe dividiert wird. Die unterstützten Werte liegen zwischen (einschließlich) 0,75 und 1,8. Das Festlegen dieser Eigenschaft ist nur relevant, wenn VisualFeatures.SmartCrops als Teil der visuellen Featureliste ausgewählt wurde. Wenn Sie VisualFeatures.SmartCrops auswählen, aber keine Seitenverhältnisse angeben, gibt der Dienst einen Zuschnittvorschlag mit einem Seitenverhältnis zurück, das ihm geeignet erscheint. In diesem Fall liegt das Seitenverhältnis zwischen (einschließlich) 0,5 und 2,0.

Auswählen geschlechtsneutraler Beschriftungen

Wenn Sie Beschriftungen oder dichte Beschriftungen extrahieren (mithilfe von VisualFeatures.Caption oder VisualFeatures.DenseCaptions), können Sie geschlechtsneutrale Beschriftungen anfordern. Geschlechtsneutrale Beschriftungen sind optional, wobei geschlechtsspezifische Beschriftungen die Standardeinstellung sind. Wenn Sie beispielsweise auf Englisch geschlechtsneutrale Beschriftungen auswählen, werden Begriffe wie women oder man durch person und boy oder girl durch child ersetzt.

Angeben von Sprachen

Sie können die Sprache der zurückgegebenen Daten angeben. Die Sprache ist optional, wobei die Standardeinstellung Englisch ist. Unter Sprachunterstützung finden Sie eine Liste der unterstützten Sprachcodes und welche visuellen Features für jede Sprache unterstützt werden.

Abrufen von Ergebnissen aus dem Dienst

Der folgende Code zeigt, wie Sie die Ergebnisse der verschiedenen Analyze-Vorgänge analysieren.

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

Problembehandlung

Logging

Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf info fest. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie setLogLevel in @azure/logger aufrufen:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in der Paketdokumentation zu @azure/logger.

Voraussetzungen

In diesem Leitfaden wird davon ausgegangen, dass Sie die auf der Schnellstartseite beschriebenen Schritte erfolgreich ausgeführt haben. Das bedeutet:

  • Sie haben eine Ressource für maschinelles Sehen erstellt und einen Schlüssel sowie eine Endpunkt-URL erhalten.
  • Sie haben erfolgreich einen curl.exe-Aufruf an den Dienst durchgeführt (oder ein alternatives Tool verwendet). Sie ändern den curl.exe-Aufruf basierend auf den hier aufgeführten Beispielen.

Authentifizierung beim Dienst

Um sich beim Bildanalysedienst zu authentifizieren, benötigen Sie einen Schlüssel für maschinelles Sehen und eine Endpunkt-URL.

Tipp

Fügen Sie den Schlüssel nicht direkt in Ihren Code ein, und machen Sie ihn nicht öffentlich. Im Artikel zur Azure KI Services-Sicherheit finden Sie weitere Authentifizierungsoptionen, wie zum Beispiel Azure Key Vault.

Im SDK-Beispiel wird davon ausgegangen, dass Sie die Umgebungsvariablen VISION_KEY mit VISION_ENDPOINT Ihrem Schlüssel und Endpunkt definiert haben.

Die Authentifizierung erfolgt durch Hinzufügen des HTTP-Anforderungsheaders Ocp-Apim-Subscription-Key und Festlegen auf Ihren Vision-Schlüssel. Der Aufruf erfolgt an die URL <endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01, wobei <endpoint> Ihre eindeutige Endpunkt-URL für maschinelles Sehen ist. Sie fügen Abfragezeichenfolgen basierend auf Ihren Analyseoptionen hinzu.

Wählen des zu analysierenden Bilds

Der Code in diesem Leitfaden verwendet Remotebilder, auf die über URL verwiesen wird. Möglicherweise möchten Sie selbst verschiedene Bilder ausprobieren, um das ganze Potenzial der Bildanalysefeatures zu erfahren.

Beim Analysieren eines Remotebilds geben Sie die URL des Bilds an, indem Sie den Anforderungstext wie folgt formatieren: {"url":"https://learn.microsoft.com/azure/cognitive-services/computer-vision/images/windows-kitchen.jpg"}. Der Content-Type sollte application/json sein.

Zur Analyse eines lokalen Bilds platzieren Sie die binären Bilddaten im HTTP-Anforderungstext. Der Content-Type sollte application/octet-stream oder multipart/form-data sein.

Auswählen von Analyseoptionen

Auswählen visueller Features bei Verwendung des Standardmodells

Die Analyse 4.0-API gibt Ihnen Zugriff auf alle Bildanalysefunktionen des Diensts. Wählen Sie ausgehend von Ihrem eigenen Anwendungsfall aus, welche Vorgänge ausgeführt werden sollen. Eine Beschreibung der einzelnen Features finden Sie in der Übersicht. Im Beispiel in diesem Abschnitt werden alle verfügbaren visuellen Features hinzugefügt, aber für die praktische Nutzung benötigen Sie wahrscheinlich weniger.

Die visuellen Features „Captions“ und „DenseCaptions“ werden nur in den folgenden Azure-Regionen unterstützt: „USA, Osten“, „Frankreich, Mitte“, „Südkorea, Mitte“, „Europa, Norden“, „Asien, Südosten“, „Europa, Westen“, „USA, Westen“.

Hinweis

Die REST-API verwendet die Begriffe Intelligente Zuschnitte und Seitenverhältnisse für intelligente Zuschnitte. Das SDK verwendet die Begriffe Zuschnittvorschläge und Seitenverhältnisse für Zuschneiden. Beide bezeichnen denselben Dienstvorgang. In ähnlicher Weise verwendet die REST-API die Benennung Lesen, um mithilfe der optischen Zeichenerkennung (Optical Character Recognition, OCR) Text im Bild zu erkennen, während das SDK die Benennung Text für denselben Vorgang verwendet.

Sie können angeben, welche Features Sie verwenden möchten, indem Sie die URL-Abfrageparameter der Analyse 4.0-API festlegen. Ein Parameter kann mehrere, durch Kommas getrennte Werte enthalten.

URL-Parameter Wert BESCHREIBUNG
features read Liest den sichtbaren Text auf dem Bild und gibt ihn als strukturierte JSON-Daten aus
features caption Beschreibt den Bildinhalt in unterstützten Sprachen mit einem vollständigen Satz.
features denseCaptions Generiert detaillierte Beschriftungen für bis zu 10 prominente Bildbereiche.
features smartCrops Findet die Rechteckkoordinaten, die das Bild in ein gewünschtes Seitenverhältnis zuschneiden würden, während der relevante Bereich beibehalten wird
features objects Erkennt verschiedene Objekte in einem Bild, einschließlich der ungefähren Position. Das Objects-Argument ist nur für Englisch verfügbar.
features tags Erstellt Tags für das Bild in einer detaillierten Liste aus Wörtern, die sich auf den Bildinhalt beziehen.
features people Erkennt Personen, die in Bildern angezeigt werden, einschließlich der ungefähren Standorte.

Eine aufgefüllte URL kann folgendermaßen aussehen:

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

Festlegen des Modellnamens bei Verwendung eines benutzerdefinierten Modells

Sie können die Bildanalyse auch mit einem benutzerdefinierten trainierten Modell durchführen. Informationen zum Erstellen und Trainieren eines Modells finden Sie unter Erstellen eines benutzerdefinierten Bildanalysemodells. Nachdem Ihr Modell trainiert wurde, benötigen Sie nur noch den Namen des Modells. Wenn Sie ein benutzerdefiniertes Modell verwenden, müssen Sie keine visuellen Features angeben.

Um ein benutzerdefiniertes Modell zu verwenden, verwenden Sie nicht den Abfrageparameter „Features“. Legen Sie stattdessen den model-name-Parameter auf den Namen Ihres Modells fest, wie hier gezeigt. Ersetzen Sie MyCustomModelName durch ihren benutzerdefinierten Modellnamen.

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

Angeben von Sprachen

Sie können die Sprache der zurückgegebenen Daten angeben. Die Sprache ist optional, wobei die Standardeinstellung Englisch ist. Unter Sprachunterstützung finden Sie eine Liste der unterstützten Sprachcodes und welche visuellen Features für jede Sprache unterstützt werden.

Die Option Sprache kann nur mit dem Standardmodell verwendet werden.

Die Sprache wird mit dem folgenden URL-Abfrageparameter angegeben. Standardwert: en.

URL-Parameter Wert Beschreibung
language en Englisch
language es Spanisch
language ja Japanisch
language pt Portugiesisch (Portugal)
language zh Chinesisch (vereinfacht)

Eine aufgefüllte URL kann folgendermaßen aussehen:

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

Auswählen geschlechtsneutraler Beschriftungen

Wenn Sie Beschriftungen oder dichte Beschriftungen extrahieren, können Sie geschlechtsneutrale Beschriftungen anfordern. Geschlechtsneutrale Beschriftungen sind optional, wobei geschlechtsspezifische Beschriftungen die Standardeinstellung sind. Wenn Sie beispielsweise auf Englisch geschlechtsneutrale Beschriftungen auswählen, werden Begriffe wie women oder man durch person und boy oder girl durch child ersetzt.

Sie können die Option für geschlechtsneutrale Untertitel nur mit dem Standardmodell verwenden.

Fügen Sie die optionale Abfragezeichenfolge gender-neutral-caption mit den Werten true oder false (Standard) hinzu.

Eine aufgefüllte URL kann folgendermaßen aussehen:

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

Auswählen von Seitenverhältnissen für intelligentes Zuschneiden

Ein Seitenverhältnis wird berechnet, indem die Zielzuschnittbreite durch die Höhe dividiert wird. Die unterstützten Werte liegen zwischen (einschließlich) 0,75 und 1,8. Das Festlegen dieser Eigenschaft ist nur relevant, wenn VisualFeatures.SmartCrops als Teil der visuellen Featureliste ausgewählt wurde. Wenn Sie VisualFeatures.SmartCrops auswählen, aber keine Seitenverhältnisse angeben, gibt der Dienst einen Zuschnittvorschlag mit einem Seitenverhältnis zurück, das ihm geeignet erscheint. In diesem Fall liegt das Seitenverhältnis zwischen (einschließlich) 0,5 und 2,0.

Sie können die Smart Cropping-Seitenverhältnisse nur mit dem Standardmodell verwenden.

Fügen Sie die optionale Abfragezeichenfolge smartcrops-aspect-ratiosmit einem oder mehreren Seitenverhältnissen, durch Komma getrennt, hinzu.

Eine aufgefüllte URL kann folgendermaßen aussehen:

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

Abrufen von Ergebnissen aus dem Dienst

Abrufen von Ergebnissen mithilfe des Standardmodells

In diesem Abschnitt erfahren Sie, wie Sie mithilfe des Standardmodells einen Analyseaufruf für den Dienst ausführen und die Ergebnisse abrufen.

Der Dienst gibt eine 200-HTTP-Antwort zurück, und der Text enthält die zurückgegebenen Daten in Form einer JSON-Zeichenfolge. Der folgende Text ist ein Beispiel für eine JSON-Antwort:

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

Fehlercodes

Bei einem Fehler enthält die Antwort des Bildanalysediensts eine JSON-Payload, die einen Fehlercode und eine Fehlermeldung enthält. Es kann auch andere Details in Form eines innerem Fehlercodes und einer inneren Fehlermeldung enthalten. Beispiel:

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

Im Folgenden finden Sie eine Liste häufiger Fehler und deren Ursachen. Listenelemente werden im folgenden Format dargestellt:

  • HTTP-Antwortcode
    • Fehlercode und Fehlermeldung in der JSON-Antwort
      • [Optional] Interner Fehlercode und interne Fehlermeldung in der JSON-Antwort

Liste der häufigen Fehler:

  • 400 Bad Request
    • InvalidRequest - Image URL is badly formatted or not accessible. Stellen Sie sicher, dass die Bild-URL gültig und öffentlich zugänglich ist.
    • InvalidRequest - The image size is not allowed to be zero or larger than 20971520 bytes. Verringern Sie die Größe des Images, indem Sie es komprimieren und/oder die Größe ändern, und senden Sie Ihre Anforderung erneut.
    • InvalidRequest - The feature 'Caption' is not supported in this region. Das Feature wird nur in bestimmten Azure-Regionen unterstützt. Die Liste der unterstützten Azure-Regionen finden Sie unter Voraussetzungen für den Schnellstart.
    • InvalidRequest - The provided image content type ... is not supported. Der HTTP-Header Content-Type in der Anforderung ist kein zulässiger Typ:
      • Für eine Bild-URL sollte Content-Type den Wert application/json haben
      • Für binäre Bilddaten sollte Content-Type den Wert application/octet-stream oder multipart/form-data haben
    • 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. Informationen zu unterstützten Bildformaten finden Sie im Abschnitt Bildanforderungen.
    • InvalidRequest - Analyze query is invalid
      • NotSupportedVisualFeature - Specified feature type is not valid. Stellen Sie sicher, dass die Feature-Abfragezeichenfolge einen gültigen Wert aufweist.
      • NotSupportedLanguage - The input language is not supported. Stellen Sie sicher, dass die Sprache-Abfragezeichenfolge einen gültigen Wert für das ausgewählte visuelle Feature aufweist, basierend auf der folgenden Tabelle.
      • 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. Der Dienst konnte das benutzerdefinierte Modell basierend auf dem von der model-name-Abfragezeichenfolge angegebenen Namen nicht finden.

Nächste Schritte