Главная / Статьи

Локальная система обработки текста с использованием Qdrant, fastembed и Gemini на Python

Небольшая система RAG на Python: разбивка локальных документов на части, встраивание их офлайн с помощью fastembed, хранение векторов в Qdrant и ответы на вопросы с использованием Gemini через командную строку.

Издатель: REACTAPP.TOP6 мин чтения1485 слов

Источники: How to Build a Simple RAG Pipeline using Qdrant

На первый взгляд, настройка собственной системы RAG (retrieval-augmented generation) кажется более сложной, чем она есть на самом деле. Часто считается, что для того, чтобы языковая модель могла читать локальные файлы, необходима сложная корпоративная инфраструктура. На деле этого не требуется. Полностью рабочий инкрементальный поток обработки может работать на одном компьютере с использованием Qdrant и Gemini, без необходимости в тяжелых фреймворках и управления сервером. Ниже описано, как это работает, что делает код и как его запустить.

Проблема, которую решает RAG

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

Обычный поиск по ключевым словам может найти такие фрагменты, но он быстро теряет эффективность, поэтому обычно используется векторный поиск.

Векторы и векторный поиск

Вектор — это список чисел, представляющий собой смысл фрагмента текста. Если преобразовать фразы «Как у вас дела?» и «Сколько вам лет?» в векторы, можно определить их степень сходства. Векторный поиск применяет эту идею для поиска ответов даже при различии формулировок. Вопрос и каждый фрагмент документа помещаются в один и тот же числовой пространство, и побеждает тот вариант, который наиболее близок по смыслу. Это важно, поскольку люди редко формулируют вопросы так же, как это сделано в документе. Даже тот, кто спрашивает «Как мне вернуть свои деньги?», всё равно нуждается в разделе под названием «Политика возврата».

