Un nodo di inferenza LLM/SLM self-hosted ad alte prestazioni, progettato per architetture AMD APU (Phoenix/Hawk Point) su Ubuntu 24.04 LTS. Il sistema è ottimizzato per fornire API ad alta velocità destinate a pipeline RAG (Retrieval-Augmented Generation), popolamento di Graph DB e integrazione fluida con piattaforme di automazione come n8n.

📐 Specifiche Tecniche (Spec-Driven)

Hardware Host: AMD Ryzen 7 260 (8C/16T), 64GB RAM Condivisa, Radeon 780M iGPU.
Sistema Operativo: Ubuntu 24.04 LTS (Kernel 6.8+).
Accelerazione: ROCm con spoofing architetturale (gfx1100).
Motori di Inferenza: * vLLM (compilato da sorgente) per throughput massimizzato su modelli generativi (es. Qwen 3.5 0.8B, Gemma 3 27B).
- Ollama per la gestione flessibile degli SLM di embedding (embeddinggemma).
Memoria: Allocazione GTT statica a livello di kernel (56GB riservati alla iGPU, 8GB al sistema operativo).

🏛️ Filosofia Architetturale

Il progetto segue tre principi fondamentali per garantire stabilità in un ambiente non-Enterprise:

Safety First: Ambienti containerizzati strettamente isolati (ipc: host), filesystem in sola lettura per i pesi dei modelli, pre-allocazione conservativa della VRAM (gpu-memory-utilization) per prevenire l'intervento dell'OOM Killer.
Little Often: Suddivisione dei servizi. Modelli di embedding leggeri su un engine, modelli generativi pesanti su un altro. Build frammentate per isolare i problemi di compilazione dei kernel C++/HIP.
Double Check: Testing rigoroso (TDD) ad ogni stadio dell'implementazione. Verifica continua dell'allocazione GTT (rocm-smi) e del corretto spoofing dell'architettura AMD.

🛠️ Prerequisiti e Configurazione Host

Prima di avviare l'infrastruttura, l'host Linux deve essere preparato per l'accelerazione hardware.

1. Impostazioni BIOS

UMA Frame Buffer Size: Impostato su Auto (lasciare la gestione dinamica al driver amdgpu).

2. Configurazione Kernel (GRUB)

Aggiungere i seguenti parametri in /etc/default/grub per stabilizzare l'iGPU ed espandere la Graphics Translation Table a 56GB:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash iommu=pt amdgpu.dc=1 amdgpu.bad_page_threshold=0 pcie_aspm=off amdgpu.gttsize=57344"

Applicare con: sudo update-grub && sudo update-initramfs -u -k all.

3. Permessi Utente

L'utente che esegue i container deve appartenere ai gruppi hardware:

sudo usermod -aG render $USER
sudo usermod -aG video $USER

🚀 Struttura del Progetto

/opt/
├── models/                             # Directory condivisa in sola lettura
│   ├── Qwen3.5-0.8B-UD-Q8_K_XL.gguf
│   └── ...
└── vllm-qwen3.5-0.8b/                  # Stack di esecuzione vLLM
    ├── docker-compose.yml
    ├── Dockerfile
    ├── test_api.py
    └── CHANGELOG.md

📦 Deployment

1. Build del Container vLLM (Custom ROCm)

L'immagine vLLM ufficiale non supporta nativamente la 780M. La compilazione dai sorgenti (v0.6.3) per gfx1100 è gestita automaticamente dal Dockerfile.

Posizionarsi nella directory operativa e lanciare la build:

cd /opt/vllm-qwen3.5-0.8b
sudo docker compose up --build -d

Nota: La compilazione dei kernel PagedAttention richiederà 15-30 minuti impegnando intensamente la CPU.

2. Monitoraggio

Verificare che l'avvio e la profilazione della memoria vadano a buon fine:

sudo docker compose logs -f

🧪 Validazione e Test (TDD)

Per confermare che l'API sia operativa e conforme allo standard OpenAI, eseguire lo script di test integrato:

python3 /opt/vllm-qwen3.5-0.8b/test_api.py

Un output corretto indica che il modello è stato caricato nella VRAM pre-allocata ed è in grado di eseguire inferenza accelerata.

🔗 Integrazione n8n

Il server vLLM espone un endpoint standard OpenAI sulla porta 8000. In n8n, utilizzare il nodo HTTP Request con le seguenti specifiche:

Method: POST
URL: http://<IP_LOCALE>:8000/v1/chat/completions
Headers: Content-Type: application/json
Body:

{
  "model": "/app/models/Qwen3.5-0.8B-UD-Q8_K_XL.gguf",
  "messages": [
    {"role": "system", "content": "Sei un estrattore di entità per Graph DB."},
    {"role": "user", "content": "{{$json.chunk_testo}}"}
  ],
  "temperature": 0.1
}