ai-sidekick: Быстрый старт в мир AI-агентов и RAG

Приветствую, Хабр! Представляю вам свой framework - ai-sidekick

Мы разберём готовый к работе фреймворк для экспериментов с MCP-tools. А также, на его основе, рассмотрим архитектуру RAG (Retrieval-Augmented Generation) AI-ассистента для поиска информации в вашей собственной базе знаний. Это не набор абстракций в тысячу строк, а минималистичная кодовая база на Python и Docker, которая предоставляет возможность эксперементировать с конфигурациями и кодом под ваши задачи.

Материал предназначен для разработчиков различного уровня (в основном для начинающих), которые хотят быстро и «без воды» на практике разобраться в основах RAG и агентных системах. Хотя на данный момент существует множество отличных глубоких теоретических статей, а также многофункциональных сложных реализаций с разнообразными фичами, найти готовую к запуску простую и понятную реализацию бывает сложно. Мне самому, при погружении в тему, не хватало такого «стартового комплекта», который можно развернуть и изучить «вживую» — от обработки данных до готового диалогового окна.

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

Глоссарий

Markdown — облегчённый язык разметки для создания форматированного текста с помощью простого синтаксиса, преобразуемого в HTML. Официальная документация (Daring Fireball)

Эмбеддинг (embedding) — это представление объектов (слов, изображений, пользователей) в виде числовых векторов фиксированной размерности, где семантически близкие объекты располагаются рядом в многомерном пространстве

Qdrant — векторная база данных с открытым исходным кодом, предназначенная для хранения и поиска знаний (или points) по векторным представлениям (embedding's). Qdrant (У ребят очень хорошая документация также и в контексте RAG)

FastAPI — высокопроизводительный веб-фреймворк на Python для быстрой разработки API. Официальная документация FastAPI

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

LLM (Large Language Model) — тип нейросетевой модели, обученной на обширных текстовых данных для генерации, классификации и анализа текста на естественном языке. Статья о LLM от Stanford

Aiogram — асинхронный фреймворк на Python для создания ботов и приложений под платформу Telegram с использованием её официального Bot API. Aiogram

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

Telegram — кроссплатформенный мессенджер с акцентом на скорость и безопасность, предоставляющий публичное API для создания ботов. Telegram

Архитектура

pipeline:

1. Знания (в нашему случае .md файлы) преобразуются в метаданные с embedding's (point) и попадают в векторную базу данных Qdrant

2. Пользователь взаимодействует с системой через диалоговое окно Telegram

3. Aiogram передаёт сообщение от пользователя в API (FastAPI)

4. API обрабатывает контекст пользователя и передаёт диалог в LLM

5. LLM (подключённая к tools) решает какой tool использовать (в нашем случае tool будет один — retriev, который отвечает за предоставление контекста из базы знаний)

6. LLM решает использовать tool retriev

7. retriev

   1. выполняет поиск знаний в Qdrant

   2. ранжирует знания в порядке релевантности

   3. преобразует знания в более понятный для LLM вид (контекст)

   4. отдаёт контекст LLM

8. На основе контекста LLM генерирует ответ и отдаёт API. API -> Bot(Aiogram) -> Telegram.

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

• data: подготовка знаний для Qdrant

• app: API (FastAPI)

• bot: взаимодействие с telegram (Aiogram)

Ниже представлена структура исходного кода проекта:

ai-sidekick/ ├── app/ # Основное приложение (FastAPI) │ ├── agent.py # Агент для взаимодействия с LLM │ ├── client.py # FastAPI клиент и эндпоинты │ ├── configs.py # Конфигурация API │ └── tools/ # Инструменты агента │ └── retrieve.py # Модуль поиска информации │ ├── bot/ # Бот-интерфейс (Telegram) │ ├── bot.py # Основная логика бота (Aiogram) │ └── configs.py # Конфигурация бота │ └── data/ # Работа с данными и БД ├── configs.py # Конфигурация модуля работы с данными ├── generate_data.py # Генерация знаний (points) ├── upload_data.py # Загрузка сгенерированных знаний в БД └── kbase/ # База знаний (.md файлы)

Пример работы

Лучший способ понять систему — увидеть её в работе на реальной задаче.

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

бабушкин яблочный пирог.md

## Ингредиенты *Тесто:* - Мука: 300г - Яйца: 2 шт. - Сахар: 150г *Начинка:* - Яблоки: 5 шт. - Корица: 1 ч.л. ## Инструкция 1. Взбить яйца с сахаром 2. Добавить муку, замесить тесто 3. Нарезать яблоки, смешать с корицей 4. Выпекать 40 минут при 180°C ## 📌 Советы Пирог лучше подавать тёплым. Хорошо сочетается с ванильным мороженым. #теги #рецепт #выпечка **бабушкин яблочный пирог.md**

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

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

бабушкин яблочный пирог.md

## Ингредиенты *Тесто:* - Мука: 300г - Яйца: 2 шт. - Сахар: 150г *Начинка:* - Яблоки: 5 шт. - Апельсин 1 шт. - Корица: 1 ч.л. ## Инструкция 1. Взбить яйца с сахаром 2. Добавить муку, замесить тесто 3. Нарезать яблоки, смешать с корицей 4. Добавить мякоть и сок апельсина 5. Выпекать 40 минут при 180°C ## 📌 Советы Пирог лучше подавать тёплым. Хорошо сочетается с ванильным мороженым. #теги #рецепт #выпечка

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

Заключение

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

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

Цель ai-sidekick — не соревноваться с мощными production-фреймворками, а стать понятной отправной точкой и песочницей. Всё, что скрыто за сложными терминами в статьях (чанкинг, tools, семантический поиск), здесь можно буквально потрогать руками в 10 небольших файлах. Вы можете за вечер:

• Поменять LLM-провайдера (с OpenAI на Anthropic, локальную Llama или что-то ещё).

• Поэкспериментировать со стратегиями чанкинга или retrieve и моделями эмбеддингов, чтобы улучшить качество поиска.

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

• Подключить другой мессенджер вместо Telegram или сделать веб-интерфейс.

Я буду рад, если настоящее решение поможет вам быстрее разобраться в технологиях, запустить свой первый прототип или вдохновит на ведение структурированной базы знаний. Исходный код, инструкции по запуску и актуальные конфигурации ждут вас в репозитории.

Ссылки и обратная связь

• 🔗 GitHub: https://github.com/lezakhar/ai-sidekick

• 📣 Telegram: Если вам, как и мне, нравится созидать, вы горите новыми идеями и проектами, хотите обсудить детали фреймворка, или вы просто добрый человек, то очень буду вам рад на канале

• 💼 LinkedIn: Для деловых контактов и обсуждения проектов linkedin

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

Из возможных продолжений:

1. Интеграция гибридного поиска в retrieve (более точный поиск)

2. Интеграция Cross-Encoder (вторая стадия для точного реранжирования результатов)

3. Поиск эвристик и методов подготовки и генерации данных для базы знаний

4. Production-архитектура для масштабирования

5. Разработка агента с возможностью цепочек размышления и интеграция полезных tools