bookSearchLLM / README.md
Alopmel's picture
Update README.md
6fc6fae verified
|
Raw History Blame Contribute Delete
11.6 kB
metadata
title: BookSearchLLM
emoji: 📚
colorFrom: purple
colorTo: blue
sdk: docker
pinned: false
short\_description: Buscador inteligente

📖 Book Search LLM

Búsqueda híbrida (literal + semántica) sobre 18 libros con FastAPI, Qdrant y Sentence-Transformers. Frontend en HTML/CSS/JS. El Space de Hugging Face utiliza Docker (no necesitas Docker local).


🧠 ¿Qué hace el proyecto?

  • Búsqueda híbrida

    • Semántica: embeddings con sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 (384 dims, distancia cosine) almacenados en Qdrant (vector dense).
    • Literal fuzzy: normalización (sin tildes), variaciones útiles para sánscrito y similitud difflib.
    • Estrategias: smart | keyword | semantic | balanced.
  • Contexto por párrafos: ventana antes/después del párrafo seleccionado, respetando el orden de capítulos (chapter_path).

  • Traducción EN/IT→ES con M2M100 (facebook/m2m100_418M) + langdetect. El resultado se guarda en translate_text dentro de Qdrant.

  • Frontend con filtros (score, tipo de match, autor/libro), paginación, historial y exportación.


🗂️ Estructura del repo

app/
  main.py                # FastAPI + endpoints
  qdrant_backend.py      # búsquedas (Qdrant) + traducción + contexto
  static/
    app.js               # UI/UX
    app.css
  templates/
    index.html           # frontend
requirements.txt         # dependencias
README.md

✅ Requisitos

  • Python 3.10 (para desarrollo local)
  • Cuenta en Hugging Face (Space con SDK docker)
  • Instancia de Qdrant accesible por URL y API Key
  • git y git-lfs

El Space usa Docker según el Dockerfile incluido; no hace falta Docker local.


📦 Dependencias (requirements.txt)

# --- Web/API ---
fastapi>=0.110,<1.0
uvicorn[standard]>=0.27
jinja2>=3.1
aiofiles>=23.2
python-dotenv>=1.0
pydantic>=2,<3

# --- Vector / búsqueda ---
qdrant-client==1.9.0
fastembed==0.5.1
onnxruntime>=1.17   # backend para fastembed en CPU

# --- LLM/Traducción M2M100 ---
transformers>=4.42,<4.47
torch>=2.2,<2.6
sentencepiece==0.1.99
safetensors>=0.4.3

# --- Utilidades proyecto ---
python-Levenshtein>=0.21
langdetect==1.0.9
huggingface_hub[hf_xet]>=0.24

🧪 Puesta en marcha local (VS Code, Windows/Linux/macOS)

1) Clonar el repo

git clone https://github.com/ALOPMEL/bookSearchLLM.git
cd bookSearchLLM

2) Crear y activar entorno virtual (Python 3.10)

PowerShell/VS Code terminal:

py -3.10 -m venv .venv
.venv\Scripts\activate

Bash (Linux/macOS/WSL):

python3 -m venv .venv
source .venv/bin/activate

Git Bash (Windows):

source .venv/Scripts/activate

En VS Code: Ctrl+Shift+P → Python: Select Interpreter → .venv.

3) Instalar dependencias

python -m pip install --upgrade pip
pip install -r requirements.txt

4) Variables de entorno

Crea .env en la raíz:

QDRANT_URL=https://TU-QDRANT:6333
QDRANT_API_KEY=xxxxxxxxxxxxxxxx
QDRANT_COLLECTION=bookSearchLLM
EMBED_MODEL=sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
M2M_MODEL=facebook/m2m100_418M
M2M_MAX_SRC_TOKENS=900
M2M_MAX_NEW_TOKENS=512
WARMUP=1
DEBUG=0

5) Ejecutar la API en local

uvicorn app.main:app --reload --host 0.0.0.0 --port 7860
# Abre http://127.0.0.1:7860

