ML/AI Engineer на Python: Backend, AI-агенты, интеграции и RAG

Архитектура AI-Backend: API, сервисы, данные и жизненный цикл

AI-Backend — это серверная часть приложения, которая принимает запросы (например, от веба/мобилки), выполняет бизнес-логику и возвращает ответ. В AI-сценариях добавляются особые требования: работа с LLM, RAG (поиск по знаниям + генерация), агенты и инструменты, хранение эмбеддингов, асинхронные задачи, наблюдаемость качества и стоимости.

В этой статье мы соберём практический каркас архитектуры, который дальше будем наполнять технологиями: FastAPI, очереди задач, векторные БД, интеграции, пайплайны оценки, деплой и мониторинг.

Что делает AI-Backend отличным от обычного Backend

Обычный Backend чаще всего:

работает с предсказуемыми SLA по времени ответа

опирается на детерминированные правила и запросы к БД

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

AI-Backend дополнительно должен уметь:

управлять недетерминированностью (LLM может отвечать вариативно)

контролировать стоимость (токены, запросы к внешним API)

обеспечивать безопасность данных (PII, секреты, утечки в промптах)

поддерживать жизненный цикл знаний (обновление документов, переиндексация)

измерять качество (оценка ответов, регрессии, A/B)

Базовые термины (чтобы дальше не было “магии”)

LLM — большая языковая модель, которая генерирует текст по входному контексту.

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

Контекст — то, что мы передаём модели вместе с промптом: история диалога, документы, извлечённые факты.

RAG (Retrieval-Augmented Generation) — подход, где перед генерацией мы находим релевантные фрагменты знаний (retrieval), а затем просим модель ответить, опираясь на них.

Эмбеддинги — числовые векторы, представляющие смысл текста; используются для семантического поиска.

Векторная БД — хранилище, оптимизированное под поиск ближайших векторов (semantic search).

Агент — компонент, который не просто отвечает, а планирует шаги и вызывает инструменты (поиск, БД, внешние API).

Слои архитектуры: как разложить систему по полкам

Надёжнее всего думать об AI-Backend как о нескольких слоях с чёткими контрактами.

!Слоистая схема AI-Backend и основные зависимости

API-слой

Задачи API-слоя:

принимать запросы и валидировать входные данные

аутентифицировать пользователя и проверять права доступа

лимитировать запросы (rate limiting) и защищать от злоупотреблений

отдавать ответы в стабильном формате (контракт)

Типовой стандарт описания API — OpenAPI. Он поддерживается, например, FastAPI.

Полезные источники:

FastAPI Documentation

OpenAPI Specification

Пример контракта (упрощённо), который удобен для AI-эндпоинтов:

В ответе полезно возвращать не только текст, но и технические метаданные:

Сервисный слой

Сервисный слой — место, где живёт бизнес-логика и оркестрация AI.

Чаще всего он состоит из нескольких подкомпонентов:

Orchestrator: собирает шаги пайплайна (проверки, retrieval, вызов модели, постобработка).

RAG-модуль: поиск документов, фильтрация, сбор контекста.

Agent-модуль: планирование шагов и вызов инструментов.

Tooling/Integrations: обёртки над внешними сервисами (CRM, Jira, платежи, почта).

Guardrails: правила безопасности и качества (проверка PII, запреты, форматы).

Практическая рекомендация: разделяйте детерминированную бизнес-логику и генеративную.

Детерминированное должно быть проверяемым тестами и иметь чёткие правила (например, расчёты, доступы).

Генеративное должно быть ограничено рамками (контекст, инструкции, допустимые действия) и иметь наблюдаемость.

Слой данных

AI-Backend почти всегда использует несколько типов хранилищ.

| Тип данных | Что хранит | Типичные технологии | Почему это нужно | |---|---|---|---| | Операционные данные | пользователи, сессии, права, сущности продукта | PostgreSQL | транзакционность и консистентность | | Кэш | результаты retrieval, токены, лимиты | Redis | ускорение и защита от повторных вычислений | | Векторные данные | эмбеддинги документов/чанков | Weaviate, Pinecone, Qdrant | семантический поиск для RAG | | Файлы/артефакты | исходные документы, логи, датасеты | S3-совместимые хранилища | дешёвое хранение больших объектов | | Журналы/метрики | события, трассировки, ошибки | OpenTelemetry-совместимый стек | наблюдаемость и отладка |

Ключевая идея: векторная БД не заменяет PostgreSQL. Она решает задачу “найти похожее по смыслу”, а реляционная БД — задачу “хранить и связывать сущности продукта”.

Асинхронные задачи и очереди

Часть операций нельзя делать в синхронном API-запросе:

индексация документов и переиндексация

пересчёт эмбеддингов

батч-оценки качества

генерация отчётов

Для этого используют очередь задач и воркеры (например, Celery).

Celery Documentation

Два главных сценария: RAG и агент

RAG-пайплайн (поиск + генерация)

Минимальный жизненный цикл запроса в RAG:

API принимает запрос и проверяет права.

Orchestrator нормализует текст и определяет “режим” (чат/поиск/инструкция).

Retrieval ищет релевантные фрагменты в векторной БД.

Формируется контекст: выбранные фрагменты + метаданные (источник, дата, права).

LLM генерирует ответ на основе контекста.

Постобработка: формат, ссылки на источники, фильтры безопасности.

Логирование: токены, время, какие документы использованы.

!Последовательность обработки запроса в RAG

Агентный сценарий (планирование и инструменты)

Агент отличается тем, что может выполнять несколько шагов и вызывать инструменты. Например:

“Посмотри статус заявки в Jira и дай резюме”

“Собери данные из CRM и составь письмо клиенту”

Чтобы агент был безопасным:

инструменты должны иметь строгие входные схемы

права проверяются до выполнения действий

ввод/вывод логируются и трассируются

ограничиваются время, количество шагов и бюджет токенов

Если вы используете фреймворки для агентов, важно понимать, что это всего лишь библиотека оркестрации, а архитектурные обязанности (безопасность, данные, наблюдаемость) остаются на вашей стороне.

LangChain Documentation

Жизненный цикл данных для RAG: от документа до ответа

RAG — это не только “прикрутить векторную БД”. Это жизненный цикл знаний.

Индексация (ingestion)

Индексация — процесс подготовки документов к поиску:

загрузка источников (PDF, HTML, базы знаний)

разбиение на фрагменты (чанки)

очистка и нормализация текста

генерация эмбеддингов

запись в векторное хранилище

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

Эта часть почти всегда асинхронная.

Версионирование знаний

Если документы меняются, вам нужно понимать:

какая версия документа участвовала в ответе

когда и почему изменился результат

Практика: хранить doc_version, ingested_at, а также “снимок” (id чанков), которые были использованы в ответе.

Удаление и доступы

Если документ удалён или доступ к нему отозван, система должна:

убрать чанки из retrieval

не цитировать документ в новых ответах

корректно обрабатывать старые логи (без утечек содержимого)

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

В AI-Backend “работает без ошибок” не означает “работает хорошо”. Нужно измерять три группы метрик.

Надёжность: ошибки API, таймауты, ретраи, процент неуспешных запросов.

Производительность: p50/p95 задержки, время retrieval, время генерации.

Стоимость и качество: токены на запрос, доля ответов с источниками, оценки пользователей.

Техническая база для трассировок и метрик:

OpenTelemetry Documentation

Практический минимум логов для каждого ответа:

trace_id и связанный request_id

выбранная модель и параметры (температура, max tokens)

статистика токенов

список использованных источников (без лишнего содержимого)

признаки срабатывания фильтров безопасности

Безопасность: что важно именно в AI

Аутентификация и авторизация

Аутентификация — кто пользователь.

Авторизация — что ему можно.

Для API часто используют OAuth2.

OAuth 2.0

Защита от prompt injection

Prompt injection — попытка пользователя заставить модель нарушить инструкции (например, раскрыть системные правила или секреты).

Базовые меры:

не класть секреты в промпт

разделять системные инструкции и пользовательский ввод

делать retrieval с учётом прав и доверенности источников

валидировать вызовы инструментов (строгие схемы)

PII и соответствие требованиям

PII — персональные данные (например, телефон, паспорт). Даже если вы не обучаете модель, вы можете:

непреднамеренно записать PII в логи

отправить PII внешнему провайдеру

Минимальные практики:

маскирование/редакция PII перед логированием

настройка сроков хранения логов

отдельные политики доступа к трассам

Деплой и конфигурация

AI-Backend почти всегда разворачивают как набор сервисов (не обязательно микросервисы, но логически разделённых компонентов): API, воркеры индексации, воркеры оценки, компоненты хранения.

Полезная методология для конфигурации и окружений:

The Twelve-Factor App

Оркестрация контейнеров часто делается через Kubernetes:

Kubernetes Documentation

Референсная структура проекта (как мыслить кодом)

Пример того, как можно разделить ответственность в репозитории:

