Share via

استدعاء Image Analysis 4.0 Analyze API

  • مقالة

توضح هذه المقالة كيفية استدعاء واجهة برمجة تطبيقات تحليل الصور 4.0 لإرجاع معلومات حول الميزات المرئية للصورة. كما يوضح لك كيفية تحليل المعلومات التي تم إرجاعها.

المتطلبات الأساسية

يفترض هذا الدليل أنك اتبعت الخطوات المذكورة في صفحة التشغيل السريع . يعني ذلك:

  • لقد أنشأت مورد Computer Vision وحصلت على عنوان URL للمفتاح ونقطة النهاية.
  • لديك حزمة SDK المناسبة مثبتة ولديك تطبيق التشغيل السريع . يمكنك تعديل تطبيق التشغيل السريع هذا استنادا إلى أمثلة التعليمات البرمجية هنا.

إنشاء العميل ومصادقته

للمصادقة مقابل خدمة تحليل الصور، تحتاج إلى مفتاح Computer Vision وعنوان URL لنقطة النهاية. يفترض هذا الدليل أنك قمت بتعريف متغيرات VISION_KEY البيئة ومع VISION_ENDPOINT المفتاح ونقطة النهاية.

تلميح

لا تقم بتضمين المفتاح مباشرة في التعليمات البرمجية الخاصة بك، ولا تنشره بشكل عام. راجع مقالة أمان خدمات Azure الذكاء الاصطناعي لمزيد من خيارات المصادقة مثل Azure Key Vault.

ابدأ بإنشاء كائن ImageAnalysisClient . على سبيل المثال:

string endpoint = Environment.GetEnvironmentVariable("VISION_ENDPOINT");
string key = Environment.GetEnvironmentVariable("VISION_KEY");

// Create an Image Analysis client.
ImageAnalysisClient client = new ImageAnalysisClient(
    new Uri(endpoint),
    new AzureKeyCredential(key));

حدد الصورة لتحليلها

يمكنك تحديد صورة عن طريق توفير عنوان URL للصورة يمكن الوصول إليه بشكل عام، أو عن طريق تمرير البيانات الثنائية إلى SDK. راجع متطلبات الصورة لتنسيقات الصور المدعومة.

عنوان URL للصورة

إنشاء كائن Uri للصورة التي تريد تحليلها.

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

المخزن المؤقت للصورة

بدلا من ذلك، يمكنك تمرير بيانات الصورة إلى SDK من خلال كائن BinaryData . على سبيل المثال، اقرأ من ملف صورة محلي تريد تحليله.

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

تحديد الخصائص المرئية

تمنحك واجهة برمجة تطبيقات Analysis 4.0 إمكانية الوصول إلى جميع ميزات تحليل الصور الخاصة بالخدمة. اختر العمليات التي تريد القيام بها بناءً على حالة الاستخدام الخاصة بك. راجع نظرة عامة للحصول على وصف لكل ميزة. يضيف المثال في هذا القسم جميع الميزات المرئية المتوفرة، ولكن للاستخدام العملي، من المحتمل أن تحتاج إلى عدد أقل.

هام

الميزات المرئية Captions ويتم DenseCaptions دعمها فقط في مناطق Azure التالية: شرق الولايات المتحدة وفرنسا الوسطى وكوريا الوسطى وشمال أوروبا وجنوب شرق آسيا وغرب أوروبا وغرب الولايات المتحدة.

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

تحديد خيارات التحليل

استخدم كائن ImageAnalysisOptions لتحديد خيارات مختلفة لاستدعاء تحليل واجهة برمجة التطبيقات.

  • اللغة: يمكنك تحديد لغة البيانات التي تم إرجاعها. اللغة اختيارية، حيث تكون اللغة الافتراضية هي الإنجليزية. راجع دعم اللغة للحصول على قائمة رموز اللغات المدعومة والميزات المرئية المدعومة لكل لغة.
  • التسميات التوضيحية المحايدة للجنس: إذا كنت تستخرج تسميات توضيحية أو تسميات توضيحية كثيفة (باستخدام VisualFeatures.Caption أو VisualFeatures.DenseCaptions)، يمكنك طلب تسميات توضيحية محايدة للجنس. تعتبر التسميات التوضيحية المحايدة للجنسين اختيارية، حيث يكون الافتراضي هو التسميات التوضيحية الجنسانية. على سبيل المثال، في اللغة الإنجليزية، عند تحديد تسميات توضيحية محايدة جنسانيا، يتم استبدال مصطلحات مثل المرأة أو الرجل بشخص، ويتم استبدال الصبي أو الفتاة بطفل.
  • نسبة العرض إلى الارتفاع للقص: يتم حساب نسبة العرض إلى الارتفاع عن طريق تقسيم عرض القص المستهدف على الارتفاع. تتراوح القيم المدعومة من 0.75 إلى 1.8 (شاملة). يكون تعيين هذه الخاصية مناسبا فقط عند تحديد VisualFeatures.SmartCrops كجزء من قائمة الميزات المرئية. إذا حددت VisualFeatures.SmartCrops ولكنك لم تحدد نسب العرض إلى الارتفاع، فترجع الخدمة اقتراح قص واحدا بنسبة عرض إلى ارتفاع تراه مناسبا. في هذه الحالة، تتراوح نسبة العرض إلى الارتفاع بين 0.5 و2.0 (شاملة).
ImageAnalysisOptions options = new ImageAnalysisOptions { 
    GenderNeutralCaption = true,
    Language = "en",
    SmartCropsAspectRatios = new float[] { 0.9F, 1.33F }};

استدعاء Analyze API

يوضح لك هذا القسم كيفية إجراء استدعاء تحليل للخدمة.

استدعاء الأسلوب Analyze على كائن ImageAnalysisClient، كما هو موضح هنا. الاستدعاء متزامن، وسيتم حظره حتى تقوم الخدمة بإرجاع النتائج أو حدوث خطأ. بدلا من ذلك، يمكنك استدعاء أسلوب AnalyzeAsync غير المحظور.

استخدم كائنات الإدخال التي تم إنشاؤها في الأقسام أعلاه. للتحليل من مخزن مؤقت للصورة بدلا من عنوان URL، استبدل imageURL في استدعاء الأسلوب بالمتغير imageData .

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

الحصول على نتائج من الخدمة

توضح لك التعليمات البرمجية التالية كيفية تحليل نتائج عمليات التحليل المختلفة.

Console.WriteLine("Image analysis results:");

// Print caption results to the console
Console.WriteLine(" Caption:");
Console.WriteLine($"   '{result.Caption.Text}', Confidence {result.Caption.Confidence:F4}");

