Edge AI Interview: How to run face recognition on Raspberry Pi with a 5MB model?

In Edge AI interviews, the "5MB model limit" constraint serves as a hard threshold to screen candidates for an industrial deployment mindset. This requires developers to distinguish between 5MP camera hardware and 5MB model weights, forcing the abandonment of heavy server-side algorithms like Dlib or ResNet in favor of ultra-lightweight solutions. The core conclusion highlights the underestimated YuNet and SFace combination within the OpenCV ecosystem; this solution compresses the total face detection and recognition model size to approximately 3.3MB, bypassing storage limits and resolving the "dependency hell" common in embedded development. Unlike competitors requiring TensorFlow Lite or PyTorch Runtime, YuNet runs on Raspberry Pi's native OpenCV, achieving high FPS real-time inference on limited CPU power, representing the optimal balance of accuracy, speed, and deployment cost. Grasping this selection logic helps avoid confusing "input pixels" with "model size" and demonstrates mastery of the full pipeline from training to edge deployment, allowing you to stand out in technical competition.

Core Difficulty Analysis: The Difference Between 5MB Model Limits and 5MP Hardware

In Edge AI interview scenarios, when an interviewer throws out the "5MB limit," they are often testing the candidate's sensitivity to embedded resource constraints. Beginners easily mishear or misunderstand this as a common Raspberry Pi hardware specification—the 5MP (5 Megapixel) camera.

However, these two represent completely different dimensions in system design: one is the dimension of input data (hardware specification), and the other is the payload of the inference engine (software model). Confusing these two concepts is a "red line" error in interviews, directly exposing the candidate's unfamiliarity with the deep learning deployment process.

Concept Definition: Hardware Specifications vs. Software Constraints

To clearly define the problem boundaries, we need to distinguish these two concepts from the perspective of system resources.

Why is the "5MB Model" a Core Key Point?

On Raspberry Pi (especially Zero or early 3B+) and lower-power MCUs, storage space and memory bandwidth are extremely precious resources.

1. L2 Cache and Memory Swapping:
   Desktop GPUs can easily run a 500MB VGG-16 model, but on edge devices, huge model weights lead to frequent RAM reads or even trigger Swap, causing inference speed to drop from "real-time" to "seconds per frame." Keeping the model within 5MB (usually corresponding to quantized MobileNet or specially designed lightweight networks) means model weights have a better chance of residing in the CPU's high-speed cache, thereby significantly improving inference FPS.
2. The Reality of Industrial Deployment:
   Although Raspberry Pi typically uses SD cards, in actual industrial mass production (such as face recognition access control, attendance machines), devices may only have 16MB or 32MB of SPI Flash. After deducting the operating system and business code, the space left for the AI model is often around 5MB.
