Wywoływanie interfejsu API analizy obrazu 4.0

W tym artykule pokazano, jak wywołać interfejs API analizy obrazów 4.0 w celu zwrócenia informacji o funkcjach wizualnych obrazu. Przedstawiono również sposób analizowania zwróconych informacji.

Wymagania wstępne

W tym przewodniku założono, że wykonano kroki wymienione na stronie szybkiego startu. Składają się na to następujące elementy:

• Utworzono zasób przetwarzanie obrazów i uzyskano klucz i adres URL punktu końcowego.
• Masz zainstalowany odpowiedni pakiet ZESTAWU SDK i masz uruchomioną aplikację Szybki start . Tę aplikację szybki start można zmodyfikować na podstawie przykładów kodu tutaj.

Tworzenie i uwierzytelnianie klienta

Aby uwierzytelnić się w usłudze Analizy obrazów, potrzebujesz klucza przetwarzanie obrazów i adresu URL punktu końcowego. W tym przewodniku założono, że zdefiniowano zmienne VISION_KEY środowiskowe oraz VISION_ENDPOINT klucz i punkt końcowy.

Ważne

Jeśli używasz klucza interfejsu API, zapisz go bezpiecznie w innym miejscu, na przykład w usłudze Azure Key Vault. Nie dołączaj klucza interfejsu API bezpośrednio do kodu i nigdy nie publikuj go publicznie.

Aby uzyskać więcej informacji na temat zabezpieczeń usług sztucznej inteligencji, zobacz Uwierzytelnianie żądań w usługach Azure AI.

Zacznij od utworzenia obiektu ImageAnalysisClient . Na przykład:

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

Wybierz obraz do przeanalizowania

Obraz można wybrać, podając publicznie dostępny adres URL obrazu lub przekazując dane binarne do zestawu SDK. Zobacz Wymagania dotyczące obrazów, aby zapoznać się z obsługiwanymi formatami obrazów.

Adres URL obrazu

Utwórz obiekt identyfikatora URI dla obrazu, który chcesz przeanalizować.

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

Bufor obrazu

Alternatywnie można przekazać dane obrazu do zestawu SDK za pośrednictwem obiektu BinaryData . Na przykład odczyt z lokalnego pliku obrazu, który chcesz przeanalizować.

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

Wybieranie funkcji wizualnych

Interfejs API Analizy 4.0 zapewnia dostęp do wszystkich funkcji analizy obrazów usługi. Wybierz operacje do wykonania na podstawie własnego przypadku użycia. Zapoznaj się z omówieniem , aby zapoznać się z opisem każdej funkcji. W przykładzie w tej sekcji dodano wszystkie dostępne funkcje wizualne, ale w przypadku praktycznego użycia prawdopodobnie potrzebujesz mniej.

Ważne

Funkcje Captions wizualne i DenseCaptions są obsługiwane tylko w niektórych regionach świadczenia usługi Azure: zobacz Dostępność regionów

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

Wybieranie opcji analizy

Użyj obiektu ImageAnalysisOptions, aby określić różne opcje wywołania interfejsu API analizowania obrazów.

• Język: możesz określić język zwracanych danych. Język jest opcjonalny, a domyślnym językiem jest angielski. Zobacz Obsługa języka, aby zapoznać się z listą obsługiwanych kodów języków i obsługiwanymi funkcjami wizualnymi dla każdego języka.
• Podpisy neutralne pod względem płci: w przypadku wyodrębniania podpisów lub gęstych podpisów (przy użyciu funkcji VisualFeatures.Caption lub VisualFeatures.DenseCaptions), możesz poprosić o podpisy neutralne pod względem płci. Podpisy neutralne pod względem płci są opcjonalne, a domyślnie są podpisami płciowymi. Na przykład w języku angielskim, gdy wybierzesz podpisy neutralne pod względem płci, terminy takie jak kobieta lub mężczyzna są zastępowane osobą, a chłopiec lub dziewczyna są zastępowane dzieckiem.
• Współczynnik proporcji przycinania: współczynnik proporcji jest obliczany przez podzielenie docelowej szerokości przycinania według wysokości. Obsługiwane wartości to od 0,75 do 1,8 (włącznie). Ustawienie tej właściwości jest istotne tylko wtedy, gdy element VisualFeatures.SmartCrops został wybrany jako część listy funkcji wizualizacji. Jeśli wybierzesz pozycję VisualFeatures.SmartCrops , ale nie określisz współczynników proporcji, usługa zwróci jedną sugestię przycinania z współczynnikiem proporcji, który zobaczy, że pasuje. W tym przypadku współczynnik proporcji wynosi od 0,5 do 2,0 (włącznie).

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

Wywoływanie interfejsu API analizy

W tej sekcji pokazano, jak wykonać wywołanie analizy do usługi.

Wywołaj metodę Analyze w obiekcie ImageAnalysisClient , jak pokazano tutaj. Wywołanie jest synchroniczne i blokuje wykonywanie, dopóki usługa nie zwróci wyników lub wystąpi błąd. Alternatywnie można wywołać nieblokacyjną metodę AnalyzeAsync .

