diff --git a/SSO.md b/SSO.md index f3be41e..562fb92 100644 --- a/SSO.md +++ b/SSO.md @@ -260,3 +260,120 @@ PATCH /providers/oauth2/{pk}/ **Правило:** при создании OAuth2-провайдера через API **всегда** указывать `signing_key`, иначе вход падает на проверке подписи. + + +--- + +# Семантический поиск по документам (B-11) + +## Что сделано + +| Компонент | Где | +|---|---| +| Эмбеддинги | Ollama `nomic-embed-text` (768), CT160:11434 | +| Хранилище | PostgreSQL + pgvector, CT151, база `rag` | +| Таблица | `chunks(source, ref, text, embedding vector(768))`, HNSW-индекс | +| Индексатор | `/opt/hub-core/rag.py` (полный), `rag_priority.py` (быстрый) | +| Ответы | `/rag?q=...` (генерация) и `&mode=find` (поиск) | + +## Как работает + +1. Документ режется на фрагменты по 2500–3000 символов. +2. Каждый фрагмент превращается в вектор через Ollama. +3. Вектор кладётся в pgvector с уникальным ключом `(source, ref)`. +4. На вопрос: вектор вопроса → ближайшие 5 фрагментов → генерация ответа + с указанием источников. + +## Источники (v1) + +- `ops/**/*.md` — документация репозитория; +- заметки Memos (SQLite из CT110). + +## Проверка + +```bash +cd /opt/hub-core +/opt/music-tools/venv/bin/python rag.py ask "как устроен мониторинг Beszel?" +curl -s 'http://127.0.0.1:9120/rag?q=как+устроен+беczel' | head -c 400 +``` + +## Ловушки + +1. **Эмбеддинг на CPU медленный**: ~8–20 с на фрагмент при загруженной + машине. Поэтому индексируем крупными кусками (2500–3000 символов), + а не по 1000. +2. **Индексация должна коммитить каждые N фрагментов**, иначе при + прерывании теряется всё (транзакция откатывается). +3. **`psycopg2` требует `client_encoding=utf8`** — без него русский текст + падает с `UnicodeEncodeError`. +4. **`/ask` уже занят** (агентский ответ по медиа), поэтому RAG живёт + на `/rag`. +5. Ollama был привязан к `127.0.0.1`; открыт в LAN через + `OLLAMA_HOST=0.0.0.0` (drop-in в CT160). + +## Что дальше + +- Добавить Paperless (тексты документов) и Nextcloud (txt/md). +- Инкрементальная индексация по времени изменения файла. +- Вечерний отчёт: «добавлено N фрагментов». + +## Режимы работы + +| Режим | Запрос | Время | Что делает | +|---|---|---|---| +| Поиск | `/rag?q=...&mode=find` | **~14 с** | находит фрагменты, без генерации | +| Ответ | `/rag?q=...` | минуты | поиск + генерация моделью | + +**Проверено на живом примере**: вопрос «как устроен Beszel» → +первый результат `ops/ops/BESZEL.md#0` со счётом 0.63. + +## Ограничение: генерация на CPU + +`qwen2.5:3b` на этой машине генерирует ответ дольше 10 минут при +текущей нагрузке (память в свопе). Поэтому: + +- **поиск использовать можно** — он быстрый и полезный; +- **генерацию** — только когда освободится память, либо перейти + на `qwen2.5:0.5b`/`1.5b`. + +После работы модель выгружается (`keep_alive=0`), чтобы не держать +1.2 ГБ в памяти. + + +--- + +# Обучение агента: подсказки по повторяющимся сбоям (B-21) + +## Что добавлено + +1. **Дедупликация причин.** Раньше в памяти копилось + `["docker state: exited", "docker state: exited", ...]` — + теперь одинаковые подряд не дублируются. +2. **Словарь решений `SOLUTIONS`.** Для типовых сбоев агент печатает + подсказку рядом с проблемой. +3. **Поле `hint` в отчёте** (`/var/lib/hub-agents/journal/<дата>-runner.json`). + +## Таблица подсказок + +| Причина | Подсказка | +|---|---| +| `exited` | перезапустить контейнер; если повторяется — смотреть логи и память CT | +| `restarting` | чаще всего права на том или конфликт порта | +| `no space` | `docker system prune` и ротация логов | +| `permission denied` | `chown` тома после пересоздания контейнера | +| `connection refused` | сервис не слушает порт: проверить процесс и `ss -ltn` | +| `не в статусе` | нет `/health`: проверить nginx-прокси и порт | +| `cert` | `certbot renew` и копирование в `/etc/nginx/certs` | + +## Пример вывода + +``` +✗ freshrss (CT111, сбоев 3): docker state: exited + → перезапустить контейнер: healthcheck в CT делает это сам; + если повторяется — смотреть docker logs и память CT +``` + +## Что дальше + +- Копить статистику: какая подсказка реально помогла (флаг `resolved_by`). +- Ограничить автоматические действия классом B (уже сделано в `actions.py`).