~/ / Artigos sobre IA / LLMs locais em uma VPS / Chamando um modelo local pelo seu código: saídas estruturadas e a API compatível com OpenAI no Ollama

Chamando um modelo local pelo seu código: saídas estruturadas e a API compatível com OpenAI no Ollama

Quando o Ollama já roda no seu servidor, o seu código precisa de duas coisas: um jeito de obter respostas em um formato fixo e um jeito de acessar o servidor a partir de bibliotecas que já falam a API da OpenAI. O Ollama documenta as duas. Este artigo resume a página de saídas estruturadas e a página de compatibilidade com a OpenAI, e aponta o que a documentação diz que não é compatível.

Publicado: 2026-10-26 · 4 min de leitura · Conferido na documentação oficial do Ollama em 2026-10-26. Os recursos compatíveis mudam entre versões, então confirme nos documentos atuais.

Duas formas de chamar o mesmo servidor

O Ollama tem a sua própria API, e os exemplos da documentação fazem POST para http://localhost:11434/api/chat. Ele também oferece uma API compatível com OpenAI em /v1/, para que clientes OpenAI já existentes possam se comunicar com ele apenas trocando a URL base.

Item	Native API	OpenAI-compatible API
Endereço base	http://localhost:11434/api/chat	http://localhost:11434/v1/
Chave de API	não mencionada nos exemplos	api_key='ollama', que a página marca como obrigatória, mas ignorada
Campo de saída estruturada	format	response_format

A linha da chave de API vem do exemplo de servidor local da documentação. Para a nuvem, a página mostra base_url https://ollama.com/v1 com uma chave de API da sua conta Ollama, o que é um caso diferente.

Saídas estruturadas: o campo format

O campo format restringe a resposta. Ele aceita a string json para JSON genérico ou um objeto de JSON schema. Nos exemplos de cURL da documentação, o corpo da requisição tem quatro campos: model, messages, stream definido como false e format. O schema dos exemplos tem type, properties e required.

Valor de format	Efeito segundo a documentação
"json"	O modelo responde com JSON genérico
um objeto de JSON schema	A resposta é restringida a esse schema

A documentação diz que o ideal é passar também o JSON schema como string no prompt, para ancorar a resposta do modelo.
Ela também diz para baixar a temperature, por exemplo para 0, para obter respostas mais determinísticas.
Para Python e JavaScript, ela sugere definir os schemas com Pydantic ou Zod, para que possam ser reutilizados na validação.
Modelos de visão aceitam o mesmo parâmetro format. O exemplo de visão da documentação passa uma imagem junto com um schema.
Segundo a página, a nuvem do Ollama atualmente não oferece suporte a saídas estruturadas.

Antes de confiar em um schema, confira-o. O JSON Schema Validator abaixo mostra se o próprio schema é válido e se uma resposta de exemplo corresponde a ele.

Confira o schema que você envia

Um schema com erro pode falhar tarde, quando a primeira requisição chega ao modelo. Cole o schema e um exemplo do JSON que você espera, e veja se os dois estão de acordo.

Experimente: JSON Schema Validator

JSON SchemaDados JSON

Segue o JSON Schema Draft 2020-12 nas palavras-chave que suporta. Lê $ref apenas dentro do mesmo schema.

Tudo roda no seu navegador. O schema e os dados não são enviados.

Os endpoints compatíveis com OpenAI

Endpoint	O que a página lista	Listado como não compatível
/v1/chat/completions	chat, streaming, JSON mode, saídas reproduzíveis, visão, tools, controle de raciocínio	logprobs, tool_choice, logit_bias, user, n; URLs de imagem (use base64)
/v1/completions	completions, streaming, JSON mode, saídas reproduzíveis	logprobs, best_of, echo, logit_bias, user, n
/v1/models	listar e recuperar modelos	não listado
/v1/embeddings	entrada de string ou de array de strings, formato de codificação, dimensões	arrays de tokens, user
/v1/responses	streaming, tools de chamada de função, resumos de raciocínio	requisições com estado: previous_response_id, conversation, truncation

No endpoint de chat, a página lista estes campos de requisição entre os compatíveis: response_format, tools, stream, stream_options, seed, stop, temperature, top_p, max_tokens, frequency_penalty e presence_penalty.
A página afirma que as saídas estruturadas funcionam pela API compatível com OpenAI por meio de response_format.
Se o seu código usa um campo da coluna de não compatíveis, mude o código em vez de esperar que o servidor o ignore. A documentação não diz como cada campo não compatível é tratado, exceto no caso de fala (speech), em que valores não compatíveis retornam um erro 400.

Tools e o formato das definições de tools

Tanto a API nativa quanto o endpoint de chat compatível com OpenAI aceitam tools. Se você descreve as tools no formato da OpenAI, o Tool Definition Checker deste site confere os nomes, as descrições e os schemas de parâmetros nesse formato antes de você enviá-los.

Quando a resposta ainda não é um JSON válido

Restringir a saída serve para lhe dar um JSON válido, mas o seu código ainda pode receber texto de outro modelo, de uma versão mais antiga ou de uma requisição sem format. A ferramenta abaixo repara as falhas comuns, como blocos de código, vírgulas sobrando e aspas erradas, e avisa quando um reparo muda o sentido.

Experimente: LLM JSON Repair

Resposta do modelo ou JSON quebrado

Indentação2 espaços4 espaçosTabMinificado

Só são aplicadas correções com uma única resposta clara. Todo o resto é apontado com a posição, em vez de ser adivinhado.

Tudo roda no seu navegador. O texto que você cola não é enviado.

Uma observação sobre acesso

O exemplo local da documentação diz que a chave de API é obrigatória, mas ignorada. Nossa leitura, não uma declaração dos documentos: a chave não protege o servidor, então mantenha o Ollama no endereço padrão e coloque uma autenticação na frente dele se outra máquina precisar acessá-lo.