VNRequest — ما هو، كيفية عمل طلبات Vision في iOS

ما هو VNRequest في Vision؟

VNRequest هو عنصر أساسي في بنية Vision، يطبق نمط الطلب-الاستجابة لتحليل الصور والفيديو. كل فئة فرعية من VNRequest تكون مسؤولة عن مهمة محددة في رؤية الحاسوب: كشف الوجوه، التعرف على النصوص، تصنيف المحتوى.

تفصل بنية VNRequest بين «ماذا نحلل» (الطلب) و«كيف نعالج» (المعالج). يقوم المطور بتكوين الطلب (نوع التحليل، المعلمات الإضافية)، ويمرره إلى المعالج مع الصورة. ينفذ المعالج الطلب ويعيد النتائج دون حاجة المطور لفهم خوارزميات ML الداخلية.

تتبع جميع الفئات الفرعية لـ VNRequest بنية موحدة: التهيئة مع completion handler اختياري، تكوين الخصائص (منطقة الاهتمام، مستوى الدقة)، والإرسال إلى المعالج. وهذا يجعل API قابلًا للتوقع وسهل التوسيع — إضافة نوع جديد من التحليل تعني إنشاء فئة فرعية جديدة لـ VNRequest.

import Vision

// ١. إنشاء الطلب
let request = VNDetectFaceRectanglesRequest { req, _ in
    // ٣. معالجة النتائج
    guard let faces = req.results as? [VNFaceObservation]
    else { return }
    print("Found \\(faces.count) faces")
}

// ٢. تنفيذ عبر المعالج
let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
try handler.perform([request])

خصائص VNRequest الرئيسية: regionOfInterest (منطقة اهتمام على الصورة لتسريع التحليل)، preferBackgroundProcessing (وضع الخلفية)، revision (نسخة الخوارزمية) و cancellationSupport. يتيح التكوين المناسب لهذه الخصائص تحسين الأداء لمهمة محددة.

وفقًا لـ Apple WWDC 2024، عبر 7 سنوات من وجود Vision، ارتفع عدد الفئات الفرعية المتاحة لـ VNRequest من 8 (iOS 11) إلى أكثر من 25 (iOS 18)، مغطية جميع مهام رؤية الحاسوب الرئيسية على الأجهزة المحمولة.

الأنواع الرئيسية لـ VNRequest للتحليل

Vision يضم أكثر من 25 فئة فرعية لـ VNRequest مقسمة إلى فئات: الكشف، التعرف، التتبع والتصنيف. ترث كل فئة فرعية من VNRequest وتضيف خصائص محددة للمهمة.

الكشف والتعرف

VNDetectFaceRectanglesRequest — الكشف عن الوجوه في الصور. يعيد VNFaceObservation بإحداثيات bounding box والثقة. VNDetectHumanRectanglesRequest — بالمثل للأشخاص. VNDetectHumanBodyPoseRequest — تقدير وضعية الجسم (نقاط هيكلية).

التحليل النصي

VNRecognizeTextRequest — التعرف على النصوص بدعم 13 لغة ومستويين من الدقة. VNReadCodeRequest — للرموز المتخصصة. VNDetectTextRectanglesRequest — البحث عن مناطق النص دون تعرف (أسرع، ولكن فقط مستطيلات).

التصنيف والتحليل

VNClassifyImageRequest — تصنيف الصور حسب 1000 فئة من ImageNet. VNGenerateImageFeaturePrintRequest — استخراج متجه الميزات لمقارنة الصور. VNDetectContoursRequest — كشف محيط الأجسام.

VNImageRequestHandler و VNSequenceRequestHandler

VNImageRequestHandler — معالج للصور الثابتة. يستقبل CGImage أو CIImage أو Data (JPEG/PNG) وينفذ واحدًا أو أكثر من VNRequest. هذه هي الطريقة الرئيسية لاستخدام Vision للصور ولقطات الشاشة والصور المحملة.

VNSequenceRequestHandler — معالج لتسلسل الصور (إطارات الفيديو). يستقبل نفس مجموعة أنواع الصور ولكنه مصمم للمعالجة إطارًا بإطار مع الحفاظ على الحالة بين الإطارات (ضروري لتتبع الأجسام).

// VNImageRequestHandler لصورة واحدة
let imageHandler = VNImageRequestHandler(
    cgImage: cgImage,
    orientation: orientation,
    options: [:])

// VNSequenceRequestHandler للفيديو
let sequenceHandler = VNSequenceRequestHandler()
try sequenceHandler.perform([trackingRequest],
    on: cgImage)

الفرق المهم: VNSequenceRequestHandler لا يدعم التنفيذ المتوازي لطلبات متعددة — كل استدعاء لـ perform() يعالج مجموعة واحدة من الطلبات لإطار واحد. للمعالجة متعددة الخيوط للفيديو، قم بإنشاء معالجات منفصلة لخيوط مختلفة.

VNImageRequestHandler يمكنه العمل على طابور خلفي. توصي Apple باستخدام DispatchQueue.global(qos: .userInitiated) للسيناريوهات التفاعلية (المستخدم ينتظر النتائج) و .background للمعالجة دفعية (على سبيل المثال، تحليل مكتبة صور كاملة).

