Consultar modelos com a API TypeSafe System One

A API System One do TypeSafe avalia o estado da aplicação com base em perguntas tipadas e retorna respostas estruturadas. No Azure Databricks, envie requisições para um serviço de modelo habilitado pelo System One via Unity Gateway. A rota Databricks utiliza o formato de solicitação e resposta System One.

Use a API System One quando uma aplicação precisar de uma decisão compacta e estruturada, em vez de prosa gerada. Pode ser uma boa opção quando o tempo de resposta importa, por exemplo, para decidir se uma solicitação precisa ser escalonada, escolher um rótulo de roteamento ou pontuá-la em uma rubrica. O tempo de resposta depende do serviço do modelo e da carga de solicitações.

Para decisões em linhas da tabela no SQL, consulte a ai_decide função.

Requisitos

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

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

Consultar um serviço modelo

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

O pedido a seguir 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

Use o nome totalmente qualificado do serviço de modelo do Unity Catalog, system.ai.openjev-qwen35-4b, no campo model da solicitação.

Campos de solicitação

Field Tipo Description
model String O nome do serviço modelo totalmente qualificado do Unity Catalog, como system.ai.openjev-qwen35-4b.
state String, objeto ou array O conteúdo para avaliar. Use uma string para texto ou dados estruturados para registros, conversas ou estado da aplicação.
questions Object Um mapa não vazio de IDs de perguntas para definições de perguntas. A resposta usa os mesmos IDs no answers objeto.

Cada questão tem um type, opcional instructions, e criteria específico do tipo:

Noul perguntas

Uma noul pergunta retorna a probabilidade de que a resposta seja sim. O objeto opcional criteria descreve o que false e true 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 múltipla escolha

Uma choice pergunta seleciona 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.

Avaliar perguntas

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

Formato da resposta

A resposta contém o identificador do modelo e uma resposta para cada pergunta em answers. O uso 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
  }
}

Essa resposta é baseada no pedido acima, com valores numéricos arredondados. Respostas, probabilidades, valores de confiança, contagem de tokens e o identificador do modelo retornado variam conforme a requisição e o backend. O valor de resposta model identifica o modelo relatado pelo backend e pode diferir do nome totalmente qualificado do serviço de modelo da solicitação.

Erros de solicitação

Para erros de validação de requisição, a rota retorna HTTP 422 com um array detail que descreve a requisição inválida.

Recursos adicionais

  • Last updated on