【YOLOで作る画像認識ツール第10回】Dockerで動かす：設定・ログ・ヘルスチェックを運用に近い形にする

2026年6月22日2026年10月4日

前回の第9回では、モデルをONNXに変換して速度を比べました。今回は、ここまで作ったAPIをDocker（アプリを、動かす環境ごと「箱（コンテナ）」に詰めて配る技術）で動かせるようにします。

開発者のパソコンでは動くのに、本番のサーバーでは動かない。この定番のトラブルを減らし、運用担当者が同じ手順で起動できるようにするための準備です。

この回で作るもの

APIを動かす環境の設計図 Dockerfile
起動・設定をまとめた compose.yaml（Docker Composeの設定ファイル）
動いているかを確かめるヘルスチェック
個人情報を残さないログの出力

先にお伝えしたいこと：この回の確認範囲

この連載の執筆環境では、Dockerイメージの実際のビルド（作成）と起動までは確認できていません。 外部のイメージ配布元やパッケージ配布元への接続が制限されており、ビルドの途中で止まったためです。確認できたのは次の範囲です。

docker compose config による、compose.yaml の書き方の検証（エラーなし）
ログ出力の追加と、そのテスト（pytest 33件成功）
Dockerを使わない起動（uvicorn）での、API・画面の動作（第4〜5回で確認済み）

読者の環境でビルドするときは、初回にうまくいかない可能性があります。その場合は、まず docker compose build のエラーメッセージを確認してください。

仕組み：コンテナに何を入れ、何を外に置くか

置き場所	何を置くか	理由
コンテナの中（イメージ）	Python・部品・`app/` のコード	誰が動かしても同じ環境になる
コンテナの外（読み取り専用で渡す）	AIモデルのファイル（`models/`）	差し替えやすく、イメージが軽くなる
実行時の設定（環境変数）	しきい値・モデルのパス	作り直さずに変えられる

AIモデルは、コードと更新のタイミングが違います。イメージに焼き込まず、外から渡す形にしておくと、モデルの入れ替えでイメージを作り直さずに済みます。

実装

Dockerfile

# Dockerfile
FROM python:3.11-slim

WORKDIR /app

# 依存だけ先に入れる（app を変えても、この層のキャッシュが効く）。推論だけなので CPU 版の PyTorch を使う
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt --extra-index-url https://download.pytorch.org/whl/cpu \
    # サーバーには画面がないので、画面表示用の部品（libGL など）を必要としない headless 版の OpenCV に差し替える
    && pip uninstall -y opencv-python \
    && pip install --no-cache-dir opencv-python-headless==4.13.0.92

COPY app ./app

# root では動かさない
RUN useradd --create-home appuser
USER appuser

# Ultralytics の設定ファイルの置き場所（書き込める場所を指定）
ENV YOLO_CONFIG_DIR=/tmp/ultralytics \
    YOLO_MODEL_PATH=/models/yolo26n.pt

EXPOSE 8000
CMD ["uvicorn", "app.api:app", "--host", "0.0.0.0", "--port", "8000"]

工夫した点は次のとおりです。

依存を先に入れる：コードだけを変えたときは、重い部品のインストールをやり直さず、素早く作り直せます
CPU版のPyTorch：推論だけなら、GPU用の巨大な部品は不要です
headless版のOpenCV：サーバーには画面がないため、画面表示用の部品が要らない版に差し替えます
rootで動かさない：万一、APIに問題があっても、コンテナの中での権限を最小限にします

compose.yaml

# compose.yaml
services:
  detector:
    build: .
    ports:
      - "127.0.0.1:8000:8000"   # 自分のパソコンからだけ接続できる。社内に公開するときは認証とあわせて見直す
    volumes:
      - ./models:/models:ro     # モデルは画像に焼き込まず、外から読み取り専用で渡す（差し替えやすい）
    environment:
      YOLO_CONFIDENCE: "0.25"
    read_only: true              # コンテナ内のファイルは書き換えられない
    tmpfs:
      - /tmp                     # 一時ファイルだけは書ける
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/health')"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 40s
    logging:
      driver: json-file
      options:
        max-size: "10m"           # ログでディスクがいっぱいにならないよう、大きさと世代を制限する
        max-file: "3"

ポートは自分のパソコンにだけ公開：127.0.0.1:8000:8000 と書くと、他のパソコンからは接続できません。第4回で触れたとおり、このAPIには認証がないためです
read_only: true：コンテナの中のファイルを書き換えられなくします。攻撃を受けても、コードを書き換えにくくなります
ヘルスチェック：30秒ごとに /health を呼び、応答がなければ「異常」と記録します。起動直後はモデルの読み込みに時間がかかるため、最初の40秒は判定を待ちます
ログの上限：1ファイル10MB・3世代まで。ログでディスクがいっぱいになり、システムが止まるのを防ぎます
restart: unless-stopped：異常で止まったら、自動で再起動します

ログを残す：ただし個人情報は残さない

運用では、「いつ・何枚・何秒かかったか」が分かるログが欠かせません。app/api.py に、ログの出力を足しました。

# app/api.py（追加部分）
started = time.perf_counter()
try:
    detections = request.app.state.detector.detect_bytes(data, conf)
except ValueError as exc:
    logger.warning("画像を読み込めませんでした bytes=%d", len(data))
    raise HTTPException(status_code=400, detail=str(exc)) from exc
# ファイル名には個人情報が含まれうるので、ログには残さない（大きさ・件数・時間だけ）
logger.info("detect bytes=%d conf=%.2f count=%d ms=%.0f", len(data), conf, len(detections),
            (time.perf_counter() - started) * 1000)

ログに残すのは、データの大きさ・しきい値・検出件数・処理時間だけです。ファイル名は残しません。 「田中様_免許証.jpg」のように、個人名などが含まれることがあるためです。テストでも、ファイル名がログに出ないことを確認しています。

動かす手順（読者の環境で）

python tools/download_assets.py      # モデルを models/ に用意する（初回のみ）
docker compose up --build            # イメージを作って起動
curl http://127.0.0.1:8000/health    # {"status":"ok"} が返れば起動している
docker compose ps                    # STATUS が healthy になれば、ヘルスチェックも通っている

先ほどお伝えしたとおり、この手順は、執筆環境ではビルドまで確認できていません。

つまずきやすい点

モデルが見つからない：./models にモデルのファイルが無いと、起動に失敗します。先にダウンロードが必要です
イメージが大きい：PyTorchなどを含むため、イメージは数GBになることがあります。ビルドと配布に時間がかかります
書き込み禁止でエラー：read_only にすると、書き込みが必要な場所（設定ファイルなど）でエラーになります。書き込める場所（/tmp）を指定しています
CPUの割り当て：コンテナに割り当てるCPUが少ないと、遅くなります。第9回の速度は、割り当てで変わります