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

デプロイガイド

環境の準備

1. システム要件

  • OS: Ubuntu 20.04以降
  • Pythonバージョン: 3.6以降
  • ハードウェアプラットフォーム: RDK X5開発ボード（推奨）または互換ARMアーキテクチャ
  • メモリ: 2GB RAM以上
  • ストレージ: 3GB以上の空き容量
  • ネットワーク: 有線／無線ネットワーク接続に対応

2. ハードウェアの接続

カメラデバイス

# 检查摄像头设备
ls /dev/video*
# 或检查 facecamera 设备（RDK X5专用）
ls /dev/facecamera

# 测试摄像头功能
v4l2-ctl --list-devices

雲台のシリアルデバイス

# 检查串口设备
ls /dev/ttyS*

# 设置串口权限
sudo chmod 666 /dev/ttyS1

# 或添加用户到dialout组（推荐）
sudo usermod -a -G dialout $USER
# 需要重新登录生效

ハードウェア接続チェックリスト

  • カメラが正しく接続され、デバイスパスにアクセスできる
  • 雲台がシリアルポート経由で /dev/ttyS1 に接続されている
  • シリアルポートのボーレートが115200に設定されている
  • 雲台への給電が正常で、サーボが正常に応答する
  • ネットワーク接続が安定している

インストール手順

1. プロジェクトのクローン

# 克隆项目到本地
git clone https://github.com/your-username/Proj_Intelligent-Face-Tracker.git
cd Proj_Intelligent-Face-Tracker

# 检查项目结构
ls -la

2. 仮想環境の作成（推奨）

# 使用Python内置venv
python3 -m venv venv
source venv/bin/activate

# 或使用conda
conda create -n face_tracker python=3.8
conda activate face_tracker

3. システム依存パッケージのインストール

# 更新包管理器
sudo apt update

# 安装系统依赖
sudo apt install -y \
    python3-dev \
    python3-pip \
    build-essential \
    cmake \
    pkg-config \
    libjpeg-dev \
    libpng-dev \
    libtiff-dev \
    libavcodec-dev \
    libavformat-dev \
    libswscale-dev \
    libv4l-dev \
    libxvidcore-dev \
    libx264-dev \
    libgtk-3-dev \
    libatlas-base-dev \
    gfortran \
    libusb-1.0-0-dev

# RDK X5特定依赖（如果适用）
sudo apt install -y hobot-dnn hobot-cv

4. Python依存パッケージのインストール

# 升级pip
pip install --upgrade pip

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

# 验证关键包安装
python -c "import cv2; print('OpenCV版本:', cv2.__version__)"
python -c "import numpy; print('NumPy版本:', numpy.__version__)"
python -c "import flask; print('Flask版本:', flask.__version__)"

5. モデルファイルの準備

# 确保模型文件在正确位置
ls -la model/yolo11n_face_detect_bayese_320x320_nv12.bin

# 如果模型文件不存在，请从以下来源获取：
# 1. 项目发布页面下载
# 2. 联系开发团队获取
# 3. 自己训练YOLO11人脸检测模型

環境設定

1. 基本設定ファイル

本プロジェクトでは、YAML設定ファイルと環境変数を使って設定を管理します。

# 查看默认配置
cat config/default.yaml

# 根据需要修改配置
cp config/default.yaml config/production.yaml
vim config/production.yaml

2. 環境変数の設定

環境変数ファイルを作成します（任意。通常は変更不要です）。

# 创建.env文件
cat > .env << 'EOF'
# Web服务配置
FACE_TRACKER_WEB_PORT=5000
FACE_TRACKER_WEB_HOST=0.0.0.0

# MCP服务配置
FACE_TRACKER_MCP_PORT=8000
FACE_TRACKER_MCP_HOST=0.0.0.0

# 日志配置
FACE_TRACKER_LOGGING_CONSOLE_LEVEL=INFO
FACE_TRACKER_LOGGING_FILE_LEVEL=DEBUG

