Навык «DEFT: добыча и встраивание»

Вы являетесь оператором рабочего процесса DEFT «встраивание, а затем добыча» для зоны интереса (AOI) VCN. Ваша задача — взять набор изображений слабых целей (результат анализа пробелов или трассировки) и пул исходных изображений, а затем сгенерировать очищенный от дубликатов набор добытых исходных изображений, похожих на цели, — готовых для подачи в следующий раунд обучения.

Рабочий процесс фиксирован и детерминирован: встраивание целей, встраивание пула источников, затем добыча ближайших соседей. Паркет, полученный на выходе каждого шага, служит входными данными для следующего шага. Здесь нет итеративного поиска, нет этапа кластеризации, нет выбора с участием человека — глубина достигается за счет выбора правильного кодера и правильного topn, а не за счет многоэтапного исследования.

Весь скин представляет собой тонкий обёртку вокруг трёх прямых вызовов docker run с обращением к образу tao_toolkit.data_services, объявленному в файле versions.yaml (определяется во время выполнения — см. раздел «Настройка»). Точка входа контейнера принимает -e [переопределения Hydra...] — передаёт embedding image_embeddings -e … для встраивания и tmm nearest_neighbors -e … для добычи данных. Флаг -e указывает на файл YAML, который предоставляет значения по умолчанию для схемы подзадачи; всё, что следует за ним, представляет собой простое переопределение Hydra (ключ=значение), которое выборочно переопределяет поля спецификации при каждом запуске. (Внутри контейнера нет ключевого слова «dataset» — это префикс «pillar» запускающего модуля TAO, который здесь опускается.) Загрузите образ один раз, если он не находится в кэше: docker pull "$DS_IMAGE" (после определения значения $DS_IMAGE в соответствии с настройками).

Ключи схемы могут переименовываться между выпусками data-services (в навыке RCA, например, inference_csv → inference_results_dir, output_dir → results_dir). В случае сомнений проверьте фактическую схему один раз для каждого образа: docker run --rm "$DS_IMAGE" embedding image_embeddings --cfg=job и ... tmm nearest_neighbors --cfg=job.

Входные данные

1. Целевой файл Parquet — результат анализа пробелов, обычно mining_gaps.parquet из репозитория tao-route-visual-changenet-samples (или gaps.parquet из tao-analyze-gaps-visual-changenet, если маршрутизация была пропущена). Обязательный столбец: filepath. Если также присутствует столбец label, во время анализа доступна фильтрация с учетом меток; в противном случае задача анализа без предупреждения игнорирует фильтр.
2. Исходный пул — файл Parquet с изображениями-кандидатами для анализа, содержащий столбец filepath. Если у пользователя есть только файл CSV, преобразуйте его в файл Parquet с теми же столбцами перед шагом 2. Для фильтрации с учетом меток пул также должен содержать столбец label.
3. Файл спецификации вложения — файл YAML, содержащий model, model_path, batch_size и (только если model_path является файлом TAO .pth/.ckpt) model_config_path. Используется повторно на этапах 1 и 2;input_parquet/output_parquet задаются при каждом запуске в качестве переопределений Hydra. Один и тот же файл спецификации ДОЛЖЕН управляться обоими этапами встраивания — встраивания из разных кодировщиков несопоставимы, а несоответствие кодировщиков является наиболее распространённой причиной сообщений о том, что «извлечённые изображения выглядят несвязанными».
4. Файл спецификации добычи — файл YAML, содержащий topn, knn_metric, filter_by_label и (редко изменяемые)source_embed_column_name/target_embed_column_name.source_parquet/target_parquet/output_parquet являются переопределениями Hydra во время выполнения. Для вложений SigLIP и CLIP следует использовать knn_metric: cosine. Если filter_by_label: true, но в одном из паркет-файлов с вложениями отсутствует столбец с метками, контейнер записывает предупреждение в журнал и продолжает работу без фильтрации.

Настройка

Определите конкретный URI tao_toolkit.data_services из файла versions.yaml один раз в самом начале выполнения, затем убедитесь в наличии Docker, набора инструментов контейнеров NVIDIA и графического процессора (GPU), прежде чем приступать к каким-либо другим действиям. GPU требуется как для прямого прохода кодера, так и для k-NN-поиска cuML/cuDF; без CUDA оба этапа завершаются с ошибкой.

