LocalAI: a API completa da OpenAI, 100% auto-hospedada

#Por que usar LocalAI

LocalAI (o projeto mudler/LocalAI no GitHub, sob licença MIT, criado e mantido por Ettore Di Giacinto e a equipe LocalAI) se apresenta como um "substituto direto" da API OpenAI. Concretamente, suas requisições para /v1/chat/completions, /v1/embeddings, /v1/audio/transcriptions, /v1/audio/speech ou /v1/images/generations são direcionadas para um servidor que você hospeda, em vez dos servidores da OpenAI. Nenhum token sai da sua rede, nenhuma cobrança por uso, nenhuma cota.

O verdadeiro interesse do LocalAI não é rodar mais um chat: é unificar várias modalidades por trás de um único endpoint compatível. Uma mesma instância disponibiliza um LLM para texto, um modelo de embeddings para o seu RAG, Whisper para transcrição, Stable Diffusion para imagens e, agora, modelos de vídeo. Para uma aplicação que precisa de várias peças, isso evita montar e manter três ou quatro servidores separados, cada um com sua própria API para aprender.

API compatível com OpenAI

Mesmos caminhos, mesmos payloads JSON. Seus SDKs oficiais (openai-python, openai-node) funcionam apenas alterando a URL base.

Multi-backend

LocalAI depende de llama.cpp (GGUF), whisper.cpp, diffusers, piper e outros, conforme o modelo. Você não precisa instalá-los um a um.

Multimodal

Texto, embeddings, áudio (STT + TTS) e imagens na mesma instância, cada um em sua própria rota OpenAI.

100 % local

Funciona offline após os modelos serem baixados. Sem telemetria de inferência, sem dependência de nuvem.

O projeto se expandiu significativamente ao longo das versões desde sua descrição inicial como um simples clone da API da OpenAI. Sua compatibilidade 'drop-in' agora também abrange as APIs da Anthropic e da ElevenLabs, em cada um de seus backends. Mais de 60 backends são compatíveis — llama.cpp, vLLM, SGLang, transformers, whisper.cpp, diffusers, MLX e MLX-VLM para Apple Silicon, entre outros — e podem ser instalados sob demanda a partir de uma galeria de backends, sem que seja necessário incluir todos antecipadamente em uma única imagem.

O LocalAI também integra agentes de IA autônomos com uso de ferramentas, RAG e suporte ao protocolo MCP, além de um modo multiusuário com autenticação por chave de API, cotas e controle de acesso por função. A versão 4.1.0 (abril de 2026) adicionou um modo de cluster distribuído com roteamento inteligente conforme a VRAM disponível e escalonamento automático; a versão 4.2.0 (maio de 2026) adicionou reconhecimento de voz e facial, diarização de falantes, uma API compatível com a do Ollama e geração de vídeo.

#LocalAI ou Ollama, conforme a necessidade

Os dois executam GGUF via llama.cpp e expõem uma API compatível com a OpenAI para texto. A diferença está no escopo e na filosofia. Ollama busca simplicidade para texto (e um pouco de visão) com uma CLI limpa; o LocalAI busca cobertura ampla — várias modalidades, mais backends, mais configurações, agentes integrados — ao custo de uma configuração significativamente mais extensa.

Nada impede que você rode os dois na mesma máquina: Ollama para o chat interativo do dia a dia, LocalAI como gateway multimodal para suas aplicações que precisam de embeddings, áudio ou imagens por trás da mesma API.

#Pré-requisitos

A forma mais organizada de implantar o LocalAI é via Docker, com uma imagem específica para o seu hardware. Reserve memória de acordo com os modelos desejados: é a VRAM (ou a RAM ao usar apenas a CPU) que, no final, determina quais modelos você poderá realmente disponibilizar.

Docker

Docker Engine ou uma versão recente do Docker Desktop. Docker Compose recomendado para uma implantação reproduzível.

GPU (opcional)

NVIDIA com o NVIDIA Container Toolkit para aceleração com CUDA 12 ou 13. O LocalAI também oferece aceleração em AMD (ROCm), Intel (oneAPI/SYCL) e Apple Silicon (Metal), com Vulkan como alternativa genérica quando nenhuma dessas opções se aplica. Sem GPU, tudo roda na CPU, mais lentamente.

VRAM por tamanho (Q4)

3B ≈ 2 GB · 7B ≈ 5 GB · 14B ≈ 9 GB · 32B ≈ 19 GB · 70B ≈ 40 GB. Adicione margem para um modelo de embeddings e/ou Whisper se os servir em paralelo.

Referências de GPU

RTX 3060 12GB (de entrada) ou RTX 4070 12GB acomodam confortavelmente um modelo de 7-14B; RTX 4090 24GB ou um Mac M4 Pro com 24-48 GB de memória unificada para quem busca modelos maiores.

Espaço em disco

