Qwen OCR распознаёт текст на фотографиях и сканах, извлекает поля из счетов и удостоверений, восстанавливает таблицы в HTML, формулы и структуру документов в LaTeX, а также возвращает координаты строк для последующей разметки. Пользователь загружает изображение или PDF, выбирает подходящую задачу, при необходимости задаёт собственные поля и получает обычный текст, JSON либо структурированный код, который можно проверить и передать в рабочую систему.

Рабочая область построена вокруг пары входной файл — инструкция. Слева или в верхней части формы выбирают изображение, ниже уточняют, что именно нужно прочитать, а справа появляется результат. Для простого перепечатывания достаточно команды вывести только текст; для накладной полезнее перечислить поля и потребовать JSON; для научной страницы лучше сразу запросить LaTeX. Такой выбор формата до запуска сокращает ручную правку после распознавания.

На качество сильнее всего влияют читаемость исходника, масштаб мелкого шрифта, поворот страницы и точность формулировки задания. Qwen OCR умеет корректировать наклон, увеличивать или уменьшать изображение перед обработкой и отделять распознавание текста от более сложного извлечения данных. Однако итог нельзя без проверки отправлять в бухгалтерию, реестр или архив: неясные символы, печати, блики и плотные таблицы остаются основными источниками ошибок.

Как устроен рабочий процесс Qwen OCR

Обычный сеанс начинается с выбора режима распознавания. Для фотографии объявления, письма или страницы книги подходит вывод сплошного текста. Для документа со сложной компоновкой выбирают разбор структуры, чтобы модель сохранила заголовки, таблицы и формулы. Для квитанции или удостоверения задают перечень полей: номер, дата, сумма, организация, фамилия и другие значения. Разделение задач важно, потому что одна и та же страница может быть прочитана по-разному: как последовательность строк, как набор координат, как таблица или как словарь реквизитов.

После загрузки файл проходит предварительное масштабирование. Маленькие изображения увеличиваются до минимального объёма пикселей, а чрезмерно крупные уменьшаются до верхнего порога. Пользователь может влиять на эти границы через параметры min_pixels и max_pixels. Увеличение верхнего порога помогает сохранить мелкий шрифт, но повышает число входных токенов, время обработки и стоимость запроса. Слишком агрессивное уменьшение, напротив, превращает тонкие знаки, десятичные разделители и индексы в трудноразличимые пятна.

Результат возвращается вместе со служебными данными о запросе и расходе токенов. В интерактивной форме пользователь видит ответ сразу, а при программном вызове получает объект, который можно разобрать автоматически. Удобнее заранее решить, куда пойдёт результат: в поле CRM, электронную таблицу, индекс полнотекстового поиска, LaTeX-редактор или систему контроля документов. Тогда формат ответа и проверочные правила задаются до распознавания, а не после него.

Первый запуск в Model Studio

Для доступа к форме распознавания требуется учётная запись Alibaba Cloud и активированный Model Studio. В панели выбирают регион, затем раздел визуальных моделей и Qwen OCR. Регион важен не только для задержки: ключи API и адреса вызова привязаны к рабочему пространству и площадке. Если ключ создан в одном регионе, а запрос отправлен на адрес другого, сервис отвечает ошибкой авторизации или не находит модель.

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

При создании ключа не вставляйте его в скриншоты, инструкции и исходный код. В приложении ключ лучше хранить в переменной окружения DASHSCOPE_API_KEY или в защищённом хранилище секретов. Если доступ выдаётся команде, полезно разделить рабочие пространства и ключи по проектам: так проще ограничивать права, отслеживать расход и отзывать один скомпрометированный ключ, не останавливая остальные процессы.

Создание и проверка API-ключа

Страница My API Key показывает идентификатор ключа, рабочее пространство, описание, дату создания и действия просмотра или удаления. Сразу после создания запишите назначение ключа в описании: например, архив договоров — тест или счета — рабочая обработка. Без такого обозначения через несколько месяцев трудно понять, какой сервис перестанет работать после удаления старой записи.

Проверку лучше проводить коротким запросом к одному изображению. Если ответ приходит, но модель не распознаёт файл, проблема обычно находится не в ключе, а в адресе изображения, MIME-типе или структуре сообщения. Если ответ содержит отказ в авторизации, проверьте регион, имя переменной окружения, отсутствие лишних пробелов и то, что ключ создан в том же рабочем пространстве, которое указано в базовом адресе.

Для производственного приложения не выводите полный ключ в журналы. Достаточно сохранять последние четыре символа, идентификатор запроса, модель, длительность и код ошибки. Такой журнал позволяет связать сбой с конкретной конфигурацией, но не раскрывает секрет человеку, который имеет доступ только к логам.

Какие входные файлы поддерживаются

Для изображений ниже 4K поддерживаются BMP, JPEG, PNG, TIFF, WebP и HEIC. При разрешении от 4K до 8K безопаснее использовать JPEG или PNG: для этого диапазона документация ограничивает набор именно этими форматами. Ширина и высота должны быть больше 10 пикселей, а отношение сторон не должно превышать 200 к 1 в любую сторону. Это исключает практически пустые полосы, чрезмерно длинные панорамы и ошибочно обрезанные фрагменты.

Изображение не должно превышать 15,68 миллиона пикселей. При передаче по публичному адресу или локальному пути допустимый размер зависит от выбранной модели, а Base64-строка ограничена 10 МБ. Base64 увеличивает объём данных примерно на треть, поэтому файл, который укладывается в лимит как обычная загрузка, может не пройти после кодирования. Для крупных сканов рациональнее использовать временный защищённый URL или загрузку через поддерживаемый файловый механизм.

PDF обрабатывается как документ, однако для надёжного контроля полезно понимать его внутреннее устройство. Если PDF уже содержит текстовый слой, обычное извлечение текста часто быстрее и точнее OCR. Qwen OCR особенно полезен для сканов, фотографий страниц, смешанных документов и случаев, когда нужно восстановить таблицы, формулы или реквизиты. Для длинного PDF стоит заранее решить, обрабатывать его целиком или разбить на страницы, чтобы ограничить объём одного ответа и упростить повторную обработку неудачной страницы.

Подготовка скана перед распознаванием

Лучший исходник — ровная страница с равномерным освещением и без сильного JPEG-сжатия. Для архивных документов предпочтителен PNG: он не добавляет блочные артефакты вокруг тонких букв и линий таблиц. Фотографию с телефона стоит обрезать по границам листа, убрать лишний стол и фон, выправить перспективу и проверить резкость на мелком тексте. Увеличение размытого изображения не возвращает потерянные детали, поэтому важнее переснять страницу, чем искусственно растянуть её в редакторе.

