चेहरा खोज 1:N चेतावनियाँ और एरर कोड

अवलोकन

चेहरा खोज चेतावनियों का एक छोटा सेट जारी करता है ताकि आपकी टीम यह समझ सके कि किसी खोज ने Approved या Declined परिणाम क्यों दिया। चेतावनियाँ POST /v3/face-search/ रिस्पॉन्स के face_search.warnings[] ऐरे में लौटाई जाती हैं (देखें चेहरा खोज रिपोर्ट)। यहाँ चेतावनियाँ वर्कफ़्लो चेतावनियों की तुलना में कम फ़ील्ड वाले फ़ॉर्मैट का उपयोग करती हैं: इसमें कोई node_id नहीं होता है। प्रलेखित रिस्पॉन्स अनुबंध पाँच फ़ील्ड्स घोषित करता है — risk, additional_data, log_type, short_description, long_description — और रनटाइम payload अतिरिक्त रूप से feature ले जाता है, जो इस endpoint पर हमेशा "LIVENESS" होता है।

जनरेट की गई चेतावनियाँ

जोखिम	कारण	गंभीरता (`log_type`)	स्थिति को प्रभावित करता है	अनुशंसित समाधान
`FACE_IN_BLOCKLIST`	खोजी गई छवि आपके एप्लिकेशन की चेहरा ब्लॉकलिस्ट में मौजूद किसी चेहरे से उच्च-विश्वास समानता बैंड से ऊपर मेल खाती है।	`error`	स्थिति को `Declined` कर देता है।	उपयोगकर्ता को अस्वीकार करें। `additional_data.blocklisted_session_id` के माध्यम से लिंक किए गए सत्र की जांच करें।
`POSSIBLE_FACE_IN_BLOCKLIST`	एक ब्लॉकलिस्टेड चेहरा उच्च-विश्वास बैंड के नीचे, निचले “संभावित” समानता बैंड के भीतर मेल खाता है।	`error`	स्टैंडअलोन चेहरा खोज API पर स्थिति को `Declined` कर देता है (वर्कफ़्लो लाइवनेस जांच की तुलना में अधिक सख्त, जो इस जोखिम को समीक्षा के लिए भेजता है)।	मैन्युअल समीक्षा। कार्रवाई करने से पहले मूल ब्लॉकलिस्ट साक्ष्य के विरुद्ध मिलान की पुष्टि करें।
`MULTIPLE_FACES_DETECTED`	सबमिट की गई खोज छवि में एक से अधिक चेहरे पाए गए। सबसे बड़े पाए गए चेहरे का उपयोग करते हुए खोज अभी भी चलती है।	`warning`	कोई नहीं — अपने आप कभी अस्वीकृत नहीं करता।	यदि सबसे बड़ा चेहरा वह नहीं है जो लक्षित था, तो फ़्रेम में केवल एक व्यक्ति के साथ पुनः कैप्चर करें।
`DUPLICATED_FACE`	चेहरा, उच्च-विश्वास बैंड से ऊपर, किसी स्वीकृत सत्र के चेहरे या इंपोर्ट किए गए उपयोगकर्ता-प्रोफ़ाइल चेहरे से मेल खाता है। स्टैंडअलोन endpoint समान-`vendor_data` वाले सत्रों को बाहर नहीं करता है, इसलिए लौटने वाला उपयोगकर्ता अपने स्वयं के पुराने सत्रों से मेल खा जाता है।	`information`	कोई नहीं — डुप्लिकेट को संकेत के रूप में दिखाया जाता है, अस्वीकृति के रूप में नहीं।	`additional_data.duplicated_session_id` के माध्यम से लिंक किए गए सत्र की जांच करें। तय करें कि अपनी ओर से खातों को ब्लॉक करना है या मर्ज करना है।
`POSSIBLE_DUPLICATED_FACE`	`DUPLICATED_FACE` के समान, लेकिन समानता उच्च-विश्वास बैंड के बजाय निचले “संभावित” बैंड में आती है।	`information`	कोई नहीं।	दोनों रिकॉर्ड्स को एक ही व्यक्ति मानने से पहले मैन्युअल समीक्षा करें।

निर्माता: FaceSearchAPIView.add_warnings (apis/views/face_search.py:250-330); स्थिति निर्धारण: get_face_search_status (apis/views/face_search.py:242-248), जो केवल दो ब्लॉकलिस्ट जोखिमों के लिए अस्वीकार करता है। जानने योग्य उत्सर्जन नियम:

