Referência da API

Referência completa da API HTTP para o endpoint de avaliação da TypeSafe.

Avalia um state em relação a um mapa de questions tipadas e recebe answers estruturadas, uma por pergunta. Para uma introdução guiada, começa pelas primitivas.

Endpoint de avaliação

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <API_KEY>
Content-Type: application/json

Corpo do pedido

A estrutura de nível superior de cada pedido. Cada entrada no mapa questions é uma pergunta tipada com o nome que escolheres.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?"
    }
  }
}

Tipos de pergunta

Uma Question é um de três tipos, definido pelo seu campo type. Os três partilham type e instructions; cada um acrescenta os seus próprios criteria.

A propriedade instructions pode ser uma string, um objeto ou um array. Podes dividir uma pergunta longa que tenha contexto extra, ou dados a que precise de fazer referência, num objeto estruturado. Coloca a pergunta num campo e os dados nos outros e refere-te aos campos de dados pelo nome entre acentos graves, tal como apontas uma pergunta a um valor state aninhado:

"instructions": {
  "potential_duplicate": {
    "name": "John Smith",
    "location": "Oakland, California",
    "last_employer": "Google"
  },
  "question": "Is the resume for the same person as `potential_duplicate`?"
}

Vê Usa estrutura nas perguntas para saber mais.

Noul

Uma pergunta de sim ou não. Devolve a probabilidade de a resposta ser sim.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?",
      "criteria": {
        "true": "Explicitly time-sensitive",
        "false": "No urgency expressed"
      }
    }
  }
}

Choice

Escolhe uma opção de um conjunto que defines. Devolve a opção escolhida e a distribuição de probabilidade completa.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    }
  }
}

Score

Avalia o estado ao longo de uma rubrica que defines. Devolve um valor ponderado pela probabilidade pelos teus níveis.

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    }
  }
}

Corpo da resposta

Uma resposta por pergunta, devolvida sob os mesmos ids que forneceu.

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 296, "output_tokens": 20 }
}

Tipos de resposta

Cada resposta traz um type que corresponde à sua pergunta. As respostas Choice e Score também trazem uma confidence entre 0 e 1, derivada da distribuição de probabilidade da resposta. Vê Confiança.

Resposta Noul

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 307, "output_tokens": 20 }
}

Resposta Choice

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 },
      "confidence": 0.81
    }
  },
  "usage": { "input_tokens": 318, "output_tokens": 34 }
}

Resposta Score

{
  "model": "jev-1.13.0",
  "answers": {
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 },
      "confidence": 0.92
    }
  },
  "usage": { "input_tokens": 304, "output_tokens": 18 }
}

Erros

Os erros usam códigos de estado HTTP padrão com um corpo JSON que descreve o que correu mal.

Como lidar com os limites de taxa

Quando recebes uma resposta 429 Too Many Requests ou 529 Overloaded, tenta novamente o pedido com retrocesso exponencial em vez de tentar imediatamente. Os nossos SDKs de cliente tratam disto automaticamente, por isso não é preciso tratamento extra se usares um dos nossos SDKs com a sua política de repetição predefinida.