LocalAI QuickStart : Exécuter des LLM compatibles OpenAI localement

LocalAI est un serveur d’inférence auto-hébergé, conçu en priorité pour une utilisation locale, qui se comporte comme une API OpenAI de remplacement pour exécuter des charges de travail d’IA sur votre propre matériel (ordinateur portable, station de travail ou serveur sur site).

Le projet vise une compatibilité pratique de type « remplacement de l’URL de l’API cloud », tout en prenant en charge plusieurs backends et modalités (texte, images, audio, embeddings, et plus encore).

Qu’est-ce que LocalAI et pourquoi les ingénieurs l’utilisent

LocalAI présente une API REST HTTP qui mimenote les points de terminaison clés d’OpenAI, notamment les complétions de chat, les embeddings, la génération d’images et les points de terminaison audio, de sorte que les outils compatibles OpenAI existants peuvent être redirigés vers votre propre infrastructure.

Au-delà de la simple génération de texte, l’ensemble de fonctionnalités de LocalAI couvre des « blocs de construction de production » courants tels que les embeddings pour la RAG, la génération d’images par diffusion, la reconnaissance vocale (speech-to-text) et la synthèse vocale (text-to-speech), avec une accélération GPU optionnelle et des modèles de distribution.

Si vous évaluez le service de modèles de langage (LLM) auto-hébergé, LocalAI est intéressant car il se concentre sur la compatibilité de l’API (pour une intégration plus facile) tout en fournissant une interface Web intégrée et un flux de travail de galerie de modèles pour réduire la friction liée à l’installation et à la configuration des modèles.

Pour une comparaison plus large des options d’hébergement de LLM auto-hébergés et dans le cloud — notamment Ollama, vLLM, Docker Model Runner et les fournisseurs de cloud gérés — consultez le guide d’hébergement de LLM pour 2026.

Si vous souhaitez une analyse comparative côte à côte de LocalAI par rapport à Ollama, vLLM, LM Studio et d’autres, l’article comparant les principaux outils LLM locaux en 2026 couvre le support API, la compatibilité matérielle et la maturité pour la production. Pour l’argumentation plus large concernant le maintien des modèles sur votre propre infrastructure, l’article Auto-hébergement de LLM et souveraineté de l’IA aborde la résidence des données et les motivations liées à la conformité.

Options d’installation de LocalAI qui fonctionnent bien en pratique

LocalAI peut être installé de plusieurs manières, mais pour la plupart des équipes, le point de départ le plus rapide et à moindre risque est l’utilisation de conteneurs (Docker ou Podman). Si vous souhaitez une référence de commandes tout en parcourant les exemples ci-dessous, la feuille de triches Docker couvre les commandes Docker les plus fréquentes et utiles.

Démarrage rapide avec Docker

Ceci démarre le serveur LocalAI et lie l’API et l’interface Web sur le port 8080 :

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

La documentation du conteneur LocalAI appelle cela le chemin le plus rapide pour mettre en place un serveur fonctionnel, avec l’API accessible sur http://localhost:8080.

Choisir la bonne image de conteneur LocalAI

LocalAI publie plusieurs variantes de conteneurs afin que vous puissiez correspondre à votre matériel :

• Une image CPU pour une large compatibilité.
• Des images spécifiques au GPU pour NVIDIA CUDA, AMD ROCm, Intel oneAPI et Vulkan.
• Des images Tout-en-un (AIO) qui sont préconfigurées avec des modèles mappés sur des noms de modèles ressemblant à OpenAI.

Le README GitHub en amont inclut des exemples concrets docker run pour les options uniquement CPU et plusieurs options GPU (variants NVIDIA CUDA, AMD ROCm, Intel, Vulkan), ainsi que des variantes AIO.

Persistance des modèles entre les redémarrages

Si vous ne montez pas de stockage, vos modèles téléchargés peuvent ne pas persister à travers les changements de cycle de vie du conteneur. Le guide de conteneur recommande de monter un volume de modèles, par exemple :

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

Cela rend le répertoire /models à l’intérieur du conteneur persistant sur votre hôte.

Un QuickStart minimaliste avec Docker Compose

LocalAI fournit également un docker-compose.yaml de référence dans le dépôt, démontrant un modèle courant : lier le port 8080, monter un volume /models, définir MODELS_PATH=/models, et précharger éventuellement un modèle en le spécifiant dans la liste des commandes (l’exemple du dépôt montre phi-2). La feuille de triches Docker Compose est une référence pratique lors de l’adaptation de ceci à votre configuration.

Une configuration Compose « bonne par défaut » (CPU) ressemble à ceci :

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

