TL;DR
- Документация для обхода должна сохранять код, таблицы параметров, контекст заголовков, язык и версию; только количество страниц не измеряет качество.
- Используйте карту сайта и обнаружение навигации вместе, фильтруйте нерелевантные маршруты и сравнивайте вывод с статических и JavaScript-рендеренных страниц перед масштабированием.
- Проверяйте Markdown на наличие отсутствующих заголовков, поломанных кодовых границ, неполных таблиц, дублирующихся путей, пустого контента и разницы версий.
- Ползите только разрешенный контент. Открытый API для обхода не дает доступа к частной документации и не обходить политику сайта.
Введение: Документация — это структурированные данные, даже когда она публикуется в формате HTML
Nstdata Crawl — это уровень сбора в этом рабочем процессе; его обзор продукта описывает получение страниц и сайтов для downstream-данных.
Сайт документации создан для читателей, которые ищут страницы, версии и примеры кода. LLM нуждается в тех же отношениях для успешной извлечения. Если паук возвращает параметр API без его конечной точки, код без его языковой метки или старую страницу версии 1 рядом с текущей страницей версии 2 без метаданных версии, полученный контекст может ввести в заблуждение, даже если каждый URL возвращен успешно.
Этот гид охватывает обнаружение документации, обход, проверку Markdown и метаданные. Он не пытается обучить полной системе векторного поиска. Для последующей стадии внедрения см. отдельный пошаговый гид по веб-сайту до базы данных векторов Pinecone. Nstdata Crawl поддерживает Markdown, HTML, сырые данные, ссылки, PDF и вывод скриншотов; текущие документы по обходу описывают компромиссы и интерфейсы задач.
Что делает документацию готовой для LLM?
Полезная запись документации включает полный контент, значимую иерархию заголовков, целостный код и таблицы, стабильный URL источника, версию, язык, временную метку обхода и хэш контента. “Конвертация Markdown завершена успешно” не является тем же самым, что и “LLM может ответить на предполагаемый вопрос.” Проверьте конкретную информацию, необходимую для вашей задачи в downstream.
Для страниц справки по API сохраняйте метод, конечную точку, детали аутентификации, имена параметров, типы, значения по умолчанию, поля ответа и поведение ошибок в одном локальном контексте. Для руководств сохраняйте последовательность шагов и предупреждений. Для журналов изменений сохраняйте даты выпуска и статусы меток.
Как обход документации отличается от общего веб-скрейпинга
Документы часто используют фреймворки, такие как Docusaurus, Nextra, VitePress или MkDocs, но их режимы рендеринга различаются в зависимости от развертывания. Не предполагайте, что браузер на JavaScript всегда требуется. Проверьте вывод со страницы, которая вам нужна: если ключевой текст отсутствует в полученном результате, тогда протестируйте рендеринг в браузере или документированное ожидание. Открытые документы для Docusaurus, VitePress и MkDocs описывают их системы публикации; поведение развернутого сайта все еще необходимо проверять напрямую.
Шаг 1: Откройте URL-адреса документации
Используйте карту сайта как один источник, а ссылки сайта как другой. Карта сайта может включать страницы, которые навигация документации больше не показывает, в то время как обнаружение ссылок может пропускать сиротские страницы, которые указаны только в карте сайта. Сравните полученные наборы URL-адресов и классифицируйте каждый путь перед обходом.
Обнаружение карты сайта против обхода ссылок
| Метод | Полезно для | Слепое пятно для проверки |
|---|---|---|
| Карта сайта | заявленный инвентарь страниц и подсказки lastmod | устаревшие или упущенные записи |
| Обнаружение ссылок | страницы, доступные из навигации документации | сиротские страницы или глубокие ссылки |
| Отобранный список URL | контролируемая группа пилотных или выпускаемых наборов | ручная нагрузка по поддержке |
Протокол карт сайта определяет формат XML, но поле lastmod является метаданными, предоставляемыми издателем, а не независимой гарантией изменения контента. Используйте его для приоритизации проверок, затем сравните содержимое страниц.
Исключите нерелевантные и дублирующиеся URL
Нормализуйте имена хостов, удалите фрагменты и решите, какие параметры запроса влияют на идентичность страницы. Исключите результаты поиска, страницы входа, варианты отслеживания, маршруты печати, дублирующиеся локализованные пути, активы и нерелевантные маркетинговые страницы. Сохраняйте как версии документации, так и локализованные страницы только когда они находятся в пределах области. Запишите, почему страница была исключена, чтобы разрыв в покрытии можно было объяснить.
Шаг 2: Обход страниц документации в Markdown
Сначала запустите небольшой пилотный проект. Для известной страницы одностраничный скрейп избегает переменных обнаружения сайта. Для раздела документации ограниченный обход сайта может обнаружить ссылки с учетом глубины и лимита страниц. Текущий пример Python SDK использует NstDataClient, CrawlRequestDto и Format.MARKDOWN:
import os from nstdata_ai_crawl import CrawlRequestDto, Format, NstDataClient with NstDataClient(os.environ["NSTDATA_API_TOKEN"]) as client: task = client.submit_crawl_task(CrawlRequestDto( url="https://docs.example.com/", formats=[Format.MARKDOWN], maxDepth=2, maxPages=80, includeUrls=["*docs.example.com/*"], excludeUrls=["*docs.example.com/search*", "*docs.example.com/login*"], ignoreQuery=True, onlyMainContent=True, timeout=60_000, )) print("task id:", task.id)
Этот код отправляет задание; он не отображает завершенную коллекцию страниц. Проводите опрос статуса, извлекайте список страниц, следуйте за его курсором и читайте упомянутые артефакты Markdown, как описано в документации. Текущий справочник по ползучести перечисляет GET /api/v1/crawl/status/{crawlId} и /pages/{crawlId}; вебхуки в настоящее время не поддерживаются, поэтому сделайте опрос частью дизайна повторных попыток и тайм-аутов вашего рабочего процесса.
Документация, отображаемая JavaScript
Проверьте, присутствует ли известная фраза, блок кода или заголовок страницы в возвращенном Markdown. Сравните с отображаемой страницей в браузере. Если контент отсутствует, проверьте рендеринг JavaScript и ожидание селектора, когда это поддерживается. Избегайте включения рендеринга глобально без причины: это может увеличить время и усложнить определение того, произошла ли ошибка из-за обнаружения, рендеринга или извлечения.
Шаг 3: Сохраните заголовки, блоки кода и таблицы
Markdown должен сохранять H1/H2/H3, обрамления кода с метками языков, таблицы, списки, предупреждения и внутренние ссылки. Полезный образец проверки может содержать:
## Создание токена Отправьте токен в заголовке `x-api-key`. | Поле | Тип | Обязательно | |---|---|---| | `project_id` | строка | да | ```python client = Client(token=token)
Это синтетическая фикция для проверки форматирования, а не захваченный вывод с живой страницы. После ползучести проверьте, что открытые и закрытые обрамления кода совпадают, и что заголовки таблиц и количество ячеек остаются последовательными.
Сохраните контекст конечной точки и параметров
Метод API трудно использовать, если его таблица параметров отделена от конечной точки. Храните ближайшие родительские заголовки с каждым фрагментом. Сохраняйте предупреждения, такие как "устаревший" или "обязательно для этой версии"; они часто меняют, безопасно ли копировать пример.
Обрабатывайте образцы кода на нескольких языках
Сохраните метку языка кода, SDK/версию, название конечной точки или функции и окружающий объяснительный текст. Не объединяйте примеры на Python и Node.js в один недифференцированный фрагмент. Если блок кода очень длинный, разбивайте по логическим границам примера или функции и повторяйте соответствующий заголовок пути.
Шаг 4: Обрабатывайте версии документации и локализацию
Обрабатывайте /v1/, /v2/, "последняя" и архивные маршруты как явные состояния. Храните version, status, language и canonical_url отдельно от текста тела. latest — это движущий указатель; зафиксируйте разрешенную версию, если сайт это определяет. Храните переводы отдельно и избегайте объединения примеров из разных локалей без проверки.
Шаг 5: Нормализуйте метаданные
Для каждой страницы сохраняйте:
{ "source_url": "https://docs.example.com/v2/reference/users", "canonical_url": "https://docs.example.com/v2/reference/users", "title": "API пользователей", "section_path": "Справочник API / Пользователи", "version": "v2", "language": "ru", "crawled_at": "временная метка выполнения", "content_hash": "хеш нормализованного тела" }
Нормализуйте идентичность URL последовательно и хешируйте нормализованное тело, а не полный HTML, чтобы изменение макета не принудило к ненужному повторному внедрению. Никогда не подделывайте даты обновления источника, когда страница их не публикует.
Шаг 6: Проверяйте качество ползучести
Создайте автоматические проверки на пустое тело, неожиданно короткий текст, повторяющийся шаблон, отсутствие заголовка, незакрытые обрамления кода, неправильно оформленные таблицы, сломанный канонический URL, дублированный нормализованный контент и отсутствие метаданных версии. Затем вручную отбирайте страницы по типу: обзор, справочник API, учебник с большим количеством кода и динамическую страницу, если в документации используется одна.
Проверка полноценности контента должна быть связана с заданием: для страницы API сравните ожидаемые названия конечных точек и важные поля; для учебника проверьте, что заголовки и блоки кода присутствуют. Зеленый HTTP статус не доказывает, что извлеченный контент полный.
Шаг 7: Храните документацию для использования LLM
Сохраните артефакты ползучести в виде файлов Markdown или JSONL во время пилота, чтобы рецензент мог их просмотреть. База данных становится полезной, когда вам нужны инкрементные обновления, статус на уровне страниц, разрешения или доступ к запросам. Запись JSONL должна хранить текст страницы и метаданные вместе, с записями фрагментов, ссылающимися на идентификатор страницы. См. реализацию Crawl-to-Pinecone для следующего этапа загрузки.
Большие сайты, мониторинг и ответственное обращение
Ограничьте первый обход глубиной, лимитами страниц и фильтрами URL. Следите за статусом задачи и ошибками на странице; продолжайте с контрольной точки, а не начинайте заново каждую страницу после одной ошибки. Используйте разумные скорости и уважайте условия сайта, рекомендации robots и разрешения на доступ. Не пытайтесь обойти авторизацию или ограничения для контента, который вы не имеете права собирать.
Измерьте:
- Покрытие URL: действительные обнаруженные страницы документов / ожидаемые в рамках документа страницы.
- Полнота контента: выборочные страницы с необходимыми разделами / выборочные страницы.
- Сохранение кода: целые соответствующие блоки кода / выборочные соответствующие блоки.
- Доля дубликатов: нормализованные дубликаты документов / принятые документы.
- Полнота метаданных: записи с необходимыми полями источника/версии / принятые записи.
Эти метрики более полезны, чем простое подсчитывание успешных запросов. Храните манифест выборки и повторно выполняйте его после изменений в пауках, сайтах документов или извлечении.
Общие ошибки и итоговый контрольный список
Общие ошибки включают в себя обход только главной страницы, исключение отношений между старыми/текущими версиями, индексацию страниц поиска, потерю меток кода, смешение языков, принятие пустых страниц, отрендеренных клиентом, и рассмотрение неудачных запросов как удаленного контента.
Перед отправкой документации в LLM проверьте обнаружение URL, диапазон доступа, успех на уровне страницы, структуру контента, метаданные версии и языка, обработку дубликатов и поведение обновления. Сохраните оригинальный URL-адрес источника, прикрепив его к частям, чтобы каждый ответ мог ссылаться на него.
Для другой части рабочего процесса продолжите с руководства по стеку веб-данных и руководства по автоматизации браузера.
Заключение
Обход документации для контекста LLM — это задача качества структурированных данных. Обнаруживайте страницы из нескольких источников, ограничивайте обход, сохраняйте технические взаимосвязи внутри каждой страницы и проверяйте результат на соответствие представительным вопросам API. После того, как Markdown пройдет эти проверки, он может использоваться для разбиения, поиска, RAG или инструмента агента.
Часто задаваемые вопросы
Q: Как мне обойти сайт документации?
Начните с карты сайта и инвентаризации навигации, фильтруйте разрешенные пути документации, отправьте ограниченный обход, получайте каждый результат и проверяйте Markdown перед его сохранением.
Q: Какой формат лучше всего подходит для документации LLM?
Markdown — практичный текстовый формат, когда он сохраняет заголовки, код, таблицы, ссылки и метаданные источника; HTML может быть лучше, когда требуется пользовательский парсинг.
Q: Как мне преобразовать документы в Markdown?
Используйте инструмент извлечения страниц, который возвращает Markdown, затем проверьте результат на наличие отсутствующих разделов, неправильно оформленных таблиц и целостности блоков кода.
Q: Требуют ли документы Docusaurus рендеринга JavaScript?
Не обязательно; сначала проверьте вывод целевой страницы и включайте рендеринг только тогда, когда необходимый контент отсутствует в нерендеренном результате.
Q: Как мне сохранить блоки кода для RAG?
Сохраняйте заблокированные блоки с их языковыми метками и близким контекстом заголовков, и разделяйте длинные примеры только на логических границах.
