Primitivas (perguntas)

Os três tipos de pergunta da TypeSafe (Choice, Score, Noul), as respostas tipadas que devolvem, como escolher entre eles e como fazer várias de uma vez.

As primitivas da TypeSafe são os pequenos blocos de construção tipados que compões no código. Andam aos pares: uma pergunta define um julgamento para um modelo System One fazer sobre um estado, e a sua resposta é o valor tipado que volta. Compões as respostas no teu código para tomar decisões. Há três tipos de pergunta, cada um devolvendo uma forma diferente de resposta.

Podes fazer uma pergunta ou enviar várias juntas. Cada pergunta de um pedido vê o mesmo estado, é avaliada de forma independente e devolve uma resposta tipada sob o ID que escolheste.

Pede um único julgamento rápido por pergunta

Os modelos System One são feitos para julgamentos rápidos e focados. Pede um julgamento que uma pessoa conhecedora faz num segundo, com o contexto certo. «Esta mensagem transmite urgência?» é uma boa pergunta. «Analisa esta mensagem e determina o melhor curso de ação» não é. Isso exige raciocínio lento e é um sinal para dividir a tarefa em perguntas pequenas e compor as respostas no código.

Se o julgamento que queres depende de vários fatores independentes, pergunta por cada fator em separado e combina as respostas com a tua própria lógica. Em vez de «avalia este pitch de startup», pergunta pelo tamanho do mercado, a viabilidade técnica e a diferenciação e depois pondera-os no código segundo a sua importância relativa. Quando as prioridades mudarem, altera o valor dos pesos em vez de reescrever um prompt. Faz várias perguntas ao mesmo tempo mostra como fazê-lo.

Define uma pergunta

Cada pergunta tem um ID, um type e instructions. As perguntas Choice e Score também aceitam criteria, que define as opções de uma pergunta Choice ou os níveis de um Score. As perguntas Noul aceitam criteria como esclarecimento opcional do que significam sim e não.

• ID. A chave que escolhes, como refund_requested. Identifica a resposta devolvida.
• type. Um de choice, score ou noul.
• instructions. A pergunta que fazes sobre o estado. É aqui que entra a tua lógica de avaliação. Escreve-a como uma pergunta clara e específica, ou como uma afirmação para o modelo julgar. Uma string chega para a maioria das perguntas. Também pode ser um objeto ou um array, o que põe a pergunta num campo e os dados a que se refere noutros; vê Usa estrutura nas perguntas.
• criteria. As respostas possíveis: um mapa de opções para uma pergunta Choice, uma lista ordenada de níveis para um Score e uma descrição opcional de sim e não para um Noul. A página de cada tipo de pergunta cobre a sua forma.

Esta pergunta verifica se um cliente pediu um reembolso:

from typesafe_sdk import Noul

questions = {
    "refund_requested": Noul(
        instructions="Does the customer request a refund?",
    ),
}

Escolhe um tipo de pergunta

Escolhe o tipo que corresponde à forma da resposta de que precisas.

• Choice serve quando a resposta é uma de um conjunto conhecido de opções sem ordem entre elas: encaminhar um ticket para um departamento, classificar um tipo de documento, detetar uma linguagem de programação. Dá a lista completa de opções e acrescenta uma opção other ou none of the above quando a lista possa não cobrir todas as entradas.

• Score serve quando a resposta cai num espetro e consegues descrever o que significa cada ponto desse espetro: gravidade de um erro, frustração do cliente, nível de competência. Os níveis são teus para os definires, e o modelo devolve uma posição ao longo deles.

• Noul serve uma pergunta clara de sim/não em que a própria probabilidade é o sinal útil: esta mensagem contém informação de identificação pessoal, o cliente está a pedir um reembolso, o currículo menciona sistemas distribuídos.

