Firecrawl: сайт в Markdown для нейросети

Firecrawl: сайт в Markdown для нейросети — это API, который по адресу страницы возвращает её содержимое в чистом Markdown, HTML или структурном JSON. В документации проекта продукт назван контекстным API для ИИ-агентов: он ищет, собирает и позволяет взаимодействовать с живой веб-страницей. Дальше — выбор операции, копируемый запрос и приёмка результата.

Что такое Firecrawl и где границы задачи

В документации проекта Firecrawl описан как контекстный API для ИИ-агентов: он ищет в вебе, собирает содержимое страниц и позволяет продолжать работу с уже собранной страницей. Три базовые операции названы прямо: Search ищет в вебе и отдаёт полное содержимое результатов, Scrape извлекает контент любого URL как Markdown, HTML или структурный JSON, Interact продолжает работу со страницей — клики, формы, динамический контент. Это и есть границы задачи: подготовка веб-контента к подаче в языковую модель.

В том же введении перечислены причины, по которым продукт применяют: вывод, готовый для LLM (чистый Markdown, структурный JSON, скриншоты), обработка сложных случаев (прокси, антибот-защита, рендеринг JavaScript, динамический контент), надёжность для продакшена, скорость и сервер MCP для подключения к ИИ-инструментам. В README проекта к этому добавлены вращающиеся прокси, оркестрация, лимиты запросов и заблокированный JavaScript-контент — всё это заявлено как работа без конфигурации со стороны пользователя.

Границы задачи стоит очертить честно. Firecrawl — это сервис подготовки веб-контента для дальнейшей обработки. Документация проекта говорит, что по умолчанию сервис уважает директивы robots.txt, а соблюдение политик сайтов — ответственность конечного пользователя. Это условие применения: собирать чужой контент нужно с учётом правил конкретного сайта.

Второе ограничение — предметное. Продукт относится к веб-контенту и документам. В README перечислены Parse (локальные PDF, DOCX, XLSX, HTML в Markdown или структурный JSON), Map (обнаружение всех URL сайта), Crawl (рекурсивный сбор контента целых сайтов), Batch Scrape (асинхронный сбор тысяч URL), Monitor (уведомления об изменениях на сайте). Каждая операция решает свою задачу, и подмена одной другой — самая частая причина неверного результата.

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

Отдельно про версию. В документации проекта примеры обращаются к адресу https://api.firecrawl.dev/v2/scrape и к другим операциям того же семейства. Поддержку конкретных параметров стоит сверять с официальной инструкцией проекта на момент работы: набор возможностей у сервиса развивается, а статья фиксирует состояние документации на момент подготовки.

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

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

Исходный набор. Есть учебный справочник по адресу https://docs.example.test/. В нём три страницы: /intro, /limits и /archive. Требуется только /limits. Страница /limits содержит заголовок «Лимиты» и текст: Разрешено 12 заявок в день. Поддержка недоступна в выходные. Задача — получить Markdown именно этой страницы и принять его по проверкам.

Маршрут выбора операции. Известная страница /limits — это scrape: адрес известен, нужен контент одной страницы. Сбор страниц справочника в заданной области ссылок — это crawl: нужен обход нескольких страниц с отчётом о том, что вернулось и что не удалось получить. Только список адресов для ручного отбора — это map: нужен перечень URL для отбора.

Копируемый шаблон запроса. Замените адрес на свой публичный URL и подставьте ключ через переменную окружения:

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com","formats":["markdown"]}'

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

Что вернёт запрос. В документации проекта показан ответ вида: success: true, объект data с полем markdown, блок metadata с заголовком страницы, описанием, языком, ключевыми словами, директивой robots, данными Open Graph, полем sourceURL и кодом statusCode. Для приёмки важны два поля: сам markdown и sourceURL — адрес, с которого получен текст. Без сохранённого sourceURL цитировать результат в базе знаний нельзя: теряется привязка утверждения к источнику.

Порядок действий по шагам:

1. Определите задачу: одна известная страница, обход сайта или список адресов.
2. Выберите операцию: scrape, crawl или map соответственно.
3. Сохраните ключ в переменной окружения, не в тексте скрипта.
4. Отправьте запрос с форматом markdown.
5. Проверьте statusCode и наличие непустого поля markdown.
6. Сверьте содержимое с исходной страницей по чек-листу приёмки.
7. Сохраните sourceURL рядом с текстом для последующего цитирования.

