Репозиторий создан как финальный проект для курса на Stepik - LLM для Python-разработчиков: от RAG до агентов

AI Docs Assistant

AI-ассистент для автоматической генерации и семантического поиска документации API с использованием RAG (Retrieval-Augmented Generation) и CrewAI.

Описание

AI Docs Assistant — это веб-сервис на базе FastAPI, который позволяет:

• Генерировать документацию API автоматически с помощью AI-агентов (CrewAI)
• Искать существующую документацию с помощью семантического поиска (RAG)
• Валидировать сгенерированную документацию на соответствие строгому формату

Проект использует:

• Qdrant — векторная база данных для хранения эмбеддингов документации
• Ollama — локальная LLM для генерации текста и создания эмбеддингов
• CrewAI — фреймворк для создания AI-агентов с ролями и задачами
• LangChain — интеграция с векторными хранилищами и эмбеддингами

Возможности

• 🤖 Автоматическая генерация документации через двухэтапный процесс (генерация + валидация)
• 🔍 Семантический поиск по существующей документации
• ✅ Проверка дубликатов — система предупреждает, если документ уже существует
• 📝 Автоматическое именование файлов на основе содержимого запроса
• 🏥 Расширенный health-check с проверкой всех зависимостей
• 🐳 Docker-поддержка для простого развёртывания

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

ai-docs-assistant/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI приложение и эндпоинты
│   ├── agents.py            # CrewAI агенты для генерации и валидации
│   ├── rag.py               # RAG-функциональность (Qdrant, эмбеддинги)
│   ├── storage.py           # Сохранение документов в файловую систему
│   ├── health.py            # Health-check эндпоинты
│   ├── logger.py            # Настройка логирования
│   ├── schemas.py           # Pydantic схемы для API
│   └── settings.py          # Конфигурация через переменные окружения
├── docs/                    # Хранилище сгенерированной документации
├── logs/                    # Логи приложения
├── tests/                   # Тесты
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── README.md

Требования

• Python 3.12+
• Docker и Docker Compose (для контейнеризации)
• Ollama с установленной моделью для LLM и эмбеддингов

Установка

1. Клонирование репозитория

git clone https://github.com/1337Tema/ai-docs-assistant.git
cd ai-docs-assistant

2. Установка зависимостей

python -m venv .venv
.venv/Scripts/activate
pip install -r requirements.txt

3. Настройка переменных окружения

Создайте файл .env в корне проекта:

# Qdrant настройки
QDRANT_HOST=qdrant
QDRANT_PORT=6333
QDRANT_COLLECTION_NAME=api_docs

# Ollama настройки
OLLAMA_HOST=localhost
OLLAMA_PORT=11434
OLLAMA_MODEL=ollama/my-api-docs  # дообученная модель, которая использовалась на курсе

# Эмбеддинги
EMBEDDING_MODEL_NAME=nomic-embed-text  # или другая модель для эмбеддингов
VECTOR_SIZE=768  # Размерность вектора эмбеддингов

4. Запуск Ollama

Убедитесь, что Ollama запущен и у вас установлены необходимые модели:

# Установка модели для LLM
ollama pull my-api-docs

# Установка модели для эмбеддингов
ollama pull nomic-embed-text

5. Запуск через Docker Compose (рекомендуется)

docker-compose up --build

Сервис будет доступен по адресу: http://localhost:8000

6. Запуск локально

Если вы запускаете локально (без Docker), убедитесь, что Qdrant запущен:

# Запуск Qdrant через Docker
docker run -p 6333:6333 qdrant/qdrant

# В другом терминале запустите приложение
uvicorn app.main:app --reload

API Эндпоинты

GET /health

Проверка состояния сервиса и всех зависимостей.

Ответ:

{
  "status": "healthy",
  "checks": {
    "qdrant": true,
    "ollama": true,
    "docs": true,
    "rag_canary": true
  }
}

POST /search

Семантический поиск по существующей документации.

Запрос:

{
  "query": "эндпоинт для получения профиля пользователя"
}

Ответ (найдено):

{
  "found": true,
  "content": "### GET /api/v1/profile\n**Описание**: ..."
}

Ответ (не найдено):

{
  "found": false,
  "message": "Документация не найдена. Используйте /generate для создания новой."
}

POST /generate

Генерация новой документации API.

Запрос:

{
  "query": "создать эндпоинт для получения списка задач"
}

Ответ (успех):

{
  "success": true,
  "message": "Документ успешно создан и сохранён.",
  "content": "### GET /api/v1/tasks\n...",
  "file_path": "docs/get_task.md"
}

Ответ (ошибка):

{
  "success": false,
  "message": "Документ уже существует. Используйте /search."
}

Формат документации

Все документы генерируются в строгом формате:

### МЕТОД /путь
**Описание**: Описание эндпоинта
**Параметры**: Параметры запроса (если есть)
**Ответ**:
```json
{
  "example": "response"
}

Как это работает

Процесс генерации документации

1. Проверка дубликатов: Система проверяет, не существует ли уже похожая документация
2. Генерация: AI-агент (API-документатор) создаёт документацию на основе запроса
3. Валидация: Второй AI-агент (валидатор) проверяет соответствие формату
4. Сохранение: Валидный документ сохраняется в docs/ с автоматическим именованием
5. Обновление RAG: Векторная база обновляется новым документом

Семантический поиск

1. Запрос преобразуется в эмбеддинг через Ollama
2. Выполняется поиск похожих документов в Qdrant
3. Возвращается наиболее релевантный документ (если score > threshold)

Логирование

Логи сохраняются в директории logs/:

• app.log — все логи приложения
• errors.log — только ошибки

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

pytest tests/

Разработка

Добавление новых типов сущностей

Для улучшения автоматического именования файлов отредактируйте словари в app/storage.py:

ACTION_KEYWORDS = {
    'get': [...],
    'create': [...],
    # добавьте новые действия
}

ENTITY_KEYWORDS = {
    'user': [...],
    'task': [...],
    # добавьте новые сущности
}

Настройка агентов

Параметры агентов (роли, цели, backstory) можно изменить в app/agents.py.

Настройка RAG

Параметры поиска (threshold, количество результатов) настраиваются в app/rag.py.

Troubleshooting

Ollama недоступен

• Убедитесь, что Ollama запущен: ollama serve
• Проверьте, что модели установлены: ollama list
• Проверьте настройки OLLAMA_HOST и OLLAMA_PORT в .env

Qdrant недоступен

• Проверьте, что контейнер Qdrant запущен: docker ps
• Проверьте настройки QDRANT_HOST и QDRANT_PORT в .env

Документы не находятся при поиске

• Убедитесь, что в docs/ есть .md файлы
• Проверьте, что RAG инициализирован (см. логи при старте)
• Попробуйте снизить similarity_threshold в запросе