Распознавание документов

Метод /recognize

Алгоритм распознавания документов включает в себя классификацию документов на изображении и распознавание в нём текста полей.

Алгоритм работы метода API /recognize

Алгоритм ищет на входящем изображении прямоугольные области, похожие на документы, и вырезает их.
Классификатор присваивает каждой вырезанной области класс: главный разворот паспорта России, водительское удостоверение образца 2011 года, СНИЛС и так далее. По ссылке доступен список поддерживаемых типов документов.
Алгоритм оценивает ориентацию документа в пространстве. При необходимости, классификатор поворачивает или зеркально отражает документ.
Алгоритм находит и вырезает поля документа. Например, в паспорте отдельно вырезаются фамилия, место рождения, серия, номер и остальные поля.
Алгоритм OCR оцифровывает символы на вырезанном поле документа.
OCR присваивает результату распознавания «уровень уверенности» confidence.
Если включен режим ручного распознавания, модуль HITL обрабатывает пару «вырезанное поле + оцифрованный текст» .
Оцифрованный текст проходит верификацию по маскам и словарям.

Уровень уверенности confidence

Параметр confidence в ответе показывает уровень уверенности алгоритма в корректности распознавания символов:

0.90-1.00 — абсолютно уверен;
0.70-0.89 — вполне уверен;
0.50-0.69 — в ответе возможна ошибка;
0.01-0.49 — в поле наверняка есть ошибка;
0 — в поле точно ошибка.

Алгоритм вернёт пустой ответ с нулевым confidence, если оцифрованный текст не пройдёт проверку по маскам и словарям. Например, дата рождения «56.12.1988» не попадёт в ответ.

Функция сверки полей с внешним файлом

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

Ниже показан пример JSON-файла для сравнения серии-номера и ФИО из паспорта РФ с результатами распознавания:

{
  "series_and_number": "1111 222222",
  "surname": "Иванов",
  "first_name": "Иван",
  "other_names": "Иванович"
}

Для составления своего JSON-файла скопируйте наименования полей из API-спецификации.

Функция сверки возвращает атрибут "valid" для каждого поля документа. Допустимые значения атрибута:

"true" — текст поля в JSON-файле и в результатах распознавания совпадают;
"false" — текст не совпадает;
"null" — поле отсутствует в JSON-файле.

Помимо этого, функция сверки возвращает атрибут "levenshtein" — расстояние Левенштейна для результата распознавания и аналогичного поля из внешнего JSON-файла.

API-спецификация

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

recognize

POST https://latest.dbrain.io/recognize

Query Parameters

