DocuWeave

DocuWeave — это современное веб-приложение для работы с документами, использующее RAG (Retrieval-Augmented Generation) и интеллектуальных агентов на основе LangGraph. Позволяет загружать, анализировать и взаимодействовать с документами через естественный язык.

✨ Ключевые возможности

📄 Умная обработка документов: Поддержка PDF, DOCX, TXT с автоматическим извлечением текста и чанкированием
🤖 Интеллектуальный агент: Агент на LangGraph с инструментами для анализа, суммаризации и ответов на вопросы
🔍 Векторный поиск: Интеграция с ChromaDB для семантического поиска по документам
💬 Интерактивный чат: Чат-интерфейс с потоковыми ответами и историей диалогов
🚀 Готовое развертывание: Полная Docker Compose конфигурация для быстрого запуска
🔐 Безопасность: JWT аутентификация, ролевая модель, защита данных

🏗️ Архитектура

Высокоуровневая схема

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │    Backend      │    │   Базы данных   │
│   (React)       │◄──►│   (FastAPI)     │◄──►│   PostgreSQL    │
│   TypeScript    │    │   Python        │    │   ChromaDB      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Пользователь  │    │   AI Сервисы    │    │   Хранилище     │
│   Интерфейс     │    │   Ollama        │    │   Документов    │
└─────────────────┘    │   LangChain     │    └─────────────────┘
                       │   LangGraph     │
                       └─────────────────┘

Модули системы

RAG система: Модульная архитектура с разделением на Indexer, Retriever, Generator, Orchestrator
Агентная система: Интеллектуальный агент на LangGraph с инструментами для анализа документов
API слой: RESTful API с эндпоинтами для документов, чатов, проектов и агента
Инфраструктура: Docker, PostgreSQL, ChromaDB, Ollama

Ключевые компоненты

UnifiedOllamaClient: Единый клиент для работы с моделями Ollama
AgentOrchestrator: Координатор работы агента с интеграцией RAG
RAGOrchestrator: Управление полным RAG пайплайном
DocumentProcessor: Обработка и чанкирование документов

🚀 Быстрый старт

Предварительные требования

Docker и Docker Compose
16+ GB RAM (рекомендуется для работы моделей Ollama)
Git

Установка и запуск за 5 минут

# 1. Клонирование репозитория
git clone <repository-url>
cd DocuWeave

# 2. Настройка переменных окружения
cp .env.example .env
# Отредактируйте .env при необходимости

# 3. Запуск всех сервисов
docker-compose up -d

# 4. Проверка работоспособности
docker-compose ps

Проверка работоспособности

После запуска откройте в браузере:

📚 Backend API документация: http://localhost:8000/docs (Swagger UI)
🎨 Frontend приложение: http://localhost:5173
🔍 ChromaDB UI: http://localhost:8001
🤖 Ollama API: http://localhost:11434

Инициализация базы данных

# Миграции выполняются автоматически при первом запуске
# Для ручного запуска:
docker-compose run migrations

📚 Подробная документация

Backend документация - Подробное описание API, архитектуры и разработки бэкенда
Frontend документация - Руководство по фронтенду, компонентам и UI
Docker Compose - Конфигурация всех сервисов
Переменные окружения - Шаблон для настройки окружения

🐳 Сервисы Docker Compose

Сервис	Порт	Назначение	Особенности
backend	8000	FastAPI приложение	Автоматическая перезагрузка, health checks
frontend	5173	React приложение	Hot reload, оптимизированная сборка
db	5432	PostgreSQL	Персистентное хранилище, health checks
chromadb	8001	ChromaDB	Векторная база для эмбеддингов
ollama	11434	Ollama LLM	Локальные LLM модели
migrations	-	Alembic миграции	Автоматическое применение миграций

📡 API Эндпоинты

Агент

POST /agent/query - Обработка запроса через интеллектуального агента
POST /agent/query/rag-fallback - Обработка с fallback на RAG
POST /agent/analyze-document - Анализ документа инструментами агента
POST /agent/batch-process - Пакетная обработка запросов
GET /agent/info - Информация о конфигурации агента
GET /agent/health - Проверка здоровья агента

Документы

POST /documents/upload - Загрузка документа (PDF, DOCX, TXT)
DELETE /documents/{document_id} - Удаление документа
GET /documents - Список документов проекта
GET /documents/{document_id} - Получение метаданных документа

Чат

