HumansXドキュメントセンター
公式サイトへ ↗
ドキュメントセンター › GX-MAT-09S

YOLO11顔検出システム -- API インターフェース説明

概要

YOLO11顔検出システムは REST API とリアルタイム映像ストリームのインターフェースを提供し、ヘルスチェック、システム監視、パラメータ設定、リアルタイム顔検出映像ストリームに対応しています。すべてのインターフェースは Flask フレームワークをベースとしており、軽量で安定した Web サービスを提供します。

REST API

基本情報

  • Base URL: http://localhost:8003
  • Content-Type: application/json
  • すべての API エンドポイントは CORS（クロスオリジンアクセス）に対応しています
  • フレームワーク: Flask 2.3+

1. ヘルスチェック

GET /api/health

システムの各コンポーネントの稼働状態を確認します

リクエスト例

GET /api/health

レスポンス例

成功レスポンス (200):

{
  "status": "healthy",
  "face_detector": true,
  "camera_manager": true,
  "config_loaded": true,
  "uptime": 3600.5
}

システム異常レスポンス (503):

{
  "status": "unhealthy",
  "face_detector": false,
  "camera_manager": true,
  "config_loaded": true,
  "uptime": 120.3
}

2. システム統計情報

GET /api/stats

システムの詳細な稼働統計情報を取得します

リクエスト例

GET /api/stats

レスポンス例

{
  "start_time": 1703001600.0,
  "total_requests": 150,
  "detection_stats": {
    "total_frames": 5420,
    "total_detections": 3245,
    "fps": 28.5,
    "avg_inference_time": 0.018,
    "face_count": 2
  },
  "camera_stats": {
    "fps_actual": 29.2,
    "total_frames": 5420,
    "width": 640,
    "height": 480,
    "is_opened": true
  }
}

3. システム情報

GET /api/info

システム設定とモデル情報を取得します

リクエスト例

GET /api/info

レスポンス例

{
  "app": {
    "name": "人脸检测应用",
    "version": "1.0.0",
    "environment": "development"
  },
  "model": {
    "name": "YOLO11",
    "path": "models/yolo11n_face_detect_bayese_320x320_nv12.bin",
    "confidence_threshold": 0.6,
    "iou_threshold": 0.45
  },
  "camera": {
    "device_id": 0,
    "width": 640,
    "height": 480,
    "fps": 30,
    "is_opened": true
  },
  "settings": {
    "show_detection_boxes": true,
    "show_center_point": true,
    "show_stats": true,
    "confidence_threshold": 0.6
  }
}

4. 設定の更新

POST /api/settings

検出パラメータと表示設定を動的に更新します

リクエスト例

POST /api/settings
Content-Type: application/json

{
  "confidence_threshold": 0.7,
  "show_detection_boxes": true,
  "show_center_point": false,
  "show_stats": true
}

リクエストパラメータ:

  • confidence_threshold (float, 任意): 信頼度しきい値 (0.0-1.0)
  • show_detection_boxes (boolean, 任意): 検出枠を表示するかどうか
  • show_center_point (boolean, 任意): 中心点を表示するかどうか
  • show_stats (boolean, 任意): 統計情報を表示するかどうか

レスポンス例

成功レスポンス (200):

{
  "status": "success",
  "updated_settings": {
    "confidence_threshold": 0.7,
    "show_detection_boxes": true,
    "show_center_point": false,
    "show_stats": true
  }
}

パラメータエラーレスポンス (422):

{
  "detail": [
    {
      "loc": ["body", "confidence_threshold"],
      "msg": "ensure this value is greater than or equal to 0.0",
      "type": "value_error.number.not_ge",
      "ctx": {"limit_value": 0.0}
    }
  ]
}

5. 設定のリセット

POST /api/settings/reset

すべての設定をデフォルト値にリセットします

リクエスト例

POST /api/settings/reset

レスポンス例

{
  "status": "success",
  "settings": {
    "show_detection_boxes": true,
    "show_center_point": true,
    "show_stats": true,
    "confidence_threshold": 0.6
  }
}

リアルタイム映像ストリーム

MJPEG 映像ストリーム

GET /video_feed

リアルタイム顔検出映像ストリームを取得します

インターフェース情報

  • レスポンス形式: multipart/x-mixed-replace; boundary=frame
  • エンコード形式: MJPEG (Motion JPEG)
  • フレームレート: 設定可能（デフォルト 15fps）
  • 画質: 設定可能（デフォルト 80）

リクエスト例

GET /video_feed

HTML5 Video への組み込み:

<img id="videoStream" src="/video_feed" alt="Face Detection Stream">

JavaScript による制御:

// 开始播放
const videoElement = document.getElementById('videoStream');
videoElement.src = '/video_feed?' + new Date().getTime();

// 停止播放
videoElement.src = '';

レスポンス形式

Multipart レスポンス形式:

--frame
Content-Type: image/jpeg

[JPEG图像数据]
--frame
Content-Type: image/jpeg

