Ir al contenido principal

codebase_search

Función Experimental

La herramienta codebase_search requiere configuración adicional que incluye un proveedor de embeddings y una base de datos vectorial.

La herramienta codebase_search realiza búsquedas semánticas en toda su base de código usando embeddings de IA. A diferencia de la búsqueda tradicional basada en texto, comprende el significado de sus consultas y encuentra código relevante incluso cuando las palabras clave exactas no coinciden.

Parámetros​

La herramienta acepta estos parámetros:

  • query (requerido): Consulta de búsqueda en lenguaje natural que describe lo que está buscando
  • path (opcional): Ruta de directorio para limitar el alcance de la búsqueda a una parte específica de su base de código

Qué Hace​

Esta herramienta busca en su base de código indexada usando similitud semántica en lugar de coincidencia exacta de texto. Encuentra bloques de código que están conceptualmente relacionados con su consulta, incluso si no contienen las palabras exactas que buscó. Los resultados incluyen fragmentos de código relevantes con rutas de archivo, números de línea y puntuaciones de similitud.

¿Cuándo se usa?​

  • Cuando AI Cockpit Reasoning necesita encontrar código relacionado con funcionalidades específicas en su proyecto
  • Cuando busca patrones de implementación o estructuras de código similares
  • Cuando busca manejo de errores, autenticación u otros patrones de código conceptuales
  • Cuando explora bases de código desconocidas para entender cómo se implementan las funciones
  • Cuando encuentra código relacionado que podría verse afectado por cambios o refactorizaciones

Características Principales​

  • Comprensión Semántica: Encuentra código por significado en lugar de coincidencias exactas de palabras clave
  • Búsqueda en Todo el Proyecto: Busca en toda su base de código indexada, no solo en los archivos abiertos
  • Resultados Contextuales: Devuelve fragmentos de código con rutas de archivo y números de línea para fácil navegación
  • Puntuación de Similitud: Resultados clasificados por relevancia con puntuaciones de similitud (escala 0-1)
  • Filtrado por Alcance: Parámetro de ruta opcional para limitar las búsquedas a directorios específicos
  • Clasificación Inteligente: Resultados ordenados por relevancia semántica para su consulta
  • Integración con la Interfaz: Resultados mostrados con resaltado de sintaxis y enlaces de navegación
  • Rendimiento Optimizado: Búsqueda rápida basada en vectores con límites de resultados configurables

Requisitos​

Esta herramienta solo está disponible cuando la función experimental de Indexación de Codebase está correctamente configurada:

  • Función Habilitada: La Indexación de Codebase debe estar habilitada en la configuración experimental
  • Proveedor de Embeddings: Se requiere clave de API de OpenAI o configuración de Ollama
  • Base de Datos Vectorial: Instancia de Qdrant en ejecución y accesible
  • Estado del Índice: La base de código debe estar indexada (estado: "Indexado" o "Indexando")

Limitaciones​

  • Función Experimental: Parte del sistema experimental de indexación de codebase
  • Requiere Configuración: Depende de servicios externos (proveedor de embeddings + Qdrant)
  • Dependencia del Índice: Solo busca en bloques de código indexados
  • Límites de Resultados: Máximo de 50 resultados por búsqueda para mantener el rendimiento
  • Umbral de Similitud: Solo devuelve resultados con puntuación de similitud superior a 0.4
  • Límites de Tamaño de Archivo: Limitado a archivos de menos de 1MB que fueron indexados correctamente
  • Soporte de Lenguajes: La efectividad depende del soporte de lenguajes de Tree-sitter

Cómo Funciona​

Cuando se invoca la herramienta codebase_search, sigue este proceso:

  1. Validación de Disponibilidad:

    • Verifica que el CodeIndexManager esté disponible e inicializado
    • Confirma que la indexación de codebase está habilitada en la configuración
    • Verifica que la indexación esté correctamente configurada (claves de API, URL de Qdrant)
    • Valida que el estado actual del índice permita la búsqueda

  2. Procesamiento de la Consulta:

    • Toma su consulta en lenguaje natural y genera un vector de embedding
    • Usa el mismo proveedor de embeddings configurado para la indexación (OpenAI u Ollama)
    • Convierte el significado semántico de su consulta en una representación matemática

  3. Ejecución de la Búsqueda Vectorial:

    • Busca en la base de datos vectorial de Qdrant embeddings de código similares
    • Usa similitud de coseno para encontrar los bloques de código más relevantes
    • Aplica el umbral mínimo de similitud (0.4) para filtrar resultados
    • Limita los resultados a 50 coincidencias para un rendimiento óptimo

  4. Filtrado por Ruta (si se especifica):

    • Filtra los resultados para incluir solo archivos dentro de la ruta de directorio especificada
    • Usa comparación de rutas normalizadas para un filtrado preciso
    • Mantiene la clasificación de relevancia dentro del alcance filtrado

  5. Procesamiento y Formato de Resultados:

    • Convierte las rutas de archivo absolutas a rutas relativas al espacio de trabajo
    • Estructura los resultados con rutas de archivo, rangos de líneas, puntuaciones de similitud y contenido del código
    • Formatea tanto para el consumo de la IA como para la visualización en la interfaz con resaltado de sintaxis

  6. Formato de Salida Dual:

    • Salida para IA: Formato de texto estructurado con consulta, rutas de archivo, puntuaciones y fragmentos de código
    • Salida para Interfaz: Formato JSON con resaltado de sintaxis y capacidades de navegación