// Print dense caption results to the console
Console.WriteLine(" Dense Captions:");
foreach (DenseCaption denseCaption in result.DenseCaptions.Values)
{
    Console.WriteLine($"   '{denseCaption.Text}', Confidence {denseCaption.Confidence:F4}, Bounding box {denseCaption.BoundingBox}");
}

// Print object detection results to the console
Console.WriteLine(" Objects:");
foreach (DetectedObject detectedObject in result.Objects.Values)
{
    Console.WriteLine($"   '{detectedObject.Tags.First().Name}', Bounding box {detectedObject.BoundingBox.ToString()}");
}

// Print text (OCR) analysis results to the console
Console.WriteLine(" Read:");
foreach (DetectedTextBlock block in result.Read.Blocks)
    foreach (DetectedTextLine line in block.Lines)
    {
        Console.WriteLine($"   Line: '{line.Text}', Bounding Polygon: [{string.Join(" ", line.BoundingPolygon)}]");
        foreach (DetectedTextWord word in line.Words)
        {
            Console.WriteLine($"     Word: '{word.Text}', Confidence {word.Confidence.ToString("#.####")}, Bounding Polygon: [{string.Join(" ", word.BoundingPolygon)}]");
        }
    }

// Print tags results to the console
Console.WriteLine(" Tags:");
foreach (DetectedTag tag in result.Tags.Values)
{
    Console.WriteLine($"   '{tag.Name}', Confidence {tag.Confidence:F4}");
}

// Print people detection results to the console
Console.WriteLine(" People:");
foreach (DetectedPerson person in result.People.Values)
{
    Console.WriteLine($"   Person: Bounding box {person.BoundingBox.ToString()}, Confidence {person.Confidence:F4}");
}

// Print smart-crops analysis results to the console
Console.WriteLine(" SmartCrops:");
foreach (CropRegion cropRegion in result.SmartCrops.Values)
{
    Console.WriteLine($"   Aspect ratio: {cropRegion.AspectRatio}, Bounding box: {cropRegion.BoundingBox}");
}

// Print metadata
Console.WriteLine(" Metadata:");
Console.WriteLine($"   Model: {result.ModelVersion}");
Console.WriteLine($"   Image width: {result.Metadata.Width}");
Console.WriteLine($"   Image hight: {result.Metadata.Height}");

استكشاف الأخطاء وإصلاحها

معالجة الاستثناء

عند التفاعل مع تحليل الصور باستخدام .NET SDK، ينتج عن أي استجابة من الخدمة التي لا تحتوي 200 على رمز حالة (نجاح) استثناء يتم طرحه. على سبيل المثال، إذا حاولت تحليل صورة لا يمكن الوصول إليها بسبب عنوان URL مقطوع، 400 يتم إرجاع الحالة، مما يشير إلى طلب غير صحيح، ويتم طرح استثناء مطابق.

في القصاصة البرمجية التالية، تتم معالجة الأخطاء بأمان عن طريق التقاط الاستثناء وعرض معلومات إضافية حول الخطأ.

var imageUrl = new Uri("https://some-host-name.com/non-existing-image.jpg");

try
{
    var result = client.Analyze(imageUrl, VisualFeatures.Caption);
}
catch (RequestFailedException e)
{
    if (e.Status != 200)
    {
        Console.WriteLine("Error analyzing image.");
        Console.WriteLine($"HTTP status code {e.Status}: {e.Message}");
    }
    else
    {
        throw;
    }
}

يمكنك معرفة المزيد حول كيفية تمكين تسجيل SDK هنا.

المتطلبات الأساسية

يفترض هذا الدليل أنك اتبعت الخطوات المذكورة في التشغيل السريع. يعني ذلك:

  • لقد أنشأت مورد Computer Vision وحصلت على عنوان URL للمفتاح ونقطة النهاية.
  • لديك حزمة SDK المناسبة مثبتة ولديك تطبيق التشغيل السريع . يمكنك تعديل تطبيق التشغيل السريع هذا استنادا إلى أمثلة التعليمات البرمجية هنا.

إنشاء العميل ومصادقته

للمصادقة مقابل خدمة تحليل الصور، تحتاج إلى مفتاح Computer Vision وعنوان URL لنقطة النهاية. يفترض هذا الدليل أنك قمت بتعريف متغيرات VISION_KEY البيئة ومع VISION_ENDPOINT المفتاح ونقطة النهاية.

تلميح

لا تقم بتضمين المفتاح مباشرة في التعليمات البرمجية الخاصة بك، ولا تنشره بشكل عام. راجع مقالة أمان خدمات Azure الذكاء الاصطناعي لمزيد من خيارات المصادقة مثل Azure Key Vault.

ابدأ بإنشاء كائن ImageAnalysisClient باستخدام أحد الدالات الإنشائية. على سبيل المثال:

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

حدد الصورة لتحليلها

يمكنك تحديد صورة عن طريق توفير عنوان URL للصورة يمكن الوصول إليه بشكل عام، أو عن طريق قراءة بيانات الصورة في المخزن المؤقت لإدخال SDK. راجع متطلبات الصورة لتنسيقات الصور المدعومة.

عنوان URL للصورة

يمكنك استخدام نموذج URL التالي للصورة.

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

المخزن المؤقت للصورة

بدلا من ذلك، يمكنك تمرير في الصورة كعنصر بايت . على سبيل المثال، اقرأ من ملف صورة محلي تريد تحليله.

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

تحديد الخصائص المرئية

تمنحك واجهة برمجة تطبيقات Analysis 4.0 إمكانية الوصول إلى جميع ميزات تحليل الصور الخاصة بالخدمة. اختر العمليات التي تريد القيام بها بناءً على حالة الاستخدام الخاصة بك. راجع نظرة عامة للحصول على وصف لكل ميزة. يضيف المثال في هذا القسم جميع الميزات المرئية المتوفرة، ولكن للاستخدام العملي، من المحتمل أن تحتاج إلى عدد أقل.

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

استدعاء أسلوب analyze_from_url مع الخيارات

تستدعي التعليمات البرمجية التالية أسلوب analyze_from_url على العميل بالميزات التي حددتها أعلاه وخيارات إضافية، محددة أدناه. للتحليل من مخزن مؤقت للصور بدلا من عنوان URL، قم باستدعاء الأسلوب analyze بدلا من ذلك، باستخدام image_data=image_data كوسيطة أولى.

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

تحديد نسب العرض إلى الارتفاع في الاقتصاص الذكي

يتم حساب نسبة العرض إلى الارتفاع عن طريق تقسيم عرض الاقتصاص المستهدف على الارتفاع. تتراوح القيم المدعومة من 0.75 إلى 1.8 (شاملة). يكون تعيين هذه الخاصية مناسبا فقط عند تحديد VisualFeatures.SMART_CROPS كجزء من قائمة الميزات المرئية. إذا حددت VisualFeatures.SMART_CROPS ولكنك لم تحدد نسب العرض إلى الارتفاع، فترجع الخدمة اقتراح قص واحدا بنسبة عرض إلى ارتفاع تراه مناسبا. في هذه الحالة، تتراوح نسبة العرض إلى الارتفاع بين 0.5 و2.0 (شاملة).

تحديد التسميات التوضيحية المحايدة للجنس

إذا كنت تقوم باستخراج التسميات التوضيحية أو التسميات التوضيحية الكثيفة (باستخدام VisualFeatures.CAPTION أو VisualFeatures.DENSE_CAPTIONS)، يمكنك طلب تسميات توضيحية محايدة للجنس. تعتبر التسميات التوضيحية المحايدة للجنسين اختيارية، حيث يكون الافتراضي هو التسميات التوضيحية الجنسانية. على سبيل المثال، في اللغة الإنجليزية، عند تحديد تسميات توضيحية محايدة جنسانيا، يتم استبدال مصطلحات مثل المرأة أو الرجل بشخص، ويتم استبدال الصبي أو الفتاة بطفل.

تحديد اللغات

يمكنك تحديد لغة البيانات التي تم إرجاعها. اللغة اختيارية، حيث تكون اللغة الافتراضية هي الإنجليزية. راجع دعم اللغة للحصول على قائمة رموز اللغات المدعومة والميزات المرئية المدعومة لكل لغة.

الحصول على نتائج من الخدمة

توضح لك التعليمات البرمجية التالية كيفية تحليل النتائج من analyze_from_url أو تحليل العمليات.

# Print all analysis results to the console
print("Image analysis results:")

if result.caption is not None:
    print(" Caption:")
    print(f"   '{result.caption.text}', Confidence {result.caption.confidence:.4f}")

if result.dense_captions is not None:
    print(" Dense Captions:")
    for caption in result.dense_captions.list:
        print(f"   '{caption.text}', {caption.bounding_box}, Confidence: {caption.confidence:.4f}")

if result.read is not None:
    print(" Read:")
    for line in result.read.blocks[0].lines:
        print(f"   Line: '{line.text}', Bounding box {line.bounding_polygon}")
        for word in line.words:
            print(f"     Word: '{word.text}', Bounding polygon {word.bounding_polygon}, Confidence {word.confidence:.4f}")

if result.tags is not None:
    print(" Tags:")
    for tag in result.tags.list:
        print(f"   '{tag.name}', Confidence {tag.confidence:.4f}")

if result.objects is not None:
    print(" Objects:")
    for object in result.objects.list:
        print(f"   '{object.tags[0].name}', {object.bounding_box}, Confidence: {object.tags[0].confidence:.4f}")

if result.people is not None:
    print(" People:")
    for person in result.people.list:
        print(f"   {person.bounding_box}, Confidence {person.confidence:.4f}")

if result.smart_crops is not None:
    print(" Smart Cropping:")
    for smart_crop in result.smart_crops.list:
        print(f"   Aspect ratio {smart_crop.aspect_ratio}: Smart crop {smart_crop.bounding_box}")

print(f" Image height: {result.metadata.height}")
print(f" Image width: {result.metadata.width}")
print(f" Model version: {result.model_version}")

استكشاف الأخطاء وإصلاحها

استثناءات

ترفع الأساليب analyze استثناء HttpResponseError لاستجابة رمز حالة HTTP غير ناجحة من الخدمة. الاستثناء status_code هو رمز حالة استجابة HTTP. يحتوي الاستثناء error.message على رسالة مفصلة تسمح لك بتشخيص المشكلة:

try:
    result = client.analyze( ... )
except HttpResponseError as e:
    print(f"Status code: {e.status_code}")
    print(f"Reason: {e.reason}")
    print(f"Message: {e.error.message}")

على سبيل المثال، عند توفير مفتاح مصادقة خاطئ:

Status code: 401
Reason: PermissionDenied
Message: Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource.

أو عند توفير عنوان URL لصورة غير موجودة أو لا يمكن الوصول إليها:

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

تسجيل الدخول

يستخدم العميل مكتبة تسجيل Python القياسية. يسجل SDK تفاصيل طلب واستجابة HTTP، والتي قد تكون مفيدة في استكشاف الأخطاء وإصلاحها. لتسجيل الدخول إلى stdout، أضف ما يلي:

import sys
import logging

# Acquire the logger for this client library. Use 'azure' to affect both
# 'azure.core` and `azure.ai.vision.imageanalysis' libraries.
logger = logging.getLogger("azure")

# Set the desired logging level. logging.INFO or logging.DEBUG are good options.
logger.setLevel(logging.INFO)

# Direct logging output to stdout (the default):
handler = logging.StreamHandler(stream=sys.stdout)
# Or direct logging output to a file:
# handler = logging.FileHandler(filename = 'sample.log')
logger.addHandler(handler)

# Optional: change the default logging format. Here we add a timestamp.
formatter = logging.Formatter("%(asctime)s:%(levelname)s:%(name)s:%(message)s")
handler.setFormatter(formatter)

تقوم السجلات بشكل افتراضي بتنقيح قيم سلاسل استعلام URL وقيم بعض عناوين طلب واستجابة HTTP (بما في ذلك Ocp-Apim-Subscription-Key التي تحتوي على المفتاح)، وحمولة الطلب والاستجابة. لإنشاء سجلات دون تغيير، قم بتعيين وسيطة logging_enable = True الأسلوب عند إنشاء ImageAnalysisClient، أو عند الاتصال analyze بالعميل.

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

لا يتم إنشاء أي سجلات منقحة لمستوى logging.DEBUG السجل فقط. تأكد من حماية أي سجلات منقحة لتجنب المساس بالأمان. لمزيد من المعلومات، راجع تكوين التسجيل في مكتبات Azure ل Python

المتطلبات الأساسية

يفترض هذا الدليل أنك اتبعت الخطوات الواردة في صفحة التشغيل السريع . يعني ذلك:

  • لقد أنشأت مورد Computer Vision وحصلت على عنوان URL للمفتاح ونقطة النهاية.
  • لديك حزمة SDK المناسبة مثبتة ولديك تطبيق التشغيل السريع . يمكنك تعديل تطبيق التشغيل السريع هذا استنادا إلى أمثلة التعليمات البرمجية هنا.

إنشاء العميل ومصادقته

للمصادقة مع خدمة تحليل الصور، تحتاج إلى مفتاح Computer Vision وعنوان URL لنقطة النهاية. يفترض هذا الدليل أنك قمت بتعريف متغيرات VISION_KEY البيئة ومع VISION_ENDPOINT المفتاح ونقطة النهاية.

تلميح

لا تقم بتضمين المفتاح مباشرة في التعليمات البرمجية الخاصة بك، ولا تنشره بشكل عام. راجع مقالة أمان خدمات Azure الذكاء الاصطناعي لمزيد من خيارات المصادقة مثل Azure Key Vault.

ابدأ بإنشاء كائن ImageAnalysisClient . على سبيل المثال:

String endpoint = System.getenv("VISION_ENDPOINT");
String key = System.getenv("VISION_KEY");

if (endpoint == null || key == null) {
    System.out.println("Missing environment variable 'VISION_ENDPOINT' or 'VISION_KEY'.");
    System.out.println("Set them before running this sample.");
    System.exit(1);
}

// Create a synchronous Image Analysis client.
ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .buildClient();

حدد الصورة لتحليلها

يمكنك تحديد صورة عن طريق توفير عنوان URL للصورة يمكن الوصول إليه بشكل عام، أو عن طريق قراءة بيانات الصورة في المخزن المؤقت لإدخال SDK. راجع متطلبات الصورة لتنسيقات الصور المدعومة.

عنوان URL للصورة

أنشئ سلسلة imageUrl للاحتفاظ بعنوان URL الذي يمكن الوصول إليه بشكل عام للصورة التي تريد تحليلها.

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

المخزن المؤقت للصورة

بدلا من ذلك، يمكنك تمرير الصورة كمخزن مؤقت للذاكرة باستخدام كائن BinaryData . على سبيل المثال، اقرأ من ملف صورة محلي تريد تحليله.

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

تحديد الخصائص المرئية

تمنحك واجهة برمجة تطبيقات Analysis 4.0 إمكانية الوصول إلى جميع ميزات تحليل الصور الخاصة بالخدمة. اختر العمليات التي تريد القيام بها بناءً على حالة الاستخدام الخاصة بك. راجع نظرة عامة للحصول على وصف لكل ميزة. يضيف المثال في هذا القسم جميع الميزات المرئية المتوفرة، ولكن للاستخدام العملي، من المحتمل أن تحتاج إلى عدد أقل.

هام

الميزات المرئية يتم دعم التسميات التوضيحية وCaptions DenseCaptions فقط في مناطق Azure التالية: شرق الولايات المتحدة، وفرنسا الوسطى، وكوريا الوسطى، وشمال أوروبا، وجنوب شرق آسيا، وغرب أوروبا، وغرب الولايات المتحدة.

// visualFeatures: Select one or more visual features to analyze.
List<VisualFeatures> visualFeatures = Arrays.asList(
            VisualFeatures.SMART_CROPS,
            VisualFeatures.CAPTION,
            VisualFeatures.DENSE_CAPTIONS,
            VisualFeatures.OBJECTS,
            VisualFeatures.PEOPLE,
            VisualFeatures.READ,
            VisualFeatures.TAGS);

تحديد خيارات التحليل

استخدم كائن ImageAnalysisOptions لتحديد خيارات مختلفة لاستدعاء تحليل واجهة برمجة التطبيقات.

  • اللغة: يمكنك تحديد لغة البيانات التي تم إرجاعها. اللغة اختيارية، حيث تكون اللغة الافتراضية هي الإنجليزية. راجع دعم اللغة للحصول على قائمة رموز اللغات المدعومة والميزات المرئية المدعومة لكل لغة.
  • التسميات التوضيحية المحايدة للجنس: إذا كنت تقوم باستخراج التسميات التوضيحية أو التسميات التوضيحية الكثيفة (باستخدام VisualFeatures.CAPTION أو VisualFeatures.DENSE_CAPTIONS)، يمكنك طلب تسميات توضيحية محايدة للجنس. تعتبر التسميات التوضيحية المحايدة للجنسين اختيارية، حيث يكون الافتراضي هو التسميات التوضيحية الجنسانية. على سبيل المثال، في اللغة الإنجليزية، عند تحديد تسميات توضيحية محايدة جنسانيا، يتم استبدال مصطلحات مثل المرأة أو الرجل بشخص، ويتم استبدال الصبي أو الفتاة بطفل.
  • نسبة العرض إلى الارتفاع للقص: يتم حساب نسبة العرض إلى الارتفاع عن طريق تقسيم عرض القص المستهدف على الارتفاع. تتراوح القيم المدعومة من 0.75 إلى 1.8 (شاملة). يكون تعيين هذه الخاصية مناسبا فقط عند تحديد VisualFeatures.SMART_CROPS كجزء من قائمة الميزات المرئية. إذا حددت VisualFeatures.SMART_CROPS ولكنك لم تحدد نسب العرض إلى الارتفاع، فترجع الخدمة اقتراح قص واحدا بنسبة عرض إلى ارتفاع تراه مناسبا. في هذه الحالة، تتراوح نسبة العرض إلى الارتفاع بين 0.5 و2.0 (شاملة).
// Specify analysis options (or set `options` to null for defaults)
ImageAnalysisOptions options = new ImageAnalysisOptions()
    .setLanguage("en")
    .setGenderNeutralCaption(true)
    .setSmartCropsAspectRatios(Arrays.asList(0.9, 1.33, 1.78));

استدعاء أسلوب analyzeFromUrl

يوضح لك هذا القسم كيفية إجراء استدعاء تحليل للخدمة.

استدعاء أسلوب analyzeFromUrl على كائن ImageAnalysisClient، كما هو موضح هنا. الاستدعاء متزامن، وسيتم حظره حتى تقوم الخدمة بإرجاع النتائج أو حدوث خطأ. بدلا من ذلك، يمكنك استخدام كائن ImageAnalysisAsyncClient بدلا من ذلك، واستدعاء أسلوب analyzeFromUrl الخاص به وهو غير محظور.

للتحليل من مخزن مؤقت للصورة بدلا من عنوان URL، قم باستدعاء أسلوب التحليل بدلا من ذلك، ومرر كوسيطة imageData أولى.

try {
    // Analyze all visual features from an image URL. This is a synchronous (blocking) call.
    ImageAnalysisResult result = client.analyzeFromUrl(
        imageUrl,
        visualFeatures,
        options);

    printAnalysisResults(result);

} catch (HttpResponseException e) {
    System.out.println("Exception: " + e.getClass().getSimpleName());
    System.out.println("Status code: " + e.getResponse().getStatusCode());
    System.out.println("Message: " + e.getMessage());
} catch (Exception e) {
    System.out.println("Message: " + e.getMessage());
}

الحصول على نتائج من الخدمة

توضح لك التعليمات البرمجية التالية كيفية تحليل النتائج من عمليات analyzeFromUrl وتحليلها.

// Print all analysis results to the console
public static void printAnalysisResults(ImageAnalysisResult result) {

    System.out.println("Image analysis results:");

    if (result.getCaption() != null) {
        System.out.println(" Caption:");
        System.out.println("   \"" + result.getCaption().getText() + "\", Confidence "
            + String.format("%.4f", result.getCaption().getConfidence()));
    }

    if (result.getDenseCaptions() != null) {
        System.out.println(" Dense Captions:");
        for (DenseCaption denseCaption : result.getDenseCaptions().getValues()) {
            System.out.println("   \"" + denseCaption.getText() + "\", Bounding box "
                + denseCaption.getBoundingBox() + ", Confidence " + String.format("%.4f", denseCaption.getConfidence()));
        }
    }

    if (result.getRead() != null) {
        System.out.println(" Read:");
        for (DetectedTextLine line : result.getRead().getBlocks().get(0).getLines()) {
            System.out.println("   Line: '" + line.getText()
                + "', Bounding polygon " + line.getBoundingPolygon());
            for (DetectedTextWord word : line.getWords()) {
                System.out.println("     Word: '" + word.getText()
                    + "', Bounding polygon " + word.getBoundingPolygon()
                    + ", Confidence " + String.format("%.4f", word.getConfidence()));
            }
        }
    }

    if (result.getTags() != null) {
        System.out.println(" Tags:");
        for (DetectedTag tag : result.getTags().getValues()) {
            System.out.println("   \"" + tag.getName() + "\", Confidence " + String.format("%.4f", tag.getConfidence()));
        }
    }

    if (result.getObjects() != null) {
        System.out.println(" Objects:");
        for (DetectedObject detectedObject : result.getObjects().getValues()) {
            System.out.println("   \"" + detectedObject.getTags().get(0).getName() + "\", Bounding box "
                + detectedObject.getBoundingBox() + ", Confidence " + String.format("%.4f", detectedObject.getTags().get(0).getConfidence()));
        }
    }

    if (result.getPeople() != null) {
        System.out.println(" People:");
        for (DetectedPerson person : result.getPeople().getValues()) {
            System.out.println("   Bounding box "
                + person.getBoundingBox() + ", Confidence " + String.format("%.4f", person.getConfidence()));
        }
    }

    if (result.getSmartCrops() != null) {
        System.out.println(" Crop Suggestions:");
        for (CropRegion cropRegion : result.getSmartCrops().getValues()) {
            System.out.println("   Aspect ratio "
                + cropRegion.getAspectRatio() + ": Bounding box " + cropRegion.getBoundingBox());
        }
    }

    System.out.println(" Image height = " + result.getMetadata().getHeight());
    System.out.println(" Image width = " + result.getMetadata().getWidth());
    System.out.println(" Model version = " + result.getModelVersion());
}

استكشاف الأخطاء وإصلاحها

استثناءات

تطرح الأساليب analyze HttpResponseException عندما تستجيب الخدمة برمز حالة HTTP غير ناجح. يحتفظ الاستثناء getResponse().getStatusCode() برمز حالة استجابة HTTP. يحتوي الاستثناء getMessage() على رسالة مفصلة تسمح لك بتشخيص المشكلة:

try {
    ImageAnalysisResult result = client.analyze(...)
} catch (HttpResponseException e) {
    System.out.println("Exception: " + e.getClass().getSimpleName());
    System.out.println("Status code: " + e.getResponse().getStatusCode());
    System.out.println("Message: " + e.getMessage());
} catch (Exception e) {
    System.out.println("Message: " + e.getMessage());
}

على سبيل المثال، عند توفير مفتاح مصادقة خاطئ:

Exception: ClientAuthenticationException
Status code: 401
Message: Status code 401, "{"error":{"code":"401","message":"Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource."}}"

أو عند توفير صورة بتنسيق لم يتم التعرف عليه:

Exception: HttpResponseException
Status code: 400
Message: Status code 400, "{"error":{"code":"InvalidRequest","message":"Image format is not valid.","innererror":{"code":"InvalidImageFormat","message":"Input data is not a valid image."}}}"

تمكين تسجيل طلب/استجابة HTTP

يمكن أن تكون مراجعة طلب HTTP المرسل أو الاستجابة المستلمة عبر السلك إلى خدمة تحليل الصور مفيدة في استكشاف الأخطاء وإصلاحها. تدعم مكتبة عميل تحليل الصور إطار عمل تسجيل وحدة تحكم مضمن لأغراض تصحيح الأخطاء المؤقتة. كما أنه يدعم التسجيل الأكثر تقدما باستخدام واجهة SLF4J . للحصول على معلومات مفصلة، راجع استخدام التسجيل في Azure SDK ل Java.

تناقش الأقسام أدناه تمكين تسجيل وحدة التحكم باستخدام إطار العمل المضمن.

عن طريق تعيين متغيرات البيئة

يمكنك تمكين تسجيل وحدة التحكم لطلب HTTP والاستجابة للتطبيق بأكمله عن طريق تعيين متغيري البيئة التاليين. يؤثر هذا التغيير على كل عميل Azure يدعم تسجيل طلب HTTP والاستجابة له.

  • تعيين متغير AZURE_LOG_LEVEL البيئة إلى debug
  • تعيين متغير AZURE_HTTP_LOG_DETAIL_LEVEL البيئة إلى إحدى القيم التالية:
القيمة‬ مستوى التسجيل
none تم تعطيل تسجيل طلب/استجابة HTTP
basic يسجل عناوين URL وأساليب HTTP والوقت فقط لإنهاء الطلب.
headers يسجل كل شيء في BASIC، بالإضافة إلى جميع عناوين الطلب والاستجابة.
body يسجل كل شيء في BASIC، بالإضافة إلى جميع نص الطلب والاستجابة.
body_and_headers يسجل كل شيء في HEADERS و BODY.

عن طريق تعيين httpLogOptions

لتمكين تسجيل وحدة التحكم لطلب HTTP والاستجابة لعميل واحد

  • تعيين متغير AZURE_LOG_LEVEL البيئة إلى debug
  • أضف مكالمة إلى httpLogOptions عند إنشاء ImageAnalysisClient:
ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS))
    .buildClient();

