Salida estructurada

La salida estructurada te ayuda a usar las respuestas del modelo directamente en el software. En lugar de pedir texto libre y analizarlo después, puedes solicitar JSON o una forma estricta basada en JSON Schema. Úsala para extracción, llenado de formularios, generación de configuraciones, decisiones de enrutamiento y cualquier flujo de trabajo donde el código posterior espere campos estables.

Modo JSON

El modo JSON le pide al modelo que devuelva JSON válido:

{
  "model": "gpt-5.4-mini",
  "messages": [
    {"role": "system", "content": "You extract information and return JSON only."},
    {"role": "user", "content": "Alice is 28 and works as an engineer. Extract name, age, and job."}
  ],
  "response_format": {
    "type": "json_object"
  }
}

El modo JSON garantiza JSON válido, pero no garantiza una estructura de campos específica. Describe claramente las claves esperadas en el prompt cuando uses este modo.

Modo JSON Schema

Usa json_schema cuando necesites una forma más estricta:

{
  "model": "gpt-5.4-mini",
  "messages": [
    {"role": "user", "content": "Alice is 28 and works as an engineer."}
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "person_info",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "age": {"type": "integer"},
          "job": {"type": "string"}
        },
        "required": ["name", "age", "job"],
        "additionalProperties": false
      }
    }
  }
}

Campos importantes:

strict: true le pide al modelo que siga el esquema de cerca.
required enumera los campos que deben estar presentes.
additionalProperties: false evita campos inesperados.

Ejemplo en Python

Reemplaza todo el valor sk-your-api-key en API_KEY con tu clave real. Para usar otro modelo, cambia MODEL. El ejemplo omite las variables de entorno del proxy del sistema y se conecta directamente a Moxus AI.

import json
import httpx
from openai import OpenAI

# Replace the entire value with your actual key before running.
API_KEY = "sk-your-api-key"
# Use the exact name from Model Square. This example uses gpt-5.4-mini.
MODEL = "gpt-5.4-mini"

client = OpenAI(
    api_key=API_KEY,
    base_url="https://moxus.ai/v1",
    # Connect directly to Moxus AI without reading system or terminal proxy variables.
    http_client=httpx.Client(trust_env=False, timeout=60.0),
)

response = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "user", "content": "Alice is 28 and works as an engineer."}
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                    "job": {"type": "string"},
                },
                "required": ["name", "age", "job"],
                "additionalProperties": False,
            },
        },
    },
)

data = json.loads(response.choices[0].message.content)
print(data["name"], data["age"], data["job"])

Ejemplo en Node.js

Reemplaza todo el valor sk-your-api-key en API_KEY con tu clave real. Para usar otro modelo, cambia MODEL. El modelo devuelve una cadena JSON; el ejemplo la convierte en un objeto con JSON.parse.

import OpenAI from "openai";

// Replace the entire value with your actual key before running.
const API_KEY = "sk-your-api-key";
// Use the exact name from Model Square. This example uses gpt-5.4-mini.
const MODEL = "gpt-5.4-mini";

const client = new OpenAI({
  apiKey: API_KEY,
  baseURL: "https://moxus.ai/v1",
});

const response = await client.chat.completions.create({
  model: MODEL,
  messages: [
    { role: "user", content: "Alice is 28 and works as an engineer." },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "person_info",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          age: { type: "integer" },
          job: { type: "string" },
        },
        required: ["name", "age", "job"],
        additionalProperties: false,
      },
    },
  },
});

const content = response.choices[0].message.content;
if (!content) {
  throw new Error("The model did not return JSON content");
}

const data = JSON.parse(content);
console.log(data.name, data.age, data.job);

Estructuras anidadas

Los esquemas pueden incluir arreglos, objetos anidados y enumeraciones:

{
  "type": "object",
  "properties": {
    "order_id": {"type": "string"},
    "status": {
      "type": "string",
      "enum": ["pending", "paid", "shipped", "done"]
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "quantity": {"type": "integer"},
          "price": {"type": "number"}
        },
        "required": ["name", "quantity", "price"],
        "additionalProperties": false
      }
    }
  },
  "required": ["order_id", "status", "items"],
  "additionalProperties": false
}