28 дней со Spring AI: от простого чата до полноценного инструмента

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

Когда я проходил AI Advent Challenge этот режим прокрастинации сломался: 28 дней подряд у тебя есть ровно сутки. В 10:00 приходит задание, а в 10:00 следующего дня - дедлайн. Поэтому каждый день заканчивается одной из двух вещей: либо у тебя есть работающий кусок, либо ты точно понимаешь, где решение не выдержало и почему.

Разработка шла в стиле "vibe coding": главный артефакт - backlog "что сделать", минимум upfront-дизайна, максимум итераций и постоянная проверка, что базовая работоспособность не сломалась.

Самое принципиальное решение было не про "какую модель взять", а про стек. Вместо привычного "Python + что-то вокруг LLM" я остался в своем прод-стеке: Java + Spring Boot, а AI-часть собрал на Spring AI. Цель была прикладная: понять, насколько LLM-интеграции нормально живут в Java-стеке, если делать не "демо-чатик", а инструмент, который реально помогает в задачах и умеет:

• sync / stream / structured режимы,

• "память" и управление контекстом,

• tool calling с ограничениями,

• RAG по коду с цитатами,

• sandbox для тестов и команд,

• интеграции с GitHub/workspace,

• немного orchestration поверх этого.

Началось все с базового чата. Но по мере того как задания усложнялись, получилась связка "retrieval + инструменты + окружение" - когда модель не просто отвечает, а помогает искать по коду, проверять гипотезы и воспроизводимо выполнять сценарии вокруг проекта.

---

Где заканчивается "магия Spring AI"

Spring AI хорошо ускоряет старт, но важно понимать границу: он закрывает слой интеграции, а "прод-поведение" почти всегда рождается из вашей инженерной обвязки.

Что дает Spring AI "из коробки"

• ChatClient - единый API к моделям: prompt -> call()/stream() -> response.

• Advisors - прослойки вокруг вызова модели (как middleware).

• Chat Memory - хранение истории/фактов вне модели и подмешивание их в запрос по conversationId.

• Tools - tool calling / function calling внутри приложения.

• RAG - базовые паттерны retrieval + интеграции для vector store.

• Observability - точки интеграции в метрики/трейсы вокруг вызовов.

Что почти всегда нужно добавить, если вы строите "боевую" систему

• Token budget + preflight: оценить заранее "влезает ли запрос" и что резать, если не влезает.

• Контекст-менеджмент: summarization/pruning/pinned facts + лимиты на tool outputs и RAG-контент.

• Безопасность инструментов: allow-list, таймауты, лимиты ресурсов, dry-run.

• RAG как пайплайн: multi-query, дедуп, пост-обработка + цитаты.

• Sandbox для команд/тестов: изоляция, ограничения, cleanup.

Два коротких "продовых" примера, почему это нужно:

• Стриминг может оборваться на середине - а вы все равно должны корректно закрыть соединение, не оставить подписки и сохранить "что успели сгенерировать".

• Инструмент может вернуть огромный вывод (логи/дифф/тесты) - и если не ограничить размер, он "съест" весь контекст и ухудшит качество следующего шага.

Запуск проекта и пререквизиты Быстрый старт (docker-compose)

---

Практические блоки

Блок 1. ChatClient и режимы: sync, stream, structured

Проблема

В реальных системах почти всегда нужны три сценария:

1. Интерактивный чат - нужен streaming (UX), устойчивость к разрывам, понятная деградация.

2. Сервисные вызовы - удобнее sync: проще таймауты/ретраи/тестирование.

3. Structured output - нужен контракт, валидация и предсказуемая обработка ошибок.

4. Несколько моделей - под разные задачи (скорость/стоимость/контекст), и необходимость тюнить параметры запроса на лету - без релиза (например, overrides на temperature/top_p/max_tokens под конкретный запрос).

Что дает Spring AI

ChatClient - единый интерфейс, где и sync, и stream выглядят одинаково по стилю.

Что пришлось достроить

• Развести режимы по контракту API: streaming-чат != sync-операция != structured вызов.