يحدد enum HttpLogDetailLevel مستويات التسجيل المدعومة.

بشكل افتراضي، عند التسجيل، يتم تنقيح قيم معينة لعنوان HTTP ومعلمة الاستعلام. من الممكن تجاوز هذا الافتراضي عن طريق تحديد الرؤوس ومعلمات الاستعلام الآمنة لتسجيلها:

ImageAnalysisClient client = new ImageAnalysisClientBuilder()
    .endpoint(endpoint)
    .credential(new KeyCredential(key))
    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS)
        .addAllowedHeaderName("safe-to-log-header-name")
        .addAllowedQueryParamName("safe-to-log-query-parameter-name"))
    .buildClient();

على سبيل المثال، للحصول على سجل كامل غير منقح لطلب HTTP، قم بتطبيق ما يلي:

    .httpLogOptions(new HttpLogOptions().setLogLevel(HttpLogDetailLevel.BODY_AND_HEADERS)
        .addAllowedHeaderName("Ocp-Apim-Subscription-Key")
        .addAllowedQueryParamName("features")
        .addAllowedQueryParamName("language")
        .addAllowedQueryParamName("gender-neutral-caption")
        .addAllowedQueryParamName("smartcrops-aspect-ratios")
        .addAllowedQueryParamName("model-version"))

