Dockerfile for llama.cpp on Linux with AMD GPU

llama.cpp をローカル PC で実行するための Docker 環境構築ファイル群

手元の Linux ホスト環境をあまりいじらずに llama.cpp を試せるようにしたもの

• 扱いやすいように compose.yml を用意
• オフィシャルのコンテナイメージ を使うが、 CLI としては使い勝手が悪いので llama-cli 用にコンテナイメージを微修正
• WebUI はオフィシャルの server-rocm タグイメージをそのまま使用
  • Ollama と同様に root ではないユーザで実行しようと画策したが、 パラメータとして引き渡す環境変数が多すぎるて同じ方法は困難なので断念
• CLI はオフィシャルの light-rocm を流用し、ユーザ権限や起動方法を変更
• server-rocm と light-rocm の 2 つのイメージを pull することになるが、 Dockerfile を見ると llama-cli か llama-server かの違いしかないので、 差分を pull するだけで専有する容量はあまり変わらない

llama-cli コンテナイメージの Build

.env の修正

使用している Linux ホスト環境に合わせて .env を修正する

• UID : llama-cli 実行する際のユーザ ID
  • 使用者の Linux ホストの UID を指定するとパーミッション的に扱いやすい
  • 自身の UID は id -u コマンドで取得できる
• RENDER_GID 【必須】: Linux ホストの render グループ ID
  • 値は getent group render コマンドで確認できる
  • この値が間違っていると GPU が使えなくなる
• USER_NAME : Ollama をインタラクティブに実行する際のユーザ名
  • UID に対応したユーザ名
  • これを指定しないと user というユーザが作られる
  • ubuntu 版で UID = 1000 の場合は既存の ubuntu ユーザがそのまま使われる（名前だけ変更）
  • ユーザ名の指定そのものにはさしたる意味はないが、 実行時にホームディレクトリをマウントする際に使われる
• LANG : 実行環境の locale
  • これを指定しなければ Linux ホストの LANG 環境変数が渡される
  • 日本語ファイル名をリストする際等で文字化けしないようにするため

Build

docker compose (或いは docker-compose) コマンドを使って Build する

$ docker compose build llama-cli

設定

.env の修正

必要に応じて compose.yml ファイルを修正する

AMD の GPU で公式にサポートされているのは Supported GPUs だけ
しかしながら実際には Compatibility matrix にあるように RDNA2 〜 RDNA4 アーキであれば動いてくれる可能性がある

Linux ホストに rocminfo パッケージがインストールされていれば以下の手順で GPU のアーキがわかる

$ rocminfo | grep gfx
  Name:                    gfx1031                            
      Name:                    amdgcn-amd-amdhsa--gfx1031       

表示された gfxXXXX の LLVM target が Supported GPUs にリストされていない場合には 近い LLVM target に偽装するために以下の環境変数を指定する

• GFX_ARCH : 偽装する LLVM target
  • 例: gfx1030
• HSA_OVERRIDE_GFX_VERSION : LLVM target の数字部分をバージョンに読み替えたもの
  • 例: 10.3.0

※ 偽装しても動かない可能性はある

AMD GPU アーキの詳細については User Guide for AMDGPU Backend を参照

参考: Pytorch Performance on AMD Radeon and Instinct GPUs Page 20

compose.yml の修正

volumes セクション

一般的な volumes の記述方法に従い mount する volume を指定する

この compose.yml では ./home 配下に CLI 用のホームディレクトリがあり、 ./home/models 配下にモデルファイルがあることを前提にしている

environment セクション

必要に応じて環境変数を設定する (以下のページの env: に書かれている LLAMA_ARG_*)

• WebUI
• CLI

自身の環境に応じ値の決定にチューニングが必要なため、 まずは llama-cli で引数によりいろいろ試した後で適切な値を環境変数に指定する

llama-server service の ports セクション

必要に応じポート番号の 8080 を変更する

この設定では localhost からしか WebUI にアクセスできない
他のクライアントからもアクセスしたい場合でも、 この ports の IP アドレス設定は変えずにホスト上に nginx 等でリバースプロキシを構築するのが望ましい
※ Docker はファイアウォールをバイパスして port を公開してしまうため

実行

モデルのダウンロード

まずは Hugging Face 等にあるモデルをダウンロードする
この compose.yml をそのまま使う場合には ./home/models/ 配下にモデルを置く

CLI

CLI で操作する

CLI は試すのが楽なので、これで自分の環境に合う環境変数を模索できる

Docker 内のシェルを起動

$ docker compose run -it --rm llama-cli bash

Docker 内のシェルで llama-cli だけでなく各種コマンドを実行できる

$ ls
$ llama-cli -m models/gpt-oss-20b-mxfp4.gguf
$ LLAMA_ARG_SPLIT_MODE=none LLAMA_ARG_MAIN_GPU=0 LLAMA_ARG_N_CPU_MOE=12 llama-cli -m models/gpt-oss-20b-mxfp4.gguf

直接 llama-cli を実行

$ docker compose run -it --rm llama-cli --split-mode none --main-gpu 0 --n-cpu-moe 12 -m models/gpt-oss-20b-mxfp4.gguf

WebUI

WebUI と CLI は独立しているので WebUI が必要な時にサービスを起動する

$ docker compose up -d

※ 上記でサービス名を指定していないが、 llama-cli service には cli profile を付けているのでここで起動されることはない

WebUI が使えるようになるまでに数分かかることがあるので、 起動後すぐにアクセスせずにしばらく待つ
docker compose ps で llama-server が healthy となればアクセス可能

$ docker compose ps

サービスを起動したホスト上で Web ブラウザから WebUI にアクセスする

URL: http://localhost:8080 (ポート番号を変更している場合にはその値)