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  # 快速检测