TAO VCN Classify – Kompetenz zur Lückenanalyse

Sie sind Analyst für die Inferenzergebnisse von NVIDIA TAO VCN Classify (Visual Component Net). Ihre Aufgabe besteht darin, die schwächsten Beispiele pro Ground-Truth-Label zu identifizieren, indem Sie den vorzeichenbehafteten Abstand vom Entscheidungsschwellenwert in die falsche Richtung messen, und diese anschließend für die nachgelagerte Augmentierung oder Neuklassifizierung herauszufiltern.

Diese Funktion ist bewusst schlank gehalten. Der „Classify“-Head von VCN ist eine binäre Grenze mit einem einzigen Wert (PASS vs. NO_PASS nach siamese_score), sodass die Analyse rechnerisch und nicht untersuchend erfolgt. Die gesamte Berechnung erfolgt über einen einzigen direkten Docker-Lauf des in ` versions.yaml ` deklarierten Images ` tao_toolkit.data_services ` (Auflösung zur Laufzeit – siehe „Setup“). Der Einstiegspunkt des Containers akzeptiert „ [Hydra-Überschreibungen...]“; wir übergeben „gap_analysis vcn_aoi key=value …“. Jede Überschreibung ist ein reines Hydra -Schlüssel-Wert-Paar, das das GapAnalysisConfig -Schema des Skripts selektiv überschreibt (Standardwerte sind im Container fest integriert; Überprüfung mit ` docker run ... gap_analysis vcn_aoi --cfg=job`). (Innerhalb des Containers gibt es kein „dataset“-Schlüsselwort – dies ist das Pillar-Präfix des TAO-Launchers und wird hier weggelassen.) Sie benötigen keine delegierte Analyse, mehrphasige Image-Audits oder Clustering nach Komponententyp – VCN stellt diese Dimensionen nicht zur Verfügung. Sehen Sie sich nach der Rückkehr des Containers nur eine kleine Auswahl repräsentativer schwacher Stichproben an, um die Lücken zu qualifizieren.