Name	Type	Description
external_check_fake	boolean	true — при использовании проверок по внешним базам (external_check_...) не делает настоящую проверку, а возвращает шаблонный ответ (необходимо для отладки) false — имитация проверки отключена
external_check_vehicle_dtp_and_restrict	boolean	true — ищет в базах ГИБДД ДТП с участием данного транспортного средства и обременения по СТС (vehicle_registration_certificate_front) false — обращение к базе по этой проверке отключено
external_check_vehicle_wanted_list	boolean	true — ищет во внешних базах, находится ли транспортное средство в розыске по ПТС или СТС (vehicle_registration_certificate_front или pts_front) false — обращение к базе по этой проверке отключено
external_check_vehicle_restrict_list	boolean	true — ищет во внешних базах обременения на транспортное средство по ПТС или СТС (vehicle_registration_certificate_front или pts_front) false — обращение к базе по этой проверке отключено
external_check_fico	boolean	true — возвращает финансовый скоринг FICO для физлица по паспорту (passport_main) false — обращение к базе по этой проверке отключено
external_check_pledges_list	boolean	true — находит во внешних базах долги физлица по паспорту (passport_main) false — обращение к базе по этой проверке отключено
external_check_inn	boolean	true — находит во внешних базах номер ИНН физлица по паспорту (passport_main) false — обращение ко внешней базе по номеру ИНН отключено
external_check_is_valid	boolean	true — проверяет подлинность документа по внешним базам документов (вроде реестров МВД/ГИБДД). Пока доступна только проверка подлинности паспорта (doc_type="passport_main") false — проверка подлинности паспорта по базам отключена
doc_type	array	Перечень типов документов, которые вы хотите распознать во входящем файле. Используется для детерминированных процессов, например, если в потоке требуется обрабатывать только главный разворот паспорта, а на все остальные типы ответ не нужен. По умолчанию выбраны все значения параметра (все типы, имеющиеся в классификаторе)
priority	integer	>0, по умолчанию — 1. Приоритет асинхронной задачи в очереди на обработку
simple_cropper	boolean	false (по умолчанию) — упрощённый алгоритм вырезания документов из изображений не используется true — используется упрощённый алгоритм вырезания документов из изображений: он работает быстрее, но даёт менее точный результат. На изображениях со сложным фоном документы могут быть вырезаны менее аккуратно
async	boolean	true — асинхронный режим обработки запросов false — синхронный режим обработки запросов
check_fake_experimental	boolean	Устарел и не используется
check_fake	boolean	true — алгоритм ищет в метаданных файла признаки модификации в цифровых редакторах, результат возвращается в отдельном поле fake false — алгоритм проверки метаданных отключен
use_internal_api	boolean	true — нормализует поле «Кем выдано» в паспорте по встроенной базе данных. Это позволяет получить текст без опечаток даже с изображений низкого качества, но может приводить к отсутствию посимвольного соответствия между документом и результатом false — нормализация отключена
use_external_api	boolean	true (по умолчанию) — алгоритм уточняет и обогащает ответ API по СТС и ПТС данными из внешних сервисов false — сервис возвращает только то, что сам распознал
pdf_raw_images	boolean	true — алгоритм оставляет решение о растеризации PDF параметру auto_pdf_raw_images false — любой PDF будет принудительно растеризован, значение параметра auto_pdf_raw_images будет проигнорировано.
auto_pdf_raw_images	boolean	true — алгоритм ищет текстовый слой в PDF. Если он найден, PDF будет принудительно растеризован false — алгоритм никогда не растеризует PDF
dpi	integer	>0, по умолчанию — 300. устанавливает число пикселей на дюйм при растеризации PDF. Рекомендуется 300, более высокие значения как правило не дают прироста качества, но увеличивают вес
quality	integer	0-100, по умолчанию — 75. устанавливает степень сжатия JPEG при растеризации PDF. Рекомендуется 75 для баланса между весом изображения и его качеством
gauss	number	Устарел и не используется
mode	string	default — задействован весь пайплайн распознавания; recognize_only — отключает алгоритмы вырезания и ориентирования документа, на этап распознавания уходит оригинальное изображение
with_hitl	boolean	true — поля документа уходят на ручную верификацию и распознавание сложных случаев с помощью Яндекс.Толоки false — ручное распознавание отключено
hitl_async	boolean	true — разрешает модулю HITL возврат неполного состава полей документа не дожидаясь окончания распознавания всех полей. Параметр работает только при использовании режима ручного распознавания документов with_hitl=true. Ответ с неполным составом полей сопровождается кодом 202, полный — кодом 200 false — отключает асинхронный режим HITL, метод вернёт ответ только по завершению обработки всех полей документа
hitl_required_fields	array	В массиве нужно перечислить названия полей документа, после обработки которых HITL может возвращать неполный ответ. Работает только с включенными параметрами with_hitl и hitl_async
hitl_sla	string	Не используется
task_tags	array	Массив строк, который позволяет присваивать запросу дополнительные идентификаторы. Например можно передавать id пакета документов для биллинга на стороне Dbrain
return_crops	boolean	false — сервис перестаёт возвращать изображения. Функцию можно использовать для экономии трафика и для удобства отладки — с ней ответ сервиса становится более читабельным. true (по умолчанию) — сервис возвращает в ответе изображения в бинарном формате.
first_occurrence_only	boolean	true — при обработке PDF сервис возвращает только первый найденный документ запрашиваемого класса. Это позволяет сократить время ответа. false (по умолчанию) — сервис обрабатывает PDF целиком и возвращает все найденные документы.
merge_and_name	string	Пустой (по умолчанию) — ответ вернётся без изменений Любое значение — все поля всех распознанных документов будут объединены в один класс с указанным в параметре именем
max_blur_score	number	>0, по умолчанию 2. Минимальный коэффициент чёткости изображения. Если чёткость меньше, параметр image_blured в ответе вернётся со значением true. Если больше — false.
min_exposure_score	number	>0, по умолчанию 0.05. Минимальная экспозиция (яркость) изображения. Если яркость меньше, параметр image_exposure в ответе вернётся со значением underexposed. Если больше — normal.
max_exposure_score	number	>0, по умолчанию 0.4. Максимальная экспозиция (яркость) изображения. Если яркость больше, параметр image_exposure в ответе вернётся со значением overexposed. Если меньше — normal.
min_filesize	integer	>0, по умолчанию 256. Минимальный размер изображения в пикселях по короткой стороне. Если размер меньше, параметр low_image_size в ответе вернётся со значением true. Если больше — false.
min_shape	integer	Минимальный размер изображения в пикселях по короткой стороне. Если размер меньше, параметр low_image_weight в ответе вернётся со значением true. Если больше — false.
hitl_symbol_field	array	В этом массиве можно перечислить поля документов, которые сервис должен возвращать с ручной проверки с посимвольной точностью, без приведения к словарю
hitl_field_to_recognize	array	Если вам нужно ручное распознавание только отдельных полей документов, перечислите в этом массиве их названия
external_check_passport_complex	boolean	true — проводит комплексную проверку паспорта по внешним источникам false — проверка не проводится
dev_invoice_alternative_engine	boolean	Параметр используется для отладки, не рекомендуется к использованию в проде