[JPEG图像数据]
--frame
...

映像ストリームの特長:

  • リアルタイム顔検出結果のオーバーレイ表示
  • 検出枠の表示を設定可能
  • パフォーマンス統計情報の表示
  • 適応的な画質制御

Web インターフェースサービス

1. メインページ

GET /

Web インターフェースのメインページにアクセスします

リクエスト例

GET /

戻り値: HTML ページ (templates/index.html)

2. 静的リソース

GET /static/

静的リソースファイルにアクセスします

リソースパス

GET /static/css/style.css     # 样式文件
GET /static/js/app.js         # JavaScript应用
GET /static/images/           # 图片资源

エラー処理

HTTP ステータスコード

ステータスコードの説明

  • 200: リクエスト成功
  • 404: リソースが存在しない
  • 422: リクエストパラメータの検証に失敗
  • 500: サーバー内部エラー
  • 503: サービス利用不可（コンポーネント異常）

エラーレスポンス形式

標準エラー形式

{
  "detail": "错误描述信息",
  "error_code": "ERROR_CODE",
  "timestamp": "2024-01-01T12:00:00Z"
}

主なエラーコード:

  • CAMERA_NOT_AVAILABLE: カメラが利用できない
  • MODEL_LOAD_FAILED: モデルの読み込みに失敗
  • INVALID_PARAMETER: パラメータ値が無効
  • SYSTEM_ERROR: システム内部エラー

パフォーマンス監視インターフェース

リアルタイムパフォーマンス指標

FPS 監視

/api/stats インターフェースからリアルタイムの FPS 情報を取得します：

{
  "detection_stats": {
    "fps": 28.5,              // 检测处理FPS
    "avg_inference_time": 0.018,  // 平均推理时间(秒)
    "total_frames": 5420,     // 总处理帧数
    "face_count": 2           // 当前检测到的人脸数
  },
  "camera_stats": {
    "fps_actual": 29.2,       // 摄像头实际FPS
    "total_frames": 5420      // 摄像头总帧数
  }
}

メモリとリソースの監視

システムは主要なリソースの使用状況を自動的に監視します：

  • メモリ使用量: 自動ガベージコレクションとメモリリーク検出
  • CPU 使用率: 推論および後処理の CPU 使用率
  • 温度監視: ハードウェア温度（RDK-X5 プラットフォーム）
  • 接続数: 現在アクティブな HTTP 接続数

使用例

Python クライアントの例

ヘルスチェックと設定

import requests
import json

base_url = "http://localhost:8003"

# 1. 健康检查
health_response = requests.get(f"{base_url}/api/health")
print("系统状态:", health_response.json())

# 2. 获取系统信息
info_response = requests.get(f"{base_url}/api/info")
system_info = info_response.json()
print("当前置信度阈值:", system_info['settings']['confidence_threshold'])

# 3. 更新设置
new_settings = {
    "confidence_threshold": 0.7,
    "show_detection_boxes": True,
    "show_center_point": False
}

settings_response = requests.post(
    f"{base_url}/api/settings",
    json=new_settings
)
print("设置更新结果:", settings_response.json())

# 4. 获取统计信息
stats_response = requests.get(f"{base_url}/api/stats")
stats = stats_response.json()
print(f"当前FPS: {stats['detection_stats']['fps']}")
print(f"检测到人脸数: {stats['detection_stats']['face_count']}")

映像ストリーム処理

import requests
import cv2
import numpy as np

# 读取MJPEG视频流
def read_mjpeg_stream(url):
    """读取MJPEG视频流"""
    response = requests.get(url, stream=True)

    if response.status_code == 200:
        bytes_data = bytes()
        for chunk in response.iter_content(chunk_size=1024):
            bytes_data += chunk

            # 查找JPEG图像边界
            a = bytes_data.find(b'\xff\xd8')  # JPEG开始
            b = bytes_data.find(b'\xff\xd9')  # JPEG结束

            if a != -1 and b != -1:
                jpg = bytes_data[a:b+2]
                bytes_data = bytes_data[b+2:]

                # 解码JPEG图像
                frame = cv2.imdecode(
                    np.frombuffer(jpg, dtype=np.uint8), 
                    cv2.IMREAD_COLOR
                )

                if frame is not None:
                    yield frame

# 使用示例
stream_url = "http://localhost:8003/video_feed"
for frame in read_mjpeg_stream(stream_url):
    # 显示视频帧
    cv2.imshow('Face Detection Stream', frame)

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

cv2.destroyAllWindows()

JavaScript フロントエンドの例

Web インターフェースへの組み込み

<!DOCTYPE html>
<html>
<head>
    <title>人脸检测系统</title>