Użyj obiektów wejściowych utworzonych w powyższych sekcjach. Aby przeanalizować z buforu obrazu zamiast adresu URL, zastąp element imageURL w wywołaniu metody zmienną imageData .

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

Pobieranie wyników z usługi

Poniższy kod pokazuje, jak analizować wyniki różnych operacji analizy.

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

Rozwiązywanie problemów

Obsługa wyjątków

W przypadku interakcji z analizą obrazu przy użyciu zestawu .NET SDK każda odpowiedź z usługi, która nie ma 200 kodu stanu (powodzenia), powoduje zgłoszenie wyjątku. Jeśli na przykład spróbujesz przeanalizować obraz, który nie jest dostępny z powodu uszkodzonego adresu URL, 400 zostanie zwrócony stan wskazujący nieprawidłowe żądanie i zostanie zgłoszony odpowiedni wyjątek.

W poniższym fragmencie kodu błędy są obsługiwane bezpiecznie przez przechwycenie wyjątku i wyświetlenie dodatkowych informacji o błędzie.

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

Więcej informacji na temat włączania rejestrowania zestawu SDK można znaleźć tutaj.

Wymagania wstępne

W tym przewodniku założono, że wykonano kroki przewodnika Szybki start. Składają się na to następujące elementy:

• Utworzono zasób przetwarzanie obrazów i uzyskano klucz i adres URL punktu końcowego.
• Zainstalowano odpowiedni pakiet zestawu SDK i masz działającą aplikację Szybki start . Tę aplikację szybki start można zmodyfikować na podstawie przykładów kodu tutaj.

Tworzenie i uwierzytelnianie klienta

Aby uwierzytelnić się w usłudze Analizy obrazów, potrzebujesz klucza przetwarzanie obrazów i adresu URL punktu końcowego. W tym przewodniku założono, że zdefiniowano zmienne VISION_KEY środowiskowe oraz VISION_ENDPOINT klucz i punkt końcowy.

Ważne

Jeśli używasz klucza interfejsu API, zapisz go bezpiecznie w innym miejscu, na przykład w usłudze Azure Key Vault. Nie dołączaj klucza interfejsu API bezpośrednio do kodu i nigdy nie publikuj go publicznie.

Aby uzyskać więcej informacji na temat zabezpieczeń usług sztucznej inteligencji, zobacz Uwierzytelnianie żądań w usługach Azure AI.

Zacznij od utworzenia obiektu ImageAnalysisClient przy użyciu jednego z konstruktorów. Na przykład:

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

Wybierz obraz do przeanalizowania

Obraz można wybrać, podając publicznie dostępny adres URL obrazu lub odczytując dane obrazu do buforu wejściowego zestawu SDK. Zobacz Wymagania dotyczące obrazów, aby zapoznać się z obsługiwanymi formatami obrazów.

Adres URL obrazu

Możesz użyć następującego przykładowego adresu URL obrazu.

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

Bufor obrazu

Alternatywnie można przekazać obraz jako obiekt bajtów . Na przykład odczyt z lokalnego pliku obrazu, który chcesz przeanalizować.

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

Wybieranie funkcji wizualnych

Interfejs API Analizy 4.0 zapewnia dostęp do wszystkich funkcji analizy obrazów usługi. Wybierz operacje do wykonania na podstawie własnego przypadku użycia. Zapoznaj się z omówieniem , aby zapoznać się z opisem każdej funkcji. W przykładzie w tej sekcji dodano wszystkie dostępne funkcje wizualne, ale w przypadku praktycznego użycia prawdopodobnie potrzebujesz mniej.

Ważne

Funkcje wizualne Captions i DenseCaptions są obsługiwane tylko w niektórych regionach świadczenia usługi Azure. Zobacz Dostępność regionów.

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

Wywoływanie metody analyze_from_url z opcjami

Poniższy kod wywołuje metodę analyze_from_url na kliencie z funkcjami wybranymi powyżej i innymi opcjami zdefiniowanymi poniżej. Aby przeanalizować z buforu obrazu zamiast adresu URL, wywołaj metodę analizuj zamiast tego jako image_data=image_data pierwszy argument.

# Analyze all visual features from an image stream. This will be a synchronously (blocking) call.
result = client.analyze_from_url(
    image_url=image_url,
    visual_features=visual_features,
    smart_crops_aspect_ratios=[0.9, 1.33],
    gender_neutral_caption=True,
    language="en"
)

Wybieranie współczynników proporcji inteligentnego przycinania

Współczynnik proporcji jest obliczany przez podzielenie docelowej szerokości przycinania według wysokości. Obsługiwane wartości to od 0,75 do 1,8 (włącznie). Ustawienie tej właściwości jest istotne tylko wtedy, gdy VisualFeatures.SMART_CROPS została wybrana jako część listy funkcji wizualizacji. Jeśli wybierzesz VisualFeatures.SMART_CROPS , ale nie określisz współczynników proporcji, usługa zwróci jedną sugestię przycinania z współczynnikiem proporcji, który zobaczy, że pasuje. W tym przypadku współczynnik proporcji wynosi od 0,5 do 2,0 (włącznie).

