📋 MANUAL DE EMPLEO

BÚSQUEDA SEMÁNTICA V2

Sistema Avanzado de Búsqueda Semántica con IA para Imágenes y Documentos

📖 ÍNDICE

🚀 INTRODUCCIÓN

Búsqueda Semántica V2 es un sistema avanzado de búsqueda inteligente que combina múltiples tecnologías de IA para proporcionar una experiencia de búsqueda semántica superior en imágenes y documentos. El sistema utiliza modelos de lenguaje de última generación, bases de datos vectoriales y procesamiento de imágenes para ofrecer resultados de búsqueda altamente relevantes y contextuales.

¿Qué hace este sistema?

🔍 Búsqueda Semántica Inteligente

Comprende el contexto y significado de las consultas, no solo palabras clave

🖼️ Análisis Automático de Imágenes

Detecta objetos, personas y características en las imágenes

🔍 Búsqueda Híbrida

Combina búsqueda de texto tradicional con similitud semántica

🖥️ Interfaz Gráfica Moderna

Aplicación de escritorio intuitiva con PySide6

⚡ Procesamiento por Lotes

Manejo eficiente de grandes volúmenes de datos

💾 Bases de Datos Híbridas

MongoDB para almacenamiento + Qdrant para búsquedas vectoriales

✨ CARACTERÍSTICAS PRINCIPALES

🔍 Búsqueda Inteligente

  • Búsqueda semántica con embeddings vectoriales usando Ollama
  • Búsqueda híbrida combinando texto y similitud semántica
  • Búsqueda por similitud con cálculo de similitud coseno
  • Sugerencias automáticas basadas en contenido existente
  • Filtros avanzados por ubicación, objetos, fechas, etc.

🖼️ Procesamiento de Imágenes

  • Detección automática de objetos en imágenes usando modelos de IA
  • Extracción de metadatos (EXIF, ubicación, fecha, dimensiones)
  • Análisis de contenido con IA para generar descripciones automáticas
  • Procesamiento por lotes para grandes volúmenes de datos
  • Soporte para múltiples formatos (JPG, PNG, GIF, BMP, TIFF)

💾 Bases de Datos Híbridas

  • MongoDB para almacenamiento principal de documentos
  • Qdrant para búsquedas vectoriales optimizadas
  • Sincronización automática entre ambas bases de datos
  • Escalabilidad para millones de documentos
  • Backup y restauración integrados

🖥️ Interfaz Gráfica

  • Aplicación de escritorio moderna con PySide6
  • Interfaz intuitiva con pestañas organizadas
  • Monitoreo en tiempo real del procesamiento
  • Estadísticas detalladas del sistema
  • Previsualización de imágenes con información detallada
🛠️ REQUISITOS DEL SISTEMA

Software Requerido

Python 3.8+
(recomendado Python 3.11)
MongoDB 4.4+
Base de datos principal
Qdrant 1.0+
Base de datos vectorial
Ollama
Con modelos instalados

Modelos de IA Requeridos

# Instalar modelos necesarios en Ollama
ollama pull qwen3:14b_40K # Modelo de lenguaje principal
ollama pull embeddinggemma # Modelo de embeddings

Hardware Recomendado

CPU
Multi-core (4+ núcleos)
RAM
8GB mínimo, 16GB recomendado
GPU
Opcional (para aceleración)
Espacio
10GB+ para modelos y datos
⚙️ INSTALACIÓN Y CONFIGURACIÓN

1. Instalación Automática con Conda

En Linux/Mac:

./setup_conda_linux.sh

En Windows:

setup_conda_windows.bat
¿Qué hace el script de instalación?
  1. Verifica que Conda esté instalado
  2. Crea entorno virtual busqueda_semantica_v2
  3. Instala Python 3.11
  4. Instala todas las dependencias necesarias
  5. Verifica la instalación

2. Activación del Entorno

Linux/Mac:

conda activate busqueda_semantica_v2

Windows:

conda activate busqueda_semantica_v2

3. Configuración de Variables de Entorno

# MongoDB
MONGODB_URI=mongodb://localhost:27017/
MONGODB_DATABASE=album
MONGODB_COLLECTION=imagenes_2

# Qdrant
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=
QDRANT_COLLECTION=imagenes_semanticas

# Ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen3:14b_40K
EMBEDDING_MODEL=embeddinggemma

# Aplicación
LOG_LEVEL=INFO
BATCH_SIZE=50
MAX_WORKERS=4

4. Inicio de Servicios

MongoDB:

sudo systemctl start mongod

Qdrant:

