JSON-схема плагінів SIMA (історичний знімок)

Дата знімка: 2026-02-17

Цей документ зберігає результати перевірки використання JSON-полів етапами конвеєра моделі SIMA станом на лютий 2026 року. Згадки про «поточну» поведінку нижче стосуються саме цього знімка.

Історичний контракт: Наведені нижче назви плагінів та обов’язкові JSON-поля не є контрактом розгортання Platform 3.0.0. Універсальний BoxDecode тепер використовує neatobjectdecode, який налаштовується через типізований етап маніфесту та властивості середовища виконання. Старі вимоги simaaiboxdecode нижче не визначають конфігурацію на рівні застосунку. Актуальні вимоги до конфігурації та сумісних пакетів див. у контракті контексту статичного маніфесту SIMA.

1. Зафіксуйте обсяг робіт і матрицю плагінів.

1.1 Входить до сфери застосування (модель конвеєра)

• simaaiprocesscvu використовується як:
  • етап попередньої обробки (kernel=preproc)
  • етап квантування/тестування (kernel=quanttess)
  • обгортка для етапу обробки після виконання операцій detess/dequant (kernel=detessdequant у послідовності моделі, елемент бекенду все ще є simaaiprocesscvu у src/nodes/sima/DetessDequant.cpp).
• simaaiprocessmla
• simaaiboxdecode (універсальний декодер даних)
• етапи корисного навантаження detess/dequant/tess у tmp/gst/*:
  • detessdequant
  • detessellate
  • quantize
  • slicedequant

1.2 Не входить до сфери застосування.

Універсальні плагіни для програми CVU та спеціалізовані утиліти для роботи з графами не входять до сфери застосування цієї схеми, зокрема, але не обмежуючись цим:

• overlay, genericrender, argmax, nms*, groupkeypoints, distancecalculation, cv_process, cvresize, fastbev*, PyGast-plugins/*, застарілі плагіни та власні шаблони для застосунків/тестів.

1.3 Охоплені вихідні коди

Статичне вилучення охоплювало обидва запитані дерева:

• tmp/gst_plugins_source/gst/*
• tmp/gst/*

Перевірка у дзеркалі:

• Те саме в обох деревах: genericboxdecode, detessdequant, detessellate, quantize, slicedequant.
• Розбіжність: processcvu, processmla

1.4 Матриця плагінів

Плагін / Етап	Наразі необхідні ключі JSON (актуальні шляхи коду).	Ключі, які можна визначити на основі наявних даних.	Властивості, що використовуються під час виконання (не повинні бути статичним JSON).	Ключі, призначені лише для використання з MLA.
simaaiprocesscvu (попередня обробка/квантування/пост-обробка)	infer-first: з’єднання встановлюються з ConfigManager::getBuffers(), якщо це можливо; JSON input_buffers/output_memory_order використовується лише як резервний варіант.	input_width/input_height можуть надходити з блоків керування/середовища виконання для графа 200/202; масиви з’єднань можуть бути отримані з метаданих CM.	під час обробки кожного кадру відбувається повторне узгодження значень параметрів середовища виконання; під час створення структури більше не відбувається перезапису полів JSON для кожного етапу.	шляхи quant/tess і post опосередковано використовують поля форми тензора MLA.input_depth, slice_*)
simaaiprocessmla	simaai__params, model_path, batch_size; використання outputs[*] є бажаним, але більше не є обов’язковим, оскільки розміри сегментів можна визначити на основі полів, що визначають форму вихідних даних.	розміри сегментів вихідних даних можна визначити на основі output_*/slice_* + dtype.	input_segment_name необов’язкова допоміжна програма для налаштування в середовищі виконання; шлях до моделі може бути отриманий із пакета.	outputs, data_type, output_*, slice_*, параметри квантування.
simaaiboxdecode	Фактично, ці параметри необхідні для завантажувача конфігурації бекенду: buffers.output.size, memory.next_cpu, system.out_buf_queue; наразі визначення кількості класів залежить від версії реалізації.	Кількість класів (num_classes) можна визначити на основі input_depth/ slice_depth + num_in_tensor + decode_type (нова логіка обробки даних).	buffers.input[*].name було переналаштовано з вихідного коду; порогові значення/topk часто використовуються як параметри, що налаштовуються під час роботи (у середовищі виконання).	input_*, slice_*, data_type, num_in_tensor
detessdequant (застарілий автономний елемент GST)	simaai__params плюс поля парсера: orig_img_width, orig_img_height, frame_width, frame_height, num_in_tensor, next_cpu, no_of_outbuf, out_sz, input_*, slice_*, q_scale, q_zp.	в плагіні немає; на вищому рівні реалізовано механізм визначення форми в StageConfig.	іменування проміжних буферів/маршрутизація ЦП здійснюється в середовищі виконання в процесах обгортки.	input_*, slice_*, q_scale, q_zp, num_in_tensor
detessellate корисне навантаження (tmp/gst/detessellate)	приймає de_tess.* або еквіваленти у форматі root/static-contract (input_*, slice_*/output_*); buffers.input[0].offset (необов’язковий параметр, значення за замовчуванням — 0).	кількість тензорів і їх розмірності можна отримати на основі статичних полів, визначених на етапі створення маніфесту.	ім’я/шлях вхідних даних має визначатися під час виконання, а не бути статичним.	угода про розподіл/частку
quantize корисне навантаження (tmp/gst/quantize)	quant_scale, zero_point (резервний варіант у форматі JSON).	кількість елементів вхідного потоку визначається на основі розміру вхідного буфера.	тепер спочатку використовує метадані q_scale/q_zp з вищих рівнів, а потім переходить до JSON у разі потреби.	не застосовується (узагальнена квантизація)
slicedequant корисне навантаження (tmp/gst/slicedequant)	зчитує розділ (slice_dequant/simaai__params/root) для резервного визначення форми; JSON-файл для квантування використовується лише як резервний варіант.	отримуємо перші кількісні дані з метаданих середовища виконання; розмірності можна отримати з маніфесту статичного контракту.	метадані середовища виконання (q_scale/q_zp) є кращим способом передачі даних.	Формат/кількісні показники вихідних даних MLA