أضف المزيد إلى ما سبق للحصول على استجابة HTTP غير منقحة. عند مشاركة سجل غير منقح، تأكد من أنه لا يحتوي على أسرار مثل مفتاح الاشتراك الخاص بك.

المتطلبات الأساسية

يفترض هذا الدليل أنك اتبعت الخطوات المذكورة في التشغيل السريع. يعني ذلك:

  • لقد أنشأت مورد Computer Vision وحصلت على عنوان URL للمفتاح ونقطة النهاية.
  • لديك حزمة SDK المناسبة مثبتة ولديك تطبيق التشغيل السريع . يمكنك تعديل تطبيق التشغيل السريع هذا استنادا إلى أمثلة التعليمات البرمجية هنا.

إنشاء العميل ومصادقته

للمصادقة مقابل خدمة تحليل الصور، تحتاج إلى مفتاح Computer Vision وعنوان URL لنقطة النهاية. يفترض هذا الدليل أنك قمت بتعريف متغيرات VISION_KEY البيئة ومع VISION_ENDPOINT المفتاح ونقطة النهاية.

تلميح

لا تقم بتضمين المفتاح مباشرة في التعليمات البرمجية الخاصة بك، ولا تنشره بشكل عام. راجع مقالة أمان خدمات Azure الذكاء الاصطناعي لمزيد من خيارات المصادقة مثل Azure Key Vault.