Шум можно уменьшить медианным или усредняющим фильтром, но фильтрацию нельзя применять без просмотра результата. Сильное сглаживание уничтожает точки над буквами, запятые, тонкие индексы и элементы печатей. Неравномерное освещение исправляют локальным выравниванием контраста. При этом нужно сохранить различие между светло-серыми строками и фоном: превращение страницы в жёсткое чёрно-белое изображение иногда сливает соседние символы.

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

Обычное распознавание текста

Задача text_recognition предназначена для китайского и английского текста и возвращает обычную строку без обязательной разметки. В интерактивной форме достаточно потребовать вывести только содержимое изображения. Такая формулировка уменьшает риск, что модель добавит пояснение, пересказ или Markdown-рамку. Для русского, французского, немецкого и других поддерживаемых языков используется многоязычный режим.

Обычный текст удобен для полнотекстового поиска, чернового копирования и последующей языковой обработки. Он не гарантирует сохранение колонок, табличных границ и точной геометрии. Если порядок строк критичен, лучше перейти к высокоточному распознаванию с координатами или к разбору документа. Иначе две колонки могут слиться в одну последовательность, а подпись сбоку окажется между строками основного текста.

После получения результата проверьте числа, похожие символы и переносы. Частые пары ошибок — латинская O и цифра 0, I и 1, B и 8, кириллическая С и латинская C. Для номеров договоров и счетов полезно применять регулярные выражения, проверку длины и контрольную сумму, если она предусмотрена форматом. Слова можно проверять словарём, но словарь не должен автоматически исправлять фамилии, артикулы и редкие технические термины.

Многоязычное распознавание и русский текст

Встроенный многоязычный режим поддерживает арабский, французский, немецкий, итальянский, японский, корейский, португальский, русский, испанский и вьетнамский языки. Он возвращает обычный текст и подходит для вывесок, этикеток, паспортных страниц, многоязычных инструкций и сканов, где кроме китайского или английского присутствует другой алфавит. Если на странице смешаны языки, в инструкции полезно прямо указать, что нужно сохранить исходное написание и не переводить текст.

Русский документ следует проверять на смешение кириллицы и латиницы. Внешне одинаковые буквы А, В, Е, К, М, Н, О, Р, С, Т, Х могут иметь разные коды Unicode. Для обычного чтения это незаметно, но поиск, сравнение реквизитов и электронная подпись могут не сработать. После OCR разумно нормализовать пробелы и кавычки, а для идентификаторов дополнительно проверять алфавит каждого поля.

Если модель переводит отдельные фразы вместо дословной передачи, укажите: Сохрани язык, регистр, пунктуацию и порядок строк; не переводи и не исправляй. Для двуязычной таблицы можно запросить JSON с отдельными полями original и translation, но это уже сочетает OCR и языковую генерацию. В критичных документах перевод следует отделять от распознавания: сначала получить точную транскрипцию, затем запускать перевод отдельным шагом.

Высокоточное распознавание и координаты строк

Режим advanced_recognition возвращает не только текст, но и положение каждой строки. В массиве words_info присутствуют текст, четыре вершины области location и описание повёрнутого прямоугольника rotate_rect. Координаты позволяют нарисовать рамки на исходнике, подсветить найденную строку, связать значение с зоной документа или построить интерфейс ручной проверки.

Для редактирования персональных данных координаты особенно важны: простой текст не показывает, где находится фамилия или номер. Однако рамку нельзя принимать на веру. Проверьте, охватывает ли она всю строку, не задевает ли соседний текст и соответствует ли масштабу исходного изображения. Если перед распознаванием картинка была изменена, координаты надо пересчитать обратно к первоначальным размерам.

Поворотный прямоугольник удобен для наклонных этикеток и фотографий. Угол следует трактовать в соответствии с форматом ответа, а не как произвольный CSS-поворот. Для отображения рамок полезно сначала использовать официальный пример draw_bbox.py, затем перенести логику в свой стек. Контрольный тест должен включать горизонтальные, вертикальные и диагональные строки, иначе ошибка знака угла проявится только на редком документе.

Автоматическое исправление поворота

Параметр enable_rotate включает коррекцию ориентации до распознавания. Он полезен для фотографий, сделанных боком, и документов, которые сканер сохранил с поворотом на 90 или 180 градусов. В интерактивном режиме эту функцию следует сравнить с ручным поворотом: на странице с несколькими направлениями текста автоматика может выбрать ориентацию, удобную для основной части, но ухудшить подписи на полях.

Если поворот исправлен, а строки всё равно идут под углом, проблема может быть в перспективном искажении. enable_rotate не заменяет выравнивание трапеции, когда верхний край листа заметно короче нижнего. Сначала исправьте перспективу или переснимите страницу параллельно плоскости документа, затем включайте автоматический поворот для остаточного наклона.

При пакетной загрузке полезно сохранять флаг, был ли применён поворот, и миниатюру нормализованной страницы. Оператор проверки должен видеть именно тот вариант, который анализировала модель. Иначе текст и координаты будут сопоставляться с оригиналом другой ориентации, что создаст ложное впечатление неправильной разметки.

Извлечение реквизитов в JSON

Задача key_information_extraction предназначена для чеков, удостоверений, форм и других документов с повторяемыми полями. В режиме пользовательской схемы передаётся result_schema: имена полей задаются заранее, а модель заполняет значения. Поддерживается вложенность до трёх уровней, поэтому можно описать адрес как объект, позиции счёта как список и итоговые суммы как отдельный блок.

Схема должна быть максимально однозначной. Поле номер без контекста может означать номер документа, заказа, счёта или телефона. Лучше использовать invoice_number, contract_number, phone_number и дополнить инструкцию русскими пояснениями. Для списка товаров задайте шаблон элемента с наименованием, количеством, единицей, ценой и суммой. Если структура ожидается всегда, валидируйте ответ JSON Schema и отклоняйте запись, где отсутствуют обязательные поля или типы не совпадают.

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

Как проектировать схему полей

Начните с минимального набора, который реально используется дальше. Каждый лишний ключ увеличивает объём ответа и создаёт ещё одну точку контроля. Для счёта обычно достаточно номера, даты, поставщика, покупателя, валюты, итоговой суммы, налога и строк товаров. Для пропуска — фамилии, имени, номера, даты действия и организации. Поля, которых на документе может не быть, помечайте как допускающие пустое значение и отдельно различайте не найдено и на изображении написано пусто.

Даты лучше приводить к единому формату только после сохранения исходной строки. Модель может вернуть 03/04/26, и без контекста невозможно уверенно решить, третье апреля это или четвёртое марта. Храните raw_date и normalized_date; нормализацию выполняйте по стране, языку и типу документа. Аналогично поступайте с суммами: отдельно сохраняйте исходное написание, валюту и числовое значение.

