Перейти к содержимому
RAGRAF

Конфигурация корпуса: каждый ключ с пояснением

Полный разбор YAML-конфига: проект, отбор файлов, секреты, эмбеддинги, индексы, Joern, пороги переиндексации и валидация.

Минимальный рабочий конфиг #

YAML
project: myproject
root: C:/path/to/your/project
languages: [python, javascript, markdown]
include: ["**/*.py", "**/*.js", "**/*.md"]
exclude: ["**/node_modules/**", "**/build/**"]

ragraf init <каталог> создаёт конфиг сам — с разумными дефолтами и комментариями. Всё остальное ниже — опционально, но стоит понимания.

Секция secrets — безопасность по умолчанию #

YAML
secrets_exclude:            # не индексируются и не читаются ВОВСЕ
  - "**/.env"
  - "**/.env.*"
  - "**/*.pem"
  - "**/*.key"
  - "**/secrets/**"

Это исключение, а не маскировка: файлы не открываются на чтение ни на одной стадии — ни скан, ни чанки, ни векторы, ни логи. Проверка протоколом M3-T2 на образцах-приманках (файл с маркером внутри secrets_exclude обязан отсутствовать во всех трёх хранилищах).

Эмбеддинги #

YAML
embedding:
  model: sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
  dim: 384
  batch_size: 64
  device: auto              # auto | cpu | cuda — см. статью о GPU

Модель скачивается один раз (~240 МБ) в ~/.ragraf/models (переопределяется RAGRAF_MODEL_CACHE). Мультиязычная MiniLM выбрана потому, что корпуса и запросы смешанные (код + русский/английский в docblocks и запросах агента). dim обязан соответствовать модели — несовпадение ловится на старте индексации, а не в ответах.

Индексация #

YAML
index:
  retain_revs: 3            # сколько ревизий хранить (архивы журнала не в счёт)
  chunk_budget: 8000        # токен-бюджет чанка; превышение режет чанк
  reindex_on_drift: warn    # warn | auto | fail
  full_reindex_threshold: 0.35   # доля изменённых файлов → полная пересборка
  fast_reindex_threshold: 0.05   # доля → быстрая пересборка затронутых

Правило валидации: full > fast обязательно (нарушение — ошибка конфига на старте, а не странное поведение потом). Пороги работают от доли файлов, чей sha256 разошёлся: до fast — точечная пересборка затронутых чанков (эмбеддинги неизменённых переиспользуются по chunk_sha256), между порогами — стандартная, выше full — полная (обычно дешевле, чем тысяча точечных).

Реальные ориентиры: на 323-файловом корпусе полная индексация — 71 с (из них CPG 64 с); переиспользование эмбеддингов делает точечную пересборку единицами секунд.

Joern (опциональный CPG-слой) #

YAML
index:
  joern_enabled: true
  joern_heap_gb: 8          # или RAGRAF_JOERN_HEAP_GB

Без Joern/JDK 21 индексация не падает: capability=degraded, slice отказывает с причиной, остальное работает. Подробности — в статье о CPG-слое.

Схема БД #

YAML
schema:
  migrations: ["migrations/*.sql"]   # glob относительно root
  dsn_from: config/database.php      # индексировать ФАКТ ссылки на конфиг, без значений

information_schema используется read-only, если DSN разрешён окружением; иначе схема берётся только из миграций. Значения секретов из конфигов в индекс не попадают в любом случае.

Телеметрия #

YAML
telemetry:
  enabled: true             # журнал usage_call локально; ничего не уходит наружу
  arg_digest_chars: 60      # дайджест аргумента вместо полного текста

Журнал — основа usage_stats и панели; аргументы хранятся как sha1 + дайджест, полные тексты запросов — никогда.

Валидация и отладка #

Конфиг проверяется на старте каждой команды: неизвестные ключи — предупреждение (не ошибка: форвард-совместимость), несовместимые типы — ошибка с указанием ключа. Панель администратора пишет изменения проектных конфигов с валидацией и .bak-копией. Быстрая диагностика живого конфига:

Shell
ragraf -p config/mycorpus.yaml status      # ревизия, capability, размеры, дрейф
ragraf -p config/mycorpus.yaml selftest    # окружение: 9+2 компонента

Смежное: GPU-вычисления → · CPG/Joern → · первый запуск →