Score (Балльная шкала)

Числа перед каждым шагом — это позиции на шкале, описанные в подразделе Уровни.

Структура запроса

Тело POST-запроса к TypeSafe API содержит те же три поля верхнего уровня, что и любой другой тип вопроса: state (оцениваемый контент), model и questions. Каждый вопрос типа Score имеет следующие поля:

• type: Всегда "score".
• instructions: Вопрос, на который отвечает модель. Что именно оценивается.
• criteria: Упорядоченный массив описаний уровней, от нижнего края шкалы к верхнему. Должно быть как минимум два уровня; API принимает до 10 уровней.

Ниже приведен запрос, где состояние — это отчет об ошибке, а вопрос — насколько критичен данный баг:

<TypesafeExample
display="request"
example={{
state: 'The export button crashes the settings page in Safari. It works in Chrome, but a few of our customers only use Safari.',
selectedModels: ['jev-latest'],
questions: {
bug_severity: {
type: 'score',
instructions: 'How severe is the reported issue?',
criteria: [
'Cosmetic; no impact to functionality',
'Broken or degraded feature, but workaround exists',
'Blocking issue; no workaround exists',
],
},
},
}}
/>

Вы сами выбираете ID вопроса — в данном случае bug_severity. Этот ID не отправляется в модель. Ответ возвращается под тем же ID.

Уровни

Каждый элемент массива criteria представляет собой уровень: точку на спектре возможных ответов, описанную словами. Номер уровня — это его индекс в массиве criteria, начиная с 0, поэтому три элемента выше соответствуют уровням 0, 1 и 2. Порядок элементов в массиве определяет их нумерацию.

Модель получает текстовые описания и ничего больше, и каждый уровень оценивается изолированно относительно состояния.

Значение score в ответе — это положение на числовой шкале уровней. Для трехшкальной градации оно лежит в диапазоне от 0 до 2 и может попадать в промежуток между двумя уровнями.

Наши клиентские SDK предоставляют типизированные вопросы. В Python тот же вопрос задается через Score:

from typesafe_sdk import Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state="The export button crashes the settings page in Safari. It works in Chrome, but a few of our customers only use Safari.",
        questions={
            "bug_severity": Score(
                instructions="How severe is the reported issue?",
                criteria=[
                    "Cosmetic; no impact to functionality",
                    "Broken or degraded feature, but workaround exists",
                    "Blocking issue; no workaround exists",
                ],
            ),
        },
    )

    print(response.answers["bug_severity"].score)

Используйте метод system_one или эндпоинт https://api.typesafe.ai/v1/systemone для вызова модели System One. Поле model определяет, какая модель обрабатывает запрос. В руководстве Как создавать решения с помощью TypeSafe рассматривается, где в коде следует вызывать модель.

Используйте один из наших клиентских SDK или вызывайте TypeSafe API напрямую. Если интеграцию пишет агент разработки, сначала установите скилл TypeSafe для агентов, чтобы он знал форматы запросов и ответов.

Структура ответа

В ответе в словаре answers возвращается по одной записи на каждый вопрос под соответствующими идентификаторами из запроса. Ниже показан ответ на пример запроса выше:

{
  "model": "jev-1.13.0",
  "answers": {
    "bug_severity": {
      "type": "score",
      "score": 1.43,
      "confidence": 0.35,
      "legend": {
        "0": "Cosmetic; no impact to functionality",
        "1": "Broken or degraded feature, but workaround exists",
        "2": "Blocking issue; no workaround exists"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.57,
        "2": 0.43
      }
    }
  },
  "usage": {
    "input_tokens": 332,
    "output_tokens": 18
  }
}

Каждый ответ Score содержит пять значений:

• type: Тип вопроса TypeSafe.
• probabilities: Вероятность каждого уровня со строковыми ключами номеров уровней. Сумма значений равна 1.
• score: Положение на числовой шкале уровней от 0 до максимального индекса уровня (здесь 2). Это сумма произведений номеров уровней на их вероятности: 0 × 0.0 + 1 × 0.57 + 2 × 0.43 = 1.43.
• legend: Словарь, сопоставляющий номер каждого уровня с его текстовым описанием.
• confidence: Число от 0 до 1, рассчитанное на основе формы распределения probabilities. Ярко выраженный пик на одном уровне означает высокую уверенность. Распределение вероятности по нескольким уровням означает низкую уверенность.