Для персональных данных включите правило не домысливать закрытые символы. Если часть номера перекрыта бликом или маской, лучше получить вопросительный знак или null, чем правдоподобное, но вымышленное значение. После OCR можно отправить запись на ручную проверку, если поле содержит знак неопределённости, не проходит контрольную сумму или конфликтует с другой частью документа.

Распознавание чеков, билетов и удостоверений

Qwen OCR содержит шаблоны для множества распространённых документов: удостоверений личности, паспортов, водительских документов, транспортных билетов, банковских и налоговых форм. Наличие шаблона не отменяет проверку конкретного макета. Один и тот же вид документа может отличаться по году выпуска, региону, языку, расположению печатей и защитных элементов.

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

Удостоверения требуют повышенного внимания к конфиденциальности. Не используйте реальные документы в демонстрационных скриншотах и общих тестовых пространствах. Ограничьте срок хранения входных файлов и ответов, маскируйте номера в логах и разделяйте права просмотра. Для полей с высокой юридической значимостью задайте обязательную ручную сверку по изображению.

Таблицы: вывод в HTML

Задача table_parsing преобразует таблицу в HTML с элементами table, tr и td. Такой результат можно показать в браузере, разобрать библиотекой DOM или преобразовать в CSV и электронную таблицу. В инструкции важно потребовать сохранить порядок слева направо и сверху вниз, а для объединённых ячеек — корректно использовать colspan и rowspan, если они присутствуют в ответе.

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

Сложнее всего распознаются таблицы без явных линий, с многострочными заголовками, повернутым текстом и примечаниями внутри ячеек. Иногда лучше вырезать таблицу в отдельное изображение и запускать распознавание отдельно от остальной страницы. Если таблиц несколько, обработка каждого фрагмента отдельным запросом упрощает сопоставление и снижает риск, что строки двух блоков смешаются.

Формулы и математические выражения

Режим formula_recognition возвращает LaTeX-представление формулы. Он полезен для конспектов, учебников, статей и рукописных вычислений. Модель должна получить изображение именно формулы или чётко указанную область страницы: если вокруг много текста, ответ может включить лишние пояснения или выбрать не то выражение.

Проверяйте индексы, степени, границы суммирования, дроби и скобки. Внешне похожие конструкции могут давать математически разные результаты: x_1 и x^1, \sum_{i=1}^{n} и \sum_i^n, вертикальная черта как модуль или условие. Полезно отрендерить полученный LaTeX и сравнить изображение с исходником, а не читать код только глазами.

Для страницы с несколькими формулами лучше получить структурный разбор документа или разрезать страницу на блоки. Каждому блоку присвойте идентификатор и сохраните координаты. Тогда исправление одной формулы не нарушит порядок остальных, а редактор сможет показать оригинал рядом с отрендеренным результатом.

Разбор структуры документа

Задача document_parsing предназначена для сканов и страниц PDF, где нужно сохранить не только слова, но и роль элементов: заголовки, обычные абзацы, подписи, таблицы и формулы. Результат возвращается как LaTeX-текст. Такой формат удобен для научных документов и дальнейшей верстки, но требует компиляции и очистки перед публикацией.

Структурный разбор не равен точному восстановлению оригинального дизайна. Он стремится передать логическую последовательность и типы элементов, а не повторить шрифты, отступы и декоративные рамки. Для архивной копии храните исходный PDF рядом с распознанным текстом; для редактируемой версии используйте LaTeX как основу и вручную проверяйте разрывы разделов, подписи рисунков и ссылки.

Длинный документ лучше обрабатывать страницами или логическими разделами. Один огромный ответ труднее повторно получить после ошибки, а ограничение длины вывода может обрезать конец. При постраничной схеме сохраняйте номер страницы и добавляйте маркеры продолжения абзацев. После объединения проверьте переносы слов, нумерацию формул и таблиц, а также заголовки, которые могли повториться на каждой странице.

Работа с PDF на практике

Перед OCR определите, действительно ли страницы являются изображениями. Если текст выделяется курсором и корректно копируется, сначала используйте обычный PDF-парсер. OCR оставьте для сканированных страниц, встроенных фотографий, повреждённой кодировки и сложной структуры. Гибридный процесс быстрее: текстовые страницы проходят прямое извлечение, сканы отправляются в Qwen OCR, а итог объединяется по порядку.

Для многостраничного PDF создайте очередь с идентификатором документа и номером страницы. Ошибочная страница должна повторяться независимо, без повторной оплаты за уже обработанные. Результаты сохраняйте атомарно: сначала во временную запись, затем в основную базу после успешной валидации. Если вывод обрывается, пометьте страницу как неполную и не объединяйте её автоматически.

После распознавания можно создать поисковый индекс или новый PDF с текстовым слоем, но Qwen OCR сам по себе не предоставляет готовую кнопку экспорта в DOCX или сборки PDF/A. Эти операции выполняет внешнее приложение. Для каталога документов полезно хранить три сущности: оригинал, нормализованное изображение и проверенный текст. Это позволяет повторить обработку с другими параметрами без потери исходника.

Несколько изображений в одном запросе

Сервис поддерживает ввод нескольких изображений, но объединять их стоит только тогда, когда они образуют один логический контекст: разворот, лицевая и оборотная стороны карты, чек с продолжением или несколько кадров одной таблицы. В инструкции укажите порядок и назначение каждого изображения. Без явной нумерации модель может смешать поля или не объяснить, с какой страницы взято значение.

Для независимых документов пакетный API обычно предпочтительнее одного многоизображенческого сообщения. Он сохраняет отдельный статус каждой задачи и облегчает повтор. Один общий запрос может завершиться ошибкой из-за одного повреждённого файла, а длинный ответ сложнее сопоставить с входами.

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

Как писать инструкцию для модели

Хорошая инструкция определяет задачу, формат и поведение при неопределённости. Вместо распознай документ напишите: Выведи текст в исходном порядке, не переводи, сохрани регистр; неразборчивый символ замени знаком вопроса; не добавляй пояснений. Для JSON перечислите ключи, типы и допустимые пустые значения. Для таблицы уточните, нужны ли объединённые ячейки и заголовки.

Не смешивайте слишком много целей в одном запросе. Просьба одновременно распознать текст, перевести, кратко пересказать, классифицировать и найти ошибки повышает риск пропусков. Надёжнее разделить процесс: OCR, затем валидация, затем перевод или анализ. Между этапами сохраняйте исходный результат, чтобы можно было понять, где появилась ошибка.

Инструкция должна быть устойчива к документам без ожидаемого поля. Запретите догадки и задайте явное значение null. Если документ другого типа, полезно возвращать document_type и confidence_note, но числовую уверенность нельзя считать калиброванной вероятностью, если сервис не предоставляет такую метрику. Практичнее использовать формальные признаки: поле отсутствует, значение не проходит шаблон, текст содержит знак неопределённости.