Важно: это не “единственно правильная структура”, а способ сделать так, чтобы API не знало деталей RAG, а RAG не зависел напрямую от HTTP.

Как эта архитектура связана с тем, что будет дальше в курсе

В следующих темах мы будем постепенно реализовывать каждый слой:

API на Python (FastAPI), схемы, ошибки, контракты и OpenAPI

сервисную оркестрацию: RAG, агенты, инструменты и интеграции

слой данных: PostgreSQL, Redis, векторное хранилище, S3-объекты

асинхронные задачи: индексация, переиндексация, фоновые джобы

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

Цель — прийти к продакшен-подходу, где AI — это часть системы, а не “скрипт вокруг LLM”.

Интеграция LLM в Python: SDK, промптинг, structured outputs и tool calling

В прошлой статье мы разобрали архитектуру AI-Backend: API-слой, сервисный слой (оркестрация), слой данных, очереди задач и наблюдаемость. Теперь спустимся на уровень практической интеграции LLM в Python: как писать код, который

стабильно вызывает модель через SDK,

управляет качеством ответов через промптинг,

возвращает структурированные данные, а не «просто текст»,

безопасно подключает инструменты (tool calling) для действий и интеграций.

Цель этой темы — чтобы LLM в вашем Backend была компонентом с контрактами, а не «магией в одном файле».

Что именно мы интегрируем

LLM обычно подключают к Backend в двух режимах.

Генерация текста: ответ пользователю, резюме, объяснение.

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

В продакшене второй режим критически важен, потому что сервисному слою нужны валидируемые входы и выходы.

SDK и базовый вызов модели

SDK — это официальная библиотека провайдера, которая упрощает вызовы API, обработку ответов и (часто) стриминг.

Ниже примеры на OpenAI SDK для Python.

openai-python (GitHub)

OpenAI API Documentation

Минимальная обёртка клиента

Правильная практика для Backend: создать единый модуль интеграции и не раскидывать вызовы модели по роутам.

Что важно контролировать при каждом вызове

Модель и версия (для воспроизводимости и регрессий).

Параметры генерации.

- Температура влияет на вариативность: чем выше, тем более разнообразный (и менее предсказуемый) текст. - Лимиты на длину ответа защищают от лишних затрат и «разноса».

Таймауты и ретраи.

- Во внешнем API возможны временные ошибки.

Логи и метрики.

- В архитектуре из прошлой статьи это часть наблюдаемости: токены, время, модель, trace_id.

Промптинг как инженерная дисциплина

Промптинг — это способ задавать модели роль, ограничения и формат вывода. В Backend промпт — это часть контракта сервиса.

Роли и разделение ответственности

Типичный паттерн сообщений:

system: жёсткие правила поведения (политики, формат, запреты).

user: конкретный запрос пользователя.

Ключевая идея: пользовательский ввод — недоверенный. Нельзя позволять ему «переписать правила».

Шаблон промпта для продакшена

Контекст задачи (что мы делаем и для кого).

Ограничения (что нельзя делать).

Требуемый формат ответа.

Критерии качества.

Пример системной инструкции для FAQ-бота:

Техники, которые реально улучшают качество

Явный формат ответа (особенно JSON).

Примеры (few-shot), если задача специфическая.

Декомпозиция.

- Например: «сначала выдели сущности, затем сформируй ответ». Это помогает, когда вы совмещаете LLM и бизнес-логику.

Ограничение области знаний.

- В RAG-сценариях: «отвечай только на основе предоставленного контекста, иначе скажи, что данных недостаточно».

Structured outputs: как получать валидный JSON

Structured outputs — это режим, когда вы требуете от модели вернуть данные в строгом формате (обычно JSON), чтобы дальше их:

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

сохранить,

использовать для вызова инструмента,

передать в другой сервис.

В отличие от «просто попросить JSON текстом», structured outputs стремится сделать результат машиночитаемым и устойчивым.

!Пайплайн получения и проверки структурированного ответа

Описание схемы через Pydantic

Pydantic даёт два преимущества:

удобное описание структуры,

проверка типов и обязательных полей.

Пример запроса со structured outputs (JSON Schema)

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

Принципиально важно: даже если вы включили structured outputs, валидация на вашей стороне обязательна. LLM остаётся вероятностной системой, и ваша задача как Backend-инженера — делать «жёсткие границы».

Типичные стратегии при ошибках валидации

Повтор с сообщением об ошибке.

- Вы возвращаете модели, какие поля не прошли проверку, и просите исправить.

Fallback на ручной парсер.

- Иногда проще вытащить ключевые поля регулярками, но это крайний вариант.

Отказоустойчивый сценарий.

- Например, создать тикет с priority=medium и добавить пометку «требует уточнения».

Tool calling: как подключать инструменты и интеграции

Tool calling — это режим, когда модель не выполняет действия сама, а просит Backend вызвать инструмент (функцию) с определёнными параметрами.

Это фундамент для AI-агентов и для интеграций (CRM, Jira, платежи), о которых в курсе будет отдельный большой блок.

Ключевой принцип безопасности:

модель предлагает вызов,

Backend проверяет права, валидирует вход, и только потом выполняет.

!Последовательность безопасного вызова инструмента через LLM

Дизайн инструментов: строгие контракты

Хороший инструмент имеет:

короткое имя,

чёткое описание,

JSON Schema параметров,

детерминированный результат,

отсутствие «лишних» возможностей.

Пример: инструмент для получения статуса заявки.

Пример объявления tool и обработки результата

Ниже общий паттерн: LLM решает, что нужен инструмент, Backend выполняет и возвращает результат.

Правила безопасного tool calling в Backend

Проверка прав до выполнения.

- Модель не знает вашу модель доступа.

Валидация входа инструмента.

- Лучше через Pydantic-схему, чем вручную.

Лимиты.

- Ограничьте число шагов, общий бюджет токенов, время.

Аудит.

- Логируйте: какой инструмент, кто вызвал, какие параметры (с редактированием PII), результат.

Сужение возможностей.

- Не делайте инструмент «execute_sql» или «http_request_to_anywhere» без жёстких ограничений.

Практическая сборка в рамках архитектуры AI-Backend

Чтобы связать с прошлой статьёй, держим простое разделение.

API-слой

- принимает запрос, - возвращает ответ, - не содержит промптов и логики инструментов.

Сервисный слой

- orchestrator собирает пайплайн, - вызывает LLMClient, retrieval (в будущем RAG), инструменты.

Integrations

- Jira/CRM клиенты, - строго типизированные методы.

Observability

- логирование токенов, задержек, - trace_id.

Пример минимального orchestrator (скелет):

Сейчас это выглядит просто, но именно такой каркас позволяет дальше без боли добавить:

RAG (retrieval + контекст),

историю диалога,

tool calling с авторизацией,

оценку качества,

очереди задач.

Частые ошибки при интеграции LLM

Вызовы модели прямо из роутов.

- Потом невозможно централизованно добавить ретраи, лимиты, логи.

Отсутствие контрактов.

- «Спросили JSON, пришло почти JSON» — а дальше падает бизнес-логика.

Нет валидации.

- Structured outputs не отменяет проверки.

Инструменты без авторизации.

- Самый опасный класс ошибок в агентных сценариях.

Нет наблюдаемости.

- Без токенов, времени и модели вы не сможете управлять стоимостью и качеством.

Что дальше по курсу

Следующие темы логично развивают этот материал:

API-контракты для AI-эндпоинтов (ошибки, идемпотентность, стриминг).

Интеграции и агенты: библиотечная оркестрация, реестр инструментов, политики безопасности.

RAG: индексация, retrieval, управление версиями знаний.

Наблюдаемость AI: трассировки, метрики качества, регрессии и стоимость.

RAG в продакшене: эмбеддинги, чанкинг, векторные БД и оценка качества

В прошлых темах курса мы:

разобрали архитектуру AI-Backend (слои API, сервисы, данные, очереди, наблюдаемость),

научились интегрировать LLM в Python (SDK, промптинг, structured outputs, tool calling).

Теперь соберём центральный продакшен-пазл для корпоративных ассистентов и AI-поиска: RAG (Retrieval-Augmented Generation). Практическая цель — сделать так, чтобы модель отвечала на основе ваших данных, с ссылками на источники, воспроизводимо и измеримо.

RAG в продакшене — это не один вызов векторной БД. Это конвейер знаний:

загрузить документы,

разрезать на фрагменты,

построить эмбеддинги,

положить в векторное хранилище,

по запросу искать релевантное,

собрать контекст,

сгенерировать ответ,

измерять качество и стоимость.

!Общая картина того, из каких этапов состоит RAG в продакшене

Базовые понятия без «магии»

Документ — единица знания (страница базы знаний, PDF, тикет, статья).

Чанк — фрагмент документа, который индексируется и извлекается (обычно несколько предложений).

Эмбеддинг — числовой вектор, который кодирует смысл текста и позволяет искать похожее по смыслу.

