Decisions está em Beta, e seu contrato de requisição e resposta corresponde à TypeSafe Classify API.
- Responde por meio de APIs nativas de decisão ou de saídas estruturadas em modelos de chat compatíveis: consulte Modelos compatíveis.
- Ainda não aplica plugins de PII, guardrails nem evaluators: consulte Aplicação durante a Beta.
- Requer uma chave de API com a permissão
classify. - Disponível apenas pela API e pelo SDK.
Visão geral
Decisions responde a perguntas tipadas sobre um conteúdo em uma única chamada. Envie o conteúdo comostate e uma ou mais questions nomeadas para POST /decisions na URL base do AI Gateway, https://router.toqan.ai/eu/v3/router.
A resposta retorna uma resposta estruturada por pergunta, portanto nada precisa ser extraído de texto livre. Uma resposta choice ou score também traz as probabilidades que a fundamentam e uma confiança para a opção ou o nível selecionado.
Uma pergunta combina instructions em linguagem natural com um type que define o formato da resposta e criteria que definem a rubrica:
state não se limita a texto: um objeto ou array é serializado como JSON antes da classificação, de modo que a mesma chamada pode avaliar uma mensagem de cliente, um payload de ferramenta ou um registro inteiro.
Várias perguntas podem ser feitas de uma só vez, cada uma com sua própria rubrica, de modo que uma requisição custa uma única ida e volta em vez de uma chamada por pergunta. Consulte Tipos de pergunta para ver os criteria esperados por cada tipo.
A requisição é rastreada, precificada e tem limite de taxa como qualquer outro tráfego do gateway. Consulte Aplicação durante a Beta para saber o que se aplica atualmente.
Casos de uso
- Triagem e roteamento. Pergunte com
noulse a mensagem relata um problema e comchoicequal é o tópico ou produto; em seguida, roteie com base nos rótulos e escale as linhas com baixa confiança. - Criação de dados rotulados. Transforme uma rubrica em uma pergunta
choicepara rotular um corpus para Evaluators ou Datasets e useprobabilitiespara escolher as linhas que merecem revisão humana. - Pontuação de feedback aberto. Use
scoreem respostas de pesquisas, transcrições de suporte ou textos de avaliações para obter uma leitura ordinal sem escrever um prompt de pontuação. - Filtro antes de trabalhos caros. Use uma pergunta
noulno modelo nativo, cujos tokens de saída são gratuitos, como verificação prévia, e envie apenas as requisições aprovadas para um modelo maior. - Enriquecimento de registros estruturados. Passe um registro como
statee faça uma pergunta por campo a ser derivado, em vez de criar um prompt por campo. - Comparação de modelos com uma única rubrica. Faça as mesmas perguntas a
typesafe/jev-lateste a um modelo de chat para ver onde divergem. Limites ajustados em um não se transferem para o outro, então compare as respostas em vez das probabilidades brutas.
Modelos compatíveis
Esta lista inclui ofertas e versões ativas do catálogo de modelos. Modelos nativos usam a API de decisão do provedor; modelos emulados respondem por meio de saídas estruturadas ou de uma chamada de ferramenta forçada. Consulte Preços e limites para detalhes de cobrança.
Modelos de chat retornam os mesmos campos com suas próprias probabilidades, que expressam a estimativa do modelo e não são calibradas; portanto, limites ajustados em um modelo não se transferem para outro.
Na classificação emulada, o raciocínio é definido no mínimo permitido pelo modelo.
O OpenAI Decisions aceita texto, arrays de mensagens e histórico de funções ou ferramentas personalizadas em
state. Mensagens de usuário aceitam partes input_text, input_image e input_json. As imagens podem usar data URLs base64 inline ou URLs HTTP(S) públicas. Mensagens de system e developer aceitam texto; mensagens de assistant aceitam texto de saída e recusas. IDs de arquivo, áudio, referências de itens e partes de conteúdo soltas não são compatíveis. Outros objetos e arrays são serializados como texto. A OpenAI pode retornar {"type": "refusal"} na chave de uma pergunta individual; trate as recusas antes de ler os campos pontuados.
Qualquer outro modelo retorna 400.
Início rápido
Requisição
Cada pergunta tem um
type e instructions, que podem ser uma string, um objeto ou um array. O OpenAI nativo preserva arrays de partes input_text, input_image e input_json, de modo que cada pergunta pode incluir suas próprias imagens. O limite de 128 imagens abrange a entrada compartilhada e as instruções das perguntas em conjunto. O formato de criteria depende do tipo de pergunta.
Tipos de pergunta
noul
Retorna a probabilidade de que a afirmação em instructions seja verdadeira para state. A probabilidade é calibrada em typesafe/jev-latest e informada pelo próprio modelo nos modelos de chat.
O objeto opcional criteria pode definir o que conta como true e false.
JSON
choice
Seleciona uma opção de uma rubrica. O objeto obrigatório criteria mapeia o nome de cada opção para uma descrição. Defina uma descrição como null quando o nome da opção for suficiente para que o modelo a interprete.
JSON
score
Retorna uma posição em uma escala ordenada. Defina criteria como um array com pelo menos duas descrições de nível, ordenadas do mais baixo para o mais alto. O índice da resposta se refere a esse array.
JSON
Resposta
Provedores nativos retornam seus própriosconfidence e score. A classificação emulada usa uma única chamada de saída estruturada. O OpenAI Decisions retorna uma pontuação ponderada por probabilidade e preserva sua própria confiança. Os campos abaixo descrevem essas diferenças entre provedores.
JSON
A resposta inclui
telemetry opcional. Leia x-orq-trace-id e x-orq-trace-span-id dos cabeçalhos da resposta quando SDKs ou implantações mais antigos o omitirem. O handler os define assim que a requisição é rastreada, portanto uma requisição rejeitada antes desse ponto não traz nenhum dos dois: autenticação e autorização (401, e 403 para a falta da permissão classify ou para um modelo que não está habilitado no workspace nem compartilhado com o projeto), limites de plano e de orçamento (429) e validação do corpo da requisição (o 400 para um corpo malformado, o 422 para uma requisição inválida). Tudo o que for rejeitado após o rastreamento os traz, incluindo o 400 para um modelo que não oferece suporte a classify. O próprio objeto telemetry é opcional e retornado por builds mais recentes do que algumas implantações executam, então recorra aos cabeçalhos quando ele estiver ausente.
Modelos de chat emulados retornam os mesmos campos pontuados, mas os números não têm o mesmo significado: suas probabilidades são estimativas do próprio modelo e não são calibradas, e seu confidence é simplesmente o maior desses valores. Compare choice e score entre modelos, não confidence.
Consulte a referência da API Create decisions para ver o esquema completo de requisição e resposta, incluindo os campos aceitos além dos listados acima.
Fallbacks, novas tentativas, timeouts, cache e identidade
Use estas opções em/decisions:
retry.count define as novas tentativas após a primeira, de 0 a 5. Defina 0 para fazer exatamente uma chamada por modelo.
- Omitir
retrymantém o padrão do gateway de duas novas tentativas nos códigos de status padrão. - As novas tentativas são acionadas para os códigos em
on_codes, com408sempre incluído. O gateway respeitaRetry-Aftere aguarda um segundo quando o cabeçalho está ausente. - Depois que as novas tentativas se esgotam, o gateway tenta o próximo fallback, até 10 por requisição.
- A resposta informa o modelo bem-sucedido e seus custos. Um fallback de chat paga as tarifas de entrada e saída do modelo de chat.
timeout.call_timeout se aplica separadamente a cada chamada de modelo, incluindo modelos nativos e emulados. Cada nova tentativa e fallback recebe um novo timeout. Se todos os modelos excederem o tempo limite, a requisição retorna 408. Essas opções também se aplicam a /classify.
Em requisições com imagens inline, todo fallback deve oferecer suporte à classificação de imagens OpenAI nativa; cadeias incompatíveis são rejeitadas com 422 antes de uma chamada ao provedor.
Um fallback inacessível interrompe o restante da cadeia de fallbacks. Chaves de sessão devem permitir todos os modelos solicitados conforme sua política de factory.
Cache
O cache de prompt nativo da OpenAI reutilizastate compartilhado correspondente entre requisições, mesmo quando as perguntas mudam. Ele é habilitado implicitamente por padrão para prefixos de pelo menos 1.024 tokens. Defina prompt_cache_key para particionar a reutilização. Adicione prompt_cache_breakpoint: {"mode": "explicit"} a partes de texto ou imagem compartilhadas para marcar limites; defina prompt_cache_options.mode como explicit para usar apenas os limites marcados. As instruções das perguntas não podem conter breakpoints e ficam fora do prefixo reutilizável. Decisions oferece suporte a um tempo de vida mínimo de 30 minutos; a opção de 12 horas se aplica à Responses API.
Defina cache para atender uma requisição repetida a partir da resposta armazenada em vez de chamar o provedor novamente, como nos outros endpoints do gateway. A chave de cache é o corpo completo da requisição junto com o workspace e o projeto, portanto qualquer alteração em state, questions, model ou outro campo do corpo gera uma entrada diferente. Uma resposta em cache retorna os model, answers e usage armazenados; a requisição continua sendo rastreada, mas nenhuma chamada ao provedor é feita e nenhum custo é adicionado. O cabeçalho de resposta X-Cache informa HIT ou MISS, e telemetry identifica o trace da requisição atual. Uma regra de roteamento com configuração de cache aplica o mesmo cache às requisições de Decisions correspondentes.
Batch
Envie grandes cargas de trabalho offline como um batch de Decisions em vez de uma requisição por decisão. Defina oendpoint do batch como /v3/router/decisions e dê a cada linha uma requisição de Decisions como body. Cada linha aceita os campos de Requisição, e a chave de API precisa das permissões batches e classify.
JSON
Aplicação durante a Beta
Aplicado em todas as requisições:
Não aplicado durante a Beta:
- Plugins de PII.
stateeinstructionschegam ao provedor exatamente como foram enviados, mesmo quando um plugin de redação está configurado para tráfego que de outra forma corresponderia. - Guardrails e evaluators. Eles não são executados, portanto uma regra de guardrail correspondente não pode bloquear uma requisição de Decisions.
- Regras de roteamento. Uma regra não reescreve o modelo nem adiciona fallbacks; apenas sua configuração de cache se aplica.
load_balancer,pluginseguardrailsno nível da requisição. Eles não fazem parte deste contrato. Campos desconhecidos no corpo são ignorados em vez de rejeitados, portanto enviá-los não tem efeito e não retorna erro.