ابدأ بإنشاء كائن ImageAnalysisClient . على سبيل المثال:

// Load the .env file if it exists
require("dotenv").config();

const endpoint = process.env['VISION_ENDPOINT'] || '<your_endpoint>';
const key = process.env['VISION_KEY'] || '<your_key>';

const credential = new AzureKeyCredential(key);
const client = createClient(endpoint, credential);

حدد الصورة لتحليلها

يمكنك تحديد صورة عن طريق توفير عنوان URL للصورة يمكن الوصول إليه بشكل عام، أو عن طريق قراءة بيانات الصورة في المخزن المؤقت لإدخال SDK. راجع متطلبات الصورة لتنسيقات الصور المدعومة.

عنوان URL للصورة

يمكنك استخدام نموذج URL التالي للصورة.

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

المخزن المؤقت للصورة

بدلا من ذلك، يمكنك تمرير الصورة كصفيف بيانات. على سبيل المثال، اقرأ من ملف صورة محلي تريد تحليله.

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

تحديد الخصائص المرئية

تمنحك واجهة برمجة تطبيقات Analysis 4.0 إمكانية الوصول إلى جميع ميزات تحليل الصور الخاصة بالخدمة. اختر العمليات التي تريد القيام بها بناءً على حالة الاستخدام الخاصة بك. راجع نظرة عامة للحصول على وصف لكل ميزة. يضيف المثال في هذا القسم جميع الميزات المرئية المتوفرة، ولكن للاستخدام العملي، من المحتمل أن تحتاج إلى عدد أقل.

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

