YOLO11 顔検出システム — 設定ガイド

概要

YOLO11 顔検出システムは、YAML 設定ファイルと環境変数による階層型の設定管理方式を採用しています。設定は優先度に基づく上書きの仕組みを採用しており、開発・テスト・本番などの複数のデプロイ環境に対応し、柔軟な設定管理とデプロイを実現します。

⚙️ 設定の階層

設定の優先度（高い順）：

1. 実行時の設定更新 - API インターフェースによる動的な変更
2. システム環境変数 - システムレベルの環境変数
3. YAML 設定ファイル - 基本設定ファイル
4. コードのデフォルト値 - ハードコードされたデフォルト値

メイン設定ファイル

ファイルの場所

• メイン設定： config/face_config.yaml
• 設定管理： config/config_manager.py

完全な設定例

# 人脸检测应用配置文件
# Face Detection Application Configuration

# 应用基本信息
app:
  name: "人脸检测应用"
  version: "1.0.0"
  environment: "development"

# 服务器配置
server:
  host: "0.0.0.0"
  port: 8003
  debug: false

# 日志配置
logging:
  level: "INFO"
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

# 模型配置
model:
  # 模型文件路径（相对于项目根目录）
  path: "models/yolo11n_face_detect_bayese_320x320_nv12.bin"
  # 置信度阈值
  confidence_threshold: 0.6
  # IOU阈值
  iou_threshold: 0.45

# 摄像头配置
camera:
  # 设备ID（0为默认摄像头）
  device_id: 0
  # 分辨率
  width: 640
  height: 480
  # 帧率
  fps: 30
  # 是否使用异步捕获线程
  async_capture: true

# Web界面配置
web:
  # 视频流质量 (1-100)
  video_quality: 80
  # 视频流帧率
  stream_fps: 15
  # 是否显示检测框
  show_detection_boxes: true
  # 是否显示中心点
  show_center_point: true
  # 是否显示统计信息
  show_stats: true

# 检测配置
detection:
  # 检测类别名称
  class_names: ["face"]
  # 检测框颜色 (BGR格式)
  box_color: [0, 255, 0]  # 绿色
  # 文本颜色
  text_color: [255, 255, 255]  # 白色
  # 线条粗细
  line_thickness: 2
  # 字体大小
  font_scale: 0.6

環境変数による設定

対応している環境変数

環境変数の一覧

# 服务器配置
FACE_SERVER_HOST=0.0.0.0          # 服务监听地址
FACE_SERVER_PORT=8003             # 服务端口号
FACE_SERVER_DEBUG=false           # 调试模式

# 应用配置
FACE_APP_NAME="人脸检测应用"        # 应用名称
FACE_APP_VERSION="1.0.0"          # 应用版本
FACE_APP_ENVIRONMENT=production    # 运行环境

# 模型配置
FACE_MODEL_PATH=/path/to/model.bin # 模型文件路径
FACE_MODEL_CONFIDENCE=0.6          # 置信度阈值
FACE_MODEL_IOU=0.45               # IOU阈值

# 摄像头配置
FACE_CAMERA_DEVICE=0              # 摄像头设备ID
FACE_CAMERA_WIDTH=640             # 摄像头宽度
FACE_CAMERA_HEIGHT=480            # 摄像头高度
FACE_CAMERA_FPS=30                # 摄像头帧率
FACE_CAMERA_ASYNC=true            # 异步捕获模式

# Web界面配置
FACE_WEB_QUALITY=80               # 视频流质量
FACE_WEB_STREAM_FPS=15            # 视频流帧率
FACE_WEB_SHOW_BOXES=true          # 显示检测框
FACE_WEB_SHOW_CENTER=true         # 显示中心点
FACE_WEB_SHOW_STATS=true          # 显示统计信息

# 日志配置
FACE_LOG_LEVEL=INFO               # 日志级别
FACE_LOG_FORMAT="%(asctime)s - %(name)s - %(levelname)s - %(message)s"

環境変数の使用例

Docker でのデプロイ例

# Dockerfile示例
FROM python:3.9-slim

# 设置环境变量
ENV FACE_SERVER_HOST=0.0.0.0
ENV FACE_SERVER_PORT=8003
ENV FACE_SERVER_DEBUG=false
ENV FACE_MODEL_PATH=/app/models/yolo11n_face_detect_bayese_320x320_nv12.bin
ENV FACE_CAMERA_DEVICE=0
ENV FACE_LOG_LEVEL=INFO

# 复制应用文件
COPY . /app
WORKDIR /app

# 安装依赖
RUN pip install -r requirements.txt

# 启动应用
CMD ["python", "main.py"]

Docker Compose の例

