Initial SQL-only 1C adapter baseline

docs/runbooks/q6-lora-troubleshooting.md

@@ -0,0 +1,151 @@
+# Q6 LoRA Troubleshooting
+
+Цель: короткая памятка по типовым проблемам при обучении, конвертации и публикации `Qwen3-Coder Q6` с LoRA.
+
+## Main Rule
+
+На `docker-gpu` training/download контейнеры должны видеть код из `Z:\LLM\model-chat-app`, а не напрямую из `Z:\codex\LLM`.
+
+Актуальный поток такой:
+
+1. локальный репозиторий архивируется;
+2. архив синхронизируется в `Z:\LLM\model-chat-app`;
+3. training/download контейнеры используют этот каталог как `/workspace` или `/app`.
+
+Если новые `scripts`, `plugins` или `registry/model-cards` не попали в `model-chat-app`, контейнеры будут работать на старом коде.
+
+## Quick Checks
+
+Проверить GPU host:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/check_gpu_host.ps1 -SshTarget docker-gpu
+```
+
+Показать план полного пайплайна:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/train_and_publish_q6_lora.ps1 -PlanOnly
+```
+
+Прогнать только безопасный preflight:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/train_and_publish_q6_lora.ps1 -SkipDownload -SkipTrain -SkipConvert -SkipRestart -SkipSmoke
+```
+
+## Common Failures
+
+### `Model card not found for id qwen3-coder-30b-a3b-instruct`
+
+Причина:
+
+- контейнер загрузки стартовал раньше, чем новый `model card` попал в `Z:\LLM\model-chat-app`.
+
+Что делать:
+
+```powershell
+. .\scripts\app_archive.ps1
+$archive = New-AppArchive
+Test-AppArchive -Archive $archive
+Sync-AppDirectory -SshTarget docker-gpu -RemoteArchive 'C:\ProgramData\LLM\model-chat-app.zip' -RemoteAppDir 'Z:\LLM\model-chat-app' -Archive $archive
+docker -H ssh://docker-gpu rm -f llm-hf-range-qwen3-coder-base
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\download_hf_range_gpu.ps1 -CardId qwen3-coder-30b-a3b-instruct -LocalDir /models/base/qwen3-coder-30b-a3b-instruct -Detached -ContainerName llm-hf-range-qwen3-coder-base
+```
+
+### `requirements-training.txt` not found
+
+Причина:
+
+- training container смонтировал неправильный workspace path.
+
+Правильное ожидание:
+
+- `HOST_WORKSPACE_DIR=Z:/LLM/model-chat-app`
+- wrapper `scripts/run_1c_lora_training_gpu.ps1` сам синхронизирует текущий код в `model-chat-app` перед `docker compose up`.
+
+### `base model is incomplete at /models/base/qwen3-coder-30b-a3b-instruct`
+
+Причина:
+
+- HF-база еще не скачана полностью.
+
+Что смотреть:
+
+```powershell
+docker -H ssh://docker-gpu logs -f llm-hf-range-qwen3-coder-base
+docker -H ssh://docker-gpu run --rm -v Z:/LLM/models:/models alpine sh -lc "ls -lah /models/base/qwen3-coder-30b-a3b-instruct"
+```
+
+Хороший признак:
+
+- в логе идут строки `OK <filename>`
+- появились все `model-00001-of-00016.safetensors` ... `model-00016-of-00016.safetensors`
+
+### `CUDA out of memory`
+
+Причина:
+
+- слишком тяжелая конфигурация для текущего режима RTX 4090.
+
+Что делать:
+
+- остановить лишние тяжелые сервисы;
+- убедиться, что активен только нужный training/runtime контур;
+- при необходимости уменьшить training нагрузку в `plugins/1c/training/configs/qwen3-coder-30b-a3b-lora.yaml`.
+
+### `llama.cpp` стартовал без адаптера
+
+Причина:
+
+- не передан `-LoraPath`
+- `.gguf` адаптер не был создан
+- опубликован не тот путь
+
+Проверка:
+
+```powershell
+docker -H ssh://docker-gpu run --rm -v Z:/LLM/models:/models alpine sh -lc "ls -lah /models/adapters/1c/qwen3-coder-30b-a3b-1c-lora-v1.gguf"
+powershell -ExecutionPolicy Bypass -File scripts\manage_gpu_q6_service.ps1 -Action status -LoraPath /models/adapters/1c/qwen3-coder-30b-a3b-1c-lora-v1.gguf
+```
+
+## Monitoring Commands
+
+Скачивание базы:
+
+```powershell
+docker -H ssh://docker-gpu logs -f llm-hf-range-qwen3-coder-base
+```
+
+Обучение:
+
+```powershell
+docker -H ssh://docker-gpu logs -f llm-train-1c-lora
+```
+
+Q6 runtime:
+
+```powershell
+docker -H ssh://docker-gpu logs -f llm-llama-qwen3-coder-q6-test
+```
+
+Endpoint check:
+
+```powershell
+python scripts\check_inference_endpoint.py --base-url http://docker-gpu.cin.su:8081 --expected-model qwen3-coder-1c-q6 --print
+```
+
+Smoke eval:
+
+```powershell
+python scripts\run_1c_smoke_eval.py --base-url http://docker-gpu.cin.su:8081 --model qwen3-coder-1c-q6
+```
+
+## Recommended Order
+
+1. Дождаться полной загрузки HF-базы.
+2. Прогнать `PreflightOnly`.
+3. Запустить обучение.
+4. Конвертировать LoRA в GGUF.
+5. Перезапустить `Q6` с `-LoraPath`.
+6. Прогнать endpoint check и smoke eval.