# Определить конкретный URI tao_toolkit.data_services → nvcr.io/... из файла versions.yaml
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"

Каждый путь на хосте, который контейнер считывает или в который записывает, должен быть смонтирован с помощью bind-mount. Наиболее предсказуемый подход заключается в монтировании корневой директории рабочего пространства с идентичными путями внутри и снаружи контейнера, а затем в повторном использовании одного псевдонима $DOCKER для всех трёх вызовов:

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

Не передавайте аргумент `--user $(id -u):$(id -g) ` — это вызывает ошибку KeyError в функции `getpwuid()` во время импорта трансформеров ещё до начала любой работы. Контейнер запускается с правами root; после этого команда `chown` возвращает UID хоста.

Создавайте два файла спецификации один раз за итерацию, размещая их в каталоге $WORKSPACE, чтобы аргумент -e разрешался по обе стороны монтирования; значения для отдельного запуска не включаются в спецификацию и передаются в качестве переопределений Hydra. Если исходный пул представляет собой файл CSV, сначала преобразуйте его в формат Parquet (сохранив путь к файлу и метку, если она есть). В файле embedding_spec.yaml по умолчанию используется model: SigLIP, model_path: google/siglip-base-patch16-224, batch_size: 64; в файле mining_spec.yaml по умолчанию используются значения topn: 5, knn_metric: cosine, filter_by_label: "false" (в кавычках — схема интерпретирует это как строку).

См. файл references/setup.md для получения полной информации о среде, обработке переменной TAO_SKILL_BANK_PATH, обосновании монтирования путей, обходном решении для команды chown при использовании getpwuid, фрагменте кода для преобразования CSV в Parquet, а также дословных блоков для создания файлов спецификаций.

Метод

Три команды, в указанном порядке. Вывод каждой команды в формате Parquet служит входом для следующей команды. Запускайте их как обычные команды Bash; псевдоним $DOCKER из файла Setup управляет контейнером, графическим процессором и монтированием. Каждый вызов имеет одинаковую структуру: -e для встроенных значений по умолчанию, затем несколько переопределений Hydra для путей, специфичных для данного запуска.

Шаг 1 — Встраивание целевых образов

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

Считывает результаты анализа пробелов / маршрутизации и записывает файл в формате Parquet с столбцами filepath, embedding и любыми дополнительными столбцами метаданных (например, label, siamese_score, weakness), перенесёнными дословно из входных данных. Выведите схему выходных данных (pd.read_parquet(...).columns) в стандартный вывод, чтобы хук проверки скрипта мог подтвердить наличие столбца вложения.

Если вам нужно переопределить model / model_path / batch_size для одного запуска без редактирования спецификации, добавьте их в качестве переопределений Hydra (например, model_path=...).

Шаг 2 — Встраивание исходного пула

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

Формат команды такой же, как в шаге 1, но применяется к исходному пулу. Используйте тот же файл embedding_spec.yaml, что и в шаге 1, и не переопределяйте здесь параметры model, model_path и batch_size — несовпадение настроек кодировщика в этих двух шагах приводит к получению несопоставимых вложений.

Шаг 3 — Поиск ближайших соседей

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

Для каждого целевого вложения находит topn ближайших исходных вложений по выбранной метрике, удаляет дубликаты по всем целям и записывает одностолбцовый (filepath) файл в формате Parquet, содержащий уникальные извлеченные исходные пути. Контейнер также создает файл mining_summary.txt рядом с выходным файлом Parquet, содержащий: количество запросов, количество соседей, количество удаленных дубликатов, а также (при включенной фильтрации по меткам) количество сохраненных и удаленных пар. Настройте topn, knn_metric или filter_by_label с помощью встроенного переопределения Hydra при прогоне (например, topn=10) — нет необходимости переписывать спецификацию.

Если filter_by_label=true, но в одном из паркет-файлов вложений отсутствует столбец с метками, контейнер записывает предупреждение в журнал и продолжает работу без фильтрации. Если объем добытых данных оказался больше ожидаемого или содержит межметковые пары, проверьте журнал Docker на наличие этого предупреждения, прежде чем считать, что задача выполнилась правильно.

См. файл references/reference-invocation.md, где приведён минимальный рецепт «скопируй-вставь-отредактируй» (решает $DS_IMAGE, записывает обе спецификации, запускает все три шага, меняет владельца выходных файлов и выводит количество строк), который можно запустить как единый потоковый блок Bash.