Mejores Prácticas para Consultas de Búsqueda​

Patrones de Consulta Efectivos​

Bueno: Conceptual y específico

<codebase_search>
<query>autenticación de usuario y validación de contraseña</query>
</codebase_search>

Bueno: Enfocado en funciones

<codebase_search>
<query>configuración del pool de conexiones a la base de datos</query>
</codebase_search>

Bueno: Orientado a problemas

<codebase_search>
<query>manejo de errores para solicitudes de API</query>
</codebase_search>

Menos efectivo: Demasiado genérico

<codebase_search>
<query>función</query>
</codebase_search>

Tipos de Consultas que Funcionan Bien​

  • Descripciones Funcionales: "procesamiento de carga de archivos", "lógica de validación de email"
  • Patrones Técnicos: "implementación del patrón singleton", "uso del método factory"
  • Conceptos de Dominio: "gestión de perfil de usuario", "flujo de procesamiento de pagos"
  • Componentes de Arquitectura: "configuración de middleware", "scripts de migración de base de datos"

Alcance por Directorio​

Use el parámetro opcional path para enfocar las búsquedas en partes específicas de su base de código:

Buscar dentro de módulos de API:

<codebase_search>
<query>middleware de validación de endpoint</query>
<path>src/api</path>
</codebase_search>

Buscar en archivos de prueba:

<codebase_search>
<query>patrones de configuración de datos de prueba</query>
<path>tests</path>
</codebase_search>

Buscar en directorios de funciones específicas:

<codebase_search>
<query>gestión del estado del componente</query>
<path>src/components/auth</path>
</codebase_search>

Interpretación de Resultados​

Puntuaciones de Similitud​

  • 0.8-1.0: Coincidencias muy relevantes, probablemente exactamente lo que está buscando
  • 0.6-0.8: Buenas coincidencias con fuerte similitud conceptual
  • 0.4-0.6: Potencialmente relevante pero puede requerir revisión
  • Por debajo de 0.4: Filtrado por ser demasiado diferente

Estructura de Resultados​

Cada resultado de búsqueda incluye:

  • Ruta del Archivo: Ruta relativa al espacio de trabajo del archivo que contiene la coincidencia
  • Puntuación: Puntuación de similitud que indica relevancia (0.4-1.0)
  • Rango de Líneas: Números de línea de inicio y fin para el bloque de código
  • Fragmento de Código: El contenido real del código que coincidió con su consulta

Ejemplos de Uso​

  • Al implementar una nueva función, AI Cockpit Reasoning busca "middleware de autenticación" para entender los patrones existentes antes de escribir nuevo código.
  • Al depurar un problema, AI Cockpit Reasoning busca "manejo de errores en llamadas de API" para encontrar patrones de error relacionados en toda la base de código.
  • Al refactorizar código, AI Cockpit Reasoning busca "patrones de transacciones de base de datos" para garantizar consistencia en todas las operaciones de base de datos.
  • Al incorporarse a una nueva base de código, AI Cockpit Reasoning busca "carga de configuración" para entender cómo arranca la aplicación.

Ejemplos de Uso​

Buscar código relacionado con autenticación en todo el proyecto:

<codebase_search>
<query>lógica de inicio de sesión y autenticación de usuario</query>
</codebase_search>

Encontrar código relacionado con la base de datos en un directorio específico:

<codebase_search>
<query>conexión a la base de datos y ejecución de consultas</query>
<path>src/data</path>
</codebase_search>

Buscar patrones de manejo de errores en código de API:

<codebase_search>
<query>respuestas de error HTTP y manejo de excepciones</query>
<path>src/api</path>
</codebase_search>

Buscar utilidades de prueba y configuraciones de mock:

<codebase_search>
<query>configuración de pruebas y creación de datos de prueba</query>
<path>tests</path>
</codebase_search>

Encontrar código de configuración y configuración del entorno:

<codebase_search>
<query>variables de entorno y configuración de la aplicación</query>
</codebase_search>