DEFT-Fähigkeit „Mining and Embedding“

Sie sind der Betreiber des DEFT-Workflows „Embed-then-Mine“ für VCN-AOI. Ihre Aufgabe besteht darin, ein Parquet aus schwachen Zielbildern (die Ausgabe der Lückenanalyse oder des Routings) und einen Quellpool zu nehmen und daraus ein dedupliziertes Parquet aus extrahierten Quellbildern zu erstellen, die den Zielbildern ähneln – bereit für die nächste Trainingsrunde.

Der Workflow ist fest vorgegeben und deterministisch: Einbetten der Zielbilder, Einbetten des Quellpools, anschließend Mining der nächsten Nachbarn. Das Parquet-Ergebnis jedes Schritts dient als Eingabe für den nächsten Schritt. Es gibt keine iterative Suche, keinen Clustering-Durchlauf und keine „Human-in-the-Loop“-Auswahl – die Tiefe entsteht durch die Wahl des richtigen Encoders und des richtigen „topn“, nicht durch eine mehrphasige Untersuchung.

Die gesamte Funktion ist eine schlanke Hülle um drei direkte „docker run“-Aufrufe für das in „versions.yaml“ deklarierte Image „tao_toolkit.data_services“ (wird zur Laufzeit aufgelöst – siehe „Setup“). Der Einstiegspunkt des Containers akzeptiert „ -e [Hydra-Überschreibungen...] “ – wobei „image_embeddings -e …“ für die Einbettung und „tmm nearest_neighbors -e …“ für das Mining übergeben werden. Das Flag -e verweist auf eine YAML-Datei, die Standardwerte für das Schema der Teilaufgabe bereitstellt; alles, was danach folgt, ist eine reine Hydra-Überschreibung (Schlüssel=Wert), die bestimmte Felder der Spezifikation pro Lauf selektiv überschreibt. (Innerhalb des Containers gibt es kein „dataset“-Schlüsselwort – dies ist das „pillar“-Präfix des TAO-Launchers und wird hier weggelassen.) Laden Sie das Image einmal herunter, falls es nicht zwischengespeichert ist: docker pull "$DS_IMAGE" (nach Auflösung von $DS_IMAGE gemäß der Einrichtung).

Schema-Schlüssel können zwischen den Releases von Data-Services umbenannt werden (beim RCA-Skill lautete „inference_csv“ → „inference_results_dir“ und „output_dir“ → „results_dir“). Im Zweifelsfall sollten Sie das tatsächliche Schema einmal pro Image überprüfen: docker run --rm "$DS_IMAGE" embedding image_embeddings --cfg=job und ... tmm nearest_neighbors --cfg=job.

Eingaben

1. Ziel-Parquet-Datei – die Ausgabe der Lückenanalyse, typischerweise `mining_gaps.parquet ` aus ` tao-route-visual-changenet-samples ` (oder `gaps.parquet ` aus ` tao-analyze-gaps-visual-changenet `, falls das Routing übersprungen wurde). Erforderliche Spalte: filepath. Ist auch die Spalte „label“ vorhanden, ist eine labelbasierte Filterung während des Mining-Vorgangs möglich; andernfalls ignoriert die Mining-Aufgabe den Filter stillschweigend.
2. Quellpool – ein Parquet-Datensatz mit Kandidatenbildern, die ausgewertet werden sollen, mit einer Spalte „filepath “. Falls der Benutzer nur über eine CSV-Datei verfügt, muss diese vor Schritt 2 in ein Parquet mit denselben Spalten konvertiert werden. Für die label-bewusste Filterung muss der Pool außerdem eine Spalte „label“ enthalten.
3. Einbettungsspezifikationsdatei – eine YAML-Datei, die „model“, „model_path“, „batch_size“ und (nur wenn „model_path“ ein TAO -„.pth“/.„.ckpt“ ist) „model_config_path“ enthält. Wird in den Schritten 1 und 2 wiederverwendet;„input_parquet“ und „output_parquet“ werden pro Durchlauf als Hydra-Überschreibungen bereitgestellt. Für beide Einbettungsschritte MUSS dieselbe Spezifikation verwendet werden – Einbettungen aus unterschiedlichen Encodern sind nicht vergleichbar, und nicht aufeinander abgestimmte Encoder sind die häufigste Ursache für Meldungen wie „Die extrahierten Bilder scheinen nichts miteinander zu tun zu haben“.
4. Mining-Spezifikationsdatei – eine YAML-Datei, die topn, knn_metric, filter_by_label sowie (selten geänderte)source_embed_column_name/target_embed_column_name enthält.source_parquet/target_parquet/output_parquet sind Hydra-Überschreibungen zur Laufzeit. SigLIP- und CLIP-Einbettungen sollten „knn_metric: cosine“ verwenden. Wenn „filter_by_label: true“ ist, aber in einer der beiden Einbettungs-Parquet-Dateien eine Label -Spalte fehlt, protokolliert der Container eine Warnung und fährt ohne Filterung fort.