VNObservation: بنية النتائج

VNObservation — الفئة الأساسية لجميع نتائج طلبات Vision. تحتوي كل فئة فرعية من VNObservation على بيانات محددة لنوع التحليل: إحداثيات bounding box، النص المتعرف عليه، الثقة، المعرف الفريد (uuid) والطابع الزمني (timeRange).

الفئات الفرعية الرئيسية لـ VNObservation: VNFaceObservation (نتيجة كشف الوجوه مع bounding box و landmarks)، VNRecognizedTextObservation (نص متعرف عليه مع مرشحين)، VNBarcodeObservation (رمز شريطي مفكوك مع payload و symbology)، VNClassificationObservation (فئة تصنيف مع ثقة).

func handleTextResults(request: VNRequest) {
    guard let observations = request.results
        as? [VNRecognizedTextObservation]
    else { return }

    for observation in observations {
        let bbox = observation.boundingBox
        let text = observation.topCandidates(1).first ?? ""
        print("\\(text) at \\(bbox)")
    }
}

خاصية confidence (من 0.0 إلى 1.0) موجودة في جميع مثالات VNObservation وتشير إلى ثقة النموذج في النتيجة. توصي Apple بتجاهل الملاحظات ذات الثقة < 0.5 لمعظم المهام. للتطبيقات الحرجة (الطب، الأمن)، يجب رفع العتبة إلى 0.8–0.9.

VNObservation تحتوي أيضًا على timeRange (لطلبات الفيديو) و uuid (معرف فريد للمطابقة بين الإطارات). ويسمح ذلك بتتبع نفس الكائن (على سبيل المثال، وجه) عبر تسلسل إطارات الفيديو.

تنفيذ عدة طلبات في نفس الوقت

إحدى المزايا الرئيسية لـ VNRequest هي القدرة على تنفيذ طلبات متعددة مختلفة على نفس الصورة في استدعاء واحد لـ handler.perform(). يقوم Vision بتحسين ترتيب التنفيذ داخليًا ويعيد استخدام الحسابات المشتركة (على سبيل المثال، معالجة الصور الأولية).

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

import Vision

// طلبات متعددة في مصفوفة واحدة
let faceRequest = VNDetectFaceRectanglesRequest()
let textRequest = VNRecognizeTextRequest()
let barcodeRequest = VNDetectBarcodesRequest()
let classifyRequest = VNClassifyImageRequest()

let handler = VNImageRequestHandler(cgImage: cgImage, options: [:])
try handler.perform([
    faceRequest,
    textRequest,
    barcodeRequest,
    classifyRequest
])

// الوصول إلى نتائج كل طلب
print("Faces: \\(faceRequest.results?.count ?? 0)")
print("Text blocks: \\(textRequest.results?.count ?? 0)")

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

الأداء: دمج 3–4 طلبات في perform() واحد أسرع بنسبة 30–40% من التنفيذ المتسلسل لأن Vision يعيد استخدام حسابات ML المشتركة ومعالجة الصور الأولية (التحجيم، تصحيح الألوان).

الطلبات المخصصة مع VNCoreMLRequest

VNCoreMLRequest هو جسر بين Core ML و Vision، يسمح بتشغيل أي نموذج Core ML كطلب Vision. يتم تغليف النموذج في VNCoreMLModel، وتمريره إلى VNCoreMLRequest، ويتولى Vision معالجة الصور الأولية تلقائيًا (التحجيم، القص إلى حجم إدخال النموذج).

VNCoreMLRequest يرث من VNRequest، لذا يدعم جميع الميزات القياسية: regionOfInterest، completion handler، طلبات متعددة. ويسمح بدمج نموذج ML مخصص مع الكشافات المضمنة في Vision في pipeline واحد.

import Vision
import CoreML

// تغليف نموذج Core ML
guard let mlModel = try VNCoreMLModel(
    for: MyCustomClassifier().model)
else { return }

// إنشاء VNCoreMLRequest
let coreMLRequest = VNCoreMLRequest(model: mlModel) { request, _ in
    guard let results = request.results
        as? [VNClassificationObservation]
    else { return }

    for result in results.prefix(5) {
        print("\\(result.identifier): \\(result.confidence)"
    }
}
coreMLRequest.imageCropAndScaleOption = .centerCrop
coreMLRequest.regionOfInterest = faceBoundingBox

imageCropAndScaleOption يحدد كيفية تحجيم Vision للصورة بما يتناسب مع إدخال النموذج: .centerCrop (قص مركز)، .scaleFill (تمديد) أو .scaleFit (تحجيم مع الحفاظ على نسبة الأبعاد). يعتمد الاختيار على نوع النموذج وموقع الكائن في الصورة.

مثال عملي: كشف الوجوه عبر VNDetectFaceRectanglesRequest، ثم تصنيف كل وجه عبر VNCoreMLRequest بنموذج مخصص (على سبيل المثال، تقدير الجنس أو العمر). بدمج طلبين في perform() واحد، تحصل على pipeline كامل لتحليل الوجوه في مرة واحدة.