~/ / Artículos de IA / LLM locales en un VPS / Llamar a un modelo local desde tu código: salidas estructuradas y la API compatible con OpenAI en Ollama
Llamar a un modelo local desde tu código: salidas estructuradas y la API compatible con OpenAI en Ollama
Cuando Ollama ya funciona en tu servidor, tu propio código necesita dos cosas: una forma de obtener respuestas con una forma fija y una forma de llegar al servidor desde bibliotecas que ya hablan la API de OpenAI. Ollama documenta ambas. Este artículo resume la página de salidas estructuradas y la página de compatibilidad con OpenAI, y señala lo que la documentación indica que no se admite.
Publicado: · 4 min de lectura · Comprobado con la documentación oficial de Ollama el 2026-10-26. Las funciones admitidas cambian entre versiones, así que confírmalas en los documentos actuales.
Dos formas de llamar al mismo servidor
Ollama tiene su propia API, en la que los ejemplos de la documentación hacen POST a http://localhost:11434/api/chat. También ofrece una API compatible con OpenAI bajo /v1/, de modo que los clientes de OpenAI existentes puedan comunicarse con él cambiando la URL base.
| Elemento | Native API | OpenAI-compatible API |
|---|---|---|
| Dirección base | http://localhost:11434/api/chat | http://localhost:11434/v1/ |
| Clave de API | no se menciona en los ejemplos | api_key='ollama', que la página marca como obligatoria pero ignorada |
| Campo de salida estructurada | format | response_format |
La línea de la clave de API procede del ejemplo de servidor local de la documentación. Para la nube, la página muestra base_url https://ollama.com/v1 con una clave de API de tu cuenta de Ollama, que es un caso distinto.
Salidas estructuradas: el campo format
El campo format limita la respuesta. Acepta la cadena json para JSON genérico, o un objeto de JSON Schema. En los ejemplos de cURL de la documentación, el cuerpo de la petición tiene cuatro campos: model, messages, stream establecido en false y format. El esquema de los ejemplos tiene type, properties y required.
| Valor de format | Efecto según la documentación |
|---|---|
| "json" | El modelo responde con JSON genérico |
| un objeto de JSON Schema | La respuesta queda limitada a ese esquema |
- La documentación dice que lo ideal es pasar también el JSON Schema como cadena en el prompt, para anclar la respuesta del modelo.
- También dice que se baje la temperature, por ejemplo a 0, para obtener respuestas más deterministas.
- Para Python y JavaScript sugiere definir los esquemas con Pydantic o Zod, de modo que se puedan reutilizar para la validación.
- Los modelos de visión aceptan el mismo parámetro format. El ejemplo de visión de la documentación pasa una imagen junto con un esquema.
- Según la página, la nube de Ollama no admite por ahora las salidas estructuradas.
Antes de confiar en un esquema, compruébalo. El JSON Schema Validator de abajo te indica si el propio esquema es válido y si una respuesta de ejemplo lo cumple.
Comprueba el esquema que envías
Un esquema con un error puede fallar tarde, cuando la primera petición llega al modelo. Pega el esquema y un ejemplo del JSON que esperas, y comprueba si coinciden.
Pruébalo: JSON Schema Validator
Sigue JSON Schema Draft 2020-12 en las palabras clave que admite. Lee $ref solo dentro del mismo esquema.
Todo se ejecuta en tu navegador. El esquema y los datos no se suben.
Los endpoints compatibles con OpenAI
| Endpoint | Lo que indica la página | Indicado como no admitido |
|---|---|---|
| /v1/chat/completions | chat, streaming, JSON mode, salidas reproducibles, visión, herramientas, control del razonamiento | logprobs, tool_choice, logit_bias, user, n; URL de imágenes (usa base64) |
| /v1/completions | completions, streaming, JSON mode, salidas reproducibles | logprobs, best_of, echo, logit_bias, user, n |
| /v1/models | listar y recuperar modelos | no figura |
| /v1/embeddings | entrada de cadena o de matriz de cadenas, formato de codificación, dimensiones | matrices de tokens, user |
| /v1/responses | streaming, herramientas de llamada a funciones, resúmenes de razonamiento | peticiones con estado: previous_response_id, conversation, truncation |
- En el endpoint de chat, la página enumera estos campos de la petición entre los admitidos: response_format, tools, stream, stream_options, seed, stop, temperature, top_p, max_tokens, frequency_penalty y presence_penalty.
- La página afirma que las salidas estructuradas funcionan a través de la API compatible con OpenAI mediante response_format.
- Si tu código usa un campo de la columna de no admitidos, cambia el código en lugar de esperar que el servidor lo ignore. La documentación no explica cómo se trata cada campo no admitido, salvo en el caso del habla, donde los valores no admitidos devuelven un error 400.
Herramientas y el formato de sus definiciones
Tanto la API nativa como el endpoint de chat compatible con OpenAI aceptan tools. Si describes las herramientas con la forma de OpenAI, el Tool Definition Checker de este sitio comprueba los nombres, las descripciones y los esquemas de parámetros según ese formato antes de que los envíes.
Cuando la respuesta sigue sin ser JSON válido
Limitar la salida sirve para obtener JSON válido, pero tu propio código aún puede recibir texto de otro modelo, de una versión anterior o de una petición sin format. La herramienta de abajo repara los fallos habituales, como los bloques de código, las comas finales y las comillas incorrectas, y avisa cuando una reparación cambia el significado.
Pruébalo: LLM JSON Repair
Solo se aplican las correcciones que tienen una respuesta clara. Todo lo demás se informa con su posición en lugar de adivinarse.
Todo se ejecuta en tu navegador. El texto que pegas no se sube.
Una nota sobre el acceso
El ejemplo local de la documentación dice que la clave de API es obligatoria pero se ignora. Nuestra interpretación, no una afirmación de los documentos: la clave no protege el servidor, así que mantén Ollama en su dirección predeterminada y pon una autenticación por delante si otra máquina debe acceder a él.
Fuentes
Sigue leyendo
- Open WebUI en un VPS: ejecútalo en Docker y conéctalo a OllamaEjecuta Open WebUI con Docker y conéctalo a Ollama en tu propio servidor: los comandos, la primera cuenta, los dos tipos de conexión y cómo actualizar.
- ¿Qué puede hacer un modelo local? Tools, thinking, vision y embeddings en Ollama, y qué cabe en un VPSTools, thinking, vision, embeddings: qué significan las etiquetas de la biblioteca de Ollama, qué modelos las llevan y cuánto pesan las descargas.
- Instalar Ollama en un VPS y mantenerlo en marcha: instalación, servicio systemd, ajustes y actualizacionesInstala Ollama en un VPS con Linux y mantenlo en marcha: el comando de instalación, el servicio systemd, las variables de entorno, el almacenamiento de modelos y las actualizaciones, según la documentación oficial.
- ¿Cuánta memoria necesita un LLM local en un VPS? Archivo del modelo más caché KVArchivo del modelo más caché KV: lo que dicen la biblioteca de Ollama, las preguntas frecuentes de Ollama y las configuraciones oficiales de los modelos sobre la memoria que necesita un LLM local en un VPS.