Cada modelo pesa vários GB, às vezes mais para imagens ou vídeos. Reserve um volume dedicado para não precisar baixar nada novamente a cada reinício do contêiner.

#Implantar o LocalAI com Docker

1. 01
   Iniciar um contêiner de teste

   O comando mais rápido inicia o LocalAI e expõe a API na porta 8080. Use a imagem « -gpu-nvidia-cuda-12 » (ou « -cuda-13 » com os drivers mais recentes) se você tiver uma placa NVIDIA, ou a imagem padrão para CPU caso contrário.
2. 02
   Verificar se a API responde

   Assim que o contêiner estiver pronto, a rota /v1/models deve retornar a lista (inicialmente vazia) no formato OpenAI. Esse é o sinal de que o servidor está corretamente vinculado à porta 8080.
3. 03
   Persistir os modelos

   Monte um volume em /models (ou /build/models conforme a imagem) para que os modelos baixados permaneçam após o reinício. Sem volume, tudo é baixado novamente a cada “docker run”.
4. 04
   Mudar para Docker Compose

   Para uso a longo prazo, descreva o serviço em um docker-compose.yml: imagem, portas, volume e reserva de GPU. Você reinicia tudo com um '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

#Instalar um modelo a partir da galeria

O LocalAI fornece uma galeria de modelos pré-configurados, acessível também por meio de «local-ai models list» na linha de comando ou em models.localai.io: cada entrada inclui o backend correto, o template de prompt e os parâmetros padrão. Você pode instalar um modelo por seu nome via API, sem precisar escrever YAML manualmente.

# 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

Para controle total, você também pode definir um modelo manualmente em um arquivo YAML colocado no diretório /models. Esse arquivo descreve o nome exposto pela API, o backend e o arquivo de pesos a carregar.

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

#Uma única API para texto, embeddings, áudio e imagens

É aqui que o LocalAI se destaca. Cada modalidade segue sua rota padrão da OpenAI; basta ter instalado o modelo adequado para cada uma. Veja as quatro peças mais úteis.

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

#Migrar uma aplicação OpenAI sem alterar o código

Como as rotas e os payloads são idênticos, migrar uma aplicação se resume a alterar a URL base e substituir os nomes dos modelos. Os SDKs oficiais aceitam uma base_url personalizada: esse é o único parâmetro a alterar, seja a aplicação voltada para a API da OpenAI, da Anthropic ou da 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 base

Substitua o endpoint OpenAI por http://votre-hote:8080/v1. Normalmente apenas uma variável de ambiente OPENAI_BASE_URL.

Nomes dos modelos

« gpt-4o » → o nome do seu modelo local. É o principal ajuste a fazer no código ou na configuração.

Chave de API

Opcional localmente; insira qualquer valor se o SDK o exigir, ou configure uma chave real no LocalAI.

Diferenças de comportamento

Um modelo local de 7B não pensa como o GPT-4. Ajuste seus prompts e expectativas, em vez de assumir uma paridade de qualidade.

#Solução de problemas

O container inicia lentamente na primeira execução

As imagens do LocalAI e o primeiro download de modelo são volumosos. Isso é normal; as inicializações seguintes são rápidas se o volume /models for persistente.

« model not found »

O campo 'model' da requisição deve corresponder exatamente ao 'name' da galeria ou do YAML. Verifique com 'curl /v1/models'.

Sem aceleração por GPU

Certifique-se de usar uma imagem « -gpu-nvidia-cuda-12 » (ou « -cuda-13 »), instale o NVIDIA Container Toolkit e passe « --gpus all ». Ative DEBUG=true para ver o backend realmente selecionado.

Respostas lentas ou OOM

O modelo excede a capacidade da sua VRAM e passa a usar CPU/RAM para a parte que não cabe nela. Reduza um nível (Q4_K_M em vez de Q8_0, ou um modelo menor) ou reduza context_size.

Uma modalidade não responde

Cada rota exige seu modelo: sem modelo de embeddings instalado, não há embeddings; sem modelo Whisper, não há /audio. Instale a peça faltante na galeria.

#Para se aprofundar

O LocalAI é apenas um dos servidores de inferência para modelos de pesos abertos disponíveis. Para escolher de forma informada, compare-o com o llama-server (o servidor HTTP do llama.cpp) e com a abordagem do Ollama, e refine o equilíbrio entre memória e qualidade dos seus modelos com o guia sobre quantização. Em seguida, conecte uma interface ou um aplicativo a ele por meio do seu endpoint OpenAI.

• llama-server: uma API OpenAI local com llama.cpp
• Ollama vs llama.cpp: qual escolher?
• Escolher sua quantização (Q4, Q5, Q8, FP16)
• RAG local sem codar: Open WebUI, AnythingLLM
• Fonte: repositório GitHub do LocalAI
• Fonte: documentação oficial do LocalAI
• Fonte: galeria de backends LocalAI

#FAQ