# 硬件配置
FACE_TRACKER_CAMERA_DEVICE_PATH=/dev/facecamera
FACE_TRACKER_GIMBAL_SERIAL_PORT=/dev/ttyS1
FACE_TRACKER_GIMBAL_BAUDRATE=115200

# 模型配置
FACE_TRACKER_MODEL_PATH=model/yolo11n_face_detect_bayese_320x320_nv12.bin
FACE_TRACKER_MODEL_CONFIDENCE_THRESHOLD=0.6
FACE_TRACKER_MODEL_IOU_THRESHOLD=0.45

# 追踪配置
FACE_TRACKER_TRACKING_PID_KP=0.6
FACE_TRACKER_TRACKING_KALMAN_ENABLED=true
FACE_TRACKER_TRACKING_PREDICTION_ENABLED=true
EOF

3. 設定ファイルのカスタマイズ

ログ設定

# config/default.yaml 中的日志配置
logging:
  console_level: "INFO"    # DEBUG, INFO, WARNING, ERROR
  file_level: "DEBUG"
  format: "[%(name)s] [%(asctime)s.%(msecs)03d] [%(levelname)s] %(message)s"
  datefmt: "%H:%M:%S"
  file_path: "logs/app.log"
  max_file_size: 10485760  # 10MB
  backup_count: 5

カメラ設定

camera:
  device_path: "/dev/facecamera"  # 或 "/dev/video0"
  width: 640
  height: 480
  fps: 30

雲台設定

gimbal:
  serial_port: "/dev/ttyS1"
  baudrate: 115200
  pan_pin: 3
  tilt_pin: 4
  init_pan_angle: 135.0
  init_tilt_angle: 135.0
  angle_range: [0, 270]

追跡設定

tracking:
  auto_enabled: false
  pid_kp: 0.6
  kalman_enabled: true
  prediction_enabled: true
  target_center_threshold: 50  # 像素

サービスの起動

方法1：起動スクリプトを使用する（推奨）

# 启动所有服务
./bin/start-mcp-server.sh

# 停止所有服务
./bin/stop-mcp-server.sh

# 查看服务状态
ps aux | grep python | grep face_tracker

起動スクリプトの内容

#!/bin/bash
# bin/start-mcp-server.sh

set -e

echo "启动智能人脸追踪系统..."

# 检查Python虚拟环境
if [[ "$VIRTUAL_ENV" != "" ]]; then
    echo "使用虚拟环境: $VIRTUAL_ENV"
else
    echo "警告: 未检测到虚拟环境"
fi

# 检查必要文件
if [ ! -f "model/yolo11n_face_detect_bayese_320x320_nv12.bin" ]; then
    echo "错误: 模型文件不存在"
    exit 1
fi

# 创建日志目录
mkdir -p logs

# 设置环境变量
export PYTHONPATH="${PYTHONPATH}:$(pwd)"

# 启动服务
echo "正在启动服务..."
python main.py &

SERVER_PID=$!
echo "服务已启动, PID: $SERVER_PID"
echo $SERVER_PID > face_tracker.pid

echo "服务启动完成!"
echo "Web界面: http://localhost:5000"
echo "MCP服务: http://localhost:8000/mcp/"

方法2：直接実行する

# 使用默认配置启动
python main.py

# 指定配置文件启动
python main.py --config config/production.yaml

# 启用调试模式
python main.py --debug

# 后台运行
nohup python main.py > logs/server.log 2>&1 &

デプロイの検証

1. サービス状態の確認

起動後、システムは利用可能なすべてのアクセスアドレスを表示します。

启动信息:
- Web界面: http://127.0.0.1:5000
- MCP服务: http://127.0.0.1:8000/mcp/
- API接口: http://127.0.0.1:5000/api/system/status

局域网访问:
- Web界面: http://192.168.1.100:5000 (主要)
- MCP服务: http://192.168.1.100:8000/mcp/

2. 機能テスト

Webサービスのテスト

# 测试Web服务
curl http://localhost:5000/api/system/status

# 测试人脸检测API
curl http://localhost:5000/api/faces

# 在浏览器中访问
# http://localhost:5000

MCPサービスのテスト