Этот маршрут закрывает типовую задачу: получить текст одной публичной страницы и передать его дальше в модель или в базу знаний. Следующий раздел разводит учебный эталон и то, что даёт реальный запуск.

Ручной эталон и результаты реального запуска

Учебный эталон приёмки для страницы /limits задан заранее, до запроса. Он состоит из четырёх пунктов: обе оговорки сохранены; число 12 не заменено на 20; навигация не выдана за основной текст; реальный адрес источника сохранён для последующего цитирования. Это ручной эталон — набор ожиданий, с которым сравнивают результат.

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

Сравним два взгляда на один и тот же сбор.

Из таблицы видно, где чаще всего расходятся ожидание и факт. Число в эталоне фиксировано как учебное значение: 12 заявок в день — это содержимое синтетической страницы. Если на реальной странице стоит другое число, эталон не «побеждает»: приёмка фиксирует расхождение и требует разобраться, изменилась страница или сбор потерял фрагмент.

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

Про навигацию. Сайты часто отдают меню, хлебные крошки и футер вместе с основным текстом. В документации проекта для CLI показан флаг --only-main-content, который ограничивает вывод основным содержимым страницы. Это подсказка: если в Markdown попали ссылки меню, стоит проверить доступные параметры выборки и повторно принять результат.

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

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

Отрицательный случай и неизвестные значения

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

Первая: HTTP 200 с формой входа вместо текста. Сервер ответил успешно, но вернул страницу авторизации. Сбор не принят: содержимого, которое требовалось, в ответе нет. Код ответа здесь не доказательство пригодности.

Вторая: пустой Markdown. Поле markdown пришло, но текста в нём нет. Сбор не принят: передавать в модель нечего.

Третья: запрошен /archive вместо /limits. Получен другой адрес или другая операция. Сбор не принят: неверный URL или неверный выбор операции.

Сведём диагностику в таблицу.

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

Про неизвестные значения скажем прямо. Учебный пример задаёт условные величины: 12 заявок в день и недоступность поддержки в выходные. Это содержимое синтетической страницы. Реальные лимиты, квоты и тарифы зависят от аккаунта и условий сервиса; их стоит смотреть в личном кабинете и в актуальной документации проекта. Подставлять учебное число в планирование нельзя.

Так же осторожно стоит относиться к заявлениям о скорости и охвате. В README проекта приведены собственные оценки: покрытие 96% веба, включая страницы с активным JavaScript, и P95-задержка 3.4 секунды по миллионам страниц. Это утверждения владельца продукта о своём сервисе, и в планировании их стоит проверять на своих задачах.

Отдельно про сторонние обзоры. Например, в блоге Bright Data приведено сравнение Crawl4AI и Firecrawl, а в блоге ScrapingBee — обзор инструментов веб-скрейпинга с собственными тестами. Это коммерческие конкуренты, и их измерения, проценты и цены относятся к их методикам. Переносить эти числа на Firecrawl нельзя: они не становятся нашими фактами.

Условия доступа без неподтверждённых тарифов

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

Что известно про способы подключения. В документации перечислены Python SDK, Node SDK, CLI и API reference. CLI устанавливается одной командой, которая проводит аутентификацию в браузере и добавляет навыки обнаруженным кодинг-агентам:

npx -y firecrawl-cli@latest init --all --browser

После установки агент нужно перезапустить, чтобы он увидел новые навыки. Для MCP-клиентов в README проекта приведён конфиг подключения:

{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "fc-YOUR_API_KEY"
      }
    }
  }
}

Ключ в этом конфиге — заполнитель. Настоящий ключ храните в переменной окружения или в защищённом хранилище секретов.

Про лицензию и развёртывание. В README проекта сказано, что проект распространяется в основном под лицензией AGPL-3.0, а SDK и часть компонентов интерфейса — под MIT. Там же указано, что сервис доступен как облако и как открытый код, который можно развернуть самостоятельно. Для самостоятельного развёртывания в README приведена ссылка на руководство по self-hosting.

