Início Rápido do LocalAI: Execute LLMs Compatíveis com OpenAI Localmente

O LocalAI é um servidor de inferência de auto-hospedagem, com prioridade local, projetado para funcionar como uma API OpenAI plug-and-play 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 para “substituir a URL da API na nuvem”, suportando múltiplos backends e modalidades (texto, imagens, áudio, embeddings e mais).

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

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

Para além da geração básica de texto, o conjunto de funcionalidades 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 GPU opcional e padrões distribuídos.

Se estiver a avaliar a servir LLMs com auto-hospedagem, o LocalAI é interessante porque foca na compatibilidade da API (para facilitar a integração), fornecendo também uma interface Web integrada e um fluxo de trabalho de galeria de modelos para reduzir a fricção na instalação e configuração de modelos.

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

Se deseja uma análise lado a lado do LocalAI contra o Ollama, vLLM, LM Studio e outros, a página comparando as principais ferramentas locais de LLM em 2026 cobre suporte de API, compatibilidade de hardware e prontidão para produção. Para o caso mais amplo de manter os modelos na sua própria infraestrutura, a página auto-hospedagem de LLM e soberania da IA aborda as 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 formas, mas para a maioria das equipas, o ponto de partida mais rápido e com menor risco é através de contentores (Docker ou Podman). Se precisar de uma referência de comandos enquanto trabalha nos exemplos abaixo, a folha de dicas do Docker cobre os comandos Docker mais frequentes e úteis.

Início mais rápido com Docker

Isto inicia o servidor LocalAI e liga 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 contentor do LocalAI define isto como o caminho mais rápido para colocar um servidor funcional em funcionamento, com a API acessível em http://localhost:8080.

Escolher a imagem de contentor LocalAI certa

O LocalAI publica vários sabores de contentor para que possa adaptar-se ao seu hardware:

• Uma imagem de CPU para ampla compatibilidade.
• Imagens específicas de 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 modelos semelhantes à OpenAI.

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

Persistir modelos entre reinícios

Se não montar armazenamento, os modelos descarregados podem não persistir através de alterações no ciclo de vida do contentor. O guia do contentor 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

Isto torna /models dentro do contentor persistente no seu hospedeiro.

Um QuickStart mínimo com Docker Compose

O LocalAI também fornece um docker-compose.yaml de referência no repositório, demonstrando um padrão comum: ligar 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 repositório mostra phi-2). A folha de dicas do Docker Compose é uma referência útil ao adaptar isto à sua configuração.

Uma configuração Compose “padrão boa” (CPU) é assim:

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

A ideia principal é a mesma do exemplo upstream: diretório de modelos do hospedeiro ↔ contentor /models.

Se também estiver a utilizar a ferramenta nativa docker model do Docker juntamente com o LocalAI, a folha de dicas do Docker Model Runner cobre comandos de pull, run, package e configuração.

Instalações do LocalAI sem contentores

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

Se preferir instalações scriptadas no Linux, a introdução rápida do DeepWiki descreve um caminho install.sh que deteta automaticamente o hardware e configura o sistema em conformidade.

Uma sequência de utilização previsível

Um fluxo de trabalho LocalAI fiável é:

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

Esta sequência corresponde à orientação oficial de “Experimentar” e “Configurar modelos”, que estrutura o processo em torno de iniciar o servidor, instalar modelos via galeria ou CLI, e testar depois os 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 resolução de problemas utiliza /readyz como primeiro diagnóstico para confirmar que o LocalAI está a responder.

Instalar um modelo da galeria ou importar um URI

O LocalAI fornece dois fluxos principais de onboarding de modelos:

• Instalação da Galeria de Modelos via interface Web, onde abre a UI, vai à aba Models, navega pelos modelos e clica em Install.
• Instalação e execução via CLI, utilizando 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 de ficheiros de modelos diretos e outros registos), e a interface Web inclui um fluxo dedicado de Importar Modelo com um editor YAML para configuração avançada.

Verificar o que o LocalAI pensa que pode servir

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

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

Isto é explicitamente recomendado tanto como “próximo passo” após a instalação do contentor como diagnóstico de resolução de problemas.

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

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

• Todo o sinalizador CLI pode ser definido via variável de ambiente.
• Variáveis de ambiente têm precedência sobre sinalizadores CLI.

