docker-compose.llm.cuda.yml

# 「答える」層の推論を NVIDIA の GPU で動かすための上書き。推論サーバを定義して
# いるのは docker-compose.llm.yml なので、その後ろに重ねる:
#
#   docker compose -f docker-compose.yml -f docker-compose.llm.yml \
#                  -f docker-compose.llm.cuda.yml --profile llm up -d
#
# 手元ビルドで試すなら docker-compose.build.yml も足す(この上書きは chiezo-llm しか
# 触らないので、重ねる順さえ守ればどの土台にも乗る)。
#
# NVIDIA 専用なのでファイル名も cuda にしてある。イメージが CUDA ビルドで、
# `gpus: all` も NVIDIA Container Toolkit の経路だから、他ベンダーでは動かない。
# llama.cpp は同じビルド番号で rocm(AMD)・vulkan(ベンダー非依存)・intel などの
# イメージも出しているが、デバイスの渡し方が違う(ROCm は /dev/kfd と /dev/dri、
# Vulkan は /dev/dri)ので、使うなら別の上書きを起こすことになる。
#
# 別ファイルに分けてあるのは、GPU の指定(`gpus: all`)が「無い環境では起動そのものが
# 失敗する」設定だから。本体に書くと GPU の無いマシンで compose が通らなくなる。
#
# 前提: ホストに nvidia-container-toolkit が入っていること(WSL2 でもドライバは
# Windows 側のものを使うので、Linux 側にドライバを入れ直す必要はない)。確認は:
#
#   docker run --rm --gpus all nvidia/cuda:13.0.1-base-ubuntu24.04 nvidia-smi
#
# agent モード(/v1/ask?mode=agent)を使うならこちら側が実質の前提になる。ツール
# 呼び出しが安定するのは 8B 級からで、そのクラスを CPU で回すと 1 問が分単位になる。
services:
  chiezo-llm:
    # CUDA 13 向け。ドライバが古くて動かないときは server-cuda12-<同じビルド番号> に落とす
    # (対応 CUDA は `nvidia-smi` の右上に出る CUDA Version を見る)。
    image: ghcr.io/ggml-org/llama.cpp:server-cuda-b10156
    gpus: all
    environment:
      # 既定は Qwen3-8B の Q4_K_M(約 5GB)。
      # コンテキスト長は KV キャッシュとして VRAM を食うので、モデルのサイズだけ見て
      # 決めてはいけない。VRAM 12GB の GPU での実測(いずれも画面描画に使われる 2GB 弱を含む):
      #   ctx 32768 → 11.3GB 使用(空き 0.9GB) / ctx 16384 → 8.8GB 使用(空き 3.4GB)
      # 32k は「載る」が、画面も同じ GPU が描いている場合は空きが 1GB を切って危ない
      # (ブラウザ等が GPU メモリを要求すると Windows がシステムメモリへ退避し、
      # ホストごとページング地獄になる。docs/design-notes.md「VRAM を使い切ると…」参照)。
      # agent モードに要る量の目安は CHIEZO_AGENT_MAX_STEPS × CHIEZO_AGENT_TOOL_CHARS で、
      # 既定(6 × 3000 字)なら 16k で足りる。
      - LLAMA_ARG_HF_REPO=${CHIEZO_LLM_HF_REPO:-Qwen/Qwen3-8B-GGUF:Q4_K_M}
      - LLAMA_ARG_CTX_SIZE=${CHIEZO_LLM_CTX_SIZE:-16384}
      # 同時に処理する会話の数(llama.cpp の既定は 4)。1 にしてある — LAN 内から
      # 1 人が話すのに 4 並列は要らず、スロットごとにホスト側の計算バッファを持つぶん
      # メモリが増える(実測で llama-server のホスト RSS が 3.7GB まで育ち、
      # 8GB の VM で OOM killer に殺された)。
      - LLAMA_ARG_N_PARALLEL=${CHIEZO_LLM_PARALLEL:-1}
      # ホスト側のプロンプトキャッシュの上限(MiB)。llama-server は過去の
      # プロンプトの KV スナップショットをホスト RAM に持ち、既定は 8192MiB = 8GiB。
      # 会話を続けるほど育つので、メモリの小さい機械ではこれが OOM の直接の原因になる
      # (実測: 会話中にホスト常駐が 3.7GB まで伸びて OOM killer に殺された)。
      # 512MiB に抑えても、直前の会話の使い回しは効く(外れたぶんはプロンプトを
      # 読み直すだけで、実測 3,000 tok/s 以上出るので体感差は小さい)。
      - LLAMA_ARG_CACHE_RAM=${CHIEZO_LLM_CACHE_RAM:-512}
      # 全層を GPU に載せる(既定の auto は載る分だけ載せるので、VRAM が足りている
      # つもりで一部が CPU に残っていた、という取りこぼしを避ける)。
      - LLAMA_ARG_N_GPU_LAYERS=${CHIEZO_LLM_GPU_LAYERS:-999}
      # 思考(reasoning)は既定で切る。Qwen3 のような hybrid thinking のモデルは
      # 放っておくと 1 ステップごとに数百トークン考えるので、道具を 3〜7 回呼ぶ
      # agent モードでは待ち時間がそのぶん積み上がる。品質を優先するなら .env で -1。
      - LLAMA_ARG_THINK_BUDGET=${CHIEZO_LLM_THINK_BUDGET:-0}
      # ツール呼び出しはモデルのチャットテンプレートを通して初めて成立する。
      # b10156 では既定で有効だが、上流の既定が変わっても壊れないよう明示しておく。
      - LLAMA_ARG_JINJA=1
      - LLAMA_ARG_HOST=0.0.0.0
      - LLAMA_ARG_PORT=7011
      - LLAMA_CACHE=/models
    # 重みは VRAM に載るが、ダウンロードとロードでホスト側のメモリも要る。上限を課すのは
    # 推論はいつ殺しても失うのは 1 回の回答だけだから(取り込みと判断が逆になる理由は
    # docs/design-notes.md「メモリ方針」を参照)。
    # 4g にしてあるのは、VM で動かしている場合(WSL2 など)に VM のメモリが 8GB 程度だと、
    # 6g ではほぼ全部を 1 コンテナに渡すのと同じになり、ホスト側の余裕まで奪うため。
    mem_limit: ${CHIEZO_LLM_MEM_LIMIT:-4g}