Referência da API

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

Avalie um state contra um mapa de questions tipadas e receba answers estruturadas, uma por pergunta. Para uma introdução guiada, comece pelas primitivas.

Endpoint de avaliação

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

Corpo da requisição

O formato de nível superior de cada requisição. Cada entrada do mapa questions é uma pergunta tipada à qual você dá um nome.

{
  "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 compartilham type e instructions; cada um adiciona o seu próprio criteria.

A propriedade instructions pode ser uma string, um objeto ou um array. Você pode dividir uma pergunta longa que tenha contexto extra, ou dados aos quais ela precise se referir, em um objeto estruturado. Coloque a pergunta em um campo e os dados nos outros, e refira-se aos campos de dados pelo nome entre crases, da mesma forma que você aponta uma pergunta para um valor aninhado de state:

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

Consulte Use estrutura nas perguntas para saber mais.

Noul

Uma pergunta de sim/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 você define. 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 segundo uma rubrica que você define. Devolve um valor ponderado pela probabilidade entre os seus 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 você 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 correspondente à sua pergunta. As respostas de Choice e Score também trazem uma confidence entre 0 e 1, derivada da distribuição de probabilidade da resposta. Consulte 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 status HTTP padrão com um corpo JSON que descreve o que deu errado.

Como lidar com limites de taxa

Quando você receber uma resposta 429 Too Many Requests ou 529 Overloaded, repita a requisição com backoff exponencial em vez de tentar de novo imediatamente. Os nossos SDKs de cliente tratam isso automaticamente, então nenhum tratamento extra é necessário se você usar um dos nossos SDKs com a sua política de retentativas padrão.