Wybieranie podpisów neutralnych pod względem płci

Jeśli wyodrębniasz podpisy lub gęste podpisy (przy użyciu biblioteki VisualFeatures.CAPTION lub VisualFeatures.DENSE_CAPTIONS), możesz poprosić o podpisy neutralne pod względem płci. Podpisy neutralne pod względem płci są opcjonalne, a domyślnie są podpisami płciowymi. Na przykład w języku angielskim, gdy wybierzesz podpisy neutralne pod względem płci, terminy takie jak kobieta lub mężczyzna są zastępowane osobą, a chłopiec lub dziewczyna są zastępowane dzieckiem.

Określanie języków

Możesz określić język zwracanych danych. Język jest opcjonalny, a domyślnym językiem jest angielski. Zobacz Obsługa języka, aby zapoznać się z listą obsługiwanych kodów języków i obsługiwanymi funkcjami wizualnymi dla każdego języka.

Pobieranie wyników z usługi

Poniższy kod pokazuje, jak analizować wyniki z analyze_from_url lub analizować operacje.

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

Rozwiązywanie problemów

Wyjątki

Metody analyze zgłaszają wyjątek HttpResponseError dla nieudanych odpowiedzi kodu stanu HTTP z usługi. status_code Wyjątek to kod stanu odpowiedzi HTTP. error.message Wyjątek zawiera szczegółowy komunikat, który umożliwia diagnozowanie problemu:

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

Na przykład po podaniu nieprawidłowego klucza uwierzytelniania:

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.

Możesz też podać adres URL obrazu, który nie istnieje lub jest niedostępny:

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

Rejestrowanie

Klient używa standardowej biblioteki rejestrowania języka Python. Zestaw SDK rejestruje szczegóły żądania HTTP i odpowiedzi, które mogą być przydatne podczas rozwiązywania problemów. Aby zalogować się do pliku stdout, dodaj następujące elementy:

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)

Domyślnie dzienniki redaguje wartości ciągów zapytania adresu URL, wartości niektórych nagłówków żądań HTTP i odpowiedzi (w tym Ocp-Apim-Subscription-Key, które zawierają klucz) oraz ładunki żądania i odpowiedzi. Aby utworzyć dzienniki bez redaction, ustaw argument logging_enable = True metody podczas tworzenia ImageAnalysisClientmetody lub podczas wywoływania analyze na kliencie.

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

Dzienniki nie są generowane tylko dla poziomu logging.DEBUG dziennika. Pamiętaj, aby chronić żadne zredagowanych dzienników, aby uniknąć naruszenia zabezpieczeń. Aby uzyskać więcej informacji, zobacz Konfigurowanie rejestrowania w bibliotekach platformy Azure dla języka Python

Wymagania wstępne

W tym przewodniku założono, że wykonano kroki na stronie szybkiego startu. Składają się na to następujące elementy:

• Utworzono zasób przetwarzanie obrazów i uzyskano klucz i adres URL punktu końcowego.
• Masz zainstalowany odpowiedni pakiet ZESTAWU SDK i masz uruchomioną aplikację Szybki start . Tę aplikację szybki start można zmodyfikować na podstawie przykładów kodu tutaj.

Tworzenie i uwierzytelnianie klienta

Aby uwierzytelnić się w usłudze Image Analysis Service, potrzebujesz klucza przetwarzanie obrazów i adresu URL punktu końcowego. W tym przewodniku założono, że zdefiniowano zmienne VISION_KEY środowiskowe oraz VISION_ENDPOINT klucz i punkt końcowy.

Ważne

Jeśli używasz klucza interfejsu API, zapisz go bezpiecznie w innym miejscu, na przykład w usłudze Azure Key Vault. Nie dołączaj klucza interfejsu API bezpośrednio do kodu i nigdy nie publikuj go publicznie.

Aby uzyskać więcej informacji na temat zabezpieczeń usług sztucznej inteligencji, zobacz Uwierzytelnianie żądań w usługach Azure AI.

Zacznij od utworzenia obiektu ImageAnalysisClient . Na przykład:

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

Wybierz obraz do przeanalizowania

Obraz można wybrać, podając publicznie dostępny adres URL obrazu lub odczytując dane obrazu do buforu wejściowego zestawu SDK. Zobacz Wymagania dotyczące obrazów, aby zapoznać się z obsługiwanymi formatami obrazów.

Adres URL obrazu

imageUrl Utwórz ciąg do przechowywania publicznie dostępnego adresu URL obrazu, który chcesz przeanalizować.

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

Bufor obrazu

Alternatywnie można przekazać obraz jako bufor pamięci przy użyciu obiektu BinaryData . Na przykład odczyt z lokalnego pliku obrazu, który chcesz przeanalizować.

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

