ONNX 顔モデルを TensorRT と OpenVINO に変換する
InsightFace 形式の ONNX モデルを TensorRT engine と OpenVINO IR に変換し、検証、精度選択、ベンチマーク、本番リリース確認まで扱う実践ガイドです。
このガイドで作るもの
多くの InsightFace デプロイは、研究環境、Python サービス、エッジ配布で扱いやすい ONNX から始まります。本番では NVIDIA GPU 向けに TensorRT、Intel CPU/iGPU/エッジ向けに OpenVINO が必要になることが多いです。
このガイドでは、ONNX グラフ検証、静的形状の簡略化、TensorRT engine 作成、OpenVINO IR 書き出し、ベンチマーク、元の ONNX 出力との比較までを安全な手順としてまとめます。
始める前に
- 入力名、入力レイアウト、正規化規則が確認済みの ONNX モデル。
- Linux x86_64 サーバー。Ubuntu 22.04 LTS または 24.04 LTS と sudo 権限を推奨します。
- NVIDIA GPU 向けの場合、TensorRT package と一致する NVIDIA driver と CUDA toolkit。
- 本番の画像サイズ、人物分布、照明、カメラ品質を反映した小さな検証セット。
1. Linux サーバーに変換ツールをインストールする
クリーンな Linux x86_64 サーバーから始めます。Python wheel、OpenVINO、NVIDIA driver、CUDA、TensorRT ツールのサポートが安定しているため、Ubuntu 22.04 LTS または 24.04 LTS が実用的な標準です。
ONNX ユーティリティは virtual environment に入れ、CPU と Intel デバイス向け変換には PyPI の OpenVINO を使い、TensorRT はサーバーの driver と CUDA に合う NVIDIA パッケージを入れます。変換 artifact と一緒にバージョンを保存し、production engine を再現できるようにします。
- TensorRT engine は production と同じ CUDA、TensorRT、driver 系でビルドします。
- Python ツールは virtual environment に分離し、serving stack に影響しないようにします。
- 顧客モデルや production モデルを変換する前に検証コマンドを実行します。
sudo apt-get update
sudo apt-get install -y python3 python3-venv python3-pip build-essential
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install onnx onnxsim onnxruntime numpysource .venv/bin/activate
python -m pip install openvino
ovc --help
benchmark_app --help# Install an NVIDIA driver and CUDA version supported by your TensorRT package first.
# Then download the matching TensorRT tar package from NVIDIA Developer.
tar -xzf TensorRT-10.*.Linux.x86_64-gnu.cuda-12.*.tar.gz
export TENSORRT_HOME=$PWD/TensorRT-10.*
export PATH=$TENSORRT_HOME/bin:$PATH
export LD_LIBRARY_PATH=$TENSORRT_HOME/lib:$LD_LIBRARY_PATH
trtexec --versionsource .venv/bin/activate
python - <<'PY'
import onnx
import onnxruntime
import openvino
print("onnx", onnx.__version__)
print("onnxruntime", onnxruntime.__version__)
print("openvino", openvino.__version__)
PY
trtexec --version2. ソース ONNX グラフを検証する
変換前に、入力名や形状を推測せずモデルを確認します。顔認識モデルの入力は通常 NCHW layout（batch, channels, height, width）の 1x3x112x112 で、検出器やスワッパーではより大きな動的形状を使う場合があります。
RGB/BGR 順序、平均と標準偏差、チャネルレイアウト、アラインメント、クロップサイズ、出力後処理を正確に記録してください。ランタイム変換では前処理の不一致は修正できません。
python - <<'PY'
import onnx
from onnx import checker
model_path = "models/insightface.onnx"
model = onnx.load(model_path)
checker.check_model(model)
print("IR version:", model.ir_version)
print("Inputs:")
for item in model.graph.input:
shape = [dim.dim_value or dim.dim_param for dim in item.type.tensor_type.shape.dim]
print(" ", item.name, shape)
print("Outputs:")
for item in model.graph.output:
shape = [dim.dim_value or dim.dim_param for dim in item.type.tensor_type.shape.dim]
print(" ", item.name, shape)
PY3. 必要に応じて形状を固定し簡略化する
TensorRT と OpenVINO は、グラフ形状が明確なほど最適化しやすくなります。固定サイズの顔認識 backbone では入力形状を固定し、検出器では動的次元を残して後で現実的な optimization profile を定義します。
簡略化後は、簡略化モデルが元の ONNX と数値的に近い出力を返すことを検証してください。商用出荷モデルでは、cosine similarity チェックを CI に含めるべきです。
python -m onnxsim models/insightface.onnx models/insightface.simplified.onnx --overwrite-input-shape input:1,3,112,1124. TensorRT engine を構築する
TensorRT engine はハードウェアと TensorRT バージョンに依存します。本番と同じ GPU クラス、ドライバ、CUDA スタックで構築し、元 ONNX、TensorRT バージョン、CUDA バージョン、精度、optimization profile を artifact と一緒に保存します。
最新の NVIDIA GPU では、ほとんどの顔 embedding と顔交換ワークロードで FP16 が標準的な本番選択です。INT8 は高スループット検出に有効ですが、キャリブレーションデータと厳格な精度ゲートが必要です。
- min/opt/max shapes は理論上限ではなく実際の batch size に合わせます。
- 検出器やスワッパーの入力形状が大きく異なる場合は、主要な入力ファミリーごとに engine を分けます。
- embedding cosine similarity や検出指標がリリース閾値を超えて悪化した engine は採用しません。
trtexec --onnx=models/insightface.simplified.onnx --saveEngine=engines/insightface_fp16.plan --minShapes=input:1x3x112x112 --optShapes=input:16x3x112x112 --maxShapes=input:32x3x112x112 --fp16 --workspace=4096 --verbosetrtexec --onnx=models/insightface.simplified.onnx --saveEngine=engines/insightface_int8.plan --minShapes=input:1x3x112x112 --optShapes=input:16x3x112x112 --maxShapes=input:32x3x112x112 --int8 --calib=calibration.cache5. ONNX を OpenVINO IR に変換する
OpenVINO IR は XML と BIN で構成され、OpenVINO runtime からデプロイできます。CPU 中心のサービス、Intel GPU 推論、運用のシンプルさを重視する edge box に適しています。
認識モデルでは、FP16 圧縮によりメモリを削減しスループットを改善でき、embedding のドリフトは通常小さくなります。監査が重要な検証システムでは、本番が FP16 でも比較用 FP32 artifact を残してください。
ovc models/insightface.simplified.onnx --output_model openvino/insightface.xml --input "input[1,3,112,112]" --compress_to_fp16=Truebenchmark_app -m openvino/insightface.xml -d CPU -shape "input[16,3,112,112]" -hint throughput6. OpenVINO で推論する
サービス起動時に compiled OpenVINO model を一度ロードし、リクエスト間で再利用します。本番ハードウェア方針に合わせて CPU、GPU、AUTO、HETERO を選択します。
顔認識では、cosine similarity や照合閾値を計算する前に、ONNX baseline と同じ方法で出力 embedding を正規化します。
from openvino import Core
import numpy as np
core = Core()
compiled = core.compile_model("openvino/insightface.xml", "CPU")
input_layer = compiled.input(0)
output_layer = compiled.output(0)
batch = np.random.rand(16, 3, 112, 112).astype("float32")
embeddings = compiled([batch])[output_layer]
print(embeddings.shape)7. 精度を検証し安全にリリースする
engine が動くだけでは変換完了ではありません。代表的な検証セットで元 ONNX、TensorRT、OpenVINO の出力を比較します。Embedding では cosine similarity、norm 分布、閾値影響を、検出では recall、false positive、landmark、NMS を確認します。
レイテンシ、スループット、メモリ、精度がすべて本番目標を満たした場合だけ artifact を昇格します。artifact metadata と rollback 手順をリリースパッケージに含めてください。
- 固定 random seed と安定した前処理コードで比較を再現可能にします。
- cold start と steady-state latency は別々に benchmark します。
- カメラ品質や顔姿勢は検証セットと異なるため、production drift を監視します。