~/ / Articoli sull'IA / LLM locali su un VPS / Chiamare un modello locale dal proprio codice: structured outputs e API compatibile con OpenAI in Ollama

Chiamare un modello locale dal proprio codice: structured outputs e API compatibile con OpenAI in Ollama

Quando Ollama gira sul tuo server, il tuo codice ha bisogno di due cose: un modo per ottenere risposte in una forma fissa e un modo per raggiungere il server da librerie che parlano già l'API OpenAI. Ollama documenta entrambi. Questo articolo riassume la pagina sugli structured outputs e quella sulla compatibilità con OpenAI, e indica che cosa la documentazione dice di non supportare.

Pubblicato: 2026-10-26 · 4 min di lettura · Verificato sulla documentazione ufficiale di Ollama il 2026-10-26. Le funzionalità supportate cambiano da una versione all'altra, quindi confermale nei documenti attuali.

Due modi per chiamare lo stesso server

Ollama ha una propria API, in cui gli esempi della documentazione fanno POST a http://localhost:11434/api/chat. Offre anche un'API compatibile con OpenAI sotto /v1/, così che i client OpenAI esistenti possano comunicare con Ollama cambiando solo l'URL di base.

Voce	API nativa	API compatibile con OpenAI
Indirizzo di base	http://localhost:11434/api/chat	http://localhost:11434/v1/
Chiave API	non menzionata negli esempi	api_key='ollama', che la pagina indica come obbligatoria ma ignorata
Campo per l'output strutturato	format	response_format

La riga sulla chiave API deriva dall'esempio di server locale della documentazione. Per il cloud, la pagina mostra base_url https://ollama.com/v1 con una chiave API del tuo account Ollama, che è un caso diverso.

Structured outputs: il campo format

Il campo format vincola la risposta. Accetta la stringa json per un JSON generico oppure un oggetto JSON Schema. Negli esempi cURL della documentazione il corpo della richiesta ha quattro campi: model, messages, stream impostato su false e format. Lo schema degli esempi ha type, properties e required.

Valore di format	Effetto secondo la documentazione
"json"	Il modello risponde con un JSON generico
un oggetto JSON Schema	La risposta è vincolata a quello schema

La documentazione afferma che è l'ideale passare anche lo JSON Schema come stringa nel prompt, per ancorare la risposta del modello.
Dice inoltre di abbassare la temperature, per esempio a 0, per completamenti più deterministici.
Per Python e JavaScript suggerisce di definire gli schemi con Pydantic o Zod, in modo da poterli riutilizzare per la validazione.
I modelli di visione accettano lo stesso parametro format. L'esempio di visione nella documentazione passa un'immagine insieme a uno schema.
Secondo la pagina, il cloud di Ollama al momento non supporta gli structured outputs.

Prima di fare affidamento su uno schema, controllalo. Il JSON Schema Validator qui sotto ti dice se lo schema stesso è valido e se una risposta di esempio vi corrisponde.

Controlla lo schema che invii

Uno schema con un errore può fallire tardi, quando la prima richiesta arriva al modello. Incolla lo schema e un esempio del JSON che ti aspetti, e verifica se concordano.

Provalo: JSON Schema Validator

JSON SchemaDati JSON

Segue JSON Schema Draft 2020-12 per le parole chiave che supporta. Legge $ref solo all'interno dello stesso schema.

Tutto viene eseguito nel tuo browser. Lo schema e i dati non vengono caricati.

Gli endpoint compatibili con OpenAI

Endpoint	Che cosa elenca la pagina	Elencato come non supportato
/v1/chat/completions	chat, streaming, JSON mode, output riproducibili, visione, strumenti, controllo del ragionamento	logprobs, tool_choice, logit_bias, user, n; URL di immagini (usa base64)
/v1/completions	completamenti, streaming, JSON mode, output riproducibili	logprobs, best_of, echo, logit_bias, user, n
/v1/models	elenco e recupero dei modelli	non elencato
/v1/embeddings	input come stringa o array di stringhe, formato di codifica, dimensioni	array di token, user
/v1/responses	streaming, strumenti di function calling, riepiloghi del ragionamento	richieste con stato: previous_response_id, conversation, truncation

Sull'endpoint chat la pagina elenca tra i campi di richiesta supportati: response_format, tools, stream, stream_options, seed, stop, temperature, top_p, max_tokens, frequency_penalty e presence_penalty.
La pagina afferma che gli structured outputs funzionano tramite l'API compatibile con OpenAI con response_format.
Se il tuo codice usa un campo della colonna dei non supportati, modifica il codice invece di aspettarti che il server lo ignori. La documentazione non dice come venga gestito ciascun campo non supportato, tranne che per il parlato (speech), dove i valori non supportati restituiscono un errore 400.

Strumenti e formato delle definizioni degli strumenti

Sia l'API nativa sia l'endpoint chat compatibile con OpenAI accettano tools. Se descrivi gli strumenti nella forma OpenAI, il Tool Definition Checker di questo sito verifica nomi, descrizioni e schemi dei parametri rispetto a quel formato prima che tu li invii.

Quando la risposta non è comunque un JSON valido

Vincolare l'output serve a ottenere un JSON valido, ma il tuo codice può comunque ricevere testo da un altro modello, da una versione più vecchia o da una richiesta senza format. Lo strumento qui sotto ripara i difetti più comuni, come i blocchi di codice, le virgole finali e gli apici sbagliati, e avvisa quando una riparazione cambia il significato.

Provalo: LLM JSON Repair

Risposta del modello o JSON rotto

Rientro2 spazi4 spaziTabulazioneMinificato

Vengono applicate solo le correzioni con un'unica risposta chiara. Tutto il resto viene segnalato con la sua posizione invece di essere indovinato.

Tutto avviene nel tuo browser. Il testo che incolli non viene caricato.

Una nota sull'accesso

L'esempio locale della documentazione dice che la chiave API è obbligatoria ma ignorata. Nostra lettura, non un'affermazione dei documenti: la chiave non protegge il server, quindi lascia Ollama sul suo indirizzo predefinito e metti un'autenticazione davanti se un'altra macchina deve raggiungerlo.