Фиксированное системное сообщение

Qwen OCR использует внутреннее системное сообщение и не принимает пользовательскую замену. Все указания нужно передавать в сообщении пользователя. Это влияет на архитектуру интеграции: если приложение привыкло задавать общие правила через роль system, для OCR их следует перенести в текст запроса или использовать встроенные задачи.

Храните шаблоны инструкций в версии конфигурации, а не размазывайте строки по коду. Для каждого типа документа заведите идентификатор шаблона, схему ответа и набор тестов. Изменение формулировки может повлиять на ключи JSON, порядок строк и склонность модели добавлять пояснения, поэтому шаблон следует выпускать вместе с миграцией парсера.

В многооборотном режиме допустимы уточняющие сообщения, но для стабильной автоматизации лучше, чтобы один запрос был самодостаточным. Диалог полезен оператору, который хочет спросить о конкретном поле или исправить неоднозначность. Машинная очередь должна получать воспроизводимый ответ по фиксированным входам и инструкции.

Проверка и нормализация результата

Первая проверка — синтаксическая. JSON должен разбираться стандартным парсером, HTML — ограниченным DOM-парсером, LaTeX — хотя бы проходить базовую компиляцию или линтер. Если модель оборачивает JSON в Markdown-блок, удаляйте ограждение только после проверки, что внутри находится один объект. Нельзя извлекать первую найденную фигурную скобку без контроля конца: в тексте могут встречаться примеры и дополнительные пояснения.

Вторая проверка — предметная. Даты должны существовать, суммы иметь допустимый диапазон, коды соответствовать регулярным выражениям, а связанные поля не противоречить друг другу. Для счёта проверяют итог, налог и сумму позиций; для билета — согласованность даты и маршрута; для удостоверения — срок действия и длину номера. Нарушение не означает автоматически ошибку OCR, но требует ручной сверки.

Третья проверка — визуальная. Оператор видит исходник, распознанное значение и, при наличии, рамку строки. Интерфейс должен позволять исправить значение и сохранить, кто и когда внёс правку. Эти исправления полезно собирать как тестовый набор, но не следует автоматически обучать на них внешнюю модель без проверки качества и разрешения на использование данных.

Подключение через DashScope SDK

DashScope предоставляет полный доступ к встроенным задачам OCR и параметру автоматического поворота. В Python сообщение содержит роль user и элементы content с изображением. В ocr_options задаётся task, а для пользовательского извлечения — task_config и схема. Базовый адрес зависит от региона и рабочего пространства.

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

Обновление SDK может менять доступные поля и способы сериализации, поэтому фиксируйте диапазон версии зависимости и прогоняйте тесты перед обновлением. Особенно важны тесты на content, ocr_result, usage и finish_reason. Если приложение молча ожидает поле text, а специализированная задача вернула данные в ocr_result, результат может быть ошибочно принят за пустой.

import os
import dashscope

dashscope.base_http_api_url = "REGIONAL_WORKSPACE_ENDPOINT"
messages = [{
    "role": "user",
    "content": [{
        "image": "file:///absolute/path/page.png",
        "enable_rotate": True
    }]
}]
response = dashscope.MultiModalConversation.call(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    model="QWEN_OCR_MODEL_ID",
    messages=messages,
    ocr_options={"task": "advanced_recognition"}
)
print(response)

OpenAI-совместимый интерфейс

OpenAI-совместимый вызов удобен, если приложение уже использует client.chat.completions.create и формат image_url. Он сокращает объём изменений в инфраструктуре, но не выводит все специализированные функции отдельными параметрами. Встроенные задачи и поворот приходится имитировать точной инструкцией или переходить на DashScope для полного набора возможностей.

При передаче изображения можно использовать публичный URL или строку data:image/...;base64. MIME-тип в префиксе должен совпадать с реальным форматом. Если PNG закодирован как image/jpeg, сервер может отклонить запрос или декодировать его непредсказуемо. Для локального файла удобнее прочитать байты, определить тип и только затем сформировать data URL.

Совместимость протокола не означает идентичность поведения разных моделей. Не переносите параметры, предназначенные для текстового генератора, без проверки. Qwen OCR имеет фиксированное системное сообщение, специализированные форматы и собственные лимиты изображений. Отдельный адаптер с явным контрактом надёжнее, чем универсальная функция, которая отправляет все возможные поля каждому провайдеру.

Локальный путь, URL и Base64

Локальный путь в DashScope SDK задаётся схемой file:// и абсолютным адресом. На Linux и macOS путь выглядит как file:///home/user/page.png; в Windows правила различаются между Python и Java, поэтому используйте примеры документации и тестируйте пробелы и не-ASCII символы. Относительный путь зависит от текущей папки процесса и часто ломается после развёртывания.

Публичный URL должен быть доступен серверу без авторизации через браузерную сессию. Временная ссылка должна жить дольше максимального времени запроса и не блокировать диапазоны адресов облака. После обработки ссылку следует отозвать. Не передавайте постоянный публичный адрес к архиву персональных документов.

Base64 полезен для небольших файлов и закрытой сети, но увеличивает размер запроса и расход памяти. Не сохраняйте полную строку в логах. Перед отправкой проверяйте размер исходных байтов, формат и возможность открыть изображение локальной библиотекой. Это отделяет повреждение файла от ошибки сервиса.

Масштабирование min_pixels и max_pixels

Параметр min_pixels задаёт нижний порог: маленькое изображение увеличивается, пока число пикселей не достигнет значения. Обычно дефолт достаточен. Искусственное увеличение не создаёт новых деталей, но помогает модели получить достаточное визуальное представление для небольшого логотипа, номера или фрагмента.

max_pixels ограничивает верхний объём. Если на странице не читается мелкий текст, порог можно повысить, однако это увеличивает число токенов. Изменение следует оценивать на контрольном наборе: сравнивайте точность конкретных полей, задержку и usage.image_tokens. Самый большой предел не всегда лучше, потому что шум и декоративные элементы тоже занимают визуальные токены.

Для документов разного типа создайте профили. Чек с крупными строками может обрабатываться с умеренным пределом, а инженерный чертёж с мелкими обозначениями требует большего. Профиль выбирают после классификации документа или по размеру шрифта. Так расходы контролируются точнее, чем единым максимальным значением для всех файлов.

Расход токенов и стоимость

Сервис учитывает входные и выходные токены. Изображение переводится в визуальные токены после масштабирования; для ряда моделей один токен соответствует блоку 32 на 32 пикселя, плюс служебные маркеры. Фактический расчёт нужно брать из usage ответа, а локальную формулу использовать только для предварительной оценки.

