概要
Dockerを使用してYOLO-Worldを動かす時に、2025年3月時点で公式READMEの手順どおりにインストールしても上手く動作しなかった。また、インストールを進める中で、複数のディレクトリ内にあるREADMEを行き来する必要があり分かりづらかった。
本記事では、試行錯誤の末に解決した YOLO-World のデモ手順を1からまとめた。
OS は Ubuntu 22.04.4
↓ A person wearing black clothes, blue jeans, blue painted busの検出結果
手順
1. GitHubからコードを取得する
--recursiveオプションを付けることで、/third_party以下のサブモジュールも取得できる。cdでコードの場所に移動する。
git clone --recursive https://github.com/AILab-CVC/YOLO-World.git
cd YOLO-World
2. 学習済みモデルのダウンロード
weightディレクトリを作成し、Hugging Faceから学習済みモデル（checkpoint）を落とす。今回は、APの最も高いYOLO-Worldv2-Xを使用する。
mkdir weights
cd weights
wget https://huggingface.co/wondervictor/YOLO-World/resolve/main/yolo_world_v2_x_obj365v1_goldg_cc3mlite_pretrain_1280ft-14996a36.pth
cd ..
（オプション）他のモデルを使いたい場合
↓ 2025年3月時点で最新の公式READMEだと、checkpointのURLにアクセスした時にInvalid username or password.が出るため、過去のREADMEを参照する。
① 学習済みモデルのリンク取得
README の Zero-shot Inference on LVIS dataset テーブルに移動する。
テーブルの最も右端にあるHF Checkpoints 🤗のリンクからHugging Faceのページへ移動し、Copy download linkをクリックすると、wgetで使用可能なダウンロードリンクが取得できる。
② configファイル名をメモ
テーブル一番左端のモデル名を押下してリンク先に移動し、パスとファイル名をメモしておく。
例： YOLO-Worldv2-Sの入力画像サイズ600の場合
→ configs/pretrain/yolo_world_v2_s_vlpan_bn_2e-3_100e_4x8gpus_obj365v1_goldg_train_1280ft_lvis_minival.py
3. アノテーションのダウンロード
今回は LVIS-minival のアノテーションファイルをダウンロードする。
mkdir -p data/coco/lvis
cd data/coco/lvis
wget https://huggingface.co/GLIPModel/GLIP/resolve/main/lvis_v1_minival_inserted_image_name.json
cd ../../..
これが無い場合、実行した時にNo such file or directory: 'data/coco/lvis/lvis_v1_minival_inserted_image_name.json' エラーが出る。モデルの評価や学習を行わず、自前のデータで物体検出を行う場合でも必要っぽかった。
↓ 公式README（Preparing Data for YOLO-World）に他のデータセットへのリンクが記載
4. 一部コードの修正
このままコンテナを作成して実行すると SyntaxError が発生するため、コードを修正する必要がある。
File "/yolo/yolo_world/models/detectors/yolo_world.py", line 61
self.text_feats, None = self.backbone.forward_text(texts)
^^^^
SyntaxError: cannot assign to None
お好きなエディタで YOLO-World/yolo_world/models/detectors/yolo_world.py を開き、61行目のNoneの返却値受け取り部分を削除する。
def reparameterize(self, texts: List[List[str]]) -> None:
# encode text embeddings into the detector
self.texts = texts
+ self.text_feats = self.backbone.forward_text(texts)
- self.text_feats, None = self.backbone.forward_text(texts)
5. Dockerfileと依存関係の修正
公式リポジトリのDockerfileのままだと上手く動作しないため、以下の通りに書き換える。
CUDA 11.8 と torch==2.0.x ~ 2.1.x 辺りが無難に動作する。
① Dockerfileの修正
FROM nvidia/cuda:11.8.0-devel-ubuntu22.04
ENV FORCE_CUDA="1"
ENV MMCV_WITH_OPS=1
RUN apt-get update && apt-get install -y --no-install-recommends \
python3-pip \
libgl1-mesa-glx \
libsm6 \
libxext6 \
libxrender-dev \
libglib2.0-0 \
git \
python3-dev \
python3-wheel
RUN pip3 install --upgrade pip wheel \
&& pip config set global.index-url https://pypi.org/simple \
&& pip3 install torch==2.1.2+cu118 torchvision==0.16.2+cu118 torchaudio==2.1.2+cu118 --index-url https://download.pytorch.org/whl/cu118 \
&& pip3 install --no-cache-dir \
gradio==5.6.0 \
opencv-python==4.9.0.80 \
supervision \
mmengine==0.10.4 \
setuptools \
openmim \
onnx \
onnxsim
RUN mim install mmcv==2.1.0 \
&& mim install mmdet==3.3.0 \
&& mim install mmengine==0.10.6\
&& mim install mmyolo==0.6.0 \
&& pip3 install git+https://github.com/lvis-dataset/lvis-api \
&& pip3 install numpy==1.23.5
COPY . /yolo
WORKDIR /yolo
RUN pip3 install ./third_party/mmyolo \
&& pip3 install -e .[demo]
② pyproject.tomlの修正
transformersやその他の依存関係のバージョンを指定する必要がある。YOLO-World 直下の pyproject.toml の 30 行目から先を、以下のように書き換える。
dependencies = [
"wheel",
"torch==2.1.2",
"torchvision==0.16.2",
"transformers==4.36.2",
"tokenizers",
"numpy==1.23.5",
"opencv-python==4.9.0.80",
"supervision",
"openmim",
"mmcv==2.1.0",
"mmdet>=3.0.0",
"mmengine==0.10.4",
"mmyolo",
"timm==0.6.13",
"albumentations",
]
6. Dockerコンテナ作成 & 実行
① コンテナの作成
YOLO-World直下のディレクトリに移動し、Dockerfileからイメージを作成する。
docker build -t yolo-world .
イメージ作成が完了次第コンテナを作成し、Dockerコンテナへ接続する。~/YOLO-World の部分はマウント元のパス。
docker run -it --name yolo-world --gpus all -v ~/YOLO-World:/yolo yolo-world
② 実行
Dockerコンテナ内で以下のコマンドを実行することで、YOLO-Worldv2-Xによる物体検出が実行できる。
他のモデル（例： YOLO-Worldv2-S）を使用したい場合は、手順 2-① でダウンロードしたパスを[学習済みモデルのパス]、手順 2-② のパスを [configのパス] に書き換える。
コマンドライン引数の説明
PYTHONPATH=./ python3 [実行ファイル] [configのパス] [学習済みモデルのパス] [入力画像パス] [検出したいプロンプト] [--topk Top-k] [--threshold 信頼スコア閾値] [--output-dir 出力画像パス]
PYTHONPATH=./ python3 demo/image_demo.py configs/pretrain/yolo_world_v2_x_vlpan_bn_2e-3_100e_4x8gpus_obj365v1_goldg_train_lvis_minival.py weights/yolo_world_v2_x_obj365v1_goldg_cc3mlite_pretrain_1280ft-14996a36.pth demo/sample_images 'A person wearing black clothes, blue jeans, blue painted bus' --topk 100 --threshold 0.1 --output-dir out
↓ 公式README（YOLO-World Demo）
まとめ
以上の手順で実行できる。なかなか大変だった。。。
YOLO-Worldをオープンソースで公開してくれた貢献者の方々に感謝です。
↓ 参考になったIssues