</head>
<body>
    <!-- 视频流显示 -->
    <div id="videoContainer">
        <img id="videoStream" src="/video_feed" alt="Face Detection Stream">
    </div>

    <!-- 控制面板 -->
    <div id="controlPanel">
        <label>
            置信度阈值:
            <input type="range" id="confidenceSlider" 
                   min="0.1" max="1.0" step="0.1" value="0.6">
            <span id="confidenceValue">0.6</span>
        </label>

        <label>
            <input type="checkbox" id="showBoxes" checked> 显示检测框
        </label>

        <label>
            <input type="checkbox" id="showCenter" checked> 显示中心点
        </label>

        <button id="resetSettings">重置设置</button>
    </div>

    <!-- 统计信息 -->
    <div id="statsPanel">
        <div>FPS: <span id="fpsValue">--</span></div>
        <div>人脸数: <span id="faceCount">--</span></div>
        <div>推理时间: <span id="inferenceTime">--</span>ms</div>
    </div>

    <script>
        // API接口封装
        class FaceDetectionAPI {
            constructor(baseUrl = '') {
                this.baseUrl = baseUrl;
            }

            async updateSettings(settings) {
                const response = await fetch('/api/settings', {
                    method: 'POST',
                    headers: {
                        'Content-Type': 'application/json',
                    },
                    body: JSON.stringify(settings)
                });
                return await response.json();
            }

            async getStats() {
                const response = await fetch('/api/stats');
                return await response.json();
            }

            async resetSettings() {
                const response = await fetch('/api/settings/reset', {
                    method: 'POST'
                });
                return await response.json();
            }
        }

        // 初始化API客户端
        const api = new FaceDetectionAPI();

        // 控制面板事件处理
        const confidenceSlider = document.getElementById('confidenceSlider');
        const confidenceValue = document.getElementById('confidenceValue');
        const showBoxes = document.getElementById('showBoxes');
        const showCenter = document.getElementById('showCenter');
        const resetButton = document.getElementById('resetSettings');

        // 置信度滑块
        confidenceSlider.addEventListener('input', async (e) => {
            const value = parseFloat(e.target.value);
            confidenceValue.textContent = value;

            await api.updateSettings({
                confidence_threshold: value
            });
        });

        // 检测框显示开关
        showBoxes.addEventListener('change', async (e) => {
            await api.updateSettings({
                show_detection_boxes: e.target.checked
            });
        });

        // 中心点显示开关
        showCenter.addEventListener('change', async (e) => {
            await api.updateSettings({
                show_center_point: e.target.checked
            });
        });

        // 重置设置按钮
        resetButton.addEventListener('click', async () => {
            await api.resetSettings();
            location.reload(); // 刷新页面以更新UI状态
        });

        // 定时更新统计信息
        setInterval(async () => {
            try {
                const stats = await api.getStats();
                document.getElementById('fpsValue').textContent = 
                    stats.detection_stats.fps.toFixed(1);
                document.getElementById('faceCount').textContent = 
                    stats.detection_stats.face_count;
                document.getElementById('inferenceTime').textContent = 
                    (stats.detection_stats.avg_inference_time * 1000).toFixed(1);
            } catch (error) {
                console.error('获取统计信息失败:', error);
            }
        }, 1000);
    </script>
</body>
</html>

cURL コマンドの例

コマンドラインによるインターフェーステスト

# 1. 健康检查
curl -X GET http://localhost:8003/api/health

# 2. 获取系统信息
curl -X GET http://localhost:8003/api/info

# 3. 获取统计信息
curl -X GET http://localhost:8003/api/stats

# 4. 更新置信度阈值
curl -X POST http://localhost:8003/api/settings \
  -H "Content-Type: application/json" \
  -d '{
    "confidence_threshold": 0.8,
    "show_detection_boxes": true
  }'

# 5. 重置设置
curl -X POST http://localhost:8003/api/settings/reset

# 6. 下载单帧图像（通过MJPEG流）
curl http://localhost:8003/video_feed | head -c 100000 > frame.jpg

パフォーマンスベンチマーク

Horizon RDK-X5 プラットフォーム

ハードウェアアクセラレーション性能

  • 推論時間: 15-25ms
  • 映像ストリーム FPS: 25-30 FPS
  • メモリ使用量: ~200MB
  • CPU 使用率: 15-25%
  • 消費電力: 3-5W

開発環境 CPU モード

CPU シミュレーション性能

  • シミュレーション推論時間: ~20ms
  • 映像ストリーム FPS: 15-20 FPS
  • メモリ使用量: ~150MB
  • CPU 使用率: 10-20%

注意: CPU モードは開発テスト専用であり、実際の推論計算は行いません

API の制限とクォータ

リクエスト制限

同時接続制限

  • 映像ストリーム接続: 最大 5 同時接続
  • API リクエスト頻度: 毎秒最大 100 リクエスト
  • パラメータ更新: 毎分最大 30 回の設定更新

データ制限

データサイズ制限

  • リクエストボディサイズ: 最大 1KB
  • 映像ストリームのフレームサイズ: 設定した画質パラメータに応じて動的に調整
  • ログファイル: 自動ローテーション、最大 100MB
← 前へYOLO11 顔検出 - システムアーキテクチャ設計次へ →YOLO11顔検出システム -- 全体紹介