【2025年版】YOLO-Worldをローカルで実行する手順

## 概要
https://github.com/AILab-CVC/YOLO-World

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`の検出結果
![bus.jpg](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/985195/c847fa4c-7e9e-4317-9781-f29a55792ffb.jpeg)


## 手順
### 1. GitHubからコードを取得する
`--recursive`オプションを付けることで、`/third_party`以下のサブモジュールも取得できる。cdでコードの場所に移動する。
```bash
git clone --recursive https://github.com/AILab-CVC/YOLO-World.git
cd YOLO-World
```


### 2. 学習済みモデルのダウンロード
`weight`ディレクトリを作成し、Hugging Faceから学習済みモデル（checkpoint）を落とす。今回は、APの最も高い`YOLO-Worldv2-X`を使用する。
```bash
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 ..
```
https://huggingface.co/wondervictor/YOLO-World/blob/main/yolo_world_v2_x_obj365v1_goldg_cc3mlite_pretrain_1280ft-14996a36.pth

:::note info
#### （オプション）他のモデルを使いたい場合

↓ 2025年3月時点で最新の公式READMEだと、checkpointのURLにアクセスした時に`Invalid username or password.`が出るため、過去のREADMEを参照する。

https://github.com/AILab-CVC/YOLO-World/tree/1abfce1d3692d1167e7b252a944b82e5d731cfec?tab=readme-ov-file#zero-shot-inference-on-lvis-dataset

#### ① 学習済みモデルのリンク取得
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`
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/985195/cef0b26a-e7f2-496e-b4f1-7bdb742b23ab.png)

:::


### 3. アノテーションのダウンロード
今回は LVIS-minival のアノテーションファイルをダウンロードする。
```bash
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'` エラーが出る。モデルの評価や学習を行わず、自前のデータで物体検出を行う場合でも必要っぽかった。

https://huggingface.co/GLIPModel/GLIP/blob/main/lvis_v1_minival_inserted_image_name.json

↓ 公式README（Preparing Data for YOLO-World）に他のデータセットへのリンクが記載

https://github.com/AILab-CVC/YOLO-World/blob/master/docs/data.md


### 4. 一部コードの修正
このままコンテナを作成して実行すると `SyntaxError` が発生するため、コードを修正する必要がある。

```bash
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`の返却値受け取り部分を削除する。

```diff_python:yolo_world.py
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の修正
```Dockerfile: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 行目から先を、以下のように書き換える。

```bash:pyproject.toml
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からイメージを作成する。
```bash
docker build -t yolo-world .
```

イメージ作成が完了次第コンテナを作成し、Dockerコンテナへ接続する。`~/YOLO-World` の部分はマウント元のパス。
```bash
docker run -it --name yolo-world --gpus all -v ~/YOLO-World:/yolo yolo-world
```

#### ② 実行
Dockerコンテナ内で以下のコマンドを実行することで、`YOLO-Worldv2-X`による物体検出が実行できる。
他のモデル（例： `YOLO-Worldv2-S`）を使用したい場合は、手順 2-① でダウンロードしたパスを`[学習済みモデルのパス]`、手順 2-② のパスを `[configのパス]` に書き換える。

<details><summary>コマンドライン引数の説明</summary>

> PYTHONPATH=./ python3 [実行ファイル] [configのパス] [学習済みモデルのパス] [入力画像パス] [検出したいプロンプト] [--topk Top-k] [--threshold 信頼スコア閾値] [--output-dir 出力画像パス]

</details>

```bash
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）

https://github.com/AILab-CVC/YOLO-World/tree/master/demo


## まとめ
以上の手順で実行できる。なかなか大変だった。。。
YOLO-Worldをオープンソースで公開してくれた貢献者の方々に感謝です。

↓ 参考になったIssues

https://github.com/AILab-CVC/YOLO-World/issues/573