docs: README.md с примерами вызова, установкой и настройкой
This commit is contained in:
host committed
1 parent
0875fdee69
commit
1dd5be68dd
1 file changed
+161
@@ -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
|
||||||
|
```
|
||||||
Reference in new issue
Block a user