1.5 Передача контексту маніфесту (поточна)

• Тип контексту конвеєра: sima.model.manifest.v1
• Безпечний для ABI доступ до плагіна: manifest_accessor_v1 у include/gst/SimaPluginStaticManifestAbi.h.
• Ключі для пошуку на етапі:
  • element_name (за замовчуванням)
  • logical_stage_id (отримується зі властивості конвеєра stage-id або stage_id, якщо її встановлено).
• Застарілий рядок manifest_json залишається для забезпечення плавності переходу.
• Конструктори фрагментів вузлів/моделей тепер генерують stage-id=<element-name> для шляху до моделі SIMA. модулі розроблено таким чином, щоб логічний пошук був детермінованим, навіть якщо застосовуються додаткові перетворення імен.

2. Необхідна схема основних істин.

2.1 Метод статичного вилучення

Отримано з чітко визначених точок доступу:

• json["..."]
• contains("...")
• допоміжні функції для аналізатора (parser_get_int, parser_get_double_array, тощо).

Основні місця, де було знайдено важливі докази:

• tmp/gst/processcvu/gstsimaaiprocesscvu.cpp:1667
• tmp/gst/processmla/gstsimaaiprocessmla.cpp:579
• tmp/gst/genericboxdecode/payload.cpp:61
• tmp/gst/detessdequant/gstsimaaidetessdequant.cpp:276
• tmp/gst/detessellate/detessellate.cpp:361
• tmp/gst/quantize/payload.cpp:124
• tmp/gst/slicedequant/payload.cpp:57

Докази, отримані під час роботи/виведення результатів:

• src/nodes/sima/Preproc.cpp:245
• src/nodes/sima/DetessDequant.cpp:238
• src/nodes/sima/SimaBoxDecode.cpp:158
• src/pipeline/runtime/StageConfig.cpp:296
• src/pipeline/runtime/StageConfig.cpp:411

2.2. Використовується метод динамічного імітування відмов.

