Как настроить RAG с LlamaIndex

После выполнения этой инструкции вы настроите базовый RAG с LlamaIndex по официальному quickstart-сценарию: загрузите локальные документы, построите VectorStoreIndex, зададите вопрос через index.as_query_engine(), сохраните индекс и загрузите его повторно.

Ниже используется быстрый путь через пакет llama-index. Официальный репозиторий LlamaIndex выделяет два основных старта: bundled starter-пакет llama-index и более кастомный путь через llama-index-core с явными интеграциями. Для первого рабочего RAG проще начинать со starter-пакета.

• Время: точная оценка не указана в источниках; длительность зависит от того, настроены ли у вас LLM и эмбеддинги.
• Сложность: средняя.
• Стоимость: пакет доступен через PyPI, но расходы на LLM, эмбеддинги и LlamaParse в исходном наборе источников не зафиксированы; проверьте официальные страницы перед запуском.
• Что потребуется: Python >=3.10,<4.0, проектная папка с документами, доступ к совместимым интеграциям LLM и эмбеддингов, если ваш сценарий предполагает генерацию ответа.
• Актуальная версия: llama-index 0.14.23 и llama-index-core 0.14.23 по PyPI; latest release в репозитории — v0.14.23; актуальность источников — 2026-08-14.

Практический вердикт: если вам нужен первый воспроизводимый RAG по локальной папке документов, берите llama-index. Редакционное ограничение: исходный пакет источников фиксирует каркас RAG, хранение и проверку качества, но не фиксирует единую актуальную интеграцию LLM и эмбеддингов на 2026-08-14, поэтому продакшн-настройку провайдера нужно сверять с текущей документацией перед внедрением.

Что именно вы настраиваете

Официальная концептуальная схема LlamaIndex разбивает RAG на пять стадий: loading, indexing, storing, querying и evaluation. В этой инструкции каждая стадия соответствует одному конкретному действию.

Пошаговая настройка

1. Выберите стартовый путь установки.

   Если вам нужен быстрый запуск, используйте llama-index. Если нужен полностью кастомный стек с явным выбором LLM, эмбеддингов, retriever и vector store, официальный репозиторий предлагает путь через llama-index-core и отдельные интеграции. В этой инструкции дальше используется llama-index.

   Ожидаемый результат: вы понимаете, что строите базовый RAG через starter-пакет, а не через вручную собранный стек.

2. Установите пакет llama-index в Python 3.10+ окружение.

   По PyPI текущая версия пакета — 0.14.23, а требование к Python — >=3.10,<4.0.

   python -m pip install llama-index

   Ожидаемый результат: пакет установлен без ошибок в совместимое Python-окружение.

3. Подготовьте папку data с документами.

   Создайте в проекте каталог data и положите туда файлы, по которым будете искать ответ. Для локальной папки официальный встроенный loader — SimpleDirectoryReader. Если основная нагрузка — PDF и вам нужен managed-parsing, в документации также указан LlamaParse, но его цена, лимиты и региональная доступность в этом материале не подтверждены.

   Ожидаемый результат: у вас есть непустая папка data с исходными файлами.

4. Загрузите документы через SimpleDirectoryReader.

   Сделайте первый шаг пайплайна loading.

   from llama_index.core import SimpleDirectoryReader
   
   documents = SimpleDirectoryReader('data').load_data()

   Ожидаемый результат: переменная documents содержит загруженные документы из локальной папки.

5. Постройте индекс из загруженных документов.

   Это стадия indexing из официальной схемы.

   from llama_index.core import VectorStoreIndex
   
   index = VectorStoreIndex.from_documents(documents)

   Ожидаемый результат: объект index создан без ошибки и готов к запросам.

6. Создайте query engine из индекса.

   Официальный простой путь к запросам после построения индекса — index.as_query_engine().

   query_engine = index.as_query_engine()

   Ожидаемый результат: у вас есть объект query_engine для выполнения вопросов к базе знаний.

7. Задайте первый вопрос к вашему RAG.

   На минимальном уровне querying выглядит так:

   response = query_engine.query('О чем эти документы?')
   print(response)

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

8. Сохраните индекс на диск.

   Это стадия storing. Официальный поток сохранения использует index.storage_context.persist().

   index.storage_context.persist()

   Ожидаемый результат: индекс записан в хранилище, которое затем можно переиспользовать без повторной индексации исходных документов.

9. Загрузите индекс из сохранённого хранилища.

   Для повторного старта используйте официальный поток с StorageContext.from_defaults(persist_dir='./storage') и load_index_from_storage(...).

   from llama_index.core import StorageContext, load_index_from_storage
   
   storage_context = StorageContext.from_defaults(persist_dir='./storage')
   reloaded_index = load_index_from_storage(storage_context)
   reloaded_query_engine = reloaded_index.as_query_engine()
   response = reloaded_query_engine.query('О чем эти документы?')
   print(response)

   Ожидаемый результат: индекс повторно загружается из ./storage, и запрос работает без новой загрузки и построения индекса.

Как проверить, что всё работает

