Интенсив 21–22.11 · БесплатноБесплатный 2-дневный интенсив по вайбкодингу 21–22 ноября в 16:00 МСК (Сб–Вс) · Живой Поток 3 стартует 23.11Записаться бесплатно →Поток 3 (23.11)
РелизРазбор · На радарHabr AI→ оригинал

Команда вынесла 203 КБ промптов из PHP-кода в YAML — это треть всего кода

Команда PHP-проекта держит 203 КБ промптов — примерно треть объёма всего PHP-кода — в YAML-файлах в Git, а не в коде. Раньше промпты правили в админке, и прод расходился со стейджем без всякой истории правок. Теперь в одном файле лежат текст, модель, температура и формат ответа, а код вызывает такую «способность» по имени. Вывод: промпт стоит версионировать как код, вместе с параметрами генерации.

AI-обработка оригинала Habr AI; редакция Hamidun News
Команда вынесла 203 КБ промптов из PHP-кода в YAML — это треть всего кода
Источник: Habr AI. Коллаж: Hamidun News.
Слушать статью
Паспорт материала и цифры
ПараметрДанные
ПервоисточникHabr AI ↗
Главный редактор
Ключевой факт #1Пользовательские данные подставляют через str_replace после Blade
Ключевой факт #2Смысловой ретрай — 2 попытки, сетевой — 3 с растущей паузой
На проде в лог пишут только ошибкив запросах лежит переписка

Где хранить промпты — вопрос, который рано или поздно встаёт перед каждой командой, строящей продукт на LLM. Один PHP-проект ответил на него радикально: в репозитории лежит 203 килобайта промптов, а это примерно треть объёма всего PHP-кода. При этом в самом коде нет ни одного промпта. Все они — YAML-файлы (простой текстовый формат для конфигов), которые проходят ревью, версионируются в Git и выкатываются вместе с релизом. Проект под NDA, поэтому автор выдумал примеры промптов на сценарии с ботом поддержки, но структура файлов, код обработки и грабли настоящие. По дороге выяснилось, что «вынести промпт в конфиг» — не одно решение, а десяток мелких, и каждое легко принять неправильно.

Почему не в коде и не в админке

Промпт в коде — это деплой ради запятой. Но у промптов есть специфика: правит их не разработчик, а тот, кто отвечает за качество ответов модели. Подкрутил формулировку, посмотрел на выдачу, откатил, попробовал иначе. Цикл измеряется часами, а не спринтами.

Очевидный ответ — редактируемое поле в админке. Команда так и сделала в первой версии и получила типичный результат: промпт на проде отличается от промпта на стейдже, никто не помнит, кто и зачем поменял абзац про формат ответа, откатиться можно только по памяти. Ревью нет, истории нет, дифф посмотреть негде. Git закрывает все четыре проблемы ценой одной: чтобы поправить промпт, нужно уметь сделать коммит. Для этой команды обмен оказался приемлемым.

Единицей хранения стала не строка текста, а «способность» — например, summarize-ticket. В одном файле лежат провайдер, модель, параметры генерации, системный и пользовательский шаблоны для каждого языка и ожидаемый формат ответа. Причина простая: один и тот же текст с температурой 0,2 и 0,9 — это два разных поведения. Если температура живёт в коде, а текст в файле, вчерашний результат не воспроизвести. Код вызывает способность по имени и ничего не знает про модель или провайдера.

Шаблоны, безопасность и мелкие грабли

Промпт почти никогда не бывает константой: в него подставляют историю сообщений и контекст. Команда не стала писать свой шаблонизатор и подключила Blade одной строкой. Цена понятна: Blade компилирует шаблон в PHP и исполняет его, значит, содержимое YAML-файла — исполняемый код. Пока файлы проходят ревью, это приемлемо. Но если продакт захочет редактировать промпты прямо в админке, полноценный шаблонизатор туда пускать нельзя: нужен ограниченный движок без выполнения кода и доступа к файловой системе.

Вторая защита — порядок подстановки. Сначала рендерится доверенный шаблон из репозитория, и только потом обычным str_replace в готовый текст вставляются строки от пользователя, например имя. Если отдать имя внутрь шаблонизатора, человек, назвавшийся {{ config('app.key') }}, получит в ответе ключ приложения.

