LocalAI QuickStart: Esegui Localmente Modelli Linguistici Compatibili con OpenAI

LocalAI è un server di inferenza self-hosted e local-first progettato per comportarsi come un’API OpenAI plug-and-play per eseguire carichi di lavoro di IA sull’hardware proprio (laptop, workstation o server in locale).

Il progetto punta alla compatibilità pratica per “sostituire l’URL dell’API cloud”, supportando al contempo molteplici backend e modalità (testo, immagini, audio, embedding e altro).

Cos’è LocalAI e perché gli ingegneri lo utilizzano

LocalAI presenta un’API REST HTTP che replica gli endpoint chiave di OpenAI, inclusi completamenti di chat, embedding, generazione di immagini e endpoint audio, in modo che gli strumenti esistenti compatibili con OpenAI possano essere reindirizzati verso la propria infrastruttura.

Oltre alla semplice generazione di testo, l’insieme delle funzionalità di LocalAI copre i comuni “mattoni per la produzione” come gli embedding per RAG, la generazione di immagini basata su diffusione, speech-to-text e text-to-speech, con accelerazione GPU opzionale e modelli distribuiti.

Se si sta valutando il servizio di LLM self-hosted, LocalAI è interessante perché si concentra sulla compatibilità API (per un’integrazione più semplice) fornendo al contempo una Web UI integrata e un flusso di lavoro di galleria modelli per ridurre l’attrito nell’installazione e nella configurazione dei modelli.

Per un confronto più ampio tra le opzioni di hosting LLM self-hosted e cloud — inclusi Ollama, vLLM, Docker Model Runner e provider cloud gestiti — consultare la guida all’hosting LLM per il 2026.

Se si desidera una panoramica lato a lato di LocalAI rispetto a Ollama, vLLM, LM Studio e altri, il confronto degli strumenti principali per LLM locali nel 2026 copre il supporto API, la compatibilità hardware e la prontezza per la produzione. Per il caso più ampio di mantenere i modelli sulla propria infrastruttura, l’auto-hosting di LLM e la sovranità dell’IA tratta la residenza dei dati e le motivazioni di conformità.

Opzioni di installazione di LocalAI che funzionano bene nella pratica

LocalAI può essere installata in vari modi, ma per la maggior parte dei team il punto di partenza più rapido e a rischio minimo è tramite container (Docker o Podman). Se si desidera un riferimento di comandi mentre si seguono gli esempi sottostanti, la scheletro di comandi Docker copre i comandi Docker più frequenti e utili.

Avvio rapido con Docker

Questo avvia il server LocalAI e lega l’API e la Web UI sulla porta 8080:

docker run -p 8080:8080 --name local-ai -ti localai/localai:latest

La documentazione del container di LocalAI definisce questo il percorso più veloce per far partire un server funzionante, con l’API raggiungibile su http://localhost:8080.

Scegliere l’immagine container LocalAI corretta

LocalAI pubblica più varianti di container in modo da poter corrispondere all’hardware:

• Un’immagine CPU per una compatibilità ampia.
• Immagini specifiche per GPU per NVIDIA CUDA, AMD ROCm, Intel oneAPI e Vulkan.
• Immagini All-in-One (AIO) già preconfigurate con modelli mappati su nomi simili a OpenAI.

Il README upstream di GitHub include esempi concreti docker run per opzioni solo CPU e diverse GPU (varianti NVIDIA CUDA, AMD ROCm, Intel, Vulkan), oltre alle varianti AIO.

Persistere i modelli tra i riavvii

Se non si monta un archivio di memorizzazione, i modelli scaricati potrebbero non persistere tra i cambiamenti del ciclo di vita del container. La guida del container raccomanda di montare un volume per i modelli, ad esempio:

docker run -ti --name local-ai -p 8080:8080 \
  -v "$PWD/models:/models" \
  localai/localai:latest-aio-cpu

Questo rende /models all’interno del container persistente sul proprio host.

Un Docker Compose QuickStart minimale

LocalAI fornisce anche un docker-compose.yaml di riferimento nel repository, che dimostra un modello comune: lega la porta 8080, monta un volume /models, imposta MODELS_PATH=/models, e opzionalmente pre-carica un modello specificandolo nella lista dei comandi (l’esempio del repo mostra phi-2). La scheletro di comandi Docker Compose è un riferimento utile mentre si adatta questo alla propria configurazione.

Un setup Compose “buono di default” (CPU) appare così:

services:
  localai:
    image: localai/localai:latest
    container_name: local-ai
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    environment:
      - MODELS_PATH=/models

