VNRequest — چیست، ساختار درخواست‌های Vision در iOS

VNRequest در Vision چیست؟

VNRequest — عنصر بنیادین معماری Vision است که الگوی Request-Response را برای تحلیل تصاویر و ویدیو پیاده می‌کند. هر زیرکلاس VNRequest مسئول یک وظیفه مشخص بینایی کامپیوتر است: جستجوی چهره، بازشناسی متن، طبقه‌بندی محتوا.

معماری VNRequest «چه چیزی را تحلیل کنیم» (درخواست) را از «چگونه پردازش کنیم» (handler) جدا می‌کند. توسعه‌دهنده درخواست (نوع تحلیل، پارامترهای اضافی) را پیکربندی کرده و آن را همراه با تصویر به handler ارسال می‌کند. Handler درخواست را اجرا کرده و نتایج را بازمی‌گرداند بدون اینکه توسعه‌دهنده نیاز به درک الگوریتم‌های داخلی ML داشته باشد.

همه زیرکلاس‌های VNRequest از یک ساختار واحد پیروی می‌کنند: مقداردهی با completion handler اختیاری، پیکربندی ویژگی‌ها (منطقه تحلیل، سطح دقت) و ارسال به handler. این API را قابل پیش‌بینی و به راحتی قابل توسعه می‌سازد — افزودن یک نوع تحلیل جدید به معنای ایجاد یک زیرکلاس جدید VNRequest است.

import Vision

// 1. ایجاد درخواست
let request = VNDetectFaceRectanglesRequest { req, _ in
    // 3. پردازش نتایج
    guard let faces = req.results as? [VNFaceObservation]
    else { return }
    print("Found \\(faces.count) faces")
}

// 2. اجرا از طریق handler
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 و confidence می‌شود. VNDetectHumanRectanglesRequest — به همین ترتیب برای انسان‌ها. VNDetectHumanBodyPoseRequest — تشخیص حالت بدن انسان (نقاط اسکلت).

تحلیل متن

VNRecognizeTextRequest — بازشناسی متن با پشتیبانی از 13 زبان و دو سطح دقت. VNReadCodeRequest — برای کدهای تخصصی. VNDetectTextRectanglesRequest — جستجوی نواحی متن بدون بازشناسی (سریع‌تر، اما فقط مستطیل‌ها).

طبقه‌بندی و تحلیل

VNClassifyImageRequest — طبقه‌بندی تصویر بر اساس 1000 دسته ImageNet. VNGenerateImageFeaturePrintRequest — استخراج feature vector برای مقایسه تصاویر. VNDetectContoursRequest — تشخیص خطوط اشیاء.

VNImageRequestHandler و VNSequenceRequestHandler

VNImageRequestHandler — handler برای تصاویر استاتیک. CGImage، CIImage یا Data (JPEG/PNG) را قبول کرده و یک یا چند VNRequest را اجرا می‌کند. این روش اصلی استفاده از Vision برای عکس‌ها، نمایش‌های از صفحه و تصاویر آپلود شده است.

VNSequenceRequestHandler — handler برای توالی تصاویر (قاب‌های ویدیو). همان مجموعه نوع‌های تصویر را می‌پذیرد، اما برای پردازش قاب به قاب با حفظ وضعیت بین قاب‌ها (برای ردیابی اشیاء ضروری است) طراحی شده است.

// VNImageRequestHandler برای تک تصویر
let imageHandler = VNImageRequestHandler(
    cgImage: cgImage,
    orientation: orientation,
    options: [:])

// VNSequenceRequestHandler برای ویدیو
let sequenceHandler = VNSequenceRequestHandler()
try sequenceHandler.perform([trackingRequest],
    on: cgImage)

تفاوت مهم: VNSequenceRequestHandler از اجرای همزمان چند درخواست پشتیبانی نمی‌کند — هر تماس perform() یک مجموعه درخواست را برای یک قاب پردازش می‌کند. برای پردازش چند رشته‌ای ویدیو، نمونه‌های جداگانه handler را برای رشته‌های مختلف ایجاد کنید.

VNImageRequestHandler می‌تواند در صف پس‌زمینه اجرا شود. Apple DispatchQueue.global(qos: .userInitiated) را برای سناریوهای تعاملی (کاربر منتظر نتیجه است) و .background را برای پردازش دسته‌ای (مثل تحلیل کل کتابخانه عکس) توصیه می‌کند.

VNObservation: ساختار نتایج

VNObservation — کلاس پایه برای همه نتایج درخواست‌های Vision. هر زیرکلاس VNObservation داده‌های مخصوص نوع تحلیل را شامل می‌شود: مختصات bounding box، متن بازشناسی شده، اطمینان (confidence)، شناسه یکتا (uuid) و نشان زمان (timeRange).

زیرکلاس‌های کلیدی VNObservation: VNFaceObservation (نتیجه تشخیص چهره با bounding box و landmarks)، VNRecognizedTextObservation (متن بازشناسی شده با candidates)، VNBarcodeObservation (بارکد رمزگشایی شده با payload و symbology)، VNClassificationObservation (دسته طبقه‌بندی با confidence).

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 توصیه می‌کند مشاهدات با confidence < 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 کامل تحلیل چهره را در یک گذر دریافت می‌کنید.