Векторная БД — хранилище, которое умеет быстро находить ближайшие векторы (семантический поиск).

Retrieval — этап поиска релевантных чанков по запросу.

Grounded answer — ответ, который опирается на найденные источники, а не на «память модели».

Продакшен-цели RAG: что считаем «хорошо»

RAG строят не ради технологии, а ради метрик. Обычно целятся в следующее:

Достоверность: ответы основаны на ваших источниках.

Покрытие: система находит нужные фрагменты даже при перефразировании запроса.

Управляемость: можно менять знания, версии, доступы, и результат предсказуем.

Стабильность стоимости: контроль токенов, кэширование, лимиты.

Измеримость: качество retrieval и генерации измеряется и не деградирует незаметно.

В терминах архитектуры из первой статьи:

API остаётся тонким.

В сервисном слое живёт RAG-orchestrator.

В слое данных появляются: объектное хранилище для исходников, реляционная БД для метаданных/версий, векторная БД для поиска.

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

Эмбеддинги: как выбрать и как использовать

Что такое эмбеддинг на практике

Модель эмбеддингов превращает текст в вектор фиксированной длины. Затем вы сравниваете векторы запроса и чанков, чтобы найти ближайшие.

Ключевая продакшен-идея: retrieval — это отдельная модельная задача, часто с другой моделью, чем генерация.

Полезные источники:

OpenAI Embeddings guide

Sentence Transformers documentation

Практические правила выбора модели эмбеддингов

Язык: если у вас много русского, проверяйте качество на русском, а не на английских примерах.

Домен: юридические тексты, код, медицина могут требовать специализированных эмбеддингов.

Размерность и скорость: более «тяжёлые» эмбеддинги могут давать лучший recall, но дороже.

Стабильность: фиксируйте версию модели эмбеддингов так же, как версию LLM.

Важно про нормализацию текста

До эмбеддинга желательно:

убрать мусор (навигацию, футеры, повторяющиеся подписи),

нормализовать пробелы,

сохранить структуру (заголовки как текст, списки как строки),

вытащить метаданные (источник, дата, ACL-доступы, doc_version).

Чанкинг: главный рычаг качества retrieval

Чанкинг решает дилемму:

слишком мелко — теряется смысл, много шума,

слишком крупно — не помещается в контекст LLM и падает точность поиска.

Базовые стратегии чанкинга

| Стратегия | Когда подходит | Риск | |---|---|---| | По фиксированной длине (символы/токены) | быстрый старт, однородные тексты | режет смысл по середине | | По структуре (заголовки, разделы) | статьи, документация, базы знаний | разделы бывают слишком большие | | По предложениям с окном (overlap) | FAQ, инструкции, смешанные форматы | больше чанков, больше стоимость | | Семантический чанкинг | сложные тексты, где важны смысловые границы | сложнее и дороже реализовать |

Overlap: зачем он нужен

Overlap — это перекрытие соседних чанков. Он помогает не терять смысл на границе.

Практика:

стартовое значение overlap часто делают умеренным,

затем подбирают по метрикам retrieval (см. раздел про оценку).

Что хранить вместе с чанком

Помимо текста чанка в индексе почти всегда нужны метаданные:

doc_id и chunk_id,

source (URL, путь, система-источник),

doc_version и ingested_at,

title или путь разделов,

acl или список групп доступа,

дополнительные поля для фильтрации (язык, продукт, регион).

Без метаданных вы не сделаете нормально:

контроль доступа,

удаление и переиндексацию,

цитирование и объяснимость.

Минимальный пример чанкинга в Python

Ниже пример простого чанкинга по словам с overlap. В продакшене вы обычно будете считать в токенах, но принцип тот же.

Векторные БД: что выбрать и как правильно индексировать

Что делает векторная БД

Векторная БД хранит:

векторы (эмбеддинги чанков),

payload (метаданные),

индексы для быстрого nearest neighbor поиска.

Популярные варианты:

Qdrant documentation

Weaviate documentation

Pinecone documentation

локальная библиотека для прототипов: FAISS (GitHub)

Критерии выбора в продакшене

Фильтры по метаданным: нужны для ACL и бизнес-фильтрации.

Гибридный поиск: сочетание keyword и semantic часто лучше, чем любой один.

Операции жизненного цикла: upsert, delete по doc_id, переиндексация.

Наблюдаемость и бэкапы.

Мульти-тенантность: если у вас много организаций/пространств.

Важная деталь: ACL и фильтрация

Одна из главных продакшен-ошибок — делать retrieval без учёта прав.

Правильный принцип:

векторная БД должна уметь фильтровать по метаданным,

orchestrator должен передавать фильтры (например, tenant_id, группы пользователя),

если фильтровать нельзя, retrieval становится источником утечек.

Пример: схема данных для чанка

Так обычно выглядит один элемент индекса (логически, не привязано к конкретной БД):

Retrieval: как искать так, чтобы LLM отвечала хорошо

Retrieval в продакшене — это обычно несколько подпроцессов.

Стандартный пайплайн retrieval

Нормализовать запрос (язык, опечатки, иногда расширение запроса).

Получить эмбеддинг запроса.

Выполнить поиск top-k в векторной БД с фильтрами по метаданным.

Опционально применить rerank (переранжирование) более точной моделью.

Собрать контекст: выбрать фрагменты, ограничить размер, добавить ссылки.

!Последовательность этапов поиска релевантных фрагментов

Почему нужен rerank

Векторный поиск хорошо находит «примерно похожее», но хуже различает тонкие нюансы. Rerank берёт кандидатов top-k и сортирует по релевантности более точной моделью.

Практический эффект:

меньше нерелевантного контекста,

выше шанс, что LLM «увидит» правильный фрагмент,

меньше галлюцинаций.

Rerank можно делать разными способами:

отдельной моделью переранжирования,

LLM в режиме оценки релевантности (дороже),

гибридом keyword + vector до rerank.

Сбор контекста и цитирование

Контекст для LLM обычно включает:

текст чанков,

заголовок/источник,

идентификаторы для цитат.

Важно не «заливать всё подряд». Контекст должен быть:

релевантный,

достаточно короткий,

с явными границами (где какой источник).

Минимальный формат контекста:

Дальше в системной инструкции вы фиксируете правило:

отвечай только на основе источников,

если источников недостаточно, задай уточнение или скажи, что данных нет,

добавь citations (список doc_id/chunk_id).

Это связывает текущую тему с прошлой статьёй про structured outputs: citations удобно возвращать структурой, а не «в тексте как получится».

Индексация и жизненный цикл знаний

Ingestion как отдельная асинхронная задача

Индексацию почти всегда выносят в фоновые воркеры (из первой статьи: очереди задач), потому что это:

долго,

периодически,

требует ретраев и контроля версий.

Этапы ingestion обычно такие:

Забрать документы из источника.

Превратить в чистый текст (парсинг).

Разбить на чанки.

Посчитать эмбеддинги.

Записать в векторную БД.

Записать метаданные в PostgreSQL.

Обновить статус индексации.

Версионирование

Без версионирования вы не сможете объяснить, почему вчера ответ был один, а сегодня другой.

Минимально стоит хранить:

doc_version (например, хэш содержимого),

ingested_at,

связь ответа с использованными doc_id/chunk_id.

Удаление и право быть забытым

Если документ удалили или доступ отозвали, система должна:

удалить чанки из индекса,

перестать возвращать их в retrieval,

не логировать сырые тексты (или хранить логи с редактированием).

Оценка качества RAG: что измерять и как не обмануть себя

Оценка RAG делится на два больших класса: retrieval-качество и качество ответа.

Офлайн-оценка retrieval

Вы строите датасет: набор запросов и ожидаемых источников (или ожидаемых документов).

Метрики, которые понятны инженеру:

Recall@k: в скольких запросах среди top-k нашёлся правильный документ.

Precision@k: какая доля найденного действительно релевантна.

Их смысл без формул:

Recall@k отвечает на вопрос: мы вообще достали нужное?

Precision@k отвечает на вопрос: мы не тащим слишком много мусора?

Что важно в продакшене:

датасет должен отражать реальные вопросы,

запросы должны покрывать разные формулировки,

оценку нужно повторять при изменении: чанкинга, эмбеддингов, фильтров, rerank.

Оценка качества ответа

У ответа обычно интересуют следующие свойства:

Faithfulness: ответ не противоречит источникам.

Groundedness: ответ опирается на источники, а не «додумывает».

Helpfulness: ответ реально решает задачу пользователя.

Citations quality: ссылки соответствуют фрагментам.

Часть этого можно измерять экспертной разметкой или LLM-as-a-judge (аккуратно, с контролем смещения).

Инструменты, которые часто используют для RAG-оценки:

Ragas documentation

Онлайн-метрики в продакшене

Онлайн-метрики не заменяют офлайн, но помогают ловить деградации.

Типичный минимум:

доля ответов с citations,

среднее число найденных чанков,

