Interroga i modelli con l'API TypeSafe System One

L'API System One di TypeSafe valuta lo stato dell'applicazione rispetto a domande tipizzate e restituisce risposte strutturate. In Azure Databricks, invia richieste a un servizio di modello abilitato per System One tramite Unity Gateway. La rotta Databricks utilizza il formato di richiesta e risposta System One.

Usa l'API System One quando un'applicazione ha bisogno di una decisione compatta e strutturata invece di prosa generata. Può essere una buona scelta quando il tempo di risposta è importante, ad esempio per decidere se una richiesta deve essere escalata, scegliere un'etichetta di routing o valutarla in base a una griglia di valutazione. Il tempo di risposta dipende dal servizio del modello e dal carico delle richieste.

Per decisioni sulle righe di tabella in SQL, vedi la ai_decide funzione.

Requisiti

  • Un spazio di lavoro abilitato per Unity Catalog e Unity Gateway.
  • Un servizio modello Unity Catalog supportato da un modello compatibile con System One. L'esempio utilizza il servizio openjev-qwen35-4b model, il cui nome pienamente qualificato è system.ai.openjev-qwen35-4b.
  • Permesso di eseguire il servizio del modello.

La route System One richiede un servizio modello Unity Catalog. Non supporta un servizio provider di modelli né un endpoint di serving esterno a Unity Catalog.

Consulta un servizio modello

Il corpo della richiesta contiene il nome del servizio modello pienamente qualificato, lo stato da valutare e una o più domande nominate. Ogni domanda utilizza uno dei tipi noul, choice o score.

La seguente richiesta include una domanda per ogni 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

Usa il nome del servizio modello Unity Catalog, completamente qualificato, system.ai.openjev-qwen35-4b, nel campo della model richiesta.

Campi della richiesta

Campo Type Description
model Stringa Il nome del servizio modello Unity Catalog, completamente qualificato, come system.ai.openjev-qwen35-4b.
state Stringa, oggetto o array Il contenuto da valutare. Usa una stringa per il testo o dati strutturati per record, conversazioni o stato dell'applicazione.
questions Object Una mappa non vuota degli ID delle domande alle definizioni delle domande. La risposta utilizza gli stessi ID nell'oggetto answers .

Ogni domanda ha un type, opzionale instructions, e un criteria specifico per tipo:

Domande Noul

Una noul domanda restituisce la probabilità che la risposta sia sì. L'oggetto opzionale criteria descrive cosa significano false e true. Fornisci instructions oppure una descrizione per true o false. La risposta contiene un noul numero da 0 (no) a 1 (sì).

Domande a scelta

Una domanda choice seleziona un'opzione dall'oggetto criteria. Ogni opzione si mappa a una descrizione o a null quando non è necessaria una descrizione aggiuntiva. Definisci opzioni da 1 a 255. La risposta contiene l'choice selezionato, una probabilità per ogni opzione e un valore confidence.

Assegna un punteggio alle domande

Una score domanda valuta lo stato rispetto a un criteria array ordinato. La risposta contiene un elemento score ponderato in base alla probabilità, un legend che associa gli indici dei livelli ai criteri, le probabilità per ciascun livello e un valore confidence. Definisci livelli da 1 a 10.

Formato della risposta

La risposta contiene l'identificatore del modello e una risposta per ogni domanda in answers. L'uso del token appare in usage, con input_tokens e 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
  }
}

Questa risposta si basa sulla richiesta sopra, con i valori numerici arrotondati. Risposte, probabilità, valori di confidenza, conteggi dei token e l'identificatore del modello restituito variano in base alla richiesta e al backend. Il valore di risposta model identifica il modello segnalato dal backend e può differire dal nome del servizio modello completamente qualificato della richiesta.

Errori di richiesta

Per gli errori di validazione delle richieste, la route restituisce HTTP 422 con un detail array che descrive la richiesta non valida.

Risorse aggiuntive

  • Last updated on