Einrichtung

Lösen Sie die konkrete URI „tao_toolkit.data_services“ aus der Datei „versions.yaml“ einmalig zu Beginn des Laufs auf und stellen Sie anschließend sicher, dass Docker, das NVIDIA-Container-Toolkit und eine GPU vorhanden sind, bevor Sie weitere Schritte unternehmen. Eine GPU ist sowohl für den Vorwärtsdurchlauf des Encoders als auch für die cuML/cuDF-k-NN-Suche erforderlich; beide Schritte schlagen ohne CUDA fehl.

# „tao_toolkit.data_services“ → konkrete „nvcr.io/...“-URI 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"

Jeder Host-Pfad, den der Container liest oder in den er schreibt, muss per Bind-Mount eingebunden werden. Der am besten vorhersehbare Ansatz besteht darin, das Stammverzeichnis des Arbeitsbereichs so einzubinden, dass die Pfade innerhalb und außerhalb des Containers identisch sind, und dann einen $DOCKER- Alias für die drei Aufrufe wiederzuverwenden:

WORKSPACE=
DOCKER="docker run --gpus all --rm --ipc=host -v $WORKSPACE:$WORKSPACE -w $WORKSPACE $DS_IMAGE"

Übergeben Sie nicht --user $(id -u):$(id -g) – dies löst während des Imports der Transformatoren einen getpwuid() -KeyError aus, noch bevor die eigentliche Arbeit beginnt. Der Container läuft als Root; chown setzt die UID anschließend wieder auf die des Hosts zurück.

Erstellen Sie die beiden Spec-Dateien einmal pro Iteration und legen Sie sie unter $WORKSPACE ab, damit das Argument -e auf beiden Seiten der Einbindung aufgelöst wird; lauffspezifische Werte bleiben aus der Spec heraus und werden als Hydra-Überschreibungen übergeben. Wenn es sich bei dem Quellpool um eine CSV-Datei handelt, konvertieren Sie diese vorab in das Parquet-Format (unter Beibehaltung des Dateipfads und gegebenenfalls des Labels ). Die Standarddatei `embedding_spec.yaml ` verwendet `model: SigLIP`, `model_path: google/siglip-base-patch16-224`, `batch_size: 64`; die Standarddatei „mining_spec.yaml“ verwendet „topn: 5“, „knn_metric: cosine“, „filter_by_label: ‚false‘“ (in Anführungszeichen – das Schema liest dies als Zeichenkette).

Siehe „references/setup.md“ für die vollständigen Hinweise zur Umgebung, den Umgang mit TAO_SKILL_BANK_PATH, die Gründe für das Einbinden von Pfaden, den Workaround für „getpwuid chown“, den Ausschnitt zur Konvertierung von CSV in Parquet sowie die wörtlichen Abschnitte zur Erstellung der Spezifikationsdateien.

Vorgehensweise

Drei Befehle in der angegebenen Reihenfolge. Die Parquet-Ausgabe jedes Befehls dient als Eingabe für den nächsten Befehl. Führen Sie sie als einfache Bash-Befehle aus; der Alias $DOCKER aus dem Setup kümmert sich um den Container, die GPU und die Einbindungen. Jeder Aufruf folgt dem gleichen Schema: -e für die fest integrierten Standardwerte, gefolgt von einer Handvoll Hydra-Überschreibungen für die lauffallspezifischen Pfade.

Schritt 1 – Einbetten der Ziel-Images