доля ответов с уточняющим вопросом,

p50/p95 задержки retrieval и генерации,

токены на запрос и стоимость,

клики по источникам и оценки пользователей.

Это напрямую продолжает тему наблюдаемости из первой статьи: без логов retrieval и citations вы не сможете отлаживать качество.

Типовые продакшен-проблемы и как их диагностировать

| Симптом | Частая причина | Что проверить | |---|---|---| | LLM «галлюцинирует» | в контексте нет ответа или он нерелевантен | Recall@k, чанкинг, фильтры ACL | | Ответы правильные, но длинные и дорогие | слишком много чанков в контексте | лимиты, rerank, отбор final-n | | На один и тот же вопрос разные ответы | плавающие знания или параметры | версии эмбеддингов, doc_version, температура | | Утечки закрытых данных | retrieval без ACL-фильтра | фильтрация по tenant_id/acl_groups | | Слабое качество на русском | неподходящие эмбеддинги/чанкинг | локальный eval датасет на русском |

Как это складывается в кодовую архитектуру курса

Связываем с предыдущими статьями:

API-слой принимает запрос input, conversation_id, metadata.

Сервисный слой (orchestrator) делает:

- retrieval, - сбор контекста, - вызов LLM через единый LLM-клиент, - structured output для citations и служебных полей.

Data слой:

- PostgreSQL для документов, версий, прав, - объектное хранилище для оригиналов, - векторная БД для чанков.

Workers:

- ingestion, - переиндексация, - офлайн-оценки.

Observability:

- трейсинг этапов retrieval и generation, - логи использованных doc_id/chunk_id, - токены и стоимость.

В следующих темах курса обычно логично углубляться в:

реализацию ingestion-воркеров и переиндексации,

гибридный поиск и reranking,

расширенную оценку качества и регрессионные тесты RAG,

политики безопасности для RAG и агентов (prompt injection, data leakage).

AI-агенты: планирование, память, инструменты, оркестрация и multi-agent

В предыдущих темах курса мы собрали основу AI-Backend (слои API, сервисы, данные, очереди, наблюдаемость), научились интегрировать LLM в Python (SDK, structured outputs, tool calling) и построили RAG в продакшене (ингест, векторный поиск, качество).

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

В продакшене «агент» — это не библиотека, а паттерн архитектуры: цикл принятия решений + строгие контракты инструментов + память + оркестрация и ограничения.

Что такое AI-агент и чем он отличается от «LLM-чатбота»

LLM-чатбот обычно делает один шаг: получил текст, сгенерировал текст.

AI-агент делает цикл:

Получает цель или пользовательский запрос.

Строит план или выбирает следующий шаг.

При необходимости вызывает инструменты (tool calling).

Сохраняет состояние и память.

Повторяет шаги, пока задача не завершена или не сработали лимиты.

Ключевое отличие: агент может выполнять действия во внешних системах (CRM, Jira, БД, почта), а значит появляются требования к безопасности, наблюдаемости, идемпотентности и авторизации.

!Цикл работы агента и ключевые точки контроля

Место агента в архитектуре AI-Backend

Свяжем агента с архитектурой из первой статьи.

API-слой (FastAPI) принимает запрос, делает аутентификацию, выдаёт trace_id, не содержит логики планирования.

Сервисный слой (orchestrator) решает, какой режим использовать: обычный ответ, RAG или агент.

Agent runtime управляет циклом: шаги, tool calling, лимиты, обработка ошибок.

Tool registry / integrations содержит инструменты с жёсткими схемами входа и политиками доступа.

Память хранит краткосрочное состояние и долгосрочные знания (часто через RAG).

Observability пишет трассы и метрики по каждому шагу.

Полезные ссылки для контекста:

FastAPI Documentation

OpenAI Function calling guide

OpenTelemetry Documentation

Планирование: как агент решает, что делать дальше

Планирование — это способ превратить запрос пользователя в последовательность шагов. В продакшене важно, чтобы план был:

ограничен по шагам и стоимости,

проверяем и трассируем,

совместим с правами доступа и политиками.

Основные стратегии планирования

| Стратегия | Идея | Когда подходит | Риски | |---|---|---|---| | ReAct-подход | модель попеременно «думает» и вызывает инструменты | простые задачи и быстрый старт | сложнее контролировать траекторию, возможны лишние шаги | | Plan-and-execute | сначала создаём план, затем выполняем шаги | задачи из нескольких этапов, где нужен контроль | план может устареть при ошибках инструментов | | Router + specialists | сначала классифицируем запрос, затем запускаем специализированного агента | много типов задач, разные политики | нужна качественная маршрутизация | | Граф/машина состояний | шаги задаются как узлы и переходы, LLM выбирает ветку | строгий контроль и воспроизводимость | больше инженерной работы |

Если вам нужен высокий контроль, на практике часто выигрывает подход «граф выполнения», где LLM ограничена выбором переходов.

Инструментальные варианты для оркестрации графов:

LangGraph Documentation

План как структурированные данные

Чтобы план был управляемым, удобнее получать его не «в тексте», а как JSON по схеме, которую вы валидируете (идея из темы про structured outputs).

Пример схемы плана:

Дальше orchestrator может:

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

проверить, что tool_name входит в allowlist,

проверить права пользователя до выполнения,

выполнить шаги с лимитами.

Инструменты: контракты, безопасность, идемпотентность

Инструменты (tools) — это то, что делает агента полезным для бизнеса. Но это же и главный источник рисков.

Правила хорошего инструмента

Строгая схема входа

- параметры описаны через JSON Schema или Pydantic - additionalProperties запрещены

Детерминированность

- инструмент возвращает понятный результат, без «магии»

Явные ошибки

- различайте not_found, forbidden, timeout, validation_error

Идемпотентность для операций записи

- повторный вызов не должен создавать дубли - используйте idempotency_key

Авторизация до выполнения

- модель не должна быть единственным «решателем», можно ли делать действие

> Правило продакшена: модель может предложить вызов инструмента, но решение выполнять или нет всегда остаётся за backend.

Пример: инструмент с валидацией и идемпотентностью

Память агента: что хранить и где

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

Виды памяти в backend-реализации

| Тип памяти | Что это | Где хранить | Пример | |---|---|---|---| | Краткосрочная память | последние сообщения и промежуточное состояние выполнения | Redis или PostgreSQL | текущий план, уже выполненные шаги | | Сжатая память диалога | краткое резюме истории, чтобы экономить токены | PostgreSQL | итоговые факты: «пользователь работает в отделе X» | | Долгосрочная семантическая память | поиск по прошлым диалогам/заметкам через эмбеддинги | векторная БД | «мы уже обсуждали возврат товара 2 недели назад» | | Память знаний | корпоративные документы и базы знаний | RAG-конвейер | «политика отпусков» |

Заметьте, что долгосрочная память технически очень похожа на RAG: вы индексируете тексты (например, заметки и решения) и извлекаете релевантное по запросу.

Практика: как не раздувать контекст

Окно последних сообщений

- в контекст попадает только последние реплик

Суммаризация

- старые части диалога сворачиваются в короткое резюме

Семантическое извлечение

- вместо всей истории вы вытаскиваете только релевантные фрагменты (векторный поиск)

Важно: память должна быть владельцем данных, а LLM — только потребителем. Это снижает риск утечек и помогает соблюдать политики хранения.

Оркестрация агента: лимиты, состояния, очереди задач и наблюдаемость

Агент в продакшене должен быть управляемым. Оркестрация отвечает за:

Лимиты

- max_steps на задачу - max_tool_calls на ответ - бюджет токенов и таймауты

Управление состоянием

- что уже сделано - какие ошибки были - можно ли продолжать

Отказоустойчивость

- ретраи для временных ошибок инструментов - fallback на безопасный ответ

Асинхронность

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

Для асинхронных задач из архитектуры первой статьи часто используют:

Celery Documentation

Наблюдаемость агентных шагов

Минимум, который стоит логировать на каждый запрос:

trace_id и conversation_id

модель и параметры генерации

число шагов и число вызовов инструментов

какие инструменты вызывались и с какими типами аргументов (с редактированием PII)

коды ошибок инструментов

токены и задержки по этапам

Техническая основа для трассировки:

OpenTelemetry Documentation

Multi-agent: когда один агент уже не справляется

Multi-agent — это система из нескольких агентов с разными ролями. Это имеет смысл, когда:

задачи требуют разных компетенций и политик доступа,

нужно параллельно исследовать варианты,

нужен контроль качества через «проверяющего» агента.

!Типовая топология multi-agent с координатором и специалистами

Типовые паттерны multi-agent

| Паттерн | Как работает | Плюсы | Минусы | |---|---|---|---| | Manager-Worker | координатор дробит задачу и собирает результат | простая модель контроля | координатор может стать узким местом | | Specialist Routing | маршрутизатор выбирает агента по типу запроса | гибкие политики и промпты | ошибки маршрутизации бьют по качеству | | Critic/Reviewer | один агент делает, другой проверяет | выше качество и безопасность | дороже по токенам | | Parallel Search | несколько агентов параллельно ищут факты/источники | выше покрытие | нужно дедуплицировать и ранжировать |

