130 lines
6.4 KiB
Markdown
130 lines
6.4 KiB
Markdown
# Nextcloud AI Service v8
|
|
|
|
Servicio unificado que escucha automáticamente tu Nextcloud, descarga audios y PDFs, los procesa con Whisper + 3 modelos de IA y publica resúmenes enriquecidos junto con un dashboard en tiempo real.
|
|
|
|
```
|
|
┌─────────────┐ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
│ Nextcloud │───▶│ Whisper │───▶│ Claude (Z.ai)│───▶│ Gemini (CLI │
|
|
│ Audios/PDFs │ │ Transcribe │ │ Bullet + │ │ + API) │
|
|
└─────────────┘ └─────────────┘ │ Resumenes │ │ Formato final │
|
|
└──────┬───────┘ └──────┬───────┘
|
|
│ │
|
|
▼ ▼
|
|
Markdown / DOCX / PDF Dashboard
|
|
```
|
|
|
|
## Principales capacidades
|
|
- **Pipeline único**: descarga desde Nextcloud vía WebDAV, transcribe con Whisper, resume con Claude + Gemini y clasifica automáticamente.
|
|
- **Dashboard integrado**: panel Flask (http://localhost:5000) para ver archivos, reprocesar o limpiar estados con un click.
|
|
- **Diseño GPU-first**: Docker + CUDA 12.1 con PyTorch optimizado; limpieza agresiva de VRAM cuando los modelos están ociosos.
|
|
- **Alertas opcionales**: soporte Telegram y WebDAV retries para operaciones largas.
|
|
- **Código limpio**: sin Ollama ni servicios secundarios; sólo lo esencial para escalar y mantener.
|
|
|
|
## Estructura mínima
|
|
```
|
|
cbc/
|
|
├─ Dockerfile
|
|
├─ docker-compose.yml
|
|
├─ main.py # Servicio principal + loop de monitoreo
|
|
├─ dashboard.py # Flask dashboard reutilizando la lógica de main.py
|
|
├─ templates/index.html # UI del dashboard
|
|
├─ requirements.txt
|
|
└─ README.md
|
|
```
|
|
|
|
## Requisitos
|
|
- NVIDIA GPU con drivers CUDA 12.1+ y `nvidia-container-toolkit` si usas Docker.
|
|
- Python 3.10+ (el Dockerfile usa 3.10) y Node.js ≥ 20 para las CLI externas.
|
|
- Claves activas para:
|
|
- **Z.ai (Claude CLI)** → `ANTHROPIC_AUTH_TOKEN` y `ANTHROPIC_BASE_URL`.
|
|
- **Google Gemini** (CLI o API) → `GEMINI_API_KEY`.
|
|
- **DeepInfra GPT-OSS-120B** → `DEEPINFRA_API_KEY`.
|
|
- Servidor Nextcloud accesible por WebDAV (usuario, contraseña y URL remota).
|
|
|
|
### Instalación de las CLIs externas
|
|
```bash
|
|
npm install -g @anthropic-ai/claude-code
|
|
npm install -g @google/gemini-cli
|
|
```
|
|
Recuerda exportar las mismas variables de entorno (`ANTHROPIC_*`, `GEMINI_API_KEY`) para que las CLIs compartan credenciales con el servicio.
|
|
|
|
## Configuración
|
|
1. Copia el ejemplo `.env` (no versionado) y completa:
|
|
```env
|
|
NEXTCLOUD_URL=http://tu-servidor:8080/remote.php/webdav
|
|
NEXTCLOUD_USER=...
|
|
NEXTCLOUD_PASS=...
|
|
|
|
GEMINI_API_KEY=...
|
|
DEEPINFRA_API_KEY=...
|
|
ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic
|
|
ANTHROPIC_AUTH_TOKEN=...
|
|
|
|
TELEGRAM_TOKEN=... (opcional)
|
|
TELEGRAM_CHAT_ID=... (opcional)
|
|
```
|
|
2. Crea los directorios utilizados por los volúmenes (si no existen):
|
|
```bash
|
|
mkdir -p downloads resumenes_docx
|
|
```
|
|
|
|
## Ejecución local (sin Docker)
|
|
```bash
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install --upgrade pip
|
|
pip install -r requirements.txt
|
|
python3 main.py
|
|
```
|
|
- El dashboard se expone en `http://localhost:5000`.
|
|
- Los registros viven en `logs/service.log`.
|
|
|
|
## Ejecución con Docker
|
|
```bash
|
|
docker compose up -d --build
|
|
docker compose logs -f app
|
|
```
|
|
El único servicio (`nextcloud_ai_app`) ya expone el dashboard y comparte `downloads/` y `resumenes_docx/` como volúmenes.
|
|
|
|
## Flujo del pipeline
|
|
1. **Monitoreo**: cada `POLL_INTERVAL` segundos se listan nuevas entradas en Nextcloud (`Audios`, `Pdf`, `Textos`...).
|
|
2. **Descarga y preproceso**: los archivos se guardan en `downloads/` con normalización y sanitización de nombres.
|
|
3. **Transcripción (Whisper)**: modelo `medium` optimizado para español (soporte GPU).
|
|
4. **Resúmenes colaborativos**:
|
|
- Claude CLI genera bullet points por lotes y resumen integral.
|
|
- Gemini CLI/API aplica formato final y estilo consistente.
|
|
5. **Clasificación y renombrado**: se detectan temáticas (Historia, Contabilidad, Gobierno, Otras Clases) + topics para nombrar archivos inteligentemente.
|
|
6. **Entrega**: se generan `.md`, `.docx`, `.pdf` y se suben de nuevo a Nextcloud.
|
|
7. **Dashboard**: refleja estado (procesados/pendientes), permite reprocesar o resetear registros, y sirve descargas locales.
|
|
|
|
## Dashboard en detalle
|
|
- **Vista general**: tarjetas con totales, filtros por origen (local/WebDAV) y buscador instantáneo.
|
|
- **Acciones rápidas**:
|
|
- `Procesar`: envía el archivo nuevamente al pipeline.
|
|
- `Resetear`: elimina la marca de procesado para forzar un reprocesamiento automático.
|
|
- `Descargar`: enlaces directos a TXT/MD/DOCX/PDF disponibles.
|
|
- **API**:
|
|
- `GET /api/files` → listado.
|
|
- `POST /api/reprocess` → reprocesa.
|
|
- `POST /api/mark-unprocessed` → limpia estado.
|
|
- `GET /api/refresh` → sincroniza.
|
|
- `GET /health` → healthcheck.
|
|
|
|
## Buenas prácticas operativas
|
|
- **CUDA libre**: el servicio libera VRAM si los modelos quedan ociosos; revisa el log para ver las limpiezas agresivas.
|
|
-.**Telegram**: usa `ERROR_THROTTLE_SECONDS` para evitar spam en errores repetidos.
|
|
- **Respaldo**: `processed_files.txt` guarda el historial de todo lo procesado; respáldalo si cambias de servidor.
|
|
- **Extensibilidad**: si necesitas nuevos formatos o pasos, agrega funciones en `main.py` reutilizando `ThreadPoolExecutor` y los helpers existentes.
|
|
|
|
## Troubleshooting rápido
|
|
| Problema | Fix |
|
|
| --- | --- |
|
|
| Claude o Gemini devuelven error de permisos | Exporta `CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS=1` (ya se envía al contenedor). |
|
|
| No aparecen archivos en el dashboard | Verifica credenciales Nextcloud y `logs/service.log`. |
|
|
| Tiempo de espera alto en WebDAV | Ajusta `HTTP_TIMEOUT` y `WEBDAV_MAX_RETRIES` en `.env`. |
|
|
| GPU ocupada constantemente | Reduce `MODEL_TIMEOUT_SECONDS` o baja el tamaño del modelo Whisper. |
|
|
|
|
---
|
|
|
|
La meta de esta versión es mantener el proyecto ágil y escalable: menos archivos, menos servicios y una sola fuente de verdad. Si necesitas habilitar nuevas integraciones (por ejemplo, más modelos o destinos), añade módulos dedicados dentro de `main.py` o expórtalos a un paquete propio manteniendo este núcleo ligero. ¡Felices resúmenes! 💡
|