LocalAI : l'API OpenAI complète, 100 % auto-hébergée

#Pourquoi LocalAI

LocalAI (le projet mudler/LocalAI sur GitHub) se présente comme un « drop-in replacement » de l'API OpenAI. Concrètement, vos requêtes vers /v1/chat/completions, /v1/embeddings, /v1/audio/transcriptions, /v1/audio/speech ou /v1/images/generations partent vers un serveur que vous hébergez, au lieu des serveurs d'OpenAI. Aucun token ne quitte votre réseau, aucune facturation à l'usage, aucun quota.

L'intérêt réel de LocalAI n'est pas de faire tourner un chat de plus : c'est d'unifier plusieurs modalités derrière un seul endpoint compatible. Une même instance sert un LLM pour le texte, un modèle d'embeddings pour votre RAG, Whisper pour la transcription et Stable Diffusion pour les images. Pour une application qui a besoin de plusieurs briques, ça évite d'assembler et de maintenir trois ou quatre serveurs distincts.

API compatible OpenAI

Les mêmes chemins, les mêmes payloads JSON. Vos SDK officiels (openai-python, openai-node) fonctionnent en changeant seulement l'URL de base.

Multi-backend

LocalAI s'appuie sur llama.cpp (GGUF), whisper.cpp, diffusers, piper et d'autres selon le modèle. Vous n'avez pas à les installer un par un.

Multimodal

Texte, embeddings, audio (STT + TTS) et images sur la même instance, chacun sur sa route OpenAI.

100 % local

Fonctionne hors ligne une fois les modèles téléchargés. Pas de télémétrie d'inférence, pas de dépendance cloud.

#LocalAI ou Ollama, selon le besoin

Les deux exécutent des GGUF via llama.cpp et exposent une API compatible OpenAI. La différence est de périmètre et de philosophie. Ollama vise la simplicité pour le texte (et un peu de vision) avec une CLI épurée ; LocalAI vise la couverture large — plusieurs modalités, plus de backends, plus de réglages — au prix d'une configuration plus verbeuse.

Ollama

Idéal si vous voulez surtout du chat texte, une prise en main immédiate (« ollama run ») et un daemon qui écoute sur http://localhost:11434. Écosystème d'interfaces très fourni.

LocalAI

Idéal si vous avez besoin d'audio, d'images ou d'embeddings servis à côté du texte, sur une seule API, ou si vous remplacez une intégration OpenAI multimodale existante.

Config

Ollama masque presque tout ; LocalAI expose des fichiers YAML de modèle (backend, template, paramètres) pour un contrôle fin.

En pratique

Rien n'empêche de faire tourner les deux : Ollama pour le chat interactif, LocalAI comme passerelle multimodale pour vos apps.

#Prérequis

LocalAI se déploie le plus proprement via Docker. Prévoyez de la mémoire selon les modèles visés : c'est la VRAM (ou la RAM en CPU pur) qui dicte ce que vous pourrez servir.

Docker

Docker Engine ou Docker Desktop récent. Docker Compose recommandé pour un déploiement reproductible.

GPU (optionnel)

NVIDIA avec le NVIDIA Container Toolkit pour l'accélération CUDA. LocalAI tourne aussi en CPU, plus lentement.

VRAM par taille (Q4)

3B ≈ 2 Go · 7B ≈ 5 Go · 14B ≈ 9 Go · 32B ≈ 19 Go · 70B ≈ 40 Go. Ajoutez la marge pour un modèle d'embeddings et/ou Whisper si vous les servez en parallèle.

Repères GPU

RTX 3060 12GB (entrée) ou RTX 4070 12GB tiennent un 7-14B confortablement ; RTX 4090 24GB ou un Mac M4 Pro 24-48 Go unifié pour viser plus gros.

Espace disque

Chaque modèle pèse plusieurs Go. Prévoyez un volume dédié pour ne rien re-télécharger à chaque redémarrage du conteneur.

#Déployer LocalAI en Docker

1. 01
   Lancer un conteneur de test

   La commande la plus rapide démarre LocalAI et expose l'API sur le port 8080. Utilisez l'image « -gpu-nvidia-cuda12 » si vous avez une carte NVIDIA, ou l'image CPU par défaut sinon.
