LocalAI: l'API OpenAI completa, 100 % ospitata autonomamente

#Perché LocalAI

LocalAI (il progetto mudler/LocalAI su GitHub, con licenza MIT, creato e mantenuto da Ettore Di Giacinto e dal team LocalAI) si presenta come un «drop-in replacement» dell'API OpenAI. In pratica, le tue richieste a /v1/chat/completions, /v1/embeddings, /v1/audio/transcriptions, /v1/audio/speech o /v1/images/generations vengono inviate a un server che ospiti tu, anziché ai server di OpenAI. Nessun token lascia la tua rete, nessuna fatturazione a consumo, nessuna quota di utilizzo.

Il vero vantaggio di LocalAI non è far girare una chat in più: è unificare diverse modalità dietro un unico endpoint compatibile. Una stessa istanza serve un LLM per il testo, un modello di embedding per il tuo RAG, Whisper per la trascrizione, Stable Diffusion per le immagini e ora anche modelli video. Per un'applicazione che ha bisogno di diversi componenti, questo evita di assemblare e mantenere tre o quattro server separati, ciascuno con la propria API da imparare.

API compatibile con OpenAI

I medesimi percorsi, i medesimi payload JSON. I tuoi SDK ufficiali (openai-python, openai-node) funzionano cambiando soltanto l'URL di base.

Multi-backend

LocalAI si basa su llama.cpp (GGUF), whisper.cpp, diffusers, piper e altri a seconda del modello. Non devi installarli uno per uno.

Multimodale

Testo, embedding, audio (STT + TTS) e immagini sulla stessa istanza, ciascuno sul proprio endpoint OpenAI.

100 % locale

Funziona offline una volta scaricati i modelli. Nessuna telemetria di inferenza, nessuna dipendenza dal cloud.

Il progetto si è notevolmente ampliato nel corso delle versioni rispetto alla sua descrizione iniziale come semplice clone dell'API OpenAI. La compatibilità «drop-in» copre ormai anche le API di Anthropic e di ElevenLabs, su ciascuno dei suoi backend. Sono supportati più di 60 backend — llama.cpp, vLLM, SGLang, transformers, whisper.cpp, diffusers, MLX e MLX-VLM per Apple Silicon, tra gli altri — installabili al bisogno da una galleria di backend, senza doverli includere tutti in anticipo in un'unica immagine.

LocalAI integra anche agenti IA autonomi con uso di strumenti, RAG e supporto al protocollo MCP, nonché una modalità multiutente con autenticazione tramite chiave API, quote e controllo degli accessi basato sui ruoli. La versione 4.1.0 (aprile 2026) ha aggiunto una modalità cluster distribuito con routing intelligente in base alla VRAM disponibile e auto-scaling; la 4.2.0 (maggio 2026) ha aggiunto il riconoscimento vocale e facciale, la diarizzazione dei parlanti, un'API compatibile con Ollama e la generazione video.

#LocalAI o Ollama, a seconda del bisogno