Конвейер RAG — это механизм, соединяющий всё это воедино. Обычно он включает шесть шагов:

  1. Получение данных: файл попадает в папку documents/ в данном коде.
  2. Разбиение на фрагменты: скрипт разделяет файл на меньшие, перекрывающиеся части. Поиск 50-страничного документа как единого целого неэффективен, поэтому требуется его разделение.
  3. Встраивание: небольшая локальная модель преобразует каждый фрагмент в вектор, в результате чего фрагменты на схожие темы оказываются рядом друг с другом.
  4. Хранение: векторы сохраняются в Qdrant — базе данных векторов, предназначенной для быстрого поиска наиболее близких к новому вектору значений среди миллионов. Она работает быстро, является с открытым исходным кодом и запускается локально без необходимости настройки сервера или создания учетной записи.
  5. Поиск: вопрос также преобразуется в вектор, и Qdrant возвращает фрагменты, наиболее близкие к нему, то есть те, которые с наибольшей вероятностью содержат ответ.
  • Генерация: полученные фрагменты помещаются в промпт и отправляются в Gemini, который формирует ответ, основанный на реальных документах.
  • Шаги с 1 по 4 выполняются автоматически с помощью флага -i или монитора -w, поэтому документы всегда доступны для поиска. Шаги 5 и 6 выполняются по требованию при использовании параметра -q.

    Реализация на Python

    Код остается простым и не использует крупные фреймворки, поэтому легко понять, куда уходят данные.

    Чтение файлов

    Сначала находятся файлы, и из них извлекается необработанный текст, независимо от того, являются ли это записи в формате Markdown или неупорядоченные документы Word:

    def read_document(path) -> str:
        # dispatches on extension: .txt/.md read directly,
        # .pdf via pypdf, .docx via docx2txt -> returns plain textdef file_status(path, state) -> str:
        # "not_indexed" if never seen, "modified" if file_hash(path)
        # differs from the hash stored in state, else "indexed"
    

    Разбиение на части

    Далее текст разделяется с помощью простого скользящего окна, так что предложение, проходящее через границу разделения, сохраняет свой контекст:

    def chunk_text(text, chunk_size=500, overlap=50) -> list:
        words = text.split()
        step = chunk_size - overlap
        return [" ".join(words[i:i+chunk_size])
                for i in range(0, len(words), step)]
    

    Эмбеддинги и стабильные идентификаторы

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

    def chunk_ids_for(chunks) -> dict:
        # id = uuid5(namespace, chunk_text) for each chunk
        # -> same text always gets the same id, across re-indexes
        ...
    

    Сам процесс встраивания происходит внутри вызова Qdrant:

    # inside index_file():
    client.add(collection_name=index_name, documents=new_chunks, ids=new_ids)
    # Qdrant's fastembed integration embeds `documents` automatically
    

    Синхронизация файлов с базой данных

    Здесь происходит согласование локальных файлов и базы данных. Исправление опечатки не приводит к удалению индекса и перезапуску. Код сравнивает идентификаторы, удаляет те части, которые исчезли, и добавляет новые:

    def index_file(path, state) -> bool:
        chunks = chunk_text(read_document(path))
        new_ids = chunk_ids_for(chunks)
        old_ids = state[path.name].chunk_ids  # from last time
        client.delete(collection_name, ids=old_ids - new_ids)   # removed chunks
        client.add(collection_name, ids=new_ids - old_ids, ...)  # new/changed chunks
        state[path.name] = {...updated record...}
    

    Файлы, удалённые из папки, также удаляются:

    def prune_deleted(state) -> int:
        # for each file in state no longer present in DOCUMENT_DIR:
        #     delete its Qdrant collection, drop its state entry
    

    Ответ на запрос

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

    def resolve_index_names(spec, state) -> list:
        # "all" -> every indexed collection; "a,b" -> ["a","b"], validated
    

    Затем запрос выполняется по каждому из них, и результаты объединяются:

    def cmd_query(index_spec, question, top_k, show_sources):
        for name in resolve_index_names(index_spec, state):
            hits += client.query(collection_name=name, query_text=question, limit=top_k)
        hits = sorted(hits, key=score, reverse=True)[:top_k]
    

    Генерация

    В конце концов полученные фрагменты направляются непосредственно в Gemini, где они сопоставляются с предоставленным текстом:

    def generate_answer(question, context) -> str:
        prompt = f"Answer using only this context:\n{context}\n\nQuestion: {question}"
        return genai.Client(api_key=...).models.generate_content(
            model=GEMINI_MODEL, contents=prompt
        ).text
    

    Остальное — это вспомогательный код. get_client() устанавливает соединение с Qdrant, load_state() и save_state() читают и записывают файл .rag_state.json, а sanitize_index_name() преобразует имена файлов в допустимые имена коллекций. Функции команд (cmd_list_files, cmd_index, cmd_watch) связывают всё с параметрами командной строки.

    Запуск локально

    Клонируйте репозиторий и перейдите в папку проекта:

    git clone https://github.com/Shivvam/rag-pipeline-qdrant.git
    cd rag-cli
    

    Затем создайте среду, установите необходимые компоненты и настроите файл конфигурации:

    python3 -m venv venv
    source venv/bin/activate   # on Windows: venv\Scripts\activate
    pip install -r requirements.txt
    cp .env.example .env   # then edit in your GEMINI_API_KEY
    

    Перед запуском app.py снова активируйте виртуальную среду в любом новом терминале. Для того чтобы параметр -q возвращал ответы, необходимо установить значение GEMINI_API_KEY; остальные команды будут работать без него.

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

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

    python app.py -lf                        # list files in ./documents + status
    python app.py -li                        # list existing indexes
    

    Чтобы обработать новые документы или обновить изменённые:

    python app.py -i myfile.md               # index one file (or re-index if changed)
    python app.py -i all                     # index every not_indexed/modified file
    

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

    python app.py -w                          # watch ./documents, auto-index on add/edit
    

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

    python app.py -q report "What is X?"      # query a single index
    python app.py -q report,notes "What is X?"  # query multiple indexes together
    python app.py -q all "What is X?" --sources # query everything, show retrieved chunks
    python app.py -q report "..." -k 8        # retrieve top 8 chunks instead of default 5
    

    Статус, отображаемый параметром -lf, может принимать три значения. not_indexed означает, что файл никогда не обрабатывался, indexed — что он в актуальном состоянии, а modified — что он изменился с момента последней обработки и необходимо повторить запуск с параметром -i.

    Решения по проектированию

    Несколько решений позволяют сделать процесс быстрым и простым.

    • Qdrant: каждый файл получает собственную коллекцию, названную по очищенному имени файла, с добавлением числового суффикса в случае коллизии имён. По умолчанию используется локальный режим на диске (./qdrant_storage), поэтому сервер не требуется. Для одновременного доступа укажите значение QDRANT_URL в файле .env, указывающее на реальный сервер Qdrant. В локальном режиме каталог блокируется для одного процесса, поэтому параметры -w и -q не могут выполняться одновременно.
    • Встраивание: модель BAAI/bge-small-en-v1.5 работает через fastembed. Она загружается один раз и сохраняется в кэше, поэтому нет расходов на API и нет зависимости от сети во время запроса.
    • Gemini: она записывает только окончательный ответ из полученных фрагментов, причем по умолчанию используется версия gemini-3.5-flash.
    • Состояние: файл .rag_state.json хранит хэши файлов, статус, названия индексов и количество фрагментов, что позволяет использовать опции -lf и -li мгновенно, поскольку Qdrant не требует повторного сканирования. Идентификаторы фрагментов берутся непосредственно из текста, поэтому периндексация происходит поэтапно — перевстраиваются только измененные фрагменты.
    • Типы файлов: форматы .txt и .md работают сразу. Для форматов .pdf и .docx требуется библиотека pypdf или docx2txt, обе из которых уже указаны в списке требований.