Se dois tipos parecerem ambos adequados, prefere o que dá uma resposta sobre a qual o teu código possa agir diretamente. Um Choice entre refund, rebook e information corresponde diretamente a três caminhos de código. Um Score de frustração do cliente corresponde a um limiar. Um Noul corresponde a um if.

O que vem de volta

As respostas também são primitivas. Cada tipo de pergunta devolve um valor tipado que o teu código pode comparar, usar com limiares, ordenar, passar para mais lógica ou colocar no estado de um pedido seguinte (vê Quando uma pergunta depende de outra).

Duas propriedades destas respostas tornam-nas componíveis:

• Cada resposta está limitada às opções que forneceu. O modelo devolve uma distribuição de probabilidade pelas tuas opções ou níveis, nunca um valor fora deles. O teu código nunca tem de recuperar um valor a partir de prosa gerada.
• Cada resposta é independente. A resposta de uma pergunta não é contexto oculto para outra. Podes acrescentar ou remover perguntas sem alterar os resultados das outras.

Confiança explica como a confidence deriva das probabilities e como usá-la para decidir quando agir automaticamente e quando escalar para uma pessoa.

Faz referência a campos específicos

O conteúdo a avaliar, o estado, é muitas vezes um objeto JSON com várias partes: uma conversa, um registo, uma política. Quando uma pergunta incide sobre uma dessas partes, nomeia-a nas instructions com um caminho de pontos e índices até à sua chave, incluindo os acentos graves. O modelo fica então a saber que parte do estado deve julgar.

Toma a conversa de apoio da página Estado:

{
  "ticket": {
    "subject": "Duplicate charge",
    "messages": [
      {"from": "customer", "text": "I was charged twice for order A-104. Please refund the duplicate."},
      {"from": "support", "text": "We are checking the charges."}
    ]
  },
  "order": {
    "id": "A-104",
    "charges": [
      {"amount_usd": 49, "status": "captured"},
      {"amount_usd": 49, "status": "captured"}
    ]
  },
  "refund_policy": "Duplicate charges are eligible for a refund."
}

Estas duas perguntas apontam para a mensagem do cliente, a política e os encargos, por caminho:

questions = {
    "refund_requested": {
        "type": "noul",
        "instructions": "Does `ticket.messages[0].text` request a refund?",
    },
    "policy_supports_refund": {
        "type": "noul",
        "instructions": (
            "Does `refund_policy` support the refund requested "
            "in `ticket.messages[0].text`, given `order.charges`?"
        ),
    },
}

Os caminhos explícitos deixam claro que partes de um estado estruturado devem informar cada julgamento. Vê Estado para saber como estruturar a entrada.

Faz várias perguntas ao mesmo tempo

Envia num único pedido todas as perguntas que usem o mesmo estado. Podes misturar tipos de pergunta livremente. Os modelos System One avaliam cada pergunta de um pedido em paralelo. Acrescentar perguntas quase não altera o tempo de resposta e custa apenas os tokens das perguntas extra, que são baratos. Fazer uma pergunta de que podes não precisar é quase gratuito.

Este pedido classifica uma mensagem de cliente, verifica a urgência e pontua a frustração, tudo ao mesmo tempo:

{
  "state": "Our API integration started returning 500 errors on every request about 20 minutes ago, and we can't process any customer orders until this is fixed.",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this",
      "criteria": {
        "billing": "Payment or subscription issues",
        "technical": "Bugs or integration problems",
        "sales": "Pricing or account questions"
      }
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "The message conveys urgency or time-sensitivity"
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated the customer appears",
      "criteria": [
        "Calm, just stating facts",
        "Frustrated but civil",
        "Very angry, strong language"
      ]
    }
  }
}

Os nossos SDKs de cliente fornecem perguntas e respostas tipadas. Em Python, passa um dicionário questions de objetos Choice, Noul e Score a client.system_one(...). Este pedido envia um ticket e uma política de reembolso uma só vez e obtém uma resposta tipada para cada pergunta:

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