• Устойчивый lifecycle стрима:

  • корректно закрывать SSE,

  • не оставлять подписки,

  • обрабатывать таймауты/ошибки.

• Делать preflight до открытия стрима (чтобы не начинать SSE, если запрос заведомо "не влезет").

• Пробрасывать conversationId везде, где есть сессия/память.

Пример (фрагмент): preflight + conversationId + tool callbacks

---

Блок 2. Advisors: точка сборки логики вокруг вызова модели

Проблема

Очень быстро выясняется, что обычный "вызов модели" - не самый сложный кусок. Интересное начинается вокруг вызовов:

• подключить память,

• добавить RAG,

• подмешать системные инструкции/политики,

• нормализовать и ограничить контекст,

• включить наблюдаемость.

Если размазать это по контроллерам/сервисам - получится код, который сложно расширять и еще сложнее поддерживать.

Что дает Spring AI

Advisors - middleware-слои вокруг вызова модели, подключаемые через .advisors(...).

Практически полезная мысль: advisors - это место, где удобно держать "стандартные" части поведения, например:

• memory-подмешивание,

• retrieval-подмешивание,

• trimming/budget-политики,

• safety/policy-правила,

• observability-обвязку.

Что пришлось достроить

• Политики: что добавлять в контекст всегда, что - только для отдельных режимов, сколько токенов выделять под память/tools/RAG.

• Ограничение размеров tool outputs и retrieval документов (иначе они "съедают" окно).

• Вокруг advisor-цепочки - сервисные "рамки": preflight, лимиты, allow-list tools.

Где это в проекте

Ключевой "якорь", с которого все начинает работать согласованно - привязка conversationId:

• ChatStreamController.java

• StructuredSyncService.java

Именно там видно: .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, ...)), после чего память и любые другие advisors начинают работать по одному и тому же ключу.

---

Блок 3. Память и контекст: как вообще устроена "память" у LLM

Важный факт

У LLM нет памяти в привычном смысле: модель не хранит состояние между запросами и отвечает только на то, что вы дали ей в контекст конкретного вызова. В Spring AI это прямо отражено в концепции "внешней памяти": Chat Memory.

Отсюда вытекает ключевая инженерная мысль:

Когда кто-то говорит "у нас есть память в llm", обычно это означает: мы где-то храним историю/факты и каждый раз решаем, какую часть вернуть в prompt.

Проблема

Контекстное окно у модели ограничено, а в запрос "лезут":

• история диалога,

• system prompt,

• tool schemas и tool outputs,

• RAG-документы,

• сама задача пользователя.

Что может излишне "раздуть" контекст после чего модель может начать теряться в переданных токенах.

Что дает Spring AI

ChatMemory и ChatMemoryRepository + типовые стратегии вроде "окна сообщений".

Что пришлось достроить

• Token budget + preflight: оценка токенов и решение "что резать/сжимать" до вызова модели.

• Summarization истории, но контролируемо (очередь + backpressure + деградации).

• Хранение памяти в БД, чтобы переживать рестарты и масштабирование.

• Паттерн "summary + tail": краткая сводка + хвост последних сообщений.

Полезная практическая стратегия деградации (в общих чертах):
сначала ограничивать tool outputs -> потом ограничивать RAG -> потом сжимать историю -> и только потом "не выполняем запрос".

Пример (фрагмент): оценка токенов Пример (фрагмент): summarization очередь + деградация Пример (фрагмент): summary + tail без дублей

---

Блок 4. Structured output: когда нужен объект, а не текст

Structured output - это подход, где вы просите модель вернуть ответ в строго заданном формате (чаще всего JSON), чтобы затем:

• распарсить в DTO,

• провалидировать,

• и безопасно встроить в бизнес-логику (пайплайны, оркестрации, автоматические решения).

Где это реально полезно

• классификация (например, "определи тип запроса"),

• извлечение структурированных данных из текста (сущности, поля формы),

• построение плана действий (список шагов, параметры инструмента),

• генерация настроек/конфига,

