Skip to content

README.md

Latest commit

 

History

History
257 lines (179 loc) · 9.88 KB

README.md

File metadata and controls

257 lines (179 loc) · 9.88 KB
Raw

legal-rag-starter-kit

Reusable RAG core for source-grounded vertical AI assistants.
Supports hosted OpenAI-compatible APIs, local Ollama runtimes, source-aware answers, insufficient-basis mode, retrieval quality controls, and reusable evaluation workflows.

О проекте

legal-rag-starter-kit — это переиспользуемая инфраструктурная основа для построения вертикальных AI-ассистентов с Retrieval-Augmented Generation.

Проект позиционируется как starter kit / technical core, а не как готовый конечный бот под один узкий сценарий.
Ключевая идея: отделить стабильное domain-agnostic ядро (retrieval, prompting, cache, runtime orchestration) от domain-specific слоев (корпус, продуктовая логика, UX, шаблоны ответов, экспорт).

Позиционирование

Проект предназначен для команд и индивидуальных разработчиков, которым нужна надежная база для запуска вертикальных ассистентов с source-grounded ответами.

Это foundation-уровень, на котором строятся специализированные продукты:

  • ассистенты по юридическим документам;
  • ассистенты по комплаенсу;
  • ассистенты по финансам;
  • ассистенты по персональным базам знаний;
  • другие вертикальные RAG-приложения с собственными корпусами и требованиями.

Ключевые возможности ядра

  • Provider-agnostic LLM client
    • Нейтральные переменные LLM_API_KEY и LLM_BASE_URL с backward-compatible fallback.
  • Hosted + Local режимы
    • Поддержка OpenAI-compatible hosted APIs.
    • Поддержка локальных рантаймов через Ollama.
  • Source-grounded generation
    • Ответы формируются на основе retrieved context с ссылочностью на источники.
  • Insufficient-basis mode
    • Явная фиксация недостаточности данных вместо уверенных неподтвержденных выводов.
  • Language-aware prompting
    • Контроль языка и формата ответа в зависимости от языка запроса.
  • Retrieval quality pass
    • Фильтрация и компактизация контекста: cutoff + dedup + guarded fallback.
  • Кеширование
    • Кеш запросов/ответов и версия корпуса для управляемой инвалидации.
  • Переиспользуемая оценка качества
    • Подходит для системной оценки retrieval/generation в разных вертикалях.
  • Экспортно-ориентированная архитектура
    • Ядро отделено от слоев экспорта (включая PDF-пайплайны).
  • Web-first подход
    • Core не зависит от UI; web-слой остается легкой интеграцией поверх ядра.

Retrieval Quality (runtime)

В рантайме используется компактный quality pass:

  1. Raw retrieval
    Получение расширенного набора кандидатов (например, raw_top_k=10).

  2. Soft distance cutoff
    Сохранение только документов с расстоянием не выше порога (например, 0.44).

  3. Dedup по источнику и разделу
    Удаление повторов одного и того же source/section для повышения разнообразия контекста.

  4. Контролируемый fallback
    Если после фильтров остался один документ, можно добавить 1–2 лучших из хвоста.
    Если после cutoff документов нет, fallback не добавляется (чистый insufficient-basis сценарий).

  5. Final context clamp
    Ограничение итогового контекста компактным final_top_k (например, 5).

Этот подход снижает шум и дубли без перегрузки prompt лишними фрагментами.

Структура проекта

app_core/                 # переиспользуемое ядро
  config/                 # конфигурация core-уровня
  cache/                  # кеш и хранилище кеша
  evaluation/             # reusable evaluation-логика
  generation/             # prompt builder и generation helpers
  llm/                    # provider-agnostic клиентский слой
  retrieval/              # векторное хранилище и retrieval-логика
  schemas/                # схемы и структуры данных

web/                      # web-интерфейс
  templates/              # html-шаблоны
  static/                 # статические ресурсы

