Como usar o Ollama com uma GUI (e um fallback hospedado)

Por que o Ollama precisa de uma GUI separada

Se você quer saber como usar o Ollama com uma GUI, o primeiro fato a aceitar é que o projeto Ollama é um servidor e uma ferramenta de linha de comando. Ele baixa modelos e responde a requisições em uma porta local. A janela de chat é responsabilidade de outro software, e existem várias boas opções.

Essa divisão é útil. Como o Ollama expõe uma API estilo OpenAI na sua própria máquina (por padrão na porta 11434 em /v1), qualquer front end que permita definir uma URL base do OpenAI personalizada pode usá-lo. A mesma propriedade significa que você pode apontar esse front end para outro local mais tarde. Este artigo percorre a configuração local primeiro, depois adiciona um endpoint hospedado como uma segunda conexão.

Escolha um front-end

Três famílias de ferramentas cobrem a maioria das pessoas. Verifique a documentação de cada projeto para os passos de instalação atuais, pois eles mudam frequentemente.

• Open WebUI. Uma interface de navegador auto-hospedada. Suporta Ollama diretamente e também aceita qualquer conexão compatível com OpenAI. Geralmente instalada com Docker ou pip.
• Clientes de desktop. Aplicativos nativos como Chatbox ou Msty permitem adicionar um servidor Ollama ou um provedor compatível com OpenAI através de uma tela de configurações. Sem servidor para rodar.
• Front ends para roleplay e escrita. O SillyTavern permite adicionar um endpoint compatível com OpenAI, e ferramentas similares existem para ficção de longo formato e personagens companheiros para adultos.

Se você não quer um container Docker, um cliente de desktop é o caminho mais curto. Se quer uma interface compartilhada para várias pessoas em uma mesma rede, o Open WebUI é a escolha usual.

Passo a passo com Open WebUI

1. Instale e inicie o Ollama, depois puxe um modelo com o comando ollama pull. Confirme se ele responde no terminal antes de prosseguir.
2. Inicie o Open WebUI. Com Docker, o padrão usual é publicar uma porta e montar um volume para os dados dele.
3. Abra a página web, crie a primeira conta local (ela se tornará o admin) e procure a área de conexões nas configurações de admin.
4. Verifique se a URL do Ollama aponta para a máquina onde o Ollama roda. Quando ambos estão no mesmo host, isso é normalmente o endereço local na porta 11434. Quando o Open WebUI roda dentro de um container, localhost significa o próprio container, que é a razão mais comum para a lista de modelos permanecer vazia.
5. Recarregue, escolha um modelo no menu suspenso e envie uma mensagem.

Esta é uma GUI completa. Nada sai do seu computador, e a velocidade depende da sua GPU ou CPU.

Adicionando uma conexão compatível com OpenAI hospedada

Agora o plano de contingência. Suponha que o modelo que você pode executar localmente seja pequeno demais para uma cena longa, ou sua GPU esteja ocupada renderizando. Você pode adicionar uma segunda conexão à mesma GUI. Para isso, você precisa de uma chave de API, que pode obter na página da chave de API após se cadastrar com Google ou com e-mail e senha. Um crédito de teste único de $0,50 está disponível com um clique, não precisa de pagamento e dura 7 dias.

No Open WebUI, adicione uma conexão OpenAI com estes valores:

• URL base: https://api.ollamansfw.com/v1
• Chave de API: sua chave, enviada como Authorization: Bearer
• Modelo: uncensored

Se preferir variáveis de ambiente ao iniciar o container, o Open WebUI documenta OPENAI_API_BASE_URL e OPENAI_API_KEY para esse propósito:

Copydocker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=https://api.ollamansfw.com/v1 \
  -e OPENAI_API_KEY=YOUR_KEY \
  -v open-webui:/app/backend/data \
  --name open-webui ghcr.io/open-webui/open-webui:main
# model to pick in the UI: uncensored

Após recarregar, uncensored deve aparecer no menu suspenso de modelos ao lado dos seus modelos locais. A interface o encontra através de GET /v1/models. Você pode alternar entre um modelo local e o hospedado dentro da mesma lista de conversas.

Teste o endpoint fora da GUI primeiro

Quando uma GUI mostra um erro vago, a maneira mais rápida de saber se o problema é a chave ou a interface é uma chamada direta. Aqui está uma requisição de streaming com curl:

Copycurl -N https://api.ollamansfw.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "stream": true,
    "messages": [{"role": "user", "content": "Write two sentences about a lighthouse keeper."}]
  }'

