ドキュメントシステムアーキテクチャ設計
概要
インテリジェント顔追跡システムは 統合 MCP サーバーアーキテクチャ v2.0.0 を採用し、顔検出機能とパン・チルト制御機能をモジュール化されたシステムに統合しています。従来の単一 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. 統合サーバー
役割：システムのライフサイクル管理とサービスのオーケストレーション
主な機能：
- サービス起動：モデルとサービスコンポーネントを順に初期化し、起動プロセスを協調させます。
- リソース管理：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株式会社までお問い合わせください。