QUICKSTART.md

🚀 Guía de Inicio Rápido - Aliah-Plus

Instalación en 3 Pasos

1. Clonar el Repositorio

git clone https://github.com/tu-usuario/aliah-plus.git
cd aliah-plus

2. Instalar Dependencias

Opción A: Con virtualenv

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
playwright install chromium

Opción B: Con Docker

docker build -t aliah-plus .
docker run -p 8000:8000 aliah-plus

3. Ejecutar

python app.py

El servidor estará disponible en: http://localhost:8000

Documentación interactiva: http://localhost:8000/docs

---

Uso Básico con cURL

Búsqueda Completa

curl -X POST "http://localhost:8000/api/v1/search?threshold=0.75&enable_ocr=true&enable_cross_ref=true" \
  -F "file=@persona.jpg"

Solo Extracción OCR

curl -X POST "http://localhost:8000/api/v1/ocr-extract" \
  -F "file=@miniatura.jpg"

Comparar Dos Rostros

curl -X POST "http://localhost:8000/api/v1/compare" \
  -F "file1=@persona1.jpg" \
  -F "file2=@persona2.jpg"

---

Uso con Python

import requests

# Búsqueda
with open('persona.jpg', 'rb') as f:
    response = requests.post(
        'http://localhost:8000/api/v1/search',
        files={'file': f},
        params={
            'threshold': 0.75,
            'enable_ocr': True,
            'enable_cross_ref': True
        }
    )

results = response.json()
print(f"Encontrados: {results['total_verified']} resultados verificados")

for match in results['matches'][:5]:
    print(f"• {match['domain']} - Similitud: {match['similarity']:.2%}")

---

Despliegue en Hugging Face Spaces

1. Crear nuevo Space: https://huggingface.co/spaces
2. Seleccionar "Docker" como SDK
3. Subir todos los archivos del proyecto
4. El Dockerfile se ejecutará automáticamente
5. Tu Space estará en: https://huggingface.co/spaces/tu-usuario/aliah-plus

---

Verificar Instalación

# Health check
curl http://localhost:8000/health

# Debería retornar:
{
  "status": "healthy",
  "version": "1.0.0",
  "components": {
    "face_processor": "ok",
    "embedding_engine": "ok",
    "stealth_search": "ok",
    "ocr_extractor": "ok",
    "cross_referencer": "ok",
    "vector_db": "ok"
  }
}

---

Ejemplos Incluidos

# Ejecutar ejemplos interactivos
python examples/usage_example.py

---

Troubleshooting

Error: "No se detectó rostro"

• Asegúrate de que la imagen tenga un rostro visible y bien iluminado
• La imagen debe tener al menos 100x100 píxeles
• El rostro debe estar frontal (no de perfil)

Error: "Playwright not installed"

playwright install chromium
playwright install-deps

Error: "CUDA not available"

• El sistema funcionará con CPU, pero será más lento
• Para usar GPU, instala: pip install torch torchvision --extra-index-url https://download.pytorch.org/whl/cu118

Error en Hugging Face Spaces

• Verifica que el Dockerfile esté correctamente configurado
• El puerto debe ser 7860 (no 8000)
• Revisa los logs en la pestaña "Logs" del Space

---

Configuración Avanzada

Edita config.yaml para ajustar:

• Umbrales de similitud
• Motores de búsqueda habilitados
• Configuración de OCR
• Timeouts y rate limits

---

Soporte

• Issues: https://github.com/tu-usuario/aliah-plus/issues
• Discussions: https://github.com/tu-usuario/aliah-plus/discussions
• Email: support@aliah-plus.dev

---

🎉 ¡Listo! Ya puedes usar Aliah-Plus