Questo articolo è diverso dagli altri che ho scritto in questa serie su AI privata. Gli altri parlano di strategia, architettura, scelte di alto livello. Questo è una guida tecnica step-by-step. Se siete il CTO o il tech lead che ha deciso di portare un ecosistema AI privato dentro l’azienda e volete sapere esattamente cosa fare lunedì mattina per partire, è qui.
Lavoro come cofondatore di LocalAI.io dal 2023, e in questi anni ho visto centinaia di setup in produzione. Ho distillato in questa guida il percorso operativo che, a partire da un Mac Mini M4 Pro o un server Linux base, in 90 minuti porta un’azienda dal “non abbiamo niente” a un ecosistema AI privato completo, con gateway compatibile OpenAI, modello locale funzionante, vector database per il RAG, primo agente che risponde alle domande sui vostri documenti aziendali.
La guida è scritta per chi sa cosa è Docker e ha terminale aperto. Se siete completamente nuovi al mondo dell’infrastruttura container, vi consiglio di lavorare insieme a un developer che vi affianchi sui primi step. Il setup di base è semplice, ma la produzione richiede un occhio operativo.
Prerequisiti hardware e software
Per una prima installazione LocalAI di valutazione, ipotizziamo lo scenario più semplice: un Mac Mini M4 Pro 48 GB. Vanno bene anche un Linux server con almeno 32 GB di RAM, una workstation con RTX 4070 o superiore, oppure un server cloud privato italiano con GPU dedicata. Per produzione su 100+ utenti simultanei serve hardware più potente (vedere la mia guida hardware precedente).
Software preliminare: Docker installato e funzionante (Docker Desktop su Mac, Docker Engine + Compose v2 su Linux), 50 GB di spazio disco libero (i modelli pesano), connessione internet veloce per il primo download dei modelli, terminale e un editor di testo.
Verifica preliminare:
docker --version
docker compose version
df -hSe Docker non è installato, fermarsi qui e installarlo (su Mac da docker.com, su Linux con i package manager standard). Procediamo assumendo che il setup di base sia pronto.
Step 1: avvio di LocalAI base (15 minuti)
Creiamo la cartella del progetto e il file Docker Compose minimo:
mkdir -p ~/ai-aziendale/{models,data}
cd ~/ai-aziendaleCreiamo il file docker-compose.yml:
services:
localai:
image: localai/localai:latest
container_name: localai
restart: unless-stopped
ports:
- "8080:8080"
environment:
- LOCALAI_API_KEY=cambia-questa-chiave-in-produzione
- MODELS_PATH=/models
- CONTEXT_SIZE=4096
- THREADS=8
volumes:
- ./models:/models
- ./data:/dataSe siete su server Linux con GPU NVIDIA, usate l’immagine localai/localai:latest-gpu-nvidia-cuda-12 e aggiungete la configurazione GPU sotto deploy.resources.reservations.devices.
Avviamo il container:
docker compose up -dIl primo avvio scarica l’immagine, può richiedere 5-10 minuti a seconda della velocità della connessione. Verifichiamo che sia attivo con curl http://localhost:8080/readyz. Se vede risposta OK, LocalAI è in piedi. La Web UI è raggiungibile a http://localhost:8080.
Step 2: scaricare e caricare il primo modello (20 minuti)
LocalAI ha una galleria integrata di modelli pre-configurati. Per partire, scarichiamo Qwen 4 32B-A3B che è la mia raccomandazione di default per la PMI italiana (rapporto qualità/velocità ottimale).
Dalla Web UI: tab Models → cercare “qwen” → cliccare Install sul modello desiderato. In alternativa via CLI:
curl -X POST http://localhost:8080/models/apply
-H "Content-Type: application/json"
-H "Authorization: Bearer cambia-questa-chiave-in-produzione"
-d '{"id": "huggingface@Qwen/Qwen3-32B-A3B-Instruct"}'Il download impiega 15-20 minuti per un modello da 32B (18 GB di peso quantizzato Q4). Quando il modello è caricato, testiamolo:
curl http://localhost:8080/v1/chat/completions
-H "Content-Type: application/json"
-H "Authorization: Bearer cambia-questa-chiave-in-produzione"
-d '{
"model": "qwen3-32b-a3b",
"messages": [
{"role": "system", "content": "Rispondi in italiano professionale."},
{"role": "user", "content": "Cosa sai dell AI Act europeo?"}
],
"temperature": 0.7
}'Se la risposta arriva, il modello è funzionante. Su un Mac Mini M4 Pro, aspettate 50-70 token al secondo.
Step 3: integrare un’applicazione esistente (10 minuti)
LocalAI espone API completamente compatibili OpenAI. Qualsiasi applicazione che usa la libreria OpenAI può essere ripuntata sostituendo base_url e api_key. Esempio Python:
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8080/v1",
api_key="cambia-questa-chiave-in-produzione"
)
response = client.chat.completions.create(
model="qwen3-32b-a3b",
messages=[
{"role": "system", "content": "Sei un assistente aziendale."},
{"role": "user", "content": "Riassumi il documento allegato in 3 punti."}
]
)
print(response.choices[0].message.content)Da qui in poi, ogni applicazione AI che il vostro team ha sviluppato (chatbot, tool interni, integrazioni con CRM) può essere ripuntata su LocalAI con tre righe di codice. È il vero superpotere dell’API-compatibility: zero refactor.
Step 4: aggiungere il vector database per RAG (20 minuti)
Per RAG (Retrieval Augmented Generation), serve un vector database che indicizzi i documenti aziendali e li recuperi semanticamente durante le query. Qdrant è la scelta più equilibrata oggi.
Aggiungiamo Qdrant al docker-compose.yml:
qdrant:
image: qdrant/qdrant:latest
container_name: qdrant
restart: unless-stopped
ports:
- "6333:6333"
- "6334:6334"
volumes:
- ./qdrant_storage:/qdrant/storageRestart dei container con docker compose up -d e verifica con curl http://localhost:6333/healthz.
Ora serve un modello di embedding per generare le rappresentazioni vettoriali dei vostri documenti. LocalAI supporta nativamente modelli di embedding. Carichiamo un modello multilingue:
curl -X POST http://localhost:8080/models/apply
-H "Content-Type: application/json"
-H "Authorization: Bearer cambia-questa-chiave-in-produzione"
-d '{"id": "huggingface@BAAI/bge-m3"}'Step 5: ingestione documenti aziendali (15 minuti)
Carichiamo i documenti aziendali nel vector database. Script Python di esempio per indicizzare una cartella di PDF:
import os
from openai import OpenAI
from qdrant_client import QdrantClient
from qdrant_client.models import VectorParams, Distance, PointStruct
from pypdf import PdfReader
import uuid
openai_client = OpenAI(
base_url="http://localhost:8080/v1",
api_key="cambia-questa-chiave-in-produzione"
)
qdrant = QdrantClient(host="localhost", port=6333)
collection_name = "documenti_aziendali"
qdrant.recreate_collection(
collection_name=collection_name,
vectors_config=VectorParams(size=1024, distance=Distance.COSINE)
)
docs_folder = "./documenti"
for filename in os.listdir(docs_folder):
if not filename.endswith(".pdf"):
continue
reader = PdfReader(os.path.join(docs_folder, filename))
for page_num, page in enumerate(reader.pages):
text = page.extract_text()
if not text.strip():
continue
chunks = [text[i:i+500] for i in range(0, len(text), 500)]
for chunk in chunks:
embedding = openai_client.embeddings.create(
model="bge-m3",
input=chunk
).data[0].embedding
qdrant.upsert(
collection_name=collection_name,
points=[PointStruct(
id=str(uuid.uuid4()),
vector=embedding,
payload={"text": chunk, "filename": filename, "page": page_num}
)]
)
print("Indicizzazione completata.")Questo script va eseguito una volta sui vostri documenti iniziali, poi pianificato per girare quando si aggiungono nuovi documenti (cron job, n8n workflow, manuale).
Step 6: il primo agente RAG (10 minuti)
L’ultimo pezzo: l’agente che usa il vector database per rispondere a domande sui vostri documenti.
from openai import OpenAI
from qdrant_client import QdrantClient
openai_client = OpenAI(
base_url="http://localhost:8080/v1",
api_key="cambia-questa-chiave-in-produzione"
)
qdrant = QdrantClient(host="localhost", port=6333)
def chiedi(domanda: str) -> str:
embedding = openai_client.embeddings.create(
model="bge-m3",
input=domanda
).data[0].embedding
risultati = qdrant.search(
collection_name="documenti_aziendali",
query_vector=embedding,
limit=5
)
contesto = "nn".join([r.payload["text"] for r in risultati])
risposta = openai_client.chat.completions.create(
model="qwen3-32b-a3b",
messages=[
{"role": "system", "content": "Rispondi solo sulla base del contesto fornito. Se non sai, dillo."},
{"role": "user", "content": f"Contesto:n{contesto}nnDomanda: {domanda}"}
]
)
return risposta.choices[0].message.content
print(chiedi("Quali sono le regole sui rimborsi spese?"))Eseguite lo script e ponete domande sui documenti che avete indicizzato. Se le risposte sono accurate, avete un primo agente AI RAG funzionante.
Da prototipo a produzione: cosa manca ancora
Quello che abbiamo costruito in 90 minuti è un prototipo funzionante. Per portarlo in produzione su 50-200 utenti aziendali servono altri tre componenti che vale la pena pianificare subito.
Autenticazione e gestione utenti. Il setup base usa una API key condivisa. In produzione serve SSO (Okta, Azure AD, Google Workspace), oppure almeno un sistema di user management. LocalAI supporta multi-tenancy nativo, va configurato.
Frontend. Per gli utenti finali serve un’interfaccia. Open WebUI è la scelta più rapida (compatibile OpenAI, si integra con LocalAI in cinque minuti). In alternativa, sviluppate un’interfaccia custom usando librerie come Vercel AI SDK o LangChain.
Monitoraggio e logging. Per l’AI Act servirà logging strutturato di tutte le interazioni, metriche di performance, alert su anomalie. LocalAI esporta metriche Prometheus, che potete agganciare a Grafana per dashboard di monitoraggio. Per il logging completo, vale la pena integrare un sistema come Langfuse o un equivalente custom.
Backup e disaster recovery. I modelli pesano decine di GB e sono difficili da redownlodare velocemente. Il vector database con i vostri documenti indicizzati è ancora più critico. Pianificare backup periodici delle cartelle models/ e qdrant_storage/.
Stack alternativo e specializzazioni
Lo stack base che ho descritto va bene per la PMI italiana media. Per scenari più specifici:
Per aziende che vogliono modelli multipli in parallelo (uno per chat, uno specializzato per estrazione strutturata, uno per codice): LocalAI gestisce nativamente più modelli, basta caricarli tutti e routare le richieste applicativamente.
Per workload server con alta concorrenza (200+ utenti simultanei): valutare vLLM come motore di inferenza sotto LocalAI, oppure deployment distribuito su più nodi GPU.
Per fine-tuning su dati aziendali specifici: LocalAI supporta fine-tuning LoRA. Setup più complesso, vale la pena partire dal supporto della community o di chi conosce il dominio.
Cosa fare nei prossimi 30 giorni
Una volta avviato lo stack di base, vale la pena pianificare le prime quattro settimane di adozione interna con metodo.
Settimana 1: setup completo (i 90 minuti di questa guida), indicizzazione di un primo corpus documentale ristretto (es. policy HR, FAQ tecniche), test con 3-5 utenti early adopter del team interno.
Settimana 2: raccolta feedback, miglioramento del system prompt, espansione del corpus a documenti aggiuntivi, prima integrazione con un sistema aziendale (CRM, helpdesk).
Settimana 3: apertura a 10-20 utenti, monitoraggio metriche (latenza, qualità delle risposte, errori), aggiunta del frontend Open WebUI o equivalente.
Settimana 4: valutazione roll-out più ampio, definizione del piano di scalabilità (più hardware, più modelli, integrazione con SSO aziendale), pianificazione governance.
Per chi sta valutando l’avvio di un ecosistema AI privato aziendale e vuole supporto operativo, c’è la pagina Advisory dove descrivo i formati di collaborazione che propongo. Per la community LocalAI in italiano, il canale Discord di LocalAI.io è il posto giusto.
La domanda finale, quella che cambia il modo di fare AI aziendale nei prossimi 12 mesi, è semplice. Lunedì mattina, avete in casa il vostro primo endpoint AI privato funzionante? Se la risposta è no, questa guida vi dà tutto quello che serve per cambiarla entro le 12.