Примитивы (Вопросы)

Если вам требуется оценить уровень навыка, используйте Score с заданными градациями, такими как «нет опыта», «базовое знакомство», «ежедневное использование» и «глубокая экспертиза». Если нужно бинарное решение «да/нет», четко сформулируйте условие, например: «Указано ли в резюме, что кандидат использовал Python в коммерческой разработке?»

Если кажется, что подходят оба типа, отдайте предпочтение тому, чей ответ ваш код может использовать наиболее прямо. Выбор Choice между refund, rebook и information напрямую проецируется на три ветки выполнения в коде. Оценка Score степени раздражения клиента проецируется на числовой порог. Noul проецируется на простое условие if.

Что возвращает модель

Ответы также являются примитивами. Каждый тип вопроса возвращает типизированное значение, которое ваш код может сравнивать, сопоставлять с пороговыми значениями, сортировать, передавать в дальнейшую логику или помещать в состояние последующего запроса (см. Когда один вопрос зависит от другого).

Два фундаментальных свойства делают эти ответы компонуемыми:

• Каждый ответ строго ограничен предоставленными вариантами. Модель возвращает распределение вероятностей по вашим вариантам или уровням и никогда не выходит за их пределы. Вашему коду никогда не придется вычленять значение из сгенерированного текста.
• Каждый ответ независим. Ответ на один вопрос не становится скрытым контекстом для другого. Вы можете добавлять или удалять вопросы, не меняя результатов остальных.

В разделе Уверенность (Confidence) объясняется, как confidence вычисляется из probabilities и как использовать этот показатель для разграничения автоматических действий и эскалации человеку.

Обращение к конкретным полям

Оцениваемый контент — состояние (state) — часто представляет собой JSON-объект, состоящий из нескольких частей: переписки, записей базы данных, регламентов. Когда вопрос касается конкретной части, укажите ее в instructions с помощью пути через точку и индексы, заключенного в обратные кавычки. Модель точно поймет, какую часть состояния необходимо оценить.

Взгляните на диалог со службой поддержки из раздела State:

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

Эти два вопроса обращаются к сообщению клиента, регламенту и списаниям по путям:

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`?"
        ),
    },
}

Явные пути однозначно определяют, какие именно части структурированного состояния должны учитываться при вынесении суждения. Структурирование входных данных описано в разделе Состояние (State).

Задавайте несколько вопросов одновременно

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

Этот запрос одновременно классифицирует сообщение клиента, проверяет его срочность и оценивает степень раздражения:

<TypesafeExample
example={{
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',
],
},
},
}}
/>

Наши клиентские SDK предоставляют типизированные вопросы и ответы. В Python передайте словарь questions с объектами Choice, Noul и Score в вызов client.system_one(...). Этот запрос передает тикет и правила возврата один раз и получает типизированный ответ на каждый вопрос:

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)

Варианты установки и примеры для вашего языка программирования см. в разделе клиентские SDK.

Задавайте спекулятивные вопросы

Задавайте любые вопросы, которые могут потребоваться вашему коду, включая те, ответы на которые понадобятся лишь при определенных условиях, и позвольте коду самому решать, какие ответы использовать. Если обращение оказалось не отчетом о баге, просто проигнорируйте ответ о критичности ошибки. Мы называем это паттерном Спекулятивное ветвление (Speculative fan-out). В кукбуке по параллельным вопросам показано, как объединение 13 вопросов в один вызов обходится в 11.5 раз дешевле и выполняется в 9.6 раз быстрее, чем 13 отдельных вызовов, возвращая абсолютно идентичные ответы.

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

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

Например, приоритет тикета может складываться из трех вопросов типа Score: насколько критичен баг, насколько раздражен клиент и насколько подробно отчет описывает проблему для инженера. На странице Score этот запрос и код нормализации и взвешивания ответов подробно разобраны в разделе Разделение сложного суждения на несколько оценок Score. Этот подход называется паттерном Композитная оценка (Composite scoring).

Когда один вопрос зависит от другого

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

Разделение на два запроса — это исключение, а не правило. Если вопросы второго запроса можно было сформулировать относительно исходного состояния, задайте их в первом запросе и позвольте коду проигнорировать ненужные. В трех наших кукбуках второй запрос делается по обоснованной причине: в предложении навыков (Skill suggestion) в первом запросе ранжируются 182 навыка, а затем для топ-3 запрашивается полный текст и проводится повторная оценка; в восстановлении структуры (Structure recovery) сначала проверяется, разрывает ли перенос строки предложение, строки объединяются в блоки, а затем эти блоки классифицируются; в иерархической классификации (Hierarchical classification) каждый ответ Choice определяет, какие варианты будут предложены в следующем запросе.

Рекомендации по декомпозиции рабочего процесса на сфокусированные суждения см. в руководстве Как создавать решения с помощью TypeSafe.

Следующие шаги

Чтобы увидеть, как эти элементы объединяются в системные архитектуры, перейдите в раздел Паттерны.