Consultar modelos com a API TypeSafe System One

A API System One do TypeSafe é um formato de pedido e resposta para avaliar o estado da aplicação em relação a perguntas tipadas e devolver respostas estruturadas. No Azure Databricks, você envia os pedidos do System One através do Unity Gateway para um serviço de modelo do Unity Catalog alojado pela Databricks, e não para um modelo TypeSafe. Por exemplo, o OpenJev (Qwen3.5 4B) é um modelo aberto baseado no Qwen3.5 que suporta a API System One.

Use a API do System One quando uma aplicação precisa de uma decisão compacta e estruturada em vez de prosa gerada. Pode ser uma boa opção quando o tempo de resposta é importante, por exemplo, para decidir se um pedido precisa de encaminhamento para nível superior, escolher um rótulo de encaminhamento ou pontuá-lo com base numa rubrica. O tempo de resposta depende do serviço do modelo e da carga de pedidos.

Para decisões sobre linhas de tabela em SQL, veja a ai_decide função.

Requirements

• Um espaço de trabalho habilitado para o Unity Catalog e o Unity Gateway.
• Um serviço de modelo do Unity Catalog apoiado por um modelo compatível com o System One. O exemplo utiliza o openjev-qwen35-4b serviço modelo, cujo nome totalmente qualificado é system.ai.openjev-qwen35-4b.
• Permissão para executar o serviço de modelos.

A rota System One requer um serviço de modelo do Unity Catalog. Não suporta um serviço de fornecedor de modelos nem um endpoint de serving que não seja do Unity Catalog.

Consultar um serviço modelo

O corpo do pedido contém o nome totalmente qualificado do serviço de modelo, o estado a avaliar e uma ou mais perguntas nomeadas. Cada pergunta utiliza um dos tipos noul, choice ou score.

O pedido seguinte inclui uma pergunta 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

Utilize o nome totalmente qualificado do serviço de modelo do Unity Catalog, system.ai.openjev-qwen35-4b, no campo model do pedido.

Campos de solicitação

Cada pergunta tem um type, opcional instructions, e criteria específico do tipo:

Noul perguntas

Uma noul pergunta devolve a probabilidade de a resposta ser sim. O objeto opcional criteria descreve o que true e false significam. Forneça instructions ou uma descrição para true ou false. A resposta contém um noul número de 0 (não) a 1 (sim).

Perguntas de escolha múltipla

Uma choice pergunta permite selecionar uma opção do criteria objeto. Cada opção corresponde a uma descrição ou a null quando não é necessária uma descrição adicional. Defina de 1 a 255 opções. A resposta contém a opção selecionada choice, uma probabilidade para cada opção e um valor confidence.

Pontuar perguntas

Uma pergunta avalia score o estado em relação a um array ordenado criteria. A resposta contém um resultado ponderado pela probabilidade score, um mapeamento legend que mapeia índices de nível para os critérios, probabilidades para cada nível e um valor confidence. Defina níveis de 1 a 10.

Formato da resposta

A resposta contém o identificador do modelo e uma resposta para cada pergunta em answers. A utilização de tokens aparece em usage, com 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
  }
}

Esta resposta baseia-se no pedido acima, com os valores numéricos arredondados. Respostas, probabilidades, valores de confiança, contagens de tokens e o identificador do modelo devolvido variam consoante o pedido e o backend. O valor da resposta model identifica o modelo reportado pelo backend e pode diferir do nome totalmente qualificado do serviço do modelo do pedido.

Erros de requisição

Para erros de validação do pedido, a rota devolve HTTP 422 com um array detail que descreve os erros no pedido inválido.

Recursos adicionais

• APIs nativas de fornecedores
• Serviços de modelo de consulta
• Referência da API TypeSafe