version: '3.8'
services:
  face-detection:
    build: .
    ports:
      - "8003:8003"
    devices:
      - /dev/video0:/dev/video0  # 摄像头设备
    environment:
      FACE_SERVER_HOST: "0.0.0.0"
      FACE_SERVER_PORT: 8003
      FACE_SERVER_DEBUG: "false"
      FACE_MODEL_CONFIDENCE: 0.7
      FACE_CAMERA_DEVICE: 0
      FACE_WEB_QUALITY: 90
      FACE_LOG_LEVEL: "INFO"
    volumes:
      - ./models:/app/models
      - ./logs:/app/logs

システムサービスの例

# /etc/systemd/system/face-detection.service
[Unit]
Description=YOLO11 Face Detection Service
After=network.target

[Service]
Type=simple
User=face-detection
WorkingDirectory=/opt/face-detection
ExecStart=/opt/face-detection/venv/bin/python main.py
Restart=always
RestartSec=10

# 环境变量
Environment=FACE_SERVER_HOST=0.0.0.0
Environment=FACE_SERVER_PORT=8003
Environment=FACE_MODEL_PATH=/opt/face-detection/models/yolo11n_face_detect_bayese_320x320_nv12.bin
Environment=FACE_CAMERA_DEVICE=0
Environment=FACE_LOG_LEVEL=INFO

[Install]
WantedBy=multi-user.target

設定項目の詳細説明

1. アプリケーション設定（app）

環境の種類：

• development：開発環境
• testing：テスト環境
• production：本番環境

2. サーバー設定（server）

待ち受けアドレスの説明：

• 0.0.0.0：すべてのネットワークインターフェースで待ち受け
• 127.0.0.1：ローカルからのアクセスのみ
• 192.168.x.x：特定のネットワークインターフェースを指定

3. モデル設定（model）

パラメータの説明：

• 信頼度しきい値：検出感度を制御します。値が大きいほど判定が厳しくなります。
• IOU しきい値：NMS 処理時の重なりのしきい値
• モデルパス：相対パスと絶対パスに対応

4. カメラ設定（camera）

デバイス ID の説明：

• 0：デフォルトのカメラ
• 1, 2, ...：その他のカメラデバイス
• Linux ではそれぞれ /dev/video0 、 /dev/video1 などに対応します

対応解像度：

• 一般的な解像度：640x480、1280x720、1920x1080
• 対応解像度はカメラのハードウェアに依存します

5. Web インターフェース設定（web）

品質パラメータの説明：

• video_quality：JPEG 圧縮品質。画質と帯域幅に影響します
• stream_fps：出力フレームレート。帯域幅を節約するため、カメラのフレームレートより低く設定できます

6. 検出設定（detection）

色フォーマットの説明：

• BGR 形式を使用：[青, 緑, 赤]
• 範囲：0〜255
• よく使う色：赤 [0,0,255]、緑 [0,255,0]、青 [255,0,0]

7. ログ設定（logging）

ログレベル：

• DEBUG：詳細なデバッグ情報
• INFO：一般情報
• WARNING：警告メッセージ
• ERROR：エラー情報
• CRITICAL：重大なエラー

✅ 設定の検証

起動時の検証

自動検証の項目

システムの起動時に、次の項目が自動的に検証されます。

1. モデルファイル：モデルファイルが存在し、読み取り可能かを確認
2. カメラデバイス：カメラデバイスが利用可能かを確認
3. ポートの空き状況：ポートが使用中でないかを確認
4. パラメータの範囲：数値パラメータが有効範囲内かを確認
5. 権限チェック：ファイルとデバイスへのアクセス権限を確認

検証失敗時の処理

# 配置验证示例
def validate_config(config):
    """配置验证函数"""
    errors = []

    # 验证模型文件
    if not Path(config.model.path).exists():
        errors.append(f"模型文件不存在: {config.model.path}")

    # 验证端口范围
    if not 1 <= config.server.port <= 65535:
        errors.append(f"端口号无效: {config.server.port}")

    # 验证置信度阈值
    if not 0.0 <= config.model.confidence_threshold <= 1.0:
        errors.append(f"置信度阈值超出范围: {config.model.confidence_threshold}")

    if errors:
        logger.error("配置验证失败:")
        for error in errors:
            logger.error(f"  - {error}")
        sys.exit(1)

設定のホットアップデート

ホットアップデートに対応している設定

• 検出パラメータ：信頼度しきい値、IOU しきい値
• 表示オプション：検出枠、中心点、統計情報の表示
• 映像ストリームのパラメータ：品質、フレームレート
• ログレベル：実行時にログの詳細度を調整

ホットアップデート API

# 通过API更新配置
import requests

