Primitivas (perguntas)

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

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

Você pode fazer uma pergunta ou enviar várias juntas. Cada pergunta em uma requisição vê o mesmo estado, é avaliada de forma independente e devolve uma resposta tipada sob o ID que você escolheu.

Peça um único julgamento rápido por pergunta

Os modelos System One são feitos para julgamentos rápidos e focados. Peça um julgamento que uma pessoa com conhecimento faria em um segundo, com o contexto certo. “Esta mensagem transmite urgência?” é uma boa pergunta. “Analise esta mensagem e determine o melhor curso de ação” não é. Essa 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 você quer depende de vários fatores independentes, pergunte sobre cada fator separadamente e combine as respostas com a sua própria lógica. Em vez de “avalie este pitch de startup”, pergunte sobre tamanho de mercado, viabilidade técnica e diferenciação, e depois pondere-os no código conforme a importância relativa. Quando as prioridades mudarem, mude o valor dos pesos em vez de reescrever um prompt. Faça várias perguntas juntas mostra como fazer isso.

Defina uma pergunta

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

• ID. A chave que você escolhe, como refund_requested. Ela identifica a resposta devolvida.
• type. Um de choice, score ou noul.
• instructions. A pergunta que você está fazendo sobre o estado. É aqui que vai a sua lógica de avaliação. Escreva-a como uma pergunta clara e específica, ou como uma afirmação para o modelo julgar. Uma string basta para a maioria das perguntas. Também pode ser um objeto ou um array, o que coloca a pergunta em um campo e os dados aos quais ela se refere em outros; consulte Use 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 o seu formato.

Esta pergunta verifica se um cliente solicitou um reembolso:

from typesafe_sdk import Noul

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

Escolha um tipo de pergunta

Escolha o tipo que corresponde ao formato da resposta que você precisa.

• Choice cabe quando a resposta é uma de um conjunto conhecido de opções sem ordem entre elas: rotear um ticket para um departamento, classificar um tipo de documento, detectar uma linguagem de programação. Dê a lista completa de opções e adicione uma opção other ou none of the above quando a lista puder não cobrir todas as entradas.

• Score cabe quando a resposta cai em um espectro e você consegue descrever o que cada ponto desse espectro significa: gravidade de um bug, frustração do cliente, nível de habilidade. Os níveis são seus para definir, e o modelo devolve uma posição ao longo deles.

• Noul cabe em 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á pedindo um reembolso, o currículo menciona sistemas distribuídos.

Se dois tipos parecerem caber, prefira aquele cuja resposta o seu código consegue usar diretamente. Um Choice entre refund, rebook e information mapeia diretamente para três caminhos de código. Um Score de frustração do cliente mapeia para um limiar. Um Noul mapeia para um if.

O que volta

As respostas também são primitivas. Cada tipo de pergunta devolve um valor tipado que o seu código pode comparar, aplicar limiar, ordenar, passar para lógica adicional ou colocar no estado de uma requisição seguinte (consulte Quando uma pergunta depende de outra).

Duas propriedades dessas respostas as tornam componíveis:

• Toda resposta fica restrita às opções que você forneceu. O modelo devolve uma distribuição de probabilidade sobre as suas opções ou níveis, nunca um valor fora deles. O seu código nunca precisa recuperar um valor de texto gerado.
• Toda resposta é independente. A resposta de uma pergunta não é contexto oculto para outra. Você pode adicionar ou remover perguntas sem mudar os resultados das outras.

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

Faça referência a campos específicos

O conteúdo sendo avaliado, o estado, geralmente é um objeto JSON com várias partes: uma conversa, um registro, uma política. Quando uma pergunta for sobre uma dessas partes, nomeie-a nas instructions com um caminho de pontos e índices até a sua chave, incluindo as crases. Assim o modelo sabe qual parte do estado deve julgar.

Tome a conversa de suporte da página de 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 as cobranças 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`?"
        ),
    },
}

Caminhos explícitos deixam claro quais partes de um estado estruturado devem informar cada julgamento. Consulte Estado para saber como estruturar a entrada.

Faça várias perguntas juntas

Envie em uma única requisição todas as perguntas que usam o mesmo estado. Você pode misturar tipos de pergunta livremente. Os modelos System One avaliam em paralelo cada pergunta de uma requisição. Adicionar perguntas quase não muda o tempo de resposta e custa apenas os tokens das perguntas extras, que são baratos. Fazer uma pergunta que talvez você não precise é quase de graça.

Esta requisição classifica uma mensagem de cliente, verifica a urgência e pontua a frustração, tudo de uma vez:

{
  "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, passe um dicionário questions de objetos Choice, Noul e Score para client.system_one(...). Esta requisição envia um ticket e uma política de reembolso uma vez e recebe 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)

Consulte os SDKs de cliente para instalação e uso na sua linguagem.

Faça perguntas especulativas

Faça todas as perguntas que o seu código possa precisar, incluindo aquelas cuja resposta só importa para algumas entradas, e deixe o código decidir quais respostas usar. Se um ticket não for um relatório de bug, ignore a resposta de gravidade. Chamamos isso de padrão Fan-out especulativo. O cookbook de perguntas em paralelo mostra como agrupar 13 perguntas em uma única chamada é 11.5x mais barato e 9.6x mais rápido do que 13 chamadas separadas, sem mudança nas respostas.

Divida um julgamento complexo em várias perguntas

Um julgamento que depende de várias coisas é melhor dividido em uma pergunta por coisa. Combine as respostas no seu código, dando a cada uma um peso conforme a sua importância relativa. Os pesos são seus. Quando o resultado combinado não corresponde ao que a sua equipe decidiria, mude-os no código e execute de novo. Adicionar perguntas quase não muda o tempo de resposta, porque elas rodam em paralelo dentro de uma única requisição. A divisão custa alguns tokens de pergunta extras.

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

Quando uma pergunta depende de outra

As perguntas em uma mesma requisição são independentes: uma resposta não se torna contexto para outra pergunta. Se um julgamento posterior depende de uma resposta anterior, faça uma segunda requisição no código. A dependência é real apenas quando o seu código não consegue construir a segunda requisição antes de ter a primeira resposta: ele precisa da resposta para buscar mais dados para o estado, para decidir de que o estado é feito ou para escolher as opções da próxima pergunta. Caso contrário, faça as perguntas juntas e combine as respostas no código.

Duas requisições são a exceção, não a regra. Se as perguntas da segunda requisição pudessem ter sido feitas contra o estado original, faça-as na primeira requisição e deixe o código ignorar as que não precisa. Três cookbooks fazem uma segunda requisição por um motivo real. Sugestão de habilidades classifica 182 habilidades em uma requisição e depois busca o texto completo das três melhores e as julga de novo com essa evidência melhor. Recuperação de estrutura pergunta se cada quebra de linha dividiu uma frase, reúne as linhas em blocos a partir dessas respostas e depois classifica os blocos, que não existiam até a primeira requisição responder. Classificação hierárquica usa cada resposta de Choice para decidir quais opções a próxima requisição oferece.

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

Próximos passos

Para ver como eles se compõem em arquiteturas de sistema, vá para Padrões.