Сократить расход помогают обрезка лишних полей, разделение большого листа на нужные зоны и выбор подходящего max_pixels. Но чрезмерная обрезка опасна: подпись поля может остаться за краем, и значение потеряет контекст. Для форм лучше сохранять пару метка — значение, даже если интересует только значение.

Для прогнозирования бюджета запишите среднее число входных и выходных токенов по каждому классу документов и умножьте на ожидаемый поток. Отдельно учитывайте повторные запросы и ручные проверки. Бесплатная квота ограничена сроком и регионом, поэтому рабочий расчёт должен опираться на обычную тарификацию, а не на временный бонус.

Пакетная обработка

Для большого объёма, где ответ не нужен немедленно, используется Batch API. Задания отправляются асинхронно, сервис формирует файл результатов и файл ошибок. Такой режим подходит для оцифровки архива, ночной обработки счетов и подготовки поискового индекса.

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

Пакетный процесс нуждается в отчёте: сколько задач принято, завершено, отклонено по формату, не прошло OCR и отправлено на ручную проверку. Одного статуса готово недостаточно. Для архива полезно сохранять хэш входного файла, чтобы повторная загрузка той же страницы не создавала дубликат и лишний расход.

Развёртывание собственного веб-интерфейса

Официальный пример показывает, как разместить форму загрузки поверх Qwen OCR с помощью Function Compute. Пользователь выбирает файл, вводит инструкцию и видит результат в соседней области. Такой интерфейс можно адаптировать под конкретный процесс: вместо свободного промпта показать список типов документов и набор обязательных полей.

Серверная функция хранит ключ API в переменной окружения, принимает файл, при необходимости размещает его во временном объектном хранилище и вызывает модель. Клиентская часть не должна получать секрет. Ограничьте тип и размер файла до загрузки, добавьте проверку MIME на сервере и удаляйте временный объект после завершения.

В форме полезно показывать исходное изображение рядом с ответом, индикатор обработки и понятную ошибку. Не выводите пользователю необработанный стек исключения. Для долгих запросов используйте идентификатор задания и повторный опрос статуса, чтобы обновление страницы не создавало второй платный вызов.

Просмотр результата в веб-форме

В демонстрационном интерфейсе слева остаются загрузка и поле инструкции, а справа отображается исходный документ и извлечённые данные. Такая компоновка удобна для ручной сверки. В рабочей версии стоит добавить масштабирование изображения, переход к найденной области, подсветку изменённых полей и кнопку подтверждения.

Результат нельзя показывать только как картинку или длинный блок текста. Для JSON полезна форма с отдельными полями, для таблицы — безопасный просмотр HTML, для LaTeX — отрендерованное выражение и исходный код. Оператор должен видеть, что именно будет сохранено в базе, а не только красивое представление.

После исправления сохраняйте первоначальный ответ модели и отредактированное значение раздельно. Это помогает оценивать качество, находить типовые ошибки и откатывать случайную правку. Журнал должен включать идентификатор запроса, время, пользователя и причину изменения.

Конфигурация Function Compute

В Function Compute задаются среда выполнения, объём памяти, тайм-аут, доступ в интернет и переменные окружения. Для OCR-прокси особенно важны DASHSCOPE_API_KEY, адрес объектного хранилища и регион. Тайм-аут должен учитывать загрузку файла и максимальную длительность ответа, но его не следует завышать без контроля: зависшая функция будет дольше занимать ресурсы.

Переменные USER_NAME и USER_PASSWORD в демонстрационном проекте позволяют включить простую защиту формы, однако для рабочего сервиса лучше использовать корпоративную аутентификацию и разграничение ролей. Пароль в переменной окружения не должен отображаться в журналах или клиентском коде. Секреты предпочтительно хранить в специализированном менеджере ключей.

После изменения конфигурации выполните тест с небольшим файлом и тест с максимально допустимым. Проверьте память, время и удаление временных объектов. Если функция перезапускается на большом Base64, передавайте файл потоком или через хранилище, а не собирайте несколько копий байтов в памяти.

Контроль функции и журналов

Список функций показывает имя, среду выполнения и активность. Название должно однозначно описывать назначение, например ocr-invoices-prod, а не общий ocr. Для тестовой и рабочей среды создавайте разные функции, ключи и хранилища. Это предотвращает попадание реальных документов в экспериментальный процесс.

В журнал записывайте длительность этапов: получение файла, загрузка, вызов модели, разбор ответа и сохранение. Если весь запрос медленный, такая разбивка показывает источник задержки. При ошибке храните код, request_id, размер и формат изображения, но не полный текст документа и не API-ключ.

Метрики должны включать долю успешных ответов, повторов, ручной проверки и среднее число токенов. Резкий рост output_tokens может означать, что модель начала добавлять пояснения из-за изменённого шаблона. Резкий рост image_tokens часто связан с новым разрешением входных файлов или слишком высоким max_pixels.

Публикация через собственный домен

Для пользовательского адреса в Function Compute создаётся привязка домена к функции, версии и маршруту. Сначала домен добавляют в список, затем указывают путь и обработчик. После этого DNS направляют на выданный CNAME. Ошибка в маршруте приводит к 404, а неверная версия может открыть старую форму с несовместимой схемой.

Используйте HTTPS и ограничьте максимальный размер тела запроса на уровне шлюза. Добавьте заголовки безопасности, запрет встраивания формы на чужие сайты и защиту от межсайтовых запросов. Если форма доступна извне, установите ограничение частоты, иначе злоумышленник сможет расходовать токены через ваш ключ.

При обновлении функции публикуйте версию и переключайте домен после теста, а не меняйте рабочий код без точки возврата. Для схем JSON нужна обратная совместимость: старый клиент не должен падать, если появилось необязательное поле. Несовместимое изменение выпускайте под новым маршрутом.

Настройка маршрута домена

В форме привязки задаются доменное имя, путь, функция и версия или алиас. Маршрут / подходит для единственного приложения, а несколько инструментов лучше разделить: /ocr, /review и /api. Алиас вроде stable позволяет переключать версию функции без изменения DNS.

После создания проверьте не только главную страницу, но и загрузку файла, обратный вызов и статические ресурсы. Относительные пути могут работать на системном адресе и ломаться под префиксом /ocr. В клиентском коде используйте базовый путь из конфигурации.

Для диагностики DNS сравните CNAME, сертификат и регион функции. Если браузер открывает старую страницу, очистите CDN-кэш и проверьте TTL. Не снижайте TTL до минимума постоянно: это увеличивает число DNS-запросов без пользы после завершения миграции.

Типовые ошибки входного файла

