1. 目的と構築方針

本書は、Ubuntu 24.04 上でローカルLLM推論環境を構築し、将来的に PDF-RAG サイトへ接続するための標準手順を示します。重点は「壊れにくいこと」と「再現しやすいこと」です。

• NVIDIA ドライバは Ubuntu / APT 系の標準手順で導入します。.run インストーラは保守負荷が高いため標準手順から外します。
• CUDA Toolkit は NVIDIA 公式のパッケージマネージャ方式で導入します。
• vLLM は依存衝突を避けるため、既存 Python 環境へ混ぜず、必ず新しい専用環境を作成します。
• AMD 側 GPU は CUDA から見えないため、今回の vLLM 構成では計算資源として使いません。
• 標準モデルは Qwen2.5-7B-Instruct-AWQ、Qwen3.5-9B-AWQ は拡張オプションとして扱います。

2. 対象構成とモデル選定

標準手順は Qwen2.5-7B-Instruct-AWQ で最後まで通ることを優先し、Qwen3.5-9B-AWQ は付録的な拡張構成として扱います。Qwen3.5 を使う場合は text-only 運用、thinking 無効化、短めの max-model-len を前提にします。

3. 事前確認（BIOS / OS / ディスク）

• BIOS/UEFI は最新化します。特に AMD CPU 側の更新は microcode と合わせて先に済ませます。
• Secure Boot が有効な場合、NVIDIA カーネルモジュール署名まわりの追加確認が必要です。
• 空きディスクは最低 50GB を推奨します。モデルキャッシュを /opt/LLM 配下へ寄せるためです。
• Ubuntu 24.04 系を前提にし、カーネル更新後は必ず再起動します。

初回更新

sudo apt update
sudo apt full-upgrade -y
sudo reboot

4. NVIDIA ドライバ整備

まずは Ubuntu 標準の方法で NVIDIA ドライバを入れます。ドライバだけ先に安定させ、その後に CUDA Toolkit を追加します。

標準手順

sudo apt install -y ubuntu-drivers-common
ubuntu-drivers devices
sudo ubuntu-drivers install
sudo reboot

導入後の確認

nvidia-smi
cat /proc/driver/nvidia/version

nvidia-smi で RTX 4060 Ti が見えていれば、CUDA 利用の前提は整っています。AMD 側 GPU はここに出ても CUDA デバイスにはなりません。

5. CUDA Toolkit 導入

CUDA Toolkit は NVIDIA 公式のネットワークリポジトリ経由で導入します。package manager installation を標準とします。

CUDA Toolkit

cd /tmp
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2404/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update
sudo apt install -y cuda-toolkit

nvcc が見つからない場合のみ、PATH を追加します。

PATH の補正（必要時のみ）

echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
nvcc --version

6. Python / uv / 配置方針

vLLM は CUDA / PyTorch / 自前コンパイルカーネルの相性に敏感です。既存の Python 環境へ混ぜず、専用ディレクトリと専用仮想環境を切ります。

作業ディレクトリ

sudo mkdir -p /opt/LLM/qwen35/{venv,cache/huggingface,logs,run,models}
sudo chown -R $USER:$USER /opt/LLM

uv の導入

curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"
uv --version

専用 venv の作成

uv venv --python 3.12 /opt/LLM/qwen35/venv
source /opt/LLM/qwen35/venv/bin/activate
python --version

恒久設定

cat >> ~/.bashrc <<'EOF'
export QWEN35_HOME=/opt/LLM/qwen35
export HF_HOME=/opt/LLM/qwen35/cache/huggingface
export HUGGINGFACE_HUB_CACHE=/opt/LLM/qwen35/cache/huggingface/hub
alias qwen35on='source /opt/LLM/qwen35/venv/bin/activate && export HF_HOME=/opt/LLM/qwen35/cache/huggingface && export HUGGINGFACE_HUB_CACHE=/opt/LLM/qwen35/cache/huggingface/hub'
EOF
source ~/.bashrc

7. vLLM 導入

Qwen3.5 系は比較的新しいため、vLLM は fresh environment 上で導入し、必要に応じて nightly を使います。

vLLM インストール

qwen35on
uv pip install -U vllm --torch-backend=auto --extra-index-url https://wheels.vllm.ai/nightly

GPU 認識確認

python - <<'PY'
import torch
print("torch:", torch.__version__)
print("cuda available:", torch.cuda.is_available())
print("cuda version:", torch.version.cuda)
print("device count:", torch.cuda.device_count())
print("device 0:", torch.cuda.get_device_name(0) if torch.cuda.is_available() else "N/A")
PY

