Локальний пайплайн RAG із Qdrant, fastembed та Gemini на Python
Невеликий пайплайн RAG на Python: ділимо локальні документи на частини, інкорпоруємо їх офлайн за допомогою fastembed, зберігаємо вектори в Qdrant та відповідаємо на запитання за допомогою Gemini через CLI.
На перший погляд, налаштування власної системи RAG (retrieval-augmented generation) здається складнішим, ніж є насправді. Часто стверджується, що для того, щоб модель LLM могла читати локальні файли, потрібна ціла корпоративна інфраструктура. Це не так. Повністю функціональний інкрементальний процес може працювати на одному пристрої за допомогою Qdrant та Gemini, без використання важких фреймворків та без необхідності керування сервером. Нижче описано, як це працює, що робить код та як його запустити.
Проблема, яку вирішує RAG
Моделі мови знають лише дані, на яких вони навчалися. Вони ніколи не бачили ваші нотатки, звіти чи PDF-файли, які ви зберегли сьогодні вранці. RAG усуває цю прогалину. Замість того, щоб сподіватися, що модель вгадає відповідь на основі загальних знань, система шукає у ваших документах відповідні фрагменти, передає їх моделі та просить її відповісти лише на основі цього контексту. Таким чином модель перестає вигадувати інформацію, оскільки читає ваші матеріали.
Звичайний пошук за ключовими словами може знайти такі уривки, але він швидко втрачає ефективність, тому зазвичай використовується векторний пошук.
Вектори та векторний пошук
Вектор — це список чисел, який представляє сенс фрагмента тексту. Якщо перетворити фрази „Як справи?“ та „Скільки вам років?“ на вектори, можна обчислити їхню схожість. Векторний пошук застосовує цю ідею для пошуку відповідей навіть тоді, коли формулювання відрізняються. Запит та кожен фрагмент документа поміщаються у один і той самий числовий простір, і перемагає той, хто має найбільш схожий сенс. Це важливо, оскільки люди рідко формулюють запити так само, як це зроблено в документі. Людина, яка запитує „Як мені повернути гроші?“, все одно потребує розділу під назвою „Політика повернення грошей“.
Конвеєр RAG — це механізм, який об’єднує все це. Він зазвичай складається з шести кроків:
- Завантаження: файл потрапляє у папку, у цьому коді —
documents/. - Розділення на частини: скрипт розділяє файл на менші, перекриваючі одна одну фрагменти. Пошук у 50-сторінковому документі як єдиного цілого не ефективний, тому необхідне розділення.
- Вбудовування: невелика локальна модель перетворює кожен фрагмент на вектор, і фрагменти на схожі теми опиняються поруч один з одним.
- Зберігання: вектори потрапляють у Qdrant — базу даних векторів, створену для швидкого отримання найближчих результатів серед мільйонів нових векторів. Вона є швидкою, має відкритий код та працює локально, без необхідності налаштовувати сервер чи створювати облікові записи.
- Отримання інформації: запит також вбудовується, і Qdrant повертає фрагменти, які знаходяться найближче до нього, тобто ті, що найімовірніше містять відповідь.
Кроки від 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)]
Ембеддинги та стабільні ID
Ембеддинг відбувається локально, без зовнішніх викликів API для кожного речення. Кожен фрагмент також отримує прогнозований ID, отриманий шляхом хешування його тексту, тому незмінний текст зберігає той самий ID у кожній роботі:
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
Синхронізація файлів із базою даних
Тут локальні файли узгоджуються з базою даних. Виправлення опечатки не видаляє індекс та не змушує перезапускати процес. Код порівнює ID, видаляє ті частини, які зникли, та додає нові:
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 не потребує повторного сканування. ID фрагментів беруться безпосередньо з тексту, тому переіндексація відбувається поступово — переембеддуються та оновлюються лише змінені фрагменти. - Типи файлів: формати
.txtта.mdпрацюють негайно. Для форматів.pdfта.docxпотрібні бібліотекиpypdfабоdocx2txt, які вже вказані у списку вимог.