Ошибка формата возникает, когда расширение не совпадает с содержимым, MIME-тип указан неверно или файл повреждён. Откройте изображение локально библиотекой, определите фактический формат и пересохраните без метаданных. Простое переименование .tiff в .jpg не преобразует данные.

Ошибка размера решается уменьшением разрешения или выбором подходящего способа передачи. Не уменьшайте скан до тех пор, пока текст становится нечитаемым. Лучше обрезать пустые поля, разделить разворот на страницы и сохранить PNG или качественный JPEG. Для Base64 учитывайте увеличение объёма.

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

Ошибки авторизации и региона

При отказе в доступе проверьте, активирован ли Model Studio, создан ли ключ и соответствует ли он рабочему пространству. Затем сравните регион ключа, модели и базового адреса. Адрес из примера нельзя копировать без замены WorkspaceId и региона.

Если ключ работает в интерактивном тесте, но не в функции, проверьте имя переменной, права секретного хранилища и факт публикации новой конфигурации. Контейнер может использовать старую ревизию. Временно выведите только наличие переменной и последние четыре символа, затем удалите диагностический лог.

При ограничении прав RAM убедитесь, что роль функции может читать нужный секрет и объектное хранилище. Не выдавайте широкие административные права ради быстрого исправления. Минимальный набор разрешений уменьшает последствия компрометации.

Обрезанный или пустой ответ

Пустой ответ может означать, что приложение читает не то поле. Специализированная задача через DashScope возвращает данные в ocr_result, тогда как обычный вызов может содержать text. Сначала сохраните полный ответ в защищённый диагностический файл и проверьте структуру, finish_reason и usage.

Обрезание возникает при слишком длинном выводе. Для большой таблицы или документа разделите страницу на области, сократите лишние пояснения и обрабатывайте страницы отдельно. Увеличение лимита вывода доступно не во всех конфигурациях и может требовать согласования, поэтому архитектура не должна зависеть от единственного огромного ответа.

Если модель повторяет строки, ограничьте инструкцию требованием вывести результат один раз и добавьте постобработку повторяющихся блоков. Автоматическое удаление дубликатов применяйте осторожно: в счёте одинаковые позиции могут быть реальными. Сравнивайте не только текст, но и координаты или номер строки.

Галлюцинации и неразборчивый текст

Документация предупреждает, что мелкий или низкокачественный текст может приводить к вымышленным фрагментам. Это отличается от обычной опечатки: модель способна вернуть правдоподобное слово, которого нет на странице. Поэтому инструкция должна запрещать догадки и предписывать знак вопроса или null для неясного символа.

Критичные поля проверяются по изображению и формальным правилам. Если номер банковской карты, документа или счёта не проходит длину и контрольную сумму, запись не исправляют наиболее вероятным вариантом. Её отправляют оператору. Для повторного запроса можно вырезать область, повысить max_pixels и попросить распознать только один фрагмент.

Вопросы, не связанные с извлечением текста, модель выполняет без гарантии точности. Не используйте OCR-вызов для юридической интерпретации, проверки подлинности документа или определения личности. Эти задачи требуют отдельных систем и процедур.

Безопасность документов

Перед отправкой определите класс данных. Паспорта, банковские реквизиты, медицинские формы и договоры могут подпадать под внутренние и законодательные ограничения. Убедитесь, что выбранный регион и договор с облачным провайдером соответствуют требованиям организации. Не загружайте конфиденциальный документ в личное тестовое пространство.

Срок хранения должен быть минимальным. Временный файл удаляется после обработки, а в журнале остаются хэш, размер, тип и идентификатор запроса. Ответ также может содержать персональные данные, поэтому его защита не менее важна, чем защита изображения. Маскируйте значения в аналитике и системе мониторинга.

Разделите роли: оператор видит документ и исправляет поля, разработчик видит технические метрики без содержимого, администратор управляет ключами. Экспорт массива документов должен требовать отдельного разрешения и фиксироваться в аудите.

Практический сценарий: входящие счета

Поток начинается с проверки типа файла и разделения PDF на страницы. Первая страница классифицируется как счёт, затем схема извлекает номер, дату, поставщика, покупателя, валюту, налог, итог и строки. Для каждой строки сохраняются наименование, количество, единица, цена и сумма.

Валидатор сравнивает сумму строк с итогом, нормализует валюту и проверяет номер поставщика по справочнику. Несоответствие не исправляется автоматически: оператор видит исходный фрагмент и поле. После подтверждения данные передаются в бухгалтерскую систему, а оригинал и проверенный JSON связываются одним идентификатором.

Для повторяющегося поставщика можно настроить профиль обрезки и правила, но не следует жёстко привязываться к координатам: макет счёта меняется. Qwen OCR полезен именно тем, что извлекает данные по смыслу и схеме; координаты применяются для проверки, а не как единственный способ найти поле.

Практический сценарий: архив договоров

Для архива важны полнотекстовый поиск и сохранение структуры. Страницы без текстового слоя отправляются на разбор документа, а текстовые страницы извлекаются обычным парсером. Заголовки, номера разделов и подписи сохраняются вместе с номером страницы.

После OCR текст проходит нормализацию переносов, но исходные дефисы и номера пунктов не удаляются без проверки. Поисковый индекс хранит ссылку на страницу и координаты строки, если они получены. Пользователь находит фразу и сразу открывает соответствующий участок скана.

Юридически значимый поиск не заменяет оригинал. Результат OCR используется как навигация и черновой текст. При цитировании сотрудник сверяет формулировку по изображению, особенно если документ плохо сохранился или содержит рукописные исправления.

Практический сценарий: научные статьи и формулы

Страницы разбираются в LaTeX с сохранением заголовков, абзацев, таблиц и формул. Для сложных формул можно выполнить отдельный запрос по вырезанному фрагменту и заменить соответствующий блок. Результат компилируется в изолированной среде, где запрещены опасные команды.

Ссылки, номера уравнений и подписи рисунков проверяются вручную. OCR может правильно прочитать формулу, но потерять номер или связать подпись с соседним рисунком. Полезно сравнивать отрендерованный PDF рядом с оригинальной страницей.

Если цель — сделать статью доступной для поиска, необязательно восстанавливать идеальную вёрстку. Достаточно точного текста и корректных формул. Если требуется повторная публикация, понадобится редакторская вычитка и оформление по стилю издания.

Практический сценарий: каталоги и этикетки

Фотографии этикеток часто сняты под углом и содержат отражения. Сначала исправляют перспективу, затем включают поворот и извлекают артикул, название, размер, состав, страну и штрихкод. Для артикула задаётся строгий шаблон, потому что одна ошибка символа создаёт другой товар.

Если на одном снимке несколько этикеток, их лучше обнаружить и вырезать отдельным этапом. Один общий ответ может смешать значения. Каждому фрагменту присваивается координата на исходной фотографии, чтобы оператор мог быстро проверить товар.

