Spaces:
Sleeping
Download README.md from Alopmel/bookSearchLLM: direct link, hf CLI and curl.
- Browser
- Download file 11.6 kB
-
https://huggingface.co/spaces/Alopmel/bookSearchLLM/resolve/main/README.md
- Command line
-
hf download hf://spaces/Alopmel/bookSearchLLM/README.md
-
curl -L -o README.md https://huggingface.co/spaces/Alopmel/bookSearchLLM/resolve/main/README.md
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 (vectordense). - Literal fuzzy: normalización (sin tildes), variaciones útiles para sánscrito y similitud
difflib. - Estrategias:
smart | keyword | semantic | balanced.
- Semántica: embeddings con
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 entranslate_textdentro 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
Dockerfileincluido; 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; opcionalchapter_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úsquedaPOST /api/search/advanced→ filtrosPOST /api/context→ contexto por párrafoPOST /api/translate→ traducción (EN/IT→ES con M2M100) y guardado en QdrantGET /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_hubsentencepiecefaltante → revisarequirements.txtCould 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"
- 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
- 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
- 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)
- 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
- 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
- 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
- Clona el repo, crea
.envcon Qdrant y selecciona Python 3.10 en VS Code. pip install -r requirements.txty arranca conuvicorn app.main:app --reload.- Haz login en HF (
huggingface-cli login) y añade el remotohf. git push hf mainpara reconstruir el Space (Docker).
📝 Licencia
MIT (ajústala si el cliente necesita otra).