Bases de datos inteligentes de documentación para tu asistente de código con IA
Cómo crear bases de datos inteligentes para tu asistente de código con IA
Alimentar a un agente de IA con documentación sin filtrar es como pedirle que busque algo concreto en medio de un montón de información irrelevante. En NameOcean llevamos tiempo explorando cómo preparar la documentación técnica para que funcione bien con flujos de desarrollo impulsados por IA. Aquí te comparto un enfoque práctico y efectivo.
El problema: no todas las páginas aportan lo mismo
Muchos sitios de documentación incluyen páginas que existen solo por estructura o por requisitos legales. Índices, políticas de privacidad, listas de cambios o páginas de referencia son útiles para que las personas naveguen, pero no enseñan nada útil a un modelo de IA.
Si introduces toda esa información en una base de datos vectorial sin discriminar, obligas al sistema a procesar contenido que no aporta valor. El resultado es más lento, más costoso y menos preciso.
Una estrategia de dos fases para clasificar
La forma más eficiente combina reglas automáticas con una clasificación selectiva mediante LLM.
Primera fase: filtrado rápido
Empieza aplicando patrones sobre las URLs y la estructura básica del contenido. Puedes descartar de inmediato:
- Páginas legales que contengan términos como
/legal/,/privacyo/terms - Índices con menos de 200 palabras que solo contengan enlaces
- Listas de cambios y páginas de referencia con patrones predecibles
Esta fase se ejecuta en local, no tiene coste y suele eliminar entre el 40% y el 60% de las páginas.
Segunda fase: clasificación con LLM
Para el resto, envías a un modelo local solo lo esencial: la URL, el título, las primeras 200 palabras y la jerarquía de encabezados. Le pides que clasifique según el marco Diátaxis, que distingue entre contenido conceptual, tutoriales, guías prácticas, ejemplos y páginas estructurales.
El LLM solo procesa lo que las reglas no pudieron resolver, manteniendo el proceso rápido y económico.
Generar embeddings de forma inteligente
Una vez filtrado el ruido, llega el momento de crear los embeddings. Las páginas de documentación suelen ser largas, así que no conviene truncarlas.
En su lugar, divide el contenido por encabezados y calcula el promedio de los embeddings resultantes. Esto conserva el contexto que aportan los títulos, bloques de código y listas. Puedes hacerlo con un modelo local de sentence transformers, sin depender de APIs externas.
Construir un grafo de conocimiento híbrido
El verdadero valor aparece cuando combinas dos tipos de relaciones:
- Enlaces explícitos: los hipervínculos que ya existen en la documentación y reflejan su estructura intencionada.
- Conexiones semánticas: relaciones que surgen al comparar embeddings. Si dos páginas superan un umbral de similitud (por ejemplo 0.75), se consideran relacionadas aunque no estén enlazadas.
Almacena ambas como aristas dirigidas en un grafo. Limita el número de vecinos por página (20 es un buen punto de partida) y excluye las páginas de navegación, legales y de referencia del cálculo semántico.
El resultado final: una base de datos SQLite portátil
Todo queda recogido en un único archivo SQLite que contiene:
- El contenido limpio en markdown
- Las clasificaciones de cada página
- Los embeddings
- Las aristas del grafo con sus pesos
- Metadatos y URLs
Esto permite que un agente de IA consulte la información mediante SQL, filtre por tipo de contenido o navegue entre páginas relacionadas. Además, el archivo es completamente portátil y funciona sin conexión.
Flujo de trabajo recomendado
El proceso completo consta de seis pasos:
- Rastrear el sitio respetando las normas de robots.txt
- Convertir el HTML extraído en markdown limpio
- Clasificar las páginas con reglas y, cuando sea necesario, con LLM
- Generar embeddings locales dividiendo por encabezados
- Construir el grafo combinando enlaces explícitos y semánticos
- Guardar todo en SQLite
Por qué importa para los desarrolladores
Tanto si estás creando un asistente de código interno como integrando IA en tu entorno de desarrollo, la calidad de la documentación marca la diferencia. Al estructurarla bien desde el principio, tu agente de IA trabaja con información relevante en lugar de ruido. Las consultas son más rápidas, las respuestas más precisas y mantienes el control total sobre tus datos sin depender de servicios de terceros.