Image for post Búsqueda Semántica con FastAPI y ChromaDB: Indexando y Consultando tus Propios Datos

Búsqueda Semántica con FastAPI y ChromaDB: Indexando y Consultando tus Propios Datos

Escrito por Sergio Márquez

En el mundo digital actual, la cantidad de información crece exponencialmente. Tradicionalmente, la búsqueda de información se ha basado en palabras clave, un método que, aunque útil, tiene limitaciones significativas. Si buscas "coches rápidos", un sistema de búsqueda por palabras clave podría no encontrar documentos que hablen de "vehículos deportivos" o "automóviles de alta velocidad" porque no hay una coincidencia exacta de términos. Aquí es donde la búsqueda semántica entra en juego, permitiendo a las máquinas entender el significado y el contexto detrás de las palabras, no solo las palabras en sí. [6, 9, 12]

Este artículo te guiará paso a paso en la construcción de una API de búsqueda semántica utilizando FastAPI para la interfaz web y ChromaDB como base de datos vectorial, todo ello potenciado por modelos de embeddings de Sentence Transformers. Al final, tendrás una aplicación funcional capaz de indexar tus propios datos y realizar búsquedas inteligentes que van más allá de las coincidencias literales.

Conceptos Clave

Embeddings: El Lenguaje de las Máquinas

Los embeddings son representaciones numéricas (vectores) de texto, imágenes, audio o cualquier otro tipo de dato, que capturan su significado semántico. [1, 4, 5, 12] En el contexto del texto, palabras o frases con significados similares se mapean a vectores que están "cercanos" en un espacio multidimensional. Esto significa que si dos frases tienen un significado parecido, sus vectores correspondientes estarán próximos entre sí. [12]

Estos vectores se generan utilizando modelos de lenguaje pre-entrenados, como los de la librería sentence-transformers, que han aprendido a codificar el significado de las palabras y frases a partir de vastas cantidades de texto. [1, 2, 4, 5]

Bases de Datos Vectoriales: Almacenando el Significado

Una base de datos vectorial es un tipo de base de datos especializada diseñada para almacenar, gestionar y buscar eficientemente estos embeddings de alta dimensión. [18, 22, 25] A diferencia de las bases de datos tradicionales que buscan por valores exactos o rangos, las bases de datos vectoriales realizan búsquedas de "similitud", encontrando los vectores más cercanos a un vector de consulta dado. [18, 22]

Esto es crucial para la búsqueda semántica, ya que nos permite encontrar documentos o fragmentos de texto que son conceptualmente similares a nuestra consulta, incluso si no comparten las mismas palabras clave. [12, 18]

ChromaDB: Tu Base de Datos Vectorial Ligera

ChromaDB es una base de datos vectorial de código abierto, ligera y fácil de usar, que se integra perfectamente con el ecosistema Python. [18, 22, 25, 26] Es ideal para proyectos de IA, prototipos y aplicaciones de menor escala, ya que puede funcionar en memoria o persistir datos localmente. [22, 25, 26] ChromaDB simplifica la gestión de colecciones de embeddings y ofrece funcionalidades de búsqueda de similitud de manera eficiente. [22, 26]

FastAPI: Construyendo APIs Rápidas y Robustas

FastAPI es un framework web moderno y de alto rendimiento para construir APIs con Python, conocido por su velocidad, facilidad de uso y soporte para programación asíncrona. [3, 10, 16] Utiliza tipado de Python para la validación de datos (gracias a Pydantic) y genera automáticamente documentación interactiva de la API (OpenAPI/Swagger UI), lo que acelera el desarrollo y la depuración. [3, 11, 14, 17, 20, 21]

Implementación Paso a Paso

1. Configuración del Entorno

Primero, asegúrate de tener Python 3.9+ instalado. Luego, crea un entorno virtual y instala las dependencias necesarias:

# Crear y activar un entorno virtual
python -m venv venv
source venv/bin/activate  # En Linux/macOS
# venv\Scripts\activate  # En Windows

# Instalar dependencias
pip install fastapi uvicorn chromadb sentence-transformers

2. Inicializar ChromaDB y el Modelo de Embeddings

Crearemos un archivo main.py que contendrá nuestra aplicación FastAPI. Dentro de este archivo, inicializaremos ChromaDB y cargaremos nuestro modelo de embeddings. Usaremos all-MiniLM-L6-v2 de Sentence Transformers, un modelo pequeño pero eficiente para propósitos generales. [1, 2, 18, 22]

# main.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List, Dict, Any
import chromadb
from sentence_transformers import SentenceTransformer
import os

# Configuración de la base de datos ChromaDB
# Usaremos una base de datos persistente que se guardará en la carpeta './chroma_db'
CHROMA_DB_PATH = "./chroma_db"
chroma_client = chromadb.PersistentClient(path=CHROMA_DB_PATH)

# Nombre de la colección de documentos
COLLECTION_NAME = "mis_documentos"

# Cargar el modelo de Sentence Transformers para generar embeddings
# 'all-MiniLM-L6-v2' es un buen modelo balanceado entre tamaño y rendimiento
print("Cargando modelo de embeddings... Esto puede tardar un momento la primera vez.")
embedding_model = SentenceTransformer('all-MiniLM-L6-v2') [1, 2]
print("Modelo de embeddings cargado.")

# Obtener o crear la colección en ChromaDB
# ChromaDB puede usar su función de embedding por defecto o la que le proporcionemos.
# Aquí, generaremos los embeddings manualmente para tener más control.
try:
    collection = chroma_client.get_or_create_collection(name=COLLECTION_NAME)
    print(f"Colección '{COLLECTION_NAME}' lista. Documentos actuales: {collection.count()}")
except Exception as e:
    print(f"Error al inicializar ChromaDB o la colección: {e}")
    exit(1)

app = FastAPI(
    title="API de Búsqueda Semántica con FastAPI y ChromaDB",
    description="API para indexar y consultar documentos usando embeddings y búsqueda de similitud."
)

3. Definir Modelos de Datos con Pydantic

Para la validación de las entradas y salidas de nuestra API, utilizaremos Pydantic. [11, 14, 17, 20, 21]

# main.py (continuación)

class DocumentoInput(BaseModel):
    id: str
    contenido: str
    metadata: Dict[str, Any] = {}

class DocumentoOutput(BaseModel):
    id: str
    contenido: str
    metadata: Dict[str, Any]
    distancia: float = None # Para resultados de búsqueda

class SearchQuery(BaseModel):
    query: str
    n_results: int = 5

class SearchResult(BaseModel):
    documentos: List[DocumentoOutput]

4. Implementar Endpoints de la API

Ahora, crearemos los endpoints para añadir documentos y realizar búsquedas.

Endpoint para Añadir Documentos (`POST /documents`)

Este endpoint recibirá un documento, generará su embedding y lo almacenará en ChromaDB. [19, 22, 26]

# main.py (continuación)

@app.post("/documents", response_model=DocumentoOutput, summary="Añadir un nuevo documento")
async def add_document(doc_input: DocumentoInput):
    try:
        # Generar embedding para el contenido del documento
        embedding = embedding_model.encode(doc_input.contenido).tolist()

        # Añadir el documento a la colección de ChromaDB
        collection.add(
            embeddings=[embedding],
            documents=[doc_input.contenido],
            metadatas=[doc_input.metadata],
            ids=[doc_input.id]
        )
        return DocumentoOutput(id=doc_input.id, contenido=doc_input.contenido, metadata=doc_input.metadata)
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Error al añadir documento: {e}")

Endpoint para Búsqueda Semántica (`POST /search`)

Este endpoint tomará una consulta de texto, generará su embedding y buscará los documentos más similares en ChromaDB. [19, 22, 26, 27]

# main.py (continuación)

@app.post("/search", response_model=SearchResult, summary="Realizar búsqueda semántica")
async def semantic_search(search_query: SearchQuery):
    try:
        # Generar embedding para la consulta
        query_embedding = embedding_model.encode(search_query.query).tolist()

        # Realizar la búsqueda de similitud en ChromaDB
        results = collection.query(
            query_embeddings=[query_embedding],
            n_results=search_query.n_results,
            include=['documents', 'metadatas', 'distances']
        )

        # Formatear los resultados
        found_documents = []
        if results and results['documents']:
            for i in range(len(results['documents'][0])):
                doc_id = results['ids'][0][i]
                content = results['documents'][0][i]
                metadata = results['metadatas'][0][i]
                distance = results['distances'][0][i]
                found_documents.append(DocumentoOutput(
                    id=doc_id,
                    contenido=content,
                    metadata=metadata,
                    distancia=distance
                ))
        
        return SearchResult(documentos=found_documents)
    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Error en la búsqueda semántica: {e}")

@app.get("/health", summary="Verificar el estado de la API")
async def health_check():
    return {"status": "ok", "chroma_documents": collection.count()}

5. Mini Proyecto / Aplicación Sencilla

Para ejecutar la API, guarda el código anterior como main.py y usa Uvicorn:


uvicorn main:app --reload

Esto iniciará el servidor en http://127.0.0.1:8000. Puedes acceder a la documentación interactiva en http://127.0.0.1:8000/docs. [10, 16]

Ejemplo de Uso con `curl`

Añadir Documentos:

curl -X POST "http://127.0.0.1:8000/documents" \
-H "Content-Type: application/json" \
-d '{ "id": "doc1", "contenido": "El perro es el mejor amigo del hombre.", "metadata": { "autor": "ChatGPT" } }'

curl -X POST "http://127.0.0.1:8000/documents" \
-H "Content-Type: application/json" \
-d '{ "id": "doc2", "contenido": "Los gatos son animales independientes y elegantes.", "metadata": { "autor": "Bard" } }'