Name

Type

Description

external_check_fake

boolean

true — при использовании проверок по внешним базам (external_check_...) не делает настоящую проверку, а возвращает шаблонный ответ (необходимо для отладки) false — имитация проверки отключена

external_check_vehicle_dtp_and_restrict

boolean

true — ищет в базах ГИБДД ДТП с участием данного транспортного средства и обременения по СТС (vehicle_registration_certificate_front) false — обращение к базе по этой проверке отключено

external_check_vehicle_wanted_list

boolean

true — ищет во внешних базах, находится ли транспортное средство в розыске по ПТС или СТС (vehicle_registration_certificate_front или pts_front) false — обращение к базе по этой проверке отключено

external_check_vehicle_restrict_list

boolean

true — ищет во внешних базах обременения на транспортное средство по ПТС или СТС (vehicle_registration_certificate_front или pts_front) false — обращение к базе по этой проверке отключено

external_check_fico

boolean

true — возвращает финансовый скоринг FICO для физлица по паспорту (passport_main) false — обращение к базе по этой проверке отключено

external_check_pledges_list

boolean

true — находит во внешних базах долги физлица по паспорту (passport_main) false — обращение к базе по этой проверке отключено

external_check_inn

boolean

true — находит во внешних базах номер ИНН физлица по паспорту (passport_main) false — обращение ко внешней базе по номеру ИНН отключено

external_check_is_valid

boolean

true — проверяет подлинность документа по внешним базам документов (вроде реестров МВД/ГИБДД). Пока доступна только проверка подлинности паспорта (doc_type="passport_main") false — проверка подлинности паспорта по базам отключена

doc_type

array

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

priority

integer

>0, по умолчанию — 1. Приоритет асинхронной задачи в очереди на обработку

simple_cropper

boolean

false (по умолчанию) — упрощённый алгоритм вырезания документов из изображений не используется true — используется упрощённый алгоритм вырезания документов из изображений: он работает быстрее, но даёт менее точный результат. На изображениях со сложным фоном документы могут быть вырезаны менее аккуратно

async

boolean

true — асинхронный режим обработки запросов false — синхронный режим обработки запросов

check_fake_experimental

boolean

Устарел и не используется

check_fake

boolean

true — алгоритм ищет в метаданных файла признаки модификации в цифровых редакторах, результат возвращается в отдельном поле fake false — алгоритм проверки метаданных отключен

use_internal_api

boolean

