Перевод с разбором · для Вани

Примеры (few-shot)

Зачем тебе это нужно

Для структурированных задач — парсинг заявки, формирование сметы, классификация типа лестницы — примеры работают лучше любого словесного описания формата. Описание говорит, как должно быть; пример показывает, как это выглядит. Для твоего кода-потребителя JSON это критично.

Техника называется few-shot (или multishot) — несколько пар вход-выход прямо в промпте. Противоположное zero-shot: просим без примеров.

Три свойства хорошего набора примеров

• Релевантные. Похожи на реальные заявки, которые приходят.
• Разнообразные. Покрывают варианты: полные заявки, обрывочные, с опечатками, про маршевые и винтовые лестницы.
• Структурированные. Каждый пример в теге <example>, набор — в <examples>. Модель чётко отличает примеры от инструкций.

Оптимум — 3–5 примеров. Больше — риск переобучения на них.

Как это выглядит в промпте парсинга заявки

Ты парсер заявок на деревянные лестницы. Возвращай JSON по схеме.

<examples>
  <example>
    <input>Здравствуйте, нужна лестница на 2 этаж, из дуба. Высота пролёта около 2.8 м.</input>
    <output>{"floors": 2, "wood_type": "oak", "approx_run_length_mm": 2800, "notes": ""}</output>
  </example>
  <example>
    <input>Хочу винтовую лестницу, сосна, диаметр 1.6м</input>
    <output>{"floors": null, "wood_type": "pine", "approx_run_length_mm": null, "notes": "винтовая, диаметр 1.6 м"}</output>
  </example>
  <example>
    <input>Надо лестницу</input>
    <output>{"floors": null, "wood_type": "unknown", "approx_run_length_mm": null, "notes": "данных недостаточно"}</output>
  </example>
</examples>

Заявка клиента:
{{USER_MESSAGE}}

Что здесь происходит: три разных типа заявки — детальная, частичная, почти пустая. Показываем модели, как реагировать на каждую. {{USER_MESSAGE}} — подстановка из твоего Kotlin-кода.

Как подставить пример в Kotlin

val prompt = promptTemplate
    .replace("{{USER_MESSAGE}}", order.rawText.trim())

val response = openAi.chatCompletion {
    model = "gpt-5.4-mini"
    messages {
        system(prompt)
        user("Верни JSON по схеме.")
    }
}
val json = response.choices.first().message.content
val parsed = Json.decodeFromString<ParsedOrder>(json)

Что здесь происходит: шаблон промпта читается из файла, в нём подставляется реальный текст заявки, запрос уходит в LLM, ответ парсится через kotlinx.serialization в data class. Модель возвращает чистый JSON — потому что так показано в примерах.

Частые ошибки

• Однотипные примеры. Модель решит, что вход всегда такого вида — и начнёт подгонять новые заявки под шаблон.
• Примеры без разметки. Если просто писать «вот примеры:» и три куска текста — модель путает их с реальным запросом.
• «Чистые» примеры. Не добавляй только идеальные — обязательно включи кейсы с пропусками и неоднозначностями, иначе модель будет паниковать на реальных данных.

Что это значит для твоей системы

• В файле src/main/resources/prompts/parse_order.txt держи 3–5 few-shot примеров. Все из реальных заявок (обезличенных).
• Для каждой LLM-фичи (парсинг, смета, классификация) — свой набор примеров. Не пытайся вмещать всё в один универсальный промпт.
• Один пример должен покрывать «пустую» заявку (ничего не понятно) — чтобы модель знала, как правильно вернуть «данных недостаточно», а не выдумывать значения.
• Прогоняй test-фикстуру после каждого изменения примеров. Новый пример может внезапно ухудшить поведение на соседних кейсах.

Полная версия — в docs/use-examples.html.