استدعاء تحليل واجهة برمجة التطبيقات مع الخيارات

تستدعي التعليمات البرمجية التالية واجهة برمجة التطبيقات Analyze مع الميزات التي حددتها أعلاه وخيارات إضافية، محددة أدناه. للتحليل من مخزن مؤقت للصورة بدلا من عنوان URL، استبدل imageURL في استدعاء الأسلوب ب imageData.

const result = await client.path('/imageanalysis:analyze').post({
  body: {
      url: imageUrl
  },
  queryParameters: {
      features: features,
      'language': 'en',
      'gender-neutral-captions': 'true',
      'smartCrops-aspect-ratios': [0.9, 1.33]
  },
  contentType: 'application/json'
});

تحديد نسب العرض إلى الارتفاع في الاقتصاص الذكي

يتم حساب نسبة العرض إلى الارتفاع عن طريق تقسيم عرض الاقتصاص المستهدف على الارتفاع. تتراوح القيم المدعومة من 0.75 إلى 1.8 (شاملة). يكون تعيين هذه الخاصية مناسبا فقط عند تحديد VisualFeatures.SmartCrops كجزء من قائمة الميزات المرئية. إذا حددت VisualFeatures.SmartCrops ولكنك لم تحدد نسب العرض إلى الارتفاع، فترجع الخدمة اقتراح قص واحدا بنسبة عرض إلى ارتفاع تراه مناسبا. في هذه الحالة، تتراوح نسبة العرض إلى الارتفاع بين 0.5 و2.0 (شاملة).

تحديد التسميات التوضيحية المحايدة للجنس

إذا كنت تقوم باستخراج التسميات التوضيحية أو التسميات التوضيحية الكثيفة (باستخدام VisualFeatures.Captions أو VisualFeatures.DenseCaptions)، يمكنك طلب تسميات توضيحية محايدة للجنس. تعتبر التسميات التوضيحية المحايدة للجنسين اختيارية، حيث يكون الافتراضي هو التسميات التوضيحية الجنسانية. على سبيل المثال، في اللغة الإنجليزية، عند تحديد تسميات توضيحية محايدة جنسانيا، يتم استبدال مصطلحات مثل المرأة أو الرجل بشخص، ويتم استبدال الصبي أو الفتاة بطفل.

تحديد اللغات

يمكنك تحديد لغة البيانات التي تم إرجاعها. اللغة اختيارية، حيث تكون اللغة الافتراضية هي الإنجليزية. راجع دعم اللغة للحصول على قائمة رموز اللغات المدعومة والميزات المرئية المدعومة لكل لغة.

الحصول على نتائج من الخدمة

توضح لك التعليمات البرمجية التالية كيفية تحليل نتائج عمليات التحليل المختلفة.

const iaResult = result.body;

