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

Роли и system prompt

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

У тебя в системе, скорее всего, будет несколько разных LLM-задач: парсер заявок, генератор BOM, ревьюер сметы, ассистент мастера. У каждого своя «роль». System prompt — это то место, где ты описываешь, кто сейчас говорит, в каких рамках, какой формат ответа. Один и тот же GPT-5.4 с разными system prompts ведёт себя как разные специализированные модели.

Что такое роли в API

Сообщение в API бывает одного из трёх типов:

• system — инструкция для всей сессии (характер, формат, ограничения).
• user — что пришло от пользователя (или от твоего Kotlin-кода).
• assistant — ответ модели. В истории диалога накапливаются предыдущие её ответы.

Минимальный пример на Kotlin

val response = openAi.chatCompletion {
    model = "gpt-5.4-mini"
    messages {
        system("""
            Ты парсер заявок на лестницы. Возвращай только JSON по
            схеме, указанной ниже. Не добавляй пояснений.
            Schema: { "floors": int|null, "wood_type": string, ... }
        """.trimIndent())
        user(order.rawText)
    }
}

Что здесь происходит: в system — роль парсера и формат ответа. В user — текст заявки от клиента. Модель возвращает строку — JSON. Ты её десериализуешь в data class.

Что обычно идёт в system prompt

• Кто ты и для кого. «Ты парсер заявок для системы управления производством лестниц».
• Цель задачи. «Преврати свободный текст клиента в структурированный заказ».
• Формат выхода. «JSON по схеме, без обёртки в markdown, без комментариев».
• Поведение на неоднозначностях. «Если поле не упомянуто — null. Не выдумывай».
• Стандарты домена. «Длины в миллиметрах, углы в градусах, высота — от пола до пола».
• Примеры (few-shot — см. предыдущую статью).

Сильный vs слабый system prompt

Слабый:

Ты помощник по лестницам. Помогай.

Сильный:

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

Задача: из свободного текста клиента извлечь структурированные данные и
вернуть их одним валидным JSON-объектом.

Правила:
- Все размеры в миллиметрах. Если клиент дал в метрах — переведи.
- wood_type: oak | pine | ash | unknown.
- floors: 2 или 3, иначе null.
- Если поле не упомянуто клиентом — ставь null (для wood_type — "unknown").
- Не выдумывай данные.
- Ответ: только JSON. Без пояснений, без markdown-обёртки.

Если текст клиента совсем бессмысленный, верни:
{"parse_error": "reason"}

Что здесь происходит: чёткая роль, правила по домену, поведение на редких случаях, жёсткий контракт на выход. На такой промпт модель отвечает предсказуемо.

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

• Для каждой LLM-задачи — свой system prompt в отдельном файле (prompts/parser.txt, prompts/bom_generator.txt). Не смешивай задачи в одном промпте.
• Держи в system prompt стандарты домена: единицы, названия, enum-значения. Это избавит от «лестница деревянная» вместо oak.
• Обязательно указывай fallback на парсинг-ошибку. LLM может получить мусор на входе, и молчать — хуже, чем вернуть parse_error.
• Версионируй промпты. Когда меняешь system prompt и запускаешь на проде — это такое же изменение, как новая миграция БД.

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