Entrambi eseguono file GGUF tramite llama.cpp ed espongono un'API compatibile con OpenAI per il testo. La differenza sta nell'ambito e nella filosofia. Ollama punta sulla semplicità per il testo (e un po' di visione), con un'interfaccia a riga di comando essenziale; LocalAI punta su una copertura ampia — più modalità, più backend, più impostazioni, agenti integrati — al prezzo di una configurazione sensibilmente più prolissa da predisporre.

Nulla impedisce di eseguire entrambi sulla stessa macchina: Ollama per la chat interattiva quotidiana, LocalAI come gateway multimodale per le tue applicazioni che necessitano di embedding, audio o immagini attraverso la stessa API.

#Prerequisiti

Il modo più pulito per distribuire LocalAI è tramite Docker, con un'immagine dedicata in base al tuo hardware. Prevedi una quantità di memoria adeguata ai modelli che intendi usare: alla fine è la VRAM (o la RAM se usi solo la CPU) a determinare quali modelli potrai effettivamente servire.

Docker

Docker Engine o Docker Desktop recente. Docker Compose consigliato per un deploy riproducibile.

GPU (opzionale)

NVIDIA con il NVIDIA Container Toolkit per l'accelerazione CUDA 12 o 13. LocalAI accelera anche AMD (ROCm), Intel (oneAPI/SYCL) e Apple Silicon (Metal), con Vulkan come fallback generico quando nessuno di questi percorsi è applicabile. Senza GPU, tutto gira sulla CPU, più lentamente.

VRAM per dimensione (Q4)

3B ≈ 2 GB · 7B ≈ 5 GB · 14B ≈ 9 GB · 32B ≈ 19 GB · 70B ≈ 40 GB. Aggiungi un margine per un modello di embedding e/o Whisper se li servi in parallelo.

Riferimenti GPU

Una RTX 3060 12GB (di fascia base) o una RTX 4070 12GB ospita comodamente un modello da 7-14B; una RTX 4090 24GB o un Mac M4 Pro con 24-48 GB di memoria unificata per puntare a modelli più grandi.

Spazio su disco

Ogni modello occupa diversi GB, a volte di più per immagini o video. Prevedi un volume dedicato per non dover scaricare nuovamente nulla a ogni riavvio del container.

#Distribuire LocalAI con Docker

1. 01
   Avviare un container di test

   Il comando più rapido avvia LocalAI ed espone l'API sulla porta 8080. Usa l'immagine « -gpu-nvidia-cuda-12 » (o « -cuda-13 » con i driver più recenti) se hai una scheda NVIDIA, altrimenti usa l'immagine CPU predefinita.
2. 02
   Verificare che l'API risponda

   Una volta che il container è pronto, la rotta /v1/models deve restituire l'elenco (vuoto all'inizio) nel formato OpenAI. È il segno che il server è correttamente in ascolto sulla porta 8080.
3. 03
   Rendere persistenti i modelli

   Monta un volume su /models (o /build/models a seconda dell'immagine) in modo che i modelli scaricati vengano conservati dopo il riavvio. Senza volume, tutto viene scaricato di nuovo ogni volta che si esegue « docker run ».
4. 04
   Passare a Docker Compose

   Per un uso continuativo, descrivi il servizio in un docker-compose.yml: immagine, porte, volume e prenotazione delle risorse GPU. Puoi riavviare tutto con un solo «docker compose up -d».

# Lance LocalAI, API OpenAI-compatible sur le port 8080
docker run -p 8080:8080 --name localai \
  -v $PWD/models:/models \
  localai/localai:latest

# Version GPU NVIDIA (CUDA 12) :
# docker run -p 8080:8080 --gpus all \
#   -v $PWD/models:/models \
#   localai/localai:latest-gpu-nvidia-cuda-12

# Version GPU NVIDIA (CUDA 13, plus récente) :
# docker run -p 8080:8080 --gpus all \
#   -v $PWD/models:/models \
#   localai/localai:latest-gpu-nvidia-cuda-13

services:
  localai:
    image: localai/localai:latest-gpu-nvidia-cuda-12
    container_name: localai
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    environment:
      - DEBUG=true
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    restart: unless-stopped

# La route est identique à celle d'OpenAI
curl http://localhost:8080/v1/models

#Installare un modello dalla galleria

LocalAI fornisce una galleria di modelli preconfigurati, consultabile anche tramite « local-ai models list » da riga di comando o su models.localai.io: ogni voce include il backend corretto, il template del prompt e i parametri predefiniti. Puoi installare un modello specificandone il nome tramite l'API, senza scrivere YAML a mano.

# Installe un modèle de la galerie (nom d'exemple)
curl http://localhost:8080/models/apply -H "Content-Type: application/json" -d '{
  "id": "localai@qwen2.5-7b-instruct"
}'

# Suivre l'avancement du téléchargement
curl http://localhost:8080/models/jobs

Per un controllo totale, puoi anche definire manualmente un modello in un file YAML posizionato nella cartella /models. Questo file descrive il nome esposto dall'API, il backend e il file dei pesi da caricare.

name: qwen2.5-7b
backend: llama-cpp
parameters:
  model: qwen2.5-7b-instruct-q4_k_m.gguf
context_size: 8192
template:
  chat: |
    <|im_start|>system
    {{.SystemPrompt}}<|im_end|>
    {{.Input}}

#Una sola API per testo, embedding, audio e immagini

È qui che LocalAI si distingue. Ogni modalità utilizza il relativo endpoint standard OpenAI; basta aver installato il modello adeguato per ciascuna. Ecco le quattro componenti più utili.