Оценка 1.43 означает, что модель колеблется между уровнями 1 и 2, склоняясь к уровню 1. Это точно соответствует содержанию отчета: функция экспорта сломана, и переход на Chrome решает проблему для большинства пользователей, но не для тех, кто работает исключительно в Safari. Модель присваивает 0.57 варианту «существует обходной путь» и 0.43 варианту «обходного пути нет», а уверенность равна 0.35 из-за разделения мнений.

В Python SDK объект ScoreAnswer содержит типизированные поля score, confidence, probabilities и legend. При этом SDK использует целочисленные ключи уровней для probabilities и legend вместо строк.

Интерпретация Score

Посмотрим, как меняется оценка при различных входных данных на примере вопроса и уровней из рассмотренного выше запроса:

"Насколько критична описанная проблема?"
  → 0: Косметическая; не влияет на функциональность
  → 1: Функция сломана или деградировала, но есть обходной путь
  → 2: Блокирующая проблема; обходного пути нет

Посмотрим, как разные отчеты о багах влияют на оценку:

<tr>
  <td>The PDF export button does nothing when clicked. I can still export to CSV and convert it myself, but that takes ages.</td>
  <td>1.0</td><td>1.0</td><td>0.0</td><td>1.0</td><td>0.0</td>
</tr>

<tr>
  <td>Export to PDF fails with a spinner that never finishes. Some of our team say CSV export still works for them, others say it fails too.</td>
  <td>1.11</td><td>0.84</td><td>0.0</td><td>0.89</td><td>0.11</td>
</tr>

<tr>
  <td>The export button crashes the settings page in Safari. It works in Chrome, but a few of our customers only use Safari.</td>
  <td>1.43</td><td>0.35</td><td>0.0</td><td>0.57</td><td>0.43</td>
</tr>

<tr>
  <td>Nobody on our team can log in since this morning. We get a 500 error on every attempt.</td>
  <td>2.0</td><td>1.0</td><td>0.0</td><td>0.0</td><td>1.0</td>
</tr>

<th colSpan={3} style={{ textAlign: 'left' }}><code>probabilities</code></th>
</tr>

<tr>
  <th style={{ width: '44%' }}>Состояние</th>
  <th style={{ width: '12%', whiteSpace: 'nowrap' }}><code>score</code></th>
  <th style={{ width: '16%', whiteSpace: 'nowrap' }}><code>confidence</code></th>
  <th style={{ width: '9%', whiteSpace: 'nowrap' }}>Уровень 0</th>
  <th style={{ width: '9%', whiteSpace: 'nowrap' }}>Уровень 1</th>
  <th style={{ width: '10%', whiteSpace: 'nowrap' }}>Уровень 2</th>
</tr>

В этих примерах уверенность 1.0 означает, что полученное распределение сосредоточило всю вероятность на одном уровне. Это характеризует степень определенности модели, а не абсолютную гарантию безошибочности ответа.

Score представляет собой математическое ожидание номеров уровней, взвешенное по вероятностям. В третьем и четвертом примерах вероятность разделена между уровнями 1 и 2. Больший вес уровня 2 повышает итоговый балл. Это не измеряет долю пользователей, у которых нет обходного пути.

Различные распределения могут давать одинаковый балл score. Оценка 1.0 может означать, что вся вероятность находится на уровне 1, либо что по половине вероятности приходится на уровни 0 и 2. Всегда анализируйте probabilities и confidence вместе со значением score, чтобы различать подобные ситуации.

Дробная оценка — это положение на шкале. Вы можете использовать ее для ранжирования отчетов по критичности или округлять до ближайшего целого уровня, когда коду требуется дискретное решение. В нашем кукбуке по сопоставлению сущностей показан пример принятия решения через округление до ближайшего уровня.

Низкая уверенность для Score обычно указывает на одну из трех причин: уровни частично перекрываются для данного состояния, вопрос измеряет сразу несколько измерений, либо состояние содержит недостаточно информации для уверенного вывода. Рекомендации по использованию уверенности в коде см. в документации Уверенность (Confidence).