🗄️ Qdrant (colección)

  • Nombre: bookSearchLLM (ajústalo en .env)
  • Vector dense: 384 dimensiones, cosine
  • Puntos: ~16k (variable)
  • Payload mínimo por punto: text, book, page, paragraph_index, author; opcional chapter_path, translate_text.

☁️ Conectar y desplegar en Hugging Face (Space Docker)

1) Login en HF

pip install huggingface_hub git-lfs
huggingface-cli login   # pega tu Access Token

2) Añadir remoto del Space y publicar

git remote add hf https://huggingface.co/spaces/Alopmel/bookSearchLLM
git add -A && git commit -m "feat: actualización app y backend"
git push hf main

El Space reconstruye el Docker automáticamente con el Dockerfile.

3) Si el repo principal está en GitHub

git remote -v   # origin → GitHub, hf → HuggingFace

🐳 Dockerfile (referencia)

FROM python:3.11-slim
ENV PIP_NO_CACHE_DIR=1 \
    HF_HOME=/app/.cache/huggingface \
    HUGGINGFACE_HUB_CACHE=/app/.cache/huggingface \
    UVICORN_WORKERS=1 \
    OMP_NUM_THREADS=1
WORKDIR /app
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
RUN python - <<'PY'
from fastembed import TextEmbedding
TextEmbedding("sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2")
from sentence_transformers import SentenceTransformer
SentenceTransformer("sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2")
print("Modelos precargados ✅")
PY
COPY . .
EXPOSE 7860
CMD ["python", "-m", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

📥 Ejemplos de uso de la API (curl)

Buscar (híbrido):

curl -X POST "http://127.0.0.1:7860/api/search" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "¿Qué es el spanda?",
    "strategy": "smart",
    "max_results": 50
  }'

Contexto por párrafo:

curl -X POST "http://127.0.0.1:7860/api/context" \
  -H "Content-Type: application/json" \
  -d '{
    "libro": "Tantraloka",
    "author": "Abhinavagupta",
    "page": 120,
    "paragraph_index": 3,
    "before": 2,
    "after": 2
  }'

Traducción EN/IT → ES (M2M100) + guardado en Qdrant:

curl -X POST "http://127.0.0.1:7860/api/translate" \
  -H "Content-Type: application/json" \
  -d '{
    "libro": "Tantraloka",
    "page": 120,
    "paragraph_index": 3,
    "author": "Abhinavagupta",
    "text": "Consciousness is the ground of reality.",
    "src_lang": "en"
  }'

🔌 Endpoints

  • POST /api/search → búsqueda
  • POST /api/search/advanced → filtros
  • POST /api/context → contexto por párrafo
  • POST /api/translate → traducción (EN/IT→ES con M2M100) y guardado en Qdrant
  • GET /health → estado + stats

🧩 Detalles clave de implementación

  • Embeddings con fastembed
  • Fuzzy: variaciones + similitud difusa
  • Estrategia smart: preguntas largas → semántica; tokens cortos → balanced/keyword
  • Traducción: troceo + batch con M2M100; persistencia en Qdrant

🆘 Troubleshooting

Problemas comunes

  • huggingface-cli: command not found → pip install huggingface_hub
  • sentencepiece faltante → revisa requirements.txt
  • Could not import module "main" → ejecuta desde raíz: uvicorn app.main:app --reload

Entornos virtuales

Crear / activar / desactivar

py -3.10 -m venv .venv
.venv\Scripts\activate
deactivate
python3 -m venv .venv
source .venv/bin/activate
deactivate

Listar entornos virtuales

Get-ChildItem -Recurse -Directory -Force | Where-Object { $_.Name -in @('venv','.venv') }
find . -type d \( -name "venv" -o -name ".venv" \)

Ver versión de Python

$py = ".venv\\Scripts\\python.exe"; & $py -V
source .venv/bin/activate && python -V

Borrar entornos bloqueados (Windows)

Get-Process python,pythonw,uvicorn,pip -ErrorAction SilentlyContinue | Stop-Process -Force
Remove-Item -Recurse -Force .venv

Logs del servidor

