README.md

---
title: AI Scraper ФИПИ
emoji: 🕷️
colorFrom: blue
colorTo: purple
sdk: docker
sdk_version: "docker"
python_version: "3.11"
app_file: app.py
pinned: false
---

# 🕷️ AI Scraper ФИПИ

Сервис для автоматического сбора заданий с сайта ФИПИ (fipi.ru) с использованием AI-анализа на основе **ruBERT**.

---

## ✨ Возможности

- 🕷️ **Автоматический парсинг** заданий с сайта ФИПИ
- 🧠 **AI-классификация** заданий через ruBERT
- 💾 **Сохранение в Supabase** с автоматическим обновлением
- 🚀 **Деплой на Hugging Face Spaces**
- 📊 **REST API** для доступа к заданиям
- 🔍 **Поиск** по заданиям
- 📈 **Статистика** и аналитика

---

## 📁 Структура

```
ai-scraper/
├── app.py                 # Основное FastAPI приложение
├── scraper.py             # Парсер сайта ФИПИ
├── rubert_client.py       # Клиент для ruBERT API
├── supabase_client.py     # Интеграция с Supabase
├── models.py              # Pydantic модели
├── requirements.txt       # Python зависимости
├── schema.sql             # SQL схема для Supabase
├── Dockerfile             # Docker конфигурация
├── hf_spaces_config.yaml  # Конфиг для Hugging Face
├── .env.example           # Шаблон переменных окружения
└── README.md              # Документация
```

---

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

### 1. Локальная разработка

```bash
cd ai-scraper

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

# Активируйте
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac

# Установите зависимости
pip install -r requirements.txt

# Скопируйте .env.example в .env (опционально)
cp .env.example .env

# Заполните .env своими ключами
# ИЛИ настройте переменные окружения в вашей системе

# Запустите сервер
uvicorn app:app --reload --host 0.0.0.0 --port 8000
```

Откройте http://localhost:8000/docs для Swagger UI.

---

## ⚙️ Переменные окружения

### Для локальной разработки

Скопируйте `.env.example` в `.env` и заполните своими значениями:

```env
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key
RUBERT_URL=https://your-rubert.hf.space
FIPI_BASE_URL=https://fipi.ru
```

### Для Hugging Face Spaces

**Не нужно загружать `.env` файл!** Настройте переменные через интерфейс:

1. Откройте ваш Space
2. Перейдите в **Settings** → **Secrets**
3. Добавьте переменные:
   - `SUPABASE_URL`
   - `SUPABASE_SERVICE_KEY`
   - `RUBERT_URL` (опционально)
   - `FIPI_BASE_URL` (опционально)

---

## 🗄️ Настройка Supabase

### 1. Создайте проект

