Consultar modelos con la API de TypeSafe System One

La API System One de TypeSafe es un formato de solicitud y respuesta para evaluar el estado de la aplicación frente a preguntas tipadas y devolver respuestas estructuradas. En Azure Databricks, envías las solicitudes de System One a través de Unity Gateway a un servicio modelo de Unity Catalog alojado por Databricks, no a un modelo TypeSafe. Por ejemplo, OpenJev (Qwen3.5 4B) es un modelo abierto basado en Qwen3.5 que soporta la API System One.

Utiliza la API de System One cuando una aplicación necesita una decisión compacta y estructurada en lugar de prosa generada. Puede ser una buena opción cuando el tiempo de respuesta importa, por ejemplo para decidir si una solicitud debe escalarse, elegir una etiqueta de enrutamiento o puntuarla con una rúbrica. El tiempo de respuesta depende del servicio del modelo y de la carga de solicitudes.

Para las decisiones sobre filas de tablas en SQL, consulte la función ai_decide.

Requisitos

  • Un espacio de trabajo habilitado para Unity Catalog y Unity Gateway.
  • Un servicio de modelo de Unity Catalog respaldado por un modelo compatible con System One. El ejemplo utiliza el openjev-qwen35-4b servicio modelo, cuyo nombre totalmente cualificado es system.ai.openjev-qwen35-4b.
  • Permiso para ejecutar el servicio de modelo.

La ruta System One requiere un servicio de modelos de Unity Catalog. No soporta un servicio de proveedor de modelos ni un punto final que no sea Unity Catalog.

Consulta de un servicio modelo

El cuerpo de la solicitud contiene el nombre del servicio de modelo completamente cualificado, el estado a evaluar y una o más preguntas con nombre. Cada pregunta utiliza uno de los tipos noul, choice o score.

La siguiente solicitud incluye una pregunta de cada tipo:

curl \
-u token:$DATABRICKS_TOKEN \
-X POST \
-H "Content-Type: application/json" \
-d '{
  "model": "system.ai.openjev-qwen35-4b",
  "state": {
    "message": "My card was charged twice for the same order and I need a refund.",
    "channel": "support"
  },
  "questions": {
    "is_billing": {
      "type": "noul",
      "instructions": "Is this a billing-related request?",
      "criteria": {
        "true": "The message concerns a charge, payment, invoice, or refund.",
        "false": "The message does not concern billing."
      }
    },
    "intent": {
      "type": "choice",
      "instructions": "Which intent best matches the message?",
      "criteria": {
        "refund": "The customer requests a refund.",
        "duplicate_charge": "The customer reports being charged more than once.",
        "other": "Another request."
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is the request?",
      "criteria": [
        "Can wait",
        "Needs attention soon",
        "Urgent"
      ]
    }
  }
}' \
https://<workspace_host>/ai-gateway/typesafe/v1/systemone

Utilice el nombre completo del servicio de modelo de Unity Catalog, system.ai.openjev-qwen35-4b, en el campo model de la solicitud.

Campos de solicitud

Campo Tipo Description
model String El nombre completo del servicio de modelo de Unity Catalog, como system.ai.openjev-qwen35-4b.
state Cadena, objeto o array El contenido para evaluar. Use una cadena para texto o datos estructurados para registros, conversaciones o estado de la aplicación.
questions Object Un mapa no vacío de IDs de preguntas a definiciones de preguntas. La respuesta utiliza los mismos IDs en el answers objeto.

Cada pregunta tiene un type, un instructions opcional y un criteria específico del tipo:

Preguntas noul

Una noul pregunta devuelve la probabilidad de que la respuesta sea sí. El objeto opcional criteria describe qué significan true y false. Proporciona instructions o una descripción para true o false. La respuesta contiene un noul número del 0 (no) al 1 (sí).

Preguntas de opción

Una pregunta choice permite seleccionar una opción del objeto criteria. Cada opción se asigna a una descripción o a null cuando no se necesita ninguna descripción adicional. Defina de 1 a 255 opciones. La respuesta contiene el choice seleccionado, una probabilidad para cada opción y un valor confidence.

Puntuar preguntas

Una pregunta score califica el estado respecto a una matriz criteria ordenada. La respuesta contiene una score ponderada por probabilidad, una legend que asigna los índices de nivel a los criterios, probabilidades para cada nivel y un valor de confidence. Defina de 1 a 10 niveles.

Formato de respuesta

La respuesta contiene el identificador del modelo y una respuesta para cada pregunta en answers. El uso de tokens aparece en usage, con input_tokens y output_tokens:

{
  "model": "<returned-model-id>",
  "answers": {
    "is_billing": {
      "type": "noul",
      "noul": 0.98
    },
    "intent": {
      "type": "choice",
      "choice": "duplicate_charge",
      "confidence": 0.965,
      "probabilities": {
        "refund": 0.023,
        "duplicate_charge": 0.977,
        "other": 0.0002
      }
    },
    "urgency": {
      "type": "score",
      "score": 1.902,
      "confidence": 0.852,
      "legend": {
        "0": "Can wait",
        "1": "Needs attention soon",
        "2": "Urgent"
      },
      "probabilities": {
        "0": 0.0069,
        "1": 0.0845,
        "2": 0.9086
      }
    }
  },
  "usage": {
    "input_tokens": 238,
    "output_tokens": 0
  }
}

Esta respuesta se basa en la petición anterior, con los valores numéricos redondeados. Las respuestas, probabilidades, valores de confianza, conteos de tokens y el identificador del modelo devuelto varían según la solicitud y el backend. El valor de respuesta model identifica el modelo reportado por el backend y puede diferir del nombre de servicio modelo totalmente cualificado de la solicitud.

Errores de solicitud

Para los errores de validación de la solicitud, la ruta devuelve HTTP 422 con un detail array que describe la solicitud inválida.

Recursos adicionales

  • Se actualizó por última vez el