File size: 4,847 Bytes
6d35aff | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 | # Environment and APE build
Orienter has two runtime layers. The lightweight manifest, provider, and evaluation utilities use the root `requirements.txt`. Stage 2 additionally needs PyTorch, CUDA, Detectron2, detrex, and the compiled `ape._C` extension.
## Public starting point
Use Python 3.10 or later for the public environment. This is required by the current Pillow security release; the historical Python 3.9 environment is recorded below for provenance, not recommended for processing untrusted images.
For lightweight utilities:
```bash
python -B -m venv .venv
source .venv/bin/activate
python -B -m pip install --upgrade pip
python -B -m pip install -r requirements.txt
```
For the CUDA detector, `environment.reference.yml` is a compatibility starting point based on the verified experiment host, with Python and Pillow moved to currently supported public versions:
```bash
conda env create -f environment.reference.yml
conda activate orienter-ape-reference
bash scripts/build_ape_extension.sh
```
The environment file pins PyTorch 2.2.0 with CUDA 12.1 and the exact Detectron2 and detrex commits observed in the working server environment. It deliberately builds the vendored APE source after environment creation instead of redistributing a machine-specific binary. It is not a cross-platform lockfile or a security attestation for the older research stack. Audit the resolved environment on the publication host. The target machine needs a CUDA toolkit compatible with its PyTorch build, a supported C++ compiler, and enough memory/disk to compile the extension.
`scripts/build_ape_extension.sh` does not install or upgrade dependencies. It performs an editable build of the vendored APE source in the active environment, then runs the environment checker. Review the active environment before executing it.
## Verify the runtime
From the repository root:
```bash
python -B scripts/check_environment.py
python -B scripts/verify_assets.py --repo-root . --hash-checkpoint
python -B scripts/smoke_control_path.py
python scripts/run_tests.py
```
The environment check fails if the detector dependency stack is unavailable. `--allow-no-cuda` relaxes only the CUDA-availability check, and `--skip-ape-extension` relaxes only the compiled `ape._C` check; both remain diagnostic flags and still require PyTorch, torchvision, Detectron2, and detrex. They do not turn this command into a checker for the lightweight root requirements, and they are not valid evidence for Stage 2 inference readiness.
After mounting screenshots and application metadata, validate their contracts before a live run:
```bash
python -B scripts/verify_assets.py \
--repo-root . \
--questions /absolute/path/to/questions.jsonl \
--images-dir /absolute/path/to/images \
--app-metadata-cache /absolute/path/to/app_metadata.json
```
To reproduce semantic evaluation offline, separately mount the frozen cache and verify its full SHA-256:
```bash
python -B scripts/verify_assets.py \
--repo-root . \
--skip-checkpoint \
--embedding-cache /absolute/path/to/embedding_dict.json
```
## Verified historical server environment
The release checkpoint, one-image APE smoke test, and test suite were exercised in the historical server `conda` environment named `ape` with:
| Component | Observed version |
| --- | --- |
| Python | 3.9.18 |
| PyTorch | 2.2.0+cu121 |
| torchvision | 0.17.0+cu121 |
| CUDA runtime reported by PyTorch | 12.1 |
| CUDA toolkit (`nvcc`) | 12.2 |
| NVIDIA driver | 535.261.03 |
| GPU | NVIDIA A100-PCIE-40GB |
| GCC | 11.4.0 |
| Detectron2 | 0.6, commit `017abbfa5f2c2a2afa045200c2af9ccf2fc6227f` |
| detrex | 0.3.0, commit `776058ec229be37a5ff2a2b0bb54133bdd5da663` |
| transformers | 4.37.2 |
| NumPy | 1.22.4 |
| SciPy | 1.7.3 |
| Pillow | 10.2.0 |
| OpenCV Python | 4.9.0.80 |
| xformers | 0.0.24 |
| fairscale | 0.4.13 |
| lvis | 0.5.3 |
`torch.cuda.is_available()` returned `True`, and `ape._C` imported successfully when invoked from the Orienter repository root. Running Python from inside `approach/ovod/APE` before building the local extension can shadow the installed APE package with the unbuilt source tree; build first and run the public entrypoints from the Orienter root.
The historical environment includes an old Pillow version and is retained only as execution provenance. Do not use it for arbitrary or untrusted images. A fresh build of `environment.reference.yml` on the final Hugging Face target remains part of the release gate because compiled CUDA extensions are host-sensitive.
## Files that must stay local
Do not commit compiled extensions, `build/`, `*.egg-info`, model caches, virtual/conda environments, logs, generated candidates or predictions, or configuration files containing credentials or private absolute paths. Re-run the release hygiene tests after every live validation.
|