---
license: other
language:
  - ru
  - kk
tags:
  - legal
  - semantic-search
  - retrieval
  - faiss
  - sentence-transformers
  - fastapi
  - openai
pipeline_tag: sentence-similarity
---

# 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 корпус (в демо — Конституция РК как пример). Каждая строка:

```json
{
  "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) Подготовка окружения

```bash
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
```

Если их нет:

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

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

```bash
python site/backend/assistant/assistant_create.py
```

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

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

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

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

```bash
docker compose up --build
```

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

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

- Локальный retrieval без ассистента:
  ```bash
  python src/demo_cli.py
  ```
- Чат через ассистента (CLI):
  ```bash
  python site/backend/assistant/demo_assistant.py
  ```

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

```bash
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.