Друзья, приветствую! Сегодня я хотел бы рассмотреть интересующую многих тему, а именно связку большой языковой модели по типу DeepSeek или ChatGPT со своей базой знаний.
В рамках этой статьи я дам вам подробное объяснение принципов работы векторных баз данных и того, зачем их можно использовать в рамках связки своей базы знаний с готовыми «большими» нейросетями.
В качестве примера рассмотрим поиск по документации Amvera Cloud — облачной платформы со встроенным проксированием к OpenAI, Gemini, Claude, Grok, а также с возможностью обновления проектов через git push.
Мы сейчас активно разрабатываем ИИ-агента, который будет помогать пользователям с развертыванием проектов в облаке, устранением ошибок в коде и конфигурации, а также упростит работу с документацией. И как раз поиск по документации — отличный кейс для применения векторной базы данных, такой как Chroma.
Сразу разберем некий ограничивающий блок
Готовые нейросети, такие как DeepSeek, ChatGPT или Claude изначально заточены на то, что на вход они будут получать некие текстовые данные с определенным контекстом (промпт) и далее, на основании своих параметров и обучения они будут делать обработку вашего запроса, выполняя необходимую задачу.
То есть, учитывая что мы будем работать с готовыми языковыми моделями, от процесса подготовки промптов с определенным контекстом и отправки запросов к готовым нейросетям мы отойти не сможем.
Отсюда выходит логичная задача — каким образом нам подвязать к процессу общения с нейросетью нашу базу данных. Представим, что это тысячи страниц профессиональной литературы. Сомнительно то, что мы будем сотни мегабайт данных формировать в один гигантский промпт и при этом будем ожидать, что нейросеть согласится с ним работать. Как минимум, мы получим ошибку о том, что переданный контекст превышен.
Логично, что напрашивается решение формировать свой запрос, дополняя его только необходимым для этого конкретного запроса контекстом, но как это сделать? Простейший вариант — это организация некоего SEO-поисковика. Мы отправляем, например, «обучение нейросетей» и по нашим гигабайтам данных идет поиск, но и тут возникает логическая проблема. Даже если мы найдем информацию, допустим это 1000 вхождений такой фразы как «обучение нейросетей», каким образом нам выделять этот самый контекст? Как мы будем решать, что важно передавать нейросети для общения, а что передавать не нужно?
Конечно, можно сильно заморочиться с поисковиком этим, но, как вы понимаете, подход не то чтобы оптимальный, а это значит, что необходимо искать другое, более гибкое и удачное решение, о котором мы сегодня детально поговорим.
Векторные базы данных
Я знаю, что вы, с большой вероятностью, либо не слышали о существовании таких баз данных, либо знакомы с ними поверхностно. Поэтому далее я подробно и на пальцах разложу, что это за базы данных такие и, главное, мы разберемся, как они помогут нам в нашей задаче.
Если коротко и грубо, то векторная база данных — это представление данных: текстовых или байтовых в числовом представлении или, правильнее, в виде векторов.
Для примера, слово «привет» в векторном представлении будет иметь следующий вид [-0.012, 0.124, -0.056, 0.203, …, 0.078] (убрал лишние цифры для наглядности).
В сегодняшнем контексте большого значения нет в том, каким математическим образом получаются эти цифры. Сейчас важно только общее понимание цифрового представления данных.
Практическая польза
На этом этапе вы можете закономерно сказать: «Это все весело и очень интересно, но какая в этом всем практическая польза и как вообще получать эти странные цифры»? Давайте разберемся.
Первое, что нужно понять — это то, что нейросети не умеют читать ваши тексты или смотреть на ваши фото в общечеловеческом представлении. Например, отправляя запрос ChatGPT, происходит следующее:
-
Нейросеть принимает текст.
-
Трансформирует этот текст в векторы или, более корректное название, в эмбеддинги.
-
Использует эти эмбеддинги для генерации ответа на основе обученных параметров модели.
-
Делает вычисления.
-
Получает ответ в виде эмбеддинга.
-
Трансформирует эмбеддинг в человеческий текст (Natural Language).
-
Отправляет вам человеческий текст.
То есть, уже на данном этапе видно, что в общении с нейросетями появляется такая штука, как числовое представление входящей информации (представление в виде эмбеддингов), и теперь давайте разберемся, для чего это необходимо.
Эмбеддинги и зачем они нужны
Эмбеддинги — это «цифровые отпечатки смысла» текста. Давайте разберем это утверждение на реальном примере.
Представьте, что у вас есть огромная куча документов — книги, статьи, заметки. И вы хотите находить в них информацию не по точным словам, а по смыслу.
Как это реализовать:
-
Нейросеть принимает все подготовленные вами слова и превращает их все в последовательности чисел (эмбеддинги).
Пример:
-
«Кот» → [0.2, -0.5, 0.7, …]
-
«Кошечка» → [0.19, -0.48, 0.69, …] (почти те же числа, ведь смысл близкий!).
-
Векторная база данных, например Chroma, хранит эти числа и умеет:
-
Искать близкие по смыслу векторы (даже если слова разные).
-
Отвечать на запросы типа: «Найди что-то про усатых питомцев» → выдаст документы про котов, кошек, котят.
Простая аналогия:
-
Обычный поиск (как Ctrl+F): ищет точные совпадения слов.
-
Запрос «автомобиль» не найдет «машина».
-
-
Поиск по эмбеддингам: ищет похожие смыслы.
-
«Автомобиль», «машина», «транспорт» — будут рядом в числах, и база их свяжет.
-
Зачем это нужно?
-
Чат-боты (как ChatGPT) используют эмбеддинги для понимания запросов по смыслу, а не по точному соответствию.
-
Вы можете спросить документ своими словами, и система поймет, даже если там нет точных совпадений.
Итог: Эмбеддинги — это «переводчик» текста в числа, чтобы искать по смыслу, а не буквам. Векторные базы — их «хранилище», где поиск работает как магнит для похожих идей.
Существуют специальные нейросети, которые умеют трансформировать ваши текстовые данные в векторное (числовое) представление. Для таких задач не обязательно тянуть таких гигантов, как ChatGPT или DeepSeek, а достаточно будет брать именно специальные нейросети. Далее, в практической части, я буду проводить демонстрацию создания эмбеддингов и реализацию умного поиска на примере нейросети paraphrase-multilingual-MiniLM-L12-v2.
Данная нейросеть весит всего 500 МБ, и она запускается локально даже на средних компьютерах, так что идеально подойдет для наших задач.
Векторные базы данных (продолжение)
К этому моменту вы должны понять, что при работе с данными в числовом представлении действует следующая связка:
Текстовые данные при помощи специальной нейросети трансформируются в векторное (числовое) представление. Далее, для того чтобы начал работать умный поиск, нам нужно:
-
Получить эмбеддинг вашего массива данных в векторном представлении.
-
Написать текстовый запрос по типу «найди все, что носится на руке».
-
Трансформировать запрос в векторное представление.
-
Сравнить вектор запроса с векторами из большого эмбеддинга.
-
Найденный результат трансформировать обратно в человеческую речь.
-
Выдать результат.
Теперь возникает логический вопрос с хранением этих числовых данных. Понятно, мы можем взять текст, потом его превратить в векторы при помощи какой-то, пока непонятной, paraphrase-multilingual-MiniLM-L12-v2, но что там с хранением?
Хранится это может как в специализированной базе данных, по типу Chroma, с которой мы будем сегодня работать, так и в оперативной памяти.
Принцип хранения в оперативной памяти:
-
Подготавливаем текстовые данные.
-
Их трансформируем в эмбеддинги.
-
Отправляем запрос уже на эмбеддинг.
-
После завершения работы скрипта память очищается, и при новом заходе появляется повторная необходимость в генерации эмбеддинга.
Принцип хранения в специализированной базе данных:
-
Подготавливаем текстовые данные.
-
Трансформируем их в эмбеддинг.
-
Эмбеддинг сохраняем в формате базы данных.
-
При работе подключаемся к базе данных и используем готовый эмбеддинг.
Векторные базы данных бывают как локальные (Self-hosted решения), так и облачные.
Простейшая локальная база данных — это ChromaDB, с которой мы будем сегодня работать. Выбрал ее за простоту и за очень хорошую интеграцию с языком программирования Python.
Другие векторные локальные базы данных: Qdrant, Weaviate, Milvus и другие.
Вот несколько примеров облачных баз данных: Pinecone, RedisVL, Qdrant Cloud и другие.
Чем сегодня займемся?
Далее еще будет теория, но я уверен, что вы ждете практической части. Поэтому давайте разберемся, чем мы практически займемся, кроме поглощения теоретической информации.
Далее я покажу вам на практическом примере, как трансформировать текстовые данные в векторную базу данных ChromaDB. Мы сначала на простом примере создадим базу данных и поработаем с поиском по ней, а после уже будем работать с более сложным примером, на основе которого мы будем делать нашего умного ассистента в дальнейшем.
После того как мы полностью разберемся с тем, как работает генерация эмбеддингов и умный поиск внутри них — мы подключим к общему контексту большие нейросети DeepSeek и GPT, реализуя такую логику:
-
Пользователь отправляет определенный запрос.
-
Мы, используя умный поиск, достаем из нашей векторной базы данных дополнительный контент.
-
Запрос пользователя вместе с нашей «умной выдачей» мы перенаправим в DeepSeek / GPT и получим ответ от нейросети уже на основе нашего личного контекста.
Будет интересно!
Простая векторная база данных
Теперь, для закрепления общего теоретического блока, описанного выше, подготовим простую базу данных ChromaDB на основе описания товаров выдуманного интернет-магазина (для простейшего примера это наглядный пример).
Представим, что у нас есть массив товаров такого вида:
SHOP_DATA = [
{
"text": 'Ноутбук Lenovo IdeaPad 5: 16 ГБ RAM, SSD 512 ГБ, экран 15.6", цена 55000 руб.',
"metadata": {
"id": "1",
"type": "product",
"category": "laptops",
"price": 55000,
"stock": 3,
},
},
{
"text": "Смартфон Xiaomi Redmi Note 12: 128 ГБ, камера 108 МП, цена 18000 руб.",
"metadata": {
"id": "2",
"type": "product",
"category": "phones",
"price": 18000,
"stock": 10,
},
},
# ... и так далее
]
Как видите, информация представлена в виде списка словарей, каждый из которых содержит 2 основных ключа: text и metadata.
Документы и метаданные в векторных базах данных
Это важный момент, на котором стоит остановиться подробнее. Вы должны понимать, что в базе данных ChromaDB весь наш «умный» поиск будет работать «из коробки» только на значении ключа text (имя может быть любым).
В контексте векторных баз данных выделяются такие понятия как документы (в нашем случае это текст, описывающий конкретный товар) и метаданные.
Ограничения на длину документа
На этапе подготовки текстовых данных для загрузки в векторную базу крайне важно учитывать ограничения по длине текста, устанавливаемые моделью, которая будет преобразовывать его в векторное представление. Эти ограничения зависят от конкретной нейросети и обычно составляют от 256 до 512 токенов.
Таким образом, если вы, например, планируете добавить в базу полную книгу объёмом в 200 страниц, её необходимо предварительно разбить на более мелкие фрагменты — каждый длиной не более 256–512 токенов. Это обеспечит корректную обработку текста моделью и сохранение смысловой целостности в векторном пространстве.
Модель paraphrase-multilingual-MiniLM-L12-v2, с которой мы будем работать сегодня, имеет ограничение в 512 токенов на документ. Это примерно 250–350 слов или 1500–2200 символов. Однако, учитывая, что мы будем использовать наши данные совместно с мощными нейросетями Deepseek и ChatGPT, мы сделаем размер документов меньше, чтобы избежать перегруженности контекста.
Роль метаданных
Метаданные — это наши помощники, которые делают поиск более точным и локальным. Вот простой пример:
Представим, что ваш интернет-магазин занимается реализацией ноутбуков, смартфонов и прочей техники. Вы можете ограничить умный поиск по метаданным категории (category). Независимо от того, будете ли вы использовать метаданные для поиска явно, важно понимать, что найденные документы (результаты поиска) всегда будут содержать эти метатеги, что позволит вам выполнять дополнительную обработку.
Пример с книгами:
Представим, что вы решили загрузить в векторную базу данных всю серию книг про Гарри Поттера. Вы разбили весь текст на фрагменты по 512 токенов, а в качестве метатегов указали: название книги, номер страницы, номер главы и прочую информацию.
Далее вы отправляете запрос в стиле «Когда Гарри Поттер узнал о крестражах». Ваш умный поиск возвращает определенное количество результатов — документов с метатегами, которые позволяют вам понять, из какой это книги и на какой странице находится информация.
Другой пример работы с метатегами — это ограничение поиска конкретной книгой, серией книг или автором при формировании запроса.
При этом помните, что умный поиск никак не связан с метаданными, если вы явно не укажете логику их обработки в запросе.
Практическое применение метаданных
В контексте метаданных для наших товаров:
{
"id": "1",
"type": "product",
"category": "laptops",
"price": 55000,
"stock": 3,
}
Мы передаем ID товара, тип, категорию, цену и остаток на складе. Например, на сайте можно было бы реализовать умный поиск по товарам и на странице результатов отображать для пользователя только те товары, которые имеют найденный ID.
Таким образом, векторная база данных — это отличный инструмент не только для интеграции с нейросетями, но и для решения практических задач, таких как умный поисковик на сайте или в вашем API.
Создание векторной базы данных на Python
Теперь напишем немного кода. Код будет простым, так как нам не нужно делить документы (описания товаров) на фрагменты или выполнять дополнительную логику по парсингу и обработке товаров.
Подготовка проекта
Первое, что делаем — это создаем новый проект Python с выделенным виртуальным окружением. В проект добавляем файл requirements.txt со следующим содержимым:
langchain-huggingface==0.1.2
torch==2.6.0
loguru==0.7.3
chromadb==0.6.3
sentence-transformers==3.4.1
langchain-chroma==0.2.2
pydantic-settings==2.8.1
langchain-text-splitters==0.3.7
langchain-deepseek==0.1.3
langchain-openai==0.3.11Что за langchain?
Вы могли заметить, что слово langchain в зависимостях у меня встретилось целых 5 раз, что не случайно.
Langchain – это мощнейший инструмент Python, который позволяет «из коробки» интегрировать в свои проект огромное количество нейросетей и прочих полезных инструментов. Данный фреймворк заслуживает упоминания далеко не в одной статье, поэтому, настоятельно рекомендую ознакомиться с документацией по проекту (105к + звезд на GitHub должны намекать на то что проект стоит внимания).
В сегодням же проекте мы будем использовать следующие инструменты данного фреймворка:
langchain-text-splitters==0.3.7
Инструмент для разбиения больших текстов на меньшие фрагменты (чанки). Содержит различные стратегии сегментации: по символам, предложениям, токенам, семантическим блокам. Необходим для обработки объемных документов, когда они превышают контекстное окно языковых моделей (256-512 токенов в нашем случае).
langchain-deepseek==0.1.3
Интеграция с моделями DeepSeek AI. Позволяет использовать мощные языковые модели DeepSeek для анализа и генерации текста (сегодня демонстрация будет выпонена на основе модели deepseek-chat).
langchain-openai==0.3.11
Адаптер для работы с API OpenAI. Предоставляет доступ к семейству языковых моделей GPT и их функциям. Включает поддержку чат-моделей, embedding-моделей и функций для работы с изображениями через DALL-E (рассмотрим пример с моделью gpt-3.5-turbo).
langchain-chroma==0.2.2
Коннектор к векторной базе данных ChromaDB. Позволяет хранить и эффективно извлекать векторные представления текстов для реализации функций семантического поиска и построения баз знаний с возможностью поиска по схожести.
langchain-huggingface==0.1.2
Интеграция с экосистемой Hugging Face открывает доступ к тысячам открытых моделей, разработанных сообществом. Среди них языковые модели, модели для эмбеддингов, классификации и других задач в области NLP. Этот инструмент особенно полезен, когда требуется запустить модели локально или использовать специализированные модели. В нашем случае мы сможем применять локальную нейросеть paraphrase-multilingual-MiniLM-L12-v2.
Другие пакеты
-
torch: Библиотека для машинного обучения, на которой работают многие языковые модели
-
loguru: Удобный логгер для отслеживания процесса работы нашего кода
-
chromadb: Собственно, сама векторная база данных, которую мы будем использовать
-
sentence-transformers: Библиотека для преобразования текста в векторы (эмбеддинги)
Установка зависимостей
Теперь выполним установку:
pip install -r requirements.txt
Установка может занять продолжительное время из-за общего веса устанавливаемых пакетов (в моем случае процесс установки занял ~20 минут).
Создание базы данных
Теперь создадим файл с именем create_chromadb.py (имя можете дать любое).
Выполним импорты:
import time
from langchain_huggingface import HuggingFaceEmbeddings
import torch
from loguru import logger
from langchain_chroma import Chroma
Определим основные переменные:
CHROMA_PATH = "./shop_chroma_db"
COLLECTION_NAME = "shop_data"
Коллекции в векторных базах данных можно сравнить с таблицами в классических базах данных. Если не указывать имя коллекции, ChromaDB подставит значение по умолчанию.
Теперь добавим массив товаров (чем больше — тем лучше):
SHOP_DATA = [
{
"text": 'Ноутбук Lenovo IdeaPad 5: 16 ГБ RAM, SSD 512 ГБ, экран 15.6", цена 55000 руб.',
"metadata": {
"id": "1",
"type": "product",
"category": "laptops",
"price": 55000,
"stock": 3,
},
},
# Здесь добавьте остальные товары
]
И наконец, напишем функцию для создания базы данных:
def generate_chroma_db():
try:
start_time = time.time()
logger.info("Загрузка модели эмбеддингов...")
embeddings = HuggingFaceEmbeddings(
model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
model_kwargs={"device": "cuda" if torch.cuda.is_available() else "cpu"},
encode_kwargs={"normalize_embeddings": True},
)
logger.info(f"Модель загружена за {time.time() - start_time:.2f} сек")
logger.info("Создание Chroma DB...")
chroma_db = Chroma.from_texts(
texts=[item["text"] for item in SHOP_DATA],
embedding=embeddings,
ids=[str(item["metadata"]["id"]) for item in SHOP_DATA],
metadatas=[item["metadata"] for item in SHOP_DATA],
persist_directory=CHROMA_PATH,
collection_name=COLLECTION_NAME,
)
logger.info(f"Chroma DB создана за {time.time() - start_time:.2f} сек")
return chroma_db
except Exception as e:
logger.error(f"Ошибка: {e}")
raise
В этом коде мы:
-
Создаем модель для преобразования текста в векторы (эмбеддинги)
-
Инициализируем базу данных Chroma с нашими товарами
-
Передаем тексты, ID, метаданные и настройки пространства поиска
-
Логируем успешное создание базы или ошибки
Важно отметить, что мы используем многоязычную модель paraphrase-multilingual-MiniLM-L12-v2, которая хорошо работает с русским языком. Это позволит нам корректно создавать векторные представления для наших товаров на русском языке. Сама модель при первом запуске будет загружена автоматически из репозитория Hugging Face. При повторных запусках, если модель уже на вашей машине, в загрузке необходимости не будет.
Особенность выбранной модели в том, что она сбалансирована по размеру и качеству — даёт хорошие результаты векторизации текста даже на CPU, но при наличии CUDA-совместимой видеокарты работает значительно быстрее. Плюс, благодаря параметру normalize_embeddings=True, все создаваемые эмбеддинги будут нормализованы, что улучшит точность поиска похожих товаров.
Выполняем код:
if __name__ == "__main__":
generate_chroma_db()
Готово! Теперь у нас есть основа для создания векторной базы данных с описанием из документов. В корне проекта после запуска должна появиться папка с именем «shop_chroma_db», в которой будут лежать файлы базы данных. В дальнейшем мы сможем использовать эту базу для семантического поиска товаров по запросам пользователей — поиск будет находить не только точные совпадения, но и семантически близкие товары.
Пишем поисковик по базе данных
Теперь, когда база готова, мы можем описать простую поисковую систему в её рамках. Принцип тут будет сводиться к следующему:
-
Подключаемся к существующей базе данных, получая эмбеддинги
-
Принимаем от пользователя поисковой запрос
-
Трансформируем поисковой запрос в векторное представление
-
Сравниваем полученный вектор запроса с данными в базе данных
-
Возвращаем пользователю то количество документов, которое он запросил
Что касается выдачи документов пользователю. Тут есть такая особенность: мы всегда указываем то количество документов, которые хотим получить. Допустим, это может быть 5 штук. Если вы не будете жёстко привязываться к метаданным через фильтры, то вы всегда будете получать в ответ от базы данных ровно то количество документов, которое указали.
То есть, даже если выдача вообще не будет соответствовать вашему запросу, вы всё равно ваши 5 документов в ответ получите. Это важно учитывать при разработке пользовательского интерфейса.
Сам ответ состоит из: документа, метаданных, которые к нему были привязаны, и из индекса ранжирования (чем ниже этот индекс – тем более похожий по смыслу документ вы получите). Сама выдача идёт по принципу: чем ниже индекс, тем выше позиция на выдаче.
Теперь вернёмся к коду.
Импорты:
from langchain_huggingface import HuggingFaceEmbeddings
import torch
from loguru import logger
from langchain_chroma import Chroma
Переменные:
CHROMA_PATH = "./shop_chroma_db"
COLLECTION_NAME = "shop_data"
Теперь опишем функцию для подключения к существующей базе данных:
def connect_to_chroma():
"""Подключение к существующей базе Chroma."""
try:
logger.info("Загрузка модели эмбеддингов...")
embeddings = HuggingFaceEmbeddings(
model_name="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2",
model_kwargs={"device": "cuda" if torch.cuda.is_available() else "cpu"},
encode_kwargs={"normalize_embeddings": True},
)
chroma_db = Chroma(
persist_directory=CHROMA_PATH,
embedding_function=embeddings,
collection_name=COLLECTION_NAME,
)
logger.success("Успешное подключение к базе Chroma")
return chroma_db
except Exception as e:
logger.error(f"Ошибка подключения к Chroma: {e}")
raise
Данная функция вернёт готовый к работе объект базы данных, в рамках которой и будет осуществляться векторный поиск.
Теперь опишем функцию, которая позволит вести поиск как по документу (страницам документации), так и по метаданным:
def search_products(query: str, metadata_filter: dict = None, k: int = 4):
"""
Поиск страниц по запросу и метаданным.
Args:
query (str): Текстовый запрос для поиска
metadata_filter (dict): Опциональный фильтр по метаданным
k (int): Количество результатов для возврата
Returns:
list: Список найденных документов с их метаданными
"""
try:
chroma_db = connect_to_chroma()
results = chroma_db.similarity_search_with_score(
query, k=k, filter=metadata_filter
)
logger.info(f"Найдено {len(results)} результатов для запроса: {query}")
formatted_results = []
for doc, score in results:
formatted_results.append(
{
"text": doc.page_content,
"metadata": doc.metadata,
"similarity_score": score,
}
)
return formatted_results
except Exception as e:
logger.error(f"Ошибка при поиске: {e}")
raise
И теперь вызовем её:
for i in search_products(query="как развернуть приложение в Amvera, используя git push?"):
print(i)
Параметр metadata_filter позволяет нам указать условия фильтрации по метаданным. Тут больше подойдет пример поиска по товарам интернет-магазина, чем наша документация. Например, если мы хотим найти только ноутбуки с ценой менее 60000 рублей, мы можем использовать фильтр такого вида:
filter_condition = {
"category": "laptops",
"price": {"$lt": 60000}
}
Тут хочу отметить, что этот пример учебный. В боевой системе обычно создаётся класс для управления сессией с базой данных, чтоб можно было подключиться один раз и удерживать соединение. В текущей реализации каждый вызов функции будет заново запускать соединение и загрузку модели эмбеддингов, что довольно ресурсоёмко. В следующей статье, если я увижу, что вам интересна данная тема, я покажу, как реализовать такой класс и как на основе векторной базы данных можно создать полноценное веб-приложение.
Кстати, исходный код сегодняшнего проекта, как и уже написанный класс для управления соединением с векторной базой данных, вы найдете в моем телеграмм канале «Лёгкий путь в Python». Там полный исходный код проекта лежит уже порядка недели.
Вызываем поиск и посмотрим на результаты.
Неплохо, правда? Несмотря на то, что в запросе мы явно не указывали конкретную модель пылесоса или его характеристики, векторный поиск сумел понять семантику запроса и вернуть наиболее подходящие результаты из нашей базы. Это демонстрирует мощь векторных баз данных в сочетании с современными языковыми моделями.
Приступаем к практике
Теперь, когда вы уже поняли общие принципы работы с векторными базами данных, мы можем приступить к созданию более сложной логики.
Речь пойдёт о сервисе Amvera Cloud, который я уже не раз упоминал в своих предыдущих статьях на Хабре. Вкратце, это платформа для простого деплоя (удалённого запуска) проектов, практически, на любом языке программирования.
Одно из приятных преимуществ Amvera Cloud — возможность быстро развернуть проект на самых разных технологиях, используя git push (или перетянув файлы в интерфейсе), а также получить к нему бесплатное доменное имя. Дополнительно, сервис предоставляет бесплатное встроенное проксирование к API OpenAI, Antropic, Cloude и Grok, что удобно для взаимодействия с LLM. Благодаря таким техническим возможностям, у сервиса весьма обширная и подробная документация — на все случаи жизни: от базовых руководств, вроде миграции с Heroku, до более специфических тем — например, запуска проектов на FastAPI или Django, или решения вопросов, связанных с биллингом.
Именно эта документация (а это порядка 70 различных документов) отлично подойдёт для практической демонстрации: мы сможем взять массив текстов, преобразовать его в векторную базу данных и показать, как эффективно интегрировать такую базу с нейросетевыми моделями для получения осмысленных и полезных ответов.
Вводные данные
В моих руках уже было порядка 70-ти документов в Markdown от Amvera в таком формате:
# Поддержка проб Kubernetes
## Как настраивать?
В форму нужно заполнять настройки в формате yaml, нативно формату, который используется
самим k8s(см. [здесь](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/)).
Конфигурационный файл, подставляется в ваш Deployment, который загружается с ним в кластер.
**Это означает, что если вы загрузили неработающую настройку, или в неправильном формате, ваш проект упадет на этапе сборки.** ...
Эти документы мне были предоставлены в виде проекта, содержащего как файлы md, так и прочие технические файлы. Но, скорее всего, в вашем случае такого подарка не будет.
Поэтому важно помнить, что для сбора информации под базу данных можно использовать любые удобные вам инструменты: парсинг сайтов, загрузку данных из собственных SQL-баз, чтение документов в форматах Excel, Word, PDF и так далее. Главное, чтобы в итоге информация была преобразована в формат, который поддерживается векторными базами данных и имеет чёткую структуру.
Первое, что я реализовал в формате задачи с подготовкой – это решил трансформировать все эти файлы с вложенной структурой в JSON формат такого вида:
{
"text": "бэкапы бэкапы data eval rst admonition важно и так далее по тексту",
"metadata": {
"section_count": 2,
"section_1": "Бэкапы",
"section_2": "Бэкапы /data"
}
}
То есть это полная текстовая информация в ключе text без знаков препинания, спец-символов и капса, и помещённая в метаданные техническая информация по типу количества секций, названий и прочее.
Тут важно понимать, что метаданные – это наши помощники, но вам ничего бы не помешало зарядить только тексты. Однако с метаданными мы получаем дополнительные возможности для фильтрации и анализа результатов поиска.
Опишем логику для создания папки с JSON-файлами:
Импорты
import json
import os
import re
import string
import sys
from typing import Any, Dict, List
from config import settings
from loguru import logger
Тут я использовал встроенные в Python библиотеки, за исключением loguru – для удобного логирования результатов. Само извлечение будет ориентировано на регулярные выражения.
Выведем константы:
HEADER_PATTERN = re.compile(r"^(#+)\s(.+)")
PUNCTUATION_PATTERN = re.compile(f"[{re.escape(string.punctuation)}]")
WHITESPACE_PATTERN = re.compile(r"\s+")
Опишем логику для нормализации текстов:
def normalize_text(text: str) -> str:
"""Нормализация текста: удаление знаков препинания и специальных символов."""
if not isinstance(text, str):
raise ValueError("Входной текст должен быть строкой")
# Удаление знаков препинания
text = PUNCTUATION_PATTERN.sub(" ", text)
# Удаление переносов строк и лишних пробелов
text = WHITESPACE_PATTERN.sub(" ", text)
# Приведение к нижнему регистру
return text.lower().strip()
Напишем логику для парсинга одного документа формата md:
def parse_markdown(md_path: str) -> Dict[str, Any]:
"""Парсинг markdown файла и создание структурированных данных."""
if not os.path.exists(md_path):
raise FileNotFoundError(f"Файл {md_path} не найден")
try:
with open(md_path, "r", encoding="utf-8") as file:
content = file.read()
except Exception as e:
logger.error(f"Ошибка при чтении файла {md_path}: {e}")
raise
sections: List[str] = []
section_titles: List[str] = []
current_section: str | None = None
current_content: List[str] = []
for line in content.splitlines():
section_match = HEADER_PATTERN.match(line)
if section_match:
if current_section:
sections.append("\n".join(current_content).strip())
section_titles.append(current_section)
current_content = []
current_section = section_match.group(2)
current_content.append(current_section)
else:
current_content.append(line)
if current_section:
sections.append("\n".join(current_content).strip())
section_titles.append(current_section)
# Нормализация текста для векторной базы данных
normalized_sections = [normalize_text(section) for section in sections]
full_text = " ".join(normalized_sections)
# Создаем структуру метаданных
metadata = {
"file_name": os.path.basename(md_path),
"section_count": len(section_titles),
}
# Добавляем заголовки как отдельные поля
for i, title in enumerate(section_titles):
metadata[f"section_{i+1}"] = title
return {"text": full_text, "metadata": metadata}
И опишем функцию для парсинга всех документов:
def process_all_markdown(input_folder: str, output_folder: str) -> None:
"""Обработка всех markdown файлов в директории."""
if not os.path.exists(input_folder):
raise FileNotFoundError(f"Входная директория {input_folder} не найдена")
try:
os.makedirs(output_folder, exist_ok=True)
except Exception as e:
logger.error(f"Ошибка при создании выходной директории: {e}")
raise
for root, _, files in os.walk(input_folder):
for file_name in files:
if file_name.endswith(".md"):
try:
md_path = os.path.join(root, file_name)
output_path = os.path.join(
output_folder, file_name.replace(".md", ".json")
)
parsed_data = parse_markdown(md_path)
with open(output_path, "w", encoding="utf-8") as file:
json.dump(parsed_data, file, ensure_ascii=False, indent=4)
logger.info(f"Результат сохранен в {output_path}")
except Exception as e:
logger.error(f"Ошибка при обработке файла {file_name}: {e}")
На вход функция принимает папку, в которой находятся все документы, и папку, в которую запишутся полученные JSON файлы.
Логика обнаружения md файлов работает таким образом, чтобы искать по всем вложенным папкам директории с документами. Это особенно полезно, если ваша документация имеет сложную структуру файлов и директорий.
Теперь вызываем:
if __name__ == "__main__":
try:
process_all_markdown(
input_folder="путь к папке с документами",
output_folder="путь к папке для сохранения JSON",
)
except Exception as e:
logger.error(f"Критическая ошибка: {e}")
sys.exit(1)
Запускаем.
Файлы готовы! Теперь нам остается прочитать все файлы и на их основе создать векторную базу данных.
Обратите внимание, что наш парсер выделяет из Markdown не только текст, но и структуру документа. В метаданных мы сохраняем название файла и заголовки всех разделов. Это позволяет нам потом не только искать по содержимому, но и точно указывать, из какого раздела документации был взят тот или иной фрагмент, что очень полезно для создания осмысленных ответов ассистента.
Создаем базу данных
Процесс создания базы данных под Amvera не сильно отличается от описанного ранее подхода, с той разницей, что данные мы будем брать из существующих JSON-файлов.
Перед продолжением для более структурированного кода давайте создадим файл .env в корне проекта и поместим в него следующие переменные:
DEEPSEEK_API_KEY=sk-1234
OPENAI_API_KEY=sk-proj-1234
Здесь должны находиться оба ключа API. Если ключей нет, можно файл не создавать.
Далее создаем файл config.py и заполним его следующим образом:
import os
from pydantic import SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict
class Config(BaseSettings):
DEEPSEEK_API_KEY: SecretStr
BASE_DIR: str = os.path.abspath(os.path.join(os.path.dirname(__file__)))
DOCS_AMVERA_PATH: str = os.path.join(BASE_DIR, "amvera_data", "docs_amvera")
PARSED_JSON_PATH: str = os.path.join(BASE_DIR, "amvera_data", "parsed_json")
AMVERA_CHROMA_PATH: str = os.path.join(BASE_DIR, "amvera_data", "chroma_db")
AMVERA_COLLECTION_NAME: str = "amvera_docs"
MAX_CHUNK_SIZE: int = 512
CHUNK_OVERLAP: int = 50
LM_MODEL_NAME: str = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
DEEPSEEK_MODEL_NAME: str = "deepseek-chat"
OPENAI_MODEL_NAME: str = "gpt-3.5-turbo"
OPENAI_API_KEY: SecretStr
model_config = SettingsConfigDict(env_file=f"{BASE_DIR}/.env")
settings = Config() # type: ignore
В этом классе мы собираем все необходимые переменные для работы проекта. Как видите, здесь указаны пути к важным папкам (у вас структура может отличаться), названия коллекций, максимальный размер чанка, имена моделей нейросетей.
Обратите особое внимание на объявление API-ключей:
OPENAI_API_KEY: SecretStr
DEEPSEEK_API_KEY: SecretStr
Важно описывать их не как обычные строки, а именно через SecretStr. Это требование библиотеки LangChain для безопасной работы с конфиденциальными данными.
Теперь мы можем импортировать переменную settings в любом месте кода и через точку обращаться к необходимым нам настройкам.
Создание базы данных
Вернемся к созданию базы данных. Начнем с импортов:
import json
import os
import sys
from typing import Any, Dict, List, Optional
import torch
from langchain_chroma import Chroma
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_text_splitters import RecursiveCharacterTextSplitter
from loguru import logger
from config import settings
Здесь среди прочего вы видите импорт RecursiveCharacterTextSplitter. Этот компонент позволит нам разделять большие документы на смысловые чанки (фрагменты текста, связанные между собой по смыслу).
Напишем функцию для загрузки всех существующих JSON-файлов в формат списка словарей:
def load_json_files(directory: str) -> List[Dict[str, Any]]:
"""Загрузка всех JSON файлов из указанной директории."""
documents = []
try:
if not os.path.exists(directory):
logger.error(f"Директория {directory} не существует")
return documents
for filename in os.listdir(directory):
if filename.endswith(".json"):
file_path = os.path.join(directory, filename)
try:
with open(file_path, "r", encoding="utf-8") as file:
data = json.load(file)
documents.append(
{"text": data["text"], "metadata": data["metadata"]}
)
logger.info(f"Загружен файл: {filename}")
except Exception as e:
logger.error(f"Ошибка при чтении файла {filename}: {e}")
logger.success(f"Загружено {len(documents)} JSON файлов")
return documents
except Exception as e:
logger.error(f"Ошибка при загрузке JSON файлов: {e}")
return documents
После выполнения этой функции мы получим все данные из JSON-файлов в виде словарей, помещенных в оперативную память. Информацию из этих словарей можно будет использовать для создания векторной базы данных.
Теперь опишем логику для разбиения больших документов на смысловые фрагменты:
def split_text_into_chunks(text: str, metadata: Dict[str, Any]) -> List[Any]:
"""Разделение текста на чанки с сохранением метаданных."""
text_splitter = RecursiveCharacterTextSplitter(
chunk_size=settings.MAX_CHUNK_SIZE,
chunk_overlap=settings.CHUNK_OVERLAP,
length_function=len,
is_separator_regex=False,
)
chunks = text_splitter.create_documents(texts=[text], metadatas=[metadata])
return chunks
В результате работы этой функции мы по-прежнему имеем список из словарей, но теперь большие тексты разделены на смысловые фрагменты. При этом каждый из фрагментов содержит необходимые метаданные. Это важно для сохранения общего контекста даже при разбиении большого текста на множество частей.
Наконец, опишем логику для создания векторной базы данных:
def generate_chroma_db() -> Optional[Chroma]:
"""Инициализация ChromaDB с данными из JSON файлов."""
try:
# Создаем директорию для хранения базы данных, если она не существует
os.makedirs(settings.AMVERA_CHROMA_PATH, exist_ok=True)
# Загружаем JSON файлы
documents = load_json_files(settings.PARSED_JSON_PATH)
if not documents:
logger.warning("Нет документов для добавления в базу данных")
return None
# Инициализируем модель эмбеддингов
embeddings = HuggingFaceEmbeddings(
model_name=settings.LM_MODEL_NAME,
model_kwargs={"device": "cuda" if torch.cuda.is_available() else "cpu"},
encode_kwargs={"normalize_embeddings": True},
)
# Подготавливаем данные для Chroma
all_chunks = []
for i, doc in enumerate(documents):
chunks = split_text_into_chunks(doc["text"], doc["metadata"])
all_chunks.extend(chunks)
logger.info(
f"Документ {i+1}/{len(documents)} разбит на {len(chunks)} чанков"
)
# Создаем векторное хранилище
texts = [chunk.page_content for chunk in all_chunks]
metadatas = [chunk.metadata for chunk in all_chunks]
ids = [f"doc_{i}" for i in range(len(all_chunks))]
chroma_db = Chroma.from_texts(
texts=texts,
embedding=embeddings,
ids=ids,
metadatas=metadatas,
persist_directory=settings.AMVERA_CHROMA_PATH,
collection_name=settings.AMVERA_COLLECTION_NAME,
collection_metadata={
"hnsw:space": "cosine",
},
)
logger.success(
f"База Chroma инициализирована, добавлено {len(all_chunks)} чанков из {len(documents)} документов"
)
return chroma_db
except Exception as e:
logger.error(f"Ошибка инициализации Chroma: {e}")
raise
Логика создания базы данных не сильно отличается от примеров, которые мы рассматривали ранее. Главное отличие — разбиение больших текстов на смысловые фрагменты (чанки).
На моем достаточно скромном компьютере процесс создания базы данных занял менее 10 минут. На устройствах с GPU этот процесс займет лишь несколько минут благодаря параллельным вычислениям.
Оптимизация производительности
Стоит отметить, что при работе с большими объемами данных можно дополнительно оптимизировать процесс:
-
Используйте батчинг при создании эмбеддингов (обработка документов группами)
-
Настраивайте параметры MAX_CHUNK_SIZE и CHUNK_OVERLAP в зависимости от структуры ваших данных
-
Выбирайте подходящую модель эмбеддингов, балансируя между качеством и скоростью
ChromaDB обладает хорошей производительностью для большинства задач RAG, но при очень больших объемах данных (миллионы документов) стоит рассмотреть другие решения, например FAISS или Pinecone.
Интеграция поисковика с нейросетями
Ранее мы рассмотрели, как описать поисковик без использования больших нейросетей. Чтобы закрепить этот материал, предлагаю вам самостоятельно создать такой поисковик на основе вашей базы данных.
Я же перейду к самой интересной части – объясню, как объединить выдачу из векторной базы данных с нейросетями, чтобы создать умного ИИ-агента. Для этого мы будем использовать данные из документации Amvera Cloud, которые у меня уже трансформированы в векторную базу данных.
Начальная настройка проекта
Начнем с создания файла с именем chat_with_ai.py.
Выполним необходимые импорты:
from typing import Any, Dict, List, Literal, Optional
import torch
from config import settings
from langchain_chroma import Chroma
from langchain_deepseek import ChatDeepSeek
from langchain_openai import ChatOpenAI
from langchain_huggingface import HuggingFaceEmbeddings
from loguru import logger
Здесь мы подключаем новые инструменты langchain_deepseek и langchain_openai, которые позволят нам легко интегрировать модели DeepSeek и ChatGPT (а также другие модели OpenAI) в наш проект.
Структура основного класса
Для более структурированного кода я решил оформить его в виде класса. Объявим наш класс и опишем логику инициализации:
class ChatWithAI:
def __init__(self, provider: Literal["deepseek", "openai"] = "deepseek"):
self.provider = provider
self.embeddings = HuggingFaceEmbeddings(
model_name=settings.LM_MODEL_NAME,
model_kwargs={"device": "cuda" if torch.cuda.is_available() else "cpu"},
encode_kwargs={"normalize_embeddings": True},
)
if provider == "deepseek":
self.llm = ChatDeepSeek(
api_key=settings.DEEPSEEK_API_KEY,
model=settings.DEEPSEEK_MODEL_NAME,
temperature=0.7,
)
elif provider == "openai":
self.llm = ChatOpenAI(
api_key=settings.OPENAI_API_KEY,
model=settings.OPENAI_MODEL_NAME,
temperature=0.7,
)
else:
raise ValueError(f"Неподдерживаемый провайдер: {provider}")
self.chroma_db = Chroma(
persist_directory=settings.AMVERA_CHROMA_PATH,
embedding_function=self.embeddings,
collection_name=settings.AMVERA_COLLECTION_NAME,
)
При создании объекта класса мы передаем параметр provider со значением «deepseek» или «openai» для указания той нейросети, с которой будем работать в проекте.
Обратите внимание на конструкцию:
ChatDeepSeek(
api_key=settings.DEEPSEEK_API_KEY,
model=settings.DEEPSEEK_MODEL_NAME,
temperature=0.7,
)
Таким простым образом мы можем объявить нейросеть, с которой будем взаимодействовать. Здесь достаточно передать API-токен и название модели (это обязательные параметры). Также можно передавать дополнительные параметры для более тонкой настройки, например, temperature для контроля креативности ответов.
Получение релевантного контекста
Опишем метод для получения ответа из базы данных:
def get_relevant_context(self, query: str, k: int = 3) -> List[Dict[str, Any]]:
"""Получение релевантного контекста из базы данных."""
try:
results = self.chroma_db.similarity_search(query, k=k)
return [
{
"text": doc.page_content,
"metadata": doc.metadata,
}
for doc in results
]
except Exception as e:
logger.error(f"Ошибка при получении контекста: {e}")
return []
На вход метод принимает запрос пользователя и количество документов, которые мы ожидаем получить (по умолчанию это 3 документа).
Для поиска я использовал метод similarity_search. Напомню, что суть этого метода в том, что поисковый запрос мы преобразуем в векторное представление и на основании этого вектора осуществляем поиск в нашей базе данных.
Форматирование контекста
Теперь опишем метод, который будет трансформировать полученный результат в удобный для нейросетей вид:
def format_context(self, context: List[Dict[str, Any]]) -> str:
"""Форматирование контекста для промпта."""
formatted_context = []
for item in context:
metadata_str = "\n".join(f"{k}: {v}" for k, v in item["metadata"].items())
formatted_context.append(
f"Текст: {item['text']}\nМетаданные:\n{metadata_str}\n"
)
return "\n---\n".join(formatted_context)
Этот метод трансформирует связку документ + метаданные из всех полученных документов в одно структурированное сообщение, которое мы затем передадим нейросети.
Генерация ответа
Теперь опишем метод, который будет связывать наш контекст с запросом к нейросети:
def generate_response(self, query: str) -> Optional[str]:
"""Генерация ответа на основе запроса и контекста."""
try:
context = self.get_relevant_context(query)
if not context:
return "Извините, не удалось найти релевантный контекст для ответа."
formatted_context = self.format_context(context)
messages = [
{
"role": "system",
"content": """Ты — внутренний менеджер компании Amvera Cloud (https://amvera.ru/). Отвечаешь по делу без лишних вступлений.
Правила:
1. Сразу переходи к сути, без фраз типа "На основе контекста"
2. Используй только факты. Если точных данных нет — отвечай общими фразами об Amvera Cloud, но не придумывай конкретику
3. Используй обычный текст без форматирования
4. Включай ссылки только если они есть в контексте
5. Говори от первого лица множественного числа: "Мы предоставляем", "У нас есть"
6. При упоминании файлов делай это естественно, например: "Я прикреплю инструкцию, где подробно описаны шаги"
7. На приветствия отвечай доброжелательно, на негатив — с легким юмором
8. Можешь при ответах использовать общую информацию из открытых источников по Amvera Cloud, но опирайся на контекст
9. Если пользователь спрашивает о ценах, планах или технических характеристиках — давай конкретные ответы из контекста
10. При технических вопросах предлагай практические решения
Персонализируй ответы, упоминая имя клиента если оно есть в контексте. Будь краток, информативен и полезен.""",
},
{
"role": "user",
"content": f"Вопрос: {query}\nКонтекст: {formatted_context}",
},
]
response = self.llm.invoke(messages)
if hasattr(response, "content"):
return str(response.content)
return str(response).strip()
except Exception as e:
logger.error(f"Ошибка при генерации ответа: {e}")
return "Произошла ошибка при генерации ответа."
Обратите внимание, что здесь используется текстовый промпт, который выступает в роли обертки над нашим контекстом. Сам промпт (запрос) может быть любым, и я привел лишь один из возможных примеров.
С содержимым промпта стоит экспериментировать в зависимости от конкретных требований вашего проекта. Инструкции могут быть более или менее директивными, могут ориентировать модель на разные стили ответов или разный формат подачи информации.
На вход метод принимает поисковый запрос пользователя. Этот запрос сначала обрабатывается векторной базой данных, и на его основе мы получаем структурированный текст релевантных документов. Затем этот текст объединяется с подготовленным нами промптом, и при помощи вызова self.llm.invoke(messages) мы получаем ответ от нейросети.
Далее мы трансформируем ответ и возвращаем его пользователю.
Запуск и тестирование
Теперь остается корректно инициализировать класс и вызвать его методы:
if __name__ == "__main__":
chat = ChatWithAI(provider="deepseek")
print("\n=== Чат с ИИ ===\n")
while True:
query = input("Вы: ")
if query.lower() == "выход":
print("\nДо свидания!")
break
print("\nИИ печатает...", end="\r")
response = chat.generate_response(query)
print(" " * 20, end="\r") # Очищаем "ИИ печатает..."
print(f"ИИ: {response}\n")
Обратите внимание, что здесь запущен цикл, который прервется только если пользователь напишет «выход». Это демонстрирует, как можно удерживать подключение с векторной базой данных Chroma без необходимости повторно подключаться к ней при каждом запросе.
Мы один раз подключаемся к базе, и отключимся от неё только когда завершится наш бесконечный цикл. Такой подход экономит время на инициализацию соединения при каждом запросе пользователя.
Заключение
На текущем этапе у нас получился лишь прототип поисковика по документации Amvera Cloud — пока это сложно назвать полноценным сервисом с ИИ помощником.
Если этот материал найдет у вас отклик в виде просмотров, лайков и комментариев, то уже в следующей статье я подробно расскажу, какие блоки текущего кода можно улучшить. На основе доработанного варианта мы соберем готовый веб-сервис, аналогичный сайту chat.openai.com, где реализуем полноценный и удобный чат с нашим ИИ-ассистентом.
Надеюсь, мне удалось донести до вас, как работают векторные базы данных, как собирать и структурировать под них информацию, а также как организовать генерацию и поиск по таким базам.
Из-за ограниченных ресурсов мне не удалось охватить тему глубоко и всесторонне. Поэтому настоятельно рекомендую изучить векторное представление данных более детально. Это важно хотя бы потому, что такие гиганты, как ChatGPT, Claude, DeepSeek и другие современные нейросети работают именно с векторным представлением информации.
Кроме того, советую обратить внимание на такой мощный инструмент, как LangChain. То, что мы разобрали в этой статье, — лишь малая часть его возможностей.
Напоминаю, что исходный код проекта, включая асинхронный класс для работы с векторной базой ChromaDB, а также прочий эксклюзивный контент, который я не публикую на Хабре, вы можете найти в моем бесплатном Telegram-канале «Легкий путь в Python».
На этом всё. До встречи в следующем материале!
Источник: https://habr.com/ru/companies/amvera/articles/897830/