Documentación sobre rastreo de sitios para LLM Context (Mejores Prácticas)
TL;DR
La recopilación de documentación necesita preservar el código, tablas de parámetros, contexto de encabezados, idioma y versión; un conteo de páginas por sí solo no mide la calidad.
Utiliza el mapa del sitio y el descubrimiento de navegación juntos, filtra rutas irrelevantes y compara la salida de páginas estáticas y renderizadas con JavaScript antes de escalar.
Valida Markdown por encabezados faltantes, bloques de código rotos, tablas incompletas, rutas duplicadas, contenido vacío y deriva de versiones.
Rastrear solo contenido permitido. Una API de rastreo pública no otorga acceso a documentación privada ni elude las políticas de un sitio.
Introducción: La documentación es un dato estructurado, incluso cuando se publica como HTML
Nstdata Crawl es la capa de colección en este flujo de trabajo; su visión general del producto describe la recuperación de páginas y sitios para tuberías de datos posteriores.
Un sitio de documentación está construido para lectores que navegan por páginas, versiones y ejemplos de código. Un LLM necesita las mismas relaciones para sobrevivir a la extracción. Si un rastreador devuelve un parámetro de API sin su punto final, código sin su etiqueta de idioma, o una página antigua v1 junto a una página actual v2 sin metadatos de versión, el contexto resultante puede ser engañoso incluso si cada URL se devolvió con éxito.
Esta guía cubre el descubrimiento de documentación, rastreo, validación de Markdown y metadatos. No intenta enseñar un sistema completo de búsqueda vectorial. Para la etapa de integración posterior, consulte la guía de sitio a Pinecone por separado. Nstdata Crawl admite Markdown, HTML, datos en bruto, enlaces, PDF y salida de capturas de pantalla; la actual documentación de Crawl describe los compromisos y las interfaces de tareas.
¿Qué hace que la documentación esté lista para LLM?
Un registro de documentación útil incluye contenido completo, jerarquía de encabezados significativa, código y tablas intactas, URL de origen estable, versión, idioma, marca de tiempo de rastreo y un hash de contenido. “La conversión de Markdown tuvo éxito” no es lo mismo que “el LLM puede responder a la pregunta pretendida.” Valida la información específica que tu caso de uso posterior necesita.
Descubre Nstproxy Crawl - Empieza Tu Prueba Gratuita Hoy
Para páginas de referencia de API, mantén el método, punto final, detalles de autenticación, nombres de parámetros, tipos, valores predeterminados, campos de respuesta y comportamiento de errores en el mismo contexto local. Para guías, preserva la secuencia de pasos y advertencias. Para changelogs, preserva las fechas de lanzamiento y etiquetas de estado.
Cómo se diferencia el rastreo de documentación de la recopilación general de la web
Los docs a menudo utilizan frameworks como Docusaurus, Nextra, VitePress o MkDocs, pero sus modos de renderizado difieren según el despliegue. No asumas que siempre se requiere un navegador JavaScript. Inspecciona la salida de la página que necesitas: si falta texto clave en el resultado recuperado, entonces prueba el renderizado del navegador o una espera documentada. La documentación pública para Docusaurus, VitePress, y MkDocs describe sus sistemas de publicación; el comportamiento del sitio desplegado aún necesita ser verificado directamente.
Paso 1: Descubrir URLs de documentación
Utiliza el mapa del sitio como una fuente y los enlaces del sitio como otra. Un mapa del sitio puede incluir páginas que la navegación de documentos ya no expone, mientras que el descubrimiento de enlaces puede perder páginas huérfanas que solo están listadas en un mapa del sitio. Compara los conjuntos de URL resultantes y clasifica cada ruta antes de rastrear.
Descubrimiento de sitemap versus rastreo de enlaces
Método
Útil para
Punto ciego a verificar
Sitemap
inventario de páginas declaradas y pistas de lastmod
entradas obsoletas u omitidas
Descubrimiento de enlaces
páginas alcanzables desde la navegación de documentos
páginas huérfanas o enlaces profundos
Lista de URL curada
un conjunto de piloto o liberación controlada
carga de mantenimiento manual
El protocolo de sitemaps define el formato XML, pero un campo lastmod es metadatos proporcionados por el editor, no una garantía independiente de cambio de contenido. Úsalo para priorizar verificaciones, luego compara el contenido de la página.
Excluir URLs irrelevantes y duplicadas
Normaliza nombres de host, elimina fragmentos y decide qué parámetros de consulta afectan la identidad de la página. Excluye resultados de búsqueda, páginas de inicio de sesión, variantes de seguimiento, rutas de impresión, rutas locales duplicadas, activos y páginas de marketing no relacionadas. Mantén tanto documentos versionados como páginas localizadas solo cuando estén dentro del alcance. Registra por qué se excluyó una página para que una brecha de cobertura sea explicable.
Paso 2: Rastrear páginas de docs en Markdown
Ejecuta primero un pequeño piloto. Para una página conocida, el raspado de una sola página evita variables de descubrimiento del sitio. Para una sección de docs, un rastreo del sitio acotado puede descubrir enlaces con una profundidad y límite de páginas. El ejemplo actual del SDK de Python usa NstDataClient, CrawlRequestDto, y 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)
Este código envía el trabajo; no muestra la colección de páginas completadas. Consulta el estado, recupera la lista de páginas, sigue su cursor y lee los artefactos de Markdown referenciados como se documenta. La guía de rastreo actual enumera GET /api/v1/crawl/status/{crawlId} y /pages/{crawlId}; los webhooks no son compatibles actualmente, así que haz que la consulta sea parte del diseño de reintentos y tiempos de espera de tu trabajador.
Documentación renderizada por JavaScript
Verifica si una frase conocida, un bloque de código, o un título de página están presentes en el Markdown devuelto. Compara con la página renderizada en un navegador. Si el contenido está ausente, prueba la renderización de JavaScript y una espera de selector cuando sea compatible. Evita habilitar la renderización globalmente sin razón: puede agregar tiempo y dificulta saber si un fallo provino del descubrimiento, la renderización o la extracción.
Paso 3: Preservar encabezados, bloques de código y tablas
Markdown debe preservar H1/H2/H3, bloques de código con etiquetas de lenguaje, tablas, listas, advertencias y enlaces internos. Una muestra de validación útil podría contener:
## Crear un tokenEnvía el token en el encabezado `x-api-key`.
| Campo | Tipo | Requerido ||---|---|---||`project_id`| cadena | sí |```python
client = Client(token=token)
Este es un fixture sintético para comprobar el formato, no una salida capturada de una página activa. Después de un rastreo, verifica que los bloques de código de apertura y cierre coincidan y que los encabezados de la tabla y las cuentas de celdas se mantengan consistentes.
Preservar el contexto de los puntos finales y parámetros
Un método de API es difícil de usar si su tabla de parámetros se separa del punto final. Almacena los encabezados de padre más cercanos con cada fragmento. Preserva advertencias como "obsoleto" o "requerido para esta versión"; a menudo cambian si un ejemplo es seguro para copiar.
Manejar muestras de código en múltiples lenguajes
Mantén la etiqueta de lenguaje de código, SDK/version, nombre de punto final o función, y el texto explicativo que lo rodea. No concatenes ejemplos de Python y Node.js en un solo fragmento indiferenciado. Si un bloque de código es extremadamente largo, divídelo en límites de ejemplo o función lógicos y repite el recorrido de encabezados relevantes.
Paso 4: Manejar versiones de documentación y localización
Trata /v1/, /v2/, “latest,” y rutas archivadas como estados explícitos. Almacena version, status, language, y canonical_url por separado del texto del cuerpo. latest es un puntero en movimiento; captura la versión resuelta si el sitio la identifica. Mantén traducciones separadas y evita fusionar ejemplos entre locales sin revisión.
Paso 5: Normalizar metadatos
Para cada página, retén:
{"source_url":"https://docs.example.com/v2/reference/users","canonical_url":"https://docs.example.com/v2/reference/users","title":"API de Usuarios","section_path":"Referencia de API / Usuarios","version":"v2","language":"es","crawled_at":"marca de tiempo de ejecución","content_hash":"hash del cuerpo normalizado"}
Normaliza la identidad de URL de manera consistente y haz un hash del cuerpo normalizado en lugar del HTML completo, para que un cambio de diseño no fuerce una re-embebida innecesaria. Nunca fabriques fechas de actualización de origen cuando una página no las publique.
Paso 6: Validar la calidad del rastreo
Crea controles automáticos para cuerpo vacío, texto inesperadamente corto, repetición de texto estándar, título faltante, bloques de código no cerrados, tablas mal formadas, URL canónicas rotas, contenido normalizado duplicado y metadatos de versión ausentes. Luego, muestrea manualmente páginas por tipo: resumen, referencia de API, tutorial cargado de código, y una página dinámica si la documentación utiliza una.
Una verificación de completitud de contenido debe estar ligada a la tarea: para una página de API, compara los nombres de puntos finales esperados y campos importantes; para un tutorial, verifica que los encabezados y bloques de código estén presentes. Un estado HTTP verde no prueba que el contenido extraído esté completo.
Paso 7: Almacenar documentación para uso de LLM
Guarda artefactos de rastreo como archivos Markdown o JSONL durante el piloto para que un revisor pueda inspeccionarlos. Una base de datos se vuelve útil cuando necesitas actualizaciones incrementales, estado a nivel de página, permisos o acceso a consultas. Un registro JSONL debe mantener el texto de la página y los metadatos juntos, con registros de fragmentos que hacen referencia a la ID de la página. Consulta la implementación Crawl-to-Pinecone para la siguiente etapa de ingestión.
Sitios grandes, monitoreo y acceso responsable
Límite la primera recopilación con profundidad, límites de página y filtros de URL. Monitorea el estado de la tarea y los fallos por página; continúa desde un punto de control en lugar de reiniciar cada página después de un error. Utiliza tasas razonables y respeta los términos del sitio, la guía de robots y los permisos de acceso. No intentes eludir inicios de sesión o controles para contenido que no estás autorizado a recopilar.
Medir:
Cobertura de URL: documentos válidos descubiertos / documentos esperados en el ámbito.
Completitud del contenido: páginas muestreadas con secciones requeridas / páginas muestreadas.
Preservación del código: bloques de código relevantes intactos / bloques relevantes muestreados.
Tasa de duplicados: documentos duplicados normalizados / documentos aceptados.
Completitud de los metadatos: registros con campos de fuente/versiones requeridos / registros aceptados.
Estas métricas son más útiles que contar solicitudes exitosas solamente. Mantén un manifiesto de muestra y vuélvelo a ejecutar después de cambios en el rastreador, el sitio de documentos o la extracción.
Errores comunes y lista de verificación final
Los errores comunes incluyen rastrear solo la página de inicio, excluir la relación entre versiones antiguas y actuales, indexar páginas de búsqueda, perder etiquetas de código, mezclar idiomas, aceptar páginas renderizadas por el cliente vacías y tratar las solicitudes fallidas como contenido eliminado.
Antes de enviar la documentación a un LLM, verifica el descubrimiento de URL, el alcance de acceso, el éxito a nivel de página, la estructura del contenido, los metadatos de versión e idioma, el manejo de duplicados y el comportamiento de actualización. Mantén la URL de origen original adjunta a través de la segmentación para que cada respuesta pueda citarla.
Rastrear documentación para el contexto de LLM es una tarea de calidad de datos estructurados. Descubre páginas a partir de múltiples señales, limita el rastreo, preserva las relaciones técnicas dentro de cada página y verifica el resultado contra preguntas representativas de API. Una vez que el Markdown pase estas verificaciones, puede ser utilizado para segmentación, búsqueda, RAG o una herramienta de agente.
Comienza con un mapa del sitio y un inventario de navegación, filtra los caminos de documentos permitidos, envía un rastreo limitado, recupera cada resultado y valida el Markdown antes de almacenarlo.
P: ¿Cuál es el mejor formato para la documentación de LLM?
Markdown es un formato de texto práctico cuando preserva encabezados, código, tablas, enlaces y metadatos de origen; HTML puede ser mejor cuando se requiere un análisis personalizado.
P: ¿Cómo convierto documentos a Markdown?
Usa una herramienta de extracción de páginas que devuelva Markdown, luego verifica el resultado en busca de secciones faltantes, tablas mal formadas e integridad de bloques de código.
P: ¿Los documentos de Docusaurus requieren renderizado de JavaScript?
No necesariamente; primero inspecciona la salida de la página de destino y habilita el renderizado solo cuando el contenido requerido esté ausente del resultado no renderizado.
P: ¿Cómo preservo bloques de código para RAG?
Mantén bloques cercados con sus etiquetas de lenguaje y contexto de encabezado cercano, y divide ejemplos largos solo en límites lógicos.
Documentación sobre rastreo de sitios para LLM Context (Mejores Prácticas)
Mejores prácticas para descubrir y rastrear URL de documentación, preservar código y tablas, gestionar versiones y validar Markdown listo para LLM. Incluye una lista de verificación de validación práctica para la salida de Markdown y la cobertura de páginas.
Ivy Lin
Oct. 20th 2026
Rastrea sitios web completos con una sola solicitud API
99,8% de éxito con renderizado JavaScript
Obtén datos limpios, listos para LLM, en múltiples formatos
Convierte cualquier sitio web en Markdown, HTML, JSON, enlaces, PDF y más, sin gestionar infraestructura de rastreo.