Wybieranie funkcji wizualnych

Interfejs API Analizy 4.0 zapewnia dostęp do wszystkich funkcji analizy obrazów usługi. Wybierz operacje do wykonania na podstawie własnego przypadku użycia. Zapoznaj się z omówieniem , aby zapoznać się z opisem każdej funkcji. W przykładzie w tej sekcji dodano wszystkie dostępne funkcje wizualne, ale w przypadku praktycznego użycia prawdopodobnie potrzebujesz mniej.

Ważne

Funkcje wizualne Captions i DenseCaptions są obsługiwane tylko w niektórych regionach świadczenia usługi Azure. Zobacz Dostępność regionów.

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

Wybieranie opcji analizy

Użyj obiektu ImageAnalysisOptions, aby określić różne opcje wywołania interfejsu API analizowania.

• Język: możesz określić język zwracanych danych. Język jest opcjonalny, a domyślnym językiem jest angielski. Zobacz Obsługa języka, aby zapoznać się z listą obsługiwanych kodów języków i obsługiwanymi funkcjami wizualnymi dla każdego języka.
• Podpisy neutralne pod względem płci: jeśli wyodrębniasz podpisy lub gęste podpisy (przy użyciu funkcji VisualFeatures.CAPTION lub VisualFeatures.DENSE_CAPTIONS), możesz poprosić o podpisy neutralne pod względem płci. Podpisy neutralne pod względem płci są opcjonalne, a domyślnie są podpisami płciowymi. Na przykład w języku angielskim, gdy wybierzesz podpisy neutralne pod względem płci, terminy takie jak kobieta lub mężczyzna są zastępowane osobą, a chłopiec lub dziewczyna są zastępowane dzieckiem.
• Współczynnik proporcji przycinania: współczynnik proporcji jest obliczany przez podzielenie docelowej szerokości przycinania według wysokości. Obsługiwane wartości to od 0,75 do 1,8 (włącznie). Ustawienie tej właściwości jest istotne tylko wtedy, gdy VisualFeatures.SMART_CROPS została wybrana jako część listy funkcji wizualizacji. Jeśli wybierzesz VisualFeatures.SMART_CROPS , ale nie określisz współczynników proporcji, usługa zwróci jedną sugestię przycinania z współczynnikiem proporcji, który zobaczy, że pasuje. W tym przypadku współczynnik proporcji wynosi od 0,5 do 2,0 (włącznie).

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

Wywoływanie metody analyzeFromUrl

W tej sekcji pokazano, jak wykonać wywołanie analizy do usługi.

Wywołaj metodę analyzeFromUrl w obiekcie ImageAnalysisClient , jak pokazano tutaj. Wywołanie jest synchroniczne i będzie blokowane, dopóki usługa nie zwróci wyników lub wystąpi błąd. Alternatywnie możesz użyć obiektu ImageAnalysisAsyncClient i wywołać jego metodę analyzeFromUrl , która nie blokuje.

Aby przeanalizować z buforu obrazu zamiast adresu URL, wywołaj metodę analyze i przekaż imageData jako pierwszy 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());
}

Pobieranie wyników z usługi

Poniższy kod pokazuje, jak analizować wyniki z elementu analyzeFromUrl i analizować operacje.

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

Rozwiązywanie problemów

Wyjątki

Metody analyze zgłaszają wyjątek HttpResponseException , gdy usługa odpowiada kodem stanu HTTP, który nie powiodł się. getResponse().getStatusCode() Wyjątek zawiera kod stanu odpowiedzi HTTP. getMessage() Wyjątek zawiera szczegółowy komunikat, który umożliwia diagnozowanie problemu:

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

Na przykład po podaniu nieprawidłowego klucza uwierzytelniania:

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

Możesz też podać obraz w formacie, który nie jest rozpoznawany:

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

Włączanie rejestrowania żądań HTTP/odpowiedzi

Podczas rozwiązywania problemów przydatne może być przejrzenie żądania HTTP wysłanego lub odebranie odpowiedzi za pośrednictwem przewodu do usługi Analizy obrazów. Biblioteka klienta Analizy obrazów obsługuje wbudowaną strukturę rejestrowania konsoli na potrzeby tymczasowego debugowania. Obsługuje również bardziej zaawansowane rejestrowanie przy użyciu interfejsu SLF4J . Aby uzyskać szczegółowe informacje, zobacz Używanie rejestrowania w zestawie Azure SDK dla języka Java.

W poniższych sekcjach omówiono włączanie rejestrowania konsoli przy użyciu wbudowanej struktury.

Ustawiając zmienne środowiskowe

Rejestrowanie konsoli żądania HTTP i odpowiedzi dla całej aplikacji można włączyć, ustawiając następujące dwie zmienne środowiskowe. Ta zmiana ma wpływ na każdego klienta platformy Azure, który obsługuje rejestrowanie żądań HTTP i odpowiedzi.

• Ustaw zmienną środowiskową AZURE_LOG_LEVEL na debug
• Ustaw zmienną środowiskową AZURE_HTTP_LOG_DETAIL_LEVEL na jedną z następujących wartości:

