Text Generation WebUI (Oobabooga): Guia de Instalação, Carregadores e Uso

text-generation-webui é uma interface web de código aberto e auto-hospedada para executar modelos de linguagem de grande porte localmente. Mantido no GitHub como oobabooga/text-generation-webui, ele é executado em seu navegador no endereço http://localhost:7860, oferece suporte a uma ampla gama de formatos de modelos por meio de back-ends de inferência intercambiáveis e expõe uma API REST compatível com a OpenAI. É a interface gráfica (frontend) mais completa disponível, embora exija uma curva de configuração mais acentuada do que aplicações desktop como LLM local LM Studio ou Jan. LM Studio.

O que é o text-generation-webui (e por que as pessoas o chamam de Oobabooga)

O nome de usuário do projeto no GitHub é oobabooga, que se tornou a forma abreviada usada pela comunidade para designar a própria ferramenta. Ambos os nomes referem-se ao mesmo projeto em github.com/oobabooga/text-generation-webui.

A interface é construída sobre o Gradio e executa-se inteiramente em sua máquina local — nenhum dado deixa seu sistema. Além do chat básico, ela oferece suporte a:

• Três modos de entrada: Chat (modo instrução), Chat (roleplay com cartões de personagens) e Notebook (conclusão bruta)
• Carregamento de LoRAs para pesos adaptadores ajustados finamente sobre um modelo base
• Um sistema de extensões com plugins comunitários para resumo, síntese de fala, legendagem de imagens e muito mais
• Um ponto de extremidade (endpoint) de API compatível com a OpenAI para conectar clientes de terceiros e scripts de automação

Antes de escolher um modelo, use o Calculadora de VRAM para confirmar se sua GPU consegue carregá-lo — os requisitos variam amplamente conforme o tamanho do modelo e o nível de quantização.

Instalando o text-generation-webui

O caminho recomendado em todas as plataformas é o instalador de um clique. Ele cria um ambiente isolado do Conda e instala automaticamente todas as dependências Python. Não instale no Python do sistema, a menos que tenha uma razão específica para fazê-lo.

Windows

1. Clone o repositório ou baixe um arquivo ZIP da versão mais recente na página do GitHub:
   git clone https://github.com/oobabooga/text-generation-webui
2. Clique duas vezes em start_windows.bat na pasta clonada.
3. O script detecta automaticamente o tipo de sua GPU (NVIDIA, AMD ou apenas CPU) e instala as dependências correspondentes — selecione a opção apropriada quando solicitado.
4. Após a conclusão da configuração, o servidor é iniciado automaticamente. Abra http://localhost:7860 em seu navegador.

Nas execuções subsequentes, basta clicar duas vezes novamente em start_windows.bat . O ambiente Conda já está configurado; a inicialização leva apenas alguns segundos.

Linux

1. Clone o repositório e entre no diretório:

   git clone https://github.com/oobabooga/text-generation-webui
   cd text-generation-webui

2. Torne o script executável e execute-o:

   chmod +x start_linux.sh
   ./start_linux.sh

3. Selecione seu tipo de GPU quando solicitado: NVIDIA, AMD, apenas CPU ou Apple Silicon (não aplicável no Linux, mas a opção aparece na tela).
4. Acesse a interface em http://localhost:7860 assim que o servidor estiver em execução.

macOS

1. Clone o repositório e execute o script de inicialização:

   git clone https://github.com/oobabooga/text-generation-webui
   cd text-generation-webui
   ./start_macos.sh

2. Selecione a opção D (Apple Silicon / Metal) ou C (apenas CPU) quando solicitado.
3. O back-end llama.cpp usa Metal para aceleração por GPU em chips da série M — não é necessário CUDA.

Usuários do macOS ficam limitados aos carregadores llama.cpp e Transformers. O ExLlamaV2 requer CUDA e não funciona em chips Apple Silicon.

Carregadores de modelos: qual escolher

O text-generation-webui desacopla o mecanismo de inferência da interface gráfica. Você seleciona um carregador por modelo na guia Modelo . Cada carregador aceita formatos específicos de arquivos e possui diferentes requisitos de hardware.

Padrão prático: Se você baixou um arquivo .gguf (o formato mais comum nas páginas de modelos do Hugging Face), use llama.cpp. Se você possui uma GPU NVIDIA e deseja a máxima velocidade de geração, procure uma variante EXL2 do mesmo modelo e use ExLlamaV2.

Para uma análise detalhada dos modelos que cabem realista e eficientemente em cada GPU, consulte Requisitos de VRAM para grandes modelos de linguagem (LLMs).

Carregando um modelo GGUF passo a passo

1. Copie o arquivo para a pasta text-generation-webui/models/. Arquivos únicos GGUF (por exemplo, mistral-7b-instruct.Q4_K_M.gguf) devem ser colocados diretamente nessa pasta. Arquivos divididos em várias partes devem ser colocados em uma subpasta nomeada.
2. Abra a guia Modelo para http://localhost:7860.
3. Selecione seu arquivo no menu suspenso de modelos (clique no ícone de atualização se ele não aparecer).
4. Defina Carregador para llama.cpp.
5. Defina n-gpu-layers para controlar a descarga (offloading) para a GPU. Insira um número elevado (por exemplo, 999) para transferir o maior número possível de camadas para a VRAM; insira 0 para inferência exclusivamente na CPU.
6. Clique Carregar. Uma mensagem de confirmação aparece na caixa de status assim que o modelo estiver pronto.