# 更新检测参数
response = requests.post('/api/settings', json={
    'confidence_threshold': 0.8,
    'show_detection_boxes': True,
    'show_center_point': False
})

print("配置更新结果:", response.json())

設定管理ツール

設定マネージャークラス

ConfigManager の実装

# config/config_manager.py
import yaml
import os
from pathlib import Path
from typing import Dict, Any
from dataclasses import dataclass

@dataclass
class FaceDetectionAppConfig:
    """人脸检测应用配置类"""

    @dataclass
    class AppConfig:
        name: str = "人脸检测应用"
        version: str = "1.0.0"
        environment: str = "development"

    @dataclass 
    class ServerConfig:
        host: str = "0.0.0.0"
        port: int = 8003
        debug: bool = False

    @dataclass
    class ModelConfig:
        path: str = "models/yolo11n_face_detect_bayese_320x320_nv12.bin"
        confidence_threshold: float = 0.6
        iou_threshold: float = 0.45

    @dataclass
    class CameraConfig:
        device_id: int = 0
        width: int = 640
        height: int = 480
        fps: int = 30
        async_capture: bool = True

    app: AppConfig
    server: ServerConfig
    model: ModelConfig
    camera: CameraConfig

def load_config(config_path: str = "config/face_config.yaml") -> FaceDetectionAppConfig:
    """加载配置文件"""

    # 1. 加载YAML配置
    config_file = Path(config_path)
    if config_file.exists():
        with open(config_file, 'r', encoding='utf-8') as f:
            yaml_config = yaml.safe_load(f)
    else:
        yaml_config = {}

    # 2. 应用环境变量覆盖
    config_dict = apply_env_overrides(yaml_config)

    # 3. 创建配置对象
    return create_config_object(config_dict)

def apply_env_overrides(config_dict: Dict[str, Any]) -> Dict[str, Any]:
    """应用环境变量覆盖"""

    env_mapping = {
        'FACE_SERVER_HOST': ['server', 'host'],
        'FACE_SERVER_PORT': ['server', 'port'],
        'FACE_SERVER_DEBUG': ['server', 'debug'],
        'FACE_MODEL_PATH': ['model', 'path'],
        'FACE_MODEL_CONFIDENCE': ['model', 'confidence_threshold'],
        'FACE_CAMERA_DEVICE': ['camera', 'device_id'],
        'FACE_LOG_LEVEL': ['logging', 'level'],
    }

    for env_var, config_path in env_mapping.items():
        if env_var in os.environ:
            value = os.environ[env_var]
            # 类型转换
            if config_path[1] in ['port', 'device_id']:
                value = int(value)
            elif config_path[1] in ['debug', 'async_capture']:
                value = value.lower() in ('true', '1', 'yes')
            elif config_path[1] in ['confidence_threshold', 'iou_threshold']:
                value = float(value)

            # 设置配置值
            set_nested_value(config_dict, config_path, value)

    return config_dict

トラブルシューティング

よくある設定の問題

よくある問題と解決方法

1. モデルファイルが見つからない

# 检查文件路径
ls -la models/
# 确认路径配置
echo $FACE_MODEL_PATH

1. カメラにアクセスできない

# 检查设备权限
ls -la /dev/video*
# 添加用户到video组
sudo usermod -a -G video $USER

1. ポートが使用中

# 检查端口占用
lsof -i :8003
# 或使用netstat
netstat -tulpn | grep 8003

1. 設定ファイルの書式エラー

# 验证YAML语法
python -c "import yaml; yaml.safe_load(open('config/face_config.yaml'))"

デバッグ用の設定

デバッグモードの設定

# 调试配置示例
server:
  debug: true

logging:
  level: "DEBUG"
  format: "%(asctime)s - %(name)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s"

camera:
  async_capture: false  # 简化调试

web:
  stream_fps: 5  # 降低帧率便于观察

環境変数によるデバッグ

# 启用详细日志
export FACE_LOG_LEVEL=DEBUG
export FACE_SERVER_DEBUG=true

# 降低性能以便调试
export FACE_WEB_STREAM_FPS=5
export FACE_CAMERA_FPS=15

# 启动应用
python main.py

パフォーマンスチューニングの設定

高性能設定

# 高性能配置示例
camera:
  async_capture: true
  fps: 30

web:
  stream_fps: 25
  video_quality: 85

model:
  confidence_threshold: 0.7  # 减少误检

# 线程配置
performance:
  capture_buffer_size: 3
  processing_threads: 2

低遅延設定

# 低延迟配置示例
camera:
  fps: 30
  async_capture: true

web:
  stream_fps: 30  # 与摄像头同步
  video_quality: 70  # 降低质量以减少编码时间

model:
  confidence_threshold: 0.5  # 快速检测