Wartość	Poziom rejestrowania
none	Rejestrowanie żądań HTTP/odpowiedzi jest wyłączone
basic	Rejestruje tylko adresy URL, metody HTTP i czas zakończenia żądania.
headers	Rejestruje wszystkie elementy w warstwie PODSTAWOWA oraz wszystkie nagłówki żądań i odpowiedzi.
body	Rejestruje wszystko w warstwie PODSTAWOWA oraz całą treść żądania i odpowiedzi.
body_and_headers	Rejestruje wszystko w nagłówkach i treści.

Ustawiając wartość httpLogOptions

Aby włączyć rejestrowanie konsoli żądania HTTP i odpowiedzi dla pojedynczego klienta

• Ustaw zmienną środowiskową AZURE_LOG_LEVEL na debug
• Dodaj wywołanie metody podczas httpLogOptions kompilowania elementu ImageAnalysisClient:

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

Wyliczenie HttpLogDetailLevel definiuje obsługiwane poziomy rejestrowania.

Domyślnie podczas rejestrowania niektóre wartości parametrów nagłówka HTTP i zapytania są redacted. Można zastąpić to ustawienie domyślne, określając, które nagłówki i parametry zapytania są bezpieczne do rejestrowania:

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

Aby na przykład uzyskać pełny niezredagowany dziennik żądania HTTP, zastosuj następujące elementy:

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

Dodaj więcej do powyższych, aby uzyskać niezredagowaną odpowiedź HTTP. Po udostępnieniu niezredagowanego dziennika upewnij się, że nie zawiera on wpisów tajnych, takich jak klucz subskrypcji.

Wymagania wstępne

W tym przewodniku założono, że wykonano kroki opisane w przewodniku Szybki start. Składają się na to następujące elementy:

• Utworzono zasób przetwarzanie obrazów i uzyskano klucz i adres URL punktu końcowego.
• Masz zainstalowany odpowiedni pakiet ZESTAWU SDK i masz uruchomioną aplikację Szybki start . Tę aplikację szybki start można zmodyfikować na podstawie przykładów kodu tutaj.

Tworzenie i uwierzytelnianie klienta

Aby uwierzytelnić się w usłudze Analizy obrazów, potrzebujesz klucza przetwarzanie obrazów i adresu URL punktu końcowego. W tym przewodniku założono, że zdefiniowano zmienne VISION_KEY środowiskowe oraz VISION_ENDPOINT klucz i punkt końcowy.

Ważne

Jeśli używasz klucza interfejsu API, zapisz go bezpiecznie w innym miejscu, na przykład w usłudze Azure Key Vault. Nie dołączaj klucza interfejsu API bezpośrednio do kodu i nigdy nie publikuj go publicznie.

Aby uzyskać więcej informacji na temat zabezpieczeń usług sztucznej inteligencji, zobacz Uwierzytelnianie żądań w usługach Azure AI.

Zacznij od utworzenia obiektu ImageAnalysisClient . Na przykład:

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

Wybierz obraz do przeanalizowania

Obraz można wybrać, podając publicznie dostępny adres URL obrazu lub odczytując dane obrazu do buforu wejściowego zestawu SDK. Zobacz Wymagania dotyczące obrazów, aby zapoznać się z obsługiwanymi formatami obrazów.

Adres URL obrazu

Możesz użyć następującego przykładowego adresu URL obrazu.

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

Bufor obrazu

Alternatywnie możesz przekazać obraz jako tablicę danych. Na przykład odczyt z lokalnego pliku obrazu, który chcesz przeanalizować.

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

Wybieranie funkcji wizualnych

Interfejs API Analizy 4.0 zapewnia dostęp do wszystkich funkcji analizy obrazów usługi. Wybierz operacje do wykonania na podstawie własnego przypadku użycia. Zobacz Omówienie, aby zapoznać się z opisem każdej funkcji. W przykładzie w tej sekcji dodano wszystkie dostępne funkcje wizualne, ale w przypadku praktycznego użycia prawdopodobnie potrzebujesz mniej.

Ważne

Funkcje wizualne Captions i DenseCaptions są obsługiwane tylko w niektórych regionach świadczenia usługi Azure. Zobacz: .

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

Wywoływanie interfejsu API analizy przy użyciu opcji

Poniższy kod wywołuje interfejs API analizowania obrazu z wybranymi powyżej funkcjami i innymi opcjami zdefiniowanymi w następnej kolejności. Aby przeanalizować z buforu obrazu zamiast adresu URL, zastąp element imageURL w wywołaniu imageDatametody .

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

Wybieranie współczynników proporcji inteligentnego przycinania

