| --- |
| 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 |
| **Статус:** ✅ Готово к деплою |
|
|