POST /chat/sessions - Создание сессии чата
GET /chat/sessions - Список сессий пользователя
POST /chat/{chat_id}/messages - Отправка сообщения
GET /chat/{chat_id}/messages/stream - Потоковое получение ответа
GET /chat/{chat_id}/messages - История сообщений

Проекты

GET /projects - Список проектов пользователя
POST /projects - Создание проекта
PATCH /projects/{project_id} - Обновление настроек проекта
DELETE /projects/{project_id} - Удаление проекта

Аутентификация

POST /auth/register - Регистрация пользователя
POST /auth/login - Вход и получение JWT токена
POST /auth/refresh - Обновление токена
GET /auth/me - Информация о текущем пользователе

🤖 Агентная система

Архитектура агента

Агент построен на LangGraph и состоит из следующих узлов:

graph LR
    A[Входной запрос] --> B[classify_query]
    B --> C{Тип запроса}
    C -->|Поиск| D[rag_search]
    C -->|Анализ| E[document_analysis]
    C -->|Суммаризация| F[summarize]
    D --> G[call_tools]
    E --> G
    F --> G
    G --> H[generate_response]
    H --> I[finalize]
    I --> J[Ответ пользователю]

Инструменты агента

rag_search - Поиск релевантных документов в векторной базе
document_analysis - Анализ документа (суммаризация, ключевые точки и т.д.)
summarize - Суммаризация текста
extract_entities - Извлечение сущностей из текста
answer_with_context - Ответ на вопрос на основе контекста
classify_query - Классификация запроса пользователя

Пример использования агента

# Пример запроса к агенту через API
import requests

response = requests.post(
    "http://localhost:8000/agent/query",
    json={
        "query": "Какие основные выводы из отчета по продажам?",
        "project_id": "project_123",
        "stream": False
    },
    headers={"Authorization": "Bearer <token>"}
)

print(response.json())

🔧 Конфигурация

Переменные окружения (.env)

# База данных
POSTGRES_DB=Mydatabase123
POSTGRES_HOST=db
POSTGRES_PASSWORD=Mypass123
POSTGRES_USER=Myuser123

# Ollama
OLLAMA_HOST=http://ollama:11434
OLLAMA_EMBEDDING_MODEL=nomic-embed-text
OLLAMA_LLM_MODEL=qwen2.5:7b

# ChromaDB
CHROMA_HOST=chromadb
CHROMA_PORT=8000

# Агент
AGENT_ENABLED=true
AGENT_MAX_STEPS=10

# JWT
JWT_SECRET_KEY=your-secret-key-change-in-production
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Логирование
LOG_LEVEL=INFO

Настройка моделей Ollama

По умолчанию используются:

Модель эмбеддингов: nomic-embed-text (1536 размерность)
LLM модель: qwen2.5:7b (7 миллиардов параметров)

Для изменения моделей:

Отредактируйте OLLAMA_EMBEDDING_MODEL и OLLAMA_LLM_MODEL в .env
Перезапустите сервис Ollama: docker-compose restart ollama
Убедитесь, что модель загружена: docker-compose exec ollama ollama pull <model-name>

🧪 Примеры использования

Загрузка документа

curl -X POST "http://localhost:8000/documents/upload" \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/document.pdf" \
  -F "project_id=project_123"

Взаимодействие с агентом

curl -X POST "http://localhost:8000/agent/query" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Обобщите основные идеи из загруженных документов",
    "project_id": "project_123"
  }'

Создание чат-сессии

curl -X POST "http://localhost:8000/chat/sessions" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "project_123",
    "title": "Обсуждение отчетов"
  }'

🛠️ Разработка

Локальная разработка backend

cd backend
uv sync  # Установка зависимостей
cp .env.example .env  # Настройка окружения
alembic upgrade head  # Применение миграций
uvicorn src.main:app --reload  # Запуск сервера

Локальная разработка frontend

cd frontend
npm install  # Установка зависимостей
cp .env.example .env.local  # Настройка окружения
npm run dev  # Запуск сервера разработки

Тестирование

# Backend тесты
cd backend
pytest tests/

# Frontend тесты
cd frontend
npm test

Работа с миграциями базы данных

# Создание миграции
docker-compose run --rm migrations alembic revision --autogenerate -m "описание изменений"

# Применение миграций
docker-compose up migrations

# Откат последней миграции
docker-compose run --rm migrations alembic downgrade -1

# Просмотр истории
docker-compose run --rm migrations alembic history

📊 Мониторинг и логи

Логирование