docker run -p 6333:6333 qdrant/qdrant

Ollama:

ollama serve

5. Ejecución de la Aplicación

python main.py
🖥️ INTERFAZ DE USUARIO

La aplicación cuenta con una interfaz gráfica moderna organizada en pestañas:

Pestaña 1: Búsqueda

Ubicación: Primera pestaña de la aplicación

Elementos principales:

  • Campo de consulta: Ingrese su búsqueda de forma natural
  • Tipo de búsqueda: Seleccione entre Híbrida, Texto o Semántica
  • Límite de resultados: Número máximo de resultados (1-100)
  • Umbral de similitud: Sensibilidad de la búsqueda (0.0-1.0)

Funcionalidades:

  • Búsqueda en tiempo real con autocompletado
  • Resultados ordenados por relevancia
  • Previsualización de imágenes con información detallada
  • Filtros por ubicación, objetos detectados, fechas

Pestaña 2: Estadísticas

Ubicación: Segunda pestaña

Información mostrada:

  • Total de documentos en la base de datos
  • Documentos procesados con embeddings
  • Tasa de procesamiento completado
  • Estado del sistema en tiempo real

Acciones disponibles:

  • Actualizar estadísticas manualmente
  • Procesar documentos pendientes
  • Ver logs de procesamiento

Pestaña 3: Configuración

Ubicación: Tercera pestaña

Configuraciones disponibles:

  • MongoDB: URI, base de datos, colección
  • Ollama: URL del servidor, modelo de lenguaje
  • Qdrant: URL del servidor, colección vectorial

Acciones:

  • Guardar configuración
  • Probar conexiones a todos los servicios
  • Validar configuración actual

Pestaña 4: Procesar Colección

Ubicación: Cuarta pestaña

Funcionalidad principal:

  • Procesamiento masivo de toda la colección
  • Generación de embeddings para documentos sin procesar
  • Actualización de descripciones semánticas

Configuración:

  • Tamaño del lote de procesamiento (10-200)
  • Máximo de documentos a procesar
  • Monitoreo en tiempo real del progreso

Pestaña 5: Detección de Objetos

Ubicación: Quinta pestaña

Sistema de detección:

  • Análisis automático de objetos en imágenes
  • Detección de personas y elementos
  • Procesamiento manual controlado por el usuario

Estado del sistema:

  • Número de imágenes pendientes
  • Estado del procesamiento
  • Logs de detección en tiempo real

Pestaña 6: Backup/Restore

Ubicación: Sexta pestaña

Funcionalidades:

  • Backup completo de MongoDB y Qdrant
  • Restauración desde archivos de backup
  • Validación de integridad de backups
  • Configuración de rutas de almacenamiento

Pestaña 7: Buscar Imágenes

Ubicación: Séptima pestaña

Búsqueda de archivos:

  • Exploración de directorios en busca de imágenes
  • Búsqueda recursiva en subdirectorios
  • Detección automática de imágenes nuevas
  • Procesamiento e inserción en la base de datos
🔍 FUNCIONALIDADES DETALLADAS

Sistema de Búsqueda Semántica

Tipos de Búsqueda Disponibles:

1. Búsqueda Híbrida (Recomendada)

  • Combina búsqueda de texto y similitud semántica
  • Utiliza embeddings vectoriales para encontrar resultados conceptualmente similares
  • Proporciona los resultados más relevantes y contextuales

2. Búsqueda de Texto

  • Búsqueda tradicional por palabras clave
  • Utiliza índices de texto optimizados
  • Rápida pero menos contextual

3. Búsqueda Semántica Pura

  • Basada exclusivamente en similitud vectorial
  • Encuentra imágenes conceptualmente similares
  • Ideal para consultas abstractas o creativas

Cómo Funciona la Búsqueda:

  • Procesamiento de la Consulta: La consulta del usuario se convierte en un vector de embedding
  • Comparación Vectorial: Se comparan con los embeddings de todas las imágenes
  • Cálculo de Similitud: Se calcula la similitud coseno entre vectores
  • Ordenamiento: Los resultados se ordenan por similitud descendente
    • Fórmula de Similitud:
    similitud = (A • B) / (|A| × |B|)
    Donde A y B son vectores de embedding
    Resultado entre 0.0 (nada similar) y 1.0 (idéntico)

    Procesamiento de Imágenes

    Extracción de Metadatos:

    Información EXIF:

    • Fecha y hora de creación
    • Dimensiones de la imagen
    • Configuración de cámara
    • Coordenadas GPS (si disponibles)

    Metadatos calculados:

    • Hash SHA512 para identificación única
    • Tamaño del archivo en bytes
    • Dimensiones en píxeles
    • Formato de imagen

    Detección de Objetos:

    Modelos utilizados:

    • Modelos pre-entrenados de visión por computadora
    • Detección de objetos comunes (personas, animales, vehículos)
    • Reconocimiento de escenas y contextos
  • Carga y preprocesamiento: de la imagen
  • Aplicación del modelo: de detección
  • Extracción de objetos: con confianza > 70%
  • Almacenamiento: de resultados en la base de datos

    • Generación de Descripciones:

  • Análisis: de objetos detectados
  • Extracción: de metadatos disponibles
  • Generación: de descripción natural con IA
  • Creación: de embedding semántico
  • Almacenamiento: en Qdrant para búsquedas

    • Gestión de Bases de Datos

    MongoDB (Almacenamiento Principal):

    Estructura de documentos:

    { "_id": "hash_sha512", "id_hash": "identificador_corto", "nombre": "nombre_archivo.jpg", "ruta": "/ruta/completa/a/imagen.jpg", "ancho": 1920, "alto": 1080, "peso": 2048576, "fecha_creacion": "2024-01-15T10:30:00", "coordenadas": {"lat": 40.7128, "lon": -74.0060}, "ciudad": "Nueva York", "barrio": "Manhattan", "objetos": ["persona", "edificio", "calle"], "personas": ["Juan", "María"], "embedding": [0.123, 0.456, ...], "descripcion_semantica": "Descripción generada por IA", "objeto_procesado": true }

    Qdrant (Búsquedas Vectoriales):

    Ventajas de Qdrant:
    • Búsquedas vectoriales ultra-rápidas
    • Indexación HNSW para eficiencia
    • Soporte para filtros complejos
    • Escalabilidad horizontal
    Configuración recomendada:
    • Distancia: Coseno
    • Dimensiones del vector: 384 (embeddinggemma)
    • Parámetros HNSW: m=16, ef_construction=200
    🔧 PROCESOS DE BÚSQUEDA

    Búsqueda Básica

  • Abrir la aplicación: python main.py
  • Ir a la pestaña "Búsqueda"
  • Escribir consulta: Ejemplo "perros jugando en el parque"
  • Seleccionar tipo: "Híbrida" (recomendado)
  • Configurar límite: 10-20 resultados
  • Ajustar umbral: 0.7 (70% similitud mínima)
  • Hacer clic en "Buscar"

    • Búsqueda Avanzada con Filtros

    Filtros disponibles:

    📍 Ubicación

    Ciudad, barrio, calle, país

    🔍 Objetos

    Elementos específicos detectados

    👥 Personas

    Personas identificadas en las imágenes

    📅 Fechas

    Rango de fechas de creación

    📐 Dimensiones

    Tamaño de las imágenes

    Ejemplo de búsqueda filtrada:

  • Consulta: "paisaje"
  • Filtros: Ciudad="Madrid", Objetos=["montaña", "lago"]
  • Resultado: Imágenes de paisajes con montañas y lagos en Madrid

    • Búsqueda por Similitud Visual

  • Seleccionar una imagen de los resultados
  • Hacer clic derecho o usar botón "Buscar similares"
  • El sistema encuentra imágenes visualmente similares
  • Ordenadas por similitud visual y semántica
    • 📸 PROCESAMIENTO DE IMÁGENES

    Procesamiento Individual

  • Ir a "Buscar Imágenes"
  • Seleccionar directorio con imágenes
  • Configurar opciones:
    • Búsqueda recursiva: ✓
    • Solo imágenes nuevas: ✓
  • Hacer clic en "Buscar Imágenes"
  • Revisar resultados encontrados
  • Procesar imágenes seleccionadas

    • Procesamiento por Lotes

  • Ir a "Procesar Colección"
  • Configurar parámetros:
    • Tamaño del lote: 50
    • Máximo documentos: 1000
  • Hacer clic en "Procesar Colección Completa"
  • Monitorear progreso en tiempo real
  • Ver estadísticas de procesamiento

    • Procesamiento Manual de Objetos

  • Ir a "Detección de Objetos"
  • Ver estado del sistema
  • Hacer clic en "Procesar Ahora"
  • Monitorear detección en el log
  • Verificar resultados en la base de datos
    • 💾 GESTIÓN DE BASES DE DATOS

    Backup y Restauración

    Crear Backup:

  • Ir a "Backup/Restore"
  • Seleccionar tipo: MongoDB o Qdrant
  • Elegir ruta del archivo de backup
  • Hacer clic en "Crear Backup"
  • Esperar a que termine el proceso
  • Verificar archivo creado

    • Restaurar Backup:

  • Seleccionar archivo de backup existente
  • Configurar opciones:
    • Recrear colección: ✓ (recomendado)
    • Eliminar existente: ✓
  • Confirmar restauración
  • Esperar a que termine
  • Verificar datos restaurados

    • Mantenimiento de Índices

    Índices automáticos:
    • Índice de texto para búsquedas
    • Índice único por hash SHA512
    • Índices compuestos para consultas frecuentes

    Optimización manual:

    # Recrear índices de texto
    db.imagenes_2.dropIndexes()
    db.imagenes_2.createIndex({
    nombre: "text",
    descripcion_semantica: "text",
    objetos: "text",
    ciudad: "text"
    })

    Limpieza de Datos

    Eliminar duplicados:

    # Script para eliminar duplicados por hash
    from src.database import DatabaseManager
    db = DatabaseManager()
    db.collection.delete_many({"hash_sha512": {"$in": duplicados}})

    Limpiar documentos incompletos:

    # Eliminar documentos sin información básica
    db.collection.delete_many({
    "$or": [
    {"nombre": {"$exists": False}},
    {"ruta": {"$exists": False}},
    {"ancho": {"$exists": False}}
    ]
    })
    ⚙️ CONFIGURACIÓN AVANZADA

    Variables de Entorno Avanzadas

    # Configuración de logging
    LOG_LEVEL=DEBUG
    LOG_FILE=busqueda_semantica.log

    # Configuración de procesamiento
    BATCH_SIZE=100
    MAX_WORKERS=8
    TIMEOUT_REQUESTS=30

    # Configuración de modelos
    OLLAMA_TIMEOUT=60
    EMBEDDING_DIMENSIONS=384
    SIMILARITY_THRESHOLD=0.7

    # Configuración de memoria
    MAX_MEMORY_USAGE=0.8
    GARBAGE_COLLECTION_INTERVAL=100

    # Configuración de cache
    CACHE_EMBEDDINGS=True
    CACHE_SIZE=1000
    CACHE_TTL=3600

    Configuración de Modelos

    Modelos alternativos de Ollama:

    # Modelos de lenguaje
    ollama pull llama2:13b
    ollama pull codellama:13b

    # Modelos de embeddings
    ollama pull all-minilm-l6-v2
    ollama pull mxbai-embed-large

    Configuración de parámetros:

    # En el código de inicialización
    model_kwargs = {
    "temperature": 0.1,
    "top_p": 0.9,
    "max_tokens": 512,
    "repeat_penalty": 1.1
    }

    Configuración de Qdrant

    Optimización de rendimiento:

    # Configuración recomendada
    collection_config = {
    "vectors": {
    "size": 384,
    "distance": "Cosine"
    },
    "optimizers": {
    "deleted_threshold": 0.2,
    "vacuum_min_vector_number": 1000
    },
    "hnsw_config": {
    "m": 16,
    "ef_construct": 200,
    "full_scan_threshold": 10000
    }
    }
    🐛 SOLUCIÓN DE PROBLEMAS

    Problemas Comunes

    1. Error de Conexión a MongoDB

    Síntoma: "Error al conectar a MongoDB"

    Causa: MongoDB no está ejecutándose

    Solución:

    # Verificar estado
    sudo systemctl status mongod

    # Iniciar servicio
    sudo systemctl start mongod

    # Verificar conexión
    mongosh --eval "db.adminCommand('ping')"

    2. Error de Conexión a Qdrant

    Síntoma: "Error al conectar a Qdrant"

    Causa: Qdrant no está ejecutándose

    Solución:

    # Verificar contenedor Docker
    docker ps | grep qdrant

    # Reiniciar Qdrant
    docker restart qdrant

    # Verificar API
    curl http://localhost:6333/health

    3. Error de Modelos de Ollama

    Síntoma: "Error al inicializar modelos"

    Causa: Modelos no instalados o Ollama no ejecutándose

    Solución:

    # Verificar Ollama
    ollama list

    # Instalar modelos requeridos
    ollama pull qwen3:14b_40K
    ollama pull embeddinggemma

    # Reiniciar Ollama
    ollama serve

    4. Error de Memoria Insuficiente

    Síntoma: "Out of memory" o aplicación se cierra

    Causa: Procesamiento de lotes muy grandes

    Solución:

    # Reducir tamaño de lote
    BATCH_SIZE=10 python main.py

    # Procesar en lotes más pequeños
    python procesar_coleccion.py --max-docs 100

    5. Búsquedas Lentas

    Síntoma: Resultados tardan mucho tiempo

    Causa: Falta de índices o configuración inadecuada

    Solución:

    # Recrear índices de texto
    python setup_text_indexes.py

    # Optimizar configuración Qdrant
    # Revisar parámetros HNSW

    Logs y Debug

    Ubicación de logs:
    • Archivo: busqueda_semantica.log
    • Nivel: Configurable en variables de entorno

    Modo debug:

    LOG_LEVEL=DEBUG python main.py

    Logs detallados:

    # Ver logs en tiempo real
    tail -f busqueda_semantica.log

    # Buscar errores específicos
    grep "ERROR" busqueda_semantica.log

    Recuperación de Datos

  • Si se corrompe la base de datos:
    1. Detener la aplicación
    2. Restaurar desde backup más reciente
    3. Recrear índices si es necesario
    4. Reiniciar aplicación
  • Si se pierden embeddings:
    1. Ir a "Procesar Colección"
    2. Procesar documentos sin embedding
    3. Verificar que Qdrant se actualice correctamente
    • 🔧 MANTENIMIENTO Y BACKUP

    Backup Regular

    Frecuencia recomendada:
    • Backup completo: Semanal
    • Backup incremental: Diario
    • Backup antes de cambios importantes: Siempre

    Estrategia de backup:

    # Backup diario automático
    0 2 * * * /ruta/al/proyecto/backup_daily.sh

    # Backup semanal completo
    0 3 * * 1 /ruta/al/proyecto/backup_weekly.sh

    Monitoreo del Sistema

    Métricas importantes:
    • Espacio en disco utilizado
    • Número de documentos procesados
    • Tasa de éxito de búsquedas
    • Tiempo de respuesta promedio

    Comandos de monitoreo:

    # Estado del sistema
    python status.py

    # Verificar integridad
    python check_imports.py

    # Estadísticas detalladas
    python -c "from src.database import DatabaseManager; db = DatabaseManager(); print(db.obtener_estadisticas())"

    Limpieza Periódica

    Eliminar datos antiguos:

    # Eliminar documentos con errores
    db.collection.delete_many({"error": {"$exists": True}})

    # Limpiar logs antiguos
    # (se hace automáticamente con logrotate)

    Optimizar almacenamiento:

    # Recrear colección optimizada
    python recreate_qdrant_collection.py

    # Limpiar documentos duplicados
    python setup_mongodb.py
    💻 COMANDOS DE LÍNEA

    Procesamiento por Lotes

    # Procesar toda la colección
    python procesar_coleccion.py --batch-size 50 --verbose

    # Procesar máximo 1000 documentos
    python procesar_coleccion.py --max-docs 1000 --batch-size 25

    # Procesamiento silencioso
    python procesar_coleccion.py --batch-size 100

    Búsqueda Directa

    # Búsqueda semántica desde Python
    from src.busqueda_semantica import BuscadorSemantico
    from src.database import DatabaseManager

    db = DatabaseManager()
    buscador = BuscadorSemantico(db)
    resultados = buscador.buscar_semanticamente('perros jugando en el parque')

    for r in resultados:
    print(f'{r.documento.nombre}: {r.similitud:.3f}')

    Utilidades del Sistema

    # Ver estado del sistema
    python status.py

    # Verificar integridad de datos
    python check_imports.py

    # Recrear colección de Qdrant
    python recreate_qdrant_collection.py

    # Backup de MongoDB
    python test_backup_restore_mongodb.py

    # Backup de Qdrant
    python test_backup_restore.py

    Configuración desde Línea de Comandos

    # Configurar variables de entorno
    export MONGODB_URI="mongodb://localhost:27017/"
    export OLLAMA_BASE_URL="http://localhost:11434"

    # Ejecutar con configuración específica
    MONGODB_DATABASE=album python main.py
    📸 CAPTURAS DE PANTALLA
    Interfaz principal de Búsqueda Semántica V2
    Interfaz principal con pestañas de navegación y controles de búsqueda
    Pestaña de procesamiento de colección
    Procesamiento por lotes con estadísticas en tiempo real y control de progreso
    Pestaña de búsqueda semántica
    Interfaz de búsqueda con filtros avanzados y resultados ordenados por relevancia
    Configuración del sistema
    Configuración de parámetros de conexión y modelos de IA
    Monitoreo y logs
    Seguimiento de procesos, logs del sistema y estadísticas detalladas
    Resultados de búsqueda
    Visualización de resultados con similitud, metadatos y previsualización de imágenes