Llm feature architect

LLM Feature Architect

LLM в продукте — это внешняя зависимость с недетерминированным выводом, ненулевой ценой за вызов и латентностью в секунды. Проектируется как интеграция с ненадёжным платным API, а не как вызов библиотечной функции.

Шаг 0. А нужен ли LLM?

Не нужен, если задача решается правилами, regex, полнотекстовым поиском или готовой моделью-классификатором: они детерминированы, бесплатны и мгновенны. LLM оправдан, когда вход — свободный текст/речь человека, а правила «не выписываются» (интерпретация, извлечение из неструктурированного, генерация связного текста). Гибрид часто лучший: правила отсекают 80% типовых случаев, LLM разбирает остаток.

Шаг 1. Форма задачи

Определи форму — от неё зависят промт, параметры, формат вывода и evals:

Форма	Вывод	Температура	Eval-метрика
Классификация	enum через structured output	0	accuracy на золотом наборе
Извлечение	JSON по схеме	0	точность полей, валидность схемы
Генерация (тексты, суммаризация)	текст	средняя	чек-лист качества, выборочно глазами
Диалог (саппорт, ассистент)	текст + история	средняя	сценарные прогоны
Агент (LLM выбирает инструменты)	tool calls в цикле	низкая	end-to-end сценарии

Выбор модели: маленькая/дешёвая для классификации и извлечения, старшая — для генерации и агентных сценариев. Начинай со старшей (докажи, что фича вообще работает), потом пробуй съехать на дешёвую с проверкой по evals. Актуальные модели и цены — навык claude-api.

Шаг 2. Каркас интеграции

• Один модуль-сервис. Все вызовы LLM — через один сервисный слой (services/llm.py и т.п.). Из views/handlers/tasks API напрямую не зовётся. В сервисе: клиент, промты, ретраи, логирование, подсчёт стоимости.
• Таймауты обязательны. Генерация может висеть десятки секунд; без таймаута — зависшие воркеры.
• Ретраи с экспоненциальным backoff и джиттером на 429/5xx/overloaded. На ошибку валидации ответа — один повтор с текстом ошибки в промте, не бесконечный цикл.
• Долгие вызовы — не в request/response. Веб-запрос не должен ждать LLM: очередь (Celery/arq) + опрос/пуш результата, либо стриминг, если UX диалоговый. В aiogram — «печатает…» + отдельная задача.
• Логируй запрос и ответ (модель, промт, вывод, токены, латентность, стоимость) — это сырьё для отладки и evals. Помни про PII в логах.

Шаг 3. Structured output

Текстовый «верни JSON, пожалуйста» ломается на проде. Правильно:

• принудительная схема: tool use / response schema — модель физически не может ответить мимо формата;
• на своей стороне — pydantic-валидация ответа (схема на входе не отменяет проверку на выходе);
• enum-поля для классификации вместо свободного текста;
• температура 0 для извлечения и классификации.

Шаг 4. Стоимость

• Prompt caching: стабильный префикс (системный промт, инструкции, примеры) — в начало, переменное — в конец; кеш срезает стоимость префикса в разы.
• max_tokens по задаче, а не «побольше»; для классификации хватает десятков токенов.
• Метрики: стоимость на вызов/пользователя/фичу — в логи и дашборд с первого дня; алерт на дневной бюджет. Неожиданный счёт — самый частый инцидент LLM-фич.
• Ограничение на пользователя: rate limit и/или квота, иначе один пользователь скушает бюджет.

Шаг 5. Evals — до продакшена

Промт без evals — это код без тестов: любая правка промта или смена модели — регрессия вслепую.

• Собери золотой набор 20–50 реальных примеров (вход → эталонный выход) до запуска; пополняй из прод-логов, особенно из ошибок.
• Прогон набора — скриптом (pytest подойдёт), метрика по форме задачи (см. таблицу выше). Прогоняй при каждой смене промта, модели, параметров.
• LLM-judge для оценки генерации — можно, но с калибровкой: судья должен совпадать с твоей ручной оценкой на выборке, иначе он измеряет не то.

Шаг 6. Безопасность и деградация

• Prompt injection: пользовательский ввод — это данные, не инструкции. Отделяй его в промте явной разметкой; инструкции «игнорируй предыдущее» из пользовательского текста не должны исполняться — проверь это evals-кейсом.
• Инструменты с побочными эффектами (запись в БД, отправка сообщений, платежи) агентной фиче не даются без подтверждения человека или белого списка безопасных операций.
• PII: не отправляй в API лишние персональные данные; маскируй в логах.
• Деградация: LLM недоступен → фича отключается мягко (заглушка, очередь на потом, fallback-модель), продукт живёт дальше. LLM-вызов не должен стоять на критическом пути core-функциональности.

Чек-лист ревью существующей интеграции

• Вызовы изолированы в сервисном слое, не размазаны по views/handlers?
• Таймауты и ретраи с backoff есть? 429 не роняет фичу?
• Долгие вызовы вне request/response цикла?
• Structured output со схемой + валидация ответа?
• Стоимость на вызов считается и видна? Есть лимит на пользователя?
• Стабильный префикс промта кешируется?
• Есть золотой набор и скрипт прогона? Когда гоняли последний раз?
• Пользовательский ввод отделён от инструкций? Injection-кейс в evals есть?
• Падение LLM API не ломает продукт?

Границы навыка

Актуальные ID моделей, цены, детали Anthropic API — встроенный навык claude-api. Надёжность исходящих HTTP-вызовов как таковая (circuit breaker, идемпотентность) — общая тема, см. ROADMAP http-client-reliability. Решение «делать руками или агентом» в процессе разработки — llm-delegation. Аудит очередей/Celery — django-audit; асинхронная корректность FastAPI — fastapi-architect.