Написание качественных уровней

Описывайте ситуации, а не абстрактные степени. Формулировка «Функция сломана или деградировала, но есть обходной путь» дает модели конкретный ориентир для сопоставления с состоянием. «Умеренно критичный» — не дает. Конкретные описания помогают модели четко различать уровни. Проверяйте ответы на известных примерах: высокая уверенность сама по себе не доказывает, что описание лучше.

Каждый уровень оценивается отдельно. Модель не видит номер уровня или его соседей, поэтому формулировка «хуже предыдущего уровня» для нее ничего не значит, а числа внутри описаний или инструкций не помогают. Вот что произойдет, если в качестве уровней передать просто цифры для отчета о смещенной кнопке из таблицы выше:

instructions: "Rate severity from 0 to 2, where 2 is worst"
criteria: ["0", "1", "2"]
→ score 0.55, confidence 0.33, probabilities 0: 0.45, 1: 0.55, 2: 0.0

Тот же отчет с тремя описательными уровнями получает оценку 0.0 с уверенностью 1.0. Имея только цифры, модель лишена опорных ориентиров и делит вероятность между 0 и 1.

Используйте столько уровней, сколько можете четко и различимо описать, вплоть до 10. Трех уровней часто вполне достаточно. Не добавляйте уровни, которые не можете однозначно разграничить.

Держите каждый вопрос Score строго в рамках одного измерения. Если описание гласит «пунктуальный, умный и опытный», вопрос оценивает сразу три вещи, и входные данные, где кандидат силен в одном, но слаб в другом, не смогут найти себе места. Уверенность упадет, а оценка потеряет смысл. Разделите такой запрос на отдельные вопросы Score по каждому аспекту и объедините их в коде, как показано в следующем разделе.

Если на верхнем конце шкалы существует редкий экстремальный сценарий, требующий особой реакции, выделите его в отдельный уровень. К шкале тональности, заканчивающейся на «очень зол», можно добавить уровень «оскорбления или угрозы». Без этого уровня оба сообщения могут получить близкий максимальный балл, и числовая оценка не позволит их различить.

Если промежуточных состояний не существует вовсе, а ответ представляет собой одну из дискретных категорий, используйте вместо этого Choice или разбейте задачу на несколько вопросов Noul. Обязательно тестируйте ваши уровни на реальных данных: две разные формулировки одной и той же шкалы могут вести себя по-разному на вашем корпусе текстов.

Разделение сложного суждения на несколько вопросов Score

Сложное суждение, зависящее от нескольких факторов, лучше всего разделить на отдельные вопросы Score по каждому фактору. Затем вы можете объединить возвращенные TypeSafe оценки в коде. Некоторые вопросы Score могут иметь больший вес, поэтому назначьте каждому весовой коэффициент в зависимости от его важности. Веса определяете вы сами. Если совокупный результат расходится с решением вашей команды, просто скорректируйте коэффициенты в коде и перезапустите пайплайн. Отправляйте все вопросы Score в одном запросе: они вычисляются параллельно. Добавление вопросов практически не влияет на задержку и стоит лишь небольшого количества дополнительных токенов; см. раздел Задавайте несколько вопросов одновременно.

В запросе ниже рассматривается тикет с зависающим PDF-экспортом с дополнительным контекстом. Задаются три вопроса Score: насколько критичен баг, насколько раздражен клиент и насколько подробно отчет описывает проблему для инженера.

<TypesafeExample
display="request"
example={{
state: 'Export to PDF fails with a spinner that never finishes. Some of our team say CSV export still works for them, others say it fails too. This is the third time I'm writing in and honestly I'm done. Steps: open any report, click Export, choose PDF. Chrome 128 on macOS.',
selectedModels: ['jev-latest'],
questions: {
severity: {
type: 'score',
instructions: 'How severe is the reported issue?',
criteria: [
'Cosmetic; no impact to functionality',
'Broken or degraded feature, but workaround exists',
'Blocking issue; no workaround exists',
],
},
frustration: {
type: 'score',
instructions: 'How frustrated is the customer?',
criteria: [
'Calm, just stating facts',
'Frustrated but civil',
'Very angry, strong language or threatening to leave',
],
},
report_quality: {
type: 'score',
instructions: 'How much does the report give an engineer to work with?',
criteria: [
'No detail; just says something is broken',
'Names the feature but no steps or environment',
'Steps to reproduce or environment, but not both',
'Steps to reproduce and environment',
],
},
},
}}
/>

