Sitio web a Base de Datos Vectorial: Rastrea, Trocea, Incrusta en un Solo Flujo
TL;DR
Un pipeline de sitio web a base de datos vectorial almacena fragmentos buscables y metadatos de procedencia; no coloca un sitio web completo en un solo vector.
Rastrea un conjunto limitado de páginas, valida el Markdown, lo divide en fragmentos estables, incrusta cada fragmento y luego lo inserta en un espacio de nombres de Pinecone.
La dimensión de salida del modelo de incrustación debe coincidir con el índice denso de Pinecone, y la ingestión repetida debe reutilizar identificadores deterministas en lugar de crear duplicados.
Este es un compañero orientado a la construcción de la visión general existente de Rastrear a Pinecone de Nstdata; el enfoque aquí es el contrato de datos y la ruta de actualización segura.
Introducción: Lo que construirás
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 descendentes.
Este tutorial convierte un sitio de documentación pública en registros buscables en Pinecone. El flujo es URL → Rastreo → Markdown → fragmentos → incrustaciones → Pinecone → consulta. Se detiene en la recuperación; una interfaz de chat, permisos de usuario y monitoreo en producción son capas de aplicación separadas.
Una base de datos vectorial no almacena normalmente un sitio web como un documento gigante. Cada registro es un vector para un pasaje, más un ID y metadatos que te permiten encontrar la fuente y actualizarla más tarde. Nstdata Crawl proporciona la colección de páginas y la etapa de conversión de Markdown; Pinecone almacena y recupera vectores. Para los puntos finales de rastreo actuales y las respuestas de tareas, utiliza la referencia de API de Nstdata Crawl.
Cómo se convierte el contenido del sitio web en datos vectoriales
Descubre Nstproxy Crawl - Empieza Tu Prueba Gratuita Hoy
Paso
Valor de ejemplo
Por qué se almacena
Página
https://docs.example.com/auth
Identidad de origen y cita
Markdown
Título, explicación, ejemplo de código
Contenido fuente legible
Fragmento
Una sección coherente
Unidad de recuperación
Incrustación
Vector numérico
Búsqueda de similitud semántica
Metadatos
URL, título, sección, versión, hash
Filtrado, citas, actualizaciones
Registro de Pinecone
ID estable + valores + metadatos
Objetivo de inserción y consulta
Mantén el texto de la página original en metadatos solo cuando se ajuste a tu modelo de datos y requisitos de privacidad. En este ejemplo, el texto de fragmento se adjunta a los metadatos de cada vector para que la recuperación pueda devolver un pasaje listo para cita. Para diseños de registros más grandes, evalúa la actual guía de modelado de datos y actualización de Pinecone.
Requisitos previos: API de Rastrear, incrustaciones y Pinecone
Crea un token de Nstdata Crawl, una clave API de OpenAI, y un proyecto de Pinecone. Crea un índice denso de Pinecone cuya dimensión coincida con la salida del modelo de incrustación. El ejemplo a continuación utiliza la salida predeterminada de 1,536 dimensiones de text-embedding-3-small; si estableces una dimensión de incrustación personalizada, configura el índice al mismo valor. Instala las bibliotecas y fija las versiones exactas resueltas en tu archivo de bloqueo de implementación:
Los nombres de SDK y formas de API a continuación siguen la documentación actual del proveedor. No hay credenciales de API disponibles en el entorno de escritura, por lo que el flujo de trabajo en la nube completo no se ha ejecutado de extremo a extremo.
Paso 1: Rastrear un sitio en Markdown
Para una URL conocida, utiliza el cliente de Python síncrono documentado. Para un sitio de documentación, envía un rastreo de sitio limitado con un bajo maxPages durante la primera ejecución de validación. La API a nivel de sitio devuelve un ID de tarea; consulta el estado y luego los resultados de las páginas. La referencia de Rastrear documenta POST /api/v1/crawl, GET /api/v1/crawl/status/{crawlId}, y GET /api/v1/crawl/pages/{crawlId}.
import os
from nstdata_ai_crawl import CrawlRequestDto, Format, NstDataClient
with NstDataClient(os.environ["NSTDATA_API_TOKEN"])as client: submitted = client.submit_crawl_task(CrawlRequestDto( url="https://docs.example.com/", formats=[Format.MARKDOWN], maxDepth=2, maxPages=100, includeUrls=["*docs.example.com/*"], excludeUrls=["*docs.example.com/search*","*docs.example.com/login*"], ignoreQuery=True, onlyMainContent=True, timeout=60_000,)) crawl_id = submitted.idprint("rastreo enviado", crawl_id)
El ejemplo del SDK confirma el método de envío y los campos de solicitud. Para producción, agrega sondeo con un plazo monótono, retroceso exponencial y una espera máxima; luego pagina la lista de páginas devueltas hasta que su nextCursor esté vacío. Un registro de página puede llevar una referencia de contenido en lugar del Markdown completo, así que recupera el artefacto referenciado a través del punto final de lectura de almacenamiento documentado antes de dividirlo en fragmentos. Verifica el success, el estado, los metadatos y el contenido de cada página en lugar de tratar un rastreo padre completado como prueba de que cada página es utilizable.
La respuesta de referencia de la guía de Crawl para salidas grandes utiliza campos como markdownRef y un GET /api/v1/crawl/storage/read?st={ref} autenticado. Mantenga ese paso de recuperación en el adaptador para su versión de SDK; no asuma que cada respuesta incrusta un cuerpo completo. Evite rastrear contenido solo para inicio de sesión o de otro modo no autorizado.
Paso 2: Limpiar y normalizar antes de incrustar
Preserve las rutas de los encabezados, los bloques de código, las tablas y los enlaces de origen. Solo elimine el chrome repetido que claramente no es parte del documento. Un ayudante de normalización básico es deliberadamente conservador:
No elimine cada enlace o tabla solo para reducir el conteo de tokens. La documentación de la API a menudo almacena la respuesta útil en una tabla de parámetros o en una página de versión vinculada. Capture la URL canónica final, el título, el idioma y la versión del producto como metadatos junto con el cuerpo normalizado.
Paso 3: Dividir en fragmentos conscientes de los encabezados
Una primera versión puede dividir Markdown por encabezados mientras deja juntos los bloques de código. Este ejemplo crea un registro para cada sección de encabezado; agregue un segundo paso consciente del tokenizador cuando una sección exceda el límite de entrada de su proveedor de incrustaciones.
defsplit_sections(markdown:str): heading_path, lines, fenced =[],[],Falsefor line in markdown.splitlines():if line.strip().startswith("```"): fenced =not fenced
if line.startswith("#")andnot fenced and lines: text ="\n".join(lines).strip()if text:yield" / ".join(heading_path), text
level =len(line)-len(line.lstrip("#")) heading_path = heading_path[:level -1]+[line[level:].strip()] lines =[line]else: lines.append(line) text ="\n".join(lines).strip()if text:yield" / ".join(heading_path), text
Esta es una estructura inicial, no un divisor universal. No garantiza un conteo máximo de tokens ni fusiona secciones pequeñas. La guía de divisores de texto LangChain proporciona otra implementación de marco para comparar. Agregue división recursiva para secciones grandes y pruebe el comportamiento de los límites en bloques de código y tablas. Controle el tamaño de los tokens con el tokenizador asociado a su modelo de incrustaciones en lugar de tratar el conteo de caracteres como un conteo exacto de tokens.
Para las siguientes secciones, suponga que el adaptador de resultados de página ha producido un registro validado llamado page, con campos url, title, markdown, crawled_at y content_hash. Materialice la salida del divisor una vez: sections = list(split_sections(page.markdown)). El paso anterior de rastreo de sitio envía una tarea; su adaptador debe sondearla, leer los artefactos de Markdown referenciados y construir este registro de página antes de incrustar.
Paso 4: Generar incrustaciones
La guía de incrustaciones de OpenAI documenta el punto final de incrustaciones. Incruste cada fragmento utilizando un modelo fijo y retenga el nombre del modelo con la versión del índice para que un cambio de modelo posterior no pueda mezclar silenciosamente espacios vectoriales incompatibles.
from openai import OpenAI
embedder = OpenAI()texts =[chunk_text for _, chunk_text in sections]response = embedder.embeddings.create( model="text-embedding-3-small",input=texts,)vectors =[item.embedding for item in response.data]assertlen(vectors)==len(texts)
El uso de lotes reduce la sobrecarga de solicitudes, pero dimensione los lotes utilizando los límites del proveedor y reintente errores transitorios con retrocesos. Verifique la longitud del vector antes de escribir:
expected_dimension =1536ifany(len(vector)!= expected_dimension for vector in vectors):raise ValueError("La dimensión de la incrustación no coincide con el índice de Pinecone")
Paso 5: Crear el índice de Pinecone
Cree un índice denso en la consola de Pinecone o con su API de control actual. Establezca la dimensión del índice en la dimensión de salida de incrustación y elija la métrica de similitud requerida por su diseño de recuperación. Se necesita la URL del host para operaciones en el plano de datos. Utilice primero un índice de desarrollo para que los experimentos fallidos no contaminen los datos de producción.
Paso 6: Actualizar fragmentos con ID estables
Los ejemplos de Python actuales de Pinecone aceptan registros densos con id, values y metadata opcional. Utilice un espacio de nombres para separar una colección de documentación o inquilino. Un prefijo estable hace posible eliminar todos los fragmentos para una página de origen cambiada antes de reemplazarlos.
Upsert sobrescribe un registro existente con el mismo ID. No elimina automáticamente los antiguos IDs de fragmentos que desaparecieron después de una edición de página. Mantenga la lista anterior de página a ID y elimine los IDs antiguos después de que el conjunto de reemplazo haya sido validado. Pinecone documenta el procesamiento por lotes y los espacios de nombres en su guía de upsert.
Paso 7: Consultar el índice del sitio web
Incruste la pregunta con el mismo modelo y consulte a Pinecone. Devuelva los metadatos para que la aplicación pueda mostrar un enlace de origen y un encabezado en lugar de emitir una respuesta sin formato.
question ="¿Cómo autentica la API las solicitudes?"query_vector = embedder.embeddings.create( model="text-embedding-3-small",input=question,).data[0].embedding
matches = index.query( vector=query_vector, top_k=5, include_metadata=True, namespace=namespace,)formatchin matches.matches:print(match.metadata["source_url"],match.metadata["heading_path"])print(match.metadata["text"])
Trate top_k como un parámetro de recuperación ajustable, no como una garantía de calidad. Evalúe con un pequeño conjunto de preguntas reales y verifique que cada pasaje devuelto respalde la respuesta. Para sitios controlados por acceso, aplique también permisos de inquilino y de documento antes de devolver contexto al modelo.
Paso 8: Manejar actualizaciones y eliminaciones
Almacene un hash del contenido de la página normalizado. Cuando la próxima exploración aceptada devuelva el mismo hash, omita la incrustación. Cuando el hash cambie, cree la nueva lista de fragmentos, realice un upsert, verifique que sea consultable y luego elimine los IDs anteriores. Mantenga un manifiesto fuera de Pinecone con la URL canónica, hash de contenido, marca de tiempo de exploración, versión del modelo y IDs de fragmentos. Si una exploración de origen falla, conserve el último índice conocido bueno y marque la página para revisión; un tiempo de espera no debe convertirse en una eliminación accidental.
Errores comunes y modelo de costos
Un dimension mismatch significa que el índice y la salida de incrustación no están de acuerdo. Una inundación de duplicados generalmente significa que los IDs eran aleatorios o incluían la marca de tiempo de ingestión. Citas faltantes generalmente significan que source_url se perdió durante el fragmentado. Una consulta de metadatos que no devuelve registros puede señalar a un desajuste de espacio de nombres en lugar de un problema de incrustación.
Estime el costo por página aceptada con términos separados: uso de URL de exploración, tráfico de proxy cuando está habilitado, incrustaciones para texto nuevo o cambiado, escrituras y almacenamiento de Pinecone, y llamadas al modelo en tiempo de consulta. Una página puede producir muchos fragmentos, por lo que el volumen de páginas solo no es una estimación de almacenamiento confiable. Consulte la actual tarifa de exploración de Nstdata y la documentación actual de facturación de Pinecone al preparar un presupuesto; las tarifas y los límites del plan pueden cambiar.
Pinecone versus otras tiendas de vectores para este flujo de trabajo
Pinecone es una opción gestionada cuando desea un índice de vectores alojado y no desea operar el proceso de base de datos. Chroma es conveniente para prototipos locales; Qdrant y Weaviate brindan otras implementaciones gestionadas o autohospedadas; pgvector puede ajustarse a un equipo que ya opera PostgreSQL. Compare las necesidades de filtrado, operaciones, copias de seguridad, región y modelo de permisos, no solo la latencia de búsqueda de vectores. Este tutorial usa Pinecone porque el objetivo de palabras clave apunta a esa integración, no porque una base de datos sea la mejor para cada carga de trabajo.
Un flujo confiable de base de datos de sitio web a vector depende de los contratos entre etapas: La exploración produce un artefacto de página, su código lo valida y fragmenta, el modelo de incrustación produce vectores de una dimensión conocida, y Pinecone almacena cada vector bajo un ID estable con metadatos de origen. Construya el manifiesto de URL y el comportamiento de actualización/eliminación antes de ingerir un sitio grande. Esa pequeña cantidad de organización previene pasajes obsoletos y citas rotas más tarde.
Descubra y acceda a las páginas permitidas, valide y divida su texto, genere incrustaciones y luego inserte cada vector con una ID estable y metadatos de origen.
**P: ¿Pinecone almacena la página web completa?**
Pinecone almacena registros de vectores y metadatos asociados; su aplicación decide si se almacena el texto dividido como metadatos o en un almacén de contenido separado.
**P: ¿Cuál es el mejor tamaño de fragmento para Pinecone?**
No hay un tamaño universalmente mejor; ajuste los límites de los fragmentos y la configuración de recuperación según preguntas representativas y los límites de entrada del modelo de incrustación.
**P: ¿Cómo actualizo las incrustaciones del sitio web?**
Compare un hash de contenido normalizado, vuelva a incrustar las páginas cambiadas, inserte los fragmentos de reemplazo y elimine las ID de fragmentos anteriores después de la validación.
**P: ¿Puedo almacenar múltiples sitios web en un índice?**
Sí, pero utilice espacios de nombres o filtros de metadatos de manera deliberada y haga cumplir los permisos de inquilinos en su aplicación antes de devolver el contenido recuperado.
Entender las siete dimensiones de la calidad de los datos RAG y cómo validar las páginas rastreadas, comparar entradas limpias y sin procesar, preservar la procedencia y diagnosticar fallos de recuperación. Separa errores de extracción, recuperación y generación para que los equipos puedan depurar la etapa correcta.
Lena Zhou
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.
