> For the complete documentation index, see [llms.txt](https://docs.dbrain.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dbrain.io/servisy/proverka-dokumentov/antifrod-2.0.md). # Антифрод 2.0 Анализируем изображения паспорта РФ и селфи с паспортом РФ, чтобы выявить подделки. В сравнении с первой версией Антифрод 2.0 содержит ряд важных изменений: * **Детекция поддельных селфи:** метод теперь работает не только с изображениями главного разворота паспорта РФ, но и с селфи, где человек держит в руках паспорт РФ. * **Оценка качества изображения:** метод научился определять изображения плохого качества: маленькие, засвеченные, смазанные, тёмные, чёрно-белые, обрезанные, с полями, закрытыми пальцами. * **Фотографии ксерокопий:** метод научился определять фотографии ксерокопий документов. * **Детекция очень аккуратных подделок:** на основе реальных примеров поддельных документов обновили архитектуру нейросети, которая ищет признаки подделки изображения. * **Уточнение алгоритмических проверок:** исправлены ошибки в логике. Добавлен анализ качества изображения. ## Как начать работать с сервисом Антифрод 2.0 Есть 4 популярных способа взаимодействия с сервисом. Для любого вам нужен ключ лицензии. Чтобы получить ключ, напишите нам в [телеграм](https://t.me/dbrain_support_bot) или на . Подготовьте изображение документа для теста. Если у вас такого нет, используйте [паспорт РФ из Википедии](https://ru.wikipedia.org/wiki/%D0%9F%D0%B0%D1%81%D0%BF%D0%BE%D1%80%D1%82_%D0%B3%D1%80%D0%B0%D0%B6%D0%B4%D0%B0%D0%BD%D0%B8%D0%BD%D0%B0_%D0%A0%D0%BE%D1%81%D1%81%D0%B8%D0%B9%D1%81%D0%BA%D0%BE%D0%B9_%D0%A4%D0%B5%D0%B4%D0%B5%D1%80%D0%B0%D1%86%D0%B8%D0%B8#/media/%D0%A4%D0%B0%D0%B9%D0%BB:Pasport_RF.jpg).
Через веб-демо 1. Откройте [demo.dbrain.io](https://demo.dbrain.io) 2. Введите ключ лицензии в поле «Токен» и нажмите «Применить» 3. Выберите «Антифрод» 4. Нажмите кнопку «Выберите файл для распознавания» 5. Укажите изображение, которое нужно распознать 6. Нажмите кнопку «Распознать»
Через терминал Обратитесь к методу `/fraud_v2` по адресу [latest.dbrain.io](https://latest.dbrain.io/). В этом способе только два обязательных параметра: * `token` — ваш ключ лицензии * `image` — файл с изображением документа Запрос curl должен выглядеть так: ```bash curl -X 'POST' \ 'https://latest.dbrain.io/pipelines/run/fraud_v2?token=xxx' \ -H 'accept: application/json' \ -H 'Content-Type: multipart/form-data' \ -F 'image=@image.jpg;type=image/jpeg' ```
Через Swagger * Подготовьте ключ лицензии * Откройте [Swagger](https://latest.dbrain.io/docs) и нажмите кнопку `Authorize` в правом верхнем углу * Введите свой токен в любое поле и нажмите `Authorize` * Прокрутите вниз до раздела `/pipelines/run/fraud_v2`, нажмите на него * В открывшемся разделе нажмите на кнопку `Try it out` * Прокрутите страницу вниз до раздела `Request body` * Нажмите на кнопку `Выберите файл` пункта `image` * Укажите изображение, которое нужно распознать * Нажмите кнопку `Execute` * Ответ сервиса появится в пункте `Response body` раздела `Responses` * Полученный на этом этапе `Curl` мы рекомендуем использовать как основу для написания интеграции с API сервиса Dbrain
Через Python {% code overflow="wrap" %} ```python import requests url = 'https://latest.dbrain.io/pipelines/run/fraud_v2?token=xxx' files = {'image': open('image.jpg', 'rb')} headers = {'accept': 'application/json'} response = requests.post(url, headers=headers, files=files) ``` {% endcode %} Код использует библиотеку `requests` для отправки POST-запроса с файлом изображения. Функция `open()` используется для открытия файла изображения в двоичном режиме и передачи его в параметр `files`. Параметр `headers` используется для установки заголовка `accept` в значение `application/json`. Ответ от сервера сохраняется в переменной `response`. Тело запроса передавайте в кодировке `UTF-8`.
## Параметры запроса к API Вы можете использовать следующие параметры при запросе к сервису определения подделок. **Асинхронный запрос** * **`async`** — *boolean* По умолчанию: `async=false` — сервис обрабатывает запросы синхронно. При отправке запроса вы получите ответ только после окончательного завершения обработки сервисом. Если вам нужен асинхронный режим, укажите в запросе `async=true`. В ответ на запрос сервис вернёт в теле ответа параметр `task_id`. Например: ```json "task_id": "96b8ccc950a70699927036842c624d7c" ``` Используйте этот `task_id`, чтобы получить результаты методом `result`: ```bash curl -X 'GET' \ 'https://latest.dbrain.io/result/96b8ccc950a70699927036842c624d7c?token=XXX' \ -H 'accept: application/json' ``` Не забудьте указать в параметре `token` ваш ключ лицензии. Рекомендуем запрашивать метод `result` в цикле с периодом 1-2 секунды. **Возврат оригинального изображения** * **`return_crops`** — *boolean* По умолчанию: `return_crops=false` — сервис не возвращает оригинальное изображение. Если вам нужно оригинальное изображение на выходе нашего API, укажите `return_crops=true`. Сервис вернёт оригинальное изображение в ответе API, в параметре `input_image`. **Тегирование запроса** * **`task_tags`** — *array\[string]* По умолчанию: параметр не используется. У нас есть опциональная функция тегирования запросов. Она упрощает отслеживание пакетов документов, связанных с конкретным клиентом-физлицом. Для использования функции укажите в параметре `task_tags` удобный вам тег: ``` task_tags=тег ``` ## Тело запроса к API **Изображение** * **`image`** — *string ($binary)* Изображение обязательно для передачи в запросе. Сервис ожидает изображение в двоичном виде. ## Ответ от API В ответе на запрос вы получите JSON с информацией о результатах проверки. **Пример ответа** ```json { "task_id": "a7a8e546f8bcdf3d0af17cc51a19ccac", "error": "", "task_tags": [], "success": true, "status_code": 200, "result": { "overall_result": "definitely_fake", "definitely_fake": true, "potentially_fake": false, "image": { "type": "passport", "quality": { "errors": null, "glare_detected": false, "blur_detected": false, "document_cropped": false, "document_no_color": false, "document_too_small": false, "document_too_dark": false, "glare_score": 0, "blur_score": 0.03, "crop_score": 0.01 }, "origin": "scan" }, "selfie": null, "passport": { "photo_mismatch_passport_data": null, "ai_checks": { "image_modifications_detected": { "coords": [ [ [ 1206, 1474 ], [ 1228, 1490 ], [ 1199, 1532 ], [ 1177, 1516 ] ], [ [ 969, 437 ], [ 1074, 437 ], [ 1074, 486 ], [ 969, 486 ] ] ], "confs": [ 0.47666143975924263, 0.9342110193869388 ], "cls_confidence": 1, "top_1_segmentation_confidence": 0.93, "merged_confidence": 0.97, "result": true }, "visual_field_missing": false, "photo_not_found": false, "photo_gender_mismatch": false }, "logical_checks": { "series_number_inconsistency": false, "series_mismatch_printing_year": false, "issue_year_mismatch_date_of_birth": true, "issue_code_mismatch_issue_authority": true, "mrz_presence_mismatch_issue_year": false, "visual_fields_mismatch_mrz": true, "fake_series_okato": false, "fake_year_of_birth": false } }, "file_metadata": { "not_present": true, "inconsistency": false, "maker": "", "model": "", "software": "", "date_time": { "modify_date": "", "create_date": "", "date_time_original": "", "gps_date_stamp": "" }, "gps_coords": { "latitude_ref": "", "latitude": "", "longitude_ref": "", "longitude": "", "altitude_ref": "", "altitude": "" } }, "input_image": null } } Response headers ``` **Описание полей ответа** * `task_id` — *string*, идентификатор запроса, формат: 32 символа, шестнадцатеричная строка. * `error` — *string*, текстовое описание ошибки (если есть). * `task_tags` — *array\[string]*, теги, если они были переданы в параметре `task_tags`. * `success` — *boolean*, статус запроса: * `true` — запрос выполнен успешно. * `false` — запрос не выполнен. * `status_code` — *integer*, HTTP-код статуса запроса: * `200` — запрос выполнен успешно. * `400`, `403`, `500` и т.д. — расшифрованы в «[Общей информации о сервисах](/obshaya-informaciya/readme.md)». **Поле `result`** * `overall_result` — *string*, общий результат проверки. Возможные значения: * `bad_image_quality` — качество изображения не позволяет вынести вердикт. Если вы хотите убедиться в подлинности документа, попросите прислать другое изображение. Вернуть правильную ошибку пользователю поможет раздел `image.quality`, он описан ниже. * `definitely_fake` — изображение поддельное. По совокупности факторов мы уверены, что изображение надо отклонить. * `potentially_fake` — изображение возможно поддельное. Вы можете пропустить его дальше на своё усмотрение, но мы рекомендуем отправить его на ручную проверку. * `wrong_document` — изображение не является паспортом или селфи, либо его качество не позволяет определить, что это паспорт или селфи. * `genuine` — изображение настоящее. Мы считаем, что ручные проверки не требуются. Подробней о том, каким образом присваиваются `definitely_fake` и `potentially_fake:` {% tabs %} {% tab title="definitely\_fake" %} Подойдёт любой из следующих критериев: Селфи * Нейросеть, которая анализирует изображение, идентифицировала вмешательство в изображение с уверенностью не ниже 90%. (selfie.fake). Паспорт * Нейросеть, которая анализирует изображение паспорта, идентифицировала высокую вероятность модификации изображения (passport.ai\_checks.image\_modifications\_detected). * Обнаружены критичные логические несоответствия в самом документе: например, серия паспорта не согласуется с другими данными, дата выдачи не согласуется с годом рождения. {% endtab %} {% tab title="potentially\_fake" %} Если не присвоен definitely\_fake, подойдёт любой из следующих критериев: Селфи * Нейросеть, которая анализирует изображения селфи, идентифицировала вмешательство в изображение с уверенностью от 50 до 90% (selfie.fake). * В метаданных файла обнаружены несоответствия (metadata.inconsistency). * Фото было получено сомнительным способом (например, скриншот экрана телефона, фото экрана монитора, ксерокопия). Паспорт * Нейросеть, которая анализирует изображение паспорта, идентифицировала среднюю (но не высокую) вероятность модификации изображения. * Есть логические несоответствия, которые могли возникнуть по причине ошибки наших алгоритмов, а не только фрода: например, несовпадение визуальных полей с машиночитаемой зоной. * Нейросеть считает, что пол в текстовом поле не совпадает с полом человека на фото. * Есть общие признаки некорректного документа: несогласованность метаданных, сомнительный способ получения снимка. {% endtab %} {% endtabs %} {% hint style="warning" %} Сейчас API возвращает булевые поля "definitely\_fake" и "potentially\_fake". Они исчезнут в следующих версиях. Вместо них ориентируйтесь на текстовое поле "overall\_result". {% endhint %} **Объект `image`** * `type` — *string*, тип изображения: * `passport`— документ (главный разворот паспорта). * `selfie` — селфи с паспортом. * `other` — постороннее изображение. * `quality` — объект, содержащий информацию о качестве изображения: * `errors` — *string* или `null`, ошибки при обработке качества. * `glare_detected` — *boolean. True,* если сервис обнаружил блики на полях документа. Посоветуйте пользователю убедиться, что отражения на ламинации паспорта не мешают прочитать поля документа. * `blur_detected` — *boolean. True,* если сервис обнаружил, что фото документа недостаточно чёткое. Например если пользователь снимал на длинной выдержке при недостаточном освещении. Попросите пользователя включить свет перед съёмкой или выйти на улицу. * `document_cropped` — *boolean. True,* если сервис обнаружил, что поле документа закрыто посторонним предметом или паспорт обрезан краем кадра. Посоветуйте пользователю не закрывать поля документа пальцами и взять его в кадр целиком. * `document_no_color` — *boolean. True*, если сервис обнаружил, что изображение чёрно-белое. Попросите пользователя прислать оригинальный снимок, без фильтров и упражнений в графическом редакторе. * `document_too_small` — *boolean. True*, если разрешение документа слишком низкое. Сервис ожидает, что изображение будет разрешением не менее 640 × 640 пикселей, т.е. не менее 0.4 Мп. Смартфоны, которые дают такое низкое разрешение даже на фронтальной камере перестали выпускать в 2012 году. Попросите пользователя прислать оригинальную, а не уменьшенную, фотографию. * `document_too_dark` — *boolean. True*, если изображение слишком тёмное. Вероятно пользователь сделал кадр в тёмном помещении без вспышки. Попросите пользователя включить свет перед съёмкой или выйти на улицу. * `glare_score` — *float*, степень бликов (от 0 до 1). Чем ближе число к единице, тем ярче выражены блики на полях. Сервис предъявляет довольно строгие требования к бликам в параметре `glare_detected`. Вы можете ориентироваться на `glare_score`, если хотите пропускать изображения с незначительными бликами. * `blur_score` — *float*, степень размытия (от 0 до 1). Чем ближе число к единице, тем менее чёткий снимок. Сервис предъявляет довольно строгие требования к чёткости изображения в параметре `blur_detected`. Вы можете ориентироваться на `blur_score`, если хотите пропускать изображения с незначительным размытием. * `crop_score` — *float,* степень обрезки (от 0 до 1). Чем ближе число к единице, тем сильнее закрыты поля посторонними предметами. Сервис предъявляет довольно строгие требования к целостности документа в параметре `document_cropped`. Вы можете ориентироваться на `crop_score`, если хотите пропускать изображения, где пальцы частично перекрывают поля документа или документ незначительно обрезан краем кадра. * `origin` — *string*, источник изображения: * `photo` — фотография. Ожидаемый благоприятный сценарий, который не вызывает вопросов — пользователь просто сфотографировал свой документ на смартфон. * `scan` — скан. Сомнительный сценарий: вместо фотографии пользователь прислал скан. Вы должны сами решить, подходит ли вам такое изображение. * `screenshot` — скриншот. Красный флаг — вместо фото документа пользователь сделал скриншот экрана. Высока вероятность, что у пользователя нет оригинала документа. * `monitor_photo` — фотография экрана. Красный флаг — вместо фото документа пользователь сфотографировал экрана другого смартфона, монитора или телевизора. Высока вероятность, что у пользователя нет оригинала документа. * `xerox` — Красный флаг — пользователь сфотографировал листок бумаги с изображением паспорта. Высока вероятность, что у пользователя нет оригинала документа. **Объект `selfie` (при `type`: `selfie`)** * `fake` — объект с результатами проверки селфи на подделку: * `result` — *boolean*, является ли селфи поддельным. * `confidence` — *float*, уверенность в результате (от 0 до 1). Чем ближе число к единице, тем выше уверенность сервиса. **Объект `passport`** * `photo_mismatch_passport_data` — *boolean*, несоответствие фотографии данным паспорта. {% hint style="warning" %} ВНИМАНИЕ: в данный момент проверка `photo_mismatch_passport_data` не работает. На её результаты нельзя ориентироваться. Она не учитывается в вердикте по документу в параметре `overall_result` . {% endhint %} * `ai_checks` — объект с результатами проверок паспорта с помощью искусственного интеллекта: * `image_modifications_detected` — объект: * `coords` — *array*, координаты подозрительных областей. * `confs` — уровень уверенности нейросети в подделке каждой конкретной области. * `result` — *boolean*, обнаружены ли модификации изображения. Если обнаружены, значит перед нами не оригинальная фотография, в неё вносились изменения. Попросите пользователя прислать другой снимок. * `merged_confidence` — итоговый уровень уверенности нейросети в том, что в изображение вносились изменения. Сейчас API также возвращает cls\_confidence и top\_1\_segmentation\_confidence. Они нужны для отладки и исчезнут в будущем. * `visual_field_missing` — *boolean*, отсутствуют ли обязательные поля. Если наш сервис не смог прочитать одно из обязательных полей в паспорте — перед нами подделка или пользователь всё-таки закрыл чем-то поле, например листом бумаги. Попросите пользователя прислать другой снимок. * `photo_not_found` — *boolean*, фотография не найдена. Наш сервис не видит лица в той области документа, где на паспорте должна быть фотография. Попросите пользователя прислать снимок, на котором лицо можно различить. * `photo_gender_mismatch` — *boolean*, несоответствие пола человека на фото и в текстовом поле паспорта. Вполне обычная ситуация, когда на потоке генерируешь поддельные паспорта. * `logical_checks` — объект с результатами алгоритмических проверок текстовых полей паспорта. Если у сервиса нет претензий к качеству изображения в объекте image.quality, любая из этих проверок говорит о том, что перед нами поддельный документ. * `series_number_inconsistency` — *boolean*, несоответствие серии или номера на верхней и нижней странице. * `series_mismatch_printing_year` — *boolean*, несоответствие серии паспорта дате выдачи паспорта. * `issue_year_mismatch_date_of_birth` — *boolean*, несоответствие года выдачи дате рождения. Вероятно паспорт просрочен. * `issue_code_mismatch_issue_authority` — *boolean*, несоответствие кода подразделения органу выдачи. Мы знаем какой текст, с точностью до запятой, должен быть в месте выдачи для данного сочетания даты и кода подразделения. * `mrz_presence_mismatch_issue_year` — *boolean*, несоответствие наличия или отсутствия MRZ году выдачи паспорта. MRZ (machine readable zone), она же МЧЗ (машиночитаемая зона) — две строки в нижней части паспорта, в которых закодированы текстовые поля паспорта. Печаются в паспорте РФ с 1 июля 2011 года. * `visual_fields_mismatch_mrz` — *boolean*, несоответствие визуальных полей информации в MRZ. * `fake_series_okato` — *boolean*, несуществующая серия по [ОКАТО](https://ru.wikipedia.org/wiki/%D0%9E%D0%B1%D1%89%D0%B5%D1%80%D0%BE%D1%81%D1%81%D0%B8%D0%B9%D1%81%D0%BA%D0%B8%D0%B9_%D0%BA%D0%BB%D0%B0%D1%81%D1%81%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%82%D0%BE%D1%80_%D0%BE%D0%B1%D1%8A%D0%B5%D0%BA%D1%82%D0%BE%D0%B2_%D0%B0%D0%B4%D0%BC%D0%B8%D0%BD%D0%B8%D1%81%D1%82%D1%80%D0%B0%D1%82%D0%B8%D0%B2%D0%BD%D0%BE-%D1%82%D0%B5%D1%80%D1%80%D0%B8%D1%82%D0%BE%D1%80%D0%B8%D0%B0%D0%BB%D1%8C%D0%BD%D0%BE%D0%B3%D0%BE_%D0%B4%D0%B5%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F). * `fake_year_of_birth` — *boolean*, нереалистичный год рождения. Например человек по паспорту родился в XVI веке. **Объект `file_metadata`** * `not_present` — *boolean*, метаданные отсутствуют. Любой смартфон записывает в файл изображения информацию о своей марке и модели, дате съёмки и другую полезную информацию в виде метаданых. Если всё это отсутствует, значит перед нами не оригинальный файл со смартфона. Само изображение, тем не менее, может быть оригинальным. * `inconsistency` — *boolean*, противоречия в метаданных. Например мы видим название графического редактора или видим, что дата съёмки отличается от даты изменения изображения. * `maker`, `model`, `software` — *string*, информация об устройстве и программном обеспечении. * `date_time` — объект с данными о датах и времени из метаданных: * `modify_date`, `create_date`, `date_time_original`, `gps_date_stamp` — *string*, даты и время. * `gps_coords` — объект с GPS-координатами: * `latitude_ref`, `latitude`, `longitude_ref`, `longitude`, `altitude_ref`, `altitude` — *string*, координаты и высота. **Поле `input_image`** * `input_image` — *string* или `null`, содержит исходное изображение в формате Data URL с MIME-типом JPEG в base64, если в запросе передан параметр `return_crops=true`. ## Описание типовых сценариев использования для МФО ### Онлайн-заявка на микрозайм до 15 000 рублей В этом сценарии скорость обработки критична, поэтому мы предлагаем использовать автоматическую проверку: 1. Клиент загружает фото паспорта и селфи с паспортом. 2. Отправляем асинхронный запрос к API Антифрод 2.0 (`async=true`). 3. Ключевой параметр для проверки — `overall_result:` * `definitely_fake`: отклоняем заявку * `potentially_fake`: отправляем на ручную проверку * `bad_image_quality` и `other`: просим прислать изображения повторно * `genuine`: если по вашему скорингу всё хорошо, выдаём займ 4. Если вы хотите выстроить логику обработки самостоятельно, обратите внимание на следующие параметры: * `image.type`: убеждаемся, что это "passport" и "selfie". * `image.quality`: проверяем параметры качества изображения, которые вы считаете критичными. * в случае с `image.type=selfie` проверяем `selfie.fake.result` и отклоняем при `true`. * в случае с `image.type=`passport проверяем `passport.ai_checks.image_modifications_detected.result` — отклоняем при `true`. ### POS-кредитование Здесь также важна скорость, но сумма может быть выше: 1. Консультант фотографирует паспорт клиента и делает селфи с паспортом. 2. Рекомендуем использовать синхронный запрос к API (`async=false`), чтобы максимально быстро получить результат. 3. Ключевые параметры: * Те же, что и для микрозайма до 15 000 рублей. * Дополнительно проверяем `passport.ai_checks.visual_field_missing, passport.ai_checks.photo_not_found` и все параметры `logical_checks`. ### Онлайн-заявка на крупный заём Для займов на большие суммы можно позволить более тщательную проверку: 1. Клиент загружает фото паспорта, селфи с паспортом и дополнительные документы. 2. Используем асинхронный запрос (`async=true`). 3. Ключевые параметры: * Все параметры, указанные в предыдущих сценариях. * `passport.file_metadata`: проверяем наличие и соответствие метаданных. * `passport.ai_checks.photo_gender_mismatch`: дополнительная проверка соответствия пола. ### Обновление данных в личном кабинете Здесь скорость не критична, но важна точность: 1. Клиент загружает новые фото документов. 2. Используем асинхронный запрос (`async=true`). 3. Ключевые параметры: * Все параметры, указанные для крупного займа. * Сравниваем новые данные с уже имеющимися в системе. ### Общие рекомендации по использованию API: 1. Всегда проверяйте `overall_result` как первичный индикатор подлинности. 2. Обращайте внимание на `image.quality` для всех типов запросов. Если качество низкое, запросите повторную отправку изображения. 3. Для селфи с паспортом (`image.type=selfie`) критически важно проверять `selfie.fake.result` и `selfie.fake.confidence`. 4. Для изображения паспорта (`image.type=`passport) обратите особое внимание на `passport.ai_checks.image_modifications_detected.result` — это прямой индикатор подделки. 5. Все параметры в `passport.logical_checks` важны, так как указывают на логические несоответствия в данных паспорта. 6. Для более тщательной проверки используйте `passport.file_metadata`, особенно для крупных займов. 7. Настройте разные пороговые значения для параметров в зависимости от суммы займа и типа продукта. 8. Используйте `task_tags` для связывания запросов с конкретными клиентами или заявками в вашей системе. 9. При высокой нагрузке используйте асинхронные запросы (`async=true`) и настройте систему опроса результатов. 10. Регулярно анализируйте статистику ответов API для выявления новых паттернов мошенничества и корректировки алгоритмов проверки. Применяя эти сценарии и рекомендации, вы сможете эффективно использовать Антифрод 2.0 для борьбы с различными видами фрода в процессах вашей МФО. Если вы хотите использовать наш сервис в рамках банковских или иных финансовых бизнес-процессов, напишите нам в[ телеграм](https://t.me/dbrain_support_bot) или на --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.dbrain.io/servisy/proverka-dokumentov/antifrod-2.0.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.