diff --git a/llm_project/README.md b/llm_project/README.md index 1caf187..357da78 100644 --- a/llm_project/README.md +++ b/llm_project/README.md @@ -7,6 +7,7 @@ | Файл | Что | |---|---| | **[docs/ASSISTANT_ARCHITECTURE.md](docs/ASSISTANT_ARCHITECTURE.md)** | **Полная документация**: архитектура, API, поиск, безопасность, деплой, тесты, эмбеддинги v2, инциденты | +| **[docs/ROADMAP_AND_LIMITS.md](docs/ROADMAP_AND_LIMITS.md)** | **Дорожная карта, границы применимости, план тестирования (DevOps), варианты сбора данных** | | [PLAN_docs_ai_assistant_STEPS.md](PLAN_docs_ai_assistant_STEPS.md) | План по шагам (11 этапов) | ## Диагностика и обоснования diff --git a/llm_project/docs/ROADMAP_AND_LIMITS.md b/llm_project/docs/ROADMAP_AND_LIMITS.md new file mode 100644 index 0000000..4635d9a --- /dev/null +++ b/llm_project/docs/ROADMAP_AND_LIMITS.md @@ -0,0 +1,127 @@ +# AI-ассистент: дорожная карта, границы применимости и план тестирования + +Дата: 2026-10-08 +Статус: **v1 заморожен. Ждём реальных откликов.** +Связанные документы: [`ASSISTANT_ARCHITECTURE.md`](ASSISTANT_ARCHITECTURE.md), `~/nubes/HowTo/README.md`. + +--- + +## 1. Что сделано (итог) + +- Ассистент работает **на всех трёх стендах**: `nubes-test`, `nubes-dev`, `nubes` (prod). +- Надёжность: 62/62 на прогоне (4-я итерация), шаблон 100%, инъекции/офтоп — шаблонный отказ. +- Перф: поиск ~6 мс, кэш индекса и ответов, дедлайн 40 с, логирование этапов, токены в ответе. +- Виджет: FAB «LLM», раскрывающееся описание, таймер «⏳ N с», время+токены в ответе. +- Автоматизация: redeploy через API, тест-прогон, публикация сайта (см. HowTo). +- Документация: `ASSISTANT_ARCHITECTURE.md`, `llm_project/README.md`, три HowTo, индексы в README репозиториев. + +--- + +## 2. Направления развития (что можно совершенствовать) + +По слоям, от наибольшего эффекта: + +| # | Слой | Что | Как | +|---|---|---|---| +| 1 | **Контент** | Больше `curated/*` примеров | Реальные сценарии; они приоритетны в поиске (×2.4) | +| 2 | **Поиск** | Эмбеддинги + реранкер | `user-bge-m3` + `bge-reranker-v2-m3`, векторы в памяти | +| 3 | **Поиск** | Гибрид лексика+вектора | Объединение по max (механика уже есть) | +| 4 | **Этап 1** | Точность `resource_type` | Few-shot; детерминированный шорткат при `nubes_X` в тексте | +| 5 | **Генерация** | Стриминг (SSE) | Юзер видит текст сразу | +| 6 | **Генерация** | Цитаты `[1]`, groundedness-проверка | Сверка чисел/имён с контекстом | +| 7 | **Перф** | Параллелить этап 1 и поиск | −1–2 с | +| 8 | **Перф** | Кэш ответов TTL/LRU; прогрев индекса | Сейчас без лимита/прогрева | +| 9 | **Инфра** | Несколько реплик + общий кэш (Redis) | Сейчас 1 под | +| 10 | **Продукт** | История диалога, фидбэк 👍/👎 | Новые эндпоинты | + +--- + +## 3. Где хранить сбор данных (обсуждено, НЕ реализовано) + +Цель: собрать **реальные вопросы и фидбэк** для улучшений. + +| Вариант | Плюсы | Минусы | +|---|---|---| +| **stdout → Grafana** | ноль инфраструктуры, уже есть логирование | зависит от retention логов | +| **S3 (JSONL)** | долговечно, дёшево, есть в стеке | нет S3-кред в `tf_docs` (вернуть сервисный доступ) | +| **Файл на ВМ 213** | просто | ⛔ нельзя в `/var/www/tf-docs/` (перезапишется `mc mirror`); SPOF, без бэкапа | +| **PG на ВМ 213** | структурировано | тот же SPOF/диск; 5432 localhost → из пода недоступен; +зависимость `pg` | +| **PG в кластере рядом с NodeJS** | сетевая доступность, не тот диск, управляется платформой | +сервис (стоимость), +зависимость, +секреты | + +**Если понадобится** — рекомендация: **managed `nubes_postgres` рядом с `tf_docs`**, запись fire-and-forget (не блокирует ответ, ошибки не влияют). Альтернатива для старта — stdout. + +--- + +## 4. Решение по развитию + +**Пока ничего не делаем.** Обоснование: +- Реальные пользователи ещё не тестировали → нет подтверждённых промахов. +- Сбор данных без пользователей собирать нечего. +- Любое улучшение (эмбеддинги, PG, стриминг) — работа/риск/стоимость без доказанной пользы. + +**Ждём**: конкретные плохие ответы, жалобы «не нашёл то, что есть в доках», или задачу «нужна статистика». + +**Триггеры для возобновления:** +1. ≥N конкретных плохих ответов (примеры); +2. жалоба на поиск (есть в доках, но не нашёл); +3. требование дашборда/статистики. + +--- + +## 5. План тестирования: DevOps-инженеры + +Тестируют не случайные юзеры, а **девопсы** (пишут сервисы, мануалы, IaC). +Цель теста: понять **границы применимости** — на что отвечает, на что нет. + +### 5.1. Что просить у тестировщиков + +- Задавать вопросы **в формате своей работы**: «как развернуть X из нашего стека», «какие параметры у Y», «как связать A и B», «как настроить бэкап». +- Для каждого вопроса фиксировать: **вопрос → помогло/нет → что не так** (кратко). +- Отдельно: вопросы **из внутренних регламентов** (CI/CD, пайплайны, обработка ошибок API) — чтобы понять, чего ассистент не знает. + +### 5.2. На что ассистент отвечает ХОРОШО + +- «Как развернуть сервис X» по нашим ресурсам: postgres/mongo/redis/kafka/rabbitmq/clickhouse, k8s (Штурвал, Velero, OpenBao), VMware (org→vDC→vApp→ВМ), S3, сеть (белый IP, DNS, SNAT, zones), приложения (nodejs, flask, lucee, nextcloud, gitea…). +- **Параметры ресурса**: обязательные/опциональные поля, типы. +- **Примеры HCL** и порядок создания (зависимости). +- **Готовые примеры** (`curated/*`, в т.ч. CRUD-стенд) — теперь приоритетно. +- **Жизненный цикл**: `destroy` → suspend и т.п. +- Операционные вопросы уровня ресурса: привязка внешнего IP, бэкапы, ключи доступа. +- Опечатки, другой язык (проверено: «создть пострес», «How to create…»). + +### 5.3. На что отвечает ПЛОХО / НЕ ответит (честно) + +- **Вне документации Nubes**: внутренняя кухня платформы, биллинг/цены, SLA, квоты — если этого нет на сайте. +- **Внутренние регламенты/процессы**: как писать мануалы, пайплайн публикации, CI/CD, gitea-flow — этого в пользовательской документации нет. +- **Состояние конкретного инстанса**: «что у меня сейчас развёрнуто», «почему упал мой инстанс» — ассистент **не читает облако**, только доку. +- **Ошибки apply/API**: коды ошибок, `errorLog`, диагностика — если не описано на сайте. +- **Креды/UUID/секреты** конкретных ресурсов. +- **Свежие изменения**, ещё не опубликованные в индексе (индекс берётся с сайта; обновляется при публикации доков). +- **Многошаговые процедуры вне документации** («сделай A, потом объясни, почему B») — ответит поверхностно. +- **Числа/цены**, если их нет в тексте. +- Вопросы, где нужна **семантика/перефразы**, которых нет в тексте дока (лексический поиск). + +### 5.4. Шаблон фидбэка тестировщика + +``` +ВОПРОС: <дословно> +ОЖИДАЛ: <что хотел получить> +ПОЛУЧИЛ: <ответ ассистента> +ВЕРДИКТ: помогло / частично / не помогло +ЧЕГО НЕ ХВАТИЛО: <если есть> +``` + +### 5.5. Что делать с результатами + +- Собрать список «не помогло» → классифицировать: + - **нет в доках** → вопрос к контенту (добавить страницу); + - **есть в доках, но не нашёл** → вопрос к поиску (сюда эмбеддинги); + - **ответ неверный/выдуман** → вопрос к промпту/groundedness. +- Только после этого — точечные улучшения из §2. + +--- + +## 6. Итог + +v1 работает и заморожен. Развитие — **по данным реального тестирования**, а не по догадкам. +Первый тест — **DevOps-инженеры** (см. §5), собирать отзывы вручную по шаблону §5.4.