Справочник по API

Полный справочник по HTTP API для эндпоинта оценки TypeSafe.

Оцените state по карте типизированных questions и получите структурированные answers, по одному на вопрос. Для вводного знакомства начните с примитивов.

Эндпоинт оценки

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

Тело запроса

Форма верхнего уровня каждого запроса. Каждая запись в карте questions — это типизированный вопрос, которому вы задаёте имя.

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

Типы вопросов

Question бывает одного из трёх типов, задаваемых его полем type. Все три разделяют type и instructions; каждый добавляет свои criteria.

Свойство instructions может быть строкой, объектом или массивом. Длинный вопрос с дополнительным контекстом или данными, на которые нужно ссылаться, можно разбить на структурированный объект. Поместите вопрос в одно поле, а данные — в другие и ссылайтесь на поля данных по имени в обратных кавычках так же, как указываете вопрос на вложенное значение state:

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

Подробнее см. Использование структуры в вопросах.

Noul

Вопрос «да/нет». Возвращает вероятность того, что ответ — «да».

{
  "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

Выбирает один вариант из заданного вами набора. Возвращает выбранный вариант и полное распределение вероятностей.

{
  "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

Оценивает состояние по заданной вами рубрике. Возвращает взвешенное по вероятностям значение по вашим уровням.

{
  "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"]
    }
  }
}

Тело ответа

По одному ответу на вопрос, возвращаемых под теми же id, которые вы указали.

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

Типы ответов

Каждый ответ несёт type, соответствующий своему вопросу. Ответы Choice и Score также несут confidence в диапазоне от 0 до 1, выведенную из распределения вероятностей ответа. См. Уверенность.

Ответ Noul

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

Ответ 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 }
}

Ответ 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 }
}

Ошибки

Ошибки используют стандартные коды состояния HTTP с телом JSON, описывающим, что пошло не так.

Обработка ограничений скорости

Когда вы получаете ответ 429 Too Many Requests или 529 Overloaded, повторяйте запрос с экспоненциальной задержкой, а не сразу. Наши клиентские SDK обрабатывают это автоматически, так что дополнительная обработка не нужна, если вы используете один из наших SDK с политикой повторов по умолчанию.