# Utiliser les conversions

[Français](USAGE.md) · [English](USAGE.en.md)

## 1. Choisir la variante

Consulter [la matrice](BENCHMARKS.md). Un graphe d’inférence et sa variante `_learning` sont distincts. Les bundles multi-graphes exigent tous les composants, processeurs et tokeniseurs du `pipeline.json`. Ne pas renommer un seul composant pour simuler un modèle complet. Les poids sont téléchargés séparément de l’APK.

## 2. Épingler et vérifier

Python 3.11+ et `huggingface_hub` sont nécessaires à cet exemple. Si un accès est requis, utiliser `hf auth login` ; aucun identifiant secret dans le code ou la documentation. Télécharger une révision immuable puis contrôler chaque entrée du manifeste :

```python
from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="fireviewer/litert-models",
    revision="330e9097409042751988e9fa5994b51ac2b577bc",
    allow_patterns=["models/fireviewer_dfine_m_strict_v1_learning/*"],
    local_dir="model-checkout",
)
```

Le contrôle suivant porte sur le dossier téléchargé ci-dessus.

```python
from pathlib import Path
import hashlib, json

folder = Path("model-checkout/models/fireviewer_dfine_m_strict_v1_learning")  # choose the downloaded folder
for name, expected in json.loads((folder / "artifact_manifest.json").read_text(encoding="utf-8")).items():
    path = (folder / name).resolve()
    assert path.is_relative_to(folder.resolve())
    assert path.stat().st_size == expected["bytes"]
    with path.open("rb") as stream:
        assert hashlib.file_digest(stream, "sha256").hexdigest() == expected["sha256"]
```

Le manifeste couvre aussi les configurations : conserver leurs octets. Un nouveau hash de poids exige une nouvelle qualification. Licences, notices et restrictions des modèles sources restent indépendantes d’Apache-2.0 pour l’application.

## 3. Respecter le contrat

Lire `runtime_contract.json` et `android_model_config.json` lorsqu’ils existent ; les anciennes variantes/bundles utilisent `config.json`, `pipeline.json` et le rapport de conversion. Respecter dtype, disposition NCHW/NHWC, RGB/BGR, normalisation, bornes/pas, ordre des classes et décodeur. Le prétraitement d’une famille n’est pas transférable à une autre. Redimensionner les masques au plus proche voisin et conserver la transformation de coordonnées vers l’image originale. Une entrée externe dynamique peut être redimensionnée dans le graphe vers un encodeur figé de taille fixe.

Dans Vision Dataset Studio, ouvrir **Modèles**, configurer la source HF autorisée, télécharger/importer la variante et son contrat, puis inspecter et essayer une image avant un lot. Le parcours manuel fonctionne sans modèle. Un adaptateur présent dans le code ne valide pas toutes les conversions.

## 4. Runtime et apprentissage

Le SDK autonome/conversion utilise `org.tensorflow:tensorflow-lite:2.16.1` et `org.tensorflow:tensorflow-lite-select-tf-ops:2.16.1`. La campagne applicative du 22 septembre utilise séparément LiteRT 1.4.2 + Select TF Ops 2.16.1. La rc5 du 23 septembre utilise Flex 2.16.1-vds16k1 reconstruit pour les pages 16 Ko ; sa suite de base 4/16 Ko ne remplace pas un retest de toutes les conversions. [Détails du correctif](https://github.com/unicornwhodev/vision-dataset-studio/blob/65e4620/docs/FLEX_16K.md). Ces environnements ne sont pas des garanties interchangeables. CPU, XNNPACK désactivé pour le graphe d’apprentissage, Flex pour les checkpoints ; GPU/NPU et téléphone ARM non qualifiés ici.

Les signatures réelles `train`, `infer`, `save`, `restore` et leurs noms d’entrées/sorties doivent correspondre au contrat. Les cibles suivent `targetEncoding`, formes et classes ; une annotation absente n’est pas un exemple négatif. L’application ne prend pas en charge les entrées texte d’apprentissage. Seules les têtes/adaptations sont mutables ; tous les encodeurs visuels fournis sont figés. Les adaptations de détection ne créent pas de propositions absentes du détecteur figé. Changer le nombre de classes impose de reconstruire la tête.

## 5. Cycle du lot dans l’application

Importer → préannoter si activé → corriger/valider manuellement → exporter et vérifier la relecture → apprentissage facultatif du lot exporté → nettoyage confirmé → lot suivant. L’apprentissage est désactivé par défaut et s’exécute sur Android. Il utilise uniquement les images acceptées de ce lot ; rejets et autres lots sont exclus. Le nettoyage attend sa fin et son évaluation ; interruption/erreur conservent les données. Activation des nouveaux poids manuelle. Le premier entraînement conserve l’original et crée une version séparée ; les suivants poursuivent ses derniers poids validés, même avant activation. [Versions et checkpoints](CONTINUOUS_LEARNING.md).

Les checkpoints conservent paramètres, moments et étape. Conserver aussi les hashes modèle/classes, provenance du dataset et exemples de rejeu/contrôle. Une restauration réussie ne prouve pas la généralisation. L’application exige au moins 32 images d’apprentissage et 8 de contrôle après partage déterministe. Les empreintes persistantes par projet survivent au nettoyage et excluent les copies exactes de fichiers/pixels ; elles ne couvrent pas tous les quasi-doublons retouchés.

## 6. Reproduire les contrôles Android

Utiliser [les outils de recette de l’application](https://github.com/unicornwhodev/vision-dataset-studio/tree/65e4620/tools/qa) sur un appareil dédié et avec les APK vérifiées. `fetch_model_fixtures.py` télécharge les fixtures épinglées hors APK et vérifie les manifestes. `qualify_converted_models.py` exécute chaque variante et consigne build, hashes et verdict Android. Consulter `--help` pour fournir chemins des modèles/preuves et numéro de l’appareil. La variable de consentement est `VDS_ALLOW_TEST_INSTALL=1`. Aucun entraînement automatique d’un corpus utilisateur ; conserver échecs et délais dépassés. Aucun optimiseur hôte dans ce chemin de test applicatif.

## Diagnostic

- Hash incorrect : arrêter, vérifier la révision et retélécharger le fichier concerné.
- Opération Flex/Save/Restore absente : contrôler runtime CPU et signatures.
- Forme/pas incompatible : vérifier formes et décodeur ; le défaut applicatif RTMDet sans apprentissage a été corrigé et son retest du 22 septembre est réussi.
- Perte non finie ou checkpoint incompatible : conserver les données et restaurer une génération compatible vérifiée.
- Émulateur logiciel lent : preuve fonctionnelle uniquement, aucune déduction de vitesse sur téléphone.

Lire [les résultats et limites](BENCHMARKS.md) avant utilisation.

[FireViewer Kotlin SDK / SDK Kotlin FireViewer](../android/README.md) includes detector target construction and DINOv3 four-task supervision. Its standalone test is separate from application integration.