console.log(`Model Version: ${iaResult.modelVersion}`);
console.log(`Image Metadata: ${JSON.stringify(iaResult.metadata)}`);
if (iaResult.captionResult) {
  console.log(`Caption: ${iaResult.captionResult.text} (confidence: ${iaResult.captionResult.confidence})`);
}
if (iaResult.denseCaptionsResult) {
  iaResult.denseCaptionsResult.values.forEach(denseCaption => console.log(`Dense Caption: ${JSON.stringify(denseCaption)}`));
}
if (iaResult.objectsResult) {
  iaResult.objectsResult.values.forEach(object => console.log(`Object: ${JSON.stringify(object)}`));
}
if (iaResult.peopleResult) {
  iaResult.peopleResult.values.forEach(person => console.log(`Person: ${JSON.stringify(person)}`));
}
if (iaResult.readResult) {
  iaResult.readResult.blocks.forEach(block => console.log(`Text Block: ${JSON.stringify(block)}`));
}
if (iaResult.smartCropsResult) {
  iaResult.smartCropsResult.values.forEach(smartCrop => console.log(`Smart Crop: ${JSON.stringify(smartCrop)}`));
}
if (iaResult.tagsResult) {
  iaResult.tagsResult.values.forEach(tag => console.log(`Tag: ${JSON.stringify(tag)}`));
}

استكشاف الأخطاء وإصلاحها

تسجيل الدخول

قد يساعد تمكين التسجيل في الكشف عن معلومات مفيدة حول حالات الفشل. للاطلاع على سجل لطلبات HTTP واستجاباته، قم بتعيين AZURE_LOG_LEVELمتغير البيئة إلى info. بدلًا من ذلك، يمكن تمكين التسجيل في وقت التشغيل عن طريق الاتصال setLogLevelبـ @azure/logger:

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

setLogLevel("info");

للحصول على إرشادات أكثر تفصيلا حول كيفية تمكين السجلات، يمكنك إلقاء نظرة على مستندات حزمة @azure/المسجل.

المتطلبات الأساسية

يفترض هذا الدليل أنك اتبعت الخطوات المذكورة في صفحة التشغيل السريع بنجاح. يعني ذلك:

  • لقد أنشأت مورد Computer Vision وحصلت على عنوان URL للمفتاح ونقطة النهاية.
  • لقد أجريت curl.exe مكالمة إلى الخدمة بنجاح (أو استخدمت أداة بديلة). يمكنك تعديل curl.exe الاستدعاء استنادا إلى الأمثلة هنا.

المصادقة مقابل الخدمة

للمصادقة مقابل خدمة تحليل الصور، تحتاج إلى مفتاح Computer Vision وعنوان URL لنقطة النهاية.

تلميح

لا تقم بتضمين المفتاح مباشرة في التعليمات البرمجية الخاصة بك، ولا تنشره بشكل عام. راجع مقالة أمان خدمات Azure الذكاء الاصطناعي لمزيد من خيارات المصادقة مثل Azure Key Vault.

يفترض مثال SDK أنك قمت بتعريف متغيرات VISION_KEY البيئة ومع VISION_ENDPOINT المفتاح ونقطة النهاية.

تتم المصادقة عن طريق إضافة عنوان طلب HTTP Ocp-Apim-Subscription-Key وتعيينه إلى مفتاح الرؤية الخاص بك. يتم إجراء الاستدعاء إلى عنوان URL <endpoint>/computervision/imageanalysis:analyze?api-version=2024-02-01، حيث <endpoint> هو عنوان URL الفريد لنقطة نهاية رؤية الكمبيوتر. يمكنك إضافة سلاسل الاستعلام استنادا إلى خيارات التحليل الخاصة بك.

حدد الصورة لتحليلها

يستخدم التعليمة البرمجية الموجود في هذا الدليل الصور البعيدة المشار إليها بواسطة URL. قد ترغب في تجربة صور مختلفة بنفسك لمعرفة القدرة الكاملة لميزات تحليل الصورة.

عند تحليل صورة بعيدة، يمكنك تحديد عنوان URL للصورة عن طريق تنسيق نص الطلب كما يلي: {"url":"https://learn.microsoft.com/azure/cognitive-services/computer-vision/images/windows-kitchen.jpg"}. يجب أن يكون application/jsonنوع المحتوى .

لتحليل صورة محلية، يمكنك وضع بيانات الصورة الثنائية في نص طلب HTTP. يجب أن يكون application/octet-stream نوع المحتوى أو multipart/form-data.

تحديد خيارات التحليل

تحديد الميزات المرئية عند استخدام النموذج القياسي

تمنحك واجهة برمجة تطبيقات Analysis 4.0 إمكانية الوصول إلى جميع ميزات تحليل الصور الخاصة بالخدمة. اختر العمليات التي تريد القيام بها بناءً على حالة الاستخدام الخاصة بك. راجع نظرة عامة للحصول على وصف لكل ميزة. يضيف المثال في هذا القسم جميع الميزات المرئية المتوفرة، ولكن للاستخدام العملي، من المحتمل أن تحتاج إلى عدد أقل.

يتم دعم الميزات المرئية "التسميات التوضيحية" و"التسميات التوضيحية الكثيفة" فقط في مناطق Azure التالية: شرق الولايات المتحدة وفرنسا الوسطى وكوريا الوسطى وشمال أوروبا وجنوب شرق آسيا وغرب أوروبا وغرب الولايات المتحدة.

إشعار

تستخدم واجهة برمجة تطبيقات REST مصطلحي المحاصيل الذكية ونسب العرض إلى الارتفاع للمحاصيل الذكية. يستخدم SDK مصطلحي اقتراحات الاقتصاص وقص نسب العرض إلى الارتفاع. كلاهما يشير إلى نفس عملية الخدمة. وبالمثل، تستخدم واجهة برمجة تطبيقات REST مصطلح Read للكشف عن النص في الصورة باستخدام التعرف البصري على الحروف (OCR)، بينما تستخدم SDK مصطلح Text لنفس العملية.

يمكنك تحديد الميزات التي تريد استخدامها عن طريق تعيين معلمات استعلام URL لواجهة برمجة تطبيقات Analysis 4.0. يمكن أن تحتوي المعلمة على قيم متعددة، مفصولة بفواصل.

معلمة URL قيمة ‏‏الوصف
features read يقرأ النص المرئي في الصورة ويخرجه كبيانات JSON منظمة.
features caption يصف محتوى الصورة بجملة كاملة باللغات المدعومة.
features denseCaptions إنشاء تسميات توضيحية مفصلة لما يصل إلى 10 مناطق صور بارزة.
features smartCrops البحث عن إحداثيات المستطيل التي من شأنها قص الصورة إلى نسبة العرض إلى الارتفاع المطلوبة مع الحفاظ على منطقة الاهتمام.
features objects يكتشف كائنات مختلفة داخل صورة، بما في ذلك الموقع التقريبي. تتوفر وسيطة الكائنات باللغة الإنجليزية فقط.
features tags وضع علامة على الصورة بقائمة مفصلة من الكلمات المتعلقة بمحتوى الصورة.
features people يكتشف الأشخاص الذين يظهرون في الصور، بما في ذلك المواقع التقريبية.

قد يبدو عنوان URL المعبأ بالشكل التالي:

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