Важно: multi-agent почти всегда дороже и сложнее в отладке. В продакшене его обычно вводят после того, как одиночный агент упёрся в качество или контроль.

Фреймворк, который часто используют для multi-agent прототипирования:

Microsoft AutoGen (GitHub)

Практический скелет агента на Python: цикл, инструменты, память

Ниже пример упрощённого агентного рантайма без привязки к конкретному фреймворку. Он показывает главное: цикл, обработку tool calling, валидацию и лимиты.

Что важно в этом скелете:

LLM не получает «суперспособностей», она работает только через allowlist инструментов.

Есть лимиты max_steps и max_tool_calls.

Память вынесена в отдельный интерфейс.

В точке исполнения инструмента явно подразумеваются проверки прав и валидация.

Если вы используете агентные фреймворки (например, LangChain), всё равно полезно понимать этот базовый цикл.

LangChain Documentation

Типовые угрозы и защитные меры для агентов

Prompt injection и «враждебный ввод»

Атака часто выглядит так: пользователь пытается заставить агента вызвать опасный инструмент, обойти правила или утянуть закрытый контент.

Защитные меры:

не передавать секреты в промпт

retrieval только с ACL-фильтрами (урок из RAG темы)

allowlist инструментов и запрет «универсальных» инструментов

строгая валидация входов и выходов

политики: какие инструменты можно вызывать в каком контексте

Опасные инструменты

Особенно рискованны:

произвольные SQL-запросы

произвольные HTTP-запросы

выполнение кода

Если они необходимы, вводите ограничения:

шаблоны запросов

read-only режим

песочницы

обязательный human-in-the-loop

Как тестировать агентные сценарии

Тестирование агента — это сочетание детерминированных и вероятностных проверок.

Unit-тесты инструментов (детерминированно)

Контрактные тесты схем (валидация аргументов и результатов)

Сценарные тесты (набор диалогов и ожидаемых действий)

Регрессионные тесты стоимости (лимиты токенов и шагов)

Оценка качества через офлайн датасет задач

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

Как эта тема связывает курс в единую систему

Теперь у нас есть три опоры:

LLM-интеграция даёт tool calling и structured outputs.

RAG в продакшене даёт доступ к знаниям и контроль качества retrieval.

Агенты связывают всё это в цикл действий: планирование, память, вызовы инструментов, оркестрация и ограничения.

Дальше по курсу это естественно продолжать практикой:

реестр инструментов и политики доступа

агентный orchestrator в сервисном слое (не в роуте)

фоновые задачи для долгих операций

наблюдаемость агентных шагов и оценка качества

Модели и пайплайны ML: обучение, фичи, эксперименты и реестр моделей

В предыдущих темах курса мы строили AI-Backend вокруг LLM: API-контракты, RAG-конвейер знаний, tool calling и агентную оркестрацию. Но в реальных продуктах LLM почти всегда работает вместе с классическими ML-моделями: ранжирование, антифрод, рекомендации, классификация обращений, прогнозы спроса, scoring.

Эта статья про то, как проектировать ML-часть так, чтобы она была совместима с продакшен-подходом из предыдущих тем: слои, наблюдаемость, контроль качества, версии, безопасность. Мы разберём:

как устроен жизненный цикл ML-модели;

что такое фичи и почему важен feature store;

как ставить эксперименты и не потерять воспроизводимость;

зачем нужен реестр моделей (model registry);

как ML-пайплайн связывается с Backend, RAG и агентами.

!Жизненный цикл ML-модели от данных до продакшена и обратной связи

Где в AI-Backend живёт «классический ML»

В терминах архитектуры AI-Backend из первой статьи:

API-слой принимает запрос и возвращает ответ по контракту.

Сервисный слой оркестрирует: LLM, RAG, агенты и ML-модели.

Слой данных хранит:

- сырые события и сущности (PostgreSQL/аналитическое хранилище), - признаки (иногда отдельно), - артефакты обучения (объектное хранилище), - версии моделей и метрики (реестр).

Очереди задач запускают долгие процессы: обучение, пересчёт фичей, офлайн-оценки.

Наблюдаемость фиксирует качество, задержки, стоимость и деградации.

Практический смысл: ML-модель должна быть не «ноутбуком», а сервисным компонентом с контрактами, как и LLM.

Термины, которые нужны дальше

Датасет — набор примеров для обучения, обычно таблица: строки — объекты (пользователь/заказ/тикет), столбцы — признаки и целевая переменная.

Лейбл (label) — правильный ответ для обучения модели (например, fraud=1 или category="billing").

Фича (feature, признак) — числовое/категориальное описание объекта, которое модель использует для решения задачи (например, число покупок за 30 дней).

Тренировка (training) — процесс подбора параметров модели по данным.

Инференс (inference) — использование обученной модели для предсказаний.

Эксперимент — конкретный запуск обучения: код + данные + параметры + результат.

Реестр моделей (model registry) — хранилище версий моделей с метаданными: кто обучил, на каких данных, какие метрики, где лежит артефакт.

Дрейф данных (data drift) — изменения распределения входных данных со временем.

Дрейф качества (concept drift) — изменения связи «входы -> правильный ответ» (например, новые схемы мошенничества).

Пайплайн обучения: из чего он состоит

ML-пайплайн — это повторяемый процесс, который по входным данным создаёт версию модели.

Обычно он включает:

Сбор данных и лейблов.

Очистку и валидацию данных.

Генерацию фичей.

Разделение на train/validation/test.

Обучение.

Оценку качества.

Сохранение артефактов и регистрация модели.

Ключевая продакшен-идея: воспроизводимость

Чтобы воспроизвести результат, вам нужно уметь ответить на вопросы:

Какая версия кода обучала модель?

На каких данных (и какой версии данных) она обучалась?

Какие параметры использовались?

Какие метрики получились?

Где лежит модельный артефакт?

Эти вопросы напрямую связаны с темами RAG и агентов:

в RAG мы версионируем знания (doc_version, ingested_at),

в ML мы версионируем данные/фичи и артефакты обучения.

Фичи: почему это самый дорогой и важный слой

Фичи — это мост между «сырыми данными» и моделью. Ошибки в фичах чаще ломают качество, чем выбор алгоритма.

Типичные источники фичей

события продукта (клики, просмотры, покупки),

транзакции и биллинг,

CRM/тикеты,

контент и тексты (в том числе эмбеддинги),

внешние источники (курсы валют, гео-данные).

Offline и online фичи

В продакшене важно различать:

Offline фичи — считаются для обучения на больших исторических данных.

Online фичи — считаются в момент запроса (или заранее, но доступны через быстрый доступ) для онлайн-инференса.

Проблема, которую решают команды: согласованность фичей.

Если фича считается по-разному offline и online, модель в продакшене начинает работать хуже, чем на валидации.

Leakage: «подглядывание в будущее»

Одна из самых частых причин «идеального качества на обучении» и провала в продакшене — утечка будущей информации в фичи.

Примеры:

вы считаете фичу за период после события, которое хотите предсказать,

используете итоговый статус, который формируется позже,

объединяете таблицы без учёта времени.

Продакшен-практика: в feature-расчётах всегда фиксируйте время среза (point-in-time), то есть считаете признаки так, как будто вы находитесь в прошлом.

Feature store: зачем он нужен

Feature store — это система для централизованного хранения и выдачи фичей с едиными определениями.

Он обычно решает задачи:

единая логика расчёта (один источник истины для offline и online),

контроль версий и описаний фичей,

повторное использование фичей между командами и моделями,

доступ к фичам с нужным SLA в продакшене.

Практический пример технологии:

Feast Documentation

!Как feature store связывает offline обучение и online инференс

Эксперименты: как не утонуть в запусках обучения

Эксперимент-трекинг нужен, чтобы:

сравнивать запуски,

понимать, что улучшило метрики,

воспроизводить результаты,

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

Что логировать в эксперимент

Минимальный набор:

параметры (гиперпараметры, выбор фичей, фильтры данных),

метрики (AUC/F1/accuracy или бизнес-метрики),

артефакты (файл модели, конфиг, список фичей),

ссылки на версии данных (например, id снапшота или диапазон дат),

окружение (версия библиотек).

Для трекинга часто используют MLflow:

MLflow Tracking Documentation

Пример: логирование эксперимента в MLflow

Здесь важно не то, что это iris, а паттерн: каждый запуск обучения становится объектом с метаданными.

Реестр моделей: как доставлять модель в продакшен контролируемо

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

Что обычно хранит запись в реестре:

имя модели и версия,

ссылка на артефакт (например, в S3-совместимом хранилище),

метрики и датасет/период,

список фичей и их версии,

кто и когда зарегистрировал,

статус (stage) и политика промоушена.