true — нормализует поле «Кем выдано» в паспорте по встроенной базе данных. Это позволяет получить текст без опечаток даже с изображений низкого качества, но может приводить к отсутствию посимвольного соответствия между документом и результатом false — нормализация отключена

use_external_api

boolean

true (по умолчанию) — алгоритм уточняет и обогащает ответ API по СТС и ПТС данными из внешних сервисов

false — сервис возвращает только то, что сам распознал

pdf_raw_images

boolean

true — алгоритм оставляет решение о растеризации PDF параметру auto_pdf_raw_images false — любой PDF будет принудительно растеризован, значение параметра auto_pdf_raw_images будет проигнорировано.

auto_pdf_raw_images

boolean

true — алгоритм ищет текстовый слой в PDF. Если он найден, PDF будет принудительно растеризован false — алгоритм никогда не растеризует PDF

dpi

integer

>0, по умолчанию — 300. устанавливает число пикселей на дюйм при растеризации PDF. Рекомендуется 300, более высокие значения как правило не дают прироста качества, но увеличивают вес

quality

integer

0-100, по умолчанию — 75. устанавливает степень сжатия JPEG при растеризации PDF. Рекомендуется 75 для баланса между весом изображения и его качеством

gauss

number

Устарел и не используется

mode

string

default — задействован весь пайплайн распознавания; recognize_only — отключает алгоритмы вырезания и ориентирования документа, на этап распознавания уходит оригинальное изображение

with_hitl

boolean

true — поля документа уходят на ручную верификацию и распознавание сложных случаев с помощью Яндекс.Толоки false — ручное распознавание отключено

hitl_async

boolean

true — разрешает модулю HITL возврат неполного состава полей документа не дожидаясь окончания распознавания всех полей. Параметр работает только при использовании режима ручного распознавания документов with_hitl=true. Ответ с неполным составом полей сопровождается кодом 202, полный — кодом 200 false — отключает асинхронный режим HITL, метод вернёт ответ только по завершению обработки всех полей документа

hitl_required_fields

array

В массиве нужно перечислить названия полей документа, после обработки которых HITL может возвращать неполный ответ. Работает только с включенными параметрами with_hitl и hitl_async

hitl_sla

string

Не используется

task_tags

array

Массив строк, который позволяет присваивать запросу дополнительные идентификаторы. Например можно передавать id пакета документов для биллинга на стороне Dbrain

return_crops

boolean

false — сервис перестаёт возвращать изображения. Функцию можно использовать для экономии трафика и для удобства отладки — с ней ответ сервиса становится более читабельным.

true (по умолчанию) — сервис возвращает в ответе изображения в бинарном формате.

first_occurrence_only

boolean

true — при обработке PDF сервис возвращает только первый найденный документ запрашиваемого класса. Это позволяет сократить время ответа.

false (по умолчанию) — сервис обрабатывает PDF целиком и возвращает все найденные документы.

merge_and_name

string

Пустой (по умолчанию) — ответ вернётся без изменений

Любое значение — все поля всех распознанных документов будут объединены в один класс с указанным в параметре именем

max_blur_score

number

>0, по умолчанию 2. Минимальный коэффициент чёткости изображения. Если чёткость меньше, параметр image_blured в ответе вернётся со значением true. Если больше — false.

min_exposure_score

number

>0, по умолчанию 0.05. Минимальная экспозиция (яркость) изображения. Если яркость меньше, параметр image_exposure в ответе вернётся со значением underexposed. Если больше — normal.

max_exposure_score

number

>0, по умолчанию 0.4. Максимальная экспозиция (яркость) изображения. Если яркость больше, параметр image_exposure в ответе вернётся со значением overexposed. Если меньше — normal.

min_filesize

integer

>0, по умолчанию 256. Минимальный размер изображения в пикселях по короткой стороне. Если размер меньше, параметр low_image_size в ответе вернётся со значением true. Если больше — false.

min_shape

integer

Минимальный размер изображения в пикселях по короткой стороне. Если размер меньше, параметр low_image_weight в ответе вернётся со значением true. Если больше — false.

hitl_symbol_field

array

В этом массиве можно перечислить поля документов, которые сервис должен возвращать с ручной проверки с посимвольной точностью, без приведения к словарю