• машиночитаемые промежуточные результаты между шагами оркестрации.

Что дает Spring AI

Structured Output Converter и связанные механики.

Что важно понимать про "строгость" и провайдеров

У крупных провайдеров есть механики, которые помогают добиваться более предсказуемого структурированного формата, но это не отменяет необходимости валидации на вашей стороне:

• OpenAI: Structured Outputs

• Anthropic: Structured Outputs

Даже при "строгих" подсказках/схемах в реальности могут появлятся типовые сбои:

• "почти JSON" (лишний текст до/после),

• сломанные кавычки/экранирование,

• несоответствие типов,

• недостающие обязательные поля или "лишние" поля,

• частичный ответ из-за лимита токенов,

• сложности со streaming-парсингом, если пытаться разбирать JSON "на лету".

Поэтому structured output в проде - это контролируемая, но все равно best-effort интеграция, где валидация и fallback - обязательны.

Отдельный плюс structured-подхода: он хорошо тестируется. Можно делать контрактные/"golden"-тесты на JSON и на DTO-валидацию, а не пытаться тестировать "красоту текста".

Пример (фрагмент): защита от пустого ответа

---

Блок 5. Tools: почему tool calling стал стандартом

Если упростить до одной фразы: LLM хороша в рассуждении и планировании, но "действия" она совершает через инструменты.

Tool calling (оно же function calling / tool use) - де-факто стандартный способ "подключить внешний мир" к модели:

• OpenAI: Function calling

• Anthropic: Tool use

На практике это означает: поиск по данным, вызовы внутренних сервисов, работа с репозиторием, запуск тестов - все это оформляется как инструменты с четким контрактом.

Что дает Spring AI

Tools: ToolCallback, @Tool-аннотации и регистрация tool'ов.

Что пришлось достроить

В системе tools - это не "магия модели", а API-контракты + контроль исполнения:

• allow-list инструментов под режим/запрос,

• классификация по риску: read / write / execute / external,

• таймауты и лимиты на все (включая внешние API),

• "dry-run first" для любых операций, меняющих состояние,

• ограничение размера результатов инструментов (чтобы не "съесть" контекст),

• предсказуемые ошибки "почему нельзя" вместо непойманных исключений.

Пример (фрагмент): GitHub tool как контракт + лимиты Пример (фрагмент): preview/dry-run как обязательный шаг перед опасными действиями

---

Блок 6. Sandbox и live-окружение: контроль обязателен

Как только у модели появляются инструменты уровня "выполни команду" / "запусти тесты", появляется новый класс рисков:

• таймауты,

• ресурсы (CPU/RAM/disk),

• изоляция workspace,

• очистка после выполнения,

• безопасность параметров и команд.

И тут важен практический момент:

Что дает Spring AI

Spring AI не "сделает sandbox за вас" - исполнение остается зоной ответственности приложения.

Что пришлось достроить

• Docker runner с профилями (gradle/maven/npm/…),

• таймауты и лимиты ресурсов,

• ограничения команд (лучше allow-list/шаблоны, чем произвольные строки),

• изоляция и cleanup.

Пример (фрагмент): детект типа проекта

---

Блок 7. RAG по коду, как один из инструментов: что это и зачем

RAG (Retrieval-Augmented Generation) - подход, где вы не надеетесь на "память модели", а подключаете к ответу вашу базу знаний:

1. заранее индексируете источники (код/доки/вики),

2. на запрос находите релевантные фрагменты (retrieval),

3. добавляете их в контекст,

4. модель отвечает с опорой на реальные куски данных.

Это дает:

• меньше галлюцинаций по вашему проекту,

• возможность отвечать "по факту кода", а не "как обычно принято",

• проверяемость через цитаты (file_path/чанк).

Spring AI описывает RAG как паттерн: RAG.

Немного о ETL-пайплайне

Если данных много (репозитории, монорепы, доки), "просто закинуть в vector store" быстро не получится. Почти всегда нужна обертка в виде ETL:

• Extract: собрать источники, обновления, диффы,

