Conteúdo detalhado
🔌 Por que uma API local
Uma interface de chat é ótima para você conversar. Mas um programa não conversa por uma tela — ele precisa de um endereço para mandar texto e receber resposta. Esse endereço é a API. O truque do Ollama é falar exatamente o mesmo "formato" que a OpenAI usa: assim, qualquer app, script ou agente que já sabe falar com o ChatGPT funciona com seu modelo local trocando uma única linha.
🆕 Novo aqui?
"API" (Interface de Programação de Aplicações) é uma porta de entrada por onde um programa pede algo a outro. "Endpoint" é o endereço exato dessa porta — uma URL como http://localhost:11434/v1/chat/completions. "OpenAI-compatível" quer dizer que o formato do pedido e da resposta é idêntico ao da API da OpenAI — mesmas chaves model, messages, choices — só que servido pela sua máquina.
🔑 A ideia central
A compatibilidade é a alavanca. Com ela você ganha três coisas de uma vez:
- •Reuso: bibliotecas, SDKs e ferramentas feitas para a OpenAI funcionam sem reescrever nada.
- •Portabilidade: troque entre nuvem e local mudando só a base_url — o código continua igual.
- •Automação: scripts e agentes (Trilha 4) passam a usar o modelo sem você abrir tela nenhuma.
✗ Sem API (só chat na tela)
- ✗Cada uso exige você digitando à mão
- ✗Nada de automação ou agendamento
- ✗Impossível plugar em outros programas
- ✗Sem agentes 24/7
✓ Com API local
- ✓Qualquer script chama o modelo via HTTP
- ✓Mesmo SDK da OpenAI, modelo na sua máquina
- ✓Base para automações, RAG e agentes
- ✓Tudo offline, sem pedágio por token
🌐 O endpoint do Ollama
Quando você instalou o Ollama (Módulo 3.1), ele já subiu um servidor HTTP escutando em http://localhost:11434. localhost = a própria máquina; 11434 = a porta. Esse servidor oferece dois conjuntos de rotas: as nativas do Ollama e as OpenAI-compatíveis sob /v1. Para reaproveitar apps e SDKs existentes, use sempre as de /v1.
O caminho de uma requisição, do seu programa até o modelo e de volta:
Seu programa monta o pedido
Um JSON com o model e a lista de messages — exatamente o formato da OpenAI.
O servidor Ollama recebe na :11434
Ele carrega o modelo na memória (se ainda não estiver) e roda a inferência localmente.
A resposta volta em JSON
No mesmo formato da OpenAI: o texto vem em choices[0].message.content.
🗺️ As rotas que importam
Objetivo: conhecer os endereços. As de /v1 são as que você usa com SDKs prontos.
Como verificar: rode curl http://localhost:11434/v1/models — deve listar, em JSON, os modelos que você já baixou.
💡 Dica prática
Se a porta 11434 não responde, o servidor não está de pé. No Linux/macOS o app do Ollama já o mantém rodando; se precisar subir manualmente, use ollama serve. "Connection refused" quase sempre é isso: o serviço não está ativo ou está em outra máquina.
⌨️ Primeira chamada com curl
A forma mais rápida de provar que a API funciona é o curl — uma ferramenta de terminal que faz requisições HTTP. Nenhuma instalação de biblioteca, nenhum código: só o terminal e um JSON. Se isto responder, sua API local está no ar.
⌨️ Exemplo prático: chat via curl
Objetivo: mandar uma mensagem ao modelo e receber a resposta em JSON. Cole no terminal (com o Ollama rodando e o modelo qwen2.5:7b já baixado).
Como verificar: a saída é um JSON com um campo choices. O texto da resposta está em choices[0].message.content. Se aparecer, você acabou de servir seu modelo por API.
📊 Anatomia do JSON de resposta
- model — qual modelo respondeu.
- choices[0].message.content — o texto gerado (é o que você quer).
- choices[0].finish_reason — por que parou (ex.: stop).
- usage — contagem de tokens de entrada e saída.
🐍 Do código: SDK da OpenAI apontado pro local
Aqui a compatibilidade brilha. O SDK oficial da OpenAI (a biblioteca openai em Python) funciona contra o Ollama — basta mudar a base_url para o seu endpoint local e passar uma api_key qualquer (o Ollama não valida a chave; ela é exigida só porque o SDK pede uma).
🐍 Exemplo prático: chat em Python
Objetivo: chamar o modelo local pelo SDK da OpenAI. Instale com pip install openai e rode.
Como verificar: o script imprime a frase gerada pelo modelo. Para voltar à nuvem, troque base_url e a chave — o resto do código fica idêntico. Esse é o ponto inteiro.
💡 Dica prática
Em JavaScript/TypeScript é a mesma história: o pacote openai aceita baseURL: "http://localhost:11434/v1" e apiKey: "ollama". Guarde a base_url numa variável de ambiente (OPENAI_BASE_URL) para alternar local/nuvem sem tocar no código.
✓ Faça
- ✓Use o nome de modelo que aparece em ollama list
- ✓Centralize base_url numa env var
- ✓Trate timeouts: o 1º request carrega o modelo (mais lento)
✗ Evite
- ✗Esquecer o /v1 no fim da base_url
- ✗Usar um nome de modelo que não foi baixado
- ✗Pôr uma chave real da OpenAI no código local
🌊 Streaming, embeddings e múltiplos modelos
A mesma API faz mais três coisas que você vai usar muito: streaming (a resposta chega palavra a palavra, como no ChatGPT), embeddings (transformar texto em vetores — base do RAG, no próximo módulo) e rotear por modelo (basta mudar o campo model).
🌊 Streaming: resposta token a token
Objetivo: mostrar o texto enquanto ele é gerado, sem esperar o fim. Basta stream=True.
Como verificar: o texto aparece aos poucos, não de uma vez. No curl, o equivalente é pôr "stream": true no corpo JSON.
🧮 Embeddings: texto vira vetor
Objetivo: gerar o vetor de significado de um texto — o tijolo do RAG (Módulo 3.6). Use um modelo de embedding como nomic-embed-text (baixe com ollama pull nomic-embed-text).
Como verificar: a resposta traz data[0].embedding — uma longa lista de números. É isso que um banco vetorial guarda para buscar por similaridade.
🔀 Vários modelos, um só endpoint
Você não sobe um servidor por modelo. O mesmo endpoint serve todos os que estão baixados — basta trocar o campo model: um modelo pequeno e rápido para classificação, um maior para raciocínio, um de embedding para RAG. O Ollama carrega/descarrega conforme a demanda.
🔒 Expondo na tailnet com segurança
Por padrão, a API só responde em localhost — ninguém de fora alcança. Mas no Módulo 2.4 você montou uma tailnet (rede privada via Tailscale). Juntando as duas peças, você usa o modelo de casa pelo notebook do trabalho ou pelo celular — tudo dentro da sua rede privada, sem abrir nada para a internet.
Leia da esquerda para a direita: o app/script (roxo) chama a API local na porta 11434, que roda o modelo. O ramo em ciano mostra outro dispositivo alcançando a mesma API pela tailnet — sem expor nada à internet pública.
⌨️ Exemplo prático: abrir na tailnet
Objetivo: fazer o Ollama escutar em toda a interface (não só em localhost) para os outros devices da sua tailnet alcançarem.
Como verificar: do segundo device, o curl com o IP 100.x deve responder em JSON. Se não responder, cheque se ambos estão na tailnet (tailscale status).
⚠️ Alerta: nunca exponha à internet pública
OLLAMA_HOST=0.0.0.0 abre a porta para qualquer rede a que a máquina esteja conectada. Dentro da tailnet isso é seguro: só seus devices autenticados enxergam o 100.x. Na internet aberta, não. A API do Ollama não tem login nem senha — qualquer um que alcance a porta usa (e abusa) do seu modelo.
- ✗NUNCA faça port-forward da 11434 no roteador.
- ✗NUNCA aponte a porta para um IP público.
- ✓Acesse remoto SÓ pela tailnet (IP 100.x) — é o caminho seguro.
✓ Tailnet (seguro)
- ✓Só devices seus e autenticados
- ✓Tráfego criptografado ponta a ponta
- ✓Nenhuma porta aberta no roteador
✗ Internet pública (perigoso)
- ✗Qualquer um na web alcança a porta
- ✗Sem login: API totalmente aberta
- ✗Modelo sequestrado e conta de luz sua
Auto-checagem (opcional): para usar o SDK da OpenAI com seu modelo local, o que você ajusta?
📌 Resumo do módulo
Próximo módulo:
3.6 — Embeddings, memória & RAG