Fråga modeller med TypeSafe System One API

TypeSafes System One API är ett format för förfrågningar och svar för att utvärdera applikationstillstånd mot typade frågor och returnera strukturerade svar. På Azure Databricks skickar du System One-förfrågningar via Unity Gateway till en Unity Catalog-modelltjänst som hostas av Databricks, inte till en TypeSafe-modell. Till exempel är OpenJev (Qwen3.5 4B) en öppen modell baserad på Qwen3.5 som stöder System One API.

Använd System One API när en applikation behöver ett kompakt, strukturerat beslut istället för genererad prosa. Det kan vara en bra lösning när svarstiden är viktig, till exempel för att avgöra om en begäran behöver eskaleras, välja en routingetikett eller bedöma den mot en bedömningsmatris. Svarstiden beror på modelltjänsten och förfrågningsbelastningen.

För beslut om tabellrader i SQL, se funktionen ai_decide.

Krav

  • En arbetsyta aktiverad för Unity Catalog och Unity Gateway.
  • En Unity Catalog-modelltjänst som använder en System One-kompatibel modell. Exemplet använder openjev-qwen35-4b modelltjänsten, vars fullt kvalificerade namn är system.ai.openjev-qwen35-4b.
  • Behörighet att köra modelltjänsten.

System One-rutten kräver en Unity Catalog-modelltjänst. Den stöder inte en modellleverantörstjänst eller en serveringsslutpunkt som inte använder Unity Catalog.

Skicka en fråga till en modelltjänst

Begärandetexten innehåller namnet på den fullt kvalificerade modelltjänsten, tillståndet som ska utvärderas och en eller flera namngivna frågor. Varje fråga använder en av typerna noul, choice eller score.

Följande begäran innehåller en fråga av varje typ:

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

Använd det fullt kvalificerade Unity Catalog-modelltjänstenamnet system.ai.openjev-qwen35-4b, , i förfrågans model fält.

Fält för begäran

Fält Type Description
model String Det fullständigt kvalificerade namnet på Unity Catalog-modelltjänsten, såsom system.ai.openjev-qwen35-4b.
state Sträng, objekt eller array Innehållet som ska utvärderas. Använd en sträng för text eller strukturerad data för poster, konversationer eller applikationstillstånd.
questions Object En icke-tom mappning från fråge-ID:n till frågedefinitioner. Svaret använder samma ID:n i answers-objektet.

Varje fråga har ett type, valfritt instructions, och typspecifik criteria:

Noul-frågor

En noulfråga returnerar sannolikheten att svaret är ja. Det valfria criteria objektet beskriver vad true och false betyder. Ge antingen instructions eller en beskrivning för true eller false. Svaret innehåller ett noul tal från 0 (nej) till 1 (ja).

Valfrågor

I en choice fråga väljs ett alternativ från criteria objektet. Varje alternativ motsvarar en beskrivning eller null när ingen ytterligare beskrivning behövs. Definiera 1 till 255 inställningar. Svaret innehåller det valda choice, en sannolikhet för varje alternativ och ett confidence värde.

Poängfrågor

En score fråga bedömer tillståndet mot en ordnad criteria array. Svaret innehåller en sannolikhetsviktad score, en legend som mappar nivåindex till kriterierna, sannolikheter för varje nivå och ett confidence värde. Definiera 1 till 10 nivåer.

Svarsformat

Svaret innehåller modellidentifieraren och ett svar för varje fråga i answers. Tokenanvändning förekommer i usage, med input_tokens och 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
  }
}

Detta svar baseras på begäran ovan, med avrundade numeriska värden. Svar, sannolikheter, konfidensvärden, tokenantal och den returnerade modellidentifieraren varierar beroende på förfrågan och backend. Svarsvärdet model identifierar modellen som rapporteras av backend och kan skilja sig från förfrågans fullt kvalificerade modelltjänstenamn.

Förfrågningsfel

För valideringsfel för förfrågningar returnerar rutten HTTP 422 med en detail array som beskriver den ogiltiga förfrågan.

Ytterligare resurser

  • Uppdaterades senast