amd-strix-halo-vllm-toolboxes/GUIDE.md

Guida: Usare vLLM con Podman su Strix Halo

Questa guida ti spiega come buildare e usare il container vLLM con il modello bullpoint/Qwen3-Coder-Next-AWQ-4bit su Debian 13 con Podman.

Prerequisiti

• Podman installato e funzionante
• AMD Ryzen AI Max "Strix Halo" (gfx1150) o GPU ROCm compatibile
• Accesso ai device /dev/kfd e /dev/dri
• Almeno 30GB di spazio disco per il modello e la cache

1. Buildare l'immagine

Dalla directory del progetto, esegui:

podman build -t vllm:rocm .

Note:

• Il build richiede 30-60 minuti a seconda della macchina
• L'immagine compila vLLM, bitsandbytes e flash-attention da sorgente
• Se il build fallisce, verifica di avere abbastanza spazio disco e memoria

Opzioni di build avanzate

Puoi passare argomenti personalizzati:

podman build \
  --build-arg ROCM_MAJOR_VER=7 \
  --build-arg GFX=gfx1150 \
  --network=host \
  -t vllm:rocm .

• --network=host - Usare la rete dell'host per i download (utile se hai problemi di connessione)
• --no-cache - Ignorare la cache e ricompilare tutto

2. Preparare i filesystem locali

Crea le cartelle per modelli e cache:

mkdir -p ~/models
mkdir -p ~/.cache/huggingface

3. Lanciare il container con GPU

Opzione A: Shell interattiva (Development)

Se vuoi esplorare il container e usare il TUI start-vllm:

podman run -it \
  --device /dev/kfd \
  --device /dev/dri \
  --network host \
  -v $HOME/models:/models \
  -v $HOME/.cache/huggingface:/cache/huggingface \
  -p 8000:8000 \
  vllm:rocm \
  /bin/bash

Dentro il container:

start-vllm

Oppure lancia direttamente:

vllm serve bullpoint/Qwen3-Coder-Next-AWQ-4bit \
  --tensor-parallel-size 1 \
  --trust-remote-code \
  --enforce-eager \
  --gpu-memory-utilization 0.90

Opzione B: Lanciare direttamente il servizio (Production)

Esegui vLLM in un unico comando senza shell interattiva:

podman run -d \
  --device /dev/kfd \
  --device /dev/dri \
  --network host \
  -v $HOME/models:/models \
  -v $HOME/.cache/huggingface:/cache/huggingface \
  -p 8000:8000 \
  --name vllm-server \
  vllm:rocm \
  vllm serve bullpoint/Qwen3-Coder-Next-AWQ-4bit \
    --tensor-parallel-size 1 \
    --trust-remote-code \
    --enforce-eager \
    --gpu-memory-utilization 0.90

Opzioni spiegate:

Opzione	Significato
-d	Esegui in background
--device /dev/kfd	Accesso alla GPU ROCm (kernel compute queue)
--device /dev/dri	Accesso agli acceleratori DRI (render engine)
--network host	Usa la rete dell'host (migliore performance)
-v $HOME/models:/models	Monta la cartella modelli locale
-v $HOME/.cache/huggingface:/cache/huggingface	Monta la cache HuggingFace
-p 8000:8000	Espone la porta dell'API OpenAI-compatible
--name vllm-server	Nome del container
--tensor-parallel-size 1	Usa 1 GPU (no parallelismo)
--trust-remote-code	Permetti codice remoto da HuggingFace
--enforce-eager	Modalità eager (debug/stability)
--gpu-memory-utilization 0.90	Usa il 90% della memoria GPU

4. Monitorare il container

Se lanciato in background (-d):

# Visualizza i log
podman logs -f vllm-server

# Visualizza i log ultimi 50 righe
podman logs -n 50 vllm-server

# Controlla lo stato
podman ps | grep vllm-server

# Entra nel container
podman exec -it vllm-server /bin/bash

5. Testare l'API

Una volta che il server è up, puoi testare con cURL:

Chat Completion

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bullpoint/Qwen3-Coder-Next-AWQ-4bit",
    "messages": [{"role": "user", "content": "Write a Python function to sort a list"}],
    "max_tokens": 200,
    "temperature": 0.7
  }'

Completamento testo

curl -X POST http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bullpoint/Qwen3-Coder-Next-AWQ-4bit",
    "prompt": "def fibonacci(",
    "max_tokens": 100
  }'

Listare modelli disponibili

curl http://localhost:8000/v1/models

6. Usare da un altro host (SSH Port Forwarding)

Se vLLM è su un server remoto:

ssh -L 0.0.0.0:8000:localhost:8000 user@remote-host

Poi da client locale:

curl http://localhost:8000/v1/models

7. Stoppare il container

# Se lanciato in background
podman stop vllm-server

# Rimuovere il container
podman rm vllm-server

# Se in shell interattiva, usa Ctrl+C e poi
podman stop <container-id>

8. Usare con systemd (Quadlet)

Se hai già usato il file vllm-rocm.container generato:

mkdir -p ~/.config/containers/systemd/
cp vllm-rocm.container ~/.config/containers/systemd/
systemctl --user daemon-reload
systemctl --user start vllm-rocm
systemctl --user status vllm-rocm

Visualizza i log:

systemctl --user logs -u vllm-rocm -n 50 -f

Modello: bullpoint/Qwen3-Coder-Next-AWQ-4bit

Caratteristiche

• Quantizzazione: AWQ (Activation-aware Weight Quantization) a 4-bit
• Vantaggi:
  • Occupa ~15-20GB di memoria (vs 50-60GB full precision)
  • Esecuzione molto veloce
  • Qualità proche al modello full precision
• Caso d'uso: Sviluppo code, task di programmazione

Parametri consigliati

vllm serve bullpoint/Qwen3-Coder-Next-AWQ-4bit \
  --tensor-parallel-size 1 \
  --trust-remote-code \
  --enforce-eager \
  --gpu-memory-utilization 0.90 \
  --max-model-len 4096 \
  --batch-size 16

Troubleshooting

Errore: "Unable to locate package python3.13"

Il container usa Python 3.13, disponibile in Debian 13. Verifica di usare debian:bookworm o debian:13-slim nella base image.

Errore: "No GPU detected"

Verifica che i device siano accessibili:

ls -la /dev/kfd /dev/dri

Se non ci sono, potrebbe essere un problema di driver. Su Strix Halo:

rocm-smi

Errore: "Out of memory"

Riduci --gpu-memory-utilization oppure --max-model-len:

vllm serve bullpoint/Qwen3-Coder-Next-AWQ-4bit \
  --gpu-memory-utilization 0.80 \
  --max-model-len 2048

Il container si ferma subito

Controlla i log:

podman logs vllm-server

Se vedi errori di compilazione, il build potrebbe non essere completato correttamente. Riprova:

podman build --no-cache -t vllm:rocm .

Link Utili

• vLLM Documentation
• HuggingFace Qwen3 Models
• ROCm Documentation

Domande Frequenti

D: Posso usare più GPU con Tensor Parallelism?
R: Sì, imposta --tensor-parallel-size 2 se hai 2 GPU. Su Strix Halo single-GPU, usa --tensor-parallel-size 1.

D: Come cambio modello senza riavviare il container?
R: Devi stoppare e riavviare il container con un modello diverso.

D: Posso usare questo con una Web UI?
R: Sì, usa HuggingFace Chat UI o altre app che supportano endpoint OpenAI-compatible.

D: Il modello viene scaricato ogni volta?
R: No, viene cachato in ~/.cache/huggingface. La prima volta richiede il download, le volte successive usa la cache.