Ответ TypeSafe:

{
  "model": "jev-1.13.0",
  "answers": {
    "severity": {
      "type": "score",
      "score": 1.24,
      "confidence": 0.64,
      "legend": {
        "0": "Cosmetic; no impact to functionality",
        "1": "Broken or degraded feature, but workaround exists",
        "2": "Blocking issue; no workaround exists"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.76,
        "2": 0.24
      }
    },
    "frustration": {
      "type": "score",
      "score": 1.28,
      "confidence": 0.58,
      "legend": {
        "0": "Calm, just stating facts",
        "1": "Frustrated but civil",
        "2": "Very angry, strong language or threatening to leave"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.72,
        "2": 0.28
      }
    },
    "report_quality": {
      "type": "score",
      "score": 3.0,
      "confidence": 1.0,
      "legend": {
        "0": "No detail; just says something is broken",
        "1": "Names the feature but no steps or environment",
        "2": "Steps to reproduce or environment, but not both",
        "3": "Steps to reproduce and environment"
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.0,
        "2": 0.0,
        "3": 1.0
      }
    }
  },
  "usage": {
    "input_tokens": 468,
    "output_tokens": 43
  }
}

Каждый вопрос оценивается изолированно относительно тикета и получает свой балл:

• severity: 1.24 при уверенности 0.64. Та же трактовка, что и ранее: функция сломана, но у части пользователей есть обходной путь.
• frustration: 1.28 при уверенности 0.58. Текст сформулирован вежливо, однако фразы «пишу в третий раз» и «с меня хватит» смещают часть оценки к верхнему уровню, поэтому модель делит 0.72 и 0.28 между уровнями «раздражен, но корректен» и «очень зол». Для этого тикета два уровня частично перекрываются, чем и объясняется умеренная уверенность.
• report_quality: 3.0 при уверенности 1.0. Указаны и шаги воспроизведения, и версия браузера.

Поскольку три шкалы имеют разное количество уровней, перед их объединением нормализуйте каждую оценку. Четырехуровневая шкала возвращает значения от 0 до 3, а трехуровневая — от 0 до 2, поэтому максимальный балл на одной шкале численно больше максимального балла на другой. Разделите каждый балл на максимальный номер его уровня, len(criteria) - 1, чтобы привести все оценки к интервалу от 0 до 1. Тогда веса будут в точности отражать задуманное: вес 0.6 для критичности и 0.3 для раздражения сделает критичность ровно в два раза важнее.

Приведенный ниже код на Python SDK задает эти три вопроса, нормализует каждый балл и вычисляет итоговый приоритет:

from typesafe_sdk import Score, TypeSafeClient

TRIAGE_QUESTIONS = {
    "severity": Score(
        instructions="How severe is the reported issue?",
        criteria=[
            "Cosmetic; no impact to functionality",
            "Broken or degraded feature, but workaround exists",
            "Blocking issue; no workaround exists",
        ],
    ),
    "frustration": Score(
        instructions="How frustrated is the customer?",
        criteria=[
            "Calm, just stating facts",
            "Frustrated but civil",
            "Very angry, strong language or threatening to leave",
        ],
    ),
    "report_quality": Score(
        instructions="How much does the report give an engineer to work with?",
        criteria=[
            "No detail; just says something is broken",
            "Names the feature but no steps or environment",
            "Steps to reproduce or environment, but not both",
            "Steps to reproduce and environment",
        ],
    ),
}


def normalized(answers, question_id: str) -> float:
    """Приведение оценки к диапазону от 0 до 1 делением на максимальный номер уровня."""
    top_level = len(TRIAGE_QUESTIONS[question_id].criteria) - 1
    return answers[question_id].score / top_level