L’idea chiave è la stessa dell’esempio upstream: directory host dei modelli ↔ /models del container.

Se si utilizza anche la strumentazione nativa docker model di Docker insieme a LocalAI, la scheletro di comandi Docker Model Runner copre i comandi pull, run, package e di configurazione.

Installazioni LocalAI non in container

LocalAI supporta anche installazioni tramite metodi specifici per piattaforma (ad esempio, un DMG per macOS e binari per Linux), e opzioni di distribuzione più ampie come Kubernetes.

Se si preferiscono installazioni scriptate su Linux, il quick start di DeepWiki descrive un percorso install.sh che rileva automaticamente l’hardware e configura il sistema di conseguenza.

Una sequenza di utilizzo prevedibile

Un flusso di lavoro affidabile di LocalAI è:

Avviare LocalAI → installare o importare un modello → verificare i modelli caricati → chiamare gli endpoint compatibili con OpenAI.

Questa sequenza corrisponde alla guida ufficiale “Provalo” e “Configurazione dei modelli”, che inquadra il processo intorno all’avvio del server, all’installazione di modelli tramite galleria o CLI, e poi ai test degli endpoint con curl.

Avviare il server e confermare che sia sano

Una volta che il server è in esecuzione, un controllo di sanità comune è l’endpoint di readiness:

curl http://localhost:8080/readyz

La guida per la risoluzione dei problemi utilizza /readyz come primo diagnostico per confermare che LocalAI sia reattivo.

Installare un modello dalla galleria o importare un URI

LocalAI fornisce due flussi principali di onboarding dei modelli:

• Installazione tramite Model Gallery via Web UI, dove si apre l’UI, si va alla scheda Models, si sfogliano i modelli e si clicca su Install.
• Installazione e avvio guidata da CLI, usando local-ai models list, local-ai models install e local-ai run.

La documentazione supporta anche l’importazione di modelli tramite URI (repository di Hugging Face, URI diretti di file modello e altri registry), e la Web UI include un flusso dedicato Import Model con un editor YAML per configurazioni avanzate.

Verificare cosa LocalAI pensa di poter servire

Per elencare i modelli distribuiti tramite l’API compatibile con OpenAI:

curl http://localhost:8080/v1/models

Questo è esplicitamente raccomandato sia come “prossimo passo” dopo l’installazione del container che come diagnostico di risoluzione dei problemi.

Principali parametri della riga di comando da conoscere

La CLI di LocalAI è costruita attorno al comando local-ai run, con una superficie di configurazione completa. Dobbiamo evidenziare due comportamenti operativi importanti:

• Ogni flag CLI può essere impostato tramite una variabile d’ambiente.
• Le variabili d’ambiente hanno la precedenza sui flag CLI.

Di seguito i parametri che i praticanti tendono a utilizzare presto, raggruppati per intento. Tutti i valori predefiniti e i nomi delle variabili d’ambiente sono tratti dal riferimento CLI upstream. Se si sta valutando Ollama insieme a LocalAI, la scheletro di comandi CLI di Ollama copre i suoi comandi serve, run, ps e di gestione dei modelli per il confronto.

Flag principali per server e archiviazione

La FAQ di LocalAI documenta anche le posizioni predefinite di archiviazione dei modelli e raccomanda esplicitamente LOCALAI_MODELS_PATH o --models-path se si vogliono modelli fuori dalla directory predefinita (ad esempio, per evitare di riempire una directory home).

Flag per prestazioni e capacità

Per una compatibilità più ampia e vincoli di accelerazione, la tabella di compatibilità dei modelli documenta quali backend supportano quali modalità di accelerazione (CUDA, ROCm, SYCL, Vulkan, Metal, CPU), e nota anche che i modelli non configurati esplicitamente potrebbero essere caricati automaticamente, mentre la configurazione YAML permette di fissare il comportamento. Per distribuzioni multi-GPU ad alto throughput con PagedAttention, la guida quickstart di vLLM percorre un server compatibile con OpenAI paragonabile con configurazione orientata alla produzione.

Flag per API, sicurezza e UI

Se si espone LocalAI in remoto, si dovrebbe proteggere gli endpoint e si può limitare l’accesso con una chiave API, la chiave API concede effettivamente l’accesso completo.

Tour della Web UI e come si mappa sul sistema

Di default, LocalAI serve una Web UI integrata insieme all’API (a meno che non venga disabilitata). La documentazione afferma che l’UI è accessibile sullo stesso host e porta del server, tipicamente http://localhost:8080.

Cosa si può fare nella UI integrata

La Web UI è un’interfaccia basata su browser che copre:

