Add model and runtime guidance documentation set.

Made-with: Cursor
2026-04-20 23:13:00 +10:00
parent bf1fd5e77d
commit d67fdb0791
6 changed files with 218 additions and 0 deletions
@@ -360,3 +360,8 @@ chmod +x script.sh
 - Работа с GitHub/GitLab/Gitea: `docs/openclaude-with-repositories.md`
 - Примеры cron-автоматизации: `docs/cron-examples.md`
 - Автоустановка cron: `scripts/install-cron.sh`
+- Каталог моделей: `docs/model-catalog.md`
+- Выбор runtime: `docs/runtime-choice.md`
+- Локальный Cursor-like стек: `docs/cursor-like-stack.md`
+- Честные ожидания: `docs/expectations.md`
+- Шаблон benchmark: `docs/bench-template.md`
@@ -0,0 +1,47 @@
+# Benchmark template for local coding models
+
+Шаблон, чтобы сравнивать модели не "по ощущениям", а по одинаковым задачам.
+
+## 1) Набор тест-кейсов
+
+Соберите 15-30 задач из реального проекта:
+
+- bugfix (small)
+- bugfix (cross-file)
+- рефакторинг модуля
+- добавление тестов
+- объяснение сложного участка
+- генерация migration/SQL
+
+## 2) Метрики
+
+- **Latency to first token**
+- **Decode speed (tok/s)**
+- **Время до зелёных тестов**
+- **Число итераций правок**
+- **Процент задач "с первого прогона"**
+- **Субъективная читаемость кода (1-5)**
+
+## 3) Таблица фиксации результатов
+
+| Модель | Runtime | tok/s | Time-to-green | Iterations | Pass rate | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| qwen2.5-coder:7b | Ollama |  |  |  |  |  |
+| qwen2.5-coder:14b | Ollama |  |  |  |  |  |
+| deepseek-coder:* | Ollama/vLLM |  |  |  |  |  |
+
+## 4) Регламент сравнения
+
+1. Использовать одинаковый prompt-шаблон.
+2. Одинаковый контекст/набор файлов.
+3. Одинаковый набор тест-команд.
+4. Запускать минимум 2 повтора на каждую задачу.
+5. Фиксировать дату, железо, версию модели.
+
+## 5) Критерий "принять в прод-профиль"
+
+Новая модель переводится в default, если:
+
+- не хуже текущей по pass rate
+- не хуже по time-to-green на ключевых задачах
+- нет регрессий в критичных сценариях (миграции, тесты, multi-file edits)
@@ -0,0 +1,35 @@
+# Cursor-like local stack
+
+Как собрать локальный стек, близкий по опыту к Cursor.
+
+## 1) Компоненты
+
+| Компонент | Роль |
+| --- | --- |
+| Ollama | Локальный запуск моделей + API |
+| OpenClaude | Агентный CLI-поток (tools, edit, bash, MCP) |
+| Continue (VS Code/JetBrains) | Автодополнение/чат прямо в IDE |
+| Aider | Терминальный AI pair-programmer для git-циклов |
+| Open WebUI (опционально) | Веб-чат и быстрый доступ для команды |
+
+## 2) Базовая схема запуска
+
+1. Поднять `Ollama`.
+2. Выбрать coding-модель (`qwen2.5-coder:7b` как старт).
+3. Подключить OpenClaude к локальному endpoint.
+4. Установить Continue в IDE для inline/autocomplete.
+5. Для batch/refactor задач использовать Aider.
+6. Для знаний проекта подключить RAG через MCP.
+
+## 3) Где какой инструмент использовать
+
+- **IDE coding flow**: Continue
+- **Agent loop с инструментами и автоматизацией**: OpenClaude
+- **Быстрые массовые правки в repo**: Aider
+- **Командный веб-доступ**: Open WebUI
+
+## 4) Честные ограничения
+
+- Локальный стек не всегда повторяет облачный агент 1-в-1.
+- Для сильной автономности нужны дополнительные оркестраторы и настройки.
+- Качество сильно зависит от выбранной модели и регулярного benchmark-сравнения.
@@ -0,0 +1,28 @@
+# Expectations: cloud vs local
+
+Ориентиры, чтобы заранее понимать компромиссы.
+
+| Параметр | Облачный стек | Локальный стек (условно 7B-14B) |
+| --- | --- | --- |
+| Качество "из коробки" | Обычно выше и стабильнее | Может быть очень хорошим, но требует настройки |
+| Контекст | Часто больше | Зависит от модели/рантайма |
+| Автономность агента | Часто готова сразу | Требует сборки инструментов/MCP |
+| Приватность | Код уходит во внешний сервис | Код остается у вас |
+| Скорость | Обычно стабильно высокая | Зависит от GPU/VRAM/нагрузки |
+| Стоимость | Подписка/usage | Железо + электричество + админка |
+
+## Практический вывод
+
+- Для приватных данных и контроля инфраструктуры локальный стек очень выгоден.
+- Для "сложных нажатий на кнопку" и максимального качества иногда удобен гибрид:
+  - локально для повседневных задач
+  - облако для особо сложных multi-step кейсов.
+
+## Реалистичная цель
+
+Не "скопировать 1-в-1", а собрать надежный рабочий процесс:
+
+- быстрый локальный baseline
+- понятный pipeline обновлений
+- benchmark на ваших задачах
+- fallback-профиль на случай деградации модели
@@ -0,0 +1,41 @@
+# Model catalog for coding
+
+Практический каталог моделей для code-задач в локальном и гибридном сценарии.
+
+> Важно: "лучшая модель" зависит от языка проекта, длины контекста, формата задач и вашего железа.
+
+## 1) Рекомендуемые семейства
+
+| Модель | Класс | Сильные стороны | Когда брать | Пример формата |
+| --- | --- | --- | --- | --- |
+| Qwen2.5-Coder | 7B / 14B / 32B | Сильный coding baseline, хорошая универсальность | Python/JS/TS/Go/Rust, код-ревью, рефакторинг | Ollama, GGUF, GPTQ/EXL2 |
+| DeepSeek-Coder (V2 / distill) | 16B+ / MoE варианты | Часто сильная логика в code reasoning | Сложные задачи и агентные цепочки, если есть ресурсы | Ollama/HF квантизованные |
+| Codestral (Mistral) | ~22B класс | Хороший автокомплит и редактирование | IDE-автодополнение и правки среднего размера | GGUF/GPTQ |
+| StarCoder2 | ~15B класс | Стабильная альтернатива для инлайна | Нужен второй/резервный профиль | GGUF/Ollama сборки |
+
+## 2) Где брать
+
+- **Самый простой путь:** `ollama pull <model:tag>`
+- **Гибкий путь:** Hugging Face (квантизованные сборки, ручной контроль формата)
+
+Популярные издатели квантизованных сборок на HF:
+
+- `bartowski`
+- `MaziyarPanahi`
+- `TheBloke`
+
+## 3) Рекомендуемые стартовые профили
+
+- **weak-server**: `qwen2.5:3b`
+- **balanced**: `qwen2.5-coder:7b`
+- **quality**: `qwen2.5-coder:14b` (или аналог) при наличии достаточного GPU VRAM
+
+## 4) Практика выбора
+
+1. Начните с одной быстрой и одной "качественной" модели.
+2. Прогоните одинаковый benchmark-набор задач.
+3. Сравните:
+   - токены/сек
+   - количество правок до прохождения тестов
+   - число ошибок в multi-file изменениях
+4. Зафиксируйте победителя как default-профиль.
@@ -0,0 +1,62 @@
+# Runtime choice: Ollama vs vLLM vs llama.cpp
+
+Как выбрать движок запуска моделей.
+
+## Ollama
+
+Когда подходит лучше всего:
+
+- быстрый старт
+- локальная разработка
+- минимум настройки
+- поддержка многих моделей в одном интерфейсе
+
+Плюсы:
+
+- простая установка
+- единый API-слой
+- удобные команды `pull/list/run`
+
+Минусы:
+
+- меньше тонкой оптимизации, чем в специализированных production-схемах
+
+## vLLM
+
+Когда подходит:
+
+- высокая нагрузка
+- production API
+- нужны throughput/батчинг и эффективная работа GPU
+
+Плюсы:
+
+- высокая производительность под серверные сценарии
+- хорошие возможности масштабирования
+
+Минусы:
+
+- выше порог настройки и эксплуатации
+
+## llama.cpp
+
+Когда подходит:
+
+- CPU-only/edge сценарии
+- очень тонкий контроль квантизации и runtime-параметров
+- lightweight деплой
+
+Плюсы:
+
+- гибкость и широкий набор форматов/опций
+- хороший вариант для слабых или нестандартных машин
+
+Минусы:
+
+- больше ручной настройки по сравнению с Ollama
+
+## Практическая рекомендация
+
+- Стартуйте с **Ollama**.
+- Если уперлись в нагрузку/latency в проде - переходите на **vLLM**.
+- Если нужен максимальный контроль в CPU/edge - добавляйте **llama.cpp**.