hitl_field_to_recognize

array

Если вам нужно ручное распознавание только отдельных полей документов, перечислите в этом массиве их названия

external_check_passport_complex

boolean

true — проводит комплексную проверку паспорта по внешним источникам

false — проверка не проводится

dev_invoice_alternative_engine

boolean

Параметр используется для отладки, не рекомендуется к использованию в проде

Request Body

Name	Type	Description
verify_fields	string	Активирует функцию сверки полей с внешним файлом (см. выше)
image	object	Файл, содержимое которого надо распознать
coords	string	Внутренний параметр, не для использования клиентами

Name

Type

Description

verify_fields

string

Активирует функцию сверки полей с внешним файлом (см. выше)

image

object

Файл, содержимое которого надо распознать

coords

string

Внутренний параметр, не для использования клиентами

{
  "detail": [ // техническая информация
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ],
  "items": [
    {
      "doc_type": "passport_main", // тип документа
      "fields": {
        "date_of_birth": { // наименование поля документа
          "text": "01.04.2004", // значение поля документа
          "confidence": 0.5262104272842407 // параметр Confidence
          "valid": null, // результат проверки при наличии в запросе verify_fields
          "levenshtein": null, // расстояние левенштейна после проверки при наличии в запросе verify_fields
          "coords": [ // координаты поля во входном файле
            [
              [
                873,
                1468
              ],
              [
                1187,
                1468
              ],
              [
                1187,
                1520
              ],
              [
                873,
                1520
              ]
            ]
          ]
        },
        "date_of_issue": { // наименование поля документа
          "text": "01.04.2018", // значение поля документа
          "confidence": 0.5271461009979248 // параметр Confidence
          "valid": null, // результат проверки при наличии в запросе verify_fields
          "levenshtein": null, // расстояние левенштейна после проверки при наличии в запросе verify_fields
          "coords": [ // координаты поля во входном файле
            [
              [
                752,
                1142
              ],
              [
                947,
                1142
              ],
              [
                947,
                1196
              ],
              [
                752,
                1196
              ]
            ]
          ]          
        }
      },
      "color": true, // цветность изображения в рамках объекта ("true", если цветное; "false", если ч/б)
      "other": 
      {
        "external_check_results": 
        {
          "inn": "1234567890",
          "fico":
          {
            "errorCode": 0,
            "status": "SUCCESS",
            "exclusionCode": 0,
            "score": 620,
            "reasonCode1": "D9",
            "reasonCode2": "M1",
            "reasonCode3": "T5",
            "reasonCode4": "A6",
            "reasonCode1Desc": "Слишком мало времени с момента последней просрочки",
            "reasonCode2Desc": "Количество счетов с просрочками",
            "reasonCode3Desc": "Слишком много недавних запросов кредитной истории по субъекту",
            "reasonCode4Desc": "Размер задолженности по просроченным счетам",
            "scoreSource": "nbki"
          },
          "pledges_list": [],
          "vehicle_restrict_list": [],
          "vehicle_wanted_list": [],
          "vehicle_dtp_and_restrict": 
          {
            "restrict_list": [],
            "dtp_list": []
          },
          "is_valid": true
        },
        "external_check_errors":
        {
          "inn": "string",
          "fico": "string",
          "pledges_list": "string",
          "vehicle_restrict_list": "string",
          "vehicle_wanted_list": "string",
          "vehicle_dtp_and_restrict": "string",
          "is_valid": "string"
        }
      }
      "error": null // = "Recognition for requested document not implemented", если модель не обучена распознавать документ
    }
  ],
  "task_id": null, // внутренний id задачи
  "code": null, // код ошибки
  "message": null, // сообщение об ошибке в рамках объекта
  "errno": null, // номер ошибки
  "traceback": null, // сообщение об ошибке в рамках объекта
  "fake": true, // ответ при параметре check_fake = "true"
  "pages_count": 1, // кол-во страниц во входном файле
  "docs_count": 1 // кол-во документов во входном файле
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

PreviousКлассификация документов NextРаспознавание бухгалтерских документов

Last updated 2 years ago