Результаты и отчёт

Запишите всё в папку с отметкой времени в каталоге эксперимента / итерации. Получите реальную отметку времени, выполнив в Bash команду `date +%Y-%m-%d_%H%M%S ` — НЕ указывайте её жестко и не угадывайте. Если пользователь указал собственный путь для вывода, используйте его напрямую, но сохраните ту же внутреннюю структуру. Хук упаковки автоматически добавляет каталоги `mining_config/` и файл ` claude_session.jsonl ` при записи файла ` Mining_Report.md`.

Полученный файл Parquet является артефактом, используемым последующим этапом обучения. Два файла Parquet с вложениями являются промежуточными, но их стоит сохранить — они могут быть повторно использованы в нескольких циклах майнинга на одном и том же пуле источников и являются единственным местом, куда следует обращаться, когда отчет, «выглядящий несвязанным», требует отладки на уровне кодировщика.

См. файл references/outputs-and-reporting.md для ознакомления с полной структурой каталога вывода и дословным шаблоном файла Mining_Report.md (Вердикт, Входные данные, Согласованность кодировщика, Прогон майнинга, Разбивка по меткам, Корректность вывода, Рекомендуемые действия; объем должен составлять 600–1200 слов).

Распространённые ошибки

Наиболее частая ошибка — несовпадение кодировщиков на двух этапах встраивания — самая распространённая причина получения бессмысленных результатов майнинга; оба этапа должны использовать один и тот же файл embedding_spec.yaml. Другие повторяющиеся ловушки: передача параметра --user ( ошибка KeyError при вызове getpwuid ), пропуск этапа встраивания, отсутствующий столбец с метками, приводящий к скрытому игнорированию параметра filter_by_label=true, файлы спецификаций за пределами $WORKSPACE, неразрешенные ??? сентинелы, контрольные точки TAO без model_config_path, прямая подача пулов исходных данных в формате CSV, несоответствие путей на хосте и в контейнере, отсутствие GPU, незагруженный тег образа или тег :latest, а также topn × N_targets ≫ размер исходного набора (ожидаемо — укажите фактическое количество извлеченных данных).

См. файл references/troubleshooting.md для полного списка проблем с точными ошибками, причинами и способами устранения.

Порядок выполнения

1. Определите DS_IMAGE из файла versions.yaml (images.tao_toolkit.data_services), затем один раз запустите коман ды docker info, nvidia-smi и docker image inspect "$DS_IMAGE" (загрузив образ, если он отсутствует), чтобы проверить среду. В случае сбоя любой из операций прервите процесс с чётким сообщением.
2. Запустите команду `date +%Y-%m-%d_%H%M%S`, чтобы получить метку времени; создайте каталоги ` `, `/mining_results/` и `/`.
3. Запишите файлы `embedding_spec.yaml ` и `mining_spec.yaml` в каталог с отметкой времени, указав выбранный кодер и параметры майнинга. Сохраните их в каталоге `$WORKSPACE`, чтобы путь, указанный с помощью опции `-e`, разрешался внутри контейнера.
4. Если исходный набор данных представляет собой файл CSV, сначала преобразуйте его в формат Parquet (сохранив путь к файлу и метку).
5. Запустите Шаг 1 (встраивание целей) с помощью команды docker run … embedding image_embeddings -e embedding_spec.yaml input_parquet=… output_parquet=…. Выведите количество строк и столбцов выходного файла Parquet в стандартный вывод (stdout).
6. Запустите шаг 2 (встраивание пула источников) с тем же файлом embedding_spec.yaml, что и в шаге 1. Выведите количество строк и столбцов выходного файла.
7. Запустите шаг 3 (добыча ближайших соседей) с помощью команды ` docker run … tmm nearest_neighbors -e mining_spec.yaml source_parquet=… target_parquet=… output_parquet=…`. Убедитесь, что файл `mining_summary.txt` был записан рядом с файлом `mined.parquet`.
8. Вычислите разбивку по меткам (раздел 5), объединив целевой файл embeddings.parquet с результатом поиска по пути к файлу, если оба содержат метку.
9. В последнюю очередь запишите файл Mining_Report.md — его запись запускает хук упаковки, который копирует журналы сеанса и конфигурацию навыка.