better Readme structure
This commit is contained in:
seko2521
338
docs/TROUBLESHOOTING.md
Normal file
338
docs/TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# Troubleshooting Guide
|
||||
|
||||
This guide covers common issues and their solutions when using WanGP.
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### PyTorch Installation Problems
|
||||
|
||||
#### CUDA Version Mismatch
|
||||
**Problem**: PyTorch can't detect GPU or CUDA errors
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check your CUDA version
|
||||
nvidia-smi
|
||||
|
||||
# Install matching PyTorch version
|
||||
# For CUDA 12.4 (RTX 10XX-40XX)
|
||||
pip install torch==2.6.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/test/cu124
|
||||
|
||||
# For CUDA 12.8 (RTX 50XX)
|
||||
pip install torch==2.7.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/test/cu128
|
||||
```
|
||||
|
||||
#### Python Version Issues
|
||||
**Problem**: Package compatibility errors
|
||||
**Solution**: Ensure you're using Python 3.10.9
|
||||
```bash
|
||||
python --version # Should show 3.10.9
|
||||
conda create -n wan2gp python=3.10.9
|
||||
```
|
||||
|
||||
### Dependency Installation Failures
|
||||
|
||||
#### Triton Installation (Windows)
|
||||
**Problem**: `pip install triton-windows` fails
|
||||
**Solution**:
|
||||
1. Update pip: `pip install --upgrade pip`
|
||||
2. Try pre-compiled wheel
|
||||
3. Fallback to SDPA attention: `python wgp.py --attention sdpa`
|
||||
|
||||
#### SageAttention Compilation Issues
|
||||
**Problem**: SageAttention installation fails
|
||||
**Solution**:
|
||||
1. Install Visual Studio Build Tools (Windows)
|
||||
2. Use pre-compiled wheels when available
|
||||
3. Fallback to basic attention modes
|
||||
|
||||
## Memory Issues
|
||||
|
||||
### CUDA Out of Memory
|
||||
|
||||
#### During Model Loading
|
||||
**Problem**: "CUDA out of memory" when loading model
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Use smaller model
|
||||
python wgp.py --t2v-1-3B
|
||||
|
||||
# Enable quantization (usually default)
|
||||
python wgp.py --quantize-transformer True
|
||||
|
||||
# Use memory-efficient profile
|
||||
python wgp.py --profile 4
|
||||
|
||||
# Reduce preloaded model size
|
||||
python wgp.py --preload 0
|
||||
```
|
||||
|
||||
#### During Video Generation
|
||||
**Problem**: Memory error during generation
|
||||
**Solutions**:
|
||||
1. Reduce frame count (shorter videos)
|
||||
2. Lower resolution in advanced settings
|
||||
3. Use lower batch size
|
||||
4. Clear GPU cache between generations
|
||||
|
||||
### System RAM Issues
|
||||
|
||||
#### High RAM Usage
|
||||
**Problem**: System runs out of RAM
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Limit reserved memory
|
||||
python wgp.py --perc-reserved-mem-max 0.3
|
||||
|
||||
# Use minimal RAM profile
|
||||
python wgp.py --profile 5
|
||||
|
||||
# Enable swap file (OS level)
|
||||
```
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Slow Generation Speed
|
||||
|
||||
#### General Optimization
|
||||
```bash
|
||||
# Enable compilation (requires Triton)
|
||||
python wgp.py --compile
|
||||
|
||||
# Use faster attention
|
||||
python wgp.py --attention sage2
|
||||
|
||||
# Enable TeaCache
|
||||
python wgp.py --teacache 2.0
|
||||
|
||||
# Use high-performance profile
|
||||
python wgp.py --profile 3
|
||||
```
|
||||
|
||||
#### GPU-Specific Optimizations
|
||||
|
||||
**RTX 10XX/20XX Series**:
|
||||
```bash
|
||||
python wgp.py --attention sdpa --profile 4 --teacache 1.5
|
||||
```
|
||||
|
||||
**RTX 30XX/40XX Series**:
|
||||
```bash
|
||||
python wgp.py --compile --attention sage --profile 3 --teacache 2.0
|
||||
```
|
||||
|
||||
**RTX 50XX Series**:
|
||||
```bash
|
||||
python wgp.py --attention sage --profile 4 --fp16
|
||||
```
|
||||
|
||||
### Attention Mechanism Issues
|
||||
|
||||
#### Sage Attention Not Working
|
||||
**Problem**: Sage attention fails to compile or work
|
||||
**Diagnostic Steps**:
|
||||
1. Check Triton installation:
|
||||
```python
|
||||
import triton
|
||||
print(triton.__version__)
|
||||
```
|
||||
2. Clear Triton cache:
|
||||
```bash
|
||||
# Windows
|
||||
rmdir /s %USERPROFILE%\.triton
|
||||
# Linux
|
||||
rm -rf ~/.triton
|
||||
```
|
||||
3. Fallback solution:
|
||||
```bash
|
||||
python wgp.py --attention sdpa
|
||||
```
|
||||
|
||||
#### Flash Attention Issues
|
||||
**Problem**: Flash attention compilation fails
|
||||
**Solution**:
|
||||
- Windows: Often requires manual CUDA kernel compilation
|
||||
- Linux: Usually works with `pip install flash-attn`
|
||||
- Fallback: Use Sage or SDPA attention
|
||||
|
||||
## Model-Specific Issues
|
||||
|
||||
### Lora Problems
|
||||
|
||||
#### Loras Not Loading
|
||||
**Problem**: Loras don't appear in the interface
|
||||
**Solutions**:
|
||||
1. Check file format (should be .safetensors, .pt, or .pth)
|
||||
2. Verify correct directory:
|
||||
```
|
||||
loras/ # For t2v models
|
||||
loras_i2v/ # For i2v models
|
||||
loras_hunyuan/ # For Hunyuan models
|
||||
```
|
||||
3. Click "Refresh" button in interface
|
||||
4. Use `--check-loras` to filter incompatible files
|
||||
|
||||
#### Lora Compatibility Issues
|
||||
**Problem**: Lora causes errors or poor results
|
||||
**Solutions**:
|
||||
1. Check model size compatibility (1.3B vs 14B)
|
||||
2. Verify lora was trained for your model type
|
||||
3. Try different multiplier values
|
||||
4. Use `--check-loras` flag to auto-filter
|
||||
|
||||
### VACE-Specific Issues
|
||||
|
||||
#### Poor VACE Results
|
||||
**Problem**: VACE generates poor quality or unexpected results
|
||||
**Solutions**:
|
||||
1. Enable Skip Layer Guidance
|
||||
2. Use detailed prompts describing all elements
|
||||
3. Ensure proper mask creation with Matanyone
|
||||
4. Check reference image quality
|
||||
5. Use at least 15 steps, preferably 30+
|
||||
|
||||
#### Matanyone Tool Issues
|
||||
**Problem**: Mask creation difficulties
|
||||
**Solutions**:
|
||||
1. Use negative point prompts to refine selection
|
||||
2. Create multiple sub-masks and combine them
|
||||
3. Try different background removal options
|
||||
4. Ensure sufficient contrast in source video
|
||||
|
||||
## Network and Server Issues
|
||||
|
||||
### Gradio Interface Problems
|
||||
|
||||
#### Port Already in Use
|
||||
**Problem**: "Port 7860 is already in use"
|
||||
**Solution**:
|
||||
```bash
|
||||
# Use different port
|
||||
python wgp.py --server-port 7861
|
||||
|
||||
# Or kill existing process
|
||||
# Windows
|
||||
netstat -ano | findstr :7860
|
||||
taskkill /PID <PID> /F
|
||||
|
||||
# Linux
|
||||
lsof -i :7860
|
||||
kill <PID>
|
||||
```
|
||||
|
||||
#### Interface Not Loading
|
||||
**Problem**: Browser shows "connection refused"
|
||||
**Solutions**:
|
||||
1. Check if server started successfully
|
||||
2. Try `http://127.0.0.1:7860` instead of `localhost:7860`
|
||||
3. Disable firewall temporarily
|
||||
4. Use `--listen` flag for network access
|
||||
|
||||
### Remote Access Issues
|
||||
|
||||
#### Sharing Not Working
|
||||
**Problem**: `--share` flag doesn't create public URL
|
||||
**Solutions**:
|
||||
1. Check internet connection
|
||||
2. Try different network
|
||||
3. Use `--listen` with port forwarding
|
||||
4. Check firewall settings
|
||||
|
||||
## Quality Issues
|
||||
|
||||
### Poor Video Quality
|
||||
|
||||
#### General Quality Improvements
|
||||
1. Increase number of steps (25-30+)
|
||||
2. Use larger models (14B instead of 1.3B)
|
||||
3. Enable Skip Layer Guidance
|
||||
4. Improve prompt descriptions
|
||||
5. Use higher resolution settings
|
||||
|
||||
#### Specific Quality Issues
|
||||
|
||||
**Blurry Videos**:
|
||||
- Increase steps
|
||||
- Check source image quality (i2v)
|
||||
- Reduce TeaCache multiplier
|
||||
- Use higher guidance scale
|
||||
|
||||
**Inconsistent Motion**:
|
||||
- Use longer overlap in sliding windows
|
||||
- Reduce window size
|
||||
- Improve prompt consistency
|
||||
- Check control video quality (VACE)
|
||||
|
||||
**Color Issues**:
|
||||
- Check model compatibility
|
||||
- Adjust guidance scale
|
||||
- Verify input image color space
|
||||
- Try different VAE settings
|
||||
|
||||
## Advanced Debugging
|
||||
|
||||
### Enable Verbose Output
|
||||
```bash
|
||||
# Maximum verbosity
|
||||
python wgp.py --verbose 2
|
||||
|
||||
# Check lora compatibility
|
||||
python wgp.py --check-loras --verbose 2
|
||||
```
|
||||
|
||||
### Memory Debugging
|
||||
```bash
|
||||
# Monitor GPU memory
|
||||
nvidia-smi -l 1
|
||||
|
||||
# Reduce memory usage
|
||||
python wgp.py --profile 4 --perc-reserved-mem-max 0.2
|
||||
```
|
||||
|
||||
### Performance Profiling
|
||||
```bash
|
||||
# Test different configurations
|
||||
python wgp.py --attention sdpa --profile 4 # Baseline
|
||||
python wgp.py --attention sage --profile 3 # Performance
|
||||
python wgp.py --compile --teacache 2.0 # Maximum speed
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Before Asking for Help
|
||||
1. Check this troubleshooting guide
|
||||
2. Read the relevant documentation:
|
||||
- [Installation Guide](INSTALLATION.md)
|
||||
- [Getting Started](GETTING_STARTED.md)
|
||||
- [Command Line Reference](CLI.md)
|
||||
3. Try basic fallback configuration:
|
||||
```bash
|
||||
python wgp.py --attention sdpa --profile 4
|
||||
```
|
||||
|
||||
### Community Support
|
||||
- **Discord Server**: https://discord.gg/g7efUW9jGV
|
||||
- Provide relevant information:
|
||||
- GPU model and VRAM amount
|
||||
- Python and PyTorch versions
|
||||
- Complete error messages
|
||||
- Command used to launch WanGP
|
||||
- Operating system
|
||||
|
||||
### Reporting Bugs
|
||||
When reporting issues:
|
||||
1. Include system specifications
|
||||
2. Provide complete error logs
|
||||
3. List the exact steps to reproduce
|
||||
4. Mention any modifications to default settings
|
||||
5. Include command line arguments used
|
||||
|
||||
## Emergency Fallback
|
||||
|
||||
If nothing works, try this minimal configuration:
|
||||
```bash
|
||||
# Absolute minimum setup
|
||||
python wgp.py --t2v-1-3B --attention sdpa --profile 4 --teacache 0 --fp16
|
||||
|
||||
# If that fails, check basic PyTorch installation
|
||||
python -c "import torch; print(torch.cuda.is_available())"
|
||||
```
|
||||
Reference in New Issue
Block a user