ब्लॉकलिस्ट को डुप्लिकेट पर प्राथमिकता मिलती है। एक पुष्ट ब्लॉकलिस्ट मिलान DUPLICATED_FACE को दबा देता है, और एक संभावित ब्लॉकलिस्ट मिलान POSSIBLE_DUPLICATED_FACE को दबा देता है — आपको समान विश्वास बैंड के लिए कभी भी एक युग्म के दोनों सदस्य नहीं मिलते हैं।
additional_data केवल पहले मेल खाने वाले चेहरे को संदर्भित करता है, भले ही matches[] में कई चेहरे हों। ब्लॉकलिस्ट चेतावनियाँ {blocklisted_session_id, blocklisted_session_number, api_service} ले जाती हैं; डुप्लिकेट चेतावनियाँ {duplicated_session_id, duplicated_session_number, api_service} ले जाती हैं; MULTIPLE_FACES_DETECTED में null होता है। api_service का मान बड़े अक्षरों में होता है (जैसे PASSIVE_LIVENESS) या वर्कफ़्लो सत्रों के लिए null होता है।
अनुमति सूची (allowlist) में शामिल चेहरे डुप्लिकेट चेतावनियों को दबा देते हैं — एक उच्च-विश्वास अनुमति सूची मिलान DUPLICATED_FACE/POSSIBLE_DUPLICATED_FACE को हटा देता है (यह ब्लॉकलिस्ट चेतावनियों को कभी नहीं हटाता है)।

सटीक चेतावनी स्ट्रिंग्स

जोखिम	`short_description`	`long_description`
`FACE_IN_BLOCKLIST`	ब्लॉकलिस्ट में चेहरा	सिस्टम ने ब्लॉकलिस्ट में एक चेहरे की पहचान की, जिसका अर्थ है कि चेहरे को सत्यापित करने की अनुमति नहीं है।
`POSSIBLE_FACE_IN_BLOCKLIST`	ब्लॉकलिस्ट में संभावित चेहरा	सिस्टम ने ब्लॉकलिस्ट में एक संभावित चेहरे की पहचान की, जिसका अर्थ है कि चेहरे को सत्यापित करने की अनुमति नहीं है।
`DUPLICATED_FACE`	अन्य स्वीकृत सत्र से डुप्लिकेट चेहरा	सिस्टम ने किसी अन्य स्वीकृत सत्र से डुप्लिकेट चेहरे की पहचान की, जिसके लिए आगे की जांच की आवश्यकता है।
`POSSIBLE_DUPLICATED_FACE`	अन्य स्वीकृत सत्र से संभावित डुप्लिकेट चेहरा	सिस्टम ने किसी अन्य स्वीकृत सत्र से संभावित डुप्लिकेट चेहरे की पहचान की, जिसके लिए आगे की जांच की आवश्यकता है।
`MULTIPLE_FACES_DETECTED`	कई चेहरे पाए गए	लाइवनेस छवि में कई चेहरे पाए गए। सिस्टम लाइवनेस सत्यापन और चेहरे की तुलना के लिए सबसे बड़े चेहरे का उपयोग करता है, लेकिन कई चेहरों की उपस्थिति के लिए अतिरिक्त समीक्षा की आवश्यकता हो सकती है।

खोज-छवि गेट

जब user_image में कोई चेहरा नहीं पाया जाता है, तो API face_search ऑब्जेक्ट बनने से पहले ही HTTP 400 और {"error": "No face detected in the image"} के साथ अनुरोध को अस्वीकार कर देता है — इसलिए एक सफल चेहरा खोज रिस्पॉन्स में NO_FACE_DETECTED चेतावनी कभी दिखाई नहीं देती। यह शीर्ष-स्तरीय error स्ट्रिंग के रूप में लौटाया जाता है, warnings[] में नहीं।

कॉन्फ़िगर करने योग्य सेटिंग्स

समानता बैंड जो पुष्ट मिलानों (FACE_IN_BLOCKLIST, DUPLICATED_FACE) को संभावित मिलानों (POSSIBLE_FACE_IN_BLOCKLIST, POSSIBLE_DUPLICATED_FACE) से अलग करते हैं, आंतरिक रूप से तय होते हैं — प्रति-एप्लिकेशन थ्रेशोल्ड ट्यूनिंग वर्कफ़्लो लाइवनेस जांच पर लागू होती है, इस endpoint पर नहीं। प्रति अनुरोध आपके द्वारा नियंत्रित किए जाने वाले स्विच हैं:

