Interrogez les modèles avec l’API TypeSafe System One

L’API System One de TypeSafe est un format de requête et de réponse permettant d’évaluer l’état de l’application par rapport aux questions typées et de renvoyer des réponses structurées. Sur Azure Databricks, vous envoyez des requêtes System One via Unity Gateway vers un service modèle Unity Catalog. Le modèle derrière le service peut être hébergé par Databricks ou par TypeSafe AI, Inc. :

  • OpenJev (Qwen3.5 4B) est un modèle ouvert basé sur Qwen3.5 et hébergé par Databricks.

  • TypeSafe AI Jev 1.14.0 est hébergé par TypeSafe AI, Inc. et assuré via Unity Gateway. Pour l’utiliser, un administrateur de compte doit activer la version préliminaire TypeSafe AI Models dans la console du compte. Les conditions de TypeSafe AI régissent son utilisation.

    Voir ADI Services.

Utilisez l’API System One lorsqu’une application a besoin d’une décision compacte et structurée au lieu d’une prose générée. Cela peut être un bon choix lorsque le temps de réponse est important, par exemple pour décider si une requête doit être escaladée, choisir une étiquette de routage ou la noter selon une grille d’évaluation. Le temps de réponse dépend du service de modèle et de la charge des requêtes.

Pour les décisions sur les lignes de table en SQL, voir la fonction ai_decide.

Requirements

  • Un espace de travail activé pour Unity Catalog et Unity Gateway.
  • Un service de modèle Unity Catalog soutenu par un modèle compatible System One. L’exemple utilise le service du modèle openjev-qwen35-4b, dont le nom entièrement qualifié est system.ai.openjev-qwen35-4b.
  • Autorisation d’exécuter le service de modèle.
  • Pour utiliser TypeSafe AI Jev 1.14.0, un administrateur de compte doit activer la fonctionnalité en préversion TypeSafe AI Models dans la console de compte. Consultez Gérer les versions préliminaires du compte.

La route System One nécessite un service modèle Unity Catalog. Il ne prend pas en charge de service de fournisseur de modèles ni de point de terminaison de mise en service ne faisant pas partie du catalogue Unity.

Requête d’un service modèle

Le corps de la requête contient le nom complet du service de modèle, l’état à évaluer, ainsi qu’une ou plusieurs questions nommées. Chaque question utilise l’un des types noul, choice ou score.

La demande suivante comprend une question de chaque type :

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

Utilisez le nom de service modèle entièrement qualifié du catalogue Unity, system.ai.openjev-qwen35-4b, dans le champ model de la requête.

Champs de requête

Champ Type Description
model String Le nom de service modèle Unity Catalog, entièrement qualifié, tel que system.ai.openjev-qwen35-4b.
state Chaîne, objet ou tableau Le contenu à évaluer. Utilisez une chaîne pour le texte ou des données structurées pour les enregistrements, conversations ou l’état de l’application.
questions Object Une table de correspondance non vide des identifiants des questions vers les définitions des questions. La réponse utilise les mêmes identifiants dans l’objet answers .

Chaque question a un type, une option instructions et des criteria propres à chaque type :

Questions Noul

Une noul question renvoie la probabilité que la réponse soit oui. L’objet optionnel criteria décrit ce que true et false signifient. Fournir soit instructions, soit une description pour true ou false. La réponse contient un noul nombre allant de 0 (non) à 1 (oui).

Questions Choix

Une question choice permet de sélectionner une option de l’objet criteria. Chaque option correspond à une description ou à null lorsqu’aucune description supplémentaire n’est nécessaire. Définissez de 1 à 255 options. La réponse contient l’élément choice sélectionné, une probabilité pour chaque option, et une valeur confidence.

Questions Score

Une question score évalue l’état par rapport à un tableau criteria ordonné. La réponse contient un score pondéré par probabilité, un legend qui associe les indices de niveau aux critères, les probabilités pour chaque niveau et une valeur confidence. Définissez les niveaux de 1 à 10.

Format de réponse

La réponse contient l’identifiant du modèle et une réponse pour chaque question dans answers. L’utilisation des jetons apparaît dans usage, avec input_tokens et 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
  }
}

Cette réponse est basée sur la demande ci-dessus, avec des valeurs numériques arrondies. Les réponses, probabilités, valeurs de confiance, nombre de jetons et identifiant de modèle retourné varient selon la requête et le backend. La valeur de réponse model identifie le modèle rapporté par le backend et peut différer du nom de service modèle entièrement qualifié de la requête.

Erreurs de requête

Pour les erreurs de validation des requêtes, le routage retourne HTTP 422 avec un tableau detail qui décrit l’erreur de requête non valable.

Ressources additionnelles

  • Dernière mise à jour :