LexIR

LexIR — исследовательский прототип интеллектуального юридического ассистента с гибкой архитектурой под любой правовой корпус. Система сочетает семантический поиск (fine‑tuned MPNet + FAISS) и «grounded»‑ответы ассистента, которые строятся только на найденных нормах из подключенного корпуса.

Кратко о том, как все работает

1. Источник норм: парсер/ETL вытягивает тексты правовых норм и приводит их к унифицированному формату.
2. Корпус: RU/KZ JSONL‑набор норм (в демо — Конституция РК как пример).
3. Обучение bi‑encoder: src/train_biencoder.py дообучает MPNet на парах «запрос → релевантная норма».
4. Индексы: src/build_index.py строит FAISS‑индексы по RU/KZ для базовой/LaBSE/финетюн‑модели.
5. Retrieval API: site/backend/app.py поднимает FastAPI и локально выполняет поиск по FAISS.
6. LLM‑оркестрация: Azure OpenAI Assistant получает запрос, обязан вызвать инструмент lexir_retrieve_constitution, и формирует ответ только на основе возвращенных норм.
7. UI: фронтенд отправляет запросы на /api/chat, хранит thread_id в sessionStorage и отображает ответы.

Архитектура (модули)

• Data ingestion: data_parser/adilet_zan_parser.py → data/clauses_constitution_ru_kz.jsonl (в демо).
• Training: src/train_biencoder.py → artifacts/models/finetuned_mpnet/.
• Indexing: src/build_index.py → artifacts/indexes/<alias>/{ru,kz}.faiss + *_meta.jsonl.
• Evaluation: src/evaluate.py, src/plot_eval.py, src/validate.py → artifacts/reports/.
• Backend: site/backend/app.py (FastAPI + Azure OpenAI Assistants).
• Assistant tooling: site/backend/assistant/*.py.
• Frontend: site/frontend/ (статический SPA‑интерфейс).

Структура репозитория (ключевое)

artifacts/
  models/finetuned_mpnet/       # fine‑tuned MPNet
  indexes/<alias>/              # FAISS индексы + meta JSONL
  reports/                      # eval отчеты и графики
data/
  clauses_constitution_ru_kz.jsonl
  legal_assistant_train.jsonl
  legal_assistant_test.jsonl
data_parser/
  adilet_zan_parser.py
site/
  backend/
    app.py
    assistant/
      assistant_create.py
      assistant_edit.py
      assistant_info.py
      demo_assistant.py
  frontend/
    index.html
    app.js
    styles.css
src/
  build_index.py
  train_biencoder.py
  evaluate.py
  plot_eval.py
  validate.py
  demo_cli.py
  api.py

Данные и формат

data/clauses_constitution_ru_kz.jsonl — параллельный RU/KZ корпус (в демо — Конституция РК как пример). Каждая строка:

{
  "id": "KZ.CONST.1995:ART18:PAR2:cl1",
  "text": "русский абзац ...",
  "text_kz": "қазақша абзац ...",
  "meta": {
    "doc_id": "KZ.CONST.1995",
    "article_number": "18",
    "paragraph_number": 2,
    "article_title_ru": "...",
    "article_title_kz": "...",
    "source_ru": "...",
    "source_kz": "..."
  }
}

Retrieval и ранжирование

• Модель: SentenceTransformer (по умолчанию fine‑tuned MPNet).
• Эмбеддинги нормализуются и индексируются в FAISS IndexFlatIP (cosine similarity).
• Поиск возвращает top_k, затем применяется порог min_score (в ассистенте по умолчанию 0.25).
• Результат — список норм с id, text, meta, score.

Ассистент (LLM)

Файл site/backend/assistant/assistant_create.py создает ассистента Azure OpenAI с:

• обязательным вызовом инструмента lexir_retrieve_constitution,
• запретом на «галлюцинации» и просьбой отвечать на языке пользователя,
• политикой «grounded only» — ответы строятся исключительно на найденных нормах корпуса.

Созданный assistant_id сохраняется в site/backend/assistant/assistant_id.txt.

Запуск (локально)

1) Подготовка окружения

python -m venv .venv
source .venv/bin/activate
pip install -r site/backend/requirements.txt

2) Переменные окружения

Минимальный набор (см. site/backend/app.py):

AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_VERSION=...
AZURE_OPENAI_ENDPOINT=...

Опционально:

ASSISTANT_ID=...                # если уже создан ассистент
AZURE_OPENAI_ASSISTANT_MODEL=...# требуется для assistant_edit.py

3) Индексы и модель

Backend ожидает:

artifacts/models/finetuned_mpnet/
artifacts/indexes/finetuned/{ru,kz}.faiss
artifacts/indexes/finetuned/{ru,kz}_meta.jsonl

Если их нет:

python data_parser/adilet_zan_parser.py
python src/train_biencoder.py
python src/build_index.py

4) Создание ассистента

python site/backend/assistant/assistant_create.py

5) Запуск веб‑приложения

uvicorn app:app --app-dir site/backend --host 0.0.0.0 --port 8000

Открыть в браузере: http://localhost:8000.

Запуск через Docker

docker compose up --build

docker-compose.yml берет переменные из site/backend/.env и прокидывает порт 8000.

CLI‑демо (без веб‑UI)

• Локальный retrieval без ассистента:

  python src/demo_cli.py
  

• Чат через ассистента (CLI):

  python site/backend/assistant/demo_assistant.py
  

Оценка качества

python src/validate.py
python src/evaluate.py
python src/plot_eval.py

Результаты: artifacts/reports/ и artifacts/reports/figures/.

Типичные ошибки

• Assistant id not found → запустить assistant_create.py или задать ASSISTANT_ID.
• Index file not found → собрать индексы через src/build_index.py.
• Fine‑tuned model directory not found → обучить src/train_biencoder.py либо собрать индексы на базовой модели.
• Azure credentials missing → проверить .env или переменные окружения.

Ограничения

• Ассистент не заменяет юридическую консультацию; ответы ограничены подключенным корпусом.
• Качество ответа зависит от релевантности retrieval‑результатов и качества корпуса.

Как заменить корпус на другой

1. Подготовить новый JSONL корпус в формате, совместимом с src/data_io.py (id/text/метаданные).
2. Обновить парсер/ETL (или загрузчик) для новых источников.
3. Переобучить bi‑encoder (src/train_biencoder.py) на новых парах «запрос → норма».
4. Пересобрать индексы (src/build_index.py) и перезапустить backend.