• Gestione dei modelli e l’esperienza di navigazione della galleria
• Interazioni di chat
• Interfacce per generazione di immagini e text-to-speech
• Configurazione distribuita e P2P

La struttura delle route fornisce un chiaro modello mentale della superficie dell’UI:

• / per la dashboard
• /browse per il browser della galleria modelli
• /chat/ per la chat
• /text2image/ per la generazione di immagini
• /tts/ per text-to-speech
• /talk/ per l’interazione vocale
• /p2p per le impostazioni e il monitoraggio P2P

Flusso di lavoro della Model Gallery e “Import Model”

Per gli ingegneri, la caratteristica UI più importante è l’onboarding dei modelli. La guida ufficiale “Setting Up Models” descrive:

• Installazione di modelli tramite la scheda Models con installazione in un click.
• Importazione di modelli tramite un’UI Import Model che supporta una modalità semplice (URI + preferenze) e una modalità avanzata con editor YAML e strumenti di convalida.

Questo è importante perché LocalAI esegue infine i modelli basandosi sulla configurazione YAML: è possibile gestire singoli file YAML nella directory dei modelli, utilizzare un singolo file con più definizioni di modello tramite --models-config-file, o fare riferimento a URL YAML remoti all’avvio.

Esempi che puoi incollare in un terminale

Gli endpoint compatibili con OpenAI di LocalAI sono progettati per accettare formati di richiesta familiari e restituire risposte JSON (con endpoint audio che restituiscono payload audio).

Esempio di completamenti di chat con curl

La pagina “Try it out” di LocalAI mostra di chiamare l’endpoint completamenti di chat direttamente:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      { "role": "user", "content": "Scrivi una spiegazione in un paragrafo su cosa è LocalAI." }
    ],
    "temperature": 0.2
  }'

Le immagini AIO consegnano modelli preconfigurati mappati su nomi simili a OpenAI come gpt-4, e la documentazione del container spiega che questi sono supportati da modelli open-source.

Se non si sta utilizzando un’immagine AIO, sostituire "model" con il nome del modello installato (verificare con /v1/models).

Esempio di embedding per pipeline RAG

LocalAI supporta embedding e documenti che l’endpoint embedding è compatibile con diversi backend, tra cui llama.cpp, bert.cpp e sentence-transformers.

Una richiesta minima “embeddi questo testo” contro l’endpoint compatibile con OpenAI appare così:

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-ada-002",
    "input": "Gli embedding di LocalAI sono utili per la ricerca semantica e RAG."
  }'

La documentazione degli embedding di LocalAI mostra anche come gli embedding sono abilitati tramite configurazione YAML impostando embeddings: true.

Esempio di utilizzo di un client compatibile con OpenAI

LocalAI è progettata in modo che tu possa utilizzare librerie client OpenAI standard puntandole all’URL base di LocalAI (e opzionalmente impostando una chiave API se hai abilitato l’autenticazione). Questo obiettivo di “sostituzione plug-and-play” è descritto sia nel README upstream che nella documentazione sulla compatibilità con OpenAI.

Una configurazione tipica è:

• URL base: http://localhost:8080/v1
• Chiave API: non necessaria (default) o richiesta se hai configurato --api-keys

Fondamentali di sicurezza e risoluzione dei problemi

Proteggere un server LocalAI prima di esporlo

LocalAI può essere eseguito completamente aperto su localhost di default. Se ti colleghi a un’interfaccia pubblica o lo esponi tramite un ingress, aggiungi almeno uno di questi controlli:

• Abilita l’autenticazione con chiave API usando --api-keys / API_KEY.
• Metti un reverse proxy e controlli di rete davanti ad esso (firewall, whitelist, VPN).
• Disabilita la Web UI se ti serve solo l’API (--disable-webui).
• Mantieni CORS disabilitato a meno che un client basato su browser ne abbia davvero bisogno.

Quando le chiavi API sono abilitate, gli endpoint compatibili con OpenAI accettano credenziali in luoghi comuni come un header Bearer Authorization o header x-api-key.

Diagnostica rapida quando qualcosa non funziona

La guida per la risoluzione dei problemi di LocalAI suggerisce un piccolo insieme di controlli che risolvono la maggior parte degli incidenti “è in esecuzione”:

# readiness
curl http://localhost:8080/readyz

# lista modelli
curl http://localhost:8080/v1/models

# versione
local-ai --version

Documenta anche l’abbinamento del log di debug tramite DEBUG=true o --log-level=debug, e per i deployment Docker, controllare i log del container con docker logs local-ai.