# 测试MCP服务
curl http://localhost:8000/mcp/

# 测试工具列表
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list", "params": {}}'

ハードウェアのテスト

# 测试摄像头
python -c "
import cv2
cap = cv2.VideoCapture('/dev/facecamera')
print('摄像头状态:', 'OK' if cap.isOpened() else 'Error')
cap.release()
"

# 测试串口权限
python -c "
import serial
try:
    ser = serial.Serial('/dev/ttyS1', 115200, timeout=1)
    print('串口状态: OK')
    ser.close()
except Exception as e:
    print('串口错误:', e)
"

3. 性能の検証

# 检查系统资源使用
top -p $(pgrep -f "python.*main.py")

# 检查内存使用
ps aux | grep python | grep face_tracker

# 检查网络连接
netstat -tulpn | grep -E "(5000|8000)"

# 测试检测性能
curl -s http://localhost:5000/api/system/status | jq '.performance'

トラブルシューティング

よくある問題

1. カメラデバイスの問題

問題: カメラデバイスが存在しない、またはアクセスできない

# 症状
ls: cannot access '/dev/facecamera': No such file or directory

対処方法:

# 检查可用摄像头设备
ls /dev/video*
v4l2-ctl --list-devices

# 修改配置文件使用video0
vim config/default.yaml
# 或设置环境变量
export FACE_TRACKER_CAMERA_DEVICE_PATH=/dev/video0

# 检查摄像头权限
sudo chmod 666 /dev/video0

2. シリアルポートの権限の問題

問題: シリアルポートの権限が不足している

# 症状
PermissionError: [Errno 13] Permission denied: '/dev/ttyS1'

対処方法:

# 方法1: 直接修改权限（临时）
sudo chmod 666 /dev/ttyS1

# 方法2: 添加用户到dialout组（永久）
sudo usermod -a -G dialout $USER
# 重新登录或执行
newgrp dialout

# 方法3: 创建udev规则（系统级）
sudo vim /etc/udev/rules.d/99-serial.rules
# 添加内容：
# KERNEL=="ttyS1", MODE="0666"
sudo udevadm control --reload-rules

3. モデルファイルの問題

問題: モデルファイルが見つからない、または破損している

# 症状
FileNotFoundError: Model file not found: model/yolo11n_face_detect_bayese_320x320_nv12.bin

対処方法:

# 检查文件是否存在
ls -la model/

# 检查文件权限
chmod 644 model/*.bin

# 验证文件完整性（如果有校验和）
md5sum model/yolo11n_face_detect_bayese_320x320_nv12.bin

# 重新下载模型文件（联系开发团队）

4. ポート使用中の問題

問題: ポートがすでに使用されている

# 症状
OSError: [Errno 98] Address already in use

対処方法:

# 查找占用端口的进程
sudo netstat -tulpn | grep :5000
sudo lsof -i :5000

# 终止占用进程
sudo kill -9 <PID>

# 或使用不同端口
export FACE_TRACKER_WEB_PORT=5001
export FACE_TRACKER_MCP_PORT=8001

5. メモリ不足の問題

問題: システムのメモリが不足している

# 症状
MemoryError: Unable to allocate memory for image processing

対処方法:

# 检查系统内存
free -h
df -h

# 增加swap空间
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 优化配置降低内存使用
vim config/default.yaml
# 调整：
# camera.fps: 20  # 降低帧率
# model.confidence_threshold: 0.7  # 提高阈值减少检测

6. Python依存パッケージの問題

問題: 依存パッケージのバージョンが競合している

# 症状
ImportError: cannot import name 'xxx' from 'xxx'

対処方法:

# 检查依赖版本
pip list | grep opencv
pip list | grep numpy

# 重新安装问题包
pip uninstall opencv-python
pip install opencv-python==4.10.0.84

# 或重建虚拟环境
deactivate
rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

お問い合わせ

資料のダウンロード・技術サポートについては、HumansX株式会社までお問い合わせください。

← 前へシステムアーキテクチャ設計次へ →大規模モデルの応用設計 -- インテリジェント視覚ロボットアーム制御システム