Создание базы знаний компании на основе вашего сайта документов
TL;DR
Ассистент компании по документации создается на основе выбранного, версиированного корпуса документации — не на основе слепой копии каждого URL под доменом компании.
Обходите публичные документы в Markdown, сохраняйте метаданные продукта / версии / языка, затем разбивайте, встраивайте, извлекайте и требуйте источников ссылок.
Рассматривайте частную документацию как отдельную зону безопасности: обходчик не является поставщиком идентификации или системой фильтрации разрешений.
Начните с одного продукта и одной версии документации, проверяйте с реальными вопросами поддержки и расширяйтесь только после того, как правила доступа и цитирования работают.
Введение: Зачем создавать базу знаний из сайта документов?
Nstdata Crawl — это слой сбора в этом рабочем процессе; его обзор продукта описывает извлечение страниц и сайтов для последующих потоков данных.
Сайт документации SaaS часто отвечает на одни и те же вопросы от клиентов, поддержки и разработчиков: как аутентифицироваться, какую версию SDK установить, что делает параметр или как устранить ошибку. Ассистент на основе извлечения может облегчить запрос этих страниц на естественном языке, при условии, что индекс сохраняет, из какого продукта и версии был получен каждый ответ.
Цель состоит в создании уровня поиска, основанного на доказательствах, а не автоматического двигателя правды. Система может извлечь устаревшую страницу или неправильно интерпретировать таблицу параметров, если ввод и оценка слабы. Nstdata Crawl может предоставить содержимое страницы в формате Markdown и поддерживать ограниченное открытие сайта; ваше приложение остается ответственным за выбор, разрешения, индексацию, политику обновления и поведение ответов. Официальная документация по Crawle описывает слой получения и форматы вывода.
Попробуйте Nstproxy Crawl - Начните Бесплатно Уже Сегодня
Публичные страницы документов
↓ обход и проверка
Markdown + метаданные происхождения
↓ нормализация и разбивка
Встраивания + векторные записи
↓ извлечение соответствующих отрывков
Ответ ассистента с URL-адресами источников и ярлыками версий
Пользователь может спросить: «Какой заголовок аутентифицирует текущий API?» Ассистент должен извлечь страницу из текущей версии API, привести соответствующее доказательство и показать его URL. Если корпус содержит как старую, так и текущую версию и вопрос не указывает, какая из них, ассистент должен спросить или указать, какую версию он использовал.
Шаг 1: Аудит документационного сайта
Начните с информационной архитектуры сайта, а не с краулера. Просмотрите его карту сайта, навигацию, селектор версий, локальные пути, канонические ссылки и границы аутентификации. Создайте таблицу URL с решением и владельцем:
Группа страниц
Приоритет
Пример метаданных
Правило загрузки
Введение
Высокий
продукт, язык, версия
включить текущую версию
API справочник
Высокий
конечная точка, версия, SDK
сохранить таблицы параметров
Устранение неполадок
Высокий
компонент, код ошибки
сохранить контекст кода и предупреждений
Цены
Средний/высокий
валюта, дата вступления в силу
обновлять чаще
Архив изменений
Зависит
дата выпуска, статус
отделить от текущей документации
Документация только для входа
Отдельный проект
ACL и владелец
не раскрывать через публичный индекс
Определите страницы документации с высокой ценностью
Небольшая пилотная проверка обычно должна охватывать Введение, API Справочник, Аутентификацию, руководства по SDK, Устранение неполадок и FAQ. Эти категории отвечают на конкретные вопросы поддержки и выявляют проблемы парсинга на ранних стадиях. Сохраните маркетинговые страницы, если только помощник не предназначен для ответов на вопросы о позиционировании продукта тоже.
Обработка нескольких версий и языков
Не объединяйте содержимое /v1/ и /v2/ в один недифференцированный набор. Храните product, version, language, status (текущий/устаревший) и canonical_url. Применяйте фильтр извлечения из выбранного пользователем продукта и версии. Сохраняйте локализованные страницы отдельными, так как различия в переводе могут повлиять на параметры и примеры.
Шаг 2: Сканирование публичной документации в Markdown
Используйте уровень сканирования сайта от корня документации с ограничениями по страницам и глубине. Включите только пути документации, исключите маршруты входа/поиска и нерелевантные ресурсы, и просмотрите обнаруженный список URL перед индексацией. Проведите небольшой тест в начале с репрезентативной статической страницы, страницы API с большим количеством кода и страницы, использующей рендеринг на стороне клиента.
Документированный Python SDK поддерживает CrawlRequestDto с такими полями, как url, formats, maxDepth, maxPages, includeUrls, excludeUrls, ignoreQuery, и onlyMainContent:
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=3, maxPages=250, includeUrls=["*docs.example.com/*"], excludeUrls=["*docs.example.com/search*","*docs.example.com/login*"], ignoreQuery=True, onlyMainContent=True, timeout=60_000,)) crawl_id = task.idprint(crawl_id)
Это этап отправки; не путайте возвращаемый идентификатор задачи с завершёнными страницами. Проверяйте статус задачи, просматривайте результаты и получайте любые упомянутые артефакты Markdown через задокументированную конечную точку хранения. Храните неуспешные URL-адреса в отчёте о запуске. Для практической реализации "ползунка в векторный магазин" смотрите руководство по рабочему процессу Pinecone.
Шаг 3: Очистка и организация содержания
Удаляйте повторяющиеся навигационные элементы или баннеры cookie только тогда, когда они явно являются шаблоном. Сохраняйте заголовки, метки языка кода, таблицы параметров, предостережения, ссылки и уведомления о версиях. Пример до/после должен показать, почему существует правило очистки:
Before: [Docs Home] [API] [SDK] | Authentication | Use the x-api-key header... | Related: SDKs
After: ## Authentication
Send the API token in the `x-api-key` request header...
Строка "Before" является иллюстративной, а не результатом ползунка. Для каждой реальной страницы храните извлечённое тело и его метаданные в структурированной записи:
Заполняйте crawled_at во время выполнения; приведённая выше дата является примером схемы. Используйте стабильный хеш нормализованного Markdown для различения реального изменения контента от повторного ползунка.
Шаг 4: Разбивка и встраивание технической документации
Разбивайте по заголовкам в первую очередь. Держите метод API, конечную точку, таблицу параметров, схему ответа и соответствующий пример кода вместе, когда они описывают одну операцию. Если раздел превышает лимит ввода встраивания, разделите его на границе параграфа или примера кода и скопируйте путь к заголовку в метаданные каждого фрагмента.
Используйте одну модель встраивания для генерации коллекции и запишите её название. Храните source_url, title, version, language, section_path и crawled_at с каждой записью. Вектор сам по себе не является заменой текста или его метаданных цитирования. См. руководство по встраиванию OpenAI для контракта запроса встраивания.
Шаг 5: Храните и извлекайте с фильтром по версии
Этот пример использует Chroma для локального пилотного проекта; его клиент Python и справочные коллекции описывает локальные и постоянные рабочие процессы коллекции. Для развертывания в производстве требуется явный план резервного копирования и разрешений. Для управляемой альтернативы рассмотрите документацию по обновлению записей Pinecone. Обновите фрагменты с стабильными идентификаторами, затем фильтруйте запросы по продукту и выбранной версии.
import chromadb
client = chromadb.PersistentClient(path="./docs-index")collection = client.get_or_create_collection("company_docs")collection.upsert( ids=["auth-v2-001"], documents=["Send the API token in the x-api-key header."], embeddings=[embedding],# сгенерировано выбранной вами моделью встраивания metadatas=[{"source_url":"https://docs.example.com/v2/authentication","title":"Authentication","product":"Example API","version":"v2","language":"en","section_path":"API Reference / Authentication",}],)
Во время запроса извлекайте только разрешённые продукт/версию и передавайте исходную ссылку в текст ответа. Тестируйте прямые вопросы API, вопросы, специфичные для версии, и вопросы, на которые невозможно ответить. Когда предоставленного доказательства недостаточно, помощник должен отказаться от предположений.
Шаг 6: Создайте помощника по вопросам и ответам по документации
Поток приложения: классифицируйте запрос, примените фильтры, разрешённые пользователем, извлеките отрывки, постройте контекст с URL-адресами и версиями, попросите модель дать обоснованный ответ, а затем проверьте возвращённые цитаты. Ответ должен содержать краткий ответ, ссылки на исходные разделы и метку версии. Зафиксируйте извлечённые идентификаторы и версию подсказки, чтобы можно было отследить неправильный ответ.
Используйте вопросы по аутентификации API, вопросы по установке SDK и вопросы по кодам ошибок в тестовом наборе. Для каждого теста рецензент должен подтвердить, что цитируемая страница содержит требование. Совпадающий URL-адрес недостаточен, если он указывает на старую версию.
Обработка отсутствующих, конфликтующих и устаревших документов
Если никакая страница не охватывает вопрос, скажите, что индексированные документы не подтверждают ответ. Если версии не согласуются, извлеките версию, выбранную пользователем, или задайте уточняющий вопрос. Если страница была заменена, отметьте её как устаревшую и исключите из текущей коллекции документов по умолчанию, сохранив её для явных исторических запросов.
Шаг 7: Поддерживайте индекс документов в актуальном состоянии
Запустите обнаружение по расписанию или инициируйте его из системы сборки документации, затем сравните нормализованные хэши контента. Повторно вставьте измененные страницы и удалите устаревшие идентификаторы частиц только после проверки новой версии. Рассматривайте переходные ошибки как сбои, а не удаление. Сохраняйте последнюю известную хорошую версию, пока обрабатывается новый обход.
Безопасность и контроль доступа
Публичная и внутренняя документация нуждаются в разных контрольных механизмах доступа. Не предполагайте, что API-ключ краулера обеспечивает разрешения на доступ к документам для конечного пользователя. Для частных страниц подтвердите, что владелец источника разрешает сбор данных, защитите учетные данные, разбейте индексы или применяйте фильтры уровня документа, и фиксируйте решения по доступу. Никогда не индексируйте секреты или данные клиентов в общую коллекцию по умолчанию. Проконсультируйтесь с командой безопасности вашей организации перед использованием конфиденциальных материалов.
Материалы NIST по контролю доступа являются полезной отправной точкой для проектирования рамок политики; смотрите их Руководство по системам контроля доступа. Применимые меры зависят от вашей развертки и классификации данных.
Затраты, обслуживание и общие проблемы
Запланируйте бюджет на запросы обхода, использование прокси, если это применимо, токены вставки, хранилище векторов, запросы моделей и техническое обслуживание. Частота повторного обхода и изменения документа часто имеют большее значение, чем первый импорт. Не приводите общую сумму за страницу, не измерив, сколько частиц производит каждая страница и как часто она изменяется; проверьте текущие ценовые предложения на обход перед прогнозированием.
Типичные проблемы включают смешанные версии API, повторяющиеся навигационные части, сломанные ограждения кода, устаревшие записи, оставшиеся после обновления, ссылки, указывающие на общую домашнюю страницу документации, и контент, доступ к которому пользователи не могут получить. Сначала исправьте контракт данных: стабильные идентификаторы, канонические URL, метаданные версий, белый список и задачу актуальности.
Контрольный список запуска
Определите границы публичных и частных источников.
Составьте актуальный инвентарный список URL и явную политику версий.
Сохраняйте код, таблицы, предупреждения, URL и метаданные версий.
Проверяйте ответы на основе реальных вопросов поддержки и разработчиков.
Применяйте разрешения пользователей перед возвратом извлеченного контекста.
Мониторьте обнаружение изменений, устаревшие части, неудачные URL и корректность цитирования.
База знаний компании с сайта документации успешно работает, когда она сохраняет контекст источника. Начните с небольшого публичного корпуса, явно смоделируйте метаданные продукта и версии, и требуйте от помощника ссылаться на страницу, которую он использовал. Добавьте частный или многоарендный контент только после того, как фильтры извлечения и контроль доступа были протестированы независимо.
Выберите и проползите разрешенные страницы, сохраните метаданные источника, очистите и разделите контент, вставьте его, храните в индексируемом хранилище и проверяйте ответы с помощью ссылок.
Q: Может ли база знаний с AI использовать сайт документации?
Да, если к документации можно законно получить доступ, и ее версия, язык и URL-адрес источника остаются прикрепленными к индексируемым фрагментам.
Q: Как мне создать AI-помощника для документов компании?
Соедините извлекатель с курируемым индексом документации, применяйте разрешения пользователей и фильтры версий, и инструктируйте модель отвечать на основе извлеченных фрагментов с ссылками.
Q: Как мне обрабатывать версии API в RAG?
Храните версию API в качестве метаданных, держите версии различными и фильтруйте извлечение по версии, относящейся к вопросу пользователя.
Q: Могу ли я обойти внутреннюю документацию, находясь за логином?
Только с явным разрешением источника и дизайном, который обеспечивает те же границы доступа для каждого пользователя результирующего индекса.
Понимание семи измерений качества данных RAG и того, как проверять проиндексированные страницы, сравнивать чистые и сырые данные, сохранять происхождение и диагностировать ошибки извлечения. Это разделяет ошибки извлечения, получения и генерации, чтобы команды могли отлаживать правильный этап.
Lena Zhou
Oct. 20th 2026
Сканируйте целые сайты одним API-запросом
Успешность 99,8% с рендерингом JavaScript
Получайте чистые данные для LLM в разных форматах
Преобразуйте любой сайт в Markdown, HTML, JSON, ссылки, PDF и другие форматы без управления инфраструктурой сканирования.
