Лакальны 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, якія ўжо перыявленыя ў спісе выкарыстоўваных інструментаў.