تعيين اسم النموذج عند استخدام نموذج مخصص

يمكنك أيضا إجراء تحليل الصور باستخدام نموذج مدرب مخصص. لإنشاء نموذج وتدريبه، راجع إنشاء نموذج مخصص لتحليل الصور. بمجرد تدريب النموذج الخاص بك، كل ما تحتاجه هو اسم النموذج. لا تحتاج إلى تحديد ميزات مرئية إذا كنت تستخدم نموذجا مخصصا.

لاستخدام نموذج مخصص، لا تستخدم معلمة استعلام الميزات. بدلا من ذلك، قم بتعيين المعلمة model-name إلى اسم النموذج الخاص بك كما هو موضح هنا. استبدل MyCustomModelName باسم النموذج المخصص الخاص بك.

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

تحديد اللغات

يمكنك تحديد لغة البيانات التي تم إرجاعها. اللغة اختيارية، حيث تكون اللغة الافتراضية هي الإنجليزية. راجع دعم اللغة للحصول على قائمة رموز اللغات المدعومة والميزات المرئية المدعومة لكل لغة.

ينطبق خيار اللغة فقط عند استخدام النموذج القياسي.

تحدد معلمة استعلام عنوان URL التالية اللغة. القيمة الافتراضية هي en.

معلمة URL قيمة ‏‏الوصف
language en الإنجليزية
language es الإسبانية
language ja اليابانية
language pt البرتغالية
language zh الصينية المبسطة

قد يبدو عنوان URL المعبأ بالشكل التالي:

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

تحديد التسميات التوضيحية المحايدة للجنس

إذا كنت تقوم باستخراج التسميات التوضيحية أو التسميات التوضيحية الكثيفة، يمكنك طلب تسميات توضيحية محايدة بين الجنسين. تعتبر التسميات التوضيحية المحايدة للجنسين اختيارية، حيث يكون الافتراضي هو التسميات التوضيحية الجنسانية. على سبيل المثال، في اللغة الإنجليزية، عند تحديد تسميات توضيحية محايدة جنسانيا، يتم استبدال مصطلحات مثل المرأة أو الرجل بشخص، ويتم استبدال الصبي أو الفتاة بطفل.

ينطبق خيار التسمية التوضيحية المحايدة للجنسين فقط عند استخدام النموذج القياسي.

أضف سلسلة gender-neutral-caption الاستعلام الاختيارية مع القيم true أو false (الافتراضي).

قد يبدو عنوان URL المعبأ بالشكل التالي:

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

تحديد نسب العرض إلى الارتفاع في الاقتصاص الذكي

يتم حساب نسبة العرض إلى الارتفاع عن طريق تقسيم عرض الاقتصاص المستهدف على الارتفاع. تتراوح القيم المدعومة من 0.75 إلى 1.8 (شاملة). يكون تعيين هذه الخاصية مناسبا فقط عند تحديد VisualFeatures.SmartCrops كجزء من قائمة الميزات المرئية. إذا حددت VisualFeatures.SmartCrops ولكنك لم تحدد نسب العرض إلى الارتفاع، فترجع الخدمة اقتراح قص واحدا بنسبة عرض إلى ارتفاع تراه مناسبا. في هذه الحالة، تتراوح نسبة العرض إلى الارتفاع بين 0.5 و2.0 (شاملة).

تنطبق حصص الحصص الغذائية الذكية لجانب الاقتصاص فقط عند استخدام النموذج القياسي.

أضف سلسلة smartcrops-aspect-ratiosالاستعلام الاختيارية ، مع واحد أو أكثر من نسب العرض إلى الارتفاع مفصولة بفاوصلة.

قد يبدو عنوان URL المعبأ بالشكل التالي:

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

الحصول على نتائج من الخدمة

الحصول على النتائج باستخدام النموذج القياسي

يوضح لك هذا القسم كيفية إجراء استدعاء تحليل للخدمة باستخدام النموذج القياسي، والحصول على النتائج.

ترجع الخدمة الاستجابة 200 HTTP، ويحتوي النص على البيانات التي تم إرجاعها في شكل سلسلة JSON. النص التالي هو مثال على استجابة JSON.

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

رموز الخطأ

عند الخطأ، تحتوي استجابة خدمة تحليل الصور على حمولة JSON تتضمن رمز خطأ ورسالة خطأ. قد يتضمن أيضا تفاصيل أخرى في شكل رمز الخطأ الداخلي والرسالة. على سبيل المثال:

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

فيما يلي قائمة بالأخطاء الشائعة وأسبابها. يتم تقديم عناصر القائمة بالتنسيق التالي:

  • رمز استجابة HTTP
    • رمز الخطأ والرسالة في استجابة JSON
      • [اختياري] رمز الخطأ الداخلي والرسالة في استجابة JSON

قائمة الأخطاء الشائعة:

  • 400 Bad Request
    • InvalidRequest - Image URL is badly formatted or not accessible. تأكد من أن عنوان URL للصورة صالح ويمكن الوصول إليه بشكل عام.
    • InvalidRequest - The image size is not allowed to be zero or larger than 20971520 bytes. قم بتقليل حجم الصورة عن طريق ضغطها و/أو تغيير حجمها، ثم أعد إرسال طلبك.
    • InvalidRequest - The feature 'Caption' is not supported in this region. يتم دعم الميزة فقط في مناطق Azure معينة. راجع متطلبات التشغيل السريع لقائمة مناطق Azure المدعومة.
    • InvalidRequest - The provided image content type ... is not supported. نوع المحتوى لعنوان HTTP في الطلب غير مسموح به:
      • بالنسبة إلى عنوان URL للصورة، يجب أن يكون نوع المحتوى application/json
      • بالنسبة لبيانات الصورة الثنائية، يجب أن يكون application/octet-stream نوع المحتوى أوmultipart/form-data
    • InvalidRequest - Either 'features' or 'model-name' needs to be specified in the query parameter.
    • InvalidRequest - Image format is not valid
    • InvalidRequest - Analyze query is invalid
      • NotSupportedVisualFeature - Specified feature type is not valid. تأكد من أن سلسلة استعلام الميزات لها قيمة صالحة.
      • NotSupportedLanguage - The input language is not supported. تأكد من أن سلسلة استعلام اللغة لها قيمة صالحة للميزة المرئية المحددة، استنادا إلى الجدول التالي.
      • BadArgument - 'smartcrops-aspect-ratios' aspect ratio is not in allowed range [0.75 to 1.8]
  • 401 PermissionDenied
    • 401 - Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource.
  • 404 Resource Not Found
    • 404 - Resource not found. تعذر على الخدمة العثور على النموذج المخصص استنادا إلى الاسم الذي توفره model-name سلسلة الاستعلام.

الخطوات التالية