Backend: Логи в stdout с уровнем LOG_LEVEL из .env
Ollama: Логи доступны через docker-compose logs ollama
Базы данных: Логи доступны через соответствующие контейнеры

Health checks

Backend: GET /health
Agent: GET /agent/health
ChromaDB: Автоматическая проверка в docker-compose
PostgreSQL: Автоматическая проверка в docker-compose

Трассировка агента

Каждый вызов агента записывается в GraphTrace с:

Входными параметрами
Выполненными шагами
Использованными инструментами
Финальным ответом
Временными метками

🚨 Устранение неполадок

Проблемы с памятью

Если Ollama не хватает памяти:

Увеличьте лимиты памяти в docker-compose.yml (раздел deploy.resources)
Используйте меньшие модели (например, llama3.2:3b вместо qwen2.5:7b)
Уменьшите chunk_size в настройках RAG

Проблемы с загрузкой моделей

Если модели не загружаются:

Проверьте доступность Ollama: curl http://localhost:11434/api/tags
Загрузите модели вручную: docker-compose exec ollama ollama pull qwen2.5:7b
Проверьте логи: docker-compose logs ollama

Проблемы с подключением к базам данных

Проверьте, что все сервисы запущены: docker-compose ps
Проверьте логи миграций: docker-compose logs migrations
Убедитесь, что переменные окружения корректны

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

Ошибка	Причина	Решение
`Connection refused to db:5432`	PostgreSQL не запущен	`docker-compose up -d db`
`Model not found`	Модель не загружена в Ollama	`docker-compose exec ollama ollama pull <model>`
`JWT token expired`	Токен истек	Обновите токен через `/auth/refresh`
`Document processing failed`	Неподдерживаемый формат	Проверьте формат файла (PDF, DOCX, TXT)

📈 Дорожная карта

Планируемые функции

Поддержка большего количества форматов документов (PPTX, XLSX)
Мультиязычность интерфейса и обработки
Расширенная аналитика использования
Интеграция с облачными хранилищами (Google Drive, Dropbox)
API для сторонних интеграций
Расширенная система плагинов для агента
Мобильное приложение

Улучшения производительности

Кэширование эмбеддингов
Пакетная обработка документов
Оптимизация запросов к векторной базе
Поддержка GPU для инференса

🤝 Вклад в проект

Мы приветствуем вклад в развитие DocuWeave! Пожалуйста, ознакомьтесь с руководством по вкладу перед началом.

Процесс разработки

Создайте issue с описанием задачи
Создайте feature branch
Реализуйте изменения
Напишите тесты
Создайте pull request
Пройдите code review

Стиль кода

Backend: PEP 8, type hints, docstrings
Frontend: ESLint, Prettier, TypeScript strict mode
Коммиты: Conventional Commits
Тесты: Покрытие ключевой функциональности

📚 Полезные ссылки

📄 Лицензия

Проект распространяется под лицензией MIT. Подробнее см. в файле LICENSE.

Примечание: Этот README обновляется по мере развития проекта. Для получения самой актуальной информации обратитесь к документации в соответствующих директориях или создайте issue.

Name		Name	Last commit message	Last commit date
Latest commit History 115 Commits
backend		backend
frontend		frontend
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

DocuWeave

✨ Ключевые возможности

🏗️ Архитектура

Высокоуровневая схема

Модули системы

Ключевые компоненты

🚀 Быстрый старт

Предварительные требования

Установка и запуск за 5 минут

Проверка работоспособности

Инициализация базы данных

📚 Подробная документация

🐳 Сервисы Docker Compose

📡 API Эндпоинты

Агент

Документы

Чат

Проекты

Аутентификация

🤖 Агентная система

Архитектура агента

Инструменты агента

Пример использования агента

🔧 Конфигурация

Переменные окружения (.env)

Настройка моделей Ollama

🧪 Примеры использования

Загрузка документа

Взаимодействие с агентом

Создание чат-сессии

🛠️ Разработка

Локальная разработка backend

Локальная разработка frontend

Тестирование

Работа с миграциями базы данных

📊 Мониторинг и логи

Логирование

Health checks

Трассировка агента

🚨 Устранение неполадок

Проблемы с памятью

Проблемы с загрузкой моделей

Проблемы с подключением к базам данных

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

📈 Дорожная карта

Планируемые функции

Улучшения производительности

🤝 Вклад в проект

Процесс разработки

Стиль кода

📚 Полезные ссылки

📄 Лицензия

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages