Навык анализа пробелов в системе TAO VCN Classify

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

Этот навык намеренно выполнен в облегченном варианте. Классификатор VCN представляет собой бинарную границу с единственным результатом (PASS или NO_PASS по siamese_score), поэтому анализ носит вычислительный характер, а не исследовательский. Весь расчёт осуществляется в рамках одного прямого вызова Docker run с использованием образа tao_toolkit.data_services, объявленного в файле versions.yaml (определяется во время выполнения — см. раздел «Настройка»). Точка входа контейнера принимает [переопределения Hydra...]; мы передаём gap_analysis vcn_aoi key=value …. Каждое переопределение представляет собой простой ключ-значение Hydra, которое выборочно переопределяет схему GapAnalysisConfig скрипта (значения по умолчанию встроены в контейнер; проверьте с помощью docker run ... gap_analysis vcn_aoi --cfg=job). (Внутри контейнера нет ключевого слова dataset — это префикс столбца запуска TAO, который здесь опускается.) Вам не нужны делегированный анализ, многоэтапные проверки образов или кластеризация по типам компонентов — VCN не предоставляет доступ к этим аспектам. Просмотрите лишь небольшой набор репрезентативных слабых образцов, чтобы определить пробелы после возврата контейнера.

Интерфейс CLI может меняться в зависимости от сборки контейнера data-services. Если вызов gap_analysis vcn_aoi завершается с ошибкой при разборе аргументов, проверьте фактическую схему один раз для каждого образа с помощью команды docker run --rm "$DS_IMAGE" gap_analysis vcn_aoi --cfg=job и приведите в соответствие все переименованные ключи (например, inference_csv и inference_results_dir, output_dir и results_dir) перед повторной попыткой. Имя выходного файла в формате Parquet — kpi_gaps.parquet.

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

1. Каталог результатов эксперимента — содержит файл inference/inference.csv, полученный в результате инференции TAO VCN Classify. Обязательные столбцы: input_path, object_name, label, siamese_score. Передайте каталог (например, inference/latest/), а не файл CSV — контейнер считывает файл из папки inference_results_dir/inference.csv.
2. Каталог с кодом и конфигурацией обучения — содержит файл YAML модели VCN для обучения. Контейнер считывает из него файлы dataset.classify.input_map (список условий освещения) и dataset.classify.image_ext, чтобы развернуть каждую «слабую» выборку в одну строку для каждого варианта освещения.
3. Каталог набора данных — к относительному пути input_path из каждой строки (kpi_media_path) добавляется корень каталога изображений.
4. Переопределения схемы — min_recall, top_k_per_label и, опционально, жестко зафиксированный порог передаются в качестве переопределений Hydra (значения по умолчанию: min_recall=1.0, top_k_per_label=50, threshold=-1.0, что означает полный проход). top_k_per_label должен быть положительным целым числом — его пропуск переключает контейнер в режим «фильтра ниже порога», который при min_recall=1,0 возвращает только ошибочные классификации PASS и ноль строк NO_PASS. См. раздел «Распространённые ошибки».

Настройка

Проход по порогу, ранжирование слабых мест и расширение по каждому освещению выполняются внутри образа tao_toolkit.data_services, объявленного в файле versions.yaml. Определите конкретный URI один раз в начале запуска, затем убедитесь в наличии Docker, набора инструментов контейнеров NVIDIA и графического процессора, а также проверьте, что образ кэширован:

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

TAO_SKILL_BANK_PATH обычно экспортируется установленным банком навыков. Если эта переменная не задана, перед началом работы укажите путь к корневому каталогу репозитория банка навыков. Требуется графический процессор (GPU); досрочное прерывание процесса на хосте без GPU позволит избежать непонятных ошибок на поздних этапах.

Три правила настройки являются ключевыми и их легко нарушить:

• Монтирование путей — каждый путь на хосте, который контейнер читает или в который записывает (inference.csv, YAML для обучения, корневой каталог образа набора данных, каталог вывода), должен быть смонтирован с привязкой; проще всего это сделать с помощью -v $WORKSPACE:$WORKSPACE -w $WORKSPACE, чтобы абсолютные пути разрешались одинаково с обеих сторон.
• Не передавайте --user $(id -u):$(id -g) — это вызывает ошибку KeyError: 'getpwuid(): uid not found: ' во время импорта трансформеров контейнером; вместо этого chown впоследствии возвращает UID хоста.
• -e является обязательным, а не опциональным параметром — текущие образы строго требуют его наличия и завершают работу с ошибкой ValueError: «The subtask vcn_aoi requires the following argument: -e/--experiment_spec_file» перед разбором переопределений из командной строки.

См. файл references/container-setup.md для ознакомления с полным шаблоном подключения по пути, обоснованием использования--user/chown и командой chown в Alpine, рекомендациями по использованию нескольких параметров --v, а также подробностями о требовании -e .

Метод