Współczynnik proporcji jest obliczany przez podzielenie docelowej szerokości przycinania według wysokości. Obsługiwane wartości to od 0,75 do 1,8 (włącznie). Ustawienie tej właściwości jest istotne tylko wtedy, gdy element VisualFeatures.SmartCrops został wybrany jako część listy funkcji wizualizacji. Jeśli wybierzesz pozycję VisualFeatures.SmartCrops , ale nie określisz współczynników proporcji, usługa zwróci jedną sugestię przycinania z współczynnikiem proporcji, który zobaczy, że pasuje. W tym przypadku współczynnik proporcji wynosi od 0,5 do 2,0 (włącznie).

Wybieranie podpisów neutralnych pod względem płci

Jeśli wyodrębniasz podpisy lub transkrypcje gęste (przy użyciu funkcji VisualFeatures.Caption lub VisualFeatures.DenseCaptions), możesz poprosić o podpisy neutralne pod względem płci. Podpisy neutralne pod względem płci są opcjonalne, a domyślnie są podpisami płciowymi. Na przykład w języku angielskim, gdy wybierzesz podpisy neutralne pod względem płci, terminy takie jak kobieta lub mężczyzna są zastępowane osobą, a chłopiec lub dziewczyna są zastępowane dzieckiem.

Określanie języków

Możesz określić język zwracanych danych. Język jest opcjonalny, a domyślnym językiem jest angielski. Zobacz Obsługa języka, aby zapoznać się z listą obsługiwanych kodów języków i obsługiwanymi funkcjami wizualnymi dla każdego języka.

Pobieranie wyników z usługi

Poniższy kod pokazuje, jak analizować wyniki różnych operacji analizy .

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

Rozwiązywanie problemów

Rejestrowanie

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań HTTP i odpowiedzi, ustaw zmienną AZURE_LOG_LEVEL środowiskową na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując polecenie setLogLevel w pliku @azure/logger:

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

setLogLevel("info");

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietów @azure/rejestratora.

Wymagania wstępne

W tym przewodniku założono, że pomyślnie wykonano kroki wymienione na stronie szybkiego startu. Składają się na to następujące elementy:

• Utworzono zasób przetwarzanie obrazów i uzyskano klucz i adres URL punktu końcowego.
• Pomyślnie wykonano curl.exe wywołanie usługi (lub użyto alternatywnego narzędzia). Wywołanie można curl.exe zmodyfikować na podstawie przykładów w tym miejscu.

Uwierzytelnianie w usłudze

Aby uwierzytelnić się w usłudze Analizy obrazów, potrzebujesz klucza przetwarzanie obrazów i adresu URL punktu końcowego.

Ważne

Jeśli używasz klucza interfejsu API, zapisz go bezpiecznie w innym miejscu, na przykład w usłudze Azure Key Vault. Nie dołączaj klucza interfejsu API bezpośrednio do kodu i nigdy nie publikuj go publicznie.

Aby uzyskać więcej informacji na temat zabezpieczeń usług sztucznej inteligencji, zobacz Uwierzytelnianie żądań w usługach Azure AI.

W przykładzie zestawu SDK przyjęto założenie, że zdefiniowano zmienne VISION_KEY środowiskowe oraz VISION_ENDPOINT klucz i punkt końcowy.

Uwierzytelnianie odbywa się przez dodanie nagłówka żądania HTTP Ocp-Apim-Subscription-Key i ustawienie go na klucz przetwarzania obrazów. Wywołanie jest wykonywane pod adresem URL <endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01, gdzie <endpoint> jest unikatowym adresem URL punktu końcowego przetwarzania obrazów. Ciągi zapytania są dodawane na podstawie opcji analizy.

Wybierz obraz do przeanalizowania

Kod w tym przewodniku używa zdalnych obrazów, do których odwołuje się adres URL. Możesz chcieć samodzielnie wypróbować różne obrazy, aby zobaczyć pełną możliwość funkcji analizy obrazów.

Adres URL obrazu

Podczas analizowania obrazu zdalnego należy określić adres URL obrazu, formatując treść żądania w następujący sposób: {"url":"https://learn.microsoft.com/azure/cognitive-services/computer-vision/images/windows-kitchen.jpg"}. Typ zawartości powinien mieć wartość application/json.

Image file

Aby przeanalizować obraz lokalny, należy umieścić dane obrazu binarnego w treści żądania HTTP. Typ zawartości powinien mieć wartość application/octet-stream lub multipart/form-data.

Wybieranie opcji analizy

Wybieranie funkcji wizualnych podczas korzystania z modelu standardowego

Interfejs API Analizy 4.0 zapewnia dostęp do wszystkich funkcji analizy obrazów usługi. Wybierz operacje do wykonania na podstawie własnego przypadku użycia. Zapoznaj się z omówieniem , aby zapoznać się z opisem każdej funkcji. W przykładzie w tej sekcji dodano wszystkie dostępne funkcje wizualne, ale w przypadku praktycznego użycia prawdopodobnie potrzebujesz mniej.

Funkcje wizualne "Captions" i "DenseCaptions" są obsługiwane tylko w niektórych regionach świadczenia usługi Azure: zobacz Dostępność regionów.

Uwaga

