189 lines
5.7 KiB
Markdown
189 lines
5.7 KiB
Markdown
# Руководство по API генерации исследовательских отчётов
|
|
|
|
## Обзор
|
|
|
|
Новый эндпоинт `/api/parser/report` интегрирован с сервисом `deep-research` для генерации PDF-отчётов на основе пользовательских запросов.
|
|
|
|
## Эндпоинт
|
|
|
|
**POST** `/api/parser/report`
|
|
|
|
### Параметры запроса
|
|
|
|
| Параметр | Тип | Обязательный | По умолчанию | Описание |
|
|
| ------------- | ------- | ------------ | ------------ | ------------------------------- |
|
|
| `query` | string | ✅ | - | Тема для исследования |
|
|
| `lang` | string | ❌ | "ru" | Язык отчёта ("ru", "en") |
|
|
| `depth` | integer | ❌ | 3 | Глубина исследования (1-5) |
|
|
| `breadth` | integer | ❌ | 5 | Широта исследования (2-10) |
|
|
| `report_type` | string | ❌ | "report" | Тип отчёта ("report", "answer") |
|
|
|
|
### Пример запроса
|
|
|
|
```json
|
|
{
|
|
"query": "Искусственный интеллект в здравоохранении",
|
|
"lang": "ru",
|
|
"depth": 3,
|
|
"breadth": 5,
|
|
"report_type": "report"
|
|
}
|
|
```
|
|
|
|
### Ответы
|
|
|
|
#### Успешный ответ (200 OK)
|
|
|
|
- **Content-Type**: `application/pdf`
|
|
- **Content-Disposition**: `attachment; filename="research_report_[timestamp].pdf"`
|
|
- **Тело**: PDF-файл с отчётом
|
|
|
|
#### Ошибки
|
|
|
|
| Код | Описание |
|
|
| --- | ----------------------------------------- |
|
|
| 400 | Некорректные параметры запроса |
|
|
| 500 | Внутренняя ошибка сервера |
|
|
| 504 | Таймаут при обращении к deep-research API |
|
|
|
|
## Структура PDF-отчёта
|
|
|
|
Сгенерированный PDF содержит:
|
|
|
|
1. **Титульная страница**
|
|
|
|
- Название исследования (из поля `query`)
|
|
- Дата создания
|
|
- Подзаголовок "Исследовательский отчёт"
|
|
|
|
2. **Содержание**
|
|
|
|
- Автоматически сгенерированное оглавление
|
|
|
|
3. **Основная часть**
|
|
|
|
- Введение
|
|
- Основной текст отчёта от deep-research API
|
|
- Заключение
|
|
|
|
4. **Источники**
|
|
- Список URL-адресов из поля `visitedUrls`
|
|
|
|
## Конфигурация
|
|
|
|
Настройки в `application.properties`:
|
|
|
|
```properties
|
|
# Deep Research API Configuration
|
|
deep-research.api.url=http://185.35.223.45:3051
|
|
deep-research.api.timeout=300000
|
|
```
|
|
|
|
## Примеры использования
|
|
|
|
### cURL
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8080/api/parser/report" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"query": "Блокчейн технологии в финансах",
|
|
"lang": "ru",
|
|
"depth": 4,
|
|
"breadth": 6
|
|
}' \
|
|
--output "blockchain_report.pdf"
|
|
```
|
|
|
|
### JavaScript (fetch)
|
|
|
|
```javascript
|
|
const response = await fetch('/api/parser/report', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Content-Type': 'application/json',
|
|
},
|
|
body: JSON.stringify({
|
|
query: 'Квантовые вычисления',
|
|
lang: 'ru',
|
|
depth: 3,
|
|
breadth: 5,
|
|
report_type: 'report',
|
|
}),
|
|
});
|
|
|
|
if (response.ok) {
|
|
const blob = await response.blob();
|
|
const url = window.URL.createObjectURL(blob);
|
|
const a = document.createElement('a');
|
|
a.href = url;
|
|
a.download = 'quantum_computing_report.pdf';
|
|
a.click();
|
|
}
|
|
```
|
|
|
|
### Python (requests)
|
|
|
|
```python
|
|
import requests
|
|
|
|
response = requests.post(
|
|
'http://localhost:8080/api/parser/report',
|
|
json={
|
|
'query': 'Машинное обучение в медицине',
|
|
'lang': 'ru',
|
|
'depth': 3,
|
|
'breadth': 5,
|
|
'report_type': 'report'
|
|
}
|
|
)
|
|
|
|
if response.status_code == 200:
|
|
with open('ml_medicine_report.pdf', 'wb') as f:
|
|
f.write(response.content)
|
|
print("Отчёт сохранён как ml_medicine_report.pdf")
|
|
else:
|
|
print(f"Ошибка: {response.status_code}")
|
|
```
|
|
|
|
## Тестирование
|
|
|
|
Для тестирования API используйте скрипт `test_research_api.sh`:
|
|
|
|
```bash
|
|
./test_research_api.sh
|
|
```
|
|
|
|
## Логирование
|
|
|
|
Все операции логируются. Для отладки проверьте логи приложения:
|
|
|
|
```bash
|
|
tail -f logs/application.log | grep "DeepResearchService\|ResearchPdfService"
|
|
```
|
|
|
|
## Ограничения
|
|
|
|
- Максимальное время ожидания: 5 минут (300 секунд)
|
|
- Размер генерируемого PDF ограничен только ресурсами сервера
|
|
- Deep-research API должен быть доступен по указанному URL
|
|
|
|
## Устранение неполадок
|
|
|
|
### Ошибка 504 (Gateway Timeout)
|
|
|
|
- Проверьте доступность deep-research API
|
|
- Увеличьте timeout в конфигурации
|
|
- Проверьте сетевые настройки
|
|
|
|
### Ошибка 500 (Internal Server Error)
|
|
|
|
- Проверьте логи приложения
|
|
- Убедитесь, что все зависимости установлены
|
|
- Проверьте конфигурацию MinIO для сохранения файлов
|
|
|
|
### Пустой PDF
|
|
|
|
- Проверьте, что deep-research API возвращает корректные данные
|
|
- Убедитесь, что поле `report` или `answer` в ответе не пустое
|