Локальный RAG для PDF: поиск по документам и ответы через локальную LLM

RAG — это подход, при котором модель сначала находит релевантные фрагменты в вашей базе знаний, а затем формирует ответ на их основе. В этой статье соберём минимальный локальный RAG для PDF: документы останутся на компьютере, поиск выполнит FAISS, а ответ сгенерирует локальная LLM.
Результат будет практичным, но намеренно небольшим: PDF разбиваются на фрагменты, каждому фрагменту сохраняется номер страницы, для текста строятся эмбеддинги, а найденный контекст передаётся локальному серверу Ollama. Ссылки вида «страница 4» модель получит из метаданных, а приложение выведет самостоятельно.
Что построим
Пайплайн состоит из пяти этапов:
- прочитать страницы PDF через PyMuPDF;
- разбить текст на перекрывающиеся фрагменты;
- получить векторы фрагментов с помощью sentence-transformers;
- найти ближайшие фрагменты в FAISS;
- передать контекст локальной LLM и вернуть ответ со страницами.
Это не промышленная поисковая система и не гарантия фактической корректности ответа. Зато такой вариант легко запустить, проверить и расширить без отправки исходных PDF во внешний сервис.
Подготовка окружения
Нужны Python 3.10 или новее и установленный Ollama. Создайте отдельное окружение:
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install pymupdf sentence-transformers faiss-cpu requests numpy
В Windows PowerShell команда активации выглядит так:
.venv\Scripts\Activate.ps1
Загрузите локальную модель в Ollama. Название модели в примере — параметр, поэтому его можно заменить на установленную совместимую модель:
ollama pull llama3.2:3b
ollama serve
Команда ollama serve обычно запускается в отдельном терминале. Проверьте доступность локального API:
curl http://127.0.0.1:11434/api/tags
Если команда вернула JSON со списком моделей, сервер доступен. Ниже используется только адрес loopback — запросы не должны уходить в сеть через Ollama API.
Структура проекта
local-pdf-rag/
├── data/
│ └── document.pdf
└── rag_pdf.py
Положите документы только в каталог, который вы контролируете. Не добавляйте в репозиторий PDF с персональными, коммерческими или иными чувствительными данными.
Извлечение текста и страниц
PyMuPDF возвращает текст отдельно для каждой страницы. Это важно: если сначала склеить весь документ, связь найденного фрагмента со страницей будет потеряна.
Минимальный RAG-пайплайн
Сохраните следующий код в rag_pdf.py. Он индексирует один PDF, принимает вопрос из командной строки и печатает ответ с перечнем использованных страниц.
from __future__ import annotations
import argparse
import json
from pathlib import Path
from typing import Any
import faiss
import fitz
import numpy as np
import requests
from sentence_transformers import SentenceTransformer
OLLAMA_URL = "http://127.0.0.1:11434/api/generate"
OLLAMA_MODEL = "llama3.2:3b"
EMBEDDING_MODEL = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
def extract_pages(pdf_path: Path) -> list[dict[str, Any]]:
pages = []
with fitz.open(pdf_path) as document:
for page_number, page in enumerate(document, start=1):
text = page.get_text("text").strip()
if text:
pages.append({
"page": page_number,
"text": text
})
return pages
def split_text(text: str, size: int = 900, overlap: int = 150) -> list[str]:
words = text.split()
chunks = []
step = max(1, size - overlap)
for start in range(0, len(words), step):
chunk = " ".join(words[start:start + size]).strip()
if chunk:
chunks.append(chunk)
if start + size >= len(words):
break
return chunks
def build_chunks(pages: list[dict[str, Any]]) -> list[dict[str, Any]]:
chunks = []
for page in pages:
for text in split_text(page["text"]):
chunks.append({
"page": page["page"],
"text": text
})
return chunks
def build_index(
chunks: list[dict[str, Any]],
model: SentenceTransformer
) -> faiss.Index:
vectors = model.encode(
[chunk["text"] for chunk in chunks],
normalize_embeddings=True,
convert_to_numpy=True
).astype("float32")
index = faiss.IndexFlatIP(vectors.shape[1])
index.add(vectors)
return index
def search(
question: str,
chunks: list[dict[str, Any]],
index: faiss.Index,
model: SentenceTransformer,
limit: int = 4
) -> list[dict[str, Any]]:
query_vector = model.encode(
[question],
normalize_embeddings=True,
convert_to_numpy=True
).astype("float32")
scores, positions = index.search(query_vector, min(limit, len(chunks)))
results = []
for score, position in zip(scores[0], positions[0]):
if position < 0:
continue
result = dict(chunks[position])
result["score"] = float(score)
results.append(result)
return results
def make_prompt(question: str, results: list[dict[str, Any]]) -> str:
context = "\n\n".join(
f"[Фрагмент {number}, страница {item['page']}]\n{item['text']}"
for number, item in enumerate(results, start=1)
)
return f"""Ты отвечаешь на вопросы по PDF-документу.
Правила:
1. Используй только приведённый контекст.
2. Если в контексте нет ответа, честно скажи: «В найденных фрагментах ответа нет».
3. Не придумывай номера страниц.
4. Отвечай на русском языке кратко и по существу.
5. В конце добавь строку «Источники:» и перечисли страницы из контекста.
Вопрос:
{question}
Контекст:
{context}
"""
def ask_local_llm(prompt: str) -> str:
response = requests.post(
OLLAMA_URL,
json={
"model": OLLAMA_MODEL,
"prompt": prompt,
"stream": False
},
timeout=120
)
response.raise_for_status()
return response.json()["response"].strip()
def main() -> None:
parser = argparse.ArgumentParser()
parser.add_argument("pdf", type=Path)
parser.add_argument("question")
args = parser.parse_args()
if not args.pdf.is_file():
raise SystemExit(f"PDF не найден: {args.pdf}")
pages = extract_pages(args.pdf)
if not pages:
raise SystemExit(
"В PDF не найден текст. Возможно, это скан без OCR."
)
chunks = build_chunks(pages)
if not chunks:
raise SystemExit("Не удалось создать текстовые фрагменты.")
embedding_model = SentenceTransformer(EMBEDDING_MODEL)
index = build_index(chunks, embedding_model)
results = search(
args.question,
chunks,
index,
embedding_model
)
prompt = make_prompt(args.question, results)
answer = ask_local_llm(prompt)
source_pages = sorted({item["page"] for item in results})
print(answer)
print()
print("Найденные страницы:", ", ".join(map(str, source_pages)))
if __name__ == "__main__":
main()
Здесь используется косинусная близость в форме внутреннего произведения: векторы нормализуются перед добавлением в IndexFlatIP. Переменные size и overlap задают размер фрагмента и перекрытие в словах.
Запуск и проверка результата
Из корня проекта выполните:
python rag_pdf.py data/document.pdf "Какие требования к резервному копированию указаны в документе?"
Проверяйте не только связность ответа, но и три свойства:
- ответ опирается на формулировки из PDF;
- перечисленные страницы действительно содержат найденные фрагменты;
- при вопросе вне темы модель сообщает об отсутствии ответа.
Номера страниц выводятся приложением из метаданных результатов поиска. Поэтому они не зависят только от того, насколько точно модель воспроизвела номер страницы в тексте ответа.
Типовые ошибки
«PDF не содержит текста»
Сканированные документы часто состоят из изображений. page.get_text() в таком случае вернёт пустую строку. Нужен отдельный этап OCR, после которого следует повторно проверить качество распознанного текста. OCR может ошибаться в таблицах, формулах и колонтитулах.
Слабые или нерелевантные результаты
Попробуйте уменьшить размер фрагмента, изменить перекрытие или использовать эмбеддинговую модель, которая лучше работает с языком ваших документов. Слишком большие фрагменты добавляют шум, а слишком маленькие теряют контекст.
Ollama недоступна
Убедитесь, что локальный сервер запущен, модель скачана, а имя в OLLAMA_MODEL совпадает с именем из /api/tags. Тайм-аут в примере рассчитан на локальный запуск, но первая генерация может занять больше времени из-за загрузки модели в память.
FAISS не устанавливается
Пакет faiss-cpu зависит от платформы и версии Python. Создайте новое виртуальное окружение с поддерживаемой версией Python и повторите установку. Не смешивайте пакеты из системного Python и виртуального окружения.
Безопасность и приватность
Локальный запуск снижает риск передачи документов внешнему API, но сам по себе не делает систему безопасной. Контролируйте доступ к каталогу с PDF, логам и кэшу эмбеддингов. Не выводите в логи полный текст документов без необходимости.
Ограничьте HTTP-сервис Ollama адресом 127.0.0.1, если удалённый доступ не нужен. Перед обработкой документов с персональными данными также проверьте, не создаёт ли используемая инфраструктура резервные копии или телеметрию за пределами ожидаемой локальной среды.
Ограничения минимального варианта
Пример каждый раз строит индекс заново и работает с одним PDF. Для нескольких документов стоит сохранять индекс на диск вместе с JSON-метаданными, где у каждого вектора будут путь к файлу, номер страницы и идентификатор фрагмента.
FAISS ищет по векторной близости, но не понимает структуру таблиц, изображения и сложные ссылки. Для рабочих сценариев могут понадобиться OCR, извлечение таблиц, гибридный поиск по словам и векторам, reranking, фильтрация по документу и оценка качества на заранее подготовленных вопросах.
Отдельно учитывайте границы контекста LLM: если передать слишком много найденных фрагментов, ответ может стать менее точным. Увеличивать число результатов стоит только после проверки, что дополнительные фрагменты действительно помогают.
Итог
Минимальный локальный RAG для PDF можно собрать из PyMuPDF, sentence-transformers, FAISS и локальной модели Ollama. Ключевая практическая деталь — хранить номер страницы рядом с каждым фрагментом, а не пытаться восстановить его после генерации ответа.
Дальше можно добавить кэширование индекса, поддержку нескольких файлов, OCR и автоматическую проверку цитат. Общие приёмы для подобных локальных пайплайнов собраны в разделе гайдов, а термины — в глоссарии.