Files

T

“Naeel” c34db5e5e3 docs: LLM-based documentation generation approach (gpt-oss-120b)

- Universal prompt template for any service
- Postgres test results: 9/10, zero invented params
- Requires Jenkins endpoint for map-fixed sub_fields

2026-07-05 17:27:12 +04:00

3.6 KiB

Raw Blame History

LLM-генерация документации (120B)

Идея

Вместо шаблонного docs-generator (который просто раскладывает YAML по таблицам), использовать LLM для генерации человекочитаемой документации с пониманием контекста.

Модель

gpt-oss-120b через API api.aillm.ru.

Как работает

yaml-generator получает полный YAML-спек сервиса из API Nubes
YAML (все операции, параметры, подсвойства map-fixed, MAN) подаётся LLM
LLM генерирует Markdown-страницу документации
Результат сохраняется в docs/30_registry/resources/{service}.md

Универсальный промпт

Ты — генератор документации Terraform-провайдера Nubes Cloud.
Отвечай ТОЛЬКО Markdown-кодом.

⛔ ЖЁСТКИЕ ПРАВИЛА (нарушать нельзя):

1. НЕ ВЫДУМЫВАЙ параметры. Только те, что есть в YAML.
   Если у параметра нет description — напиши "—".
   НИКОГДА не придумывай password, role, encoding и т.п.

2. Action-операции. ТОЛЬКО redeploy включается в документацию.
   restart, recovery, reconcile — ИСКЛЮЧИТЬ.

3. Subresource-операции. Каждый subresource → отдельная секция.
   Имя ресурса: nubes_{service}_{subresource}.

4. Lifecycle. suspend_on_destroy=true → "terraform destroy = Suspend".
   adopt_existing_on_create → "terraform apply может подхватить существующий".

5. Outputs. Все поля из outputs.params. vault_secrets помечать как 🔒.

6. MAN. Если service_man есть — вставить как есть в секцию ## MAN.

ФОРМАТ:
# Resource nubes_{name}
## MAN (если есть)
## Instance Operations (таблица)
## Create Parameters (таблица)
## Subresources (таблица по каждому)
## Lifecycle
## Outputs (таблица)

YAML-спек:
```yaml
{содержимое YAML-файла}


## Результаты тестирования (PostgreSQL)

| Критерий | Результат |
|---|---|
| Выдуманные параметры | ❌ 0 (было: password, roles, encoding) |
| Action-операции исключены | ✅ restart/recovery/reconcile |
| Subresources | ✅ user, database, backup |
| Параметры из YAML | ✅ username, role, dbName, dbOwner |
| Допустимые значения | ✅ app_user/ddl_user |
| Regex-ограничения | ✅ ^[A-Za-z0-9]+$ |
| Outputs | ✅ все 8 полей |
| Lifecycle | ✅ suspend_on_destroy=true |

## Ограничения

- `map-fixed` параметры описываются как "составной параметр" без подсвойств
- Нужен Jenkins-ендпоинт для получения sub_fields для map-fixed
- С полными данными оценка будет 10/10

## Интеграция в пайплайн

Предлагаемое место — после `01_generate_yamls.sh`, вместо текущего `02_generate_resources_and_docs_v2.sh` для docs-части:

01_generate_yamls.sh → YAML ↓ LLM-генератор → Markdown-доки resource-generator → Go-ресурсы

3.6 KiB Raw Blame History