0. はじめに

物体検出モデル YOLOv8 の学習を兼ねて「ポケモン図鑑」Webアプリを作成し、Streamlit Community Cloud (SCC) 上でデプロイしました。
本記事は、その外部公開方法にフォーカスした備忘録です。
推論モデル部分・Streamlitアプリ本体の実装は完了している前提で、
「Streamlitアプリの公開手順」 に特化して解説します。

1. 前提条件・必要なもの

必要なアカウント一覧
- GitHub
- Hugging Face
- Streamlit Community Cloud
事前準備・確認
- YOLOv8 で学習済みモデルが用意できていること
- Streamlit アプリがローカルで正常に動作していること

2. プロジェクト構成と必要ファイル

以下のようなディレクトリ構成で、ファイルを用意します。
特に問題がなければ app.py と requirements.txt の2つだけでOKです。

project-root/
├── app.py              # Streamlit本体
├── requirements.txt    # 必須パッケージ一覧
├── .gitignore          # 除外ファイル指定
└── packages.txt        # 補助スクリプト

3. requirements.txtの作成（依存パッケージ管理）

開発環境で利用している仮想環境が有効になっている状態で、以下のコマンドをターミナルで実行することで、
プロジェクトで使用している依存パッケージ一覧をrequirements.txtとして出力できます。

pip freeze > requirements.txt

下記は、今回私の環境で作成したrequirements.txtの内容例です。
バージョンは==で固定（ピン留め） することを推奨します。
パッケージのアップデートによる予期しない挙動や互換性の問題を防ぐためです。

requirements.txt

streamlit
ultralytics
pillow
numpy
opencv-python-headless==4.11.0.86
requests
huggingface-hub

huggingface-hubは、Hugging Faceにアップロードした学習済みモデルをロードする際に必要です。

Streamlit環境では、GUIを含むopencv-pythonをインストールするとエラーが発生する場合があります。
そのため、今回はGUI機能を含まないopencv-python-headlessを使用しています。

Google Colaboratory（Colab）を開発環境として使用している場合、
pip freeze > requirements.txtを実行すると、
Colab環境にもともとインストールされている多数の不要なパッケージまで
requirements.txtに出力されてしまいます。
そのため、実際に自分のプロジェクトで利用しているパッケージだけを手動で記載するようにしましょう。

4. packages.txtの用意（システムパッケージ追加）

画像処理系ライブラリ（OpenCVやYOLOなど）を扱う場合、SCC環境で以下のエラーが出ることがあります。

ImportError: libGL.so.1: cannot open shared object file: No such file or directory

これを解消するために、以下2行を packages.txt に記載し、必ずプロジェクトファイル構成のようにプロジェクトのルートディレクトリに配置してください。

packages.txt

libgl1-mesa-glx
libglib2.0-0

必要に応じて他のシステムパッケージもここに追記します。

5. GitHubリポジトリ作成・プッシュ

5.1 新規リポジトリ作成

GitHubのリポジトリ作成手順に従って作成します。

5.2 ファイル配置＆プッシュ

app.py・requirements.txt・packages.txt など、必要なファイルをプロジェクトファイル構成に従ってリポジトリに追加・プッシュしてください。

リポジトリはパブリック・プライベートどちらでも作成できますが、SCCとGitHubの連携に注意してください。こちらを参照。

下図のようなイメージで、GitHubのWeb画面で主要なファイルが正しく配置されていることを確認してください。

6. 学習済みモデルの配置（Hugging Face連携）

6.1 モデルファイルはGitHubに置かない

GitHubでは50 MBを超えるファイルがアップロード制限にかかるため、学習済みモデルはHugging Faceにホストして利用する方法を採用しました。

6.2 Hugging Faceへ学習済みモデルアップロード

アップロード手順はこちら

6.3 Streamlitからモデルをダウンロード・利用する

app.pyに下記のように記述します（Secrets対応）。
Streamlit 上から学習済みモデルを読み込むことができるようになります。
Streamlitの「Sectets」については後に説明します。

import streamlit as st
from huggingface_hub import hf_hub_download, login
from ultralytics import YOLO

# ────────────
# 1. Hugging Face トークンの取得とログイン
# ────────────
# Streamlit の "Secrets" に保存したトークンを読み込み
hf_token = st.secrets["HUGGINGFACE_TOKEN"]

# Hugging Face 上で認証セッションを開始
login(token=hf_token)