Você deve ver uma série de linhas data: terminando com informações de uso. Se isso funcionar, a chave e a URL estão corretas e o problema está no front end. A página de solução de problemas cobre deslizes típicos como a falta de /v1 ou um espaço no final da chave.

As mesmas configurações de cliente que você usa para modelos locais geralmente se aplicam. Temperatura, top_p, sequências de parada, seed e penalidades são passadas para o modelo.

Usando o endpoint hospedado no seu próprio código

Uma GUI é um cliente. Scripts e pequenos aplicativos são outro, e o endpoint hospedado funciona com os SDKs padrão da OpenAI. Chamada de funções e modo JSON são suportados, o que importa se sua GUI ou agente os usa.

Copyfrom openai import OpenAI

client = OpenAI(base_url="https://api.ollamansfw.com/v1", api_key="YOUR_KEY")

resp = client.chat.completions.create(
    model="uncensored",
    response_format={"type": "json_object"},
    messages=[
        {"role": "system", "content": "Reply with a JSON object with keys title and summary."},
        {"role": "user", "content": "A short story about a lighthouse keeper."},
    ],
)
print(resp.choices[0].message.content)

No Node o padrão é idêntico:

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.ollamansfw.com/v1",
  apiKey: process.env.API_KEY,
});

const stream = await client.chat.completions.create({
  model: "uncensored",
  stream: true,
  messages: [{ role: "user", content: "Name three sailing knots." }],
});
for await (const part of stream) {
  process.stdout.write(part.choices[0]?.delta?.content ?? "");
}

O início rápido tem mais exemplos, incluindo chamadas de ferramentas com tool_choice.

Problemas comuns e correções

A maioria das falhas em uma configuração de GUI vem de uma lista curta de causas.

• Lista de modelos vazia para a conexão local. O front end não consegue alcançar o Ollama. Verifique o endereço e lembre-se de que uma GUI em container não vê seu host como localhost.
• 401 do endpoint hospedado. A chave está faltando ou errada. Cole-a novamente sem espaços e certifique-se de que a GUI a envia como um token bearer.
• 404 em todas as requisições. A URL base provavelmente não tem /v1, ou tem duas vezes.
• As respostas param ou a interface trava. Algumas interfaces armazenam em buffer a saída de streaming através de um proxy. Tente o teste direto com curl acima e, se ele transmitir, verifique as configurações do proxy à frente da sua GUI.
• Respostas locais lentas. O modelo é grande demais para sua VRAM e está sendo despejado na memória do sistema. Escolha uma quantização menor ou mude essa conversa para a conexão hospedada.

Mantenha uma regra em mente para aplicativos de ficção e companheiros para adultos: o modelo hospedado responde sem recusas de conteúdo para uso adulto legal, mas conteúdo sexual envolvendo menores de idade nunca é permitido, e o serviço aplica isso como um limite rígido.

Limites e custos a saber na GUI

Front ends podem disparar várias requisições ao mesmo tempo, por exemplo, quando geram um título de chat em segundo plano enquanto a resposta principal faz streaming. Uma chave completa permite 8 requisições simultâneas e 300 requisições por minuto. Uma chave de teste permite 2 simultâneas e 60 por minuto. Uma requisição de streaming ocupa seu slot até que o streaming termine. Se você exceder um limite, receberá HTTP 429 com o código rate_limited ou concurrency, e em sobrecarga temporária um 429 com Retry-After: 5. Desativar a geração de título em segundo plano na GUI é uma solução simples para uma chave de teste.

O custo é por token: $0,15 por 1M de entrada e $0,50 por 1M de saída. Uma rodada de chat com 2.000 tokens de histórico e uma resposta de 500 tokens custa $0,0003 mais $0,00025, que é $0,00055. Os cabeçalhos de resposta incluem X-Balance-USD, então você pode acompanhar seu crédito diminuindo. Detalhes sobre recargas estão na página de preços. Este site é apenas cripto: USDT no TRC20 ou USDC na Base, qualquer valor inteiro de $20 a $500.

A janela de contexto é de 100.000 tokens, então conversas muito longas custarão mais por turno à medida que o histórico cresce, porque todo o histórico é enviado a cada vez. A maioria das GUIs tem uma configuração para reduzir ou resumir mensagens antigas.

Mais guias

• Alternativas de Software Ollama: API Hospedada Uncensored
• Precificação da API Ollamansfw: Custos por Token Explicados
• Guia da API LLM sem censura