Про тарифы и квоты. В сохранённой документации проекта конкретные цены и объёмы квот не приведены. Планировать бюджет стоит по актуальным условиям сервиса на момент работы: они меняются, а статья описывает документированный маршрут работы. Страница map указывает расход 1 кредит за вызов независимо от числа возвращённых URL, включая приведённый пример с лимитом 100 000 URL. У scrape и дополнительных опций есть собственные правила списания кредитов; перед работой сверяйте выбранную операцию и параметры с её документацией.

Про доступ из России. В сохранённой документации проекта условия доступа по странам не описаны. Проверяйте доступность сервиса и оплаты по актуальным условиям на момент работы.

Проверка фактов, ограничений и ссылок

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

Введение в документации проекта описывает продукт как контекстный API для ИИ-агентов и перечисляет три базовые операции: поиск, сбор и взаимодействие. Там же сказано, что первый запрос к scrape не требует ключа, а ключ нужен для повышенных лимитов.

Страница про map в документации проекта объясняет назначение операции: переход от одного URL к карте всего сайта. Адреса обнаруживаются в первую очередь из карты сайта, дополняются результатами поисковых систем и ранее собранными страницами. Операция ориентирована на скорость и может не охватить все ссылки сайта; для более полного и свежего списка документация предлагает использовать crawl, который обходит страницы рекурсивно и сообщает, что вернул и что не удалось получить. Для ссылок одной конкретной страницы документация предлагает формат links у операции scrape.

README проекта перечисляет дополнительные возможности: Parse для локальных документов, Agent для автономного сбора данных по описанию, Batch Scrape для асинхронного сбора тысяч URL, Monitor для уведомлений об изменениях. Там же приведены примеры на Python, Node.js, cURL и CLI, а также SDK для нескольких языков.

Про агентские модели. В README проекта сказано, что каждый запуск агента выполняется на модели spark-2, а имена spark-1-pro и spark-1-mini принимаются для обратной совместимости и помечены как устаревшие. Уровень усилий (low, medium, high) меняет бюджет рассуждений.

Про ответы. В документации проекта показано, что SDK возвращают объект data напрямую, а cURL возвращает полный payload. Это важно при разборе ответа: структура у разных способов вызова отличается.

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

Ссылки для самостоятельной проверки:

• Введение: https://docs.firecrawl.dev/introduction
• Операция map: https://docs.firecrawl.dev/features/map
• README проекта: https://raw.githubusercontent.com/firecrawl/firecrawl/main/README.md

Что остаётся за рамками проверки. Числовые обещания владельца продукта — покрытие и задержки — относятся к его собственным замерам и требуют проверки на ваших задачах. Измерения сторонних обзоров относятся к методикам этих изданий. Учебные значения из нашего примера задают условный вход.

Карточка передачи Markdown в базу знаний

Перед передачей результата составьте отдельную карточку приёмки. В ней укажите запрошенный URL, фактически полученный адрес и назначение страницы. Для учебного справочника назначение /limits — передать дневное правило и условие работы поддержки. Сохраните исходный ответ API рядом с подготовленным Markdown: если позже пропадёт оговорка, это поможет определить этап потери. Такая карточка заполняется по реальному запросу читателя; ниже задан только её учебный контракт.

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

Проверьте и подмену адреса. Если собрана /archive, найденный в ней похожий текст не подтверждает актуальную страницу /limits. Сначала установите, какой документ вернулся. Затем сравните его содержание с действительным исходником. Сходство заголовка и числа не устраняет различие документов. Это особенно важно, когда справочник хранит несколько редакций инструкции рядом.

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

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

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

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

Что такое Firecrawl простыми словами?

Это API, который по адресу страницы возвращает её содержимое в чистом Markdown, HTML или структурном JSON. В документации проекта продукт назван контекстным API для ИИ-агентов. Он ищет в вебе, собирает страницы и позволяет продолжать работу с уже собранной страницей. Результат рассчитан на подачу в языковую модель или в базу знаний.

Чем scrape отличается от crawl и map?

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

Нужен ли API-ключ для первого запроса?

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

Почему в Markdown попала навигация сайта?

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

Как понять, что сбор страницы пригоден?

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