Добавил инструкцию по установке

2026-04-01 08:50:27 +05:00
parent 71891765fb
commit b31e1377b3
2 changed files with 266 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1 +1,258 @@
-pu pu puuuu
+# 🤖 Agentic RAG — Локальный AI-ассистент с базой знаний
+
+Полностью автономный AI-агент с RAG (Retrieval-Augmented Generation) для работы с вашими документами и кодом. Работает без интернета!
+
+## 📋 Требования
+
+- **Python 3.10+**
+- **Ollama** — для запуска LLM локально
+- **Qdrant** — векторная база данных (запускается автоматически)
+- Операционная система: Linux, macOS, Windows (WSL2 рекомендуется)
+
+## 🚀 Установка
+
+### 1. Клонируйте репозиторий
+
+```bash
+git clone <ваш-репозиторий>
+cd <папка-проекта>
+```
+
+### 2. Установите Ollama
+
+```bash
+# macOS / Linux
+curl -fsSL https://ollama.com/install.sh | sh
+
+# Windows (через WSL2)
+# Установите WSL2, затем следуйте инструкции для Linux
+```
+
+### 3. Загрузите модели
+
+```bash
+# LLM модель (рекомендуется 3B параметров)
+ollama pull llama3.2:3b
+
+# Модель эмбеддингов
+ollama pull nomic-embed-text
+```
+
+### 4. Установите Qdrant
+
+Приложение использует Qdrant в embedded-режиме (база хранится локально в папке `qdrant_data/`). Для работы нужен бинарник Qdrant.
+
+#### Вариант А: Через Docker (рекомендуется)
+
+```bash
+# Скачайте бинарник 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-библиотеку (требуется больше ресурсов):
+
+```bash
+pip install qdrant[fast]
+```
+
+При этом в коде `local_knowledge_base.py` нужно изменить инициализацию клиента:
+
+```python
+# Вместо:
+self.client = QdrantClient(path=persist_dir, prefer_grpc=True)
+
+# Использовать:
+self.client = QdrantClient.from_mutable_local(path=persist_dir)
+```
+
+#### Вариант В: Через Docker
+
+```bash
+# Запуск Qdrant в контейнере
+docker run -d --name qdrant \
+  -p 6333:6333 \
+  -p 6334:6334 \
+  -v $(pwd)/qdrant_storage:/qdrant/storage \
+  qdrant/qdrant
+```
+
+После запуска измените подключение в `local_knowledge_base.py`:
+
+```python
+# Вместо локального подключения:
+self.client = QdrantClient(path=persist_dir, prefer_grpc=True)
+
+# Использовать HTTP подключение:
+self.client = QdrantClient(host="localhost", port=6333)
+```
+
+### 5. Настройте виртуальное окружение (рекомендуется)
+
+```bash
+# Создание виртуального окружения
+python -m venv venv
+
+# Активация (Linux/macOS)
+source venv/bin/activate
+
+# Активация (Windows)
+venv\Scripts\activate
+```
+
+### 6. Установите Python-зависимости
+
+```bash
+pip install -r requirements.txt
+```
+
+### 7. Запустите Ollama (если не запущен)
+
+```bash
+ollama serve
+```
+
+Оставьте этот терминал открытым (или запустите в фоне).
+
+## ▶️ Запуск
+
+```bash
+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`:
+
+```python
+llm = Ollama(
+    model="llama3.2:3b",  # Измените здесь
+    temperature=0.1,
+    num_predict=1024,
+)
+```
+
+### Изменение модели эмбеддингов
+
+В файле `agent_core.py`:
+
+```python
+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 не запущен. Запустите:
+```bash
+ollama serve
+```
+
+### Ошибка: "model not found"
+
+Модель не загружена. Скачайте:
+```bash
+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