Якщо ти будуєш RAG (Retrieval-Augmented Generation) систему і хочеш, щоб вона розуміла PDF-документи без втрати контексту — цей туторіал для тебе. Класичний підхід із розбиттям тексту на чанки часто ламає логіку документа, але Gemini 2.0 Flash з його вікном контексту на 1 мільйон токенів кардинально змінює підхід. На реалізацію базової системи піде 2–3 години, і ти отримаєш робочий пайплайн, який можна одразу інтегрувати у продукт.
🛠️ Що знадобиться
- Google AI Studio + Gemini API — основна модель для обробки PDF та генерації відповідей; є безкоштовний tier до 15 запитів/хвилину
- Python 3.11+ — мова для написання пайплайну; потрібні бібліотеки google-generativeai, pypdf2, chromadb
- ChromaDB — локальна векторна база даних для зберігання ембедингів; повністю безкоштовна і не потребує хмарного підключення
- Google Colab або VS Code — середовище для запуску коду; Colab зручніший для швидкого старту без налаштувань
- PDF-документи для тесту — підійдуть будь-які: технічна документація, звіти, контракти
📋 Покрокова інструкція
Крок 1: Отримання API ключа та налаштування середовища
Відкрий aistudio.google.com, увійди через Google акаунт і натисни кнопку “Get API Key” у лівому меню. У вікні що відкриється натисни “Create API key in new project” — ключ згенерується за 10 секунд. Скопіюй його та збережи в надійному місці. Далі відкрий термінал і виконай команду: pip install google-generativeai chromadb pypdf2 python-dotenv. Створи файл .env у корені проекту і додай рядок GEMINI_API_KEY=твій_ключ_тут — це захистить ключ від випадкового потрапляння у git репозиторій.
Крок 2: Завантаження та парсинг PDF через Gemini File API
Gemini підтримує нативне завантаження PDF через File API — це набагато точніше, ніж витягувати текст через PyPDF2, бо модель бачить документ як є, включно з таблицями та форматуванням. Створи файл pdf_loader.py і встав наступний код:
import google.generativeai as genai
import os
from dotenv import load_dotenv
load_dotenv()
genai.configure(api_key=os.getenv("GEMINI_API_KEY"))
def upload_pdf_to_gemini(pdf_path: str):
print(f"Завантажую {pdf_path}...")
uploaded_file = genai.upload_file(
path=pdf_path,
mime_type="application/pdf"
)
print(f"Файл завантажено: {uploaded_file.uri}")
return uploaded_file
def extract_structured_content(uploaded_file):
model = genai.GenerativeModel("gemini-2.0-flash")
response = model.generate_content([
uploaded_file,
"""Розбий цей документ на логічні секції.
Для кожної секції поверни JSON:
{"title": "назва секції", "content": "текст", "page": номер_сторінки}
Поверни масив таких об'єктів."""
])
return response.text
Запусти скрипт командою python pdf_loader.py і передай шлях до свого PDF. Якщо файл більше 20MB — Gemini File API все одно впорається, але завантаження може зайняти до хвилини.
Крок 3: Створення векторної бази з ChromaDB
Тепер треба зберегти оброблені секції як вектори для швидкого пошуку. Створи файл vector_store.py. Відкрий його в редакторі та додай код нижче. Зверни увагу: для ембедингів ми використовуємо модель models/text-embedding-004 від Google — вона безкоштовна і чудово працює з українськомовними текстами.
import chromadb
import json
import google.generativeai as genai
def create_vector_store(sections_json: str, collection_name: str = "pdf_docs"):
client = chromadb.PersistentClient(path="./chroma_db")
try:
client.delete_collection(collection_name)
except:
pass
collection = client.create_collection(name=collection_name)
sections = json.loads(sections_json)
for i, section in enumerate(sections):
embedding_result = genai.embed_content(
model="models/text-embedding-004",
content=section["content"],
task_type="retrieval_document"
)
collection.add(
ids=[f"section_{i}"],
embeddings=[embedding_result["embedding"]],
documents=[section["content"]],
metadatas=[{"title": section["title"], "page": section.get("page", 0)}]
)
print(f"Додано секцію: {section['title']}")
print(f"Збережено {len(sections)} секцій у ChromaDB")
return collection
Після запуску в корені проекту з’явиться папка chroma_db — це і є твоя локальна векторна база.
Крок 4: Реалізація RAG пайплайну з контекстним пошуком
Це серцевина системи — функція, яка приймає питання користувача, знаходить релевантні секції у векторній базі і передає їх Gemini для генерації відповіді. Створи файл rag_pipeline.py і реалізуй пошук та генерацію:
import chromadb
import google.generativeai as genai
def search_relevant_sections(query: str, collection, top_k: int = 3):
query_embedding = genai.embed_content(
model="models/text-embedding-004",
content=query,
task_type="retrieval_query"
)
results = collection.query(
query_embeddings=[query_embedding["embedding"]],
n_results=top_k,
include=["documents", "metadatas", "distances"]
)
return results
def generate_answer(query: str, search_results: dict) -> str:
context_parts = []
for i, (doc, meta) in enumerate(zip(
search_results["documents"][0],
search_results["metadatas"][0]
)):
context_parts.append(
f"[Секція: {meta['title']}, Сторінка: {meta['page']}]\n{doc}"
)
context = "\n\n---\n\n".join(context_parts)
model = genai.GenerativeModel("gemini-2.0-flash")
prompt = f"""Ти — асистент для аналізу документів.
Відповідай ТІЛЬКИ на основі наданого контексту.
Якщо відповіді немає в контексті — скажи про це чесно.
КОНТЕКСТ:
{context}
ПИТАННЯ: {query}
ВІДПОВІДЬ:"""
response = model.generate_content(prompt)
return response.text
def rag_query(query: str, collection) -> dict:
results = search_relevant_sections(query, collection)
answer = generate_answer(query, results)
sources = [m["title"] for m in results["metadatas"][0]]
return {"answer": answer, "sources": sources}
Крок 5: Збирання фінального пайплайну та тестування
Створи головний файл main.py, який об’єднає всі компоненти. Виконай команду python main.py --pdf ./твій_документ.pdf --query "Які основні висновки документа?". Система має завантажити PDF, розбити на секції, зберегти у ChromaDB і повернути відповідь із посиланням на джерела. Якщо все працює правильно — ти побачиш у терміналі відповідь Gemini та список секцій, з яких вона була сформована. Для повторних запитів до того самого документа ChromaDB підтягне вже готові ембединги, тому відповідь прийде за 1–2 секунди замість 10–15.
⚠️ Типові помилки та як їх уникнути
- ResourceExhausted: 429 Too Many Requests — безкоштовний tier обмежений 15 запитами/хвилину; додай
time.sleep(4)між викликами embed_content при обробці великих документів із багатьма секціями - PDF не завантажується через File API — Gemini File API не приймає захищені паролем PDF; спочатку зніми захист через
qpdf --decrypt input.pdf output.pdfу терміналі - Галюцинації у відповідях — трапляються коли prompt не містить чіткої інструкції “відповідай тільки на основі контексту”; завжди додавай цю фразу і перевіряй відповідь через поле sources
- ChromaDB повертає нерелевантні результати — якщо секції занадто великі (більше 1000 слів), схожість падає; розбивай великі секції на підсекції по 300–500 слів через додатковий Gemini запит
💡 Поради для кращого результату
По-перше, використовуй параметр task_type=”retrieval_document” при індексуванні і “retrieval_query” при пошуку — це не просто константи, вони реально змінюють вектор і підвищують точність пошуку на 15–20%. По-друге, для технічних PDF з таблицями додай до промпту інструкцію: “Таблиці конвертуй у markdown формат” — Gemini чудово розуміє структуру таблиць і ембединг такого тексту буде значно точнішим. По-третє, зберігай URI завантаженого файлу в базу даних — файли на Google серверах живуть 48 годин, і якщо RAG система отримує питання про той самий документ двічі, можна повторно використати URI замість перезавантаження. По-четверте, для виробничого середовища замість ChromaDB розглянь Qdrant — він підтримує фільтрацію за метаданими прямо у векторному запиті, що дозволяє шукати тільки в межах конкретного документа або сторінки.
❓ Часті запитання (FAQ)
1. Чи підтримує Gemini кирилицю та українські PDF?
Так, Gemini 2.0 Flash чудово працює з кириличними текстами, включно з українською. Модель text-embedding-004 також підтримує мультилінгвальні ембединги, тому можна змішувати документи різними мовами в одній ChromaDB колекції.
2. Який максимальний розмір PDF можна завантажити через File API?
Максимальний розмір файлу через Gemini File API становить 2GB, але для RAG оптимально працюють документи до 100MB. Для більших файлів краще розбивати їх на частини по главах перед завантаженням.
3. Скільки коштує використання у продакшені?
Gemini 2.0 Flash у 2026 році коштує приблизно $0.075 за мільйон вхідних токенів. Один середній PDF (50 сторінок) займає близько 50 000 токенів, тобто обробка 1000 документів обійдеться у $3–5. Ембединги через text-embedding-004 ще дешевші — $0.00004 за 1000 символів.
4. Як підвищити точність відповідей для складних аналітичних документів?
Використовуй двоетапний retrieval: спочатку знайди топ-10 секцій через векторний пошук, потім передай їх Gemini з питанням “які з цих секцій найрелевантніші?” і використовуй тільки топ-3. Цей підхід називається re-ranking і підвищує точність на 25–30%.
5. Чи можна обробляти кілька PDF одночасно в одній RAG системі?
Так, і це одна з переваг ChromaDB — додавай у metadata поле "document_id" для кожного PDF. Тоді при пошуку можна фільтрувати результати за конкретним документом через параметр where={"document_id": "назва_файлу"} у методі collection.query.
🏁 Підсумок
Ти побудував повноцінний RAG пайплайн, який завантажує PDF через Gemini File API, структурує контент, зберігає ембединги у ChromaDB і генерує точні відповіді з посиланнями на джерела. Система масштабується на сотні документів без переписування архітектури.
Прямо зараз відкрий Google AI Studio, отримай безкоштовний API ключ і запусти перший тест на будь-якому PDF зі свого комп’ютера — вже за 20 хвилин матимеш працюючий прототип. Якщо хочеш іти далі — наступний крок це додати веб-інтерфейс через Gradio або Streamlit, що займе ще максимум годину.
РОЗСИЛКА
📬 Щотижневий AI-дайджест
Найкращі статті про ШІ та автоматизацію — без спаму, лише суть
Без спаму · Відписатись будь-коли