3. Distinguishing "Input" from "Weights":
   The interviewer emphasizes 5MB to imply that you must abandon traditional heavyweight models (like Dlib's ResNet-34) and opt for modern lightweight solutions such as TensorFlow Lite quantized models or OpenCV's YuNet. Even if you are using a 5MP OV5647 camera, images are usually Resized to $320 \times 320$ or $112 \times 112$ or even smaller before being fed into these 5MB models, so the camera's physical pixel count does not constitute a bottleneck for model volume.

Summary: When answering such questions, first clearly point out that "5MB" refers to the size of the model file, and immediately demonstrate your knowledge of model compression techniques (such as Quantization) or lightweight architectures (such as MobileFaceNet), rather than getting tangled up in camera clarity.

Selection Comparison: Finding a Truly Lightweight Face Recognition Model

On resource-constrained edge devices (such as Raspberry Pi), the "5MB model limit" is a hard threshold that directly filters out many solutions that perform excellently on servers or desktops. Mentioning this limit in an interview is usually intended to test whether the candidate understands the evolution from traditional computer vision methods to modern lightweight deep learning models, as well as their sensitivity to model footprint.

We need to find the optimal solution balancing model size, inference speed (FPS), and accuracy. Below is a performance comparison of several mainstream technical routes under the 5MB limit.

Candidate Solution Analysis

1. Haar Cascades (OpenCV Traditional Solution)

• • Status: This is the oldest solution, based on XML files defining features.
  • Size: Extremely small (a few hundred KB).
  • Drawbacks: Low accuracy, highly susceptible to lighting conditions, and unable to handle profile faces. Although it meets the 5MB limit, it is almost obsolete in modern applications.

1. Dlib (HOG / CNN)

• • Status: A regular in Python tutorials, based on the face_recognition library.
  • Size: Severely exceeds the limit. Dlib's 68-point landmark model (shapepredictor68facelandmarks.dat) is usually close to 100MB, and its ResNet face recognition model is also about 21MB.
  • Conclusion: Unless using an extremely cropped unofficial model, it cannot meet the 5MB requirement, and inference speed is slow on the Raspberry Pi CPU.

1. TFLite MobileFaceNet (Quantized Version)

• • Status: A lightweight network designed specifically for mobile devices.
  • Size: Through Model Quantization technology, FP32 models can be compressed to INT8, reducing the volume to around 1-2MB.
  • Advantages: Performs reasonably well on Raspberry Pi 4B when combined with XNNPACK acceleration.

1. OpenCV YuNet + SFace (Recommended)

• • Status: A lightweight CNN model natively integrated into OpenCV 4.x.
  • Size: YuNet (detection) is only about 300KB, and SFace (recognition) is about 3MB. The sum of the two is approximately 3.3MB, perfectly fitting the 5MB limit.
  • Advantages: OpenCV official tests show that YuNet is not only faster than the traditional Cascade but also has an order-of-magnitude improvement in accuracy.

Core Metrics Comparison Table (Based on Raspberry Pi 4B CPU)

Selection Conclusion

For the "5MB size limit" interview question, OpenCV YuNet (Detection) combined with SFace (Recognition) is currently the best standard answer.

Although traditional Haar cascade classifiers are small enough, they are no longer applicable due to accuracy issues; while the Dlib solution is classic, it completely fails to meet embedded constraints in terms of storage and memory usage. In contrast, YuNet, as a CNN model designed specifically for edge computing, utilizes depthwise separable convolutions to significantly reduce the number of parameters. It maintains high precision without requiring the installation of massive dependency libraries like PyTorch or TensorFlow, running with just standard OpenCV.

Why is OpenCV YuNet the Best Choice?

When answering questions like "5MB limit" in an interview, the interviewer is not just examining the size of the model file, but also your understanding of the Deployment Environment. Many candidates fall into a trap: finding a MobileNet or ShuffleNet model that is only 4MB, but overlooking that running it requires installing massive inference frameworks like PyTorch or TensorFlow.

For edge devices like the Raspberry Pi, OpenCV YuNet is currently the best solution balancing accuracy, speed, and deployment cost, mainly due to the following three technical dimensions:

1. True "Zero-Dependency"

This is YuNet's biggest killer feature. Configuring a deep learning environment on a Raspberry Pi is often referred to as "Dependency Hell":

• Pain Points of Traditional Solutions: To run a 4MB .tflite or .pth model, you might need to install TensorFlow Lite Runtime or PyTorch. These frameworks are not only tedious to install (often involving compiling source code), but the runtime libraries themselves consume hundreds of MB of storage and a large amount of RAM.
• YuNet Advantage: YuNet has been natively integrated into the cv::FaceDetectorYN module of OpenCV (since version 4.5.4). This means that as long as standard opencv-python is installed on your Raspberry Pi, you already possess the inference engine. You don't need to introduce hundreds of megabytes of framework overhead for a 5MB model, which is a highly persuasive architectural decision in embedded engineering.

2. Extreme Model Size and CPU Optimization

YuNet was designed from the start for real-time inference on CPUs. According to OpenCV's official test data, YuNet's model file (usually in ONNX format) is extremely lightweight:

• File Size: The standard version is only about 85KB - 300KB (depending on quantization). This is far below the 5MB limit given in the question and can even fit into the on-chip Flash of a microcontroller.
• Parameter Count: Only about 75,856 parameters. In comparison, high-performance models like RetinaFace have up to 27 million parameters, making them completely unsuitable for real-time running on a Raspberry Pi 3B/4B without GPU acceleration.
• Inference Speed: At an input resolution of 320x320, YuNet's inference latency on a standard CPU can be as low as around 5ms, whereas traditional Haar Cascades might require 25ms and offer lower accuracy.

3. Robustness Brought by Modern CNN Architecture

Despite its tiny size, YuNet is still a modern algorithm based on Convolutional Neural Networks (CNN), rather than outdated technologies based on handcrafted features like Haar or HOG.

• Anti-interference Ability: It effectively handles side faces, occlusions, and lighting changes, solving the persistent ailment of traditional OpenCV Haar cascade classifiers where "frontal faces are detected, but side faces are lost."
• Minimalist Deployment Code:
  It does not require complex preprocessing or model conversion scripts; the loading and inference code aligns very well with engineering intuition:

    import cv2 as cv

# Load model (file is only ~85KB)
    # Path points to the downloaded facedetectionyunet2023mar.onnx
    detector = cv.FaceDetectorYN.create(
        model='facedetectionyunet2023mar.onnx',
        config="",
        inputsize=(320, 320),
        scorethreshold=0.9,
        nmsthreshold=0.3,
        topk=5000
    )

# Inference
    img = cv.imread('image.jpg')
    detector.setInputSize((img.shape[1], img.shape[0]))
    faces = detector.detect(img)

Summary for Interview:
When asked about the reason for selection, you should emphasize: "Although MobileFaceNet or TFLite are also lightweight choices, under the strict 5MB limit, YuNet is the only solution that simultaneously satisfies 'extremely small model file' and 'zero runtime environment burden'. It can run using the existing OpenCV library on the Raspberry Pi, avoiding the introduction of heavy deep learning frameworks, making it the optimal solution for face detection on edge devices with limited computing power."

Practical Deployment: Running YuNet on Raspberry Pi 4B

Deploying AI models on edge devices, the biggest pain point is often not the code logic, but the environment setup. Many old tutorials still guide users to compile OpenCV from source, which is not only time-consuming on the Raspberry Pi (potentially taking hours) but also prone to errors due to missing dependencies.

To quickly verify the feasibility of that "5MB model," we adopt the most streamlined modern Python workflow. We will use pre-compiled wheel packages and utilize a Python Virtual Environment to avoid conflicts with the Raspberry Pi OS system-level Python libraries (this is the best practice following the implementation of the PEP 668 standard).

Environment Setup and Directory Structure

First, ensure your Raspberry Pi system is up to date and install necessary system-level dependencies:

sudo apt update && sudo apt install -y libatlas-base-dev

Next, create the project directory and initialize the virtual environment. It is strongly recommended not to use sudo pip install directly, as this will damage the system environment.

mkdir edgefacedetect
cd edgefacedetect
python3 -m venv venv
source venv/bin/activate

After activating the virtual environment, install the lightweight version of OpenCV. For pure inference tasks (where no GUI window display is needed, or streaming via Web), opencv-python-headless is the best choice. It removes massive GUI dependencies like Qt, resulting in a smaller size and faster loading:

pip install --upgrade pip
pip install opencv-python-headless numpy

Finally, you need to prepare the model file. The YuNet ONNX model file is very small (about 300KB, far less than the 5MB limit in the interview question), making it very suitable for edge computing. You can download facedetectionyunet_2023mar.onnx from the OpenCV Zoo repository.

The recommended project directory structure is as follows:

edgefacedetect/
├── main.py                 # Inference main program
├── models/
│   └── facedetectionyunet_2023mar.onnx  # Downloaded ONNX model
└── venv/                   # Virtual environment directory

Core Code Implementation: Model Loading and Inference

The core of running YuNet on the Raspberry Pi lies in using the cv2.FaceDetectorYN class of OpenCV. Compared to traditional Haar Cascades, YuNet is based on CNNs, making it more robust when dealing with side faces, occlusions, and lighting changes, and it is optimized for CPUs.

Below is a complete, directly runnable Python script. Please pay attention to the handling of Input Size in the code: the model's input size must be strictly consistent with the image size during inference, otherwise detection will fail or errors will occur.

import cv2
import numpy as np
import time

# Configuration parameters
MODELPATH = "models/facedetectionyunet2023mar.onnx"
# Lowering inference resolution is key to improving FPS.
# 320x320 usually achieves 30+ FPS on Raspberry Pi 4B and is accurate enough for close-range face detection.
INPUTSIZE = (320, 320) 
SCORETHRESHOLD = 0.6  # Confidence threshold: Filter out false detections with low confidence
NMSTHRESHOLD = 0.3    # NMS threshold: Remove overlapping detection boxes

def main():
    # 1. Instantiate YuNet detector
    # The inputsize here is just for initialization; it can be dynamically adjusted via setInputSize when processing each frame
    detector = cv2.FaceDetectorYN.create(
        model=MODELPATH,
        config="",
        inputsize=INPUTSIZE,
        scorethreshold=SCORETHRESHOLD,
        nmsthreshold=NMSTHRESHOLD,
        topk=5000
    )

# 2. Open camera (Index 0 is usually a USB camera or libcamera mapping)
    cap = cv2.VideoCapture(0)
    if not cap.isOpened():
        print("Error: Cannot open camera.")
        return

# Set camera hardware capture resolution (recommended 640x480 to reduce bus bandwidth pressure)
    cap.set(cv2.CAPPROPFRAMEWIDTH, 640)
    cap.set(cv2.CAPPROPFRAMEHEIGHT, 480)

print(f"Model loaded: {MODELPATH}")
    print("Starting inference... Press Ctrl+C to stop.")

try:
        while True:
            ret, frame = cap.read()
            if not ret:
                break

# 3. Preprocessing: Resize image to match model inference size
            # Using raw 1080p or 720p images directly for inference will severely slow down FPS
            frameresized = cv2.resize(frame, INPUTSIZE)

# Critical step: Before every inference, ensure detector input size matches current image
            detector.setInputSize(INPUTSIZE)

# 4. Perform inference
            starttime = time.time()
            # faces output format: [x1, y1, w, h, xre, yre, xle, yle, ...] (bounding box + keypoints)
            results = detector.detect(frameresized)
            endtime = time.time()

fps = 1 / (endtime - starttime)

# 5. Process results (if faces are detected)
            faces = results[1]
            if faces is not None:
                for face in faces:
                    # Get bounding box coordinates (based on resized image)
                    box = face[0:4].astype(int)

# Print log instead of imshow (adapted for headless environment)
                    print(f"Face detected: {box} | Confidence: {face[-1]:.2f} | FPS: {fps:.1f}")

except KeyboardInterrupt:
        print("Stopped by user.")
    finally:
        cap.release()

if name == "main_":
    main()

Code Analysis and Interview Points:

• cv2.FaceDetectorYN.create: This is the standard entry point for loading YuNet. A common interview question is how to load ONNX models; OpenCV's DNN module has encapsulated this very well, eliminating the need to install the ONNXRuntime library.
• detector.setInputSize: This is a common "pitfall." YuNet is a fully convolutional network and theoretically supports dynamic sizes, but in OpenCV's implementation, you must explicitly tell the detector the current input image size (width, height) before inference, otherwise it will cause an assertion error.
• The Trade-off of Resize: The code resizes the image to 320x320 for inference. Although the Raspberry Pi camera may support 5MP (2592×1944), inputting full-resolution images directly will drop the FPS to single digits. For face detection tasks, low resolution usually contains sufficient feature information.

Core Code Implementation: Loading the Model and Inference

After configuring the environment, we need to write a Python script to call OpenCV's DNN module to perform inference. For interview scenarios on edge devices, demonstrating the conciseness and robustness of the code is equally important.

The following is a complete inference script example. This script directly loads the YuNet ONNX model, opens the camera video stream, and detects faces in every frame. To achieve a smooth frame rate on the Raspberry Pi 4B, we scale the input image before inference, which is a key step in balancing accuracy and speed.

Complete Code Example

Place the downloaded .onnx model file (e.g., facedetectionyunet_2023mar.onnx) in the same directory as the code, and run the following script:

import cv2
import numpy as np

# Model configuration parameters
# The model path here needs to be modified according to the actual downloaded filename
modelpath = "./facedetectionyunet2023mar.onnx"
# Set confidence threshold: results below 0.9 will be filtered (can be adjusted based on ambient light during the interview, usually 0.6-0.9)
scorethreshold = 0.9
# NMS (Non-Maximum Suppression) threshold: used to remove overlapping detection boxes; 0.3 means suppression if overlap exceeds 30%
nmsthreshold = 0.3
# Input size for inference: 320x320 is the golden size for YuNet on edge devices, offering very fast speed and acceptable accuracy
inputsize = (320, 320)

# 1. Initialize YuNet detector
# Note: Only OpenCV 4.5.4+ versions natively support FaceDetectorYN
detector = cv2.FaceDetectorYN.create(
    model=modelpath,
    config="",
    inputsize=inputsize,
    scorethreshold=scorethreshold,
    nmsthreshold=nmsthreshold,
    topk=5000,
    backendid=cv2.dnn.DNNBACKENDOPENCV,
    targetid=cv2.dnn.DNNTARGETCPU
)

# 2. Open camera (0 represents the default USB or CSI camera)
cap = cv2.VideoCapture(0)
# Set camera hardware capture resolution (recommended to set to 640x480 to reduce transmission bandwidth consumption)
cap.set(cv2.CAPPROPFRAMEWIDTH, 640)
cap.set(cv2.CAPPROPFRAMEHEIGHT, 480)

if not cap.isOpened():
    print("Cannot open camera")
    exit()

print("Starting inference, press 'q' to exit...")

while True:
    ret, frame = cap.read()
    if not ret:
        break

# Get the actual size of the current frame
    h, w,  = frame.shape

# 3. Key step: Update the detector's input size
    # YuNet requires explicit setting of input size. If we feed the original image directly, we need to inform the detector before inference
    # But for performance, we usually don't resize the frame directly, but let the detector handle it internally,
    # or explicitly resize the image here (if extreme speed is needed)
    detector.setInputSize((w, h))

# 4. Perform inference
    # faces output format: [x1, y1, w, h, xre, yre, xle, yle, xnt, ynt, xrcm, yrcm, xlcm, ylcm, score]
    # Contains bounding box and 5 key points (right eye, left eye, nose tip, right mouth corner, left mouth corner)
    results = detector.detect(frame)
    faces = results[1]

# 5. Draw detection results
    if faces is not None:
        for face in faces:
            # Extract bounding box coordinates (convert to integer)
            box = face[0:4].astype(np.int32)

# Draw rectangle
            cv2.rectangle(frame, (box[0], box[1]), (box[0]+box[2], box[1]+box[3]), (0, 255, 0), 2)

# Display confidence score
            score = face[-1]
            cv2.putText(frame, f"{score:.2f}", (box[0], box[1] - 10), 
                        cv2.FONTHERSHEYSIMPLEX, 0.5, (0, 255, 0), 2)

# Display the frame
    cv2.imshow('Raspberry Pi Edge AI - YuNet', frame)

# Press 'q' to exit
    if cv2.waitKey(1) & 0xFF == ord('q'):
        break

cap.release()
cv2.destroyAllWindows()

Code Key Points Analysis

When explaining this code during an interview, focus on the following technical details to reflect your understanding of edge computing characteristics:

1. cv2.FaceDetectorYN.create: This is the standard way to load pre-trained models in OpenCV Zoo. Compared to traditional Haar cascade classifiers (loading XML files), YuNet is a CNN-based model. Although the file size is small (<5MB), its robustness against side faces and occlusions is far higher than the former.
2. score_threshold and nms_threshold:

• • Score Threshold: Determines how "confident" the model must be to consider a face detected. On devices with limited computing power like the Raspberry Pi, appropriately increasing this value (e.g., 0.8-0.9) can reduce false detections and avoid processing invalid data subsequently.
  • NMS Threshold: Controls the logic for removing overlapping boxes. If faces are dense in the frame, you can appropriately increase it; if it is a single-person clock-in scenario, keeping the default is fine.

1. detector.setInputSize: This is a "pitfall" that is easily overlooked. YuNet's input layer size is dynamic, but it must be set explicitly before inference. If you change the camera resolution or scale the image in the code, you must update this parameter synchronously, otherwise it will report an error or cause the detection rate to drop sharply.
2. Backend and Target: The code explicitly specifies DNNTARGETCPU. Although the Raspberry Pi does not have a powerful GPU, OpenCV has specific NEON instruction set optimizations for ARM architecture CPUs (such as the Raspberry Pi's Cortex-A72). Ensure that the version installed via pip install opencv-python or compiled by yourself has NEON support enabled, which is crucial for achieving real-time frame rates on the CPU.

Tip: If you run the above code directly and find the frame rate is only 5-10 FPS, do not rush to change the hardware. In the next section, we will discuss how to increase the frame rate to a real-time 30 FPS by adjusting the core variable of input resolution, without sacrificing too much detection capability.

Performance Optimization: How to Boost FPS to Real-Time Levels

In edge device interviews, interviewers often set a trap like this: "Since the model is only 5MB, why does my Raspberry Pi only run at 2 FPS?"

This is usually not a problem with the model itself, but is caused by improper configuration of Input Resolution and Inference Backend. To make lightweight models like YuNet achieve real-time levels (usually >24 FPS) on a Raspberry Pi 4B, optimization is needed in the following three dimensions.

1. Trade-off Between Input Resolution and Accuracy

The most common mistake beginners make is feeding the raw high-resolution images captured by the camera directly into the model. Raspberry Pi cameras (such as V1/V2 modules) typically output 5-megapixel (2592×1944) or even higher resolution images by default.

• Problem: Even if the model weight file is small (<5MB), the computational load (FLOPs) of a Convolutional Neural Network increases quadratically with the width and height of the input image. Processing a 1080p or 5MP image will cause inference time to surge to hundreds of milliseconds.
• Solution: You must use cv2.resize to downsample the image before inference.
• • 320×320: Extreme speed. According to official OpenCV tests, YuNet's inference time at 320×320 resolution is only about 5ms, which is very suitable for close-range face detection.
  • 640×640: General balance point. If you need to detect faces at a slightly further distance, increasing the resolution to around 640 will increase inference time to about 22ms, but it will still remain within the real-time range.

Practical Code:

# Wrong approach: Use raw frame directly
# faces = detector.detect(frame)

# Correct approach: Resize inference dimensions (does not affect display dimensions)
h, w,  = frame.shape
inferencescale = 320 / max(h, w) # Maintain aspect ratio scaling
inputw = int(w * inferencescale)
inputh = int(h * inferencescale)

# Set model input size
detector.setInputSize([inputw, inputh])

2. Enable OpenCV Hardware Acceleration Instruction Sets

On Raspberry Pi, OpenCV's default backend is usually efficient enough, but explicitly specifying the backend can prevent the code from falling back to general computation mode.

Ensure that OpenCV utilizes the ARM processor's NEON instruction set to accelerate floating-point operations. Modern pip install opencv-python-headless pre-compiled packages usually include this optimization, but you need to pay attention when compiling from source. At the code level, you should explicitly set the DNN backend:

# Force use of OpenCV CPU backend (optimized for ARM)
detector.setPreferableBackend(cv2.dnn.DNNBACKENDOPENCV)
detector.setPreferableTarget(cv2.dnn.DNNTARGETCPU)

For scenarios pursuing extreme performance, you can try dedicated inference frameworks like TFLite or NCNN, but in an interview, demonstrating how to tap into OpenCV's native potential is usually enough to prove your engineering capabilities.

3. Raspberry Pi 4B Performance Benchmark Reference

Providing specific data in an interview can greatly increase credibility. The expected performance of running YuNet on a Raspberry Pi 4B (4GB/8GB RAM version) is as follows:

Summary Strategy: To run at a full 30 FPS on Raspberry Pi, you must lock the detection model's input at the 320p or 640p level, while utilizing Python multithreading (such as imutils.FileVideoStream or Picamera2's asynchronous capture) to parallelize image reading and model inference, thereby masking I/O latency.

Pitfall Guide: Common Errors and Debugging

In interviews or actual engineering deployment, interviewers often ask if you have encountered "environmental pitfalls" unique to edge devices. When deploying lightweight face recognition models (such as YuNet) on a Raspberry Pi, the code logic is usually simple, but hardware configuration and dependency environments are often the root cause of project failure. Here are the three most common obstacles and their solutions.

1. AttributeError Caused by OpenCV Version

Many developers habitually use sudo apt install python3-opencv to install OpenCV, which usually installs older versions like 3.x or 4.2 on older Raspberry Pi OS versions. However, the lightweight face detection interface cv2.FaceDetectorYN was only introduced after OpenCV 4.5.4.

• Symptom: Running the code results in the error AttributeError: module 'cv2' has no attribute 'FaceDetectorYN_create'.
• Debugging & Fix:
• • Check Version: Run python3 -c "import cv2; print(cv2.version)". If the version is lower than 4.5, you must upgrade.
  • Correct Installation: It is recommended to uninstall the system-bundled package and use pip to install the pre-compiled headless version (no GUI dependencies, smaller size, and better compatibility):

        pip3 uninstall opencv-python
        pip3 install opencv-python-headless

• • Note: In the latest Raspberry Pi OS (Bookworm), the system enforces the use of virtual environments. If you encounter error: externally-managed-environment, please create a virtual environment before performing the pip installation.

2. Camera Failure to Start (Legacy Stack vs. Libcamera)

Starting from the Bullseye version, Raspberry Pi OS migrated the underlying video stack from the traditional Legacy Camera to a new architecture based on libcamera. This causes many old codes based on cv2.VideoCapture(0) to fail to run directly.

• Symptom: The program does not report an error but the screen is black, or it prompts [WARN:0] global /tmp/buildopencv/.../capv4l.cpp (890) open VIDEOIO(V4L2:/dev/video0): can't open camera by index.
• Debugging & Fix:
• • Hardware Connection Check: First, rule out physical faults. The CSI ribbon cable connection has directionality; ensure the metal contacts are facing correctly (the interface direction may differ between Pi 4 and Pi 5, so check carefully when connecting).
  • Enable Legacy Mode (For Old OS): If using an older version of OpenCV on a Bullseye system, you usually need to enable legacy support via sudo raspi-config -> Interface Options -> Legacy Camera and reboot.
  • Bookworm System Adaptation: In the latest Bookworm system, it is recommended to use the official compatibility layer or ensure OpenCV is linked with V4L2 support during compilation. You can test if the camera is recognized by the system using the command line tool libcamera-hello.

3. Under-voltage Throttling

Face recognition models momentarily spike CPU usage during the inference phase. If the power supply is insufficient, the Raspberry Pi will force frequency throttling, causing inference speed to plummet from a normal 30ms to 200ms+, or even causing a system reboot.

• Symptom: A yellow lightning icon appears in the top right corner of the screen, or inference FPS is extremely unstable.
• Debugging & Fix:
• • Diagnostic Command: Run vcgencmd get_throttled in the terminal. If the return value is not 0x0 (e.g., 0x50005), it indicates the system has experienced under-voltage or is currently in an under-voltage state.
  • Solution: You must use an official power adapter (Pi 4 needs 5.1V/3A, Pi 5 needs 5V/5A PD power). Avoid directly using computer USB ports for power, as their current is usually insufficient to support peak power consumption during AI inference.