Azure OpenAI Decisions API: Clasificación práctica

Azure OpenAI Decisions API es un endpoint dedicado a pedirle a un modelo que evalúe evidencia y devuelva respuestas tipadas, en lugar de un párrafo de texto generado. Puede comprobar un predicado, seleccionar entre opciones que definas o puntuar una entrada según una rúbrica ordenada. Esta guía muestra cómo usar esas salidas como señales acotadas para una aplicación, con un ejemplo sintético de clasificación de solicitudes de soporte y las salvedades actuales sobre disponibilidad, privacidad y precios.

Qué hace Decisions API

El endpoint es /openai/v1/decisions. Una solicitud proporciona una implementación de modelo, una entrada compartida y una o varias preguntas con nombre. La respuesta contiene un array answers y el uso de tokens. Los tipos de pregunta documentados son:

Tipo	Salida	Uso adecuado
predicate	Una probabilidad de 0 a 1 de que una condición sea verdadera	¿El cliente solicita un reembolso? ¿La imagen muestra daños visibles?
choice	Un valor de tus opciones fijas, con probabilidades y confianza	¿A qué cola de soporte debe llegar esta solicitud?
score	Un promedio ponderado por probabilidad de índices de nivel ordenados, además de las probabilidades de nivel y la confianza	¿Qué urgencia tiene este problema en una escala definida?

Usa choice para una categoría y score para una escala ordenada. Una puntuación puede quedar entre dos niveles: si el modelo asigna probabilidad a niveles adyacentes, el número devuelto es su promedio ponderado y no necesariamente una de las etiquetas. Microsoft documenta la estructura de la solicitud, los tipos de respuesta y estas diferencias en Usa Azure OpenAI Decisions API.

La API se diferencia de un endpoint pensado para escribir una explicación de texto libre o producir un objeto que siga un esquema JSON arbitrario. La documentación de Microsoft recomienda usar salidas estructuradas con Responses API para objetos sujetos a un esquema, y function calling cuando un modelo deba solicitar una llamada a una herramienta con argumentos. Elige el endpoint según lo que tu aplicación necesite consumir.

Disponibilidad y requisitos previos

El anuncio de Foundry de Microsoft describe GPT-6 Luna como disponible de forma general en Microsoft Foundry, pero eso no significa que este endpoint esté disponible en todas las regiones de modelos. La página actual de Decisions API indica que gpt-6-luna es el único modelo compatible, describe un despliegue gradual en las regiones donde está disponible y excluye explícitamente East US 2. Enumera como requisitos una suscripción de Azure, un recurso de Azure OpenAI y una implementación de gpt-6-luna, además de documentar la autenticación mediante clave de API y Microsoft Entra ID. Verifica las opciones de endpoint e implementación para tu recurso antes de convertirlo en una dependencia obligatoria; trata la documentación del endpoint como la autoridad para esta API.

El parámetro model es el nombre de la implementación, no necesariamente el nombre canónico del modelo subyacente. En los ejemplos de Microsoft, la implementación se llama gpt-6-luna; si la tuya tiene otro nombre, envía ese nombre de implementación. Para los ejemplos de JavaScript documentados, Microsoft indica Node.js y openai versión 7.30.0 o posterior.

Un patrón práctico de integración

Trata la respuesta de la API como una entrada para una política de aplicación determinista, no como la política en sí. Asigna un nombre único a cada pregunta, define instrucciones acotadas y opciones distintas, incluye una opción de reserva como other y decide en el código de la aplicación qué ocurre ante un resultado con baja confianza o un rechazo.

Ejemplo sintético: clasificación de la cola de soporte

El ejemplo siguiente clasifica un ticket sintético. Solicita una categoría del problema y una señal de solicitud de reembolso. Los identificadores, las opciones, los umbrales y la salida de ejemplo son ilustrativos; no representan un registro real de cliente ni un resultado medido del modelo.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.AZURE_OPENAI_BASE_URL,
  apiKey: process.env.AZURE_OPENAI_API_KEY,
});