Для многоязычной упаковки сохраняйте оригинальные строки и перевод отдельно. Маркетинговые названия, единицы и юридические предупреждения нельзя автоматически заменять более естественным вариантом. OCR должен сначала передать написанное.

Практический сценарий: анкеты и формы

Форма делится на напечатанные подписи и заполненные значения. Схема задаёт поля, а координаты помогают показать оператору каждую область. Чекбоксы и подписи требуют отдельной проверки: модель может прочитать текст рядом, но не гарантирует правильное состояние отметки без специальной инструкции.

Если одно поле занимает несколько строк, схема должна допускать длинную строку или список. Не объединяйте адрес, комментарий и подпись в одно значение. Для обязательных полей валидатор проверяет наличие, а для дат и телефонов — формат.

Рукописный текст зависит от качества почерка. При неуверенности лучше отправлять поле на ручной ввод, чем многократно перезапрашивать всю страницу. Вырезанный фрагмент с повышенным разрешением иногда помогает, но повторный ответ всё равно проходит проверку.

Когда Qwen OCR подходит хуже

Для мгновенного распознавания тысяч коротких строк на CPU специализированный классический движок может быть дешевле и предсказуемее. Qwen OCR сильнее там, где требуется понять структуру, извлечь поля по смыслу, распознать таблицу или объединить текст с инструкцией. Простое массовое чтение идеально напечатанного текста не всегда оправдывает использование мультимодальной модели.

Для создания редактируемого DOCX с точным повторением макета понадобится дополнительный конвертер и ручная правка. Сервис возвращает текст, JSON, HTML или LaTeX, но не готовый офисный документ. Для полиграфической копии выбирайте программу, которая специализируется на сохранении вёрстки.

Для полностью закрытого контура без передачи данных в облако нужен локальный OCR. Qwen OCR в Model Studio требует сетевого вызова и учётной записи. Решение о применении должно учитывать политику данных, а не только качество распознавания.

Сравнение Qwen OCR с аналогами

Выбор зависит от того, нужен ли облачный разбор структуры, редактирование PDF, локальная работа или массовое распознавание. Qwen OCR выделяется сочетанием обычного текста, координат, JSON-схем, HTML-таблиц и LaTeX. Однако для правки страниц, сохранения в офисный формат или полностью автономной обработки удобнее специализированные инструменты.

Программа	Лучше подходит для	Главное ограничение
Qwen OCR	Извлечение текста, полей, таблиц и формул по инструкции	Требует облачного доступа и проверки ответа
PDF Commander	Редактирование, сборка и повседневная работа с PDF	Не предназначен для API-конвейеров OCR
ABBYY FineReader PDF	Распознавание с сохранением офисной вёрстки	Коммерческая лицензия и ресурсоёмкая обработка
PaddleOCR	Локальные и серверные OCR-конвейеры с открытым кодом	Интеграция и настройка требуют разработки
Tesseract OCR	Базовое локальное распознавание печатного текста	Слабее работает со сложной структурой документа
Google Cloud Vision OCR	Масштабируемое облачное чтение изображений и документов	Структурное извлечение требует дополнительной логики

Как выбрать между аналогами

Qwen OCR выбирают, когда документ нужно не просто перепечатать, а превратить в данные: извлечь реквизиты по схеме, получить HTML-таблицу, LaTeX или координаты. PDF Commander уместен, когда основная задача — открыть, исправить, объединить или подготовить PDF без разработки. ABBYY FineReader PDF полезен для офисной оцифровки с акцентом на редактируемую вёрстку.

PaddleOCR и Tesseract подходят для собственного локального конвейера, если команда готова настраивать модели, предобработку и постобработку. Google Cloud Vision OCR разумен в инфраструктуре Google Cloud и для стандартных облачных OCR-задач. Практический выбор делайте по десяти реальным документам и измеряйте точность ключевых полей, время, стоимость и долю ручной проверки, а не только качество одного красивого примера.

Контрольный список перед рабочим запуском

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

Добавьте синтаксическую и предметную валидацию, очередь ручной проверки и возможность повторить только одну страницу. Проверьте лимиты размера, тайм-ауты, частоту запросов и поведение при недоступности сервиса. Документируйте, где хранится оригинал, нормализованное изображение, ответ модели и исправленный результат.

Перед увеличением потока проведите нагрузочный тест и посчитайте токены. После запуска следите за изменением доли ошибок, средней длины ответа и ручных исправлений. Любое изменение инструкции, схемы, параметров или SDK прогоняйте через тот же контрольный набор.

• Определён формат результата для каждого типа документа.
• Неразборчивые символы не заменяются догадками.
• Ключи API не попадают в клиентский код и журналы.
• Ошибки одной страницы не запускают весь документ заново.
• Оператор видит исходник рядом с распознанным значением.
• Для критичных полей действуют форматные и арифметические проверки.
• Исходные файлы и временные ссылки удаляются по установленному сроку.

Частые вопросы

Можно ли просто загрузить фотографию и скопировать текст?

Да. Для китайского и английского используют обычное распознавание, для русского и других поддерживаемых языков — многоязычное. В инструкции попросите вывести только текст без перевода и комментариев.

Сохраняет ли Qwen OCR таблицу?

Специализированная задача возвращает HTML-таблицу. Перед использованием её нужно безопасно разобрать, проверить объединённые ячейки и числовые итоги.

Можно ли получить координаты слов?

Высокоточный режим возвращает области строк и повёрнутые прямоугольники. Их используют для подсветки и ручной проверки; координаты следует пересчитать, если изображение масштабировалось вне сервиса.

Что делать с неразборчивым символом?

Запретите модели угадывать и потребуйте вопросительный знак или null. Затем вырежьте область, увеличьте допустимое разрешение и отправьте поле оператору, если повтор остаётся неоднозначным.

Почему JSON иногда не разбирается?

Ответ может быть обёрнут в Markdown или содержать пояснение. Используйте встроенную задачу, жёстко задайте формат, удаляйте ограждение контролируемо и валидируйте JSON Schema.

Подходит ли сервис для русского языка?

Русский включён в многоязычный режим. После распознавания проверяйте смешение кириллицы и латиницы в кодах, фамилиях и номерах.

Можно ли получить DOCX?

Прямого экспорта DOCX нет. Сначала получают текст, HTML или LaTeX, затем преобразуют его внешним редактором или библиотекой.

Как снизить стоимость?

Обрезайте пустые поля, выбирайте разумный max_pixels, разделяйте задачи и используйте пакетную обработку для несрочного потока. Точность ключевых полей должна оставаться главным ограничением.

Нужно ли проверять результат вручную?