Interfejs API REST używa terminów Inteligentne uprawy i Współczynniki proporcji inteligentnych upraw. Zestaw SDK używa terminów Sugestie przycinania i Współczynniki proporcji przycinania. Oba odnoszą się do tej samej operacji usługi. Podobnie interfejs API REST używa terminu Odczyt do wykrywania tekstu na obrazie przy użyciu optycznego rozpoznawania znaków (OCR), natomiast zestaw SDK używa terminu Tekst dla tej samej operacji.

Możesz określić, które funkcje mają być używane, ustawiając parametry zapytania adresu URL interfejsu API Analizy 4.0. Parametr może mieć wiele wartości rozdzielonych przecinkami.

Parametr adresu URL	Wartość	Opis
features	read	Odczytuje widoczny tekst na obrazie i wyprowadza go jako dane JSON ze strukturą.
features	caption	Opisuje zawartość obrazu z pełnym zdaniem w obsługiwanych językach.
features	denseCaptions	Generuje szczegółowe podpisy dla maksymalnie 10 widocznych regionów obrazów.
features	smartCrops	Znajduje współrzędne prostokąta, które przycinają obraz do żądanego współczynnika proporcji, zachowując jednocześnie obszar zainteresowania.
features	objects	Wykrywa różne obiekty na obrazie, w tym przybliżoną lokalizację. Argument Objects jest dostępny tylko w języku angielskim.
features	tags	Taguje obraz ze szczegółową listą słów związanych z zawartością obrazu.
features	people	Wykrywa osoby pojawiające się na obrazach, w tym przybliżone lokalizacje.

Wypełniony adres URL może wyglądać następująco:

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

Ustawianie nazwy modelu podczas korzystania z modelu niestandardowego

Możesz również przeprowadzić analizę obrazów za pomocą niestandardowego wytrenowanego modelu. Aby utworzyć i wytrenować model, zobacz Tworzenie niestandardowego modelu analizy obrazów. Po wytrenowanym modelu wystarczy nazwa modelu. Nie trzeba określać funkcji wizualnych, jeśli używasz modelu niestandardowego.

Aby użyć modelu niestandardowego, nie używaj parametru zapytania funkcji. Zamiast tego ustaw model-name parametr na nazwę modelu, jak pokazano tutaj. Zastąp MyCustomModelName ciąg nazwą modelu niestandardowego.

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

Określanie języków

Możesz określić język zwracanych danych. Język jest opcjonalny, a domyślnym językiem jest angielski. Zobacz Obsługa języka, aby zapoznać się z listą obsługiwanych kodów języków i obsługiwanymi funkcjami wizualnymi dla każdego języka.

Opcja języka ma zastosowanie tylko wtedy, gdy używasz modelu standardowego.

Następujący parametr zapytania adresu URL określa język. Domyślna wartość to en.

Parametr adresu URL	Wartość	Opis
language	en	Angielski
language	es	Hiszpański
language	ja	japoński
language	pt	Portugalski
language	zh	Chiński (uproszczony)

Wypełniony adres URL może wyglądać następująco:

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

Wybieranie podpisów neutralnych pod względem płci

Jeśli wyodrębniasz podpisy lub gęste podpisy, możesz poprosić o podpisy neutralne pod względem płci. Podpisy neutralne pod względem płci są opcjonalne, a domyślnie są podpisami płciowymi. Na przykład w języku angielskim, gdy wybierzesz podpisy neutralne pod względem płci, terminy takie jak kobieta lub mężczyzna są zastępowane osobą, a chłopiec lub dziewczyna są zastępowane dzieckiem.

Opcja podpisu neutralnego pod względem płci ma zastosowanie tylko wtedy, gdy używasz modelu standardowego.

Dodaj opcjonalny ciąg gender-neutral-caption zapytania z wartościami true lub false (wartość domyślna).

Wypełniony adres URL może wyglądać następująco:

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

Wybieranie współczynników proporcji inteligentnego przycinania

Współczynnik proporcji jest obliczany przez podzielenie docelowej szerokości przycinania według wysokości. Obsługiwane wartości to od 0,75 do 1,8 (włącznie). Ustawienie tej właściwości jest istotne tylko wtedy, gdy element VisualFeatures.SmartCrops został wybrany jako część listy funkcji wizualizacji. Jeśli wybierzesz pozycję VisualFeatures.SmartCrops , ale nie określisz współczynników proporcji, usługa zwróci jedną sugestię przycinania z współczynnikiem proporcji, który zobaczy, że pasuje. W tym przypadku współczynnik proporcji wynosi od 0,5 do 2,0 (włącznie).

Inteligentne przycinanie rations proporcji ma zastosowanie tylko wtedy, gdy używasz modelu standardowego.

Dodaj opcjonalny ciąg smartcrops-aspect-ratioszapytania z co najmniej jednym współczynnikiem proporcji oddzielonym przecinkiem.

Wypełniony adres URL może wyglądać następująco:

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

Pobieranie wyników z usługi

Uzyskiwanie wyników przy użyciu modelu standardowego