Практика на MLflow:

MLflow Model Registry Documentation

Почему реестр критичен для AI-Backend

Потому что без реестра вы не сможете:

быстро откатиться на предыдущую версию,

сравнивать качество разных моделей на одинаковых данных,

объяснить, какая модель приняла решение,

связать онлайн-решение с экспериментом (для аудита).

Это похоже на RAG-цитирование: как RAG возвращает doc_id/chunk_id, так ML-решение должно уметь вернуть model_name/model_version и ключевые параметры инференса.

Деплой и инференс: online, batch и «гибрид»

Есть три базовых режима использования моделей.

Online inference

Модель вызывается прямо в API-запросе.

Плюсы:

актуальные данные,

ответ здесь и сейчас.

Минусы:

строгие требования к задержкам,

нужен доступ к online фичам.

Batch inference

Предсказания считаются периодически (например, раз в час/день) и записываются в БД.

Плюсы:

дешево и стабильно,

легко масштабировать.

Минусы:

предсказания могут быть не самыми свежими.

Гибрид

Часть фичей и предсказаний готовится в batch, а в online добавляются «последние сигналы».

Контракты ML в Backend: как делать это «по-взрослому»

Чтобы ML-модель нормально жила в сервисном слое (как LLM и RAG), нужны контракты.

Схема входа/выхода

Вход модели должен быть валидируемым (типы, обязательные поля).

Выход модели должен содержать:

- предсказание, - вероятность/score (если есть), - версию модели, - важные технические поля для наблюдаемости.

Пример схем через Pydantic:

Где хранить модель в сервисе

Распространённый подход:

при старте сервиса загрузить модель по ссылке из реестра,

держать в памяти,

периодически обновлять по сигналу (или через rolling deploy).

Для Python часто используют сериализацию:

joblib/pickle для sklearn,

onnxruntime для ONNX,

torch для PyTorch.

Важно: сериализация — это часть поверхности безопасности. Артефакты должны быть из доверенного хранилища, с контролем доступа.

Оркестрация пайплайнов: обучение и фичи как фоновые процессы

Как и ingestion в RAG, обучение и пересчёт фичей почти всегда асинхронные.

Типичный стек для оркестрации:

планировщик пайплайнов (DAG): Apache Airflow Documentation

задачи/воркеры: Celery из предыдущей архитектуры

Что важно в оркестрации:

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

контроль версий данных и артефактов,

ретраи для временных ошибок,

отдельные окружения (dev/stage/prod).

Оценка качества и мониторинг в продакшене

Офлайн-метрики (на test set) не гарантируют онлайн-качество. В проде нужно мониторить:

качество (если есть лейблы с задержкой),

стабильность входов (дрейф),

стабильность score (подозрительные смещения),

технические метрики (p95 latency, ошибки, таймауты).

Как мониторить, если лейблы приходят поздно

Частый кейс: правильный ответ появляется через дни/недели (возвраты, fraud-confirmation). Тогда:

мониторьте дрейф фичей и распределение score сразу,

считайте качество «с лагом» по мере прихода лейблов,

держите пайплайн переобучения и backfill.

Связь с RAG и агентами: практические схемы

ML как часть RAG

ML часто улучшает retrieval:

ML-ранжирование кандидатов,

классификация запроса и роутинг по индексам,

фильтрация мусорных документов.

ML как инструмент агента

Для агента ML-модель — такой же инструмент, как CRM или Jira:

строгая схема входа,

версионирование,

лимиты и наблюдаемость.

Пример сценария:

агент хочет решить: «Нужен ли human review?»

вызывает tool fraud_score,

получает decision и использует его для плана.

Ключевой принцип тот же, что в tool calling из прошлой темы: модель-агент предлагает шаг, backend валидирует и исполняет.

Минимальный продакшен-чеклист для ML-пайплайна

Данные и лейблы версионируются (хотя бы периодами и снапшотами).

Фичи определены централизованно и согласованы offline/online.

Каждый эксперимент логируется: параметры, метрики, артефакты.

Есть реестр моделей со стадиями и откатами.

В сервисе есть контракт входа/выхода и наблюдаемость.

Есть мониторинг дрейфа и качества, плюс процесс переобучения.

Что дальше по курсу

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

как оформить ML-inference как сервис в AI-Backend (FastAPI + контракты + кэширование),

как подключить feature store и сделать корректный point-in-time для обучения,

как объединить RAG, ML-ранжирование и агентную оркестрацию в единый сервисный слой.

Деплой и масштабирование: контейнеры, асинхронность, очереди, GPU и кэш

В предыдущих темах курса мы построили архитектуру AI-Backend, научились интегрировать LLM, собрали RAG-конвейер и обсудили агентную оркестрацию и классические ML-пайплайны. Эта тема переводит всё это в продакшен-плоскость: как развернуть систему, масштабировать под нагрузку и контролировать задержки и стоимость.

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

API-сервису (FastAPI)

воркерам ingestion и eval (очереди задач)

inference (LLM/эмбеддинги/ML), включая GPU

кэшу и наблюдаемости (стоимость, p95, токены, ошибки)

!Общая картина компонентов и потоков в продакшене

Что значит “масштабировать AI-Backend”

В обычном Backend масштабирование часто сводится к увеличению числа реплик API и оптимизации БД. В AI-сценариях добавляются особенности:

LLM-вызовы могут занимать секунды и стоить деньги

retrieval и rerank добавляют отдельные этапы с задержками

ingestion и переиндексация могут быть тяжёлыми и периодическими

агентные сценарии делают несколько tool calls и могут “жить” дольше одного запроса

часть вычислений может требовать GPU

На практике масштабирование — это управление тремя ресурсами:

время (latency p50/p95)

деньги (токены, GPU-время, внешние API)

надёжность (ретраи, деградации, очереди, backpressure)

Контейнеры как базовый формат поставки

Почему контейнеры нужны почти всегда

Контейнер — это упаковка приложения вместе с зависимостями и предсказуемым окружением. Для AI-Backend это важно, потому что:

зависимости Python (включая ML-библиотеки) должны быть воспроизводимыми

одна и та же сборка должна одинаково работать в dev/stage/prod

оркестратору (Kubernetes) проще масштабировать контейнеры, чем “процессы на сервере”

Полезные источники:

Docker Documentation

Kubernetes Documentation

Минимальный Dockerfile для FastAPI

Ниже пример, который фокусируется на воспроизводимости и скорости сборки.

Практические правила для образов AI-сервисов:

фиксируйте версии зависимостей (lock-файл)

не храните секреты в образе (ключи должны приходить через переменные окружения или секреты оркестратора)

отделяйте API-образ и worker-образ (или используйте один образ с разными CMD)

Локальная сборка окружения через docker-compose

Для RAG и агентов удобно поднимать инфраструктуру локально: PostgreSQL, Redis (кэш/очередь), векторное хранилище.

Важно: docker-compose — это отличный инструмент для dev, но для продакшена обычно нужен оркестратор (чаще всего Kubernetes).

Kubernetes как стандарт продакшен-оркестрации

Kubernetes даёт базовые примитивы:

реплики сервисов (масштабирование)

self-healing (перезапуск упавших контейнеров)

rollout/rollback (контролируемый деплой)

управление конфигами и секретами

планирование ресурсов CPU/RAM/GPU

Что делать статeless, а что stateful

Чтобы горизонтально масштабировать API, сервис должен быть stateless.

stateless: API-обработчики, orchestrator запроса, форматирование ответа

stateful: диалоги, память, кэш, очереди, БД, индексы

Практическое следствие для тем RAG и агентов:

история диалога и память агента должны храниться вне процесса (PostgreSQL/Redis/векторная БД)

ingestion и переиндексация должны выполняться воркерами, а не “внутри API-пода”

Минимальный Deployment (идея)

Это не “полный манифест”, но он показывает ключевое: реплики, образ, порты, секреты.

Асинхронность: ускоряем API и не блокируем сервер

Что означает async в Python Backend

Асинхронность — это способ обслуживать много параллельных запросов, пока часть операций ждёт внешние ресурсы:

HTTP к LLM API

запросы в векторную БД

Redis/PostgreSQL (если используете async-драйвер)

В FastAPI это делается через async def и неблокирующие клиенты (например, httpx).

FastAPI Documentation

httpx Documentation

Главная ошибка: “async-роут + блокирующая работа внутри”

Если внутри async def вы делаете тяжёлую CPU-работу (например, локальный inference без выделенного воркера) или используете блокирующий клиент, вы:

блокируете event loop

ухудшаете p95

теряете смысл асинхронного API

Правило:

I/O-bound (сеть, БД) оставляем в async

CPU/GPU-bound (тяжёлые вычисления) уносим в отдельный пул/процесс/воркер или в специализированный inference-сервис

Когда хватает “встроенного” бэкенд-фона, а когда нужна очередь

FastAPI имеет простые фоновые задачи, но они подходят только для коротких и некритичных действий. Для AI-Backend почти всегда нужна полноценная очередь, потому что ingestion и eval должны:

