From 5647bc4336ad3c4e89f6344111927b5eeec11dd0 Mon Sep 17 00:00:00 2001
From: Luca Sacchi Ricciardi <luca.sacchi@gmail.com>
Date: Fri, 27 Mar 2026 13:12:33 +0000
Subject: [PATCH] added README

---
 README.md          | 112 +++++++++++++++++++++++++++++++++++++++++++++
 docker-compose.yml |   4 +-
 2 files changed, 114 insertions(+), 2 deletions(-)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bec41c2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,112 @@
+# Local AI Inference Node (Ryzen 7 260 / Radeon 780M)
+
+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:
+
+1. **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.
+2. **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.
+3. **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:
+
+```bash
+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:
+```bash
+sudo usermod -aG render $USER
+sudo usermod -aG video $USER
+```
+
+---
+
+## 🚀 Struttura del Progetto
+
+```text
+/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:
+```bash
+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:
+```bash
+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:
+
+```bash
+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:**
+```json
+{
+  "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
+}
+```
+
diff --git a/docker-compose.yml b/docker-compose.yml
index 4dae553..0e150d3 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -22,6 +22,6 @@ services:
     command: >
       --model /app/models/Qwen3.5-0.8B-UD-Q8_K_XL.gguf
       --quantization gguf
-      --gpu-memory-utilization 0.50
-      --max-model-len 4096
+      --gpu-memory-utilization 0.06
+      --max-model-len 32768
     restart: unless-stopped