$DOCKER embedding image_embeddings \
    -e  \
    input_parquet= \
    output_parquet=

Liest die Ausgabe der Lückenanalyse/des Routings und schreibt eine Parquet-Datei mit dem Dateipfad, der Einbettung und allen zusätzlichen Metadatenspalten (z. B. „label“, „siamese_score“, „weakness“), die wortwörtlich aus der Eingabe übernommen werden. Gibt das Ausgabeschema (pd.read_parquet(...).columns) auf die Standardausgabe aus, damit der „script-check“-Hook überprüfen kann, ob die Einbettungsspalte vorhanden ist.

Wenn Sie „model“, „model_path“ oder „batch_size“ für einen Durchlauf überschreiben müssen, ohne die Spezifikation zu bearbeiten, fügen Sie diese als Hydra-Überschreibungen an (z. B. „model_path=...“).

Schritt 2 – Einbetten des Quellpools

$DOCKER embedding image_embeddings \
    -e  \
    input_parquet= \
    output_parquet=

Gleiche Befehlsstruktur wie in Schritt 1, angewendet auf den Quellpool. Verwenden Sie dieselbe `embedding_spec.yaml ` wie in Schritt 1 und überschreiben Sie hier die Parameter `model`, `model_path` und `batch_size` nicht anders – nicht übereinstimmende Encoder-Konfigurationen in den beiden Schritten führen zu nicht vergleichbaren Einbettungen.

Schritt 3 – Nächstgelegene Nachbarn ermitteln

$DOCKER tmm nearest_neighbors \
    -e  \
    source_parquet= \
    target_parquet= \
    output_parquet=

Für jede Ziel-Einbettung werden die topn nächstgelegenen Quell-Einbettungen gemäß der gewählten Metrik ermittelt, über alle Ziele hinweg dedupliziert und in einer einspaltigen (Dateipfad-)Parquet-Datei mit eindeutigen, extrahierten Quellpfaden gespeichert. Der Container legt außerdem neben der Parquet-Ausgabedatei eine Datei „mining_summary.txt“ ab, die folgende Angaben enthält: Anzahl der Abfragen, Anzahl der Nachbarn, Anzahl der entfernten Duplikate sowie (bei aktivierter Label-Filterung) die Anzahl der beibehaltenen und verworfenen Paare. Passen Sie „topn“, „knn_metric“ oder „filter_by_label“ beim Durchlaufen über eine Inline-Hydra-Überschreibung an (z. B. „topn=10“) – eine Neufassung der Spezifikation ist nicht erforderlich.

Wenn „filter_by_label=true“ ist, aber in einem der Embedding-Parquet-Dateien die Label -Spalte fehlt, protokolliert der Container eine Warnung und fährt ohne Filterung fort. Wenn die extrahierte Ausgabe umfangreicher als erwartet erscheint oder labelübergreifende Paare enthält, überprüfen Sie das Docker-Protokoll auf diese Warnung, bevor Sie davon ausgehen, dass die Aufgabe korrekt ausgeführt wurde.

Siehe „references/reference-invocation.md“ für das minimale „Einfügen-und-Bearbeiten“-End-to-End-Rezept (löst $DS_IMAGE auf, schreibt beide Spezifikationen, führt alle drei Schritte aus, ändert die Eigentümerrechte der Ausgaben und gibt die Zeilenanzahlen aus), das als einzelner gestreamter Bash-Block ausgeführt werden kann.

Ausgaben und Bericht

Schreiben Sie alles in einen Ordner mit Zeitstempel im Verzeichnis des Experiments bzw. der Iteration. Ermitteln Sie den tatsächlichen Zeitstempel, indem Sie in Bash den Befehl `date +%Y-%m-%d_%H%M%S ` ausführen – verwenden Sie KEINE festen Werte und raten Sie nicht. Wenn der Benutzer einen benutzerdefinierten Ausgabepfad angibt, verwenden Sie diesen direkt, behalten Sie jedoch das gleiche interne Layout bei. Der Packaging-Hook fügt „mining_config/“ und „claude_session.jsonl“ automatisch hinzu, sobald „Mining_Report.md“ geschrieben wird.