L’idée clé est la même que l’exemple en amont : répertoire de modèles hôte ↔ conteneur /models.

Si vous utilisez également les outils natifs docker model de Docker aux côtés de LocalAI, la feuille de triches Docker Model Runner couvre les commandes pull, run, package et de configuration.

Installations LocalAI non conteneurisées

LocalAI prend également en charge les installations via des méthodes spécifiques à la plate-forme (par exemple, un DMG macOS et des binaires Linux), et des options de déploiement plus larges comme Kubernetes.

Si vous préférez des installations scriptées sous Linux, le guide de démarrage rapide de DeepWiki décrit un chemin install.sh qui détecte automatiquement le matériel et configure le système en conséquence.

Une séquence d’utilisation prévisible

Un flux de travail fiable pour LocalAI est :

Démarrer LocalAI → installer ou importer un modèle → vérifier les modèles chargés → appeler les points de terminaison compatibles OpenAI.

Cette séquence correspond aux directives officielles « Essayer » et « Mise en place des modèles », qui encadrent le processus autour du démarrage du serveur, de l’installation de modèles via la galerie ou la CLI, puis des tests des points de terminaison avec curl.

Démarrer le serveur et confirmer qu’il est en bonne santé

Une fois le serveur en marche, un contrôle de base courant est le point de terminaison de disponibilité :

curl http://localhost:8080/readyz

Le guide de dépannage utilise /readyz comme premier diagnostic pour confirmer que LocalAI est réactif.

Installer un modèle depuis la galerie ou importer une URI

LocalAI propose deux flux principaux d’adoption de modèles :

• Installation via la galerie de modèles par l’interface Web, où vous ouvrez l’interface, allez à l’onglet Modèles, parcourez les modèles et cliquez sur Installer.
• Installation et exécution pilotée par CLI, en utilisant local-ai models list, local-ai models install et local-ai run.

La documentation prend également en charge l’importation de modèles par URI (répertoires Hugging Face, URI de fichiers de modèles directs et autres registres), et l’interface Web comprend un flux d’importation de modèle dédié avec un éditeur YAML pour une configuration avancée.

Vérifier ce que LocalAI pense pouvoir servir

Pour lister les modèles déployés via l’API compatible OpenAI :

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

Ceci est explicitement recommandé à la fois comme « étape suivante » après l’installation du conteneur et comme diagnostic de dépannage.

Principaux paramètres de ligne de commande à connaître

La CLI de LocalAI est construite autour de la commande local-ai run, avec une surface de configuration complète. Nous devons mettre en évidence deux comportements opérationnels importants :

• Chaque indicateur CLI peut être défini via une variable d’environnement.
• Les variables d’environnement ont la priorité sur les indicateurs CLI.

Ci-dessous, les paramètres que les praticiens utilisent le plus tôt, regroupés par intention. Toutes les valeurs par défaut et les noms de variables d’environnement sont tirés de la référence CLI en amont. Si vous évaluez Ollama aux côtés de LocalAI, la feuille de triches CLI Ollama couvre ses commandes serve, run, ps et de gestion des modèles pour comparaison.

Indicateurs de serveur et de stockage de base

La FAQ de LocalAI documente également les emplacements de stockage des modèles par défaut et recommande explicitement LOCALAI_MODELS_PATH ou --models-path si vous voulez des modèles en dehors du répertoire par défaut (par exemple, pour éviter de remplir un répertoire personnel).

Indicateurs de performance et de capacité

Pour une compatibilité plus large et des contraintes d’accélération, le tableau de compatibilité des modèles documente quels backends prennent en charge quels modes d’accélération (CUDA, ROCm, SYCL, Vulkan, Metal, CPU), et note également que les modèles non configurés explicitement peuvent être chargés automatiquement, tandis que la configuration YAML vous permet de figer le comportement. Pour les déploiements multi-GPU à haut débit avec PagedAttention, le guide de démarrage rapide vLLM parcourt un serveur comparable compatible OpenAI avec une configuration orientée production.

Indicateurs d’API, de sécurité et d’interface

Si vous exposez LocalAI à distance, vous devez protéger les points de terminaison et pouvez restreindre l’accès avec une clé API, la clé API accordant effectivement un accès complet.

Visite de l’interface Web et comment elle se mappera au système

Par défaut, LocalAI sert une interface Web intégrée aux côtés de l’API (sauf si vous la désactivez). La documentation indique que l’interface est accessible sur le même hôte et port que le serveur, généralement http://localhost:8080.

Ce que vous pouvez faire dans l’interface intégrée

L’interface Web est une interface basée sur le navigateur qui couvre :

