# Local LLM Platform

Локальная платформа для работы с моделями под разные задачи: текст, перевод, аудио, видео и 1С.

Архитектура проекта: `core + plugins`.

- `core` содержит общую платформу: реестр моделей, инференс, обучение, eval-тесты, деплой на GPU, хранилище и мониторинг.
- `plugins` содержит прикладные направления: текст, перевод, аудио, видео, фото, 1С.
- Каждый плагин проектируется как будущий отдельный сервис, но на старте живет в одном репозитории.

## Deployment Target

GPU-нагрузки разворачиваются на `docker-gpu.cin.su`.

Секреты, токены, пароли, ключи доступа и приватные датасеты не хранятся в репозитории.

Если `docker-gpu.cin.su` является Windows-хостом с контейнерами на диске `Z:`, используйте runbook `docs/runbooks/windows-docker-gpu-host.md`.

## Structure

```text
LLM/
  core/
    registry/
    inference/
    training/
    evals/
    deploy/
    storage/
    monitoring/

  registry/
    model-cards/
    templates/

  datasets/
    raw/
    prepared/

  plugins/
    text/
    translation/
    audio/
    video/
    image/
    1c/

  docs/
```

## Development Stages

1. Описать реестр моделей и формат model card.
2. Поднять базовый inference API для текстовых моделей.
3. Добавить плагины задач и их минимальные пайплайны.
4. Для 1С сначала сделать RAG и инструменты работы с метаданными.
5. После накопления качественных примеров добавить LoRA/adapter fine-tuning для 1С.
6. Тяжелые плагины постепенно выносить в отдельные контейнеры или сервисы.

## First Inference

Шаблон первого GPU inference-сервиса находится в `core/deploy/docker-gpu/vllm`.

Runbook: `docs/runbooks/first-vllm-inference.md`.
Deployment runbook: `docs/runbooks/deploy-vllm.md`.
GPU preflight: `docs/runbooks/gpu-host-preflight.md`.

Полный GPU-контур после настройки SSH-доступа:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/deploy_gpu_stack.ps1 -Pull
```

Посмотреть план без запуска:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/deploy_gpu_stack.ps1 -PlanOnly -Pull
```

Первая базовая текстовая модель: `Qwen/Qwen3-4B-Instruct-2507`.

Первая GGUF-модель для 1С/code экспериментов: `bartowski/mistralai_Devstral-Small-2-24B-Instruct-2512-GGUF`, quant `Q4_K_M`.

Исследование следующих кандидатов под 1С: `docs/research/1c-model-candidates.md`.

Набор моделей по одному кандидату на каждый плагин: `plugins/model-bundle.yaml`.

Загрузка набора:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/download_plugin_model_bundle.ps1
```

Проверка model cards:

```powershell
python scripts/validate_model_cards.py
```

Все базовые локальные проверки:

```powershell
python scripts/check_all.py
```

Проверка локального хранилища моделей:

```powershell
python scripts/check_model_storage.py --print
```

Сводный статус платформы:

```powershell
python scripts/collect_platform_status.py --print
```

Список моделей:

```powershell
python scripts/list_model_cards.py
```

Загрузка модели в локальное хранилище:

```powershell
python scripts/download_hf_model.py qwen3-4b-instruct-2507 --dry-run
```

Runbook: `docs/runbooks/download-model.md`.

Чат для ручной проверки моделей:

```powershell
python scripts/model_chat_server.py
```

Runbook: `docs/runbooks/model-chat-testbench.md`.

## 1C RAG

Стартовый контур 1С находится в `plugins/1c`.

Подготовка RAG-корпуса:

```powershell
python scripts/build_1c_knowledge_base.py
```

Отдельные шаги, если нужно управлять ими вручную:

```powershell
python scripts/prepare_1c_rag_corpus.py
```

Построение локального lexical index:

```powershell
python scripts/build_1c_rag_index.py
```

Построение локального SQLite vector index:

```powershell
python scripts/build_1c_rag_vector_index.py
python scripts/search_1c_rag_hybrid.py "реквизиты справочника номенклатура" --profile metadata --limit 5
```

Сборка 1С RAG prompt:

```powershell
python scripts/ask_1c_rag.py "Какие реквизиты есть у справочника Номенклатура?" --print-prompt
```

Runbook: `docs/runbooks/1c-rag.md`.

Проверка 1С-плагина:

```powershell
python scripts/check_1c_plugin.py --print
```

Контур безопасного взаимодействия с живыми базами 1С: `docs/runbooks/1c-live-interaction.md`.

Проверка offline/static контура верификации 1С-адаптера:

```powershell
python scripts/check_1c_adapter_verification_stack.py --base-id upo_test
```

Для нестандартных endpoint'ов добавьте `--rest-adapter-url ... --mcp-url ...`;
по умолчанию проверяются текущие стендовые URL. Несколько баз можно передать
после одного `--base-id`. Чтобы принимать только свежие persisted-отчеты,
добавьте `--max-report-age-seconds <seconds>`.
Persisted validation also checks
`reports/1c-sql/<base-id>/saved-state-copy-plan.json`: the plan must be for
the requested base, be `plan_ready`, contain active `Config`/`ConfigCAS` source
rows, and show no `ConfigSave`/`ConfigCASSave` target collisions.
PowerShell deploy/verify defaults saved-state preparation to `ConfigCASSave`;
pass `-SavedStateTable ConfigSave` when checking the base save layer instead.

Сохранить машинно-читаемый итог этой проверки:

```powershell
python scripts/check_1c_adapter_verification_stack.py --base-id upo_test --json --report reports/1c-sql/upo_test/adapter-verification-stack-check.json
```

Metadata snapshots:

```powershell
python scripts/validate_1c_metadata_snapshot.py plugins/1c/metadata/examples/metadata.example.json
python scripts/convert_1c_metadata_to_rag.py --input plugins/1c/metadata/examples/metadata.example.json --output plugins/1c/rag/sources/metadata.example.generated.md
```

Runbook: `docs/runbooks/1c-metadata-snapshot.md`.

## 1C Training Data

Проверка и подготовка синтетического training example:

```powershell
python scripts/validate_1c_training_data.py plugins/1c/training/examples/instruction.examples.jsonl
python scripts/prepare_1c_training_data.py --input plugins/1c/training/examples/instruction.examples.jsonl --output plugins/1c/training/prepared/train.chat.jsonl
```

Runbook: `docs/runbooks/1c-training-data.md`.

LoRA training:

```powershell
python scripts/preflight_1c_training.py
```

Runbook: `docs/runbooks/1c-lora-training.md`.

## Evals

Проверка eval-наборов:

```powershell
python scripts/validate_evals.py
python scripts/run_1c_smoke_eval.py --print
```

Runbook: `docs/runbooks/evals.md`.