MENU

問い合わせ

    お問い合わせ


    【YOLOで作る画像認識ツール 第4回】FastAPIで画像認識を「API」にして、ほかのシステムから使えるようにする

    (2026年10月29日 追記:記事どおりに再現できるよう、必要なコードと手順を追加しました)

    前回の第3回では、認識結果を種類ごとに数えてCSVに集計しました。ここまでは、プログラムを人が手で実行する形でした。今回は、画像認識をAPI(ほかのシステムから呼び出せる窓口)にして、既存の業務システムやスマホアプリから使えるようにします。

    使うのは、PythonのWebフレームワーク「FastAPI」です。画像を送ると、認識結果がJSONで返ってくる仕組みを作ります。

    目次

    この回で作るもの

    • 画像をアップロードすると認識結果のJSONを返す POST /detect
    • 動作確認用の GET /health
    • 大きすぎる画像・壊れた画像・範囲外のしきい値を、分かるエラーで断る処理

    仕組み:モデルは「起動時に1回だけ」読み込む

    AIモデルの読み込みには時間がかかります。リクエストのたびに読み込むと遅くなるため、サーバーの起動時に1回だけ読み込み、以降のリクエストで使い回します。

    [起動時] モデルを読み込む(数秒)
    [リクエスト] 画像を受け取る → 認識する → JSONを返す(このあいだ、モデルは読み込み済み)

    実装

    部品を追加する

    この回から、Webフレームワークの FastAPI と、それを動かすサーバーの uvicorn を使います。ファイルのアップロードを受けるための python-multipart も必要です。requirements.txt に次の変更を加えます(+ が追加、- が削除)。

    --- a/requirements.txt
    +++ b/requirements.txt
    @@ -5,3 +5,8 @@ torchvision==0.27.0
     opencv-python==4.13.0.92
     numpy==2.4.6
     pillow==12.2.0
    +# 第4回から(API)
    +fastapi==0.136.3
    +starlette==1.2.1
    +uvicorn==0.48.0
    +python-multipart==0.0.30

    テストからAPIを呼び出すための httpx も、requirements-dev.txt に足します。次の変更を加えます(+ が追加、- が削除)。

    --- a/requirements-dev.txt
    +++ b/requirements-dev.txt
    @@ -1,3 +1,4 @@
     -r requirements.txt
     pytest==9.0.3
     ruff==0.15.12
    +httpx==0.28.1

    追加した部品を入れます。

    pip install -r requirements-dev.txt --extra-index-url https://download.pytorch.org/whl/cpu

    画像のバイト列から認識できるようにする

    APIは、画像を「ファイル」ではなく「送られてきたデータ(バイト列)」として受け取ります。Detector に、バイト列から認識するメソッド detect_bytes を足し、ファイルからでもバイト列からでも同じ推論の処理(_predict)を通るように整理します。後述の「利用統計の送信を切る」設定もここで入れます。app/detector.py に次の変更を加えます(+ が追加、- が削除)。

    --- a/app/detector.py
    +++ b/app/detector.py
    @@ -1,13 +1,19 @@
     """画像1枚から物体を見つける(YOLO の推論を包む薄いクラス)。"""
     from __future__ import annotations
     
    +import io
     from dataclasses import dataclass
     from pathlib import Path
     
    -from ultralytics import YOLO
    +from PIL import Image, UnidentifiedImageError
    +
    +from ultralytics import YOLO, settings
     
     from app.config import DEFAULT_CONFIDENCE, MODEL_PATH
     
    +# Ultralytics は既定で利用統計・クラッシュ情報の送信(sync)が有効。社内の画像を扱う前提なので切っておく。
    +settings.update({"sync": False})
    +
     
     @dataclass(frozen=True)
     class Detection:
    @@ -25,11 +31,23 @@ class Detector:
             self._model = YOLO(str(model_path))
             self.confidence = confidence
     
    -    def detect(self, image_path: str | Path) -> list[Detection]:
    +    def detect(self, image_path: str | Path, confidence: float | None = None) -> list[Detection]:
             """画像ファイルを読み、しきい値以上の検出結果を返す。"""
             if not Path(image_path).exists():
                 raise FileNotFoundError(f"画像が見つかりません: {image_path}")
    -        result = self._model.predict(str(image_path), conf=self.confidence, verbose=False)[0]
    +        return self._predict(str(image_path), confidence)
    +
    +    def detect_bytes(self, data: bytes, confidence: float | None = None) -> list[Detection]:
    +        """アップロードされた画像のバイト列から検出する。画像として読めなければ ValueError。"""
    +        try:
    +            image = Image.open(io.BytesIO(data)).convert("RGB")
    +        except (UnidentifiedImageError, OSError) as exc:
    +            raise ValueError("画像として読み込めませんでした") from exc
    +        return self._predict(image, confidence)
    +
    +    def _predict(self, source: str | Image.Image, confidence: float | None) -> list[Detection]:
    +        conf = self.confidence if confidence is None else confidence
    +        result = self._model.predict(source, conf=conf, verbose=False)[0]
             detections: list[Detection] = []
             for box in result.boxes:
                 left, top, right, bottom = (round(v) for v in box.xyxy[0].tolist())

    しきい値(confidence)を、リクエストごとに変えられるようにもしました。

    APIを作る app/api.py

    APIの本体を、新しいファイル app/api.py に作ります。

    # app/api.py
    """画像認識を、ほかのシステムから呼び出せる Web API にする。
    
      uvicorn app.api:app --port 8000
      curl -F "file=@samples/fruits.jpg" http://127.0.0.1:8000/detect
    """
    from __future__ import annotations
    
    from collections.abc import AsyncIterator
    from contextlib import asynccontextmanager
    from typing import Annotated, Protocol
    
    from fastapi import FastAPI, File, HTTPException, Query, Request, UploadFile
    
    from app.config import DEFAULT_CONFIDENCE
    from app.detector import Detection, Detector
    from app.results import to_dict
    
    MAX_UPLOAD_BYTES = 10 * 1024 * 1024  # 10MB。これを超える画像は受け付けない
    
    
    class DetectorLike(Protocol):
        def detect_bytes(self, data: bytes, confidence: float | None = None) -> list[Detection]: ...
    
    
    def create_app(detector: DetectorLike | None = None) -> FastAPI:
        """detector を渡すとそれを使う(テスト用)。渡さなければ起動時にモデルを1回だけ読み込む。"""
    
        @asynccontextmanager
        async def lifespan(app: FastAPI) -> AsyncIterator[None]:
            app.state.detector = detector or Detector()
            yield
    
        app = FastAPI(title="果物の検品API", lifespan=lifespan)
    
        @app.get("/health")
        def health() -> dict[str, str]:
            return {"status": "ok"}
    
        @app.post("/detect")
        async def detect(
            request: Request,
            file: Annotated[UploadFile, File(description="認識する画像(jpg/png など)")],
            conf: Annotated[float, Query(ge=0.0, le=1.0, description="信頼度のしきい値")] = DEFAULT_CONFIDENCE,
        ) -> dict[str, object]:
            data = await file.read(MAX_UPLOAD_BYTES + 1)
            if len(data) > MAX_UPLOAD_BYTES:
                raise HTTPException(status_code=413, detail="画像が大きすぎます(上限 10MB)")
            try:
                detections = request.app.state.detector.detect_bytes(data, conf)
            except ValueError as exc:
                raise HTTPException(status_code=400, detail=str(exc)) from exc
            return to_dict(file.filename or "upload", conf, detections)
    
        return app
    
    
    app = create_app()

    押さえたい点は次のとおりです。

    • lifespan:起動時にモデルを読み込む場所です。create_app に偽の検出器を渡せるため、テストではモデルなしで動かせます
    • conf の範囲チェック:ge=0.0, le=1.0 と書くだけで、範囲外の値は自動的にエラー(422)になります
    • サイズの上限:10MBを超える画像は受け付けません。巨大なデータを送り付けられて、サーバーが動かなくなるのを防ぎます
    • エラーの種類を分ける:壊れた画像は400、大きすぎる画像は413と、原因が伝わる番号で返します

    動かして確かめる

    起動する

    uvicorn app.api:app --port 8000

    起動すると、http://127.0.0.1:8000/docs で、FastAPIが自動で作る操作画面(Swagger UI)も使えます。ブラウザから画像を送って試せます。

    画像を送る

    curl -F "file=@samples/fruits.jpg" "http://127.0.0.1:8000/detect?conf=0.4"

    開発環境では、しきい値0.4で3件(すべてorange、信頼度0.867・0.718・0.469)がJSONで返りました。2件目以降の応答は0.1秒程度でした(環境により異なります)。

    エラーの確認

    送ったもの結果
    画像ではないファイル400(画像として読み込めませんでした)
    conf=5(範囲外)422(0〜1の範囲で指定するよう自動で案内)
    10MB超の画像413(画像が大きすぎます)

    テスト

    APIのテスト tests/test_api.py を作ります。FastAPIの TestClient(内部で httpx を使います)で、偽の検出器を入れたAPIを呼び出します。

    # tests/test_api.py
    from __future__ import annotations
    
    from fastapi.testclient import TestClient
    
    from app import api
    from app.detector import Detection
    
    
    class _FakeDetector:
        def __init__(self) -> None:
            self.last_conf: float | None = None
    
        def detect_bytes(self, data: bytes, confidence: float | None = None) -> list[Detection]:
            self.last_conf = confidence
            if data == b"not-an-image":
                raise ValueError("画像として読み込めませんでした")
            return [Detection("orange", 0.87, (1, 2, 3, 4))]
    
    
    def _client(fake: _FakeDetector) -> TestClient:
        return TestClient(api.create_app(fake))
    
    
    def test_health() -> None:
        with _client(_FakeDetector()) as client:
            assert client.get("/health").json() == {"status": "ok"}
    
    
    def test_detect_returns_json_and_passes_threshold() -> None:
        fake = _FakeDetector()
        with _client(fake) as client:
            res = client.post("/detect?conf=0.5", files={"file": ("a.jpg", b"img", "image/jpeg")})
        body = res.json()
        assert res.status_code == 200
        assert body["image"] == "a.jpg" and body["count"] == 1 and body["confidence_threshold"] == 0.5
        assert fake.last_conf == 0.5
    
    
    def test_invalid_image_is_400() -> None:
        with _client(_FakeDetector()) as client:
            res = client.post("/detect", files={"file": ("a.jpg", b"not-an-image", "image/jpeg")})
        assert res.status_code == 400
    
    
    def test_conf_out_of_range_is_422() -> None:
        with _client(_FakeDetector()) as client:
            res = client.post("/detect?conf=2", files={"file": ("a.jpg", b"img", "image/jpeg")})
        assert res.status_code == 422
    
    
    def test_too_large_is_413(monkeypatch) -> None:  # type: ignore[no-untyped-def]
        monkeypatch.setattr(api, "MAX_UPLOAD_BYTES", 10)
        with _client(_FakeDetector()) as client:
            res = client.post("/detect", files={"file": ("a.jpg", b"x" * 11, "image/jpeg")})
        assert res.status_code == 413
    pytest -q      # 20件成功
    ruff check .   # 問題なし

    テストでは、偽の検出器を使い、正常な応答・しきい値の受け渡し・3種類のエラーを確認しています。

    つまずきやすい点

    • python-multipart が必要:ファイルのアップロードを受けるには、この部品が必要です(この回の最初に requirements.txt に足しました)
    • テスト時の警告:テストを実行すると、httpx(テスト用の通信部品)に関する「非推奨」の警告が表示されます。動作には影響しませんが、依存部品の版が変わると挙動が変わりうるため、この連載では版を固定しています
    • モデルを毎回読み込んでしまう:起動時に1回だけ読み込む作りにしないと、応答が極端に遅くなります
    • 認証がない:この回のAPIは、誰でも呼び出せます。社内ネットワークの外に公開するときは、認証(誰が使えるかの確認)が必須です。連載では省略しています

    補足:利用統計の送信を切っておく

    動作確認中、実行環境の通信の監視で、外部のGoogle Analyticsへの接続の試みが1件検出されました。Ultralyticsの設定に、利用統計などを送る sync という項目が既定で有効(true)になっていたため、これが原因と考えられます。画像そのものが送られるわけではありませんが、社内の画像を扱う前提では、意図しない外部通信は止めておくのが安全です。そのため、コードの先頭でこの設定を切っています。

    この設定は、先ほどの app/detector.py の変更に含めています(settings.update({"sync": False}) の行)。

    発注者向けメモ:APIにすると決めることが増える

    画像認識をAPIにすると、「誰が・どこから・どれくらい使うか」で、必要な構成と費用が変わります。

    発注者がやること チェックリスト

    • ☐ 呼び出す側のシステム(既存の業務システム・アプリ)と、送る画像の大きさ・枚数を洗い出した
    • ☐ 1日・1時間あたりの最大枚数と、許容できる応答時間(何秒以内か)を決めた
    • ☐ APIを使える人・システムの範囲(社内のみか、社外にも公開か)を決めた
    • ☐ 画像が外部に送られるかどうか、利用統計などの外部通信の有無を確認した
    • ☐ 障害時の扱い(APIが止まったとき、業務をどう続けるか)を決めた

    開発会社への質問例

    • 「想定する最大の枚数と応答時間で、どのくらいのサーバー構成が必要で、月額はいくらですか」
    • 「APIには認証を付けますか。誰がアクセスできるかは、どう管理しますか」
    • 「使うAIモデルやライブラリが、外部に利用統計や画像を送ることはありますか。あれば止められますか」
    • 「モデルを更新したとき、APIの利用側に影響が出ないようにできますか」

    まとめと次回予告

    第4回では、次のことを行いました。

    • 画像を送ると認識結果のJSONを返すAPI(FastAPI)を作った
    • モデルを起動時に1回だけ読み込み、応答を速くした
    • 大きすぎる画像・壊れた画像・範囲外の値を、分かるエラーで断るようにした
    • 利用統計の外部送信を切り、意図しない通信を防いだ

    次回の第5回では、このAPIをブラウザから使える画面にして、画像をアップロードして結果をその場で見られるようにします。

    この連載の記事一覧

    この記事は連載「YOLOで作る画像認識ツール」の1回です。連載のほかの回は次のとおりです(連載の一覧ページ)。

    システム制作・運用・保守のお問い合わせはこちら

      お問い合わせ


      よかったらシェアしてね!
      • URLをコピーしました!
      • URLをコピーしました!

      この記事を書いた人

      株式会社THIRD HERO代表取締役 朝野貴朗
      Webシステム開発を中心に、toC向けサービスサイトの運営、ツール開発などを行ってまいりました。

      目次