ドキュメントシステムアーキテクチャ設計
概要
インテリジェント顔追跡システムは統合MCPサーバーアーキテクチャ v2.0.0を採用し、顔検出と雲台制御の機能を1つのモジュール化されたシステムに統合しています。従来の単一Webアプリケーションから、AIアシスタントと連携しやすいマルチサービスプラットフォームへと進化し、MCPプロトコルとRESTful APIの両方に対応しています。
アーキテクチャの特長
- ⚡ 統合サーバー: 単一のエントリーポイントですべてのサービスを管理
- 🏗️ 階層設計: コアロジック層・サービス層・API層を明確に分離
- ⚙️ 設定管理: YAML設定ファイルで複数環境に対応
- 🔒 型安全: Pydanticによるデータ検証
- 🔄 非同期協調: スマートなサービスライフサイクル管理
- 🚨 例外駆動: きめ細かな例外処理の仕組み
ディレクトリ構成
Proj_Intelligent-Face-Tracker/
├── face_tracker_mcp/ # 主要源代码目录
│ ├── main.py # 统一入口点
│ ├── config/ # 配置管理
│ │ ├── settings.py # 配置数据模型
│ │ ├── config_loader.py # 配置加载器
│ │ └── logging_config.py # 日志配置
│ ├── core/ # 核心业务逻辑
│ │ ├── detection.py # YOLO11人脸检测
│ │ ├── gimbal_control.py # 云台控制
│ │ ├── exceptions.py # 自定义异常类
│ │ └── utils.py # 工具函数
│ ├── services/ # 服务层
│ │ ├── web_service.py # Web服务封装
│ │ └── mcp_service.py # MCP服务
│ └── api/ # API层
│ └── routes.py # 路由定义
├── src/ # 传统版本源代码（兼容）
│ ├── detection_core/ # 人脸检测核心
│ ├── utils/ # PID控制器、卡尔曼滤波等
│ └── web/ # Flask Web应用
├── config/ # 配置文件
│ └── default.yaml # 默认配置
├── bin/ # 脚本目录
├── tests/ # 测试代码
├── docs/ # 文档目录
├── logs/ # 日志目录
└── model/ # YOLO模型文件目录
🏗️ 全体アーキテクチャ
統合サーバーアーキテクチャ (UnifiedServer)
┌─────────────────────────────────────────────────────────────────┐
│ 统一服务器 (UnifiedServer) │
├─────────────────────────────────────────────────────────────────┤
│ 主线程 (Asyncio Event Loop) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ MCP服务 (FastMCP) │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │ │
│ │ │ 8个工具函数 │ │ 异步HTTP客户端 │ │ 生命周期管理 │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ 后台线程 (Background Thread) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Web服务 (Flask) │ │
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │ │
│ │ │ 实时视频流 │ │ API端点 │ │ Web界面 │ │ │
│ │ └─────────────────┘ └─────────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
サービス協調アーキテクチャ
┌─────────────────────────────────────────────────────────────────┐
│ 应用层 (Application Layer) │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ MCP服务层 │ │ Web服务层 │ │ API路由层 │ │
│ │ (FastMCP) │ │ (Flask) │ │ (RESTful) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ 业务逻辑层 (Business Logic Layer) │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 人脸检测模块 │ │ 云台控制模块 │ │ 追踪算法模块 │ │
│ │ (Detection) │ │ (GimbalControl) │ │ (Tracking) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ 硬件抽象层 (Hardware Abstraction Layer) │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ 摄像头接口 │ │ 串口通信接口 │ │ BPU推理接口 │ │
│ │ (Camera) │ │ (Serial) │ │ (hobot_dnn) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
主要コンポーネント
1. 統合サーバー (UnifiedServer)
役割: システムのライフサイクル管理とサービスの協調
主な機能:
- サービスの起動: モデルとサービスコンポーネントを順に初期化し、起動フローを協調
- リソース管理: HTTPクライアントやスレッドプールなどのリソースを一元管理
- シグナル処理: SIGINT/SIGTERMシグナルを適切に処理し、リソースを確実に解放
- ネットワーク検出: 利用可能なすべてのネットワークアクセスアドレスを自動検出して表示
技術的な実装:
class UnifiedServer:
async def start(self):
# 1. 初始化YOLO模型
self.initialize_model()
# 2. 初始化Web和MCP服务
self.initialize_services()
# 3. 启动Web服务（后台线程）
self.start_web_service()
# 4. 启动MCP服务（主线程异步）
await self.start_mcp_service()
2. 顔検出モジュール (Detection Core)
モデルアーキテクチャ: 顔検出向けに最適化されたYOLO11n量子化モデル
技術仕様:
- 入力サイズ: 320×320ピクセル、NV12形式
- 推論プラットフォーム: Horizon BPUアクセラレーション
- 信頼度しきい値: 0.6（設定可能）
- IoUしきい値: 0.45（設定可能）
- 推論性能: 約30fpsのリアルタイム検出
データの流れ:
原始图像 → BGR2NV12转换 → 模型推理 → 后处理 → 结果输出
↓ ↓ ↓ ↓ ↓
640×480 320×320 BPU推理 NMS过滤 边界框+置信度
主要クラスの設計:
class YOLO11_FaceDetect:
def __init__(self, model_path, conf_thres, iou_thres):
self.dnn_handle = load_model(model_path)
self.conf_thres = conf_thres
self.iou_thres = iou_thres
def detect(self, frame) -> List[Detection]:
# BGR → NV12 格式转换
input_tensor = self.bgr2nv12(frame)
# BPU推理
outputs = self.forward(input_tensor)
# 后处理：NMS + 坐标反量化
return self.postprocess(outputs)
3. インテリジェント追跡モジュール (Tracking System)
複数対象追跡システム:
┌─────────────────────────────────────────────────────────────────┐
│ 目标追踪系统架构 │
├─────────────────────────────────────────────────────────────────┤
│ 检测结果输入 → 目标关联 → 目标评分 → 目标选择 → 追踪输出 │
│ ↓ ↓ ↓ ↓ ↓ │
│ 边界框列表 → ID匹配 → 综合评分 → 最优选择 → 追踪坐标 │
├─────────────────────────────────────────────────────────────────┤
│ 卡尔曼滤波预测 │
├─────────────────────────────────────────────────────────────────┤
│ 位置预测 ← 状态更新 ← 测量更新 ← 预测步骤 ← 历史状态 │
│ ↓ ↓ ↓ ↓ ↓ │
│ 未来位置 → 状态估计 → 观测融合 → 运动模型 → [x,y,vx,vy] │
└─────────────────────────────────────────────────────────────────┘
対象スコアリングアルゴリズム:
def calculate_target_score(target):
# 基础评分 = 置信度权重 × 置信度 + 大小权重 × 归一化面积
base_score = (confidence_weight * target.confidence +
size_weight * normalized_area)
# 持久性评分 = 连续检测次数 / 最大历史计数
persistence_score = target.detection_count / max_history_count
# 位置连续性评分 = 1.0 - min(距离/最大距离, 1.0)
position_score = 1.0 - min(distance / max_distance, 1.0)
# 当前目标加成（避免频繁切换）
current_bonus = target_switch_threshold if is_current_target else 0
return (base_score + persistence_weight * persistence_score +
position_weight * position_score + current_bonus)
カルマンフィルターの設計:
- 状態ベクトル: [x, y, vx, vy]（位置＋速度）
- 状態遷移行列: 等速運動モデル
- 観測行列: 位置を直接観測
- ノイズモデル: プロセスノイズ＋観測ノイズ
4. 雲台制御モジュール (Gimbal Control)
ハードウェアインターフェース:
- 通信プロトコル: シリアル通信 (/dev/ttyS1, 115200ボーレート)
- 制御方式: PWMサーボ制御
- 角度範囲: 0°～270°（水平・垂直）
- 制御精度: 1°刻み
PIDコントローラー:
class PIDController:
def __init__(self, kp=0.6, ki=0.1, kd=0.05):
self.kp, self.ki, self.kd = kp, ki, kd
self.integral = 0.0
self.previous_error = 0.0
def update(self, error, dt):
self.integral += error * dt
derivative = (error - self.previous_error) / dt
output = (self.kp * error +
self.ki * self.integral +
self.kd * derivative)
self.previous_error = error
return output
例外処理の仕組み:
# 自定义异常体系
class GimbalAngleOutOfRangeError(Exception): pass
class GimbalNotConnectedError(Exception): pass
class GimbalMoveError(Exception): pass
# 分层错误处理
try:
gimbal.move_to(pan, tilt)
except GimbalAngleOutOfRangeError as e:
return {"error_type": "ANGLE_OUT_OF_RANGE", "message": str(e)}
5. MCPサービスモジュール (MCP Service)
ツール関数のアーキテクチャ:
┌─────────────────────────────────────────────────────────────────┐
│ MCP工具函数层 │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌───────────┐ │
│ │ 检测类工具 │ │ 控制类工具 │ │ 状态类工具 │ │ 追踪类工具 │ │
│ │ │ │ │ │ │ │ │ │
│ │detect_faces │ │control_ │ │get_gimbal_ │ │start_face_│ │
│ │ │ │gimbal │ │status │ │tracking │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ │move_gimbal_ │ │get_system_ │ │stop_face_ │ │
│ │ │ │relative │ │status │ │tracking │ │
│ │ │ │ │ │ │ │ │ │
│ │ │ │reset_gimbal_│ │ │ │ │ │
│ │ │ │position │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └───────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ HTTP客户端层 │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ 异步HTTP客户端 │ │
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │
│ │ │ 连接池管理 │ │ 错误处理 │ │ 超时控制 │ │ │
│ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ Web API层 │
└─────────────────────────────────────────────────────────────────┘
HTTPエラー処理:
def _handle_http_error(self, e: Exception, operation: str):
if isinstance(e, httpx.HTTPStatusError):
# 解析结构化错误响应
error_data = e.response.json()
return {
"success": False,
"error": error_data.get('message'),
"error_type": error_data.get('error_type'),
"error_code": error_data.get('error_code'),
"details": error_data.get('details', {})
}
6. Webサービスモジュール (Web Service)
Flaskアプリケーションのアーキテクチャ:
- 静的リソース: HTMLテンプレート、CSSスタイル、JavaScriptスクリプト
- 映像ストリーム: MJPEGストリームのリアルタイム伝送
- APIエンドポイント: RESTfulインターフェース、JSONレスポンスに対応
- CORS対応: クロスオリジンアクセスに対応
APIエンドポイントの設計:
GET /api/faces # 获取人脸检测结果
POST /api/gimbal/control # 控制云台绝对位置
POST /api/gimbal/relative # 控制云台相对移动
GET /api/gimbal/status # 获取云台状态
POST /api/tracking/start # 启动自动追踪
POST /api/tracking/stop # 停止自动追踪
GET /api/system/status # 获取系统状态
GET /video_feed # 实时视频流
🔧 設定管理のアーキテクチャ
設定の階層構造
┌─────────────────────────────────────────────────────────────────┐
│ 配置层次结构 │
├─────────────────────────────────────────────────────────────────┤
│ 环境变量 (最高优先级) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ FACE_TRACKER_WEB_PORT=5000 │ │
│ │ FACE_TRACKER_MCP_PORT=8000 │ │
│ │ FACE_TRACKER_LOGGING_CONSOLE_LEVEL=INFO │ │
│ └─────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ YAML配置文件 (中等优先级) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ config/default.yaml │ │
│ │ ├── logging: 日志配置 │ │
│ │ ├── model: 模型配置 │ │
│ │ ├── camera: 摄像头配置 │ │
│ │ ├── gimbal: 云台配置 │ │
│ │ └── tracking: 追踪配置 │ │
│ └─────────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ 代码默认值 (最低优先级) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Settings类中的dataclass默认值 │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
設定データクラスの設計
@dataclass
class Settings:
# 应用配置
app_name: str = "智能人脸追踪系统"
version: str = "2.0.0"
environment: str = "development"
# 服务配置
web: WebConfig = field(default_factory=WebConfig)
mcp: MCPConfig = field(default_factory=MCPConfig)
# 业务配置
model: ModelConfig = field(default_factory=ModelConfig)
camera: CameraConfig = field(default_factory=CameraConfig)
gimbal: GimbalConfig = field(default_factory=GimbalConfig)
tracking: TrackingConfig = field(default_factory=TrackingConfig)
# 系统配置
logging: LoggingConfig = field(default_factory=LoggingConfig)
📊 データフローのアーキテクチャ
リアルタイムデータフロー
┌─────────────────────────────────────────────────────────────────┐
│ 实时数据流 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 摄像头 → 图像捕获 → 人脸检测 → 目标追踪 → 云台控制 │
│ ↓ ↓ ↓ ↓ ↓ │
│ 视频流 → BGR帧 → 边界框 → 追踪坐标 → 舵机角度 │
│ │
│ ↓ │
│ │
│ Web界面 ← 视频流编码 ← 结果绘制 ← 状态更新 ← 反馈信息 │
│ ↑ ↑ ↑ ↑ ↑ │
│ 用户交互 ← MJPEG流 ← 可视化 ← JSON API ← 执行结果 │
│ │
└─────────────────────────────────────────────────────────────────┘
制御フローのアーキテクチャ
┌─────────────────────────────────────────────────────────────────┐
│ 控制流 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ AI助手/Web界面 → MCP工具/API → 业务逻辑 → 硬件控制 │
│ ↓ ↓ ↓ ↓ │
│ 自然语言/手动 → JSON请求 → 参数验证 → 串口通信 │
│ │
│ ↓ │
│ │
│ 结果反馈 ← JSON响应 ← 异常处理 ← 执行反馈 ← 硬件状态 │
│ ↑ ↑ ↑ ↑ ↑ │
│ 用户界面 ← 结构化数据 ← 错误分类 ← 操作结果 ← 传感器数据 │
│ │
└─────────────────────────────────────────────────────────────────┘
🚀 性能最適化のアーキテクチャ
並行処理の設計
- メインスレッド: MCPサービスの非同期イベントループ
- バックグラウンドスレッド: WebサービスのFlaskアプリケーション
- 検出スレッド: 独立した映像処理スレッド
- 制御スレッド: 雲台制御を逐次実行
リソース管理
- HTTPコネクションプール: httpx.AsyncClientで接続を再利用
- メモリ最適化: 画像処理にインプレース操作を使用
- CPU最適化: BPUハードウェアアクセラレーション推論
- I/O最適化: 非同期シリアル通信
拡張性の設計
- プラグインアーキテクチャ: 新しい検出モデルのプラグインに対応
- 設定のホットリロード: 実行中の設定更新に対応
- マルチデバイス対応: ハードウェアインターフェースを抽象化し、さまざまなプラットフォームに対応
- 分散デプロイ: MCPサービスを単独でデプロイ可能
🛡️ セキュリティと安定性
例外処理の体系
- カスタム例外: ビジネスロジックに関連する正確な例外分類
- 階層的な処理: ハードウェア層からAPI層まで段階的に例外を伝達
- 構造化レスポンス: 統一されたエラーレスポンス形式
- 状態の回復: 例外発生後にシステム状態を自動回復
システム監視
- ヘルスチェック: 各コンポーネントの状態を定期的にチェック
- リソース監視: CPU・メモリ・ネットワークの使用状況
- ログシステム: レベル別のログ記録とローテーション
- 性能指標: リアルタイムのフレームレート・応答時間の統計
このアーキテクチャ設計により、システムの高性能・高可用性・高拡張性が確保され、今後の機能拡張と性能最適化のための堅固な基盤となります。
お問い合わせ
資料のダウンロード・技術サポートについては、HumansX株式会社までお問い合わせください。