From 1dd5be68ddf0f7160c0a6d7d5a94ad365a4588b4 Mon Sep 17 00:00:00 2001 From: host Date: Mon, 21 Sep 2026 20:44:17 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20README.md=20=D1=81=20=D0=BF=D1=80=D0=B8?= =?UTF-8?q?=D0=BC=D0=B5=D1=80=D0=B0=D0=BC=D0=B8=20=D0=B2=D1=8B=D0=B7=D0=BE?= =?UTF-8?q?=D0=B2=D0=B0,=20=D1=83=D1=81=D1=82=D0=B0=D0=BD=D0=BE=D0=B2?= =?UTF-8?q?=D0=BA=D0=BE=D0=B9=20=D0=B8=20=D0=BD=D0=B0=D1=81=D1=82=D1=80?= =?UTF-8?q?=D0=BE=D0=B9=D0=BA=D0=BE=D0=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 161 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..999013c --- /dev/null +++ b/README.md @@ -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`, списки, таблицы, блоки кода, ``, номера страниц | +| `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://:8080/api/v1/tools/ \ + -H "Authorization: Bearer " \ + -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 млн | + + ## Приложение + Код: `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//content`. + +## Структура репозитория + +``` +document-generator/ +├── document_generator.py # сам инструмент (Open WebUI function) +├── requirements.txt # Python-зависимости +└── README.md +```