РУКОВОДСТВО · ОБНОВЛЕНО 2026-11-09
Как проверить JSONL перед загрузкой в Batch API
Пошаговая проверка JSONL до загрузки в Batch API. Кодировка, пустые строки, схема записи, уникальные идентификаторы и сверка результата.
Проверяйте JSONL на двух уровнях. Сначала убедитесь, что каждая строка содержит одно корректное значение JSON в UTF-8. Затем проверьте контракт Batch API, который обычно требует объект запроса с конкретными полями. Например, строка null соответствует формату JSON Lines, но не соответствует схеме пакетного запроса. Локальная проверка должна сообщать номер строки и причину ошибки до отправки файла.
1. Прочитайте файл построчно
Прочитайте исходные байты как UTF-8 с отказом при ошибке декодирования. В JSON Lines маркер BOM не допускается, а пустая строка не является значением JSON. Завершающий перевод строки допустим и удобен при объединении файлов. Отличайте его от дополнительной пустой записи. Если в сообщении есть перенос, JSON-сериализатор записывает его как экранированный символ внутри строки. Форматирование объекта на нескольких физических строках ломает правило одной записи на строку. Для быстрой проверки соберите две строки с объектами и вставьте между ними пустую строку. Валидатор должен указать номер этой строки до обращения к сервису.
2. Проверьте каждую запись по контракту
Сначала разберите строку обычным JSON-парсером, затем проверьте тип значения и обязательные поля. Для пакетной операции схема может требовать идентификатор, метод, путь и тело, но точные названия определяет сервис. Если тело содержит настройки модели, проверяйте их по той операции, которая будет выполнена. Ошибку синтаксиса и неизвестное поле выводите раздельно. В журнале достаточно номера строки, кода ошибки и имени поля без полного содержимого запроса.
3. Проверьте идентификаторы и ограничения партии
Проверьте уникальность идентификатора в границах партии, если контракт требует уникальные ID. Сохраните сопоставление с исходным заданием и версией данных, чтобы ответ можно было найти даже при другом порядке строк. Размер файла измеряйте в байтах после сериализации. Лимиты количества запросов и общего объёма берите из документации выбранной операции. В контрольный набор включите дублированный ID, повреждённую строку, пустую запись и корректный текст с кириллицей.
4. Сверьте ответы с исходным файлом
После выполнения разберите файл результатов по контракту, который возвращает сервис. Отдельно учитывайте успешный ответ, ошибку операции и отсутствующую запись. Завершение партии не заменяет проверку соответствия каждого результата исходному идентификатору. Для частичного повтора сохраните связь с первой попыткой и не отправляйте повторно уже принятые задания. Проверьте локально, что дубликат, потерянный ответ и перемешанный порядок обнаруживаются на синтетическом наборе.
Частые вопросы
Можно ли загрузить один JSON-массив?
Если маршрут ожидает JSONL с объектом на строку, массив не соответствует схеме записи.
Допустим ли перевод строки в конце файла?
Да. Последний перевод строки завершает запись. Дополнительная пустая строка уже нарушает формат.
Проверяет ли JSON-парсер поля API?
Парсер проверяет синтаксис. Для полей нужна отдельная проверка схемы и правил маршрута.
Зачем хранить идентификатор вне файла?
Он связывает результат с исходной задачей и версией данных при частичном повторе и разном порядке выдачи.