def priority(ticket: str) -> float:
    with TypeSafeClient() as client:
        response = client.system_one(
            state=ticket,
            questions=TRIAGE_QUESTIONS,
        )
    answers = response.answers

    severity = normalized(answers, "severity")
    frustration = normalized(answers, "frustration")
    report_quality = normalized(answers, "report_quality")

    # Подробный отчет помогает инженеру в расследовании, поэтому немного повышает приоритет.
    return 0.6 * severity + 0.3 * frustration + 0.1 * report_quality

Для рассмотренного ответа нормализованные оценки составляют 0.62 для критичности, 0.64 для раздражения и 1.0 для качества отчета. Приоритет равен 0.6 × 0.62 + 0.3 × 0.64 + 0.1 × 1.0 = 0.664, что округляется до 0.66.

Весовые коэффициенты находятся прямо в вашем коде, поэтому вы точно видите, как формируется итоговое число, и можете изменить его, если ранжирование не совпадает с видением команды. Если позже вам понадобятся дополнительные вопросы Score, просто добавьте их в TRIAGE_QUESTIONS. Количество сетевых вызовов останется равным единице. Этот подход декомпозиции сложного суждения на отдельные оценки Score с последующим взвешенным объединением в коде называется паттерном Композитная оценка (Composite scoring).

Структурированные описания уровней

Начните с простого текстового описания каждого уровня. Если модель продолжает колебаться между двумя соседними уровнями на входных данных, которые вам кажутся очевидными, передайте для каждого уровня объект вместо строки, добавив поле для описания сути уровня и поле с примерами ситуаций. Используйте одинаковые имена полей для всех уровней, чтобы модель могла корректно сопоставлять их.

Ниже приведен запрос по тому же тикету с зависающим PDF-экспортом, но с добавлением примеров к каждому уровню:

<TypesafeExample
display="request"
example={{
state: 'Export to PDF fails with a spinner that never finishes. Some of our team say CSV export still works for them, others say it fails too.',
selectedModels: ['jev-latest'],
questions: {
bug_severity: {
type: 'score',
instructions: 'How severe is the reported issue?',
criteria: [
{
what: 'Cosmetic; no impact to functionality',
examples: ['typo in a label', 'misaligned icon'],
},
{
what: 'Broken or degraded feature, but workaround exists',
examples: ['export fails in one browser but works in another'],
},
{
what: 'Blocking issue; no workaround exists',
examples: ['cannot log in', 'data loss'],
},
],
},
},
}}
/>

Ответ:

{
  "model": "jev-1.13.0",
  "answers": {
    "bug_severity": {
      "type": "score",
      "score": 1.09,
      "confidence": 0.87,
      "legend": {
        "0": {
          "what": "Cosmetic; no impact to functionality",
          "examples": [
            "typo in a label",
            "misaligned icon"
          ]
        },
        "1": {
          "what": "Broken or degraded feature, but workaround exists",
          "examples": [
            "export fails in one browser but works in another"
          ]
        },
        "2": {
          "what": "Blocking issue; no workaround exists",
          "examples": [
            "cannot log in",
            "data loss"
          ]
        }
      },
      "probabilities": {
        "0": 0.0,
        "1": 0.91,
        "2": 0.09
      }
    }
  },
  "usage": {
    "input_tokens": 379,
    "output_tokens": 18
  }
}

С простыми строками этот тикет получил оценку 1.11 с уверенностью 0.84. С примерами оценка составила 1.09 при уверенности 0.87 — небольшое изменение, так как простые строки и так хорошо позиционировали проблему. Эффект становится гораздо более заметным в тех случаях, когда простые строки оставляли модель в нерешительности, как показано в следующей таблице.

Примеры направляют модель, но они помогают только тогда, когда действительно похожи на ваши реальные входные данные. В таблице ниже показан исходный отчет по Safari с тремя различными конфигурациями уровней:

В этом сравнении релевантный пример концентрирует практически всю вероятность на одном уровне. Нерелевантный пример дает тот же результат, что и простые строки. При этом высокая уверенность сама по себе не гарантирует, какой ответ является правильным. Подбирайте примеры с известными ожидаемыми уровнями и обязательно проверяйте обновленные описания на независимых выборках перед их утверждением.