• Gestion des modèles et l’expérience de navigation de la galerie
• Interactions de chat
• Interfaces de génération d’images et de synthèse vocale
• Configuration distribuée et P2P

La structure des routes donne un modèle mental clair de la surface de l’interface :

• / pour le tableau de bord
• /browse pour le navigateur de la galerie de modèles
• /chat/ pour le chat
• /text2image/ pour la génération d’images
• /tts/ pour la synthèse vocale
• /talk/ pour l’interaction vocale
• /p2p pour les paramètres et la surveillance P2P

Galerie de modèles et flux de travail « Importer un modèle »

Pour les ingénieurs, la fonctionnalité UI la plus importante est l’adoption de modèles. Le guide officiel « Mise en place des modèles » décrit :

• Installer des modèles via l’onglet Modèles avec une installation en un clic.
• Importer des modèles via une interface Importer un modèle qui prend en charge un mode simple (URI + préférences) et un mode avancé avec un éditeur YAML et des outils de validation.

Cela est important car LocalAI exécute finalement des modèles sur la base de configurations YAML : vous pouvez gérer des fichiers YAML individuels dans le répertoire de modèles, utiliser un fichier unique avec plusieurs définitions de modèles via --models-config-file, ou référencer des URL YAML distantes au démarrage.

Exemples que vous pouvez coller dans un terminal

Les points de terminaison compatibles OpenAI de LocalAI sont conçus pour accepter des formats de requête familiers et retourner des réponses JSON (les points de terminaison audio retournant des charges utiles audio).

Exemple de complétions de chat avec curl

La page « Essayer » de LocalAI montre l’appel du point de terminaison de complétions de chat directement :

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      { "role": "user", "content": "Write a one paragraph explanation of what LocalAI is." }
    ],
    "temperature": 0.2
  }'

Les images AIO livrent des modèles préconfigurés mappés sur des noms ressemblant à OpenAI tels que gpt-4, et la documentation du conteneur explique qu’ils sont soutenus par des modèles open-source.

Si vous n’utilisez pas une image AIO, remplacez "model" par le nom du modèle que vous avez installé (vérifiez avec /v1/models).

Exemple d’embeddings pour les pipelines RAG

LocalAI prend en charge les embeddings et la documentation des embeddings indique que le point de terminaison est compatible avec plusieurs backends, notamment llama.cpp, bert.cpp et sentence-transformers.

Une requête minimale « embed this text » contre le point de terminaison compatible OpenAI ressemble à ceci :

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-ada-002",
    "input": "LocalAI embeddings are handy for semantic search and RAG."
  }'

La documentation des embeddings de LocalAI montre également comment les embeddings sont activés via la configuration YAML en définissant embeddings: true.

Exemple d’utilisation d’un client compatible OpenAI

LocalAI est conçu pour que vous puissiez utiliser des bibliothèques de clients OpenAI standard en les pointant vers l’URL de base LocalAI (et éventuellement en définissant une clé API si vous avez activé l’authentification). Cet objectif de « remplacement direct » est décrit à la fois dans le README en amont et dans la documentation de compatibilité OpenAI.

Une configuration typique est :

• URL de base : http://localhost:8080/v1
• Clé API : soit non requise (par défaut) soit requise si vous avez configuré --api-keys

Sécurité et essentiels de dépannage

Sécuriser un serveur LocalAI avant de l’exposer

LocalAI peut s’exécuter entièrement ouvert sur localhost par défaut. Si vous liez à une interface publique ou l’exposez via un ingress, ajoutez au moins un de ces contrôles :

• Activer l’authentification par clé API en utilisant --api-keys / API_KEY.
• Placer un proxy inverse et des contrôles réseau devant lui (pare-feu, autorisation, VPN).
• Désactiver l’interface Web si vous n’avez besoin que de l’API (--disable-webui).
• Garder le CORS désactivé sauf si un client basé sur navigateur en a réellement besoin.

Lorsque les clés API sont activées, les points de terminaison compatibles OpenAI acceptent les identifiants dans des emplacements courants tels qu’un en-tête Bearer Authorization ou un en-tête x-api-key.

Diagnostic rapide lorsque quelque chose ne fonctionne pas

Le guide de dépannage de LocalAI suggère un petit ensemble de vérifications qui résolvent la plupart des incidents « est-ce qu’il tourne » :

# disponibilité
curl http://localhost:8080/readyz

# lister les modèles
curl http://localhost:8080/v1/models

# version
local-ai --version

Il documente également l’activation de la journalisation de débogage via DEBUG=true ou --log-level=debug, et pour les déploiements Docker, vérifier les logs du conteneur avec docker logs local-ai.