Comment héberger LocalAI sur un VPS

Là où Ollama se concentre sur le texte, LocalAI vise la compatibilité large avec l'API OpenAI : il expose /v1/chat/completions, /v1/embeddings, /v1/images/generations et même la transcription audio, sur une seule API. Pour une équipe qui a déjà du code écrit contre le SDK OpenAI, LocalAI est un remplacement quasi transparent : vous changez l'URL de base et la clé, le reste fonctionne. Sur un VPS, vous obtenez cette polyvalence sans dépendance externe ni coût par appel. C'est particulièrement pertinent quand vous avez besoin à la fois de génération de texte, de vecteurs pour du RAG et, ponctuellement, d'images, sans multiplier les fournisseurs et les clés.

LocalAI étant polyvalent, ses besoins dépendent des fonctions activées. Les chiffres ci-dessous sont des minimums mesurés — un VPS plus généreux réduit les temps de réponse, il ne change pas la faisabilité.

Texte seul, CPU, modèle 7B (ex. Mistral-7B-GGUF) : 8 Go de RAM, 4 vCPU, 30 Go de disque. À ce gabarit, un appel /v1/chat/completions prend 5 à 15 secondes selon la quantization (Q4 est le compromis standard). Un modèle 3B tient dans 4 Go de RAM.

Texte + images (7B + Stable Diffusion) : 16 Go de RAM, GPU recommandé, 50 Go de disque. Sans GPU, la génération d'une image prend plusieurs minutes sur un CPU — préférez un VPS GPU pour un usage régulier et l'option SINGLE_ACTIVE_BACKEND=true pour éviter la saturation si vous mixez chat et images sur le même hôte CPU.

Logiciels requis : Docker 24+ et Docker Compose v2 (docker compose sans tiret), un sous-domaine dédié (ex. ia.votre-domaine.com), le port 443 ouvert, une entrée DNS pointant sur l'IP du VPS.

LocalAI supporte plusieurs formats, mais le format GGUF (produit par llama.cpp) est le standard recommandé pour le CPU : il est quantifié (réduit la RAM utilisée), portable et bien supporté par la galerie.

GGUF vs autres formats : les formats GGUF sont les seuls directement chargeables via llama.cpp sans conversion préalable. Les modèles Diffusers (images) et ONNX (embeddings légers) ont leurs propres backends et ne sont pas interchangeables avec les GGUF.

Galerie vs téléchargement manuel : la galerie est l'option la plus simple — elle télécharge le GGUF et génère le YAML de configuration automatiquement. Pour un modèle non référencé (un modèle fine-tuné, un GGUF personnalisé), déposez le fichier dans ./models/ et créez le YAML manuellement :

name: mon-modele
backend: llama
parameters:
  model: mon-modele.Q4_K_M.gguf
context_size: 4096

Lister les modèles chargés :

curl https://ia.votre-domaine.com/v1/models \
  -H 'Authorization: Bearer votre-cle-secrete'

Les modèles dont le YAML est présent dans ./config/ apparaissent dans la liste, même si leur GGUF n'a pas encore été téléchargé — dans ce cas, le premier appel déclenche le téléchargement.

LocalAI étant compatible avec l'API OpenAI, la migration d'une application existante se résume à deux changements : l'URL de base et la clé.

Python (openai SDK) :

import openai

client = openai.OpenAI(
    base_url="https://ia.votre-domaine.com/v1",
    api_key="votre-cle-secrete"
)

response = client.chat.completions.create(
    model="mistral-7b-instruct-v0.2.Q4_K_M",
    messages=[{"role": "user", "content": "Résume ce texte : ..."}]
)
print(response.choices[0].message.content)

Node.js (openai SDK) :

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://ia.votre-domaine.com/v1',
  apiKey: 'votre-cle-secrete'
});

const completion = await client.chat.completions.create({
  model: 'mistral-7b-instruct-v0.2.Q4_K_M',
  messages: [{ role: 'user', content: 'Hello' }]
});
console.log(completion.choices[0].message.content);

curl direct :

curl https://ia.votre-domaine.com/v1/embeddings \
  -H 'Authorization: Bearer votre-cle-secrete' \
  -H 'Content-Type: application/json' \
  -d '{"model": "all-minilm", "input": "Texte à vectoriser"}'

Les bibliothèques LangChain, LlamaIndex et la plupart des frameworks RAG acceptent un paramètre openai_api_base ou base_url — le changement reste identique.

404 model not found ou model not loaded : le nom de modèle passé dans model: ne correspond à aucun manifest YAML dans ./config/. Vérifiez avec GET /v1/models : le nom affiché doit être utilisé tel quel. Si le modèle n'apparaît pas, vérifiez que le YAML est bien dans le dossier monté et redémarrez le conteneur.

Inférence très lente ou killed (OOM) : le modèle dépasse la RAM disponible. Un modèle 7B Q4 nécessite environ 6 Go de RAM libre au moment du chargement. Vérifiez avec docker stats localai pendant une inférence. Solutions : passer à une quantization plus légère (Q3_K_S ou Q2_K), réduire le context_size dans le YAML, ou upgrader le VPS.

SINGLE_ACTIVE_BACKEND error : LocalAI est configuré avec SINGLE_ACTIVE_BACKEND=true et une requête tente de charger un second modèle pendant qu'un autre est actif. C'est le comportement attendu sur CPU. Attendez que la première inférence se termine, ou désactivez l'option si votre VPS a suffisamment de RAM pour plusieurs modèles simultanés.

GPU non détecté (CUDA device not found) : vérifiez que vous utilisez l'image latest-gpu-nvidia-cuda-12, que le driver NVIDIA est installé sur l'hôte (nvidia-smi), et que le conteneur a accès au GPU (gpus: all dans docker-compose.yaml sous la clé deploy:). Sans ces trois conditions, LocalAI bascule silencieusement sur le CPU.

401 Unauthorized : la variable API_KEY est définie dans le docker-compose.yaml mais le header Authorization: Bearer <clé> est absent ou incorrect dans l'appel. Tous les endpoints, y compris /v1/models, requièrent le header dès que API_KEY est positionné.