LocalAI QuickStart: Execute LLMs compatíveis com OpenAI localmente

LocalAI é um servidor de inferência auto-hospedado e local-first projetado para se comportar como uma API compatível com OpenAI para executar cargas de trabalho de IA no seu próprio hardware (laptop, estação de trabalho ou servidor local).

O projeto visa uma compatibilidade prática de “substituir a URL da API da nuvem”, enquanto suporta múltiplos backends e modalidades (texto, imagens, áudio, embeddings e muito mais).

O que é o LocalAI e por que os engenheiros o utilizam

O LocalAI apresenta uma API REST HTTP que espelha principais endpoints da OpenAI, incluindo conclusões de chat, embeddings, geração de imagens e endpoints de áudio, permitindo que ferramentas compatíveis com OpenAI existentes sejam reorientadas para a sua própria infraestrutura.

Além da geração básica de texto, o conjunto de recursos do LocalAI abrange “blocos de construção de produção” comuns, como embeddings para RAG, geração de imagens baseada em difusão, conversão de fala em texto e texto em fala, com aceleração de GPU opcional e padrões distribuídos.

Se você estiver avaliando servidores LLM auto-hospedados, o LocalAI é interessante porque foca na compatibilidade de API (para facilitar a integração) e também fornece uma interface web integrada e um fluxo de trabalho de galeria de modelos para reduzir o atrito na instalação e configuração de modelos.

Para uma comparação mais ampla de opções de hospedagem de LLM auto-hospedadas e na nuvem — incluindo Ollama, vLLM, Docker Model Runner e provedores de nuvem gerenciados — consulte o guia de hospedagem de LLM para 2026.

Se deseja uma análise lado a lado do LocalAI em comparação com Ollama, vLLM, LM Studio e outros, comparando as principais ferramentas de LLM locais em 2026 cobre suporte de API, compatibilidade de hardware e prontidão para produção. Para o caso mais amplo de manter modelos na sua própria infraestrutura, auto-hospedagem de LLM e soberania de IA cobre motivações de residência de dados e conformidade.

Opções de instalação do LocalAI que funcionam bem na prática

O LocalAI pode ser instalado de várias maneiras, mas para a maioria das equipes, o ponto de partida mais rápido e de menor risco são os contêineres (Docker ou Podman). Se desejar uma referência de comandos enquanto trabalha com os exemplos abaixo, o guia de comandos do Docker cobre os comandos Docker mais frequentes e úteis.

Início mais rápido com Docker

Isso inicia o servidor LocalAI e vincula a API e a interface Web na porta 8080:

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

A documentação do contêiner do LocalAI chama isso de o caminho mais rápido para levantar um servidor funcional, com a API acessível em http://localhost:8080.

Escolhendo a imagem de contêiner LocalAI correta

O LocalAI publica múltiplos sabores de contêiner para que você possa corresponder ao seu hardware:

• Uma imagem de CPU para ampla compatibilidade.
• Imagens específicas para GPU para NVIDIA CUDA, AMD ROCm, Intel oneAPI e Vulkan.
• Imagens All-in-One (AIO) que vêm pré-configuradas com modelos mapeados para nomes de modelo semelhantes aos da OpenAI.

O README upstream do GitHub inclui exemplos concretos de docker run para CPU-only e várias opções de GPU (variantes NVIDIA CUDA, AMD ROCm, Intel, Vulkan), além de variantes AIO.

Persistir modelos entre reinicializações

Se você não montou armazenamento, seus modelos baixados podem não persistir através de mudanças no ciclo de vida do contêiner. O guia do contêiner recomenda montar um volume de modelos, por exemplo:

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

Isso torna /models dentro do contêiner persistente no seu host.

Um Docker Compose QuickStart minimalista

O LocalAI também fornece um docker-compose.yaml de referência no repositório, demonstrando um padrão comum: vincular a porta 8080, montar um volume /models, definir MODELS_PATH=/models, e opcionalmente pré-carregar um modelo especificando-o na lista de comandos (o exemplo do repo mostra phi-2). O guia de comandos do Docker Compose é uma referência útil ao adaptar isso à sua configuração.

Uma configuração Compose de “bom padrão” (CPU) se parece com isto:

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

A ideia chave é a mesma do exemplo upstream: diretório de modelos host ↔ contêiner /models.

