Web scraping для AI начинается с выбора минимального способа получить нужные данные. Для известной страницы достаточно scrape, для поиска URL по сайту нужен map, а для контролируемого обхода раздела — асинхронный crawl. Чем уже задача, тем меньше стоимость, дублирование и риск собрать лишние данные.
Сначала определите результат
Фраза «скачать сайт» почти всегда слишком широкая. Уточните, что попадёт в следующий этап: чистый Markdown для поиска, HTML для собственного парсера, ссылки для очереди или metadata для каталога. Зафиксируйте обязательные поля, максимальное число страниц и допустимый возраст результата.
Для ответа на один вопрос может хватить двух страниц документации. Для базы знаний потребуется стабильный обход выбранных разделов. Для мониторинга цен важнее несколько конкретных URL и обнаружение изменений, чем полная копия домена.
От результата зависит и способ проверки. Markdown оценивают по сохранности заголовков, списков и таблиц. Для ссылок важны канонизация и полнота. Для структурированных полей — схема, типы и доля записей, прошедших валидацию.
Когда использовать scrape, map и crawl
Scrape подходит, когда URL уже известен и нужен контент одной страницы. Это хороший строительный блок для AI-поиска: поисковик находит кандидатов, а приложение читает только несколько лучших документов.
Map собирает карту ссылок без глубокого чтения каждой страницы. Используйте его, чтобы найти документацию, карточки каталога или материалы определённого раздела, а затем отберите URL по маске и назначению.
Crawl последовательно обходит связанные страницы и поэтому обычно выполняется как фоновая задача. Задайте стартовый URL, предел количества страниц, глубину и правила включения. Для map и crawl в LLMTOKENAPI обязателен Idempotency-Key: повтор с тем же ключом не должен создавать вторую работу и второе списание. Подробности и форматы запросов есть на странице веб-скрапинга и в API-документации.
Уважайте правила сайта
Перед обходом проверяйте условия использования ресурса, применимые права на контент и технические ограничения. Файл robots.txt задаёт правила доступа для автоматических агентов к путям сайта. Стандарт описан в RFC 9309: это технический протокол, а не разрешение на любое дальнейшее использование данных.
Ограничивайте частоту запросов и параллельность, корректно идентифицируйте свой агент там, где это уместно, и не пытайтесь обходить авторизацию или защитные механизмы. Не собирайте персональные или чувствительные данные «на всякий случай». Если разрешённость сценария неочевидна, её нужно проверить до запуска большого обхода.
Нормализуйте URL до постановки в очередь
Одна страница часто доступна по нескольким адресам: с UTM-параметрами, завершающим слешем, якорем или разным порядком query-полей. Без нормализации crawler будет повторно читать одинаковый контент.
Практический порядок:
- Разрешите относительный адрес относительно текущей страницы.
- Удалите fragment, который не влияет на серверный документ.
- Отбросьте известные аналитические параметры.
- Нормализуйте host и стандартный порт.
- Учтите canonical URL, если он корректен и остаётся в разрешённой области.
- Вычислите ключ дедупликации и только затем добавляйте адрес в очередь.
Не удаляйте все query-параметры автоматически: для каталога они могут выбирать реальную страницу или локаль. Правила должны быть доменными и тестироваться на примерах.
Извлекайте основной контент
Сырой HTML содержит навигацию, cookie-баннеры, повторяющийся footer и скрытые элементы. Если передать всё это модели, контекст станет дороже, а смысловые фрагменты — хуже. Сохраняйте заголовок, основную статью, структуру H2/H3, списки, таблицы и значимые подписи. Удаляйте повторяющийся интерфейс, но оставляйте ссылки, которые нужны для происхождения и дальнейшего обхода.
Полезно хранить две формы: нормализованный текст для индексации и минимальный набор метаданных для аудита. В него входят исходный и канонический URL, время получения, HTTP-статус, content type и hash очищенного содержимого. По hash легко понять, изменилась ли страница и нужна ли повторная обработка.
Планируйте ошибки и повторные попытки
Сетевой таймаут, 429 и временный 5xx можно повторить с растущей задержкой и случайным разбросом. Постоянный 404, запрет доступа или неподдерживаемый тип контента обычно повторять бессмысленно. Ограничьте число попыток и сохраняйте конечную причину, чтобы job не завис навсегда.
Идемпотентность особенно важна при сбое клиента после постановки задачи. Клиент может не получить ответ и отправить тот же запрос снова. Стабильный ключ, привязанный к логической операции, позволяет серверу вернуть прежний job. Не генерируйте новый ключ для каждого сетевого повтора.
Для больших обходов отдавайте результат порциями и следите за сроком хранения. В LLMTOKENAPI результаты map и crawl хранятся 24 часа, поэтому потребитель должен забрать и обработать их вовремя.
Контролируйте качество и бюджет
До запуска задайте верхнюю границу страниц и глубины, а после измеряйте долю полезных документов, дубли, средний размер, ошибки извлечения и стоимость пригодной страницы. Если из тысячи URL в индекс попали двадцать полезных, проблема обычно в слишком широких правилах, а не в недостаточном лимите.
Начните с малого участка сайта, посмотрите выборку очищенного Markdown и только затем расширяйте обход. Производственный web scraping — это управляемый конвейер с чёткой областью, а не бесконечный рекурсивный скачиватель.