Ещё несколько практических деталей:

  • Пять языков — это не перевод. Модель на русском иначе держит формат и чаще сбивается на другой язык, поэтому в неанглийских шаблонах появляются добавки вроде требования отвечать на нужном языке. Тест «смысл совпадает» бесполезен, а проверка «во всех локалях есть шаблон и одинаковый набор подстановок» нужна: переводчик легко переведёт {user} в слово «пользователь».
  • В способности модель указана коротким алиасом, а расшифровка лежит в файле провайдера. Когда провайдер переименует модель, правится один файл, а не девять.
  • В YAML хранится имя переменной окружения вроде ${FAST_CLOUD_KEY}, а не сам ключ. Настоящий ключ, вставленный «на минутку», останется в истории Git навсегда, поэтому на ревью это проверяют отдельно.
  • Кавычки вокруг чисел в YAML превращают их в строки, и провайдер отвечает ошибкой валидации. Команда приводит параметры к числам в коде.

Структурированные ответы, ретраи и логи

Провайдеры по-разному умеют отдавать структурированный ответ, поэтому в конфиге три уровня: полноценная JSON-схема, только режим «валидный JSON» и «ничего». Система деградирует по лестнице. Если провайдер понимает схему, она уходит в response_format. Если умеет только JSON-режим, схема дописывается текстом в конец системного промпта на языке пользователя. Но это просьба, а не гарантия, поэтому есть третий слой: из ответа вырезается всё между первой { и последней }, потому что модель любит добавить «Конечно! Вот ваш ответ:». Результат парсится и проверяется по схеме. Автор признаётся, что долго сопротивлялся этой функции, пока не посмотрел, сколько ответов она спасает.

Ретраи делятся на два вида. Сетевой сбой (таймаут, 502, разорванное соединение) лечится обычным повтором с экспоненциальной паузой, до трёх попыток. Смысловой сбой — код 200, но пустая строка, невалидный JSON или структура не проходит по схеме — требует повторить весь запрос, и таких попыток ровно две. Каждая стоит денег и секунд ожидания пользователя, а если модель дважды не справилась с одним промптом, проблема в промпте или в модели, а не в удаче. Честнее показать ошибку и записать случай в лог.

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

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

Сюжет

Вопросы и ответы по материалу

Что известно по теме: почему не в коде и не в админке?

Промпт в коде — это деплой ради запятой. Но у промптов есть специфика: правит их не разработчик, а тот, кто отвечает за качество ответов модели. Подкрутил формулировку, посмотрел на выдачу, откатил, попробовал иначе. Цикл измеряется часами, а не спринтами. Очевидный ответ — редактируемое поле в админке.

Что известно по теме: шаблоны, безопасность и мелкие грабли?

Промпт почти никогда не бывает константой: в него подставляют историю сообщений и контекст. Команда не стала писать свой шаблонизатор и подключила Blade одной строкой. Цена понятна: Blade компилирует шаблон в PHP и исполняет его, значит, содержимое YAML-файла — исполняемый код. Пока файлы проходят ревью, это приемлемо. Но если продакт захочет редактировать промпты прямо в админке, полноценный шаблонизатор туда пускать нельзя: нужен ограниченный движок без выполнения кода и доступа к файловой системе.

Что известно по теме: структурированные ответы, ретраи и логи?

Провайдеры по-разному умеют отдавать структурированный ответ, поэтому в конфиге три уровня: полноценная JSON-схема, только режим «валидный JSON» и «ничего». Система деградирует по лестнице. Если провайдер понимает схему, она уходит в response_format. Если умеет только JSON-режим, схема дописывается текстом в конец системного промпта на языке пользователя. Но это просьба, а не гарантия, поэтому есть третий слой: из ответа вырезается всё между первой { и последней }, потому что модель любит добавить «Конечно!

ЖХ
Жемал Хамидун — CPO Alpina Digital, продакт-менеджер AlpinaGPT. Делает AI-продукты с 2019 года. Hamidun News — pet project, который вырос в production-агрегатор с 6000+ читателей.
✦ Единое AI-пространство · Nomad

Протестируйте новые LLM и мультимодальные модели в одном окне

Платформа Nomad AI (nomadnet.ai) даёт прямой доступ к Claude Opus 5.5, GPT-6, Gemini 3.1, DeepSeek и автономным агентам без VPN, зарубежных карт и зоопарка подписок.

Открыть Nomad AI →Автономный Nomad Agent
Что вы думаете?
Загружаем комментарии…