curl -X POST "http://127.0.0.1:8000/documents" \
-H "Content-Type: application/json" \
-d '{ "id": "doc3", "contenido": "Un cachorro juega alegremente en el parque.", "metadata": { "tema": "animales" } }'

curl -X POST "http://127.0.0.1:8000/documents" \
-H "Content-Type: application/json" \
-d '{ "id": "doc4", "contenido": "La inteligencia artificial está transformando la industria tecnológica.", "metadata": { "categoria": "tecnologia" } }'
Realizar Búsqueda Semántica:

curl -X POST "http://127.0.0.1:8000/search" \
-H "Content-Type: application/json" \
-d '{ "query": "animales domésticos", "n_results": 2 }'

# Posible Salida:
# {"documentos":[
#   {"id":"doc1","contenido":"El perro es el mejor amigo del hombre.","metadata":{"autor":"ChatGPT"},"distancia":0.25...},
#   {"id":"doc3","contenido":"Un cachorro juega alegremente en el parque.","metadata":{"tema":"animales"},"distancia":0.30...}
# ]}

curl -X POST "http://127.0.0.1:8000/search" \
-H "Content-Type: application/json" \
-d '{ "query": "avances en computación", "n_results": 1 }'

# Posible Salida:
# {"documentos":[
#   {"id":"doc4","contenido":"La inteligencia artificial está transformando la industria tecnológica.","metadata":{"categoria":"tecnologia"},"distancia":0.18...}
# ]}

Errores Comunes y Depuración

  • ModuleNotFoundError o problemas de instalación: Asegúrate de que tu entorno virtual esté activado y que todas las dependencias (fastapi, uvicorn, chromadb, sentence-transformers) estén correctamente instaladas.
  • Modelo de embeddings no cargado: La primera vez que ejecutas el código, sentence-transformers descargará el modelo. Esto requiere conexión a internet y puede tardar unos minutos. Si hay un problema de red o el modelo no se descarga correctamente, la aplicación podría fallar al iniciar.
  • ChromaDB no inicializado: Verifica la ruta CHROMA_DB_PATH. Si hay problemas de permisos o la ruta no es accesible, ChromaDB podría no inicializarse. El mensaje de error en la consola te dará pistas.
  • Errores de validación de Pydantic: Si los datos que envías a la API no coinciden con los modelos DocumentoInput o SearchQuery, FastAPI devolverá un error 422 (Unprocessable Entity) con detalles sobre el campo problemático. Revisa la estructura de tu JSON.
  • Resultados de búsqueda inesperados: La calidad de la búsqueda semántica depende en gran medida del modelo de embeddings. Si los resultados no son relevantes, considera probar con un modelo de sentence-transformers diferente (aunque all-MiniLM-L6-v2 es un buen punto de partida) o asegurarte de que tus documentos sean lo suficientemente descriptivos.
  • Puerto en uso: Si uvicorn no puede iniciar, es posible que el puerto 8000 ya esté en uso. Puedes cambiarlo con uvicorn main:app --reload --port 8001.

Aprendizaje Futuro

Este mini proyecto es solo el comienzo. Aquí hay algunas ideas para llevar tu sistema de búsqueda semántica al siguiente nivel:

  • Integración con LLMs para RAG: Combina la búsqueda semántica con un Large Language Model (LLM) para construir un sistema de Retrieval Augmented Generation (RAG). Utiliza los documentos recuperados por ChromaDB como contexto para que el LLM genere respuestas más precisas y fundamentadas. [24, 29]
  • Bases de Datos Vectoriales en la Nube: Para aplicaciones en producción y a gran escala, explora servicios de bases de datos vectoriales gestionadas como Pinecone, Qdrant, Weaviate o Google Cloud Vertex AI Vector Search.
  • Estrategias de Chunking: Para documentos muy grandes, es beneficioso dividirlos en "chunks" (fragmentos) más pequeños antes de generar embeddings. Experimenta con diferentes tamaños y solapamientos de chunks para optimizar la relevancia de la búsqueda.
  • Filtrado de Metadatos Avanzado: ChromaDB permite filtrar resultados de búsqueda basándose en los metadatos asociados a los documentos. [22, 24, 26] Implementa lógica de filtrado para refinar tus búsquedas (por ejemplo, buscar solo documentos de un autor o categoría específica).
  • Modelos de Embeddings Específicos del Dominio: Si trabajas con un dominio muy específico (legal, médico, técnico), considera fine-tunear un modelo de embeddings o usar uno pre-entrenado para ese dominio para obtener mejores resultados. [1, 5]
  • Despliegue en Producción: Para un despliegue robusto, considera usar Docker para contener tu aplicación FastAPI y un servidor ASGI como Gunicorn junto con Uvicorn para gestionar múltiples workers. [3, 8, 10, 13]

La búsqueda semántica es una herramienta poderosa que abre un abanico de posibilidades para construir aplicaciones de IA más inteligentes y contextuales. ¡Experimenta y sigue construyendo!

Volver al blog