mirror of
https://github.com/RevLayDust/RLD-UVR-Opt.git
synced 2026-11-20 13:07:58 +09:00
157 lines
6.0 KiB
Markdown
157 lines
6.0 KiB
Markdown
# Coding Standards & Architecture Constraints
|
|
|
|
This document defines the coding standards, project invariants, and architectural anti-patterns enforced in **RLD UVR-Opt**.
|
|
|
|
---
|
|
|
|
## 1. Technical Invariants & Anti-Patterns
|
|
|
|
### A. Deferred & Lazy Imports
|
|
Heavy machine learning dependencies (`torch`, `onnxruntime`, `tensorrt_rtx`) must **not** be imported at module root level during application startup. Importing heavy DLLs during root load slows down CLI command dispatch (`uvr_cli --help`, `list-models`) and causes unnecessary cold-start latency.
|
|
|
|
#### Bad (Root-Level Eager Import)
|
|
```python
|
|
# BAD: Imported when module is evaluated, slowing CLI launch
|
|
import torch
|
|
import onnxruntime as ort
|
|
|
|
def process_audio(audio_path: str) -> None:
|
|
session = ort.InferenceSession("model.onnx")
|
|
...
|
|
```
|
|
|
|
#### Good (Deferred Local Import)
|
|
```python
|
|
# GOOD: Imports are deferred until the inference function is actually called
|
|
def process_audio(audio_path: str) -> None:
|
|
import torch
|
|
import onnxruntime as ort
|
|
from engine.tensorrt_rtx.session import create_trt_rtx_session
|
|
|
|
session = create_trt_rtx_session("model.onnx")
|
|
...
|
|
```
|
|
|
|
---
|
|
|
|
### B. Context Lock Prevention
|
|
Initializing CUDA context or calling `torch.cuda.init()` in the main thread before Execution Provider resolution locks GPU device context. This can cause ONNX Runtime providers (especially TensorRT) to fail or run into resource contention.
|
|
|
|
#### Bad (Premature CUDA Initialization)
|
|
```python
|
|
# BAD: Eagerly queries device before user or CLI arguments select EP
|
|
device = "cuda:0" if torch.cuda.is_available() else "cpu"
|
|
torch.cuda.init()
|
|
```
|
|
|
|
#### Good (Deferred Device Binding)
|
|
```python
|
|
# GOOD: Defer device context initialization until model session is instantiated
|
|
def resolve_inference_device(device_arg: str) -> str:
|
|
# Validate string argument without initializing CUDA driver context
|
|
if device_arg.startswith("cuda") or device_arg.startswith("trt_rtx"):
|
|
return device_arg
|
|
return "cpu"
|
|
```
|
|
|
|
---
|
|
|
|
### C. Pure Pipeline Decoupling
|
|
Inference routines in `separate.py`, `engine/tensorrt_rtx/`, and `uvr_cli/` must remain completely decoupled from GUI presentation widgets (Tkinter, `ttk`).
|
|
|
|
- **Forbidden**: Passing `tk.Tk`, `ttk.Progressbar`, or referencing GUI global state inside model runner functions.
|
|
- **Allowed**: Standard function signatures accepting primitive arguments (`str`, `Path`, `float`, `int`, `dict`) and reporting progress through callable callbacks:
|
|
```python
|
|
def run_separation(
|
|
audio_path: Path,
|
|
model_path: Path,
|
|
progress_callback: Optional[Callable[[float, str], None]] = None,
|
|
) -> Tuple[Dict[str, np.ndarray], bool]:
|
|
...
|
|
if progress_callback:
|
|
progress_callback(0.5, "Processing chunk 2/4...")
|
|
```
|
|
|
|
---
|
|
|
|
### D. PowerShell Invariants & Error Handling
|
|
All scripts in [install/](../../install/) must maintain strict compatibility with **Windows PowerShell 5.1**:
|
|
|
|
1. **Strict Mode**: Every `.ps1` file must begin with:
|
|
```powershell
|
|
Set-StrictMode -Version Latest
|
|
```
|
|
2. **Native Process Invocation**: Every external command (`python.exe`, `uv.exe`, `git.exe`) must verify exit codes:
|
|
```powershell
|
|
# Use the shared Invoke-Native helper or check $LASTEXITCODE explicitly
|
|
$res = Invoke-Native -FilePath 'uv.exe' -ArgumentList @('pip', 'install', '-r', $reqFile)
|
|
if (-not $res.Success) {
|
|
throw "Command failed with exit code $($res.ExitCode): $($res.StdErr)"
|
|
}
|
|
```
|
|
3. **No PS7 Syntactic Sugar**: Do not use PowerShell 7+ features:
|
|
- Ternary operator (`?:`) → use `if (...) { } else { }`.
|
|
- Null-coalescing (`??`) → use `if ($null -eq $x) { $x = ... }`.
|
|
- Pipeline chaining (`&&`, `||`) → use explicit conditional statements.
|
|
4. **Encoding**: Save PowerShell scripts as UTF-8 without BOM or ASCII.
|
|
|
|
---
|
|
|
|
### E. Installer Architectural Invariants
|
|
1. **Zero Side-Effects in Early Phases**:
|
|
- `Detect.ps1` (Phase 1), `Plan.ps1` (Phase 2), and `Verify.ps1` (Phase 3) must be strictly read-only.
|
|
- `-DryRun` must exit at Phase 3 with zero modifications to filesystem, registry, or environment.
|
|
2. **Single Source of Truth**:
|
|
- All version pins (PyTorch, ONNX Runtime, plugins, driver thresholds) must reside exclusively in [install/lib/Config.ps1](../../install/lib/Config.ps1).
|
|
3. **Additive Record Schema**:
|
|
- Changes to [install/install_record.json](../../install/install_record.json) must be purely additive to preserve backward compatibility with `install_record.py inspect-stack`.
|
|
4. **No Silent EP Fallbacks**:
|
|
- Inference sessions must explicitly inspect `session.get_providers()` and log the active provider.
|
|
|
|
---
|
|
|
|
## 2. Python Code Standards
|
|
|
|
- **Formatting**: Adhere to PEP 8 with 4-space indentation.
|
|
- **Type Annotations**: Provide type hints for public module functions and classes.
|
|
- **Logging vs Print**: In library code (`engine/`, `uvr_cli/`), use structured logging or verbose flags rather than raw `print()` statements.
|
|
- **Error Handling**: Catch specific exceptions rather than bare `except:`. Provide descriptive error messages.
|
|
|
|
---
|
|
|
|
## 3. Git Commit & Branch Conventions
|
|
|
|
### Commit Messages
|
|
We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
|
|
|
|
```text
|
|
<type>(<scope>): <short description in imperative mood>
|
|
|
|
[optional body explaining context and rationale]
|
|
|
|
[optional footer(s)]
|
|
```
|
|
|
|
#### Allowed Types:
|
|
- `feat`: A new feature (e.g., new Execution Provider, CLI flag).
|
|
- `fix`: A bug fix (e.g., resolver error, memory leak).
|
|
- `docs`: Documentation updates.
|
|
- `refactor`: Code restructuring without functional changes.
|
|
- `perf`: A code change that improves performance.
|
|
- `test`: Adding or correcting tests.
|
|
- `chore`: Maintenance tasks (release metadata, config updates).
|
|
|
|
#### Example:
|
|
```text
|
|
feat(engine): add Ampere architecture guard for TensorRT-RTX
|
|
|
|
- Check compute capability >= 8.0 via pynvml
|
|
- Fall back gracefully to CUDAExecutionProvider on Turing GPUs
|
|
- Add unit test coverage in tests/test_tensorrt_rtx.py
|
|
```
|
|
|
|
### Branch Naming
|
|
- Features: `feat/<feature-name>`
|
|
- Bugfixes: `fix/<bug-name>`
|
|
- Documentation: `docs/<doc-name>`
|