Agent/README.md

🤖 Agentic RAG — Локальный AI-ассистент с базой знаний

Полностью автономный AI-агент с RAG (Retrieval-Augmented Generation) для работы с вашими документами и кодом. Работает без интернета!

📋 Требования

• Python 3.10+
• Ollama — для запуска LLM локально
• Qdrant — векторная база данных (запускается автоматически)
• Операционная система: Linux, macOS, Windows (WSL2 рекомендуется)

🚀 Установка

1. Клонируйте репозиторий

git clone <ваш-репозиторий>
cd <папка-проекта>

2. Установите Ollama

# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows (через WSL2)
# Установите WSL2, затем следуйте инструкции для Linux

3. Загрузите модели

# LLM модель (рекомендуется 3B параметров)
ollama pull llama3.2:3b

# Модель эмбеддингов
ollama pull nomic-embed-text

4. Установите Qdrant

Приложение использует Qdrant в embedded-режиме (база хранится локально в папке qdrant_data/). Для работы нужен бинарник Qdrant.

Вариант А: Через Docker (рекомендуется)

# Скачайте бинарник Qdrant
curl -L https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-unknown-linux-musl.tar.gz \
  | tar -xz

# Или для macOS:
curl -L https://github.com/qdrant/qdrant/releases/latest/download/qdrant-x86_64-apple-darwin.tar.gz \
  | tar -xz

# Переместите в PATH
sudo mv qdrant /usr/local/bin/

Вариант Б: Только Python (альтернатива)

Если не хотите устанавливать бинарник, можно использовать Qdrant как Python-библиотеку (требуется больше ресурсов):

pip install qdrant[fast]

При этом в коде local_knowledge_base.py нужно изменить инициализацию клиента:

# Вместо:
self.client = QdrantClient(path=persist_dir, prefer_grpc=True)

# Использовать:
self.client = QdrantClient.from_mutable_local(path=persist_dir)

Вариант В: Через Docker

# Запуск Qdrant в контейнере
docker run -d --name qdrant \
  -p 6333:6333 \
  -p 6334:6334 \
  -v $(pwd)/qdrant_storage:/qdrant/storage \
  qdrant/qdrant

После запуска измените подключение в local_knowledge_base.py:

# Вместо локального подключения:
self.client = QdrantClient(path=persist_dir, prefer_grpc=True)

# Использовать HTTP подключение:
self.client = QdrantClient(host="localhost", port=6333)

5. Настройте виртуальное окружение (рекомендуется)

# Создание виртуального окружения
python -m venv venv

# Активация (Linux/macOS)
source venv/bin/activate

# Активация (Windows)
venv\Scripts\activate

6. Установите Python-зависимости

pip install -r requirements.txt

7. Запустите Ollama (если не запущен)

ollama serve

Оставьте этот терминал открытым (или запустите в фоне).

▶️ Запуск

python main.py

После запуска откройте браузер по адресу: http://localhost:7860

📖 Использование

Базовая работа

1. Введите ваш запрос в текстовое поле
2. Включите/выключите переключатель "Использовать базу знаний (RAG)"
3. Нажмите "Отправить" или Enter

Индексация файлов

1. Введите путь к папке с документами в поле "Путь к папке с файлами"
2. Нажмите кнопку "📥 Индексировать"
3. Дождитесь завершения индексации (индикатор прогресса)

Поддерживаемые типы файлов

Тип	Расширение
PDF	.pdf
Текст	.txt
Word	.docx
C++	.cpp, .hpp, .h, .cc

Рекомендации по индексации

• Для C++ проектов укажите корневую папку с исходным кодом
• Папки build, .git, vendor, node_modules автоматически пропускаются
• После индексации можно задавать вопросы о коде

Примеры запросов

"Объясни как работает класс Parser в загруженном коде"
"Найди функцию обработки JSON"
"Спланируй изучение Python на месяц"
"Посчитай: (15 * 4) + (120 / 3)"

⚙️ Конфигурация

Изменение модели LLM

В файле agent_core.py:

llm = Ollama(
    model="llama3.2:3b",  # Измените здесь
    temperature=0.1,
    num_predict=1024,
)

Изменение модели эмбеддингов

В файле agent_core.py:

embeddings = OllamaEmbeddings(
    model="nomic-embed-text",  # Измените здесь
)

Доступные модели Ollama

Список доступных моделей: https://ollama.com/library

Рекомендуемые модели для эмбеддингов:

• nomic-embed-text (768 dim) — универсальные
• mxbai-embed-large (1024 dim) — более мощные
• bge-m3 (1024 dim) — мультиязычные

🛠 Устранение проблем

Ошибка: "connection refused"

Ollama не запущен. Запустите:

ollama serve

Ошибка: "model not found"

Модель не загружена. Скачайте:

ollama pull llama3.2:3b
ollama pull nomic-embed-text

Медленная работа

• Используйте модель меньшего размера (например, llama3.2:1b)
• Уменьшите num_predict в настройках LLM
• Используйте SSD для хранения Qdrant

Не загружаются файлы

• Проверьте путь к папке
• Убедитесь, что у приложения есть права на чтение
• Проверьте, что файлы имеют поддерживаемые расширения

Ошибка: "Qdrant binary not found"

Qdrant не установлен. Следуйте инструкции выше (раздел "Установите Qdrant").

Ошибка: "Failed to connect to Qdrant"

Проблема с подключением к Qdrant. Проверьте:

• Qdrant бинарник установлен и доступен в PATH
• Права на запись в папку проекта (нужно для создания qdrant_data/)

📂 Структура проекта

.
├── main.py                      # Точка входа
├── agent_core.py                # Логика агента и инструменты
├── local_knowledge_base.py      # Работа с Qdrant
├── agentic_rag_interface.py     # Gradio-интерфейс
├── README.md                    # Этот файл
└── qdrant_data/                 # Данные Qdrant (создаётся автоматически)

📄 Лицензия

MIT License