# 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.