• Transform: декодирование, фильтры, чанкинг, метаданные, дедуп,

• Load: embeddings -> vector store, контроль версий, пересборка.

В Spring AI это выделено отдельным понятием: ETL Pipeline.

Что пришлось достроить

• Индексация с защитой от мусора: skip binary, skip unchanged.

• Retrieval как пайплайн:

  • multi-query,

  • дедуп,

  • topK после merge,

  • пост-обработка/реранкинг.

• "Цитаты" (file_path/чанк) как обязательный формат.

• Бюджеты: ограничивать число документов и размер контента в prompt.

• Набор "отладочных сигналов": что реально попало в контекст, сколько, почему.

Пример (фрагмент): skip binary + skip unchanged Пример (фрагмент): multi-query + дедуп + topK после merge Пример (фрагмент): контекст с citations

---

Блок 8. Observability и дисциплина логов

LLM-часть легко превратить в "черный ящик", который сожрет весь ваш бюджет, если не мерить:

• latency по режимам (stream/sync/structured),

• ошибки (где именно: модель, tools, retrieval, sandbox),

• токены/стоимость.

Spring AI поддерживает интеграцию с наблюдаемостью через Observability.

Минимальный "боевой" дашборд, который обычно окупается

• latency p50/p95 по режимам,

• tokens in/out (и "fallback-оценка", если провайдер не отдает usage),

• tool success/error rate + latency,

• retrieval empty rate,

• cost estimate.

---

Практикум: сценарий, который можно пройти руками

Идея - не просто "почитать про подходы", а включить инструменты, дать ассистенту репозиторий и прогнать реальные сценарии: анализ кода, поиск, проверка сборки/тестов, объяснение архитектуры, ревью изменений.

Подготовка

1. Поднимите проект по README (backend + backend-mcp + frontend).

2. Убедитесь, что настроены ключи, которые нужны сценарию (LLM-провайдер, GitHub).

3. Во фронтенде включите доступные MCP-инструменты (в проекте есть каталог инструментов, который UI использует, чтобы показать "что доступно").

Промпты для копирования: анализ, сборка, поиск, ревью

---

Что удалось достичь за 28 дней

Самый полезный эффект оказался не в "количестве фич", а в том, что ежедневная работа с LLM быстро калибрует ожидания и вырабатывает понимание что это такое и с чем его едят.

За этот месяц я намного четче понял:

• где LLM реально ускоряет работу (обзор кода, сводки, поиск связей, генерация черновиков, классификация/роутинг);

• где она стабильно ошибается без "обвязки" (контекст раздувается, structured "плывет", инструменты без лимитов начинают вести себя непредсказуемо);

• что качество ответа часто определяется не "умностью модели", а качеством контекста (RAG, цитаты, лимиты, preflight);

• что "инструменты" - не дополнение, а центр практического применения: модель рассуждает, а действия делает через tool-слой;

• что без наблюдаемости и дисциплины логов вы слишком поздно узнаете, где именно "дорого", "долго" и "ломается".

---

Финальная мысль

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

Поэтому рабочая интеграция выглядит не как "мы прикрутили чат", а как полноценная инженерная система, где LLM играет роль оркестратора:

• RAG дает модели факты из ваших данных, а не "догадки",

• tools/MCP дают модели действия (прочитать код, запустить тесты, сходить в GitHub),

• контекст-менеджмент делает все это возможным в рамках ограниченного окна,

• sandbox и ограничения делают действия безопасными и воспроизводимыми,

• observability объясняет, что происходит и сколько это стоит.

А дальше уже вы выбираете режим работы процесса:

• human-in-the-loop, когда важны контроль и подтверждения,

• human-out-of-the-loop, когда готовы автоматизировать целиком отдельные шаги.

Если относиться к LLM именно так - как к компоненту, вокруг которого нужна дисциплина, ограничения и измеримость - тогда "AI-часть" начинает жить в Java/Spring так же естественно, как любые другие части Spring зоопарка.

---

Репозиторий

GrinRus/ai_advent_challenge