Весь навык представляет собой один вызов docker run, за которым следует небольшая визуальная выборочная проверка. Контейнер внутренне выполняет шаги 1–4 (проход по порогам, оценка уязвимостей, выбор top-K, расширение по каждому источнику освещения). Вы выполняете шаг 5 (визуальную выборочную проверку) непосредственно с помощью инструмента Read.

Шаги 1–4 — Запуск контейнера

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

Всегда передавайте параметр top_k_per_label. Это аргумент, который переключает контейнер с фильтра по умолчанию «выборки ниже порогового значения» на правильный рейтинг top-K-per-label. При min_recall=1.0 пороговое значение по определению находится на уровне или ниже каждого оценки NO_PASS, поэтому фильтр «ниже порогового значения» возвращает ТОЛЬКО неправильно классифицированные строки PASS и ноль строк NO_PASS — что бесполезно в качестве очереди расширения. Если top_k_per_label установлен в положительное целое число (либо в спецификации, либо в качестве переопределения Hydra), контейнер вычисляет слабость со знаком относительно порога для каждой строки и выделяет K самых слабых строк для каждой метки истинного значения, которые и являются ранжированным выходом по меткам, потребляемым последующими этапами.

Считывает файл inference.csv, просматривает каждое уникальное значение siamese_score плюс одно значение чуть ниже минимума, оставляет кандидаты с коэффициентом воспроизведения класса NO_PASS ≥ min_recall (с допуском 1e-12 ), а затем выбирает пороговое значение с наилучшим показателем F1 (при равенстве: точность, затем значение порогового значения). Для каждой строки вычисляет знак слабости относительно этого порога (положительный = ошибочная классификация, отрицательный = правильная, величина = отклонение). Сортирует по слабости в порядке убывания и берет top_k_per_label лучших строк для каждого ярлыка истинных значений, затем расширяет каждую слабую строку до одной строки на каждое условие освещения с помощью dataset.classify.input_map и dataset.classify.image_ext из YAML-файла обучения.

Если ни одно из пороговых значений не соответствует целевому показателю воспроизведения, контейнер завершает работу с ненулевым кодом и записывает файл unreachable_kpi.txt в каталог results_dir с объяснением, какого показателя воспроизведения модель может фактически достичь. В этом случае остановите анализ после вызова Docker, составьте отчёт из одного раздела, объясняющий, что модель принципиально не может достичь KPI ни в одной рабочей точке, и порекомендуйте переобучение или перемаркировку — пропустите визуальную выборочную проверку.

Контейнер записывает в каталог results_dir:

Выведите сводку stdout контейнера (выбранное пороговое значение, количество сохраненных строк, разбивка по лейблам) в свой собственный stdout, чтобы хук script-check мог проверить выходные данные, сгенерированные в ходе запуска.

Шаг 5 — Визуальная выборочная проверка (небольшая, фиксированная)

Пропустите этот шаг, если существует файл unreachable_kpi.txt. В противном случае используйте инструмент «Read» для просмотра 5 самых слабых образцов с результатом «PASS» и 5 самых слабых образцов с результатом «NO_PASS» из файла kpi_gaps.parquet (очищенного от дубликатов до одной строки на образец с использованием пути к файлу FIRST-lighting), классифицируйте каждый из них как один из следующих типов: «mislabeled» / «edge case» / «data quality » / «systematic», и скопируйте каждое просмотренное изображение (измененное до размера 128×128, если доступен PIL, в противном случае просто скопируйте) в папку /rca_images/. Это единственная необходимая проверка изображений — не просматривайте десятки изображений, не выполняйте кластеризацию по режимам сбоев и не проводите аудит эталонных изображений (у VCN нет эталонных изображений).

См. файл references/visual-spot-check.md для ознакомления с точным порядком отбора образцов, правилом удаления дубликатов по условиям освещения, полным определением каждой категории вердикта и подробностями копирования изображений.

Вызов скрипта

Вставьте и отредактируйте рабочую область, четыре пути и два числовых параметра; это запускает процесс от начала до конца. Перехватите stdout, чтобы хук проверки скриптов видел количество строк.

WORKSPACE=           # монтируется идентично внутри контейнера
EXP_DIR=     # содержит файлы inference/inference.csv и train.yaml; должен находиться внутри $WORKSPACE
DATASET_ROOT=         # корневой каталог изображений для записей input_path в файле inference.csv; должен находиться внутри $WORKSPACE
MIN_RECALL=1.0                       # значение по умолчанию для нулевого пропуска; уменьшайте, если требования к KPI снижаются
TOP_K=50                             # бюджет на увеличение данных для каждого лейбла
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"

# Записать спецификацию анализа пробелов для данного запуска
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"

# Контейнер записывает данные как пользователь root с отключенным параметром --user; при необходимости верните права владения (chown) к UID хоста.
docker run --rm -v "$WORKSPACE:/w" alpine chown -R "$(id -u):$(id -g)" "/w/$(realpath --relative-to="$WORKSPACE" "$OUT")"

# Вывод данных для проверки, чтобы хук script-check видел реальные числа
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)
    sys.exit(0)