8. Hugging Face 認証とモデル配置

公開モデルでも、ローカル保存や将来的な gated repo 利用を考えると hf auth login を先に済ませた方が混乱が少なくなります。

ログイン

qwen35on
hf auth login

標準モデルは公式の Qwen2.5-7B-Instruct-AWQ を直接使います。Qwen3.5-9B-AWQ をローカル配置する場合は、実在する repo_id を指定し、config.json が保存されることを確認します。

標準モデル（任意にローカル化）

qwen35on
hf download Qwen/Qwen2.5-7B-Instruct-AWQ --local-dir /opt/LLM/qwen35/models/Qwen2.5-7B-Instruct-AWQ

拡張モデル（量子化配布の例）

qwen35on
hf download QuantTrio/Qwen3.5-9B-AWQ --local-dir /opt/LLM/qwen35/models/Qwen3.5-9B-AWQ
ls -lah /opt/LLM/qwen35/models/Qwen3.5-9B-AWQ/config.json

9. 推奨起動コマンド

9.1 標準構成: Qwen2.5-7B-Instruct-AWQ

qwen35on
export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
CUDA_VISIBLE_DEVICES=0 vllm serve   Qwen/Qwen2.5-7B-Instruct-AWQ   --served-model-name MY_MODEL   --quantization awq   --dtype half   --max-num-seqs 1   --max-model-len 4096   --gpu-memory-utilization 0.90   --tensor-parallel-size 1   --language-model-only   --host 0.0.0.0   --port 8000

9.2 拡張構成: Qwen3.5-9B-AWQ（thinking 無効化）

qwen35on
export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
CUDA_VISIBLE_DEVICES=0 vllm serve   /opt/LLM/qwen35/models/Qwen3.5-9B-AWQ   --served-model-name MY_MODEL   --quantization awq   --dtype half   --max-num-seqs 1   --max-model-len 4096   --gpu-memory-utilization 0.90   --tensor-parallel-size 1   --language-model-only   --reasoning-parser qwen3   --default-chat-template-kwargs '{"enable_thinking": false}'   --trust-remote-code   --host 0.0.0.0   --port 8000

10. API 疎通確認

モデル一覧

curl http://127.0.0.1:8000/v1/models

チャット疎通

curl http://127.0.0.1:8000/v1/chat/completions   -H "Content-Type: application/json"   -d '{
    "model": "MY_MODEL",
    "messages": [
      {"role": "system", "content": "簡潔に日本語で答えてください。"},
      {"role": "user", "content": "日本語で短く自己紹介して"}
    ],
    "max_tokens": 128,
    "temperature": 0.2
  }'

正常時は choices[0].message.content に回答が入り、Qwen3.5 の non-thinking 運用では reasoning が null になります。

11. systemd サービス化

本番運用では systemd 化して再起動時に自動起動させます。以下は標準構成の例です。Qwen3.5-9B-AWQ を使う場合は ExecStart だけ差し替えます。

/etc/systemd/system/qwen-vllm.service

[Unit]
Description=Qwen vLLM Server
After=network.target

[Service]
Type=simple
User=bee
Group=bee
WorkingDirectory=/opt/LLM/qwen35
Environment=HF_HOME=/opt/LLM/qwen35/cache/huggingface
Environment=HUGGINGFACE_HUB_CACHE=/opt/LLM/qwen35/cache/huggingface/hub
Environment=PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
Environment=CUDA_VISIBLE_DEVICES=0
ExecStart=/opt/LLM/qwen35/venv/bin/vllm serve Qwen/Qwen2.5-7B-Instruct-AWQ --served-model-name MY_MODEL --quantization awq --dtype half --max-num-seqs 1 --max-model-len 4096 --gpu-memory-utilization 0.90 --tensor-parallel-size 1 --language-model-only --host 0.0.0.0 --port 8000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

反映

sudo systemctl daemon-reload
sudo systemctl enable --now qwen-vllm
sudo systemctl status qwen-vllm --no-pager -l

12. トラブルシューティング

13. 運用メモ

• まずは標準構成で API を安定起動させ、その後に FastAPI / PostgreSQL / pgvector を接続します。
• Qwen3.5-9B-AWQ は拡張構成なので、量子化配布の信頼性確認と更新管理が必要です。
• PDF-RAG を組む場合、前段で PyMuPDF などによるテキスト抽出、チャンク化、埋め込み生成、pgvector 検索を実装します。
• ログやキャッシュは /opt/LLM 配下に寄せ、ホームディレクトリへ散らさないようにします。
• 環境更新時は、まず nvidia-smi、次に nvcc --version、最後に /v1/models で三段確認します。