1. Проверьте загрузку данных. После вызова SimpleDirectoryReader('data').load_data() у вас должны появиться объекты документов, а не ошибка пустой папки или неподходящего пути.
2. Проверьте первый ответ. Выполните query_engine.query(...) по вопросу, ответ на который явно есть в ваших файлах. Если ответ нерелевантен, проблема чаще всего в данных или в качестве извлечения.
3. Проверьте перезапуск. Сохраните индекс через index.storage_context.persist(), затем загрузите его через StorageContext.from_defaults(persist_dir='./storage') и load_index_from_storage(...). Если ответ после перезапуска снова приходит, базовая persist/reload-схема настроена верно.
4. Проверьте опору на источник, а не только красивый текст. В документации LlamaIndex для этого есть встроенные evaluators, например FaithfulnessEvaluator(llm=llm) для проверки фактической опоры на контекст и RetrieverEvaluator.from_metric_names(['mrr', 'hit_rate'], retriever=retriever) для оценки качества извлечения. Конкретные импорты и привязка к вашему провайдеру в исходном наборе источников не зафиксированы, поэтому перед запуском сверяйтесь с актуальной документацией.

Частые ошибки и исправления

• ❌ Ошибка: после загрузки нет данных для индексации.

  ✅ Решение: проверьте, что папка data существует и не пустая. В этой инструкции локальная загрузка строится именно вокруг SimpleDirectoryReader('data').load_data().

• ❌ Ошибка: установка пакета завершается ошибкой совместимости Python.

  ✅ Решение: используйте Python в диапазоне >=3.10,<4.0. Это требование зафиксировано на PyPI для llama-index и llama-index-core.

• ❌ Ошибка: первый запуск работает, а после перезапуска индекс не поднимается.

  ✅ Решение: не пропускайте сохранение через index.storage_context.persist() и загружайте индекс из того же каталога ./storage через StorageContext.from_defaults(...) и load_index_from_storage(...).

• ❌ Ошибка: ответы есть, но они плохо привязаны к вашим документам.

  ✅ Решение: начните с проверки faithfulness и retrieval. Официальная документация предлагает FaithfulnessEvaluator и RetrieverEvaluator.from_metric_names(['mrr', 'hit_rate'], retriever=retriever). Для PDF также проверьте качество загрузки; при необходимости изучите вариант с LlamaParse.

• ❌ Ошибка: вы строите новую оркестрацию поверх QueryPipeline и ожидаете долгосрочную стабильность интерфейса.

  ✅ Решение: учитывайте, что в документации QueryPipeline помечен как feature-freeze/deprecation. Для новых проектов лучше отдельно перепроверить текущую рекомендацию по workflows перед разработкой поверх этой абстракции.

Безопасность и ограничения

• Конфиденциальность данных: вы загружаете реальные документы в RAG-пайплайн, поэтому перед подключением внешних LLM и парсеров проверьте внутреннюю политику обработки данных.
• Стоимость и лимиты: в исходном наборе источников не подтверждены текущие цены и лимиты LLM-провайдеров, эмбеддингов и LlamaParse. Не закладывайте бюджет без сверки официальных страниц.
• Версионность документации: часть страниц в источниках — versioned snapshots v0.10.17 и v0.10.19, а пакеты на PyPI уже 0.14.23. Каркас RAG совпадает, но перед боевым внедрением перепроверьте актуальные API.
• Ограничение этой инструкции: материал воспроизводит минимальный RAG-каркас, но не навязывает конкретного провайдера LLM/эмбеддингов, потому что исходный пакет источников не фиксирует один обязательный путь интеграции на 2026-08-14.
• Оркестрация: QueryPipeline помечен как feature-freeze/deprecation, поэтому не стройте на нём новый долгоживущий слой без дополнительной проверки актуальной документации.

Что делать дальше

• Освежите базовую терминологию в глоссарии: RAG (Retrieval-Augmented Generation).
• Если хотите заменить облачную модель локальной, подготовьте окружение по инструкции Как настроить локальную модель через Ollama.
• Если следующий шаг — автоматизация, соберите workflow вокруг индекса по руководству Как настроить агента в n8n с ИИ.
• Если сравниваете RAG-пайплайн и агентный подход, посмотрите также Как создать простого AI-агента с LangChain.

Источники

• LlamaIndex – Build Knowledge Assistants over your Enterprise Data

• GitHub – run-llama/llama_index: LlamaIndex is the leading document agent and OCR platform · GitHub
• Releases · run-llama/llama_index · GitHub
• llama-index · PyPI
• llama-index-core · PyPI
• High-Level Concepts – LlamaIndex 🦙 v0.10.17
• Loading Data – LlamaIndex 🦙 v0.10.19
• Querying – LlamaIndex 🦙 v0.10.19
• Evaluating – LlamaIndex 🦙 v0.10.19
• Query Pipeline – LlamaIndex
• Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks

Вопросы и ответы

Что выбрать для старта: llama-index или llama-index-core?

Для первого RAG быстрее выбрать llama-index. Если вам нужен полностью кастомный стек с явным выбором интеграций, официальный репозиторий допускает путь через llama-index-core.

Можно ли начать без внешней vector database?

Да, минимальный официальный quickstart строится на VectorStoreIndex.from_documents(documents) и локальном сохранении через index.storage_context.persist(). Для первого прототипа этого достаточно.

Подходит ли этот сценарий для PDF?

Для локальной папки используйте SimpleDirectoryReader. Если вам нужен официальный managed-парсинг PDF, документация указывает на LlamaParse, но в этом материале не подтверждены его цена и лимиты.

Нужно ли строить новый проект на QueryPipeline?

С осторожностью. В официальной документации QueryPipeline помечен как feature-freeze/deprecation, поэтому для новой оркестрации лучше дополнительно проверить актуальную рекомендацию по workflows.

Как понять, что ответ действительно опирается на документы?

Используйте встроенные проверки из документации: FaithfulnessEvaluator(llm=llm) для фактической опоры на контекст и RetrieverEvaluator.from_metric_names(['mrr', 'hit_rate'], retriever=retriever) для качества извлечения.