mirror of
https://github.com/yakhyo/uniface.git
synced 2026-05-15 12:57:55 +00:00
13c4ac83d8
* fix: Fix installation conflict between onnxruntime and onnxruntime-gpu * fix: Fix CI, notebooks, type hints, and packaging issues found in audit * feat: Add new release config * ci: Automate release pipeline and document release process
306 lines
6.4 KiB
Markdown
306 lines
6.4 KiB
Markdown
# Installation
|
|
|
|
This guide covers all installation options for UniFace.
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
- **Python**: 3.10 or higher
|
|
- **Operating Systems**: macOS, Linux, Windows
|
|
|
|
---
|
|
|
|
## Why Two Extras?
|
|
|
|
`onnxruntime` (CPU) and `onnxruntime-gpu` (CUDA) both own the same Python namespace.
|
|
Installing both at the same time causes file conflicts and silent provider mismatches.
|
|
UniFace exposes them as separate, mutually exclusive extras so you install exactly one.
|
|
|
|
---
|
|
|
|
## Quick Install
|
|
|
|
=== "CPU / Apple Silicon"
|
|
|
|
```bash
|
|
pip install uniface[cpu]
|
|
```
|
|
|
|
=== "NVIDIA GPU (CUDA)"
|
|
|
|
```bash
|
|
pip install uniface[gpu]
|
|
```
|
|
|
|
---
|
|
|
|
## Platform-Specific Installation
|
|
|
|
### macOS (Apple Silicon - M1/M2/M3/M4)
|
|
|
|
The `[cpu]` extra pulls in the standard `onnxruntime` package, which has native ARM64 support
|
|
built in since version 1.13. No additional setup is needed for CoreML acceleration.
|
|
|
|
```bash
|
|
pip install uniface[cpu]
|
|
```
|
|
|
|
!!! tip "Native Performance"
|
|
`onnxruntime` 1.13+ includes ARM64 optimizations out of the box.
|
|
UniFace automatically detects and enables `CoreMLExecutionProvider` on Apple Silicon.
|
|
|
|
Verify ARM64 installation:
|
|
|
|
```bash
|
|
python -c "import platform; print(platform.machine())"
|
|
# Should show: arm64
|
|
```
|
|
|
|
---
|
|
|
|
### Linux/Windows with NVIDIA GPU
|
|
|
|
```bash
|
|
pip install uniface[gpu]
|
|
```
|
|
|
|
This installs `onnxruntime-gpu`, which includes both `CUDAExecutionProvider` and
|
|
`CPUExecutionProvider` — no separate CPU package is needed.
|
|
|
|
**Requirements:**
|
|
|
|
- NVIDIA driver compatible with your CUDA version
|
|
- CUDA 11.x or 12.x toolkit
|
|
- cuDNN 8.x
|
|
|
|
!!! info "CUDA Compatibility"
|
|
See the [ONNX Runtime GPU compatibility matrix](https://onnxruntime.ai/docs/execution-providers/CUDA-ExecutionProvider.html)
|
|
for matching CUDA and cuDNN versions.
|
|
|
|
Verify GPU installation:
|
|
|
|
```python
|
|
import onnxruntime as ort
|
|
print("Available providers:", ort.get_available_providers())
|
|
# Should include: 'CUDAExecutionProvider'
|
|
```
|
|
|
|
---
|
|
|
|
### CPU-Only (All Platforms)
|
|
|
|
```bash
|
|
pip install uniface[cpu]
|
|
```
|
|
|
|
Works on all platforms with automatic CPU fallback.
|
|
|
|
---
|
|
|
|
## Install from Source
|
|
|
|
For development or the latest features:
|
|
|
|
```bash
|
|
git clone https://github.com/yakhyo/uniface.git
|
|
cd uniface
|
|
|
|
pip install -e ".[cpu]" # CPU / Apple Silicon
|
|
pip install -e ".[gpu]" # NVIDIA GPU
|
|
```
|
|
|
|
With development dependencies:
|
|
|
|
```bash
|
|
pip install -e ".[cpu,dev]"
|
|
```
|
|
|
|
---
|
|
|
|
## FAISS Vector Store
|
|
|
|
For fast multi-identity face search using a FAISS vector store:
|
|
|
|
```bash
|
|
pip install faiss-cpu # CPU
|
|
pip install faiss-gpu # NVIDIA GPU (CUDA)
|
|
```
|
|
|
|
See the [Stores module](modules/stores.md) for usage.
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
|
|
UniFace has minimal core dependencies:
|
|
|
|
| Package | Purpose |
|
|
|---------|---------|
|
|
| `numpy` | Array operations |
|
|
| `opencv-python` | Image processing |
|
|
| `scikit-image` | Geometric transforms |
|
|
| `scipy` | Signal processing |
|
|
| `requests` | Model download |
|
|
| `tqdm` | Progress bars |
|
|
|
|
**Runtime extras (install exactly one):**
|
|
|
|
| Extra | Package | Use case |
|
|
|-------|---------|---------|
|
|
| `uniface[cpu]` | `onnxruntime` | CPU inference, Apple Silicon |
|
|
| `uniface[gpu]` | `onnxruntime-gpu` | NVIDIA CUDA inference |
|
|
|
|
**Other optional packages:**
|
|
|
|
| Package | Install | Purpose |
|
|
|---------|---------|---------|
|
|
| `faiss-cpu` / `faiss-gpu` | `pip install faiss-cpu` | FAISS vector store |
|
|
| `torch` | `pip install torch` | Emotion model (TorchScript) |
|
|
| `torchvision` | `pip install torchvision` | Faster NMS for YOLO detectors |
|
|
|
|
---
|
|
|
|
## Verify Installation
|
|
|
|
Test your installation:
|
|
|
|
```python
|
|
import uniface
|
|
print(f"UniFace version: {uniface.__version__}")
|
|
|
|
# Check available ONNX providers
|
|
import onnxruntime as ort
|
|
print(f"Available providers: {ort.get_available_providers()}")
|
|
|
|
# Quick test
|
|
from uniface.detection import RetinaFace
|
|
detector = RetinaFace()
|
|
print("Installation successful!")
|
|
```
|
|
|
|
---
|
|
|
|
## Upgrading
|
|
|
|
When upgrading UniFace, stay consistent with your runtime extra:
|
|
|
|
```bash
|
|
pip install --upgrade uniface[cpu] # or uniface[gpu]
|
|
```
|
|
|
|
If you are switching from CPU to GPU (or vice versa):
|
|
|
|
```bash
|
|
pip uninstall onnxruntime onnxruntime-gpu -y
|
|
pip install uniface[gpu] # install the one you want
|
|
```
|
|
|
|
---
|
|
|
|
## Pre-release Versions
|
|
|
|
UniFace ships release candidates and betas to PyPI ahead of stable releases (versions like `0.7.0rc1`, `0.7.0b1`, `0.7.0a1`). These let you try upcoming features before they're finalized.
|
|
|
|
`pip install uniface` always installs the latest **stable** release. To opt in to pre-releases:
|
|
|
|
```bash
|
|
# Latest pre-release (if newer than latest stable)
|
|
pip install uniface[cpu] --pre
|
|
|
|
# A specific pre-release
|
|
pip install uniface[cpu]==0.7.0rc1
|
|
```
|
|
|
|
Pre-releases are not recommended for production — APIs may still change before the stable release.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### onnxruntime Not Found
|
|
|
|
If you see:
|
|
|
|
```
|
|
ImportError: onnxruntime is not installed. Install it with one of:
|
|
pip install uniface[cpu] # CPU / Apple Silicon
|
|
pip install uniface[gpu] # NVIDIA GPU (CUDA)
|
|
```
|
|
|
|
You installed uniface without an extra. Run the appropriate command above.
|
|
|
|
---
|
|
|
|
### Both onnxruntime and onnxruntime-gpu Installed
|
|
|
|
If you previously ran `pip install uniface[gpu]` on top of a `pip install uniface[cpu]`
|
|
(or vice versa), you may have both packages installed simultaneously, which causes conflicts.
|
|
Fix it with:
|
|
|
|
```bash
|
|
pip uninstall onnxruntime onnxruntime-gpu -y
|
|
pip install uniface[gpu] # or uniface[cpu]
|
|
```
|
|
|
|
---
|
|
|
|
### Import Errors
|
|
|
|
Ensure you're using Python 3.10+:
|
|
|
|
```bash
|
|
python --version
|
|
# Should show: Python 3.10.x or higher
|
|
```
|
|
|
|
---
|
|
|
|
### Model Download Issues
|
|
|
|
Models are automatically downloaded on first use. If downloads fail:
|
|
|
|
```python
|
|
from uniface.model_store import verify_model_weights
|
|
from uniface.constants import RetinaFaceWeights
|
|
|
|
# Manually download a model
|
|
model_path = verify_model_weights(RetinaFaceWeights.MNET_V2)
|
|
print(f"Model downloaded to: {model_path}")
|
|
```
|
|
|
|
---
|
|
|
|
### CUDA Not Detected
|
|
|
|
1. Verify CUDA installation:
|
|
```bash
|
|
nvidia-smi
|
|
```
|
|
|
|
2. Check CUDA version compatibility with ONNX Runtime.
|
|
|
|
3. Reinstall the GPU extra cleanly:
|
|
```bash
|
|
pip uninstall onnxruntime onnxruntime-gpu -y
|
|
pip install uniface[gpu]
|
|
```
|
|
|
|
---
|
|
|
|
### Performance Issues on Mac
|
|
|
|
Verify you're using the ARM64 build (not x86_64 via Rosetta):
|
|
|
|
```bash
|
|
python -c "import platform; print(platform.machine())"
|
|
# Should show: arm64 (not x86_64)
|
|
```
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
- [Quickstart Guide](quickstart.md) - Get started in 5 minutes
|
|
- [Execution Providers](concepts/execution-providers.md) - Hardware acceleration setup
|