Abaixo estão os parâmetros que a maioria dos praticantes acaba por utilizar cedo, agrupados por intenção. Todos os valores padrão e nomes de variáveis de ambiente são extraídos da referência CLI upstream. Se estiver a avaliar o Ollama juntamente com o LocalAI, a folha de dicas da CLI Ollama cobre os seus comandos serve, run, ps e gestão de modelos para comparação.

Sinalizadores de servidor e armazenamento principais

A FAQ do LocalAI também documenta as localizações padrão de armazenamento de modelos e recomenda explicitamente LOCALAI_MODELS_PATH ou --models-path se quiser modelos fora do diretório padrão (por exemplo, para evitar encher um diretório home).

Sinalizadores 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 implementações multi-GPU de maior throughput com PagedAttention, o guia de início rápido vLLM percorre um servidor compatível com OpenAI comparável com configuração orientada à produção.

Sinalizadores de API, segurança e UI

Se expuser o LocalAI remotamente, deve proteger os endpoints e pode controlar o acesso com uma chave API; a chave API concede efetivamente acesso total.

Tour da interface Web e como mapeia para o sistema

Por defeito, o LocalAI serve uma interface Web integrada juntamente com a API (a menos que a desative). A documentação indica que a UI é acessível no mesmo hospedeiro e porta que o servidor, tipicamente http://localhost:8080.

O que pode fazer na interface integrada

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

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

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

• / para o painel de controlo
• /browse para o navegador da galeria de modelos
• /chat/ para chat
• /text2image/ para geração de imagens
• /tts/ para texto para fala
• /talk/ para interação de voz
• /p2p para definições e monitorização P2P

Galeria de Modelos e fluxo de trabalho “Importar Modelo”

Para engenheiros, a funcionalidade de UI mais importante é o onboarding de modelos. O guia oficial “Configurar Modelos” descreve:

• Instalar modelos via a aba Models com instalação de um clique.
• Importar modelos via uma UI de Importar Modelo que suporta um modo simples (URI + preferências) e um modo avançado com editor YAML e ferramentas de validação.

Isto é importante porque o LocalAI executa modelos baseados em configuração YAML: pode gerir ficheiros YAML individuais no diretório de modelos, usar um único ficheiro com múltiplas definições de modelos via --models-config-file, ou referenciar URLs YAML remotas no arranque.

Exemplos que pode colar num terminal

Os endpoints compatíveis com OpenAI do LocalAI são projetados para aceitar formatos de pedido familiares e devolver respostas JSON (com endpoints de áudio a devolver cargas de áudio).

Exemplo de conclusões de chat com curl

A página “Experimentar” do LocalAI mostra como chamar diretamente ao endpoint de conclusões de chat:

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

As imagens AIO são enviadas com modelos pré-configurados mapeados para nomes semelhantes à OpenAI, como gpt-4, e a documentação do contentor explica que estes são suportados por modelos de código aberto.

Se não estiver a utilizar 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 documenta que o endpoint de embeddings é compatível com vários backends, incluindo llama.cpp, bert.cpp e sentence-transformers.

Um pedido mínimo de “inserir este texto” contra o endpoint compatível com OpenAI é assim:

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

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

Exemplo usando um cliente compatível com OpenAI

O LocalAI é projetado para que possa utilizar bibliotecas de cliente OpenAI padrão apontando-as para a URL base do LocalAI (e opcionalmente definindo uma chave API se ativou a autenticação). Este objetivo de “substituição plug-and-play” é descrito tanto no README upstream como na documentação de compatibilidade OpenAI.

Uma configuração típica é:

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

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

Segurar um servidor LocalAI antes de expô-lo

O LocalAI pode executar totalmente aberto em localhost por defeito. Se ligar a uma interface pública ou expor através de um ingress, adicione pelo menos um destes controlos:

• Ativar autenticação por chave API usando --api-keys / API_KEY.
• Colocar um proxy reverso e controlos de rede à frente (firewall, lista de permissões, VPN).
• Desativar a interface Web se precisar apenas da API (--disable-webui).
• Manter o CORS desativado a menos que um cliente baseado em navegador genuinamente precise disto.

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

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

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

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

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

# versão
local-ai --version

Também documenta a ativação de registo de depuração via DEBUG=true ou --log-level=debug, e para implementações Docker, verificar registos de contentor com docker logs local-ai.