diff --git a/docs/product/search-codex-rag-plan.md b/docs/product/search-codex-rag-plan.md new file mode 100644 index 0000000..6a733ee --- /dev/null +++ b/docs/product/search-codex-rag-plan.md @@ -0,0 +1,39 @@ +# Поиск Акылдаша через Codex CLI и локальный RAG + +В лаборатории `/review` пользователь задаёт вопрос на русском или кыргызском. Бэкенд передаёт исходный вопрос в Codex CLI. Codex сам формулирует поисковые запросы, получает статьи из локального индекса и возвращает их идентификаторы. Лаборатория показывает источники и варианты уточнения ситуации. Codex CLI использует подписку ChatGPT. Эмбеддинги рассчитываются локально. + +## 1. Пересобрать корпус для RAG + +- Использовать нормализованные выгрузки ЦБД Минюста КР. В пилот включить двуязычные акты разных типов, в том числе действующие и утратившие силу. Зафиксировать версию выгрузки, коды документов и редакций. Дату принятия, дату вступления в силу и метку редакции хранить отдельно при наличии сведений в источнике. +- Группировать фрагменты по статьям и пунктам, сохраняя идентификаторы источника и границы статьи. Для длинных статей использовать окна с перекрытием. Поиск сочетает полнотекстовый и векторный отбор, а также фильтры по языку, статусу и редакции. +- Собрать пилотный индекс отдельно. Проверить хеши и покрытие RU/KY, размер текста и векторов, выдачу по номерам актов и разговорным вопросам. Локальный SQLite с FTS5 и точным векторным поиском подходит для выборки. Перед сборкой полного корпуса проверить движок с индексированным векторным поиском, включая замер на OpenSearch с фактическими настройками хранения. +- Оценить диск для индекса, модели и runtime, временных файлов и одновременного размещения двух версий индекса. В staging проверить возобновление сборки, обновление изменившихся актов и переключение на предыдущую версию. + +Первый замер и команды повторной сборки описаны в [отчёте пилота](../../tools/rag-pilot/README.md). + +## 2. Установить Codex CLI + +- Проверить уже установленный CLI в WSL и использовать его для локального прогона. Для staging подготовить отдельного непривилегированного воркера с фиксированной версией CLI. +- Авторизовать через `codex login --device-auth`, проверить `codex login status` и запуск `codex exec` после перезапуска. Описать обновление и повторную авторизацию воркера. [Авторизация Codex](https://learn.chatgpt.com/docs/auth?surface=cli) + +## 3. Настроить Codex CLI + +- Версионировать постоянные инструкции и скилл правового поиска. Явно активировать скилл на каждом запуске. Скилл задаёт поиск по юридическим терминам, проверку редакций и выбор до трёх уточнений, которые могут изменить релевантные нормы. +- Подключить локальный MCP с операциями чтения для поиска и получения статьи в конкретной редакции. Ограничить параметры, объём результата и число поисковых вызовов на вопрос. Изолировать воркер от БД пользователей, секретов и административного доступа VPS. +- Зафиксировать схему ответа с идентификаторами фрагментов, вариантами уточнения и статусом поиска. Проверить неполные данные и конфликт редакций. [Скиллы](https://learn.chatgpt.com/docs/build-skills) · [Неинтерактивный режим](https://learn.chatgpt.com/docs/non-interactive-mode) + +## 4. Интегрировать CLI с бэкендом + +- Добавить закрытый режим `/review`. Передавать исходный вопрос, язык, фильтры и выбранную деталь в воркер. Ограничить время и параллельность запусков. Различать отсутствие подходящей нормы, таймаут, потерю авторизации и исчерпание лимита подписки. +- Проверять принадлежность возвращённых идентификаторов результатам текущего запуска. Формировать цитаты, редакции и ссылки из корпуса. Версии индекса, скилла и CLI сохранять в снимке выдачи. В метриках хранить длительность этапов и тип сбоя. Объём сохраняемого пользовательского текста согласовать перед широким запуском. + +## 5. Обновить лабораторию `/review` + +- Добавить сравнение обычного поиска и Codex + RAG по одному вопросу. Показать статьи с редакцией, статусом и ссылкой на полный текст. Сохранить оценки, снимки и экспорт отзывов. +- После выдачи показать динамические кнопки уточнения и поле «Уточнить ситуацию». При повторном запуске передавать исходный вопрос и выбранную деталь. Показывать применённое уточнение с возможностью убрать его. +- Для рецензента показывать фактические запросы к корпусу, кандидатов и длительность этапов. + +## 6. Проверить эффект и подготовить развёртывание + +- Сравнить текущий поиск, прямой поиск по новому индексу и Codex с тем же новым индексом. Использовать размеченные вопросы RU/KY и точные запросы по реквизитам. Измерить попадание нужной статьи в топ‑3 и топ‑10, ошибки ссылок и редакций, пользу уточнения, задержку, сбои и расход лимита подписки. +- Уровень риска реализации `HIGH`. Выполнить целевые проверки данных и изоляции, обычный CI и независимое ревью. Сначала staging, затем отдельное решение о публичном запуске. Production-изменения требуют разрешения владельца, проверенного внешнего backup и восстановления, подтверждения ёмкости и готового отката. diff --git a/tools/rag-pilot/README.md b/tools/rag-pilot/README.md new file mode 100644 index 0000000..825281c --- /dev/null +++ b/tools/rag-pilot/README.md @@ -0,0 +1,47 @@ +# Пилот RAG для Акылдаша + +Инструмент `rag_pilot.py` создаёт отдельный SQLite-файл для небольшой двуязычной выборки нормализованных документов Минюста КР. Он объединяет FTS5 и точный поиск по 384-мерным векторам. Эмбеддинги вычисляются через ONNX Runtime на CPU. Поиск открывает файл в режиме чтения. При сборке существующий файл с таким именем не перезаписывается. + +Пилот использует последнюю объявленную редакцию каждого выбранного документа в локальном снимке. Это даёт воспроизводимую выборку для проверки поиска. Для проверки юридической актуальности нужны сведения из официального источника. Например, локальный снимок Трудового кодекса `230021083` содержит редакцию `60` с меткой 23.06.2026. В прошлой диагностике проекта отдельно была зафиксирована более поздняя официальная редакция. См. [диагностику релевантности](../../docs/product/search-relevance-findings-2026-11-03.md). + +## Воспроизведение + +Нужны Python 3.12 или новее с SQLite FTS5 и пакеты `numpy`, `onnxruntime`, `tokenizers`. Скачайте [веса ONNX](https://huggingface.co/intfloat/multilingual-e5-small/blob/main/onnx/model_qint8_avx512_vnni.onnx) как `model.onnx` и [токенизатор](https://huggingface.co/intfloat/multilingual-e5-small/blob/main/onnx/tokenizer.json) как `tokenizer.json` в `tmp/rag-model`. Скрипт проверяет SHA-256 перед загрузкой. После установки зависимостей и загрузки файлов сборка и поиск работают локально. + +Из корня репозитория: + +```text +python -m pip install numpy onnxruntime tokenizers +python -m unittest discover -s tools/rag-pilot -p "test_*.py" +python tools/rag-pilot/rag_pilot.py --model-dir tmp/rag-model build --corpus data/minjust-normalized --index data/rag-pilot/laws-v1.sqlite3 230021083 230029465 230000918 112451 111573 +python -X utf8 tools/rag-pilot/rag_pilot.py --model-dir tmp/rag-model search --index data/rag-pilot/laws-v1.sqlite3 --language ru "Могут ли меня уволить на испытательном сроке?" +python -X utf8 tools/rag-pilot/rag_pilot.py --model-dir tmp/rag-model search --index data/rag-pilot/laws-v1.sqlite3 --language ky "Сыноо мөөнөтүндө жумуштан бошотсо болобу?" +``` + +Создайте каталог `data/rag-pilot` перед сборкой. Выходной файл, зависимости и веса держите в локальных каталогах проекта. Формат пилотного артефакта — `0.1.0`. + +## Ограничения выборки + +Пять актов подобраны вручную. Их выдача подходит для проверки работоспособности и точности ссылок на фрагменты. Для оценки релевантности понадобится независимый размеченный набор. Точный векторный поиск загружает векторы выбранного языка в память, поэтому расчёт для VPS требует отдельного замера масштабируемого движка. + +## Замер 22 ноября 2026 года + +| Показатель | Результат | +|---|---:| +| Акты и фрагменты | 5 актов, 797 RU и 858 KY | +| SQLite с текстом, FTS5, метаданными и векторами | 10 256 384 байта, 9,78 МиБ | +| Векторы float32 в пилотном индексе | 2 542 080 байт, 1 536 байт на фрагмент | +| Веса и токенизатор | 129,2 МиБ | +| Локальные зависимости Python на Windows | 141,6 МиБ | + +`PRAGMA integrity_check` вернул `ok`. Проверенный SHA-256 файла — `8da4843cdcf8cadcc815512625d9157209a16695c2e2635829df3a02355c85e5`. По разговорному вопросу об увольнении на испытательном статья 24 локальной редакции Трудового кодекса заняла второе место на русском и первое на кыргызском. По точным запросам с номером статьи она заняла первое место на обоих языках. Кыргызские заголовки вида `24-берене`, которые нормализатор иногда размечает как обычные абзацы, распознаются при построении пилота. + +### Оценка места на VPS + +Равномерная случайная выборка из 512 документов манифеста (seed `20261122`) дала 4 310 фрагментов RU/KY по правилу последней редакции локального снимка. Проекция на 209 958 документов даёт 1,77 млн фрагментов. 95-процентный бутстрэп-интервал по документам составляет приблизительно 1,22–2,43 млн. Он описывает неопределённость выборки и не учитывает другой алгоритм нарезки или более свежий корпус. + +```text +python tools/rag-pilot/rag_size_sample.py data/minjust-normalized tmp/rag-model/tokenizer.json +``` + +При плотности хранения пилота это **7–14 ГиБ на один индекс** и около 10,2 ГиБ по центральной оценке. Из них 1,75–3,48 ГиБ занимают сами векторы float32. Для планирования staging стоит заложить **25–40 ГиБ свободного места** на две версии индекса, модель, runtime и временные файлы. Read-only замер `df` на VPS показал **44,1 ГиБ свободно на `/`**. В расчёт не входят исходная выгрузка, исторические редакции, внешние резервные копии и накладные расходы выбранного движка. Размер и пиковое потребление памяти OpenSearch предстоит измерить до развёртывания. diff --git a/tools/rag-pilot/rag_pilot.py b/tools/rag-pilot/rag_pilot.py new file mode 100644 index 0000000..b812fa2 --- /dev/null +++ b/tools/rag-pilot/rag_pilot.py @@ -0,0 +1,225 @@ +"""Build and query an isolated bilingual retrieval pilot on CPU.""" + +import argparse +from collections import defaultdict +from contextlib import closing +import hashlib +from itertools import batched +import json +import os +from pathlib import Path +import re +import sqlite3 +import tempfile + +import numpy as np +import onnxruntime as ort +from tokenizers import Tokenizer + + +MODEL = "intfloat/multilingual-e5-small" +MODEL_FILES = { + "model.onnx": "dd476dd0c2514e9b9be83aeb3853fac0763e0bdf4a71645407587d77c48a2d88", + "tokenizer.json": "0b44a9d7b51c3c62626640cda0e2c2f70fdacdc25bbbd68038369d14ebdf4c39", +} +LANGUAGES = ("ru", "ky") +DIMENSIONS = 384 +FORMAT_VERSION = "0.1.0" +WINDOW_SIZE = 360 +WINDOW_STEP = 328 +KY_ARTICLE = re.compile(r"^\s*\d+(?:[-‑–]\d+)*\s*[-‑–]\s*берене\b", re.IGNORECASE) + + +class Embedder: + def __init__(self, model_dir): + for name, expected in MODEL_FILES.items(): + with (model_dir / name).open("rb") as source: + if hashlib.file_digest(source, "sha256").hexdigest() != expected: + raise ValueError(f"Unexpected model file checksum: {name}") + self.tokenizer = Tokenizer.from_file(str(model_dir / "tokenizer.json")) + self.encoder = Tokenizer.from_file(str(model_dir / "tokenizer.json")) + self.encoder.enable_truncation(max_length=512) + self.encoder.enable_padding(pad_id=self.encoder.token_to_id("")) + options = ort.SessionOptions() + options.intra_op_num_threads = min(os.cpu_count() or 1, 6) + self.session = ort.InferenceSession( + str(model_dir / "model.onnx"), sess_options=options, providers=["CPUExecutionProvider"] + ) + self.input_names = {entry.name for entry in self.session.get_inputs()} + + def embed(self, texts): + encoded = self.encoder.encode_batch(texts) + mask = np.asarray([item.attention_mask for item in encoded], dtype=np.int64) + inputs = { + "input_ids": np.asarray([item.ids for item in encoded], dtype=np.int64), + "attention_mask": mask, + "token_type_ids": np.zeros_like(mask), + } + hidden = self.session.run(None, {key: inputs[key] for key in self.input_names})[0] + pooled = (hidden * mask[:, :, None]).sum(axis=1) / mask.sum(axis=1, keepdims=True) + vectors = (pooled / np.linalg.norm(pooled, axis=1, keepdims=True)).astype("