state = {
    "ticket_message": "My flight was cancelled. Can I get a refund?",
    "refund_policy": "Cancelled flights are eligible for a full refund.",
}

with TypeSafeClient() as client:
    response = client.system_one(
        state=state,
        questions={
            "refund_requested": Noul(
                instructions="Does `ticket_message` request a refund?",
            ),
            "request_type": Choice(
                instructions="What is the main request in `ticket_message`?",
                criteria={
                    "refund": "The customer wants money returned.",
                    "rebooking": "The customer wants a replacement flight.",
                    "information": "The customer is asking for information only.",
                },
            ),
            "frustration": Score(
                instructions="How frustrated does the customer appear in `ticket_message`?",
                criteria=[
                    "Calm and neutral.",
                    "Concerned but civil.",
                    "Very angry or using strong language.",
                ],
            ),
        },
    )

print(response.answers["refund_requested"].noul)
print(response.answers["request_type"].choice)
print(response.answers["frustration"].score)

Vê os SDKs de cliente para instalação e utilização na tua linguagem.

Faz perguntas especulativas

Faz todas as perguntas de que o teu código possa precisar, incluindo as cuja resposta só importa para algumas entradas, e deixa o código decidir que respostas usar. Se um ticket afinal não for um relatório de erro, ignora a resposta de gravidade. Chamamos a isto padrão Fan-out especulativo. O cookbook de perguntas em paralelo mostra como agrupar 13 perguntas numa única chamada é 11.5 vezes mais barato e 9.6 vezes mais rápido do que 13 chamadas separadas, sem alterações nas respostas.

Divide um julgamento complexo em várias perguntas

Um julgamento que depende de várias coisas é melhor dividido numa pergunta por coisa. Combina as respostas no teu código, dando a cada uma um peso pela sua importância relativa. Os pesos são teus. Quando o resultado combinado não corresponder ao que a tua equipa decidiria, altera-os no código e executa de novo. Acrescentar perguntas quase não altera o tempo de resposta, porque correm em paralelo dentro de um único pedido. A divisão custa alguns tokens de pergunta extra.

Por exemplo, a prioridade de um ticket pode ser construída a partir de três perguntas Score: quão grave é o erro, quão frustrado está o cliente e quanta informação o relatório dá a um engenheiro. A página do Score percorre este pedido e o código que normaliza e pondera as respostas em Dividir um julgamento complexo em vários Scores. Esta técnica chama-se padrão Pontuação composta.

Quando uma pergunta depende de outra

As perguntas do mesmo pedido são independentes: uma resposta não se torna contexto para outra pergunta. Se um julgamento posterior depender de uma resposta anterior, faz um segundo pedido no código. A dependência só é real quando o teu código não consegue construir o segundo pedido sem a primeira resposta: precisa da resposta para obter mais dados para o estado, para decidir de que é feito o estado, ou para escolher as opções da pergunta seguinte. Caso contrário, faz as perguntas juntas e combina as respostas no código.

Dois pedidos são a exceção, não a regra. Se as perguntas do segundo pedido pudessem ter sido feitas contra o estado original, faz as primeiras no primeiro pedido e deixa o código ignorar as de que não precisa. Três cookbooks fazem um segundo pedido por um motivo real. Sugestão de habilidades ordena 182 habilidades num pedido e depois obtém o texto completo das três melhores e volta a julgá-las com essa evidência melhor. Recuperação de estrutura pergunta se cada quebra de linha dividiu uma frase, junta as linhas em blocos a partir dessas respostas e depois classifica os blocos, que não existiam até o primeiro pedido responder. Classificação hierárquica usa cada resposta Choice para decidir que opções o pedido seguinte oferece.

Vê Como construir com a TypeSafe para orientação sobre como dividir um fluxo de trabalho em julgamentos focados.

Próximos passos

Para ver como se compõem em arquiteturas de sistema, vai a Padrões.