Das extrahierte Parquet-Datei ist das Artefakt, das vom nachgelagerten Training verwendet wird. Die beiden Embedding-Parquet-Dateien sind Zwischenprodukte, sollten aber aufbewahrt werden – sie sind über mehrere Mining-Läufe mit demselben Quellenpool hinweg wiederverwendbar und die einzige Stelle, an der nachgeschaut werden muss, wenn ein Bericht, der „unzusammenhängend erscheint“, eine Fehlerbehebung auf Encoder-Ebene erfordert.

Siehe references/outputs-and-reporting.md für die vollständige Struktur des Ausgabeverzeichnisses und die wörtliche Vorlage für „Mining_Report.md“ (Verdict, Inputs, Encoder Consistency, Mining Run, Per-Label Breakdown, Output Sanity, Recommended Actions; Umfang: 600–1200 Wörter).

Häufige Fallstricke

Der häufigste Fehler ist eine Nichtübereinstimmung der Encoder zwischen den beiden Einbettungsschritten – die mit Abstand häufigste Ursache für fehlerhafte Mining-Ergebnisse; beide Schritte müssen dieselbe „embedding_spec.yaml“-Datei verwenden. Weitere häufig auftretende Fallstricke: die Übergabe von --user (der „getpwuid“-KeyError), das Überspringen eines Einbettungsschritts, eine fehlende Label- Spalte, die filter_by_label=true stillschweigend außer Kraft setzt, Spec-Dateien außerhalb von $WORKSPACE, ungelöste ??? Sentinel, TAO-Checkpoints ohne `model_config_path`, direkt eingelesene CSV-Quellpools, Nichtübereinstimmungen zwischen Host- und Containerpfad, keine GPU, ein nicht heruntergeladenes oder `:latest` -Image-Tag sowie `topn × N_targets ≫` Quellgröße (erwartet – geben Sie die tatsächlich extrahierte Anzahl an).

Die vollständige Liste der Fallstricke mit den genauen Fehlern, Ursachen und Lösungen findest du unter references/troubleshooting.md.

Ausführungsreihenfolge

1. Lösen Sie DS_IMAGE aus „versions.yaml“ (images.tao_toolkit.data_services) auf, führen Sie dann „docker info“, „nvidia-smi“ und „docker image inspect "$DS_IMAGE"“ (mit Pull, falls fehlend) einmal 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 „/mining_results/“ und „/“.
3. Schreiben Sie „embedding_spec.yaml“ und „mining_spec.yaml“ in das Verzeichnis mit dem Zeitstempel und geben Sie dabei die Wahl des Encoders sowie die Mining-Parameter an. Speichern Sie diese Dateien unter $WORKSPACE, damit der Pfad „-e“ innerhalb des Containers aufgelöst wird.
4. Wenn der Quellpool eine CSV-Datei ist, konvertieren Sie diese zunächst in Parquet ( Dateipfad und Label beibehalten).
5. Führen Sie Schritt 1 (Ziele einbetten) über ` docker run … embedding image_embeddings -e embedding_spec.yaml input_parquet=… output_parquet=…` aus . Geben Sie die Anzahl der Zeilen und Spalten der Parquet-Ausgabe auf die Standardausgabe aus.
6. Führen Sie Schritt 2 (Einbetten des Quellpools) mit derselben ` embedding_spec.yaml ` wie in Schritt 1 aus. Geben Sie die Anzahl der Zeilen und Spalten der Ausgabedatei aus.
7. Führen Sie Schritt 3 (Nächste Nachbarn ermitteln) über ` docker run … tmm nearest_neighbors -e mining_spec.yaml source_parquet=… target_parquet=… output_parquet=…` aus . Vergewissern Sie sich, dass die Datei `mining_summary.txt` neben ` mined.parquet` geschrieben wurde.
8. Berechnen Sie die Aufschlüsselung pro Label (Abschnitt 5), indem Sie die Ziel-Embeddings-Parquet-Datei mit der „mined“-Ausgabe anhand des Dateipfads verknüpfen, sofern beide ein Label enthalten.
9. Schreiben Sie „Mining_Report.md“ zuletzt – das Schreiben löst den Packaging-Hook aus, der gleichzeitig die Sitzungsprotokolle und die Skill-Konfiguration kopiert.