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

Метод /recognize

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

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

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

  2. Классификатор присваивает каждой вырезанной области класс: главный разворот паспорта России, водительское удостоверение образца 2011 года, СНИЛС и так далее. По ссылке доступен список поддерживаемых типов документов.

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

  4. Алгоритм находит и вырезает поля документа. Например, в паспорте отдельно вырезаются фамилия, место рождения, серия, номер и остальные поля.

  5. Алгоритм OCR оцифровывает символы на вырезанном поле документа.

  6. OCR присваивает результату распознавания «уровень уверенности» confidence.

  7. Если включен режим ручного распознавания, модуль HITL обрабатывает пару «вырезанное поле + оцифрованный текст» .

  8. Оцифрованный текст проходит верификацию по маскам и словарям.

Уровень уверенности 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-спецификация для метода распознавания документов. Подробнее о том, как составить запрос на распознавание, в разделе Подключение и тестирование.

post
recognize

https://latest.dbrain.io/recognize
Request
Response
Request
Query Parameters
external_check_fake
optional
boolean
true — при использовании проверок по внешним базам (external_check_...) не делает настоящую проверку, а возвращает шаблонный ответ (необходимо для отладки) false — имитация проверки отключена
external_check_vehicle_dtp_and_restrict
optional
boolean
true — ищет в базах ГИБДД ДТП с участием данного транспортного средства и обременения по СТС (vehicle_registration_certificate_front) false — обращение к базе по этой проверке отключено
external_check_vehicle_wanted_list
optional
boolean
true — ищет во внешних базах, находится ли транспортное средство в розыске по ПТС или СТС (vehicle_registration_certificate_front или pts_front) false — обращение к базе по этой проверке отключено
external_check_vehicle_restrict_list
optional
boolean
true — ищет во внешних базах обременения на транспортное средство по ПТС или СТС (vehicle_registration_certificate_front или pts_front) false — обращение к базе по этой проверке отключено
external_check_fico
optional
boolean
true — возвращает финансовый скоринг FICO для физлица по пасспорту (passport_main) false — обращение к базе по этой проверке отключено
external_check_pledges_list
optional
boolean
true — находит во внешних базах долги физлица по паспорту (passport_main) false — обращение к базе по этой проверке отключено
external_check_inn
optional
boolean
true — находит во внешних базах номер ИНН физлица по паспорту (passport_main) false — обращение ко внешней базе по номеру ИНН отключено
external_check_is_valid
optional
boolean
true — проверяет подлинность документа по внешним базам документов (вроде реестров МВД/ГИБДД). Пока доступна только проверка подлинности паспорта (doc_type="passport_main") false — проверка подлинности паспорта по базам отключена
doc_type
optional
array
Перечень типов документов, которые требуется распознать во входящем файле. Используется для детерминированных процессов, например, если в потоке требуется обрабатывать только главный разворот паспорта, а на все остальные типы ответ не требуется. По умолчанию выбраны все значения параметра (все типы, имеющиеся в классификаторе)
priority
optional
integer
>0, по умолчанию — 1. Приоритет асинхронной задачи в очереди на обработку
simple_cropper
optional
boolean
false (по умолчанию) — упрощённый алгоритм вырезания документов из изображений не используется true — используется упрощённый алгоритм вырезания документов из изображений: он работает быстрее, но даёт менее точный результат. На изображениях со сложным фоном документы могут быть вырезаны менее аккуратно
async
optional
boolean
true — асинхронный режим обработки запросов false — синхронный режим обработки запросов
check_fake_experimental
optional
boolean
Устарел и не используется
check_fake
optional
boolean
true — алгоритм ищет в метаданных файла признаки модификации в цифровых редакторах, результат возвращается в отдельном поле fake false — алгоритм проверки метаданных отключен
use_internal_api
optional
boolean
true — нормализует поле «Кем выдано» в паспорте по встроенной базе данных. Это позволяет получить текст без опечаток даже с изображений низкого качества, но может приводить к отсутствию посимвольного соответствия между документом и результатом false — нормализация отключена
use_external_api
optional
boolean
Устарел и не используется
pdf_raw_images
optional
boolean
true — алгоритм оставляет решение о растеризации PDF параметру auto_pdf_raw_images false — любой PDF будет принудительно растеризован, значение параметра auto_pdf_raw_images будет проигнорировано.
auto_pdf_raw_images
optional
boolean
true — алгоритм ищет текстовый слой в PDF. Если он найден, PDF будет принудительно растеризован false — алгоритм никогда не растеризует PDF
dpi
optional
integer
>0, по умолчанию — 300. устанавливает число пикселей на дюйм при растеризации PDF. Рекомендуется 300, более высокие значения как правило не дают прироста качества, но увеличивают вес
quality
optional
integer
0-100, по умолчанию — 75. устанавливает степень сжатия JPEG при растеризации PDF. Рекомендуется 75 для баланса между весом изображения и его качеством
gauss
optional
number
Устарел и не используется
mode
optional
string
default — задействован весь пайплайн распознавания; recognize_only — отключает алгоритмы вырезания и ориентирования документа, на этап распознавания уходит оригинальное изображение
with_hitl
optional
boolean
true — поля документа уходят на ручную верификацию и распознавание сложных случаев с помощью Яндекс.Толоки false — ручное распознавание отключено
hitl_async
optional
boolean
true — разрешает модулю HITL возврат неполного состава полей документа не дожидаясь окончания распознавания всех полей. Параметр работает только при использовании режима ручного распознавания документов with_hitl=true. Ответ с неполным составом полей сопровождается кодом 202, полный — кодом 200 false — отключает асинхронный режим HITL, метод вернёт ответ только по завершению обработки всех полей документа
hitl_required_fields
optional
array
В массиве нужно перечислить названия полей документа, после обработки которых HITL может возвращать неполный ответ. Работает только с включенными параметрами with_hitl и hitl_async
hitl_sla
optional
string
Не используется
Body Parameters
verify_fields
optional
string
Активирует функцию сверки полей с внешним файлом (см. выше)
image
required
object
Файл, содержимое которого надо распознать
Response
200: OK
Запрос успешно обработан. В атрибуте "doc_type" указан тип найденного документа. В атрибуте "text" указано значение для выделенного поля документа. В атрибуте "confidence" указан параметр confidence для выделенного поля документа.
{
"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 // кол-во документов во входном файле
}
422: Unprocessable Entity
Запрос содержит недопустимые входные параметры
{
"detail": [
{
"loc": [
"string"
],
"msg": "string",
"type": "string"
}
]
}