こんな人に向けて
- Raspberry Pi 4 で Immich を動かしているが、顔識別やスマート検索は重くて切っている
- そのためだけにミニ PC へ買い替えるのはちょっと悔しい
- 家に Windows PC(できれば Mac も)があり、普段はそこそこ暇をしている
- ルーターで固定 IP を振るのは面倒。人に配っても同じ手順で動く構成にしたい
あくまで我が家の構成での話です。
機械学習のコンテナには認証がありません。家の LAN の外には絶対に出さないでください。
実行した結果の損害について筆者は一切責任を取りませんし、取れません。それを承知の方のみご利用ください。
背景ポエム
前回の記事で、NAS の写真を S3 Glacier Deep Archive にバックアップしつつ、家に落ちていた Raspberry Pi 4 の Immich で閲覧できるようにしました。そのとき「便利な検索機能が制限されてもいい」と書いて、顔識別とスマート検索は潔くあきらめています。Pi4 には荷が重いからです。
ところが使い始めると、妻から「子供の写真だけまとめて見たい」と言われます。そりゃそうです。高額な一眼を維持するために奥様の理解は不可欠なため、対応することにします。
最初は Pi4 の買い替えを考え、本命は Intel N100 / N150 のミニ PC(3〜4 万円前後)で高い。Pi5 はケースや電源までそろえると N100 機と値段が変わらず、Immich の機械学習のアクセラレータも使えないので微妙。
なので リモート MLを試します 。Immich の機械学習はコンテナなので、別PCでコンテナを動かせばいいということに気づきました。これで3万円浮きましたので、新しいレンズ代に回します。
リモート ML とは
Immich は「本体(サーバー)」と「機械学習(ML)」が別々のコンテナで、HTTP でやりとりしているだけです。なので ML のコンテナ immich-machine-learning だけを別の PC で動かし、本体にはその URL を教えれば済みます。公式ドキュメントでは Remote Machine Learning として案内されています。
- 本体から PC に送られるのは プレビュー画像だけ。元写真は送らず、PC 側にも保存されない
- PC は顔の位置や特徴、画像の特徴を数値にして返すだけ。結果はラズパイの DB に入る
- 顔のグループ分け(顔認識)はラズパイ側の処理
- 重いのは最初の全件処理だけ。あとは新しく取り込んだ写真の分だけになる
- 通信は家の LAN の中だけ。クラウドの料金は1円もかかりません。
要件
- Immich 本体は Pi4 に置いたまま、顔検出・スマート検索・OCR を Windows PC で動かす
- Windows PC が止まっているときは Mac が予備で処理する
- 固定 IP を使わない。PC は名前で探す
- 設定ファイルに自分の家の IP や PC 名を書かない(リポジトリをそのまま公開・配布できる)
- PC が全部止まっていても、閲覧やバックアップは普段どおり動く
用意するもの
- Immich が動いている Raspberry Pi 4(前回の記事の構成)
- Windows 10/11(64bit)の PC、メモリ 8GB 以上
- Docker Desktop(WSL 2 バックエンド)
- (任意)予備の Mac。Apple シリコンでも Intel でも可
- (任意)GPU。NVIDIA なら CUDA、Intel の内蔵 GPU なら OpenVINO で速くなる。なくても CPU で動く
dockerのインストールは別サイトにたくさん書いてありますのでそちらをご参照ください。
構成
[ラズパイ] [Windows PC(予備 Mac)]
immich_server ──> 中継 ml-relay ──(LAN, 名前で接続 :3003)──> immich_machine_learning
(コンテナ) (ラズパイ本体) desktop-abc123.local 顔の位置・特徴、画像の特徴を返す
└─ 結果を PostgreSQL に保存。顔のグループ分けはラズパイ側
| 項目 | 選んだもの |
|---|---|
| ML を動かす場所 | Windows PC の Docker Desktop(予備に Mac) |
| PC の探し方 | mDNS の名前(xxx.local)。固定 IP なし |
| コンテナ → PC の橋渡し | ラズパイ本体の socat(systemd のサービス immich-ml-relay@primary / @backup) |
| Immich の設定 |
immich-config.json に http://host.docker.internal:3101 と :3102 だけを書く |
| PC の名前の置き場所 | ラズパイの immich/.env(Git には入れない) |
| GPU |
.env の ML_ACCEL と docker-compose.yml のコメントで CPU / CUDA / OpenVINO を切り替え |
真ん中の「中継」がこの記事のいちばんのポイントです。なぜこんなものが要るのかは、後半のハマりどころに書きました。
手順
コードは yusuke-git/nas-photo-backup-s3 に置いています。
1. PC で機械学習のコンテナを起動する
PC にリポジトリを clone(またはダウンロード)し、Docker Desktop を起動してから PowerShell で実行します。
cd nas-photo-backup-s3\immich\remote-ml
copy example.env .env # CPU で動かすなら編集はいらない
docker compose up -d
docker compose logs -f # "Application startup complete" が出れば起動済み(Ctrl+C で抜ける)
中身は公式の構成をほぼそのまま使っています。
name: immich_remote_ml
services:
immich-machine-learning:
container_name: immich_machine_learning
# イメージ名の末尾に .env の ML_ACCEL がそのまま付く
image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-v3}${ML_ACCEL:-}
volumes:
# ダウンロードしたモデルの置き場所。消しても再ダウンロードされるだけ
- model-cache:/cache
ports:
- '3003:3003'
restart: unless-stopped
volumes:
model-cache:
.env で使われるのは次の 2 つだけです。CPU で動かすなら example.env をコピーしたままで動きます。
# ラズパイ側(immich/.env)の IMMICH_VERSION と同じ値にする
IMMICH_VERSION=v3
# GPU の種類。CPU で動かすなら = の後ろは空のまま
ML_ACCEL=
| 変数 | 意味 | 変えるとき |
|---|---|---|
IMMICH_VERSION |
機械学習コンテナのバージョン | ラズパイ側を v3.x.y のように固定しているときは同じ値にする |
ML_ACCEL |
イメージ名の末尾に付く GPU の種類。空なら CPU 版 | GPU を使うとき(次の節) |
ML_ACCEL= と = の後ろが空なのは書き忘れではなく、「何も付けない=CPU 版」という意味です。GPU使用の場合は下をご覧ください。
GPU を使う場合(任意)
GPU を使うときは、.env と docker-compose.yml の 2 か所 を変えます。片方だけでは GPU は使われません。
| 使う GPU | ① .env に書く値 |
② docker-compose.yml で行頭の # を外す行 |
|---|---|---|
| なし(CPU) |
ML_ACCEL=(空のまま) |
なし(編集しない) |
| NVIDIA(GeForce など) | ML_ACCEL=-cuda |
【NVIDIA】の印の下の 8 行 |
| Intel の内蔵 GPU / Arc | ML_ACCEL=-openvino |
【Intel】の印の下の 2 行と、volumes: の中の【Intel】の 1 行 |
docker-compose.yml には GPU 用の設定がコメントで入れてあるので、使う GPU の印が付いた行の行頭の # (シャープと空白 1 つ)だけを外します。字下げは残します。NVIDIA なら、外したあとはこうなります。
image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-v3}${ML_ACCEL:-}
volumes:
- model-cache:/cache
ports:
- '3003:3003'
restart: unless-stopped
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities:
- gpu
Intel の内蔵 GPU ならこうです。
image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-v3}${ML_ACCEL:-}
volumes:
- model-cache:/cache
- /usr/lib/wsl:/usr/lib/wsl
ports:
- '3003:3003'
restart: unless-stopped
devices:
- /dev/dxg:/dev/dxg
書き換えたら反映して確かめます。
docker compose config # エラーが出なければ書き方は合っている(字下げのずれはここで分かる)
docker compose up -d # GPU 用のイメージに入れ替わる(初回は数 GB のダウンロード)
docker compose ps # IMAGE の末尾が -cuda または -openvino になっていること
ジョブの実行中にタスクマネージャーの「パフォーマンス」で GPU の使用率が上がっていれば、GPU で動いています。NVIDIA は Windows 側に新しいドライバーが入っていれば WSL 2 からそのまま使えます。
Mac を予備にする場合 も同じフォルダをターミナルで起動するだけです(ML_ACCEL は空のまま)。Mac の Docker からは Apple の GPU を使えないので CPU で動きますが、M シリーズなら Pi4 よりずっと速いです。
cd nas-photo-backup-s3/immich/remote-ml
cp example.env .env
open -e .env # IMMICH_VERSION をラズパイ側と同じにする
docker compose up -d
2. PC の名前を調べる
| PC | 調べ方 | 書く名前の例 |
|---|---|---|
| Windows | 「設定」→「システム」→「バージョン情報」の「デバイス名」 |
desktop-abc123.local(デバイス名に .local を付ける。大文字小文字は区別しない) |
| Mac | 「システム設定」→「一般」→「共有」のいちばん下の「ローカルホスト名」 | my-mac.local |
ラズパイから名前が引けて、コンテナまで届くかを確かめます。
getent hosts desktop-abc123.local # IP が表示されれば名前は引けている
curl http://desktop-abc123.local:3003/ping # pong と返ればコンテナまで届いている
getent が何も返さないときは、ラズパイ側に mDNS を引く仕組みが入っていません。sudo apt-get install -y avahi-daemon libnss-mdns で入ります(次の手順のスクリプトを使うなら自動で入ります)。
3. ラズパイに PC の名前を登録する
前回の記事のセットアップスクリプト setup/3-pi-immich.sh の冒頭に PC の名前を書いて、もう一度実行します。
# 顔認識などの機械学習を動かす PC の名前。固定 IP は不要。空なら使わない
ML_PRIMARY_HOST="desktop-abc123.local" # Windows のデバイス名 + .local
ML_BACKUP_HOST="my-mac.local" # Mac のローカルホスト名。予備。なければ空のまま
cd /opt/nas-photo-backup
nano setup/3-pi-immich.sh
bash setup/3-pi-immich.sh
スクリプトは .env への書き込み、中継の導入、Immich の再起動までを行います。手でやるならこうです。
cd /opt/nas-photo-backup/immich
nano .env # ML_PRIMARY_HOST=desktop-abc123.local と ML_BACKUP_HOST=my-mac.local を書く
sudo apt-get install -y socat avahi-daemon libnss-mdns
sed "s|@REPO_DIR@|/opt/nas-photo-backup|" ml-relay/immich-ml-relay@.service | sudo tee /etc/systemd/system/immich-ml-relay@.service
sudo systemctl daemon-reload
sudo systemctl enable --now immich-ml-relay@primary immich-ml-relay@backup
docker compose up -d --force-recreate immich-server
systemctl status immich-ml-relay@primary # 「中継: 172.17.0.1:3101 -> desktop-abc123.local:3003」と出ていれば OK
Immich 側の設定はこれだけです。どの家でも同じ内容になるので、そのまま Git に入れています。
{
"machineLearning": {
"enabled": true,
"urls": [
"http://host.docker.internal:3101",
"http://host.docker.internal:3102"
]
}
}
host.docker.internal をコンテナから引けるように、ラズパイ側の docker-compose.yml の immich-server に 2 行足しています。
extra_hosts:
- 'host.docker.internal:host-gateway'
4. 初回の全件処理
- ブラウザで Immich を開き、右上ユーザーアイコンの「管理」→左の「待機中ジョブ」
- 「スマート検索」「顔検出」「OCR」を すべて で実行する
- 顔検出が終わると「探索」を押したとき人物が表示されます。
処理中は PC のタスクマネージャーで CPU / GPU が回っているのが見えます。終わるまで PC をスリープさせない でください(電源設定でスリープを一時的に切っておくと安心です)。
我が家の実績は、写真 約 4,600 枚 で、全部合わせて 20 分くらい(体感)でした。PC は Core i9-10980XE と GeForce RTX 3090 で、GPU(ML_ACCEL=-cuda)で動かしています。Pi4 だけなら何日もかかるはずの処理が、お茶を淹れている間に終わります。
普段の運用
- 新しい写真は 6 時間ごとのスキャンで取り込まれ、そのとき PC が起動していれば機械学習も自動で進む
- PC が止まっていて失敗した分は、PC を起動してから「ジョブ」画面の各ジョブの「不足分」を押すとまとめてやり直せる
- PC でコンテナを常に動かす必要はない。使わないときは
docker compose stop、再開はdocker compose start - ラズパイの Immich を更新したら、PC 側も
docker compose pull && docker compose up -dで同じバージョンにそろえる
中継(ml-relay)の中身
ラズパイ本体で動かしている中継は、socat を 1 行呼んでいるだけの小さなスクリプトです。
#!/usr/bin/env bash
# Immich(コンテナ)から、Windows PC / Mac の機械学習コンテナへの通信を中継する。
# 使い方: ml-relay.sh primary|backup
set -euo pipefail
ENV_FILE="${ENV_FILE:-$(cd "$(dirname "$0")/.." && pwd)/.env}"
case "${1:-}" in
primary) var=ML_PRIMARY_HOST; port=3101 ;;
backup) var=ML_BACKUP_HOST; port=3102 ;;
*) echo "使い方: $0 primary|backup" >&2; exit 2 ;;
esac
[ -r "$ENV_FILE" ] || { echo "$ENV_FILE が読めません" >&2; exit 1; }
# .env の「名前=値」から値だけを取り出す(引用符と空白は取り除く)
host=$(sed -n "s/^${var}=//p" "$ENV_FILE" | tail -n 1 | tr -d "\"' \r")
if [ -z "$host" ]; then
echo "$var が空なので中継しません"
exit 0
fi
# Docker のブリッジ(docker0)の IP だけで待ち受ける。LAN からは見えない
bind=$(ip -4 -o addr show docker0 2>/dev/null | awk '{print $4}' | cut -d/ -f1 | head -n 1)
[ -n "$bind" ] || { echo "docker0 が見つかりません(Docker が起動していない)" >&2; exit 1; }
echo "中継: $bind:$port -> $host:3003"
exec socat "TCP-LISTEN:$port,bind=$bind,fork,reuseaddr" "TCP:$host:3003,connect-timeout=3"
[Unit]
Description=Immich の機械学習への中継 (%i)
After=docker.service avahi-daemon.service network-online.target
Wants=network-online.target
BindsTo=docker.service
[Service]
ExecStart=/opt/nas-photo-backup/immich/ml-relay/ml-relay.sh %i
Restart=on-failure
RestartSec=10
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=read-only
PrivateTmp=yes
[Install]
WantedBy=multi-user.target
ポイントは次のとおりです。
| 工夫 | 理由 |
|---|---|
socat の fork
|
接続が来るたびに子プロセスが名前を引き直してつなぐ。PC の IP が DHCP で変わっても、何もしなくても追従する |
bind= で docker0 の IP だけ |
中継の口をコンテナからしか見えないようにする。LAN の他の機器からはラズパイの 3101 / 3102 に届かない |
connect-timeout=3 |
PC が止まっているときにすぐあきらめて、Immich が次の URL(Mac)を試せるようにする |
immich-ml-relay@primary / @backup
|
systemd のテンプレートユニット。1 つのファイルで Windows 向けと Mac 向けの 2 つを動かす |
| 名前が空なら何もせず終了 | Mac がない家は ML_BACKUP_HOST を空にするだけ。:3102 は応答しないだけで害はない |
名前には mDNS の xxx.local のほか、Tailscale の名前や IP も書けます。mDNS が通らない環境(メッシュ Wi-Fi の機種によっては通らないことがあります)でも逃げ道があります。
セキュリティで気をつけたこと
| 対象 | やったこと |
|---|---|
| 機械学習のコンテナ | 認証がない。LAN の中から誰でも呼べるので、ルーターでポート 3003 は開けない |
| Windows のファイアウォール | 許可はプライベートネットワークだけ |
| ラズパイの中継 |
docker0 でだけ待ち受け、LAN には出さない。systemd 側でも NoNewPrivileges や ProtectSystem=strict で権限を絞る |
| 送るデータ | プレビュー画像だけ。元写真は送らず、PC 側には保存されない |
| リポジトリ | IP も PC 名も入れない。各家庭の .env にだけ書く |
ポート 3003 に届かないときに手でファイアウォールを開ける場合も、プロファイルを Private に限定します。
New-NetFirewallRule -DisplayName "Immich ML (LAN)" -Direction Inbound -Protocol TCP -LocalPort 3003 -Profile Private -Action Allow
ハマりどころ・迷ったところ
今回もここからが本題かもしれません。
2. Windows と Mac で分散処理はできない
Mac もあるので「2 台で分担すれば倍速では」と考えましたが、Immich にその機能はありません。urls に複数書いても、上から順に試して、最初に応答した 1 台が全部を処理する だけです(公式ドキュメントにも振り分けはしないと書かれています)。本当に振り分けたければ、前段に nginx などのロードバランサーを自分で置くことになります。
なので Mac は「分散」ではなく「予備」として登録しました。Windows が落ちているときだけ Mac が処理します。PC の電源が切れていて処理が抜ける場面が減るので、家庭ではこちらの方が実用的だと思います。
3. 固定 IP を書きたくない(DNS を立てるのはやめた)
最初の版は immich-config.json に http://192.168.1.50:3003 のように PC の IP を直接書き、ルーターの DHCP 予約で IP を固定する手順でした。動きはしますが、自分の家の IP がリポジトリに入りますし、人に勧めるたびに「まずルーターの管理画面を開いて…」から説明することになります。
「じゃあ Pi4 でローカル DNS を動かせば名前で引けるのでは」と考えましたが、やめました。
- ラズパイが止まると、家じゅうの名前解決が止まる。Immich のために家のネットが不安定になるのは割に合わない
- PC の名前を自動で登録させるには、ルーターの DHCP を切ってラズパイに任せる必要がある。ルーターごとに設定が違い、手順書が重くなる
- DHCP を任せないなら、結局 PC の IP を固定して DNS に手で書くことになり、手間が変わらない
- コンテナはホストの DNS 設定をそのまま引き継がないので、Docker 側にも別の設定が要る
そこで落ち着いたのが mDNS(xxx.local)です。Windows 10/11 と Mac は、何も設定しなくても LAN に自分の名前を知らせています。ルーターの設定も追加のサーバーも要りません。
4. コンテナの中からは .local が引けない
mDNS で解決、と思ったら次の壁がありました。ラズパイ本体では ping desktop-abc123.local が通るのに、Immich のコンテナの中からは同じ名前が引けません。コンテナの名前解決は Docker の内蔵 DNS 経由で、マルチキャストで問い合わせる mDNS は使ってくれないためです。
回避策はいくつかあります。
| 案 | 見送った理由 |
|---|---|
Immich を network_mode: host にする |
DB や Redis との接続も含めて compose を大きく変えることになる。公式の構成から離れたくない |
| コンテナに avahi のソケットをマウントする | Immich のイメージに mDNS を引くライブラリが入っていない |
extra_hosts に IP を書く |
結局 IP を固定することになる |
そこで、名前を引ける場所(ラズパイ本体)に中継を置く ことにしました。コンテナは host.docker.internal:3101 という決まった宛先に投げるだけ、名前を引くのは本体の socat、という分担です。副産物として、Immich の設定ファイルから家ごとの値が消えました。
5. Windows のネットワークが「パブリック」だと何も届かない
ラズパイから名前も引けない、ポートにも届かない、というときはまずここを疑います。Windows は、つないでいるネットワークが「パブリック」だと mDNS の問い合わせに応答せず、ポート 3003 も受け付けません。「設定」→「ネットワークとインターネット」で、家の Wi-Fi / 有線を「プライベートネットワーク」にします。
切り分けは次の順番が早いです。
getent hosts desktop-abc123.local # 1. 名前が引けるか
curl http://desktop-abc123.local:3003/ping # 2. ポートに届くか(pong)
systemctl status immich-ml-relay@primary # 3. 中継が動いているか
1 で止まるなら名前(ネットワークの種類か、ラズパイ側の libnss-mdns)、2 で止まるならファイアウォールかコンテナ、3 なら .env の書き間違いです。
6. 細かいけど気をつけるところ
-
docker compose up -dでfailed to connect to the docker API at npipe:////./pipe/docker_engine: Docker Desktop が起動していないだけ。インストールしただけではエンジンは動いていないので、スタートメニューから Docker Desktop を起動し、「Engine running」になってからもう一度実行する(私は初手でこれを踏みました) -
3-pi-immich.shがimmich/.env: Permission deniedで止まる: 以前sudoで作った.envの持ち主が root になっていた。スクリプトは普段のユーザーで動くので読み書きできない。sudo chown pi:pi /opt/nas-photo-backup/immich/.envで持ち主を戻してから再実行する(スクリプトをsudoで動かすのは不可。今はこの状態を検知して、対処のコマンドを表示して止まるようにしてあります) - バージョンをそろえる: ラズパイの Immich と PC の機械学習コンテナのバージョンがずれると不具合の原因になる。ラズパイを更新したら PC も更新する
-
設定画面から変更できない: 設定ファイル(
IMMICH_CONFIG_FILE)を使っているので、機械学習の URL は画面からは変えられない。immich-config.jsonを直してdocker compose up -d --force-recreate immich-server - PC が止まっていると「失敗」が並ぶ: ジョブの失敗数が増えるが正常。PC を起動して「不足分」を押せば回収できる。閲覧やバックアップには影響しない
-
初回のモデルのダウンロード: 最初のジョブでモデル(数百 MB〜1GB 程度)を落とすので、動き出すまで少し待つ。
docker compose logs -fで様子が見える -
PC の名前を変えたとき:
.envを直してsudo systemctl restart immich-ml-relay@primary immich-ml-relay@backup -
やめたくなったとき:
machineLearning.enabledをfalseに戻して Immich を再作成、中継をsystemctl disable --now、PC 側はdocker compose down -v。顔やスマート検索の結果は DB に残る
まとめ
- Immich の機械学習は別のコンテナなので、そこだけ家の PC に任せられる。Pi4 を買い替えなくても顔識別とスマート検索が使える
- 重いのは最初の全件処理だけ。PC は普段止まっていてもよく、失敗した分は「不足分」でやり直せる
- 複数の PC を登録しても分散はしない。2 台目は予備と割り切る
- PC は mDNS の名前で探す。固定 IP もルーターの設定もいらない
- コンテナからは
.localを引けないので、ラズパイ本体に socat の中継を置く。おかげで設定ファイルに家ごとの値が残らない - 機械学習のコンテナは認証がない。プライベートネットワーク限定、ルーターでは開けない
- Docker Desktop は Intel でも AMD64