# ────────────
# 2. モデル読み込み関数の定義
# ────────────
@st.cache_resource
def load_yolo_model(repo_id: str, filename: str) -> YOLO:
    """
    YOLO モデルを Hugging Face からダウンロードして読み込む関数。
    @st.cache_resource デコレータを付けることで、
    「一度ダウンロード・初期化したモデル」をキャッシュし、以降は再利用します。

    Args:
        repo_id (str): Hugging Face 上のリポジトリパス（例: "username/model-name"）
        filename (str): リポジトリ内のモデルファイル名（例: "best.pt"）

    Returns:
        YOLO: 初期化済みの YOLO モデルオブジェクト
    """
    # モデルファイルを認証付きでダウンロード
    model_path = hf_hub_download(
        repo_id=repo_id,
        filename=filename,
        use_auth_token=hf_token
    )
    
    # YOLO モデルを初期化
    model = YOLO(model_path)
    return model

# ────────────
# 3. 実際にモデルをロード（初回だけダウンロード／初期化される）
# ────────────
MODEL_REPO = "username/your-trained-yolo-repo"  # ←自分のリポジトリに書き換えてください
MODEL_FILE = "your_model.pt"                   # ←実際のモデルファイル名に書き換えてください

model = load_yolo_model(repo_id=MODEL_REPO, filename=MODEL_FILE)

# ────────────
# 4. 以降のアプリ内で `model` を使って推論できます
# ────────────
# 例: results = model.predict("path/to/image.jpg")

再トレーニングしたモデルをデプロイしたい場合は、Hugging Face上の学習済みモデルファイルを差し替えるだけでOKです。

7. Streamlit Community Cloud（SCC）でのデプロイ

7.1 GitHub連携

SCCアカウント作成＆GitHub連携方法はこちら

7.2 アプリのデプロイ手順

1. Homeの「Create app」を選択

2. 「Deploy a public app from GitHub」を選択

3. デプロイ対象のリポジトリ・ブランチ・メインファイルパスを指定

空欄をクリックすると、「Repository」 がプルダウンで表示されるので、デプロイしたいリポジトリを選択してください。
「Branch」、「Main file path」 も同様に選択してください。
「App URL」 は自動で設定されます。(自分で指定したい場合は自分で設定することも可能)

4. Hugging Faceとの連携設定

Streamlitでは、外部に公開したくないAPIキーや認証情報などを安全に管理するために「Secrets」機能が用意されています。
たとえば、Hugging FaceのAPIキーを使用する場合、
以下のように保存して利用します：

画像の「Advanced sttings」をクリックしてください。

5. 各種設定を行う

① Pythonのバージョン指定を行いたい場合はこちらで設定
② Hugging Face APIキーはこちらに記述
③ 設定が終わったら「Save」ボタンで保存

6. 最後に「Deploy」ボタン「を押して完了です！

Hugging Faceとの連携設定を後から行う場合

1. デプロイしたいアプリの3点リーダーを選択

Streamlit Community Cloud にアクセスし、デプロイしたいアプリの設定を変更します。

2. 設定を選択

3. 「Secrets」タブを選択し、写真のように設定し、保存する。

黒塗りの部分にご自分のAPIキーを記述してください。

7.3 公開・動作確認

外部公開の方法です。自身のアプリを開き、以下の手順に従ってください。
① 「Share」ボタンを押す
② 「Make this app public」をonにする
③ 「Copy link」で共有URLを取得できます！！

これを見せたい人に共有して気軽にアプリを外部公開できます！！

7.4 ポケモン図鑑👾アプリ

以下のURLが実際に作った簡単なポケモン図鑑アプリです。
画像をアップロードすることでポケモンを検出できます🔍
アノテーションが大変で「ヒトカゲ」・「リザード」・「リザードン」の3種類しか検出できません^^
色違いは対応していますがメガ進化は対応していません！！！
ぜひ遊んでみてください〜！
https://pokemon-detector-mkywfn9svwca8bpstzg7b5.streamlit.app/

⚠️エラーが出たら⚠️

1. 右下の「Manage App」をクリック

2. 赤枠のログを参考にデバッグしましょう

3. デバッグを反映させましょう

デバッグが終わったら
① 3点リーダーをクリック
② 「Reboot app」をクリック
これで変更内容が適用されます👍

最後に

アプリ公開後も依存パッケージのアップデートなどでエラーが出ることがあります。定期的にアプリの動作確認を推奨します。
Streamlitアプリを外部公開する際はセキュリティ（SecretsやAPIキーの管理等）にも十分ご注意ください。
アプリのエラー・質問・ご指摘・「ここを詳しく知りたい」等があれば、ぜひコメントでお知らせください！