const decision = await client.decisions.create({
  // Set this to the name of your gpt-6-luna deployment.
  model: process.env.AZURE_OPENAI_DEPLOYMENT,
  input: "Synthetic ticket: The glass jar arrived cracked. Please replace it.",
  questions: [
    {
      type: "choice",
      name: "issue_type",
      instructions: "Choose the main support category supported by the message.",
      choices: [
        { value: "item_damage", description: "The delivered item is broken or damaged." },
        { value: "delivery", description: "The request is about shipping or arrival." },
        { value: "billing", description: "The request is about a charge or payment." },
        { value: "other", description: "The message does not fit another option." },
      ],
    },
    {
      type: "predicate",
      name: "replacement_requested",
      instructions: "Does the customer explicitly ask for a replacement?",
    },
  ],
});

const issue = decision.answers.find((answer) => answer.name === "issue_type");
const replacement = decision.answers.find((answer) => answer.name === "replacement_requested");

// Example policy only: ambiguous results go to a person; the model never issues a replacement.
const queue = issue?.type === "choice"
  && issue.choice !== "other"
  && issue.confidence >= 0.75
  ? issue.choice
  : "human_review";

const replacementSignal = replacement?.type === "predicate"
  ? replacement.probability
  : null;

console.log({ queue, replacementSignal, usage: decision.usage });

Para este ticket sintético, una respuesta ilustrativa podría ser issue_type = item_damage con una confianza superior al umbral de ejemplo y replacement_requested = true con una probabilidad alta para el predicado. Esa salida puede sugerir la cola de daños y ayudar a una persona a priorizar la revisión. No demuestra que el frasco estuviera dañado, establece la elegibilidad ni autoriza un reemplazo. Tu aplicación debe validar el pedido y la política mediante sus sistemas de confianza, gestionar las respuestas ausentes o rechazadas y exigir la confirmación correspondiente y la aprobación humana antes de una acción con consecuencias.

El umbral 0.75 es un marcador de posición, no una recomendación de Microsoft. Calibra los umbrales con ejemplos representativos y revisados, y mide tanto los falsos positivos como los falsos negativos. Prueba también un mensaje fuera de alcance, intenciones combinadas, evidencia ausente, un tipo de respuesta no reconocido, un rechazo y un fallo de la API. Dirige la incertidumbre a una ruta de reserva segura en lugar de seleccionar la primera opción sin indicarlo.

Para el ejemplo de código, establece AZURE_OPENAI_BASE_URL en https://<resource-name>.openai.azure.com/openai/v1/, AZURE_OPENAI_DEPLOYMENT en el nombre de tu implementación de gpt-6-luna y AZURE_OPENAI_API_KEY en el almacenamiento de secretos del servidor. No expongas una clave de Azure OpenAI en código del navegador. La autenticación de Entra ID también es compatible si encaja mejor con el diseño de identidad y gestión de secretos de tu aplicación.

Entrada, imágenes y gestión de respuestas

Puedes enviar texto como una cadena o como mensajes de usuario. Un mensaje también puede combinar partes input_text y input_image. La página actual de Learn enumera compatibilidad con PNG, JPG, WebP y GIF, hasta 128 imágenes por solicitud y un tamaño máximo combinado de imagen de 32 MB. Mantén la gestión de imágenes dentro del alcance solo cuando la evidencia visual sea necesaria y prueba con ejemplos que reflejen la iluminación, los ángulos y la calidad de imagen de tu flujo real.

Lee las respuestas por name y comprueba el type de cada respuesta antes de acceder a campos como choice, confidence o probability. La API puede devolver un refusal; trátalo como un resultado distinto. Registra el identificador de solicitud y el uso de tokens necesarios para las operaciones, pero evita conservar la entrada sin procesar o la salida sensible durante más tiempo del que permita tu política.

Privacidad, gestión de datos y precios