curl http://localhost:8080/v1/chat/completions -H "Content-Type: application/json" -d '{
  "model": "qwen2.5-7b",
  "messages": [{"role": "user", "content": "Explique le RAG en une phrase."}]
}'

curl http://localhost:8080/v1/embeddings -H "Content-Type: application/json" -d '{
  "model": "bert-embeddings",
  "input": "Texte à vectoriser pour ma base vectorielle"
}'

curl http://localhost:8080/v1/audio/transcriptions \
  -H "Content-Type: multipart/form-data" \
  -F file="@reunion.wav" \
  -F model="whisper-1"

curl http://localhost:8080/v1/images/generations -H "Content-Type: application/json" -d '{
  "model": "stablediffusion",
  "prompt": "un phare breton sous la pluie, aquarelle",
  "size": "512x512"
}'

#Migrare un'app OpenAI senza modificare il codice

Poiché le rotte e i payload sono identici, migrare un'applicazione equivale a ripuntare l'URL di base e a sostituire i nomi dei modelli. Gli SDK ufficiali accettano una base_url personalizzata: è il solo parametro da modificare, che l'applicazione punti all'API di OpenAI, di Anthropic o di ElevenLabs.

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8080/v1",  # au lieu de l'endpoint OpenAI
    api_key="sk-localai",                 # ignorée si l'auth n'est pas activée
)

resp = client.chat.completions.create(
    model="qwen2.5-7b",                    # au lieu de "gpt-4o-mini"
    messages=[{"role": "user", "content": "Bonjour !"}],
)
print(resp.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:8080/v1",
  apiKey: "sk-localai",
});

const resp = await client.chat.completions.create({
  model: "qwen2.5-7b",
  messages: [{ role: "user", content: "Bonjour !" }],
});
console.log(resp.choices[0].message.content);

URL di base

Sostituisci l'endpoint OpenAI con http://votre-hote:8080/v1. Spesso basta una semplice variabile d'ambiente OPENAI_BASE_URL.

Nomi dei modelli

« gpt-4o » → il nome del tuo modello locale. È l'adattamento principale da fare nel codice o nella configurazione.

Chiave API

Opzionale localmente; inserisci qualsiasi valore se l'SDK lo richiede, oppure configura una vera chiave sul lato LocalAI.

Differenze di comportamento

Un modello locale 7B non ragiona come GPT-4. Adatta i tuoi prompt e le tue aspettative piuttosto che supporre una parità di qualità.

#Risoluzione dei problemi

Il container impiega molto tempo ad avviarsi la prima volta

Le immagini dei container LocalAI e il primo download del modello sono voluminosi. È normale; gli avvii successivi sono veloci se il volume /models è persistente.

« model not found »

Il campo « model » della richiesta deve corrispondere esattamente al « name » della galleria o del YAML. Controlla con « curl /v1/models ».

Nessuna accelerazione GPU

Assicurati di usare un'immagine « -gpu-nvidia-cuda-12 » (o « -cuda-13 »), installa il NVIDIA Container Toolkit e passa « --gpus all ». Attiva DEBUG=true per vedere il backend realmente selezionato.

Risposte lente o OOM

Il modello supera la capacità della tua VRAM e viene eseguito in parte sulla CPU usando la RAM di sistema. Passa a un formato più leggero (Q4_K_M invece di Q8_0, oppure un modello più piccolo) o riduci context_size.

Una modalità non risponde

Ogni route richiede il proprio modello: niente embedding senza un modello di embedding installato, niente /audio senza un modello Whisper. Installa il componente mancante dalla galleria.

#Per approfondire

LocalAI è solo uno dei server di inferenza open-weight disponibili. Per scegliere con consapevolezza, confrontalo con llama-server (il server HTTP di llama.cpp) e con l'approccio di Ollama, e affina il compromesso tra memoria e qualità dei tuoi modelli con la guida sulla quantizzazione. Poi collega un'interfaccia o un'app al server tramite il suo endpoint OpenAI.

• llama-server : un'API OpenAI locale con llama.cpp
• Ollama vs llama.cpp: quale scegliere
• Scegliere la quantizzazione (Q4, Q5, Q8, FP16)
• RAG locale senza programmare: Open WebUI, AnythingLLM
• Fonte: repository GitHub di LocalAI
• Fonte: documentazione ufficiale LocalAI
• Fonte: galleria dei backend LocalAI

#FAQ