Для зареєстрованих плагінів (simaaiprocesscvu, simaaiprocessmla, simaaiboxdecode, detessdequant):

• базовий рівень: gst-launch-1.0 ... num-buffers=0
• змінюйте по черзі кожен ключ (видаляйте поле)
• записуйте поведінку та повідомлення, що виникають під час запуску або в середовищі виконання.
• примітка: динамічні результати відображають поточні зареєстровані плагіни середовища виконання на цьому хості.

Для незареєстрованих етапів корисного навантаження (detessellate, quantize, slicedequant):

• у цьому середовищі виконання немає доступних безпосередніх елементів GST (згідно зі звітом gst-inspect-1.0, їх відсутньо).
• отже, динамічне видалення ключів було обмежено статичною/вихідною класифікацією для цього проходу.

2.3 Категоризована карта (заморожена)

simaaiprocesscvu

• обов’язково:
  • або успішне виконання логіки буферизації CM, або використання резервного варіанту JSON з:
    • input_buffers
    • output_memory_order
    • кожен вхідний memories[*].segment_name
    • кожен вхідний memories[*].graph_input_name
• м’який/за замовчуванням:
  • graph_name
  • input_width, input_height (необов’язкові розміри у форматі JSON).
• дублікат/похідний:
  • input_buffers[*].name (з’єднано під час виконання).
  • sink_pad_tensor_index_map, отриманий із контексту маніфесту, тепер є рекомендованим для детермінованого відображення з кількома вхідними даними.
  • попередня обробка розмірностей з caps/середовища виконання
• лише для налагодження:
  • Поля стилю debug не потрібні для виконання.

Динамічні докази:

• якщо висновок CM не вдається, і відсутні дані у форматі JSON, то запуск програми завершується помилкою, пов’язаною з шиною даних.
• якщо процес виведення на основі CM завершується успішно, то input_buffers/output_memory_order можна опустити.
• якщо контекст вказує на багатоканальний вхідний етап, яким керує модель, і sink_pad_tensor_index_map відсутній або неоднозначний, то запуск завершується з помилкою, пов’язаною з шиною.

simaaiprocessmla

• обов’язково:
  • simaai__params
  • model_path
  • batch_size
  • outputs[*].name
  • outputs[*].size
  • batch_sz_model, коли batch_size != 1.
• м’який/за замовчуванням:
  • input_segment_name
• дублікат/похідний:
  • розміри/типи вихідних даних можна визначити на основі метаданих моделі у вищих шарах.
• лише для налагодження:
  • не є критичним

Динамічні докази:

• видалити model_path -> виникла невирішена помилка типу nlohmann::json (ec=134)
• batch_size=2 і видалити batch_sz_model -> виникла невизначена помилка типу (ec=134).
• видалення outputs -> запуск може завершитися успішно з num-buffers=0, але в середовищі виконання (num-buffers=1) виникає проблема, пов’язана з циклом SIGSEGV.

simaaiboxdecode

• суворо необхідне (поточна поведінка в середовищі виконання):
  • buffers.output.size
  • memory.next_cpu
  • system.out_buf_queue
• м’який/з можливістю налаштування за замовчуванням (залежить від версії реалізації):
  • У новіших версіях коду значення num_classes може визначатися автоматично або використовуватись як резервне значення, але в поточній версії середовища виконання може лише виводити попередження.
  • decode_type може призвести до появи попередження про невідповідність типів у поточному середовищі виконання.
• дублікат/похідний:
  • buffers.input[*].name – підключено до середовища виконання.
  • num_classes, що визначається за розмірністю тензора (input_depth/slice_depth) для відомих сімейств декодування.
• лише для налагодження:
  • system.debug, system.dump_data

Динамічні докази:

• видалити memory.next_cpu -> виникла невизначена помилка типу, програма припинила роботу (ec=134)
• видалити system.out_buf_queue -> виникла невизначена помилка типу, програма припинила роботу (ec=134)
• видалити num_classes -> некритичне попередження про JSON type mismatch (ec=0)

detessdequant (застарілий автономний плагін GST)