Для архивного поиска достаточно выборочного контроля, но юридические, финансовые и персональные данные требуют формальных проверок и ручной сверки при любом несоответствии.

Можно ли использовать один ключ во всех проектах?

Технически возможно, но безопаснее разделить ключи по средам и процессам. Так проще ограничивать права, считать расход и отзывать доступ без общего простоя.

Матрица диагностики качества

Симптом	Вероятная причина	Практическое действие
Пропущен мелкий текст	Слишком низкий max_pixels или размытый исходник	Вырезать область, повысить предел и сравнить с новым снимком
Колонки смешаны	Использован обычный текстовый режим	Перейти к разбору документа или координатам строк
Число заменено словом	Сжатие или блик на символе	Переснять, сохранить PNG и запретить догадки
JSON содержит пояснение	Недостаточно жёстко задан формат	Потребовать один JSON-объект и применить схему
Таблица теряет ячейки	Сложный заголовок или нет линий	Вырезать таблицу и проверить colspan/rowspan
LaTeX не компилируется	Потеряна скобка или спецсимвол	Запустить линтер и повторить только формулу
Координаты смещены	Изображение масштабировано после OCR	Пересчитать рамки к исходному размеру
Ответ обрывается	Слишком большой документ или таблица	Разделить по страницам и областям
Запрос отклонён	Неверный MIME, размер или регион	Проверить байты, лимиты, ключ и endpoint
Расход резко вырос	Поменялось разрешение или инструкция	Сравнить usage и вернуть профиль параметров
Одинаковые строки повторяются	Модель продолжила генерацию	Ограничить инструкцию и проверять дубли по координатам

Эту матрицу полезно встроить в регламент поддержки. Оператор сначала определяет симптом, затем проверяет входной файл и только после этого меняет параметры модели. Случайное повышение всех лимитов обычно увеличивает расход, но не исправляет перспективу, блик или неверную схему. Каждое изменение фиксируется вместе с примером до и после, чтобы команда не возвращалась к уже отвергнутым настройкам.

Регламент выборочной проверки

Для стабильного потока документов назначьте уровни контроля. Поля, влияющие на оплату, личность или юридические обязательства, проверяются всегда. Второстепенный текст можно проверять выборочно, но выборка должна включать разные поставщики, языки, устройства съёмки и качество бумаги. Если доля ошибок в выборке растёт, временно расширьте ручной контроль и найдите причину по типам документов.

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

Еженедельный отчёт включает число документов, страниц, повторных запросов, ручных исправлений и отказов. Ошибки группируются по причине: качество изображения, неподдерживаемый формат, неверный шаблон, неоднозначное поле, сбой сети или изменение макета. Такой отчёт показывает, что выгоднее: улучшить съёмку, изменить инструкцию, добавить правило или перевести конкретный тип документа на другой инструмент.

Правила хранения и воспроизводимости

Для каждого результата сохраняйте хэш исходного файла, идентификатор шаблона, параметры масштаба, выбранную задачу, идентификатор запроса и время. Без этих данных невозможно воспроизвести расхождение. Сам API-ключ сохранять не нужно; достаточно идентификатора рабочей конфигурации. Если политика запрещает хранить оригинал, оставьте безопасный контрольный фрагмент или синтетический тест с тем же макетом.

Изменение инструкции должно иметь номер ревизии. Новый шаблон сначала прогоняется параллельно старому на контрольном наборе, затем сравниваются точность ключевых полей, длина ответа и расход. Победа по одному показателю не гарантирует улучшение: более подробный JSON может быть точнее, но настолько дороже и сложнее для проверки, что общий процесс ухудшится.

При споре между результатами храните оба ответа и исходную область. Не выбирайте автоматически более длинный или грамотный текст. Решение принимает валидатор или оператор по изображению. Для повторного запуска используйте тот же файл и параметры; если результат меняется, пометьте поле как нестабильное и не доверяйте одиночному ответу.

План испытаний на реальных документах

Испытание начинают с разметки эталона. Два сотрудника независимо перепечатывают ключевые поля, затем расхождения сверяются по оригиналу. Это важно: без надёжного эталона невозможно понять, ошиблась модель или тестовая таблица. Для каждого поля фиксируют точное значение, допустимую нормализацию и уровень критичности.

Набор делят не случайно, а по источникам: сканер, телефон, мессенджер, электронный PDF, факс; отдельно отмечают язык, наличие печати, таблицы, рукописи, мелкого шрифта и поворота. Итоговая метрика должна показывать точность по каждой группе. Среднее значение скрывает проблему, если чистые страницы идеальны, а фотографии чеков почти всегда требуют ручной правки.

Сравнивают минимум три конфигурации: базовую, с поворотом и с увеличенным пределом пикселей. Для структурного извлечения отдельно сравнивают свободный промпт и встроенную задачу со схемой. Победителя выбирают по доле документов, прошедших валидацию без человека, средней стоимости и времени. После выбора тест сохраняют как регрессионный и повторяют при любом изменении.

Проектирование интерфейса ручной проверки

Экран проверки должен минимизировать переключение внимания. Слева показывается документ с масштабом и рамкой, справа — поле и значение. Нажатие на поле перемещает изображение к соответствующей области. Необязательные служебные данные скрываются, но доступны по запросу: идентификатор, инструкция, токены и сырой ответ.

Клавиши подтвердить, исправить, не читается и не то поле ускоряют работу и дают полезную статистику. Статус не читается отличается от пустого значения: он сигнализирует о качестве исходника и может запустить запрос нового скана. Статус не то поле указывает на ошибку схемы или модели и требует анализа шаблона.

Для таблиц показывают сетку и исходный фрагмент синхронно. Исправление одной ячейки не должно перестраивать весь HTML незаметно. Для формул отображают исходный LaTeX и рендер. Все действия записываются, а возврат к предыдущей версии выполняется без повторного OCR.

Интеграция с поиском и базой данных

Полнотекстовый индекс хранит нормализованный текст, но ссылка ведёт на оригинальную страницу. Координаты строки позволяют подсветить совпадение. Для поиска по русскому языку применяют морфологию после OCR, сохраняя исходную строку отдельно. Нормализация не должна менять номера, артикулы и формулы.

Структурированные поля записывают в типизированные колонки только после валидации. Сырой JSON хранится как приложение к записи, а не как единственный источник. Если схема изменится, старые ответы можно переразобрать без повторной отправки изображения, если в них сохранились нужные значения.

Дубликаты документов определяют по хэшу файла и ключевым реквизитам. Два разных скана одного счёта имеют разные хэши, поэтому дополнительно сравнивают поставщика, номер, дату и сумму. Автоматическое объединение выполняют только при строгом совпадении; иначе оператор выбирает основную копию.