docs: README.md с примерами вызова, установкой и настройкой

2026-09-21 20:44:17 +03:00
1 parent 0875fdee69
commit 1dd5be68dd
@@ -0,0 +1,161 @@
+# Document Generator (Open WebUI Tool)
+
+Инструмент для Open WebUI: генерация файлов **Word (.docx)**, **Excel (.xlsx)** и **PowerPoint (.pptx)** из ответов LLM с последующей загрузкой в файловое хранилище Open WebUI.
+
+- **Версия:** 3.7
+- **Автор:** Ngo Tan Tai (https://newnol.io.vn)
+- **Лицензия:** MIT
+- **Требуемая версия Open WebUI:** ≥ 0.4.0
+
+## Возможности
+
+| Функция | Формат входа | Особенности |
+|---|---|---|
+| `generate_word_doc` | Markdown | Заголовки, bold/italic, `code`, списки, таблицы, блоки кода, `<pagebreak>`, номера страниц |
+| `generate_excel_file` | JSON / CSV / Markdown-таблица | Автопоиск таблиц в nested JSON, несколько листов, защита от formula injection, автоширина колонок, автофильтр и закреплённая шапка |
+| `generate_pptx_file` | JSON / простой текст | Титульный слайд, спикер-ноуты, вставка картинок (URL, `/api/v1/files/...`, data URI), авто-разбиение «длинных» слайдов, 16:9, свой шаблон `.pptx` |
+
+## Установка
+
+### 1. Зависимости (важно!)
+
+Open WebUI **не устанавливает** пакеты из `requirements` в docstring автоматически — ставьте их в своё окружение:
+
+```bash
+pip install -r requirements.txt
+# или по одному:
+pip install python-docx openpyxl python-pptx aiohttp pillow
+```
+
+Если инструмент работает в Docker-контейнере — добавьте эти пакеты в образ или смонтируйте их в `site-packages`. Без пакетов функция вернёт понятную ошибку вида `Не установлен пакет python-docx`, а не упадёт с `NameError`.
+
+### 2. Регистрация инструмента
+
+Вариант A — через UI: **Settings → Tools → Create Tool**, вставьте содержимое `document_generator.py`.
+
+Вариант B — API:
+
+```bash
+curl -X POST http://<open-webui>:8080/api/v1/tools/ \
+  -H "Authorization: Bearer <ADMIN_API_KEY>" \
+  -H "Content-Type: application/json" \
+  -d @- <<'EOF'
+{
+  "name": "document-generator",
+  "description": "Генерация Word, Excel и PowerPoint файлов",
+  "function": "<содержимое document_generator.py>",
+  "manifest": {
+    "api_version": "v1",
+    "required_open_webui_version": "0.4.0"
+  }
+}
+EOF
+```
+
+### 3. Настройка
+
+**Valves (админ):**
+
+| Валв | Значение по умолчанию | Назначение |
+|---|---|---|
+| `public_domain` | `https://your-openwebui-domain.com` | Публичный домен Open WebUI (без `/` в конце) — для ссылки «Скачать». Если не задан, берётся из запроса |
+| `internal_api_url` | `http://127.0.0.1:8080` | Внутренний URL API Open WebUI (для загрузки файлов) |
+| `max_rows` | 50000 | Excel: максимум строк на лист |
+| `max_slides` | 60 | PPTX: максимум слайдов |
+| `max_content_chars` | 200000 | Максимальная длина входного текста/JSON |
+| `allow_formulas` | false | Excel: разрешать строки, начинающиеся с `=` (как формулы) |
+| `convert_numeric_strings` | false | Excel: превращать `'123'`, `'1 234,5'` в числа |
+| `pptx_widescreen` | true | PPTX: формат 16:9 |
+| `pptx_template_path` | — | Путь к собственному `.pptx`-шаблону на сервере |
+
+**UserValves (каждый пользователь):**
+
+| Валв | Назначение |
+|---|---|
+| `openwebui_api_key` | **Обязательно.** API Key пользователя (Settings → Account → API Keys). Без него функция вернёт предупреждение |
+
+## Примеры вызова
+
+### Word
+
+```
+Сгенерируй Word-документ:
+title: "Отчёт за 2025"
+content:
+  # Обзор
+  За год выручка выросла на **23%**.
+
+  ## Детали
+  - Q1: 12 млн
+  - Q2: 15 млн
+  | Показатель | Значение |
+  |---|---|
+  | Выручка | 62 млн |
+  <pagebreak>
+  ## Приложение
+  Код: `select * from sales;`
+```
+
+### Excel
+
+```
+Создай Excel-файл:
+filename: "quarterly_sales"
+data_json:
+  [
+    {"Месяц": "Январь", "Продажи": 1250000, "Возвраты": 45000},
+    {"Месяц": "Февраль", "Продажи": 1380000, "Возвраты": 62000},
+    {"Месяц": "Март", "Продажи": 1510000, "Возвраты": 51000}
+  ]
+```
+
+Несколько листов:
+
+```json
+{
+  "Сводка": [["Показатель", "Значение"], ["Выручка", 6200000]],
+  "Детализация": [["Артикул", "Название", "Кол-во"], ["A-100", "Видеокарта", 12]]
+}
+```
+
+### PowerPoint
+
+```
+Сделай презентацию:
+filename: "company_pitch"
+title: "Наше предложение"
+slides_content:
+  [
+    {"title": "Кто мы", "content": "10 лет на рынке\n50+ корпоративных клиентов", "notes": "Начать с истории компании"},
+    {"title": "Продукт", "content": "Модульная платформа\nБыстрый старт за 1 день", "image": "/api/v1/files/abc123/content"}
+  ]
+```
+
+Текстовый формат (без JSON) тоже работает:
+
+```
+Slide 1: Введение
+- Первый пункт
+  - Подпункт
+- Второй пункт
+
+Slide 2: Результаты
+- Выручка +23%
+```
+
+## Безопасность
+
+- **SSRF-защита:** внешние URL картинок резолвятся и проверяются — приватные адреса (loopback, 10/8, RFC1918 и т.п.) блокируются; редиректы запрещены (`allow_redirects=False`).
+- **Formula injection в Excel:** строки, начинающиеся с `=`, пишутся как обычный текст, пока `allow_formulas=true`.
+- **Имена файлов:** санитизация (`basename`, спецсимволы → `_`), лимит 100 символов.
+- **Лимиты:** размер входных данных, строк в Excel, слайдов, размера изображений — настраиваются через Valves.
+- **Внутренние пути:** из картинок разрешена только загрузка через `/api/v1/files/<id>/content`.
+
+## Структура репозитория
+
+```
+document-generator/
+├── document_generator.py   # сам инструмент (Open WebUI function)
+├── requirements.txt        # Python-зависимости
+└── README.md
+```