La guía de datos, privacidad y seguridad de Foundry Models vendidos por Azure de Microsoft indica que los prompts y las finalizaciones de los modelos vendidos por Azure no están disponibles para otros clientes y que los proveedores de modelos no los utilizan para mejorar modelos o servicios sin permiso o instrucciones. La misma guía describe el procesamiento del servicio para operar, supervisar abusos y aplicar la seguridad de contenido. La geografía del procesamiento depende del tipo de implementación: Standard permanece dentro de la geografía especificada, mientras que las implementaciones Global y Data Zone pueden procesar datos en la geografía o zona aplicable. Las funciones con estado también pueden conservar datos según su configuración. Aplica tus propios requisitos de clasificación, retención, acceso y región de datos al recurso y la implementación seleccionados; esto no es una garantía general de que no exista procesamiento ni supervisión.

Las respuestas de Decisions incluyen el uso de tokens, pero el recuento de tokens no es una cotización. La página de Decisions API remite a la página de precios de Azure OpenAI en lugar de publicar una tarifa específica del endpoint. El anuncio de precios de Foundry del 22 de septiembre de Microsoft enumera para GPT-6 Luna Standard de contexto corto unas tarifas de USD $0.10 de entrada y $0.50 de salida por millón de tokens para Global, y $0.12 de entrada y $0.60 de salida para EU Data Zone. Las tarifas de contexto largo, tokens en caché, otras implementaciones, regiones y contratos son distintas. Son tarifas del modelo, no una cotización específica del endpoint ni una estimación del coste total de la tarea. Comprueba la página de precios vigente, la implementación seleccionada, la región y el acuerdo antes de elaborar un presupuesto.

Errores comunes que debes evitar

• Tratar una probabilidad de predicado o una confianza de elección como una garantía calibrada.
• Usar score cuando la aplicación necesita una categoría fija, o interpretar una puntuación fraccionaria como un nivel seleccionado.
• Omitir una opción de reserva para entradas que quedan fuera de la lista de categorías.
• Usar el resultado del modelo como decisión de autorización para reembolsos, elegibilidad, cambios de cuenta u otras acciones con consecuencias.
• Enviar un nombre de modelo cuando la API espera el nombre de tu implementación.
• Suponer que el endpoint está disponible en todas las regiones de Azure OpenAI o que un modelo listado en otro lugar es compatible con este endpoint.
• Suponer que la descripción del tratamiento de datos del modelo elimina tus responsabilidades de retención, control de acceso y cumplimiento.
• Tratar las tarifas de tokens publicadas como una cotización para una solicitud, implementación o flujo de trabajo completo concretos.

Próximos pasos

Comprueba la disponibilidad regional e implementa el modelo compatible antes de escribir código de aplicación. Empieza con entradas sintéticas y un tipo de pregunta, captura la respuesta tipada y el uso, y crea un tratamiento determinista para la baja confianza, el rechazo, las respuestas desconocidas y los errores del servicio. Amplía el alcance solo después de que un conjunto de evaluación revisado demuestre que tus umbrales y tu ruta de reserva son adecuados.

Conclusión

Azure OpenAI Decisions API resulta útil cuando una aplicación necesita un predicado, una elección entre valores conocidos o una puntuación sobre niveles ordenados en lugar de prosa generada. Sus salidas tipadas pueden facilitar la integración del enrutamiento y la priorización, pero siguen siendo estimaciones del modelo. Verifica la disponibilidad regional vigente, protege todo el flujo de datos, valida las salidas con código determinista y mantén las decisiones con consecuencias detrás de la política de tu aplicación y la revisión humana.

Fuentes

• Usa Azure OpenAI Decisions API
• Datos, privacidad y seguridad de Foundry Models vendidos por Azure
• Precios de Azure OpenAI
• GPT-6 Astra, Sol y Luna en Microsoft Foundry

Lecturas relacionadas

• Actualizaciones de agentes de Microsoft Foundry
• Analizadores precompilados de Azure Content Understanding

Nota editorial: Esta guía asistida por IA usa ejemplos sintéticos. No se accedió ni se probó ningún recurso de Azure, endpoint o dato de cliente.