Die CLI-Oberfläche kann sich zwischen den Container-Builds der Datendienste unterscheiden. Wenn ein Aufruf von `gap_analysis vcn_aoi ` bei der Argumentauswertung fehlschlägt, überprüfen Sie das tatsächliche Schema einmal pro Image mit ` docker run --rm "$DS_IMAGE" gap_analysis vcn_aoi --cfg=job das tatsächliche Schema pro Image überprüfen und etwaige umbenannte Schlüssel (z. B. `inference_csv` vs. `inference_results_dir`, `output_dir` vs. `results_dir`) abgleichen, bevor Sie es erneut versuchen. Der Name der Parquet-Ausgabedatei lautet `kpi_gaps.parquet`.

Eingaben

1. Verzeichnis mit den Versuchsergebnissen – enthält die Datei `inference/inference.csv ` aus der TAO-VCN-Classify-Inferenz. Erforderliche Spalten: `input_path`, `object_name`, `label`, `siamese_score`. Übergeben Sie das Verzeichnis (z. B. „inference/latest/“), nicht die CSV-Datei – der Container liest „inference_results_dir/inference.csv“.
2. Verzeichnis mit Trainingscode/-konfiguration – enthält die VCN-Trainings-YAML-Datei. Der Container liest daraus „dataset.classify.input_map“ (Liste der Lichtverhältnisse) und „dataset.classify.image_ext“, um jede schwache Stichprobe auf eine Zeile pro Lichtverhältnissituation zu erweitern.
3. Verzeichnis „dataset“ – dem relativen „input_path“ jeder Zeile (kpi_media_path) wird der Bildstamm vorangestellt.
4. Schema-Überschreibungen – min_recall, top_k_per_label und optional ein festgelegter Schwellenwert werden als Hydra-Überschreibungen übergeben (Standardwerte: min_recall=1,0, top_k_per_label=50, threshold=-1,0, was einen Durchlauf bedeutet). top_k_per_label muss eine positive Ganzzahl sein – wird dieser Wert weggelassen, wechselt der Container in den Modus „Filter unterhalb des Schwellenwerts“, der bei min_recall=1,0 nur PASS-Fehlklassifikationen und null NO_PASS-Zeilen zurückgibt. Siehe „Häufige Fallstricke“.

Einrichtung

Der Schwellenwert-Sweep, das Schwachstellen-Ranking und die Erweiterung pro Beleuchtung laufen alle innerhalb des in ` versions.yaml` deklarierten Images `tao_toolkit.data_services`. Ermitteln Sie die konkrete URI einmalig zu Beginn des Durchlaufs, überprüfen Sie anschließend, ob Docker, das NVIDIA-Container-Toolkit und eine GPU vorhanden sind, und stellen Sie sicher, dass das Image zwischengespeichert ist:

# „tao_toolkit.data_services“ → konkrete URI „nvcr.io/...“ aus „versions.yaml“ auflösen
DS_IMAGE=$(python3 -c "import yaml,os; print(yaml.safe_load(open(os.environ['TAO_SKILL_BANK_PATH']+'/versions.yaml'))['images']['tao_toolkit']['data_services'])")
echo "DS_IMAGE=$DS_IMAGE"

docker info > /dev/null && echo "OK: Docker"
nvidia-smi > /dev/null && echo "OK: GPU"
docker image inspect "$DS_IMAGE" > /dev/null \
  || docker pull "$DS_IMAGE"

TAO_SKILL_BANK_PATH wird in der Regel von der installierten Skill-Bank exportiert. Falls diese Variable nicht gesetzt ist, verweisen Sie sie vor der Auflösung auf das Stammverzeichnis des Skill-Bank-Repositorys. Eine GPU ist erforderlich; ein frühzeitiger Abbruch auf einem Host ohne GPU verhindert einen verwirrenden Fehler zu einem späteren Zeitpunkt.

Drei Einrichtungsregeln sind entscheidend und können leicht falsch umgesetzt werden:

• Pfad-Einbindung – jeder Host-Pfad, den der Container liest oder in den er schreibt (inference.csv, Train-YAML, Stammverzeichnis des Datensatz-Images, Ausgabeverzeichnis), muss per Bind-Mount eingebunden werden, am einfachsten mit -v $WORKSPACE:$WORKSPACE -w $WORKSPACE, damit absolute Pfade auf beiden Seiten identisch aufgelöst werden.
• Übergeben Sie nicht `--user $(id -u):$(id -g) ` – dies löst während des Imports von `transformers` durch den Container einen `KeyError: 'getpwuid(): uid not found: '` aus; stattdessen gibt `chown` anschließend die Host-UID zurück.
• -e ist erforderlich, nicht optional – aktuelle Images verlangen dies zwingend und beenden den Vorgang mit „ValueError: Die Unteraufgabe vcn_aoi benötigt das folgende Argument: -e/--experiment_spec_file“, bevor CLI-Überschreibungen geparst werden.

Siehe „references/container-setup.md“ für das vollständige Muster zur Pfad-Einbindung, die Begründung für„--user/chown“ und den Alpine- Befehl „chown“, Hinweise zu „multi--v“ sowie Details zur Anforderung „-e “.

Vorgehensweise

Die gesamte Funktion besteht aus einem einzigen Aufruf von ` docker run`, gefolgt von einer kurzen visuellen Stichprobenprüfung. Der Container führt die Schritte 1–4 intern aus (Schwellenwertdurchlauf, Schwachstellenbewertung, Top-K-Auswahl, Erweiterung pro Beleuchtung). Sie führen Schritt 5 (visuelle Stichprobenprüfung) direkt mit dem Read-Tool durch.

Schritte 1–4 – Container ausführen

$DOCKER gap_analysis vcn_aoi \
    inference_results_dir=/inference// \
    train_config=/train.yaml \
    kpi_media_path= \
    results_dir= \
    top_k_per_label=50

Übergeben Sie immer „top_k_per_label“. Dies ist das Argument, das den Container vom Standardfilter „Beispiele unterhalb des Schwellenwerts“ auf ein korrektes Top-K-per-Label- Ranking umstellt. Bei `min_recall=1.0` liegt der Schwellenwert konstruktionsbedingt bei oder unter jedem `NO_PASS`-Wert, sodass der Filter „unterhalb des Schwellenwerts“ NUR falsch klassifizierte `PASS`-Zeilen und null `NO_PASS`-Zeilen zurückgibt – als Augmentationswarteschlange somit nutzlos. Wenn „top_k_per_label“ auf eine positive Ganzzahl gesetzt ist (entweder in der Spezifikation oder als Hydra-Überschreibung), berechnet der Container für jede Zeile die signierte Schwäche im Vergleich zum Schwellenwert und liefert die K schwächsten Zeilen pro Ground-Truth-Label, was die nach Label geordnete Ausgabe darstellt, die von den nachgelagerten Schritten verarbeitet wird.

Liest „inference.csv“, durchläuft jeden eindeutigen „siamese_score“-Wert sowie einen Wert knapp unterhalb des Minimums, behält die Kandidaten mit einem „NO_PASS“-Recall ≥ „min_recall“ (mit einer Toleranz von 1e-12 ) bei und wählt dann den Schwellenwert mit dem besten F1-Wert aus (bei Gleichstand: Präzision, dann Schwellenwert). Für jede Zeile wird die vorzeichenbehaftete Schwäche ausgehend von diesem Schwellenwert berechnet (positiv = falsch klassifiziert, negativ = korrekt, Betrag = Abstand). Sortiert nach Schwäche in absteigender Reihenfolge und wählt die besten top_k_per_label pro Ground-Truth-Label aus; anschließend wird jede schwache Zeile mithilfe von dataset.classify.input_map und dataset.classify.image_ext aus der Trainings-YAML-Datei in eine Zeile pro Beleuchtungsbedingung erweitert.

Wenn kein Schwellenwertkandidat das Recall-Ziel erfüllt, beendet der Container den Vorgang mit einem Ergebnis ungleich Null und schreibt die Datei „unreachable_kpi.txt“ in das Verzeichnis „results_dir“, in der erläutert wird, welchen Recall das Modell tatsächlich erreichen kann. In diesem Fall brechen Sie die Analyse nach dem Docker-Aufruf ab, erstellen einen einteiligen Bericht, in dem erläutert wird, dass das Modell den KPI grundsätzlich an keinem Betriebspunkt erreichen kann, und empfehlen ein erneutes Training oder eine Neuklassifizierung – überspringen Sie dabei die visuelle Stichprobenprüfung.

Der Container schreibt in das Verzeichnis „results_dir“:

Geben Sie die Zusammenfassung der Standardausgabe des Containers (gewählter Schwellenwert, Anzahl der beibehaltenen Zeilen, Aufschlüsselung nach Label) in Ihre eigene Standardausgabe aus, damit der Skript-Check-Hook die vom Lauf erzeugte Ausgabe überprüfen kann.

Schritt 5 – Visuelle Stichprobenprüfung (klein, fest)

Überspringe diesen Schritt, wenn „unreachable_kpi.txt“ existiert. Andernfalls verwende das Read-Tool, um die 5 schwächsten PASS-Beispiele und die 5 schwächsten NO_PASS-Beispiele aus „kpi_gaps.parquet“ anzuzeigen (dedupliziert auf eine Zeile pro Beispiel unter Verwendung des FIRST-Lighting-Dateipfads), klassifizieren Sie jede als genau eine der Kategorien „falsch beschriftet“ / „Grenzfall“ / „Datenqualität“ / „systematisch“ und kopieren Sie jedes angezeigte Bild (auf 128×128 skaliert, falls PIL verfügbar ist, andernfalls einfach kopieren) in „/rca_images/“. Dies ist die einzige erforderliche Bildprüfung – betrachten Sie keine Dutzende von Bildern, führen Sie kein Clustering nach Fehlermodi durch und prüfen Sie keine „Golden Images“ (VCN verfügt über keine „Golden Images“).

Siehe „references/visual-spot-check.md“ für die genaue Sortierreihenfolge bei der Stichprobenauswahl, die Regel zur Duplikatsbereinigung pro Beleuchtungsbedingung, die vollständige Definition jeder Bewertungskategorie und die Details zum Kopieren der Bilder.

Aufruf des Skripts

Fügen Sie den Arbeitsbereich, die vier Pfade und die beiden numerischen Einstellparameter ein und bearbeiten Sie sie; dies führt den Test durchgängig aus. Erfassen Sie die Standardausgabe, damit der Skript-Prüf-Hook die Zeilenanzahlen erkennt.

WORKSPACE=           # wird innerhalb des Containers identisch eingebunden
EXP_DIR=     # enthält „inference/inference.csv“ und „train.yaml“; muss sich innerhalb von $WORKSPACE befinden
DATASET_ROOT=         # Bildstammverzeichnis für Einträge in „inference.csv“ unter „input_path“; muss sich innerhalb von $WORKSPACE befinden
MIN_RECALL=1.0                       # Standardwert „zero-miss“; niedriger einstellen, wenn die KPI-Anforderungen gelockert werden
TOP_K=50                             # Augmentationsbudget pro Label
OUT="$EXP_DIR/rca_results/$(date +%Y-%m-%d_%H%M%S)"
SPEC="$OUT/vcn_aoi_spec.yaml"
IMG=$(python3 -c "import yaml,os; print(yaml.safe_load(open(os.environ['TAO_SKILL_BANK_PATH']+'/versions.yaml'))['images']['tao_toolkit']['data_services'])")

mkdir -p "$OUT"

# Schreibe die Spezifikation für die Lückenanalyse für diesen Lauf
cat > "$SPEC" <<EOF
min_recall: $MIN_RECALL
top_k_per_label: $TOP_K
EOF

docker run --gpus all --rm --ipc=host \
    -v "$WORKSPACE:$WORKSPACE" -w "$WORKSPACE" \
    "$IMG" gap_analysis vcn_aoi \
    -e "$SPEC" \
    inference_results_dir="$EXP_DIR/inference/latest/" \
    train_config="$EXP_DIR/train.yaml" \
    kpi_media_path="$DATASET_ROOT" \
    results_dir="$OUT"

# Der Container schreibt als Root, wobei --user deaktiviert ist; bei Bedarf wird die Eigentümerschaft wieder auf die Host-UID zurückgesetzt.
docker run --rm -v "$WORKSPACE:/w" alpine chown -R "$(id -u):$(id -g)" "/w/$(realpath --relative-to="$WORKSPACE" "$OUT")"

# Testausgabe, damit der „script-check“-Hook echte Zahlen sieht
python3 - "$OUT" << 'PYEOF'
import json, os, sys
out = sys.argv[1]
unreachable = os.path.join(out, „unreachable_kpi.txt“)
if os.path.isfile(unreachable):
    print(„KPI UNREACHABLE — siehe“, unreachable)
    sys.exit(0)
with open(os.path.join(out, "threshold.txt")) as f:
    print("Schwellenwert:", f.read().strip())
with open(os.path.join(out, "metrics.json")) as f:
    m = json.load(f)
print(f"precision={m['precision']:.4f} recall={m['recall']:.4f} f1={m['f1']:.4f}")
import pandas as pd
df = pd.read_parquet(os.path.join(out, "kpi_gaps.parquet"))
print(f"kpi_gaps.parquet: rows={len(df)}, cols={list(df.columns)}")
print(df['label'].value_counts())
PYEOF

Ausgaben

Schreiben Sie alles in einen Ordner mit Zeitstempel im Verzeichnis für die Versuchsergebnisse. Die Ausgaben des Containers werden direkt dorthin geschrieben; die visuelle Stichprobenprüfung schreibt in den Ordner „rca_images/“; etwaige Laufzeit-Paketierungs-Hooks können nach dem Schreiben von „RCA_Report.md“ Artefakte zur Erfassung von „session/config“ hinzufügen.

/rca_results/JJJJ-MM-TT_HHMMSS/
├── RCA_Report.md              # Vollständiger Bericht zur Lückenanalyse (von Ihnen zu erstellen)
├── kpi_gaps.parquet           # Container: Top-K der schwächsten Ergebnisse pro Label, aufgeschlüsselt nach Beleuchtungsbedingungen
├── threshold.txt              # Container: gewählter Entscheidungsschwellenwert (einzelner Float-Wert)
├── metrics.json               # Container: Verwechslungsmatrix + Verteilungsstatistiken pro Label
├── weak_samples_breakdown.txt # Container: Anzahl pro Label / falsch klassifizierte / marginale Werte
├── unreachable_kpi.txt        # Container: NUR, wenn kein Schwellenwert min_recall erfüllt
├── rca_images/                # Sie: Miniaturansichten der 10 angezeigten schwachen Beispiele
├── rca_config/                # Wird automatisch per Hook kopiert
└── session log/artifacts      # Optional, laufzeitabhängige Erfassung der Paketdaten

Rufen Sie zu Beginn des Laufs den tatsächlichen Zeitstempel ab, indem Sie in Bash den Befehl „date +%Y-%m-%d_%H%M%S“ ausführen. Verwenden Sie KEINE fest codierten Werte und machen Sie keine Schätzungen. Wenn der Benutzer einen benutzerdefinierten Ausgabepfad angibt, verwenden Sie diesen stattdessen, behalten Sie jedoch die gleiche interne Struktur bei.

Häufige Fallstricke

Der schwerwiegendste Fehlermodus ist das Vergessen von „top_k_per_label“, wenn „min_recall=1.0“ gilt: Bei diesem Recall liegt der gewählte Schwellenwert bei oder unter jedem NO_PASS-Wert; ohne „top_k_per_label“ greift der Container daher auf einen Filter „Samples unterhalb des Schwellenwerts“ zurück, der NUR falsch klassifizierte PASS-Zeilen und null NO_PASS-Zeilen zurückgibt, wodurch die Augmentationswarteschlange unterbrochen wird. Fügen Sie immer einen expliziten positiven Wert für „top_k_per_label“ (Standardwert 50) in die Spezifikation oder als Hydra-Überschreibung ein.

Siehe „references/pitfalls.md“ für die vollständige Checkliste, die Folgendes abdeckt: Vergessen von „top_k_per_label“; Übergabe von „--user“; Aufruf nur mit Hydra-Überschreibungen (kein „-e “); Spezifikationsdatei außerhalb von „$WORKSPACE“; Spezifikationsdatei mit ungelösten ??? -Sentinels; Bild nicht abgerufen / falsches Tag; Nichtübereinstimmung bei der Pfad-Einbindung; „unreachable_kpi.txt“ wurde geschrieben; in „inference.csv“ fehlen erforderliche Spalten; im Trainings-YAML-File fehlen „dataset.classify.input_map“ oder „image_ext“; „kpi_media_path“ stimmt nicht mit den „input_path “-Präfixen überein; und im Container wurde keine GPU erkannt.

Struktur des Berichts

Verfassen Sie „RCA_Report.md“ als prägnante (1000–1800 Wörter) Analyse der Rechenlücken – die Tiefe ergibt sich aus genauen Zahlen und einer klaren Maßnahmenliste, nicht aus narrativen Ausführungen. Die vollständige Berichtsvorlage (7 Abschnitte: Fazit, Schwellenwertauswahl, Schwachstellenverteilung, Top-K der schwächsten Beispiele, visuelle Stichprobenprüfung, Aufschlüsselung nach Label, empfohlene Maßnahmen – einschließlich Verwechslungsmatrix und Tabellenlayouts) befindet sich in „references/output-template.md“. Wenn die Datei „unreachable_kpi.txt“ vorhanden ist, ersetzen Sie die Abschnitte 3–6 durch einen einzigen kurzen Abschnitt, in dem der Inhalt dieser Datei zitiert wird, und fassen Sie Abschnitt 7 zu einer einzigen Empfehlung zusammen: Neu trainieren oder neu beschriften.

Ausführungsreihenfolge

1. Lösen Sie DS_IMAGE aus der Datei „versions.yaml“ (images.tao_toolkit.data_services) auf und führen Sie anschließend einmalig die Befehle „docker info“, „nvidia-smi“ und „docker image inspect "$DS_IMAGE"“ (mit Abruf, falls nicht vorhanden) aus, um die Umgebung zu überprüfen. Brechen Sie den Vorgang mit einer eindeutigen Meldung ab, falls einer der Schritte fehlschlägt.
2. Führen Sie „date +%Y-%m-%d_%H%M%S“ aus, um den Zeitstempel zu erhalten; erstellen Sie „/rca_results//“.
3. Schreiben Sie „vcn_aoi_spec.yaml“ in das Verzeichnis mit dem Zeitstempel und füllen Sie dabei „min_recall“ und „top_k_per_label“ aus. Speichern Sie die Datei unter „$WORKSPACE“, damit der Pfad „-e“ innerhalb des Containers aufgelöst wird.
4. Führen Sie folgenden Befehl aus: `docker run … "$DS_IMAGE" gap_analysis vcn_aoi -e vcn_aoi_spec.yaml inference_results_dir=… train_config=… kpi_media_path=… output_dir=…`. Der Container schreibt die Dateien` kpi_gaps.parquet`, `threshold.txt`, `metrics.json` und `weak_samples_breakdown.txt ` in das Verzeichnis `results_dir`. Geben Sie den gewählten Schwellenwert und die Anzahl der beibehaltenen Zeilen auf die Standardausgabe aus, damit der „script-check“-Hook die vom Lauf erzeugte Ausgabe überprüfen kann.
5. Falls unreachable_kpi.txt vorhanden ist, überspringe Schritt 6 und schreibe den gekürzten Bericht. Andernfalls fahre fort.
6. Wähle 10 schwache Samples (die 5 schwächsten „PASS“ + die 5 schwächsten „NO_PASS“) aus „kpi_gaps.parquet“ aus, zeige jedes Testbild mit „Read“ an, klassifiziere es und kopiere es jeweils in „rca_images/“.
7. Schreiben Sie „RCA_Report.md“ zuletzt – das Schreiben löst den Packaging-Hook aus, der die Sitzungsprotokolle und die Skill-Konfiguration mitkopiert.