search_type (most_similar, डिफ़ॉल्ट | blocklisted_or_approved) — most_similar समानता के आधार पर प्रत्येक नामांकित चेहरे को रैंक करता है; blocklisted_or_approved उम्मीदवारों को ब्लॉकलिस्ट किए गए चेहरों, अनुमति सूची में शामिल चेहरों, स्वीकृत सत्रों के चेहरों और इंपोर्ट किए गए उपयोगकर्ता-प्रोफ़ाइल चेहरों तक सीमित करता है, जिसमें ब्लॉकलिस्ट की गई प्रविष्टियों को पहले रैंक किया जाता है।
save_api_request (डिफ़ॉल्ट true) — कॉल को API-प्रकार के सत्र के रूप में सुरक्षित रखता है और खोजे गए चेहरे को आपके चेहरा खोज इंडेक्स में नामांकित करता है। चेहरा खोज कॉलों द्वारा नामांकित चेहरों को भविष्य के चेहरा खोज परिणामों से बाहर रखा जाता है। बिना स्टोर या नामांकित किए क्वेरी करने के लिए इसे false पर सेट करें।
rotate_image (डिफ़ॉल्ट false) — 90-डिग्री घुमाव का प्रयास करता है और सर्वोत्तम चेहरा पहचान वाले ओरिएंटेशन को रखता है; तब उपयोगी होता है जब EXIF ओरिएंटेशन अनुपलब्ध हो।

उदाहरण

ब्लॉकलिस्ट हिट (`Declined` स्थिति कर देता है)

{
  "warnings": [
    {
      "risk": "FACE_IN_BLOCKLIST",
      "feature": "LIVENESS",
      "additional_data": {
        "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "blocklisted_session_number": 323442,
        "api_service": "PASSIVE_LIVENESS"
      },
      "log_type": "error",
      "short_description": "Face in blocklist",
      "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
    }
  ]
}

डुप्लिकेट सिग्नल (स्थिति `Approved` बनी रहती है)

{
  "warnings": [
    {
      "risk": "MULTIPLE_FACES_DETECTED",
      "feature": "LIVENESS",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "Multiple faces detected",
      "long_description": "Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review."
    },
    {
      "risk": "DUPLICATED_FACE",
      "feature": "LIVENESS",
      "additional_data": {
        "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
        "duplicated_session_number": 1024,
        "api_service": null
      },
      "log_type": "information",
      "short_description": "Duplicated face from other approved session",
      "long_description": "The system identified a duplicated face from another approved session, requiring further investigation."
    }
  ]
}

प्रमाणीकरण

सत्यापन

निगरानी

प्लेटफ़ॉर्म

चेहरा खोज 1:N चेतावनियाँ और एरर कोड

अवलोकन

जनरेट की गई चेतावनियाँ

सटीक चेतावनी स्ट्रिंग्स

खोज-छवि गेट

कॉन्फ़िगर करने योग्य सेटिंग्स

उदाहरण

ब्लॉकलिस्ट हिट (`Declined` स्थिति कर देता है)

डुप्लिकेट सिग्नल (स्थिति `Approved` बनी रहती है)

संबंधित

चेतावनी प्रकार

​अवलोकन

​जनरेट की गई चेतावनियाँ

​सटीक चेतावनी स्ट्रिंग्स

​खोज-छवि गेट

​कॉन्फ़िगर करने योग्य सेटिंग्स

​उदाहरण

​ब्लॉकलिस्ट हिट (Declined स्थिति कर देता है)

​डुप्लिकेट सिग्नल (स्थिति Approved बनी रहती है)

​संबंधित

​चेतावनी प्रकार

अवलोकन

जनरेट की गई चेतावनियाँ

सटीक चेतावनी स्ट्रिंग्स

खोज-छवि गेट

कॉन्फ़िगर करने योग्य सेटिंग्स

उदाहरण

ब्लॉकलिस्ट हिट (`Declined` स्थिति कर देता है)

डुप्लिकेट सिग्नल (स्थिति `Approved` बनी रहती है)

संबंधित

चेतावनी प्रकार