with open(os.path.join(out, "threshold.txt")) as f:
    print("пороговое значение:", 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

Результаты

Запишите всё в папку с отметкой времени в каталоге результатов эксперимента. Результаты контейнера попадают прямо туда; визуальная выборочная проверка записывает данные в rca_images/; любой хук упаковки на время выполнения может добавлять артефакты захвата session/config после записи файла RCA_Report.md.

/rca_results/YYYY-MM-DD_HHMMSS/
├── RCA_Report.md              # Полный отчёт по анализу пробелов (вы его составляете)
├── kpi_gaps.parquet           # Контейнер: top-K самых слабых по метке, с разбивкой по освещению
├── threshold.txt              # Контейнер: выбранный порог принятия решения (одно число с плавающей запятой)
├── metrics.json               # Контейнер: матрица путаницы + статистика распределения по меткам
├── weak_samples_breakdown.txt # Контейнер: количество по меткам / количество ошибочно классифицированных / количество маргинальных
├── unreachable_kpi.txt        # Контейнер: ТОЛЬКО если ни один порог не удовлетворяет min_recall
├── rca_images/                # Вам: миниатюры 10 просмотренных слабых образцов
├── rca_config/                # Автоматически копируется хуком
└── session log/artifacts      # Необязательно, запись упаковки, зависящая от времени выполнения

В начале запуска получите реальную метку времени, выполнив в Bash команду date +%Y-%m-%d_%H%M%S. НЕ используйте жестко заданные значения и не угадывайте. Если пользователь указал собственный путь вывода, используйте его, но сохраните ту же внутреннюю структуру.

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

Самый серьезный из всех возможных сбоев — забыть указать top_k_per_label при min_recall=1.0: при данном значении recall выбранный порог находится на уровне или ниже каждого значения NO_PASS, поэтому без top_k_per_label контейнер переключается на фильтр «выборки ниже порога», который возвращает ТОЛЬКО неправильно классифицированные строки PASS и ноль строк NO_PASS, что нарушает работу очереди аугментации. Всегда указывайте явное положительное значение top_k_per_label (по умолчанию 50) в спецификации или в качестве переопределения Hydra.

См. файл references/pitfalls.md для полного контрольного списка, охватывающего: забывание top_k_per_label; передачу параметра --user; вызов только с переопределениями Hydra (без -e ); файл спецификации вне $WORKSPACE; файл спецификации с неразрешенными сигнальными знаками ???; изображение не загружено / неправильный тег; несоответствие path-mount; наличие файла unreachable_kpi.txt; отсутствие обязательных столбцов в файле inference.csv; отсутствие в YAML-файле train параметров dataset.classify.input_map или image_ext; несовпадение префиксов kpi_media_path и input_path; а также отсутствие обнаружения GPU изнутри контейнера.

Структура отчёта

Напишите файл RCA_Report.md в виде лаконичного (1000–1800 слов) анализа вычислительных пробелов — глубина анализа достигается за счет точных цифр и четкого списка действий, а не за счет описательного текста. Полный шаблон отчета (7 разделов: «Вердикт», «Выбор порогового значения», «Распределение слабых мест», «Top-K самых слабых образцов», «Визуальная выборочная проверка», «Разбивка по меткам», «Рекомендуемые действия» — с матрицей путаницы и макетами таблиц) находится в файле references/output-template.md. Если файл unreachable_kpi.txt существует, замените разделы 3–6 одним коротким разделом, цитирующим содержание этого файла, и сведите раздел 7 к одной рекомендации: переобучить или перемаркировать.

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

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`, чтобы получить метку времени; создайте каталоги ` `, `/rca_results/` и `/`.
3. Запишите файл vcn_aoi_spec.yaml в каталог с меткой времени, заполнив поля min_recall и top_k_per_label. Сохраните его в каталоге $WORKSPACE, чтобы путь -e разрешался внутри контейнера.
4. Запустите команду docker run … "$DS_IMAGE" gap_analysis vcn_aoi -e vcn_aoi_spec.yaml inference_results_dir=… train_config=… kpi_media_path=… output_dir=…. Контейнер записывает файлы `kpi_gaps.parquet`, `threshold.txt`, `metrics.json` и `weak_samples_breakdown.txt ` в каталог `results_dir`. Выведите выбранное пороговое значение и количество сохраненных строк в стандартный вывод (stdout), чтобы хук script-check мог проверить, что запуск сгенерировал ожидаемый вывод.
5. Если файл unreachable_kpi.txt существует, пропустите шаг 6 и запишите сокращённый отчёт. В противном случае продолжайте.
6. Выберите 10 слабых образцов (5 самых слабых PASS + 5 самых слабых NO_PASS) из файла kpi_gaps.parquet, просмотрите каждое тестовое изображение с помощью команды Read, классифицируйте их и скопируйте каждое в каталог rca_images/.
7. В конце создайте файл RCA_Report.md — его создание запускает хук упаковки, который копирует журналы сеанса и конфигурацию навыка.