W tej sekcji pokazano, jak wykonać wywołanie analizy do usługi przy użyciu modelu standardowego i uzyskać wyniki.

Usługa zwraca 200 odpowiedź HTTP, a treść zawiera zwracane dane w postaci ciągu JSON. Poniższy tekst jest przykładem odpowiedzi JSON.

{
    "modelVersion": "string",
    "captionResult": {
      "text": "string",
      "confidence": 0.0
    },
    "denseCaptionsResult": {
      "values": [
        {
          "text": "string",
          "confidence": 0.0,
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          }
        }
      ]
    },
    "metadata": {
      "width": 0,
      "height": 0
    },
    "tagsResult": {
      "values": [
        {
          "name": "string",
          "confidence": 0.0
        }
      ]
    },
    "objectsResult": {
      "values": [
        {
          "id": "string",
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          },
          "tags": [
            {
              "name": "string",
              "confidence": 0.0
            }
          ]
        }
      ]
    },
    "readResult": {
      "blocks": [
        {
          "lines": [
            {
              "text": "string",
              "boundingPolygon": [
                {
                  "x": 0,
                  "y": 0
                },
                {
                    "x": 0,
                    "y": 0
                },
                {
                    "x": 0,
                    "y": 0
                },
                {
                    "x": 0,
                    "y": 0
                }
              ],
              "words": [
                {
                  "text": "string",
                  "boundingPolygon": [
                    {
                        "x": 0,
                        "y": 0
                    },
                    {
                        "x": 0,
                        "y": 0
                    },
                    {
                        "x": 0,
                        "y": 0
                    },
                    {
                        "x": 0,
                        "y": 0
                    }
                  ],
                  "confidence": 0.0
                }
              ]
            }
          ]
        }
      ]
    },
    "smartCropsResult": {
      "values": [
        {
          "aspectRatio": 0.0,
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          }
        }
      ]
    },
    "peopleResult": {
      "values": [
        {
          "boundingBox": {
            "x": 0,
            "y": 0,
            "w": 0,
            "h": 0
          },
          "confidence": 0.0
        }
      ]
    }
  }

Kody błędów

Po błędzie odpowiedź usługi Image Analysis Service zawiera ładunek JSON zawierający kod błędu i komunikat o błędzie. Może również zawierać inne szczegóły w postaci i wewnętrznego kodu błędu i komunikatu. Na przykład:

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

Poniżej znajduje się lista typowych błędów i ich przyczyn. Elementy listy są prezentowane w następującym formacie:

• Kod odpowiedzi HTTP
  • Kod błędu i komunikat w odpowiedzi JSON
    • [Opcjonalnie] Wewnętrzny kod błędu i komunikat w odpowiedzi JSON

Lista typowych błędów:

• 400 Bad Request
  • InvalidRequest - Image URL is badly formatted or not accessible. Upewnij się, że adres URL obrazu jest prawidłowy i dostępny publicznie.
  • InvalidRequest - The image size is not allowed to be zero or larger than 20971520 bytes. Zmniejsz rozmiar obrazu, kompresując go i/lub zmieniając rozmiar i ponownie przesyłając żądanie.
  • InvalidRequest - The feature 'Caption' is not supported in this region. Ta funkcja jest obsługiwana tylko w określonych regionach świadczenia usługi Azure. Zobacz Wymagania wstępne szybkiego startu, aby zapoznać się z listą obsługiwanych regionów świadczenia usługi Azure.
  • InvalidRequest - The provided image content type ... is not supported. Typ zawartości nagłówka HTTP w żądaniu nie jest dozwolonym typem:
    • W przypadku adresu URL obrazu typ zawartości powinien mieć wartość application/json
    • W przypadku danych obrazu binarnego typ zawartości powinien mieć wartość application/octet-stream lub multipart/form-data
  • InvalidRequest - Either 'features' or 'model-name' needs to be specified in the query parameter.
  • InvalidRequest - Image format is not valid
    • InvalidImageFormat - Image format is not valid. Zobacz sekcję Wymagania dotyczące obrazów, aby zapoznać się z obsługiwanymi formatami obrazów.
  • InvalidRequest - Analyze query is invalid
    • NotSupportedVisualFeature - Specified feature type is not valid. Upewnij się, że ciąg zapytania funkcji ma prawidłową wartość.
    • NotSupportedLanguage - The input language is not supported. Upewnij się, że ciąg zapytania języka ma prawidłową wartość dla wybranej funkcji wizualizacji na podstawie poniższej tabeli.
    • 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. Usługa nie może odnaleźć modelu niestandardowego na podstawie nazwy podanej model-name przez ciąg zapytania.

Następne kroki

• Zapoznaj się z artykułami dotyczącymi pojęć, aby dowiedzieć się więcej o każdej funkcji.
• Zapoznaj się z przykładami kodu zestawu SDK w witrynie GitHub:
  • C#
  • Python
  • Java
  • JavaScript
• Zobacz dokumentację interfejsu API REST, aby dowiedzieć się więcej na temat funkcji interfejsu API.