переживать рестарт API

иметь ретраи и контроль ошибок

масштабироваться независимо от API

Очереди задач: ingestion, eval, batch и backpressure

Очередь задач — это способ отделить:

быстрый API-ответ пользователю

тяжёлую работу в фоне (воркеры)

В теме RAG мы обсуждали ingestion-конвейер, а в теме ML — обучение и batch-инференс. Оба сценария естественно ложатся на очередь.

Типичные задачи для очередей в этом курсе

ingestion: парсинг документов, чанкинг, эмбеддинги, запись в векторную БД

переиндексация: пересчёт эмбеддингов при смене модели или чанкинга

офлайн-оценка RAG: расчёт Recall@k и метрик качества ответов

агентные “долгие” действия: сбор отчётов, массовые операции через интеграции

ML: переобучение, пересчёт фичей, batch inference

Популярный вариант для Python:

Celery Documentation

Минимальный пример Celery-задачи

Идемпотентность и защита от дублей

В AI-сценариях ретраи — норма. Поэтому фоновые задачи должны быть идемпотентными:

повторная обработка doc_id не должна создавать дубль чанков

операции записи (создание тикета, отправка письма) должны иметь idempotency_key

Это напрямую связано с темой агентных инструментов: любое действие во внешней системе должно быть безопасно повторяемым.

Backpressure и деградация

Если внешняя система (например, LLM API) замедлилась, очередь начнёт расти. Продакшен-практика:

лимитировать число воркеров и параллелизм

ставить таймауты и ретраи с увеличением задержки

вводить “режим деградации” (например, временно отключить rerank)

кэшировать результаты там, где это безопасно

GPU: когда нужно и как подключать в продакшене

Когда GPU действительно оправдан

GPU имеет смысл, когда вы делаете локальный inference:

open-source LLM (генерация)

embedding-модель или reranker на своей инфраструктуре

CV/ASR модели

Если вы используете внешний LLM API, GPU обычно не нужен вашему сервису, но может быть нужен вашему RAG/ML конвейеру (например, локальные эмбеддинги).

GPU в контейнерах

Для доступа к GPU в контейнере обычно используют NVIDIA runtime и инструменты.

NVIDIA Container Toolkit Documentation

Ключевая идея:

вы собираете образ (часто на CUDA-базе)

при запуске даёте контейнеру доступ к GPU

GPU в Kubernetes

В Kubernetes GPU планируется как ресурс. Обычно ставят NVIDIA device plugin.

NVIDIA Kubernetes Device Plugin (GitHub)

Практические правила:

выделяйте отдельные GPU-поды для inference, не смешивайте с API

задавайте лимиты ресурсов, чтобы избежать “шумных соседей”

используйте автоскейлинг по метрикам (очередь, загрузка GPU, latency)

Отдельный inference-сервис как более контролируемая архитектура

Для сложных случаев удобнее выделить inference как отдельный сервис:

API вызывает inference по HTTP/gRPC

inference сервис масштабируется отдельно

проще внедрить батчинг и управление очередями

Это хорошо сочетается с курсом:

API остаётся тонким

orchestrator управляет шагами

очереди обрабатывают тяжёлые операции

наблюдаемость видит каждый этап

Кэш: ускорение, контроль стоимости и стабильность

Кэш в AI-Backend — это не только ускорение, но и прямое снижение стоимости токенов и внешних вызовов.

Redis Documentation

Что кэшировать в сценариях LLM, RAG и агентов

Три самых практичных слоя кэша:

кэш retrieval: результат поиска top-k по запросу и фильтрам

кэш LLM-ответов: безопасно только для детерминированных запросов и одинакового контекста

кэш инструментов: результаты внешних API (справочники, статусы), если допустимо по бизнес-логике

Ключи кэша и версионирование знаний

В теме RAG мы говорили про doc_version и ingested_at. Это должно влиять на кэш:

если обновились документы или индекс, старый retrieval-кэш может стать неправильным

если изменился промпт или модель, LLM-кэш может стать нерелевантным

Практика для ключей:

включайте версию индекса или knowledge_version

включайте модель и важные параметры (например, temperature=0 или профиль генерации)

Пример ключа:

TTL и защита от “cache stampede”

TTL помогает автоматически очищать кэш, но при массовом истечении ключей может случиться “штурм” внешних систем.

Практики:

добавляйте небольшой случайный разброс TTL (jitter)

используйте блокировку на пересчёт (один пересчитывает, остальные ждут)

кэшируйте отрицательные результаты ограниченно (например, “ничего не найдено” на короткий TTL)

Минимальный пример кэша в Python (Redis)

Ключевой принцип: кэш должен быть контролируемым и версионированным.

Наблюдаемость в деплое: без неё нельзя масштабировать безопасно

Из первой статьи курса: наблюдаемость — обязательна. В продакшен-деплое важно видеть:

p50/p95 по этапам (retrieval, rerank, generation, tool calls)

ошибки и таймауты внешних систем

токены и стоимость на запрос

размеры очередей и время ожидания задач

использование CPU/RAM/GPU

Стандартная база:

OpenTelemetry Documentation

Практика:

протаскивайте trace_id через API, воркеры и инструменты

логируйте версии: model, embedding_model, knowledge_version, model_version (для ML)

Чеклист продакшен-деплоя для AI-Backend

| Область | Что проверить | Почему это важно | |---|---|---| | Контейнеры | фиксированные зависимости, нет секретов в образе | воспроизводимость и безопасность | | API | stateless, таймауты, лимиты, rate limit | масштабирование и защита бюджета | | Очереди | ретраи, идемпотентность, dead letter подход | надёжность ingestion/агентов/ML | | RAG | версионирование знаний, ACL-фильтры, кэш retrieval | качество и защита от утечек | | GPU | отдельные inference-поды, лимиты, мониторинг загрузки | стабильность и стоимость | | Кэш | ключи включают версии, TTL, защита от stampede | скорость и контроль затрат | | Наблюдаемость | трассы этапов, токены, ошибки, очереди | управляемость качества |

Как эта тема связывает всё, что уже было в курсе

Архитектура AI-Backend задаёт разделение: API, сервисный слой, data, workers, observability.

Интеграция LLM даёт нам “дорогие” и недетерминированные вызовы, которые нужно ограничивать и кэшировать.

RAG в продакшене приносит ingestion, версионирование знаний и retrieval-метрики, которые требуют очередей и наблюдаемости.

Агенты добавляют tool calling и длинные траектории, поэтому особенно важны лимиты, идемпотентность и аудит.

Классический ML приносит отдельные пайплайны и реестр моделей, а значит фоновые задачи и воспроизводимые деплои.

Если всё это собрать, получается продакшен-система, где AI — не “скрипт вокруг LLM”, а контролируемая платформа.

Наблюдаемость, безопасность и стоимость: мониторинг, guardrails и тестирование

В предыдущих темах курса мы собрали основу AI-Backend (слои API/сервисы/данные/воркеры), научились интегрировать LLM (SDK, structured outputs, tool calling), построили RAG в продакшене, обсудили агентную оркестрацию, ML-пайплайны и деплой/масштабирование.

Эта тема связывает всё это в продакшен-контур: как сделать систему управляемой.

Наблюдаемость отвечает на вопрос: что произошло и почему?

Безопасность отвечает на вопрос: можно ли доверять действиям и данным?

Стоимость отвечает на вопрос: сколько это стоит и как держать бюджет?

Тестирование отвечает на вопрос: как не сломать качество и безопасность изменениями?

!Общая карта, где в запросе живут мониторинг, guardrails и контроль стоимости

Что такое наблюдаемость в AI-Backend

В классическом Backend достаточно знать: код ответа, время, ошибки. В AI-Backend этого мало из-за вероятностности LLM, многосоставных пайплайнов (retrieval, rerank, tool calls) и стоимости токенов.

Наблюдаемость обычно делят на три сигнала.

Логи: события и детали (кто, что запросил, какие этапы прошли).

Метрики: числа во времени (p95 latency, error rate, токены/стоимость).

Трейсы: связанный граф операций одного запроса от API до инструментов.

Базовый стандарт для трейсинга и метрик в микросервисных системах: OpenTelemetry.

Минимальный контракт наблюдаемости: что писать для каждого AI-ответа

Цель: чтобы любой ответ можно было воспроизвести и объяснить.

Идентификаторы и корреляция

request_id: уникальный идентификатор HTTP-запроса.

trace_id: идентификатор распределённого трейса (API -> retrieval -> LLM -> tools).

conversation_id: идентификатор диалога (если чат).

user_id и tenant_id: для мульти-тенантности и контроля доступа.

Практика: протаскивать trace_id через orchestrator, воркеры и интеграции.

AI-метаданные, которые нужны в логах

model: имя и версия LLM.

embedding_model: если есть retrieval.

prompt_version: версия шаблона промпта.