Перейдите на [Supabase](https://supabase.com) и создайте новый проект.

### 2. Выполните SQL скрипт

1. Откройте [SQL Editor](https://supabase.com/dashboard/project/_/sql/new)
2. Скопируйте содержимое `schema.sql`
3. Нажмите **Run**

### 3. Получите ключи

1. Перейдите в **Settings** → **API**
2. Скопируйте:
   - **Project URL** → `SUPABASE_URL`
   - **service_role key** → `SUPABASE_SERVICE_KEY`

---

## 🧠 Настройка ruBERT

### Вариант 1: Использование существующего API

Если у вас уже есть развернутый ruBERT (как в основном проекте):

```env
RUBERT_URL=https://your-rubert-instance.hf.space
```

### Вариант 2: Развертывание ruBERT

Создайте новый Space на Hugging Face с моделью ruBERT:

1. [RuBERT от DeepPavlov](https://huggingface.co/deepvk/rubert-base-cased)
2. Используйте шаблон Gradio или FastAPI
3. Добавьте эндпоинты `/api/analyze` и `/api/embedding`

---

## 🌐 Деплой на Hugging Face Spaces

### Шаг 1: Создайте Space

1. Перейдите на [Hugging Face Spaces](https://huggingface.co/spaces)
2. Нажмите **Create new Space**
3. Заполните:
   - **Space name**: `fipi-ai-scraper`
   - **License**: MIT
   - **SDK**: Docker
   - **Visibility**: Public или Private

### Шаг 2: Загрузите файлы

```bash
# Инициализируйте git в папке ai-scraper
cd ai-scraper
git init
git add .
git commit -m "Initial commit"

# Добавьте remote вашего Space
git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/fipi-ai-scraper

# Push в Space
git push -u origin main
```

### Шаг 3: Настройте переменные окружения

**Важно:** Не загружайте `.env` файл в репозиторий!

В Settings вашего Space добавьте в **Secrets**:

| Variable | Value |
|----------|-------|
| `SUPABASE_URL` | https://your-project.supabase.co |
| `SUPABASE_SERVICE_KEY` | ваш service key |
| `RUBERT_URL` | https://your-rubert.hf.space |
| `FIPI_BASE_URL` | https://fipi.ru |

⚠️ **Примечание:** Переменные окружения добавляются через интерфейс Hugging Face:
**Settings** → **Repository secrets** → **New secret**

### Шаг 4: Дождитесь деплоя

Space автоматически соберет Docker образ и запустит приложение.

---

## 📡 API Endpoints

| Метод | Эндпоинт | Описание |
|-------|----------|----------|
| GET | `/` | Информация об API |
| GET | `/api/health` | Проверка статуса сервиса |
| GET | `/api/tasks` | Получить все задания |
| GET | `/api/tasks/latest` | Последние добавленные задания |
| GET | `/api/tasks/{task_id}` | Получить задание по ID |
| GET | `/api/tasks/type/{type}` | Задания по типу |
| GET | `/api/tasks/search?q=` | Поиск заданий |
| POST | `/api/scrape` | Запустить парсинг ФИПИ |
| POST | `/api/analyze` | AI анализ существующих заданий |
| GET | `/api/stats` | Статистика по заданиям |

---

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

### Python

```python
import requests

BASE_URL = "https://your-space.hf.space"

# Получить последние задания
response = requests.get(f"{BASE_URL}/api/tasks/latest?limit=10")
tasks = response.json()
print(f"Найдено заданий: {len(tasks)}")

# Запустить парсинг ФИПИ
response = requests.post(f"{BASE_URL}/api/scrape")
result = response.json()
print(result["message"])

# Поиск заданий
response = requests.get(f"{BASE_URL}/api/tasks/search?q=сочинение")
tasks = response.json()

# Получить статистику
response = requests.get(f"{BASE_URL}/api/stats")
stats = response.json()
print(f"Всего заданий: {stats['total_tasks']}")
```

### cURL

```bash
# Health check
curl https://your-space.hf.space/api/health

# Получить задания
curl https://your-space.hf.space/api/tasks/latest

# Запустить скрапинг
curl -X POST https://your-space.hf.space/api/scrape \
  -H "Content-Type: application/json" \
  -d '{"subject": "russian"}'

# Поиск
curl "https://your-space.hf.space/api/tasks/search?q=ЕГЭ"
```

---

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

### Переменные окружения

| Переменная | Описание | Пример |
|------------|----------|--------|
| `SUPABASE_URL` | URL проекта Supabase | `https://xxx.supabase.co` |
| `SUPABASE_SERVICE_KEY` | Service role ключ Supabase | `eyJhbG...` |
| `RUBERT_URL` | URL ruBERT API | `https://rubert.hf.space` |
| `FIPI_BASE_URL` | Базовый URL ФИПИ | `https://fipi.ru` |
| `PORT` | Порт приложения | `7860` |
| `HOST` | Хост приложения | `0.0.0.0` |

---

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

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   FIPIScraper   │────▶│  RuBERTClient    │────▶│  SupabaseClient │
│   (BeautifulSoup)│    │  (HTTP API)      │     │  (Supabase JS)  │
└─────────────────┘     └──────────────────┘     └─────────────────┘
         │                       │                        │
         ▼                       ▼                        ▼
   fipi.ru                 ruBERT HF               Supabase DB
   (парсинг)              (AI анализ)              (хранение)
```

### Поток данных

1. **Скрапинг**: `FIPIScraper` парсит задания с fipi.ru
2. **Анализ**: `RuBERTClient` анализирует текст задания
3. **Сохранение**: `SupabaseClient` сохраняет в базу данных
4. **API**: FastAPI предоставляет REST эндпоинты

---

## 🔒 Безопасность

- ✅ **RLS (Row Level Security)** в Supabase
- ✅ **Валидация данных** через Pydantic
- ✅ **CORS** настроен для API
- ✅ **Service Key** не экспонируется на клиенте

---

## 🛠️ Решение проблем

### "Supabase не настроен"

Проверьте переменные окружения:
```bash
echo $SUPABASE_URL
echo $SUPABASE_SERVICE_KEY
```

### "RuBERT клиент не настроен"

Убедитесь, что `RUBERT_URL` указан и API доступен:
```bash
curl https://your-rubert.hf.space/api/health
```

### Ошибки при скрапинге

Сайт ФИПИ может блокировать запросы. Попробуйте:
- Изменить `User-Agent` в `scraper.py`
- Использовать прокси
- Добавить задержки между запросами

### Docker не собирается

Проверьте логи:
```bash
docker build -t fipi-scraper .
docker run -p 7860:7860 fipi-scraper
```

### Configuration error / Missing .env

**Это нормально!** Для Hugging Face Spaces:
1. Не загружайте `.env` в репозиторий
2. Настройте переменные через **Settings** → **Repository secrets**
3. Файл `.env.example` существует только для документации

---

## 📝 История изменений

### Март 2026 - Исправление парсера ФИПИ

**Исправленные проблемы:**
- ❌ Неверные URL-адреса (404 ошибки)
- ❌ SSL ошибки для поддоменов
- ❌ Некорректный парсинг заголовков

**Результат:**
- ✅ Найдено заданий: 0 → 12
- ✅ Все запросы возвращают 200 OK

Подробности в [FIXES.md](FIXES.md)

---

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

### Логи приложения

```bash
# Логи в Hugging Face Space
# Settings → Logs

# Локально
uvicorn app:app --log-level debug
```

### Метрики

- `/api/health` — статус сервисов
- `/api/stats` — статистика заданий

---

## 🤝 Интеграция с основным проектом

Этот сервис дополняет основной проект `refined-main`:

1. **Импорт заданий** из ФИПИ в базу
2. **AI-анализ** через тот же ruBERT
3. **Единая Supabase** для обоих сервисов

### Подключение

В основном проекте добавьте:

```typescript
// services/fipiTasks.ts
const FIPI_SCRAPER_URL = 'https://fipi-ai-scraper.hf.space';

export async function fetchLatestTasks(limit = 10) {
  const response = await fetch(`${FIPI_SCRAPER_URL}/api/tasks/latest?limit=${limit}`);
  return response.json();
}
```

---

## 📚 Дополнительные ресурсы

- [Документация FastAPI](https://fastapi.tiangolo.com/)
- [Документация Supabase](https://supabase.com/docs)
- [Hugging Face Spaces](https://huggingface.co/docs/hub/spaces)
- [ruBERT модель](https://huggingface.co/deepvk/rubert-base-cased)
- [ФИПИ](https://fipi.ru/)

---

## 📄 Лицензия

MIT License

---

**Последнее обновление:** Март 2026  
**Статус:** ✅ Готово к деплою