2. 02
   Vérifier que l'API répond

   Une fois le conteneur prêt, la route /v1/models doit renvoyer la liste (vide au début) au format OpenAI. C'est le signe que le serveur est bien branché sur le port 8080.
3. 03
   Persister les modèles

   Montez un volume sur /models (ou /build/models selon l'image) pour que les modèles téléchargés survivent au redémarrage. Sans volume, tout est retéléchargé à chaque « docker run ».
4. 04
   Passer à Docker Compose

   Pour un usage durable, décrivez le service dans un docker-compose.yml : image, ports, volume et réservation GPU. Vous relancez tout d'un « 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-cuda12

services:
  localai:
    image: localai/localai:latest-gpu-nvidia-cuda12
    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

#Installer un modèle depuis la galerie

LocalAI fournit une galerie de modèles préconfigurés : chaque entrée embarque le bon backend, le template de prompt et les paramètres par défaut. Vous pouvez installer un modèle par son nom via l'API, sans rédiger de YAML à la main.

# Installe un modèle de la galerie (nom d'exemple)
curl http://localhost:8080/models/apply -H "Content-Type: application/json" -d '{
  "id": "[email protected]"
}'

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

Pour un contrôle total, vous pouvez aussi définir un modèle à la main dans un fichier YAML placé dans le dossier /models. Ce fichier décrit le nom exposé par l'API, le backend et le fichier de poids à charger.

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}}

#Une seule API pour texte, embeddings, audio et images

C'est là que LocalAI se distingue. Chaque modalité passe par sa route OpenAI standard ; il suffit d'avoir installé le modèle adéquat pour chacune. Voici les quatre briques les plus utiles.

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"
}'

#Migrer une app OpenAI sans changer le code

Comme les routes et les payloads sont identiques, migrer une application revient à repointer l'URL de base et à remplacer les noms de modèles. Les SDK officiels acceptent une base_url personnalisée : c'est le seul paramètre à toucher.

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 de base

Remplacez l'endpoint OpenAI par http://votre-hote:8080/v1. Souvent une simple variable d'environnement OPENAI_BASE_URL.

Noms de modèles

« gpt-4o » → le nom de votre modèle local. C'est le principal ajustement à faire dans le code ou la config.

Clé d'API

Facultative en local ; mettez n'importe quelle valeur si le SDK l'exige, ou configurez une vraie clé côté LocalAI.

Écarts de comportement

Un 7B local ne raisonne pas comme GPT-4. Réajustez vos prompts et vos attentes plutôt que de supposer une parité de qualité.

#Dépannage

Le conteneur démarre lentement au premier lancement

Les images LocalAI et le premier téléchargement de modèle sont volumineux. C'est normal ; les lancements suivants sont rapides si le volume /models est persistant.

« model not found »

Le champ « model » de la requête doit correspondre exactement au « name » de la galerie ou du YAML. Vérifiez avec « curl /v1/models ».

Pas d'accélération GPU

Utilisez bien une image « -gpu-nvidia-cuda12 », installez le NVIDIA Container Toolkit et passez « --gpus all ». Activez DEBUG=true pour voir le backend réellement sélectionné.

Réponses lentes ou OOM

Le modèle dépasse votre VRAM et déborde en CPU/RAM. Descendez d'un cran (Q4_K_M plutôt que Q8_0, ou un modèle plus petit) ou réduisez context_size.

Une modalité ne répond pas

Chaque route exige son modèle : pas d'embeddings sans modèle d'embeddings installé, pas de /audio sans modèle Whisper. Installez la brique manquante depuis la galerie.

#Pour aller plus loin

LocalAI n'est qu'un des serveurs d'inférence open-weight du paysage. Pour choisir en connaissance de cause, comparez-le à llama-server (le serveur HTTP de llama.cpp) et à l'approche d'Ollama, et affinez le compromis mémoire/qualité de vos modèles avec le guide sur la quantification. Ensuite, branchez une interface ou une app dessus via son endpoint OpenAI.