• обов’язково:
  • об’єкт simaai__params
  • ключі для аналізатора: orig_img_width, orig_img_height, frame_width, frame_height, num_in_tensor, next_cpu, no_of_outbuf, out_sz, input_height, input_width, input_depth, slice_height, slice_width, slice_depth, q_scale, q_zp
• м’який/за замовчуванням:
  • жодного в поточному коді.
• дублікат/похідний:
  • деякі поля, що містять інформацію про розмір кадру/оригінального зображення, є метаданими і їх можна отримати на основі інших даних.
• лише для налагодження:
  • debug, dump_data, inpath, ibufname, n_request, тощо.

Динамічні докази:

• видалити simaai__params -> цикл SIGSEGV (час очікування)
• видалити num_in_tensor -> виникла помилка SIGSEGV у циклі (час очікування вичерпано).

detessellate корисне навантаження.

• обов’язково:
  • вирішено проблему з полями тензорів вхідних даних/зрізів (отримано з de_tess.* або згенеровано з використанням ключових слів root/static-contract).
• м’який/за замовчуванням:
  • buffers.input[0].offset (за замовчуванням — 0)
  • num_in_tensor (обчислюється на основі розмірів вектора, якщо їх не вказано).
• дублікат/похідний:
  • вектори форми можна отримати на основі статичних тензорів, що використовуються на певній стадії.
• лише для налагодження:
  • жоден

quantize корисне навантаження.

• обов’язково:
  • quant_scale
  • zero_point
• м’який/за замовчуванням:
  • жодного в поточному коді.
• дублікат/похідний:
  • кількість елементів тензора, що визначається на основі розміру вхідного масиву байтів.
• лише для налагодження:
  • жоден

slicedequant корисне навантаження.

• обов’язково:
  • кількісні параметри для деквантування (q_scale, q_zp) визначаються на основі метаданих середовища виконання або використовуються значення за замовчуванням із файлу конфігурації.
  • розміри зрізу тензора (input_*, output_depth/slice_depth) отримано в результаті синтезу секції/кореня/статичного контракту.
• м’який/за замовчуванням:
  • скалярне та векторне кодування для квантування та ключових точок форми
• дублікат/похідний:
  • формат «quant» є кращим для використання з метаданими під час роботи програми; JSON залишається лише як резервний варіант.
• лише для налагодження:
  • не застосовується

3. Контрольована точка видалення (з цієї статичної карти)

Будь-яке видалення поля JSON має включати всі наступні елементи:

1. Оновіть цю класифікацію карти правдивих тверджень для даної галузі.
2. Додайте/оновіть тестовий приклад для імітації збою:
   • у разі збою під час запуску має бути чітко вказано причину (помилка шини), програма не повинна аварійно завершувати роботу.
3. Для полів, значення яких можна визначити або отримати на основі інших даних:
   • спочатку реалізуйте логіку виведення,
   • зберегти можливість використання параметрів/плагінів як резервного варіанту,
   • залишайте JSON як останній варіант резервного копіювання лише там, де це все ще необхідно.
4. Зберігайте мінімальний обсяг JSON-файлу, що містить лише дані у форматі MLA:
   • залишилися лише невирішені метадані MLA (параметри форми/розміру/кількості).
5. Завжди вмикайте сувору перевірку за допомогою системи безперервної інтеграції:
   • unit_sima_plugin_manifest_strict_model_pipeline_test
   • unit_sima_plugin_manifest_strict_fallback_test
   • і відповідний канал тестування Vulcan CI у файлі .github/workflows/vulcan-ci.yml.

4. Виявлені поточні ризики

• Кілька шляхів, де відсутні необхідні ключі, все ще призводять до аварійного завершення роботи через невизначені винятки nlohmann::json або сигнали SIGSEGV замість помилок шини.
• Застарілий шлях detessdequant може спричиняти збої через відсутність необхідних ключів для аналізатора.
• slicedequant повністю ігнорує формат JSON і використовує скомпільовані константи.
• Розбіжності між кодом, що виконується, та вихідним кодом можуть знову виникати, якщо під час повторної збірки файли .so не копіюються з tmp/gst/*/build до deps/gst-plugins.