uvicorn app.main:app --reload --log-level debug
uvicorn app.main:app --reload --port 7860 | Tee-Object -FilePath .\server.log

📘 Guía de Comandos (PowerShell & Bash)

Este apartado está listo para copiar y pegar.

🐍 Entornos virtuales

Crear

# PowerShell
py -3.10 -m venv .venv
# Bash / WSL / macOS
python3 -m venv .venv

Activar

# PowerShell
.venv\Scripts\activate
# Bash / WSL / macOS
source .venv/bin/activate
# Git Bash en Windows (alternativa)
source .venv/Scripts/activate

Desactivar

deactivate

Eliminar (Windows bloqueado por procesos)

Get-Process python,pythonw,uvicorn,pip -ErrorAction SilentlyContinue | Stop-Process -Force
Remove-Item -Recurse -Force .venv
rm -rf .venv

Listar entornos dentro del proyecto

Get-ChildItem -Recurse -Directory -Force | Where-Object { $_.Name -in @('venv','.venv') }
find . -type d \( -name "venv" -o -name ".venv" \)

Comprobar versión de Python del venv

$py = ".venv\Scripts\python.exe"; & $py -V
source .venv/bin/activate && python -V

📦 Dependencias

pip install --upgrade pip
pip install -r requirements.txt

🚀 Servidor FastAPI (Uvicorn)

Windows (PowerShell)

(Opcional) Para evitar errores de codificación con emojis/acentos:

chcp 65001 | Out-Null
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new()
$OutputEncoding = [System.Text.UTF8Encoding]::new()
$env:PYTHONIOENCODING = "utf-8"
  1. Solo consola (el propio proyecto ya guarda en logs/app.log)
uvicorn app.main:app --reload --host 0.0.0.0 --port 7860 --log-level debug
  1. Consola y guardar copia adicional (evita duplicados usando otro archivo)
uvicorn app.main:app --reload --host 0.0.0.0 --port 7860 --log-level debug `
| Tee-Object -FilePath .\logs\uvicorn.log -Append
  1. Solo archivo, sin mostrar nada en consola

Opción A (recomendada): silenciar la consola y dejar que tu logger escriba en logs/app.log

uvicorn app.main:app --reload --host 0.0.0.0 --port 7860 --log-level debug *> $null

Opción B: redirigir toda la salida de Uvicorn a otro archivo

uvicorn app.main:app --reload --host 0.0.0.0 --port 7860 --log-level debug *> .\logs\uvicorn.log

Linux / macOS (Bash)

  1. Solo consola (el propio proyecto ya guarda en logs/app.log)
uvicorn app.main:app --reload --host 0.0.0.0 --port 7860 --log-level debug
  1. Consola y guardar copia adicional
uvicorn app.main:app --reload --host 0.0.0.0 --port 7860 --log-level debug 2>&1 | tee -a logs/uvicorn.log
  1. Solo archivo, sin mostrar nada en consola

Opción A (recomendada): silenciar la consola y dejar que tu logger escriba en logs/app.log

uvicorn app.main:app --reload --host 0.0.0.0 --port 7860 --log-level debug >/dev/null 2>&1

Opción B: redirigir toda la salida de Uvicorn a otro archivo

uvicorn app.main:app --reload --host 0.0.0.0 --port 7860 --log-level debug > logs/uvicorn.log 2>&1

🐙 Git (opcional)

git init
git add .
git commit -m "Primer commit"
git remote add origin https://github.com/usuario/repositorio.git
git branch -M main
git push -u origin main

🧹 Tips

# Ver dependencias
pip list
# Congelar dependencias
pip freeze > requirements.txt
# Probar salud
curl http://127.0.0.1:7860/health

👤 Para el programador del cliente

  1. Clona el repo, crea .env con Qdrant y selecciona Python 3.10 en VS Code.
  2. pip install -r requirements.txt y arranca con uvicorn app.main:app --reload.
  3. Haz login en HF (huggingface-cli login) y añade el remoto hf.
  4. git push hf main para reconstruir el Space (Docker).

📝 Licencia

MIT (ajústala si el cliente necesita otra).