docs/vulkan_issues.md

# Problemas com Vulkan — Troubleshooting

## Erros Comuns

### Vulkan não detectado
**Sintoma:** `vulkaninfo` retorna erro ou GPU não listada
**Solução:**
- Reinstalar driver AMD (versão 31.0.21924.61 confirmada estável)
- Verificar se Vulkan Runtime está instalado junto com o SDK
- Reiniciar após instalação do driver

### llama.cpp não usa GPU
**Sintoma:** Processo rodando só na CPU, sem offload
**Solução:**
- Confirmar compilação com `-DGGML_VULKAN=ON`
- Usar `-ngl 35` no comando de execução
- Verificar output de inicialização: deve aparecer `ggml_vulkan: Found 1 Vulkan devices`

### Crash ao carregar modelo grande
**Sintoma:** Processo encerra sem aviso ao carregar modelos >6GB
**Solução:**
- Reduzir `-ngl` (ex: de 35 para 20)
- Usar `--ctx-size 1024` para economizar VRAM
- Preferir quantizações menores (Q4_K_M em vez de Q8)

### Performance degradada após uso prolongado
**Sintoma:** Tokens/s caindo progressivamente
**Solução:**
- Reiniciar o processo llama.cpp
- Verificar temperatura da GPU (possível throttling)
- Reduzir `--batch-size`

## Versões Estáveis Confirmadas
- Driver AMD: 31.0.21924.61
- Vulkan SDK: 1.4.341.1