Mude para a guia Conversa para iniciar uma conversa ou para a guia Padrão Conclusão de Prompt Modelo de instrução no menu suspenso da guia Parâmetros.

A extensão de API compatível com a OpenAI

A extensão embutida openai expõe endpoints REST que replicam o formato das APIs OpenAI Chat Completions e Completions. Qualquer cliente que aceite uma URL base personalizada — LangChain, Open WebUI, Continue.dev ou até mesmo um script curl — pode se conectar ao seu modelo local sem alterações no código.

Ative-a passando uma flag ao iniciar:

# Linux / macOS
./start_linux.sh --extensions openai

# ou inicie diretamente o server.py dentro do ambiente Conda
python server.py --extensions openai

Alternativamente, ative-a na guia Sessão na interface gráfica e clique em Aplicar flags / Reiniciar.

Por padrão, a API escuta na porta 5000, separadamente da interface Gradio, que opera na porta 7860. Configure seu cliente para acessar:

base_url = "http://localhost:5000/v1"
api_key  = "qualquer_coisa"  # exigido pela maioria dos clientes, mas não validado localmente

Os endpoints suportados incluem /v1/chat/completions, /v1/completions, e /v1/models. A porta pode ser configurada via a flag de inicialização --api-port .

text-generation-webui vs LM Studio vs Jan

As três ferramentas executam modelos localmente, sem dependências em nuvem. Cada uma atende a usuários e casos de uso distintos.

Escolha o text-generation-webui quando você precisar de múltiplos backends de carregamento, desempenho EXL2 em GPUs NVIDIA, carregamento de LoRA, ecossistema de extensões ou acesso à API por meio de scripts para automação e fluxos de desenvolvimento.

Escolha LM Studio ou Jan quando desejar um instalador polido, busca integrada de modelos com downloads de um clique e configuração mínima. Consulte o Guia completo do LM Studio para um passo a passo detalhado dessa opção.

Se você estiver avaliando se a inferência local vale o custo do hardware, o calculadora de ponto de equilíbrio entre hospedagem local e uso de API pode quantificar a relação custo-benefício em comparação com o pagamento pelo acesso à API, conforme seu volume de uso.

Perguntas frequentes

Por que o instalador de um clique demora tanto na primeira execução?

Ele faz o download do Miniconda e constrói, do zero, um ambiente isolado do Python com PyTorch e todas as bibliotecas de carregamento de modelos. Em uma conexão rápida, isso normalmente leva de 5 a 15 minutos. Lançamentos subsequentes ignoram essa etapa e iniciam em poucos segundos.

Posso executar o text-generation-webui sem GPU?

Sim. Selecione a opção somente para CPU durante a instalação e defina n-gpu-layers para 0 ao carregar um modelo GGUF. Um modelo de 7B pode gerar de 2 a 5 tokens por segundo em uma CPU moderna de desktop — suficiente para testes, mas lento para conversações. Quantizações menores (Q4 e inferiores) melhoram o rendimento. Consulte o melhores GPUs para LLMs locais se estiver considerando uma atualização de hardware.

Como atualizo o text-generation-webui?

Executar git pull dentro do diretório do repositório para obter o código mais recente e, em seguida, execute novamente o script de inicialização. O script detecta alterações no ambiente e atualiza automaticamente as dependências. Você também pode executar pip install -r requirements.txt manualmente dentro do ambiente ativo do Conda, caso prefira uma atualização direcionada.

Qual é a diferença entre GGUF e EXL2?

Ambos são formatos quantizados que reduzem o tamanho dos arquivos de modelo e os requisitos de VRAM. O GGUF (por meio do llama.cpp) roda em GPUs NVIDIA, AMD e Apple Silicon — trata-se da opção mais portátil e com maior disponibilidade de modelos. O EXL2 (por meio do ExLlamaV2) funciona apenas em GPUs NVIDIA, mas normalmente gera tokens mais rapidamente com qualidade equivalente. Se você possui uma GPU NVIDIA e prioriza velocidade, vale a pena procurar modelos no formato EXL2.

Onde são salvos os registros das conversas?

Os registros são armazenados em text-generation-webui/logs/. Cada conversa é salva como um arquivo JSON. Você também pode exportá-la diretamente pela interface da guia Chat, usando o botão de download abaixo da janela de conversação.

Vários usuários podem se conectar a uma única instância?

O --listen faz com que o servidor fique acessível em sua rede local, em vez de apenas no localhost. No entanto, o text-generation-webui não foi projetado para implantações de produção multiusuário — não há autenticação integrada e a interface Gradio é de sessão única. A extensão da API OpenAI lida melhor com requisições API simultâneas do que a interface web em cenários com múltiplos clientes, mas, se for exposta além do localhost, recomenda-se adicionar um proxy reverso com autenticação na frente dela.