examples/                 # примеры запуска и конфигураций
raw_sources/              # исходные документы
knowledge_base/           # подготовленные/нормализованные материалы
scripts/                  # служебные и диагностические скрипты
runtime/                  # локальные runtime-артефакты (chroma, cache)
exporters/                # слой экспорта (например, PDF)

tests/                    # тесты

Примеры vertical-проектов поверх starter kit

  • Cross-Border Contract Risk Assistant
  • Trade Finance Legal Reference Assistant

Каждый vertical-проект может иметь собственные:

  • corpus/config слой;
  • prompt profile;
  • eval datasets;
  • product UX;
  • экспортные шаблоны и отчеты.

При этом runtime-ядро остается общим и переиспользуемым.

Локальный запуск

1) Создание и активация виртуального окружения

python -m venv venv

Windows (PowerShell):

.\venv\Scripts\Activate.ps1

Linux/macOS:

source venv/bin/activate

2) Установка зависимостей

pip install -r requirements.txt

3) Настройка окружения

Выберите профиль и скопируйте значения в .env:

  • .env.local.example — локальный Ollama-режим;
  • .env.hosted.example — hosted OpenAI-compatible режим;
  • .env.example — объединенный reference-шаблон.

4) Запуск приложения

python app.py

Режимы работы

Local Ollama mode

Пример конфигурации:

LLM_API_KEY=local-placeholder
LLM_BASE_URL=http://localhost:11434/v1
# Fast local mode:
RAG_CHAT_MODEL=gemma3:4b

# Quality local mode:
# RAG_CHAT_MODEL=deepseek-r1:8b
RAG_EMBEDDING_MODEL=bge-m3
RAG_CHROMA_PATH=runtime/chroma_db_local_bge_m3
RAG_CORPUS_VERSION=local-bge-m3-v1

Рекомендации:

  • разделяйте локальные и hosted векторные базы;
  • при смене embedding model/chunking обновляйте индекс и RAG_CORPUS_VERSION.

Hosted OpenAI-compatible mode

Пример конфигурации:

LLM_API_KEY=your-api-key
LLM_BASE_URL=https://your-openai-compatible-endpoint/v1
RAG_CHAT_MODEL=gpt-4o-mini
RAG_EMBEDDING_MODEL=text-embedding-3-small
RAG_CHROMA_PATH=runtime/chroma_db_hosted_text_embedding_3_small
RAG_CORPUS_VERSION=hosted-text-embedding-3-small-v1

Основные runtime-параметры

Retrieval quality controls:

RAG_RAW_TOP_K=10
RAG_MAX_DISTANCE=0.44
RAG_FINAL_TOP_K=5

# Legacy fallback:
# RAG_TOP_K=5

Дополнительно:

  • RAG_MAX_TOKENS
  • RAG_TEMPERATURE
  • RAG_CHUNK_SIZE
  • RAG_CHUNK_OVERLAP
  • RAG_MIN_CHUNK_LEN
  • RAG_EMBED_BATCH_SIZE

Масштабирование и дальнейшее развитие

При развитии starter kit для production-verticals логично добавить:

  • reranking поверх базового vector retrieval;
  • расширенные evaluation datasets и регрессионные quality-gates;
  • более точный source scoring и confidence сигналы;
  • улучшения web UI для прозрачности retrieval/source traceability;
  • генерацию PDF-чеклистов и структурированных отчетов;
  • multi-corpus конфигурации;
  • domain packs (корпус + prompts + eval profile) для быстрого запуска новых вертикалей.

Принцип архитектуры

Сохраняйте ядро нейтральным и переиспользуемым.
Предметную специализацию выносите в отдельные vertical-слои.

Именно это делает проект масштабируемым как инфраструктурный RAG starter kit.

Статус проекта

Проект находится в активной разработке.
Текущий фокус: стабилизация reusable core, quality controls и подготовка vertical demos поверх ядра.