API do Ollama compatível com a OpenAI

O Ollama executa modelos abertos na sua própria máquina e os disponibiliza por meio de uma API compatível com a OpenAI em http://localhost:11434/v1. Como o formato de comunicação é igual ao da OpenAI, o SDK oficial da OpenAI funciona com o Ollama sem alterações — e o mesmo código acessa modelos de ponta hospedados, alterando apenas a URL base.

O que é a API do Ollama compatível com a OpenAI

O Ollama é um projeto independente de código aberto para executar localmente modelos como Llama, Qwen e Mistral. Além da API nativa, ele oferece uma interface compatível com a OpenAI, permitindo que ferramentas desenvolvidas para a OpenAI funcionem sem precisar ser reescritas. Ele implementa os endpoints usados pela maioria dos aplicativos:

Ela abrange chat, completions e embeddings (além de entrada de imagem em modelos locais multimodais). Não gera imagens, vídeos nem áudio. A Kunavo implementa o mesmo contrato /v1/chat/completions — essa referência documenta cada parâmetro, o formato dos deltas de streaming e o objeto usage, além de incluir uma tabela de paridade, linha por linha, com a interface v1 do Ollama.

Chame o Ollama com o SDK da OpenAI

Aponte base_url para http://localhost:11434/v1. O SDK exige um api_key, mas o Ollama local ignora seu valor — informe qualquer string. Defina model como um modelo que você baixou (por exemplo, ollama pull llama3.2).

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",  # Ollama's OpenAI-compatible API
    api_key="ollama",  # required by the SDK, ignored by local Ollama
)

resp = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Explain quicksort in one paragraph."}],
)
print(resp.choices[0].message.content)

Ou com curl:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "messages": [{"role": "user", "content": "Hello, Ollama"}]
  }'

O mesmo código com modelos de ponta hospedados

O Ollama é ideal para desenvolvimento offline e trabalhos que exigem privacidade, mas os modelos locais ficam atrás dos modelos de ponta em raciocínio complexo, programação e contexto longo. Como a Kunavo também é compatível com a OpenAI, transferir uma chamada para um modelo hospedado exige apenas alterar duas linhas — base_url e o slug do modelo:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.kunavo.com/v1",  # only this line changes
    api_key="sk-kn-...",               # a real key now
)

resp = client.chat.completions.create(
    model="claude-sonnet-5",  # a hosted frontier model
    messages=[{"role": "user", "content": "Explain quicksort in one paragraph."}],
)
print(resp.choices[0].message.content)

Alternar por ambiente

Um padrão comum é usar o Ollama no desenvolvimento local e modelos hospedados em produção, selecionados por uma variável de ambiente. O código do cliente e da solicitação é idêntico — apenas base_url e o modelo mudam:

import os
from openai import OpenAI

# One client, switched by environment. Local for dev, hosted for prod.
if os.getenv("APP_ENV") == "production":
    client = OpenAI(base_url="https://api.kunavo.com/v1",
                    api_key=os.environ["KUNAVO_API_KEY"])
    MODEL = "claude-haiku-4-5"
else:
    client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
    MODEL = "llama3.2"

resp = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "ping"}],
)
print(resp.choices[0].message.content)

Perguntas frequentes

Próximos passos

• Guia da API compatível com a OpenAI — do endpoint local do Ollama aos modelos hospedados
• O que é um gateway de IA? — o padrão de endpoint único
• Referência de geração de respostas de chat
• Início rápido — sua primeira solicitação em 60 segundos