knowledge_version: версия индекса/знаний (из темы про RAG и версионирование).

tool_calls: какие инструменты вызывались и сколько раз.

Токены и стоимость

prompt_tokens, completion_tokens, total_tokens.

cost_usd: рассчитанная стоимость (или оценка), плюс разбиение по этапам.

RAG-детали для отладки качества

retrieval_top_k: сколько кандидатов взяли.

retrieval_selected_n: сколько реально положили в контекст.

citations: список doc_id/chunk_id.

acl_filter_applied: был ли фильтр по доступам.

Важно: не логируйте “сырой” пользовательский текст и фрагменты документов без необходимости. Для расследований обычно достаточно хэшей, идентификаторов, статистики и редактированного текста.

Практическая реализация: structured logging и request id в FastAPI

Ниже пример middleware, который добавляет request_id и возвращает его клиенту. trace_id обычно задаёт OpenTelemetry-инструментация.

Для структурированных логов используйте JSON-формат на стороне логгера (конкретная библиотека на ваш выбор), а также добавляйте поля trace_id/request_id в каждый лог в orchestrator и интеграциях.

Метрики, которые реально помогают управлять AI-системой

Технические метрики

http_requests_total и http_errors_total.

latency_ms_p50/p95 по API.

stage_latency_ms по этапам: retrieval, rerank, llm, tool.

timeouts_total и retries_total.

Стоимостные метрики

tokens_total и tokens_per_request.

cost_total и cost_per_request.

cache_hit_rate по retrieval и tool-интеграциям.

Метрики качества, которые можно снять онлайн

answers_with_citations_share.

no_answer_share (доля ответов “данных недостаточно”).

tool_success_share и tool_error_share.

user_feedback_score (лайки/дизлайки/рейтинги, если есть).

Онлайн-метрики не заменяют офлайн-оценку, но ловят деградации быстрее.

Безопасность AI-Backend: угрозы и уровни защиты

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

Ключевые угрозы

Prompt injection: попытка заставить модель игнорировать правила и выдать секреты или вызвать опасный инструмент.

Data leakage: утечки из retrieval при неправильном ACL.

PII leakage: попадание персональных данных в логи, промпты, внешние провайдеры.

Tool abuse: модель вызывает инструмент с неверными параметрами или за пределами прав пользователя.

Базовый принцип

LLM может предложить действие.

Backend должен проверить и разрешить действие.

Это продолжает идею из темы про tool calling и агентов.

Guardrails: что это и где ставить

Guardrails — это набор проверок и ограничений до, во время и после вызова LLM, чтобы система оставалась безопасной и управляемой.

Где guardrails стоят в пайплайне

Pre-LLM: очистка/маскирование, политики доступа, блок-листы, классификация запроса.

During-LLM: строгие схемы tool calling, ограничения по инструментам, лимиты.

Post-LLM: валидация структуры, фильтрация опасного контента, проверка ссылок/citations.

Пример: PII-редакция перед логированием

PII (персональные данные) — например телефон, email, паспортные данные. Минимальная практика: редактировать перед записью в логи и перед отправкой во внешние сервисы (если политика компании это требует).

Это не идеальный детектор, но иллюстрирует место механизма. В продакшене обычно используют более устойчивые подходы и политика-ориентированную обработку.

Пример: строгая валидация tool args через Pydantic

Это “жёсткая граница”, которая защищает интеграции от мусора и атак.

Дополнительно к валидации всегда нужна авторизация: имеет ли пользователь право видеть этот тикет.

Запрет “универсальных” инструментов

Самый опасный класс инструментов в агентных системах:

execute_sql без ограничений

http_request(any_url)

run_code

Если такие инструменты всё же нужны, вводите ограничения.

Read-only режим.

Allowlist доменов/таблиц/операций.

Таймауты, лимиты, аудит.

Human-in-the-loop для операций записи.

Контроль доступа в RAG: обязательный слой безопасности

В теме про RAG мы отмечали, что retrieval без ACL-фильтра создаёт утечки. Практический минимум:

хранить tenant_id и acl_groups в метаданных каждого чанка

передавать фильтры в запрос к векторной БД

логировать факт применения ACL-фильтра

Если ваше хранилище не умеет фильтры по метаданным, retrieval нужно строить иначе (например, по отдельным индексам на тенант).

Контроль стоимости: бюджеты, лимиты и кэш

В AI-Backend стоимость не является побочным эффектом, она часть SLO.

Что создаёт стоимость

токены LLM

rerank (если используете отдельную модель)

эмбеддинги (в ingestion и иногда в запросе)

tool calls к платным API

GPU-время при локальном инференсе

Три практических механизма контроля

Лимиты: max_tokens, max_steps, max_tool_calls, таймауты.

Маршрутизация: выбирать более дешёвую модель для простых запросов.

Кэш: retrieval-кэш и кэш результатов инструментов, где это допустимо.

Кэширование и версионирование тесно связано с темой RAG.

если поменялся индекс, retrieval-кэш должен инвалидироваться

если поменялись промпты или модель, LLM-кэш (если он есть) должен быть версионирован

Пример: простой cost tracker на уровне orchestrator

Здесь price_per_1k_tokens_usd — тариф вашей модели, а usage вы берёте из ответа провайдера LLM.

Тестирование AI-Backend: как сделать регрессии заметными

Тестирование в AI-Backend — это смесь детерминированного и вероятностного.

Детерминированное: инструменты, ACL, схемы, маршрутизация, кэш, бизнес-правила.

Вероятностное: качество ответа LLM, качество retrieval, поведение агента.

Пирамида тестов для AI-системы

Unit-тесты: функции чанкинга, фильтры, редактирование PII, инструменты.

Контрактные тесты: схемы structured outputs и tool args/results.

Интеграционные тесты: orchestrator + retrieval + mock LLM/tool.

Оценочные тесты: офлайн-датасеты для RAG и агентных задач.

Контрактные тесты structured outputs

Если вы ожидаете JSON по схеме, тестируйте это как контракт.

схема должна быть строгой (additionalProperties: false)

валидация должна падать на неожиданных полях

ошибки должны приводить к управляемому fallback (ретрай или безопасный ответ)

Регрессионные тесты RAG

Практический подход:

Соберите небольшой датасет реальных вопросов.

Для каждого вопроса сохраните ожидаемые документы или хотя бы ожидаемый doc_id.

Тестируйте retrieval метриками Recall@k и Precision@k при изменениях чанкинга/эмбеддингов.

Для оценки RAG часто используют фреймворки и методики, например Ragas.

Сценарные тесты для агентов

Цель: проверить, что агент вызывает правильные инструменты и не делает запрещённые действия.

Сценарий обычно включает:

ввод пользователя

ожидаемый набор разрешённых инструментов

ожидаемый факт запрета опасного действия

лимиты на шаги и tool calls

Это напрямую связывается с темой про идемпотентность и лимиты из статьи про деплой и масштабирование.

LLM-as-a-judge: аккуратно и контролируемо

Оценка “модель оценивает модель” может быть полезной, но требует дисциплины.

фиксируйте промпт судьи и версию модели

используйте слепое сравнение (A/B) там, где возможно

валидируйте judge на небольшой экспертной разметке

Инциденты и аудит: что должно быть возможным в продакшене

В зрелой системе вы должны уметь ответить на вопросы.

Кто получил ответ и по какому запросу?

Какие источники были использованы (doc_id/chunk_id) и какая была версия знаний?

Какие инструменты вызывались, с какими типами аргументов и чем закончились?

Какая модель и какой промпт использовались?

Сколько это стоило и где было узкое место по задержкам?

Это достигается комбинацией: трейсинг + структурированные логи + версии (моделей, промптов, знаний) + политика хранения.

Практический чеклист продакшен-готовности

| Область | Минимум, который должен быть | Зачем | |---|---|---| | Наблюдаемость | trace_id, этапы, токены, источники, tool calls | отладка качества и инцидентов | | Безопасность | ACL в retrieval, валидация tool args, авторизация инструментов | защита от утечек и злоупотреблений | | Guardrails | pre/post проверки, schema validation, лимиты | управляемость вероятностных ответов | | Стоимость | бюджеты, маршрутизация моделей, кэш с версионированием | стабильный финансовый контур | | Тестирование | unit/contract/integration + eval датасеты | защита от регрессий |

Как это связывает курс в единую систему

Из архитектуры AI-Backend берём разделение ответственности: наблюдаемость и guardrails не живут в роуте, они часть платформенного слоя.

Из LLM-интеграции берём structured outputs и tool calling, которые обязаны быть защищены схемами и авторизацией.

Из RAG берём версионирование знаний, citations и метрики retrieval.

Из агентов берём лимиты, идемпотентность и аудит действий.

Из деплоя и масштабирования берём очереди, кэш, таймауты и общую эксплуатационную дисциплину.

Результат: AI-Backend становится системой, где качество, безопасность и стоимость измеряются и контролируются так же строго, как функциональность.