Se você também estiver usando a ferramenta nativa docker model do Docker junto com o LocalAI, a folha de truques do Docker Model Runner cobre comandos de pull, run, package e configuração.

Instalações do LocalAI não baseadas em contêiner

O LocalAI também suporta instalações via métodos específicos da plataforma (por exemplo, um DMG do macOS e binários Linux), e opções de implantação mais amplas como Kubernetes.

Se você preferir instalações baseadas em scripts no Linux, o quick start do DeepWiki descreve um caminho install.sh que detecta automaticamente o hardware e configura o sistema de acordo.

Uma sequência de uso previsível

Um fluxo de trabalho confiável do LocalAI é:

Iniciar o LocalAI → instalar ou importar um modelo → verificar modelos carregados → chamar endpoints compatíveis com OpenAI.

Esta sequência corresponde às orientações oficiais de “Tentar agora” e “Configurando modelos”, que estruturam o processo em torno do início do servidor, instalação de modelos via galeria ou CLI e, em seguida, testar endpoints com curl.

Iniciar o servidor e confirmar que está saudável

Uma vez que o servidor esteja em execução, uma verificação de sanidade comum é o endpoint de prontidão:

curl http://localhost:8080/readyz

O guia de solução de problemas usa /readyz como primeiro diagnóstico para confirmar que o LocalAI está responsivo.

Instalar um modelo da galeria ou importar uma URI

O LocalAI fornece dois fluxos principais de onboarding de modelos:

• Instalação na Galeria de Modelos via interface Web, onde você abre a UI, vai para a aba Models, navega pelos modelos e clica em Install.
• Instalação e execução orientada por CLI, usando local-ai models list, local-ai models install e local-ai run.

A documentação também suporta a importação de modelos por URI (repositórios Hugging Face, URIs diretos de arquivos de modelo e outros registries), e a interface Web inclui um fluxo dedicado de Import Model com um editor YAML para configuração avançada.

Verificar o que o LocalAI acha que pode servir

Para listar modelos implantados através da API compatível com OpenAI:

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

Isso é explicitamente recomendado tanto como “próximo passo” após a instalação do contêiner quanto como diagnóstico de solução de problemas.

Principais parâmetros de linha de comando que valem a pena conhecer

A CLI do LocalAI é construída em torno do comando local-ai run, com uma superfície de configuração abrangente. Precisamos destacar dois comportamentos operacionais importantes:

• Cada flag da CLI pode ser definida via variável de ambiente.
• Variáveis de ambiente têm precedência sobre flags de CLI.

Abaixo estão os parâmetros que os profissionais acabam usando cedo, agrupados por intenção. Todos os padrões e nomes de variáveis de ambiente são tirados da referência CLI upstream. Se você estiver avaliando Ollama junto com o LocalAI, a folha de truques da CLI do Ollama cobre seus comandos serve, run, ps e gerenciamento de modelos para comparação.

Flags de servidor e armazenamento principais

A FAQ do LocalAI também documenta locais de armazenamento de modelo padrão e recomenda explicitamente LOCALAI_MODELS_PATH ou --models-path se você deseja modelos fora do diretório padrão (por exemplo, para evitar encher um diretório home).

Flags de desempenho e capacidade

Para compatibilidade mais ampla e restrições de aceleração, a tabela de compatibilidade de modelos documenta quais backends suportam quais modos de aceleração (CUDA, ROCm, SYCL, Vulkan, Metal, CPU), e também nota que modelos não configurados explicitamente podem ser carregados automaticamente, enquanto a configuração YAML permite fixar o comportamento. Para implantações multi-GPU de alto throughput com PagedAttention, o guia de quickstart do vLLM percorre um servidor compatível com OpenAI comparável com configuração orientada para produção.

Flags de API, segurança e UI

Se você expõe o LocalAI remotamente, deve proteger os endpoints e pode restringir o acesso com uma chave de API, a chave de API concede efetivamente acesso total.

Tour na interface Web e como ela mapeia para o sistema

Por padrão, o LocalAI serve uma interface Web integrada junto com a API (a menos que você a desative). A documentação afirma que a UI é acessível no mesmo host e porta do servidor, tipicamente http://localhost:8080.

O que você pode fazer na interface integrada

A interface Web é uma interface baseada em navegador que cobre:

• Gerenciamento de modelos e experiência de navegação da galeria
• Interações de chat
• Interfaces de geração de imagem e texto para fala
• Configuração distribuída e P2P

A estrutura de rotas oferece um modelo mental claro da área de superfície da UI:

• / para o dashboard
• /browse para o navegador da galeria de modelos
• /chat/ para chat
• /text2image/ para geração de imagem
• /tts/ para texto para fala
• /talk/ para interação de voz
• /p2p para configurações e monitoramento P2P

Fluxo de Galeria de Modelos e “Importar Modelo”

Para engenheiros, o recurso mais importante da UI é o onboarding de modelos. O guia oficial “Configurando Modelos” descreve:

• Instalar modelos através da aba Models com instalação de um clique.
• Importar modelos através de uma UI Import Model que suporta um modo simples (URI + preferências) e um modo avançado com um editor YAML e ferramentas de validação.

Isso é importante porque o LocalAI executa modelos baseado em configuração YAML: você pode gerenciar arquivos YAML individuais no diretório de modelos, usar um único arquivo com múltiplas definições de modelo via --models-config-file, ou referenciar URLs de YAML remoto na inicialização.

Exemplos que você pode colar em um terminal

Os endpoints compatíveis com OpenAI do LocalAI são projetados para aceitar formatos de requisição familiares e retornar respostas JSON (com endpoints de áudio retornando payloads de áudio).

Exemplo de conclusões de chat com curl

A página “Try it out” do LocalAI mostra chamar o endpoint de conclusões de chat diretamente:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      { "role": "user", "content": "Escreva uma explicação de um parágrafo sobre o que é o LocalAI." }
    ],
    "temperature": 0.2
  }'

Imagens AIO vêm com modelos pré-configurados mapeados para nomes semelhantes aos da OpenAI como gpt-4, e a documentação do contêiner explica que estes são suportados por modelos de código aberto.

Se você não estiver usando uma imagem AIO, substitua "model" pelo nome do modelo que instalou (verifique com /v1/models).

Exemplo de embeddings para pipelines RAG

O LocalAI suporta embeddings e documentos que o endpoint de embeddings é compatível com vários backends, incluindo llama.cpp, bert.cpp e sentence-transformers.

Uma requisição mínima “incorporar este texto” contra o endpoint compatível com OpenAI se parece com isto:

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-ada-002",
    "input": "Embeddings do LocalAI são úteis para busca semântica e RAG."
  }'

A documentação de embeddings do LocalAI também mostra como os embeddings são habilitados via configuração YAML definindo embeddings: true.

Exemplo usando um cliente compatível com OpenAI

O LocalAI é projetado para que você possa usar bibliotecas de cliente OpenAI padrão apontando-as para a URL base do LocalAI (e opcionalmente definindo uma chave de API se você habilitou autenticação). Este objetivo de “substituição direta” é descrito tanto no README upstream quanto na documentação de compatibilidade com OpenAI.

Uma configuração típica é:

• URL Base: http://localhost:8080/v1
• Chave de API: ou não necessária (padrão) ou necessária se você configurou --api-keys

Essenciais de segurança e solução de problemas

Proteger um servidor LocalAI antes de expô-lo

O LocalAI pode ser executado totalmente aberto no localhost por padrão. Se você vincular a uma interface pública ou expô-lo através de um ingress, adicione pelo menos um destes controles:

• Habilitar autenticação de chave de API usando --api-keys / API_KEY.
• Colocar um proxy reverso e controles de rede na frente dele (firewall, allowlisting, VPN).
• Desativar a interface Web se você precisar apenas da API (--disable-webui).
• Manter CORS desativado a menos que um cliente baseado em navegador realmente precise dele.

Quando as chaves de API estão habilitadas, os endpoints compatíveis com OpenAI aceitam credenciais em locais comuns como um cabeçalho Bearer Authorization ou cabeçalho x-api-key.

Diagnósticos rápidos quando algo não está funcionando

O guia de solução de problemas do LocalAI sugere um pequeno conjunto de verificações que resolvem a maioria dos incidentes de “está executando”:

# prontidão
curl http://localhost:8080/readyz

# listar modelos
curl http://localhost:8080/v1/models

# versão
local-ai --version

Ele também documenta a habilitação de log de depuração via DEBUG=true ou --log-level=debug, e para implantações Docker, verificar os logs do contêiner com docker logs local-ai.