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:

```bash
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:

```bash
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:

```bash
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`:

```bash
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:

```bash
start-vllm
```

Oppure lancia direttamente:

```bash
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:

```bash
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`):

```bash
# 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

```bash
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

```bash
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

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

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

Se vLLM è su un server remoto:

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

Poi da client locale:

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

## 7. Stoppare il container

```bash
# 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:

```bash
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:

```bash
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

```bash
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:

```bash
ls -la /dev/kfd /dev/dri
```

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

```bash
rocm-smi
```

### Errore: "Out of memory"

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

```bash
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:

```bash
podman logs vllm-server
```

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

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

## Link Utili

- [vLLM Documentation](https://docs.vllm.ai/)
- [HuggingFace Qwen3 Models](https://huggingface.co/collections/Qwen/qwen3-coder-67a2e625ef1d5c6ba5a9c14c)
- [ROCm Documentation](https://rocmdocs.amd.com/)

## 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.