renato97/cbcren2026
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor: streamline core service and clean workspace

Browse Source
This commit is contained in:
renato97
2025-12-16 23:09:48 +00:00
parent 9fb01d5c22
commit b26248076b
18 changed files with 157 additions and 1649 deletions
Download Patch File Download Diff File Expand all files Collapse all files

279
README.md
View File

@@ -1,194 +1,129 @@
# Nextcloud AI Service v8 Final
# Nextcloud AI Service v8
Sistema completo de procesamiento de audio, PDF y generación de resúmenes colaborativos mediante 3 modelos de IA.
## 🚀 Características Principales
### 🤖 Sistema Unificado de 3 IAs
- **GPT-OSS-120B**: Extracción de puntos clave mediante DeepInfra API
- **Claude CLI**: Desarrollo de resúmenes integrales mediante Z.ai API
- **Gemini CLI**: Formato y estilo final mediante CLI de Google
### 📁 Procesamiento de Archivos
- **Audio**: Transcripción con Whisper y generación de resúmenes
- **PDF**: OCR avanzado y conversión a documentos editables
- **Documentos**: Generación de resúmenes automáticos
- **Sincronización**: Integración completa con Nextcloud via WebDAV
### 🎯 Características Técnicas
- **Docker Multi-etapa**: Optimizado para producción
- **GPU CUDA 12.1**: Aceleración por hardware NVIDIA
- **CLI Tools**: Claude CLI y Gemini CLI para máxima compatibilidad
- **Unificación**: Sistema colaborativo que genera un único documento final
## 🛠️ Instalación
### Requisitos
- Docker y Docker Compose
- NVIDIA GPU con drivers CUDA 12.1+
- 16GB+ RAM recomendado
- 20GB+ espacio en disco
### Configuración
1. **Clonar el repositorio**
```bash
git clone https://gitea.cbcren.online/ren/nextcloud-ai-v8-final.git
cd nextcloud-ai-v8-final
```
2. **Configurar variables de entorno**
```bash
cp .env.example .env
# Editar .env con tus credenciales
```
3. **Iniciar servicios**
```bash
docker-compose up -d
```
## ⚙️ Configuración de Variables de Entorno
### Nextcloud
```env
NEXTCLOUD_URL=https://tu-nextcloud.com
NEXTCLOUD_USER=tu_usuario
NEXTCLOUD_PASS=tu_contraseña
```
### APIs de IA
```env
GEMINI_API_KEY=tu_gemini_key
DEEPINFRA_API_KEY=tu_deepinfra_key
ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic
ANTHROPIC_AUTH_TOKEN=tu_z_ai_token
```
### Notificaciones (Opcional)
```env
TELEGRAM_TOKEN=tu_bot_token
TELEGRAM_CHAT_ID=tu_chat_id
```
## 📊 Arquitectura del Sistema
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.
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ GPT-OSS-120B │───▶│ Claude CLI │───▶│ Gemini CLI │
│ (DeepInfra) │ │ (Z.ai) │ │ (Google) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ Sistema Unificado │
│ (Documento Final Único) │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Nextcloud Service │
│ (Sincronización WebDAV) │
└─────────────────────────────────────────────────────────────────┘
┌─────────────┐ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐
│ Nextcloud │───▶│ Whisper │───▶│ Claude (Z.ai)│───▶│ Gemini (CLI │
│ Audios/PDFs │ │ Transcribe │ │ Bullet + │ │ + API) │
└─────────────┘ └─────────────┘ │ Resumenes │ │ Formato final │
└──────┬───────┘ └──────┬───────┘
│ │
▼ ▼
Markdown / DOCX / PDF Dashboard
```
## 🔧 Uso
## 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.
### Procesamiento Automático
1. Sube archivos de audio a la carpeta `Audios` en Nextcloud
2. El sistema detecta automáticamente y genera resúmenes
3. Los documentos finales se guardan en `Documentos`
4. Las versiones Markdown se sincronizan con `Notes`
## 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
```
### Monitoreo
- **Logs**: `docker-compose logs -f app`
- **Estado**: `docker-compose ps`
- **Telegram**: Notificaciones automáticas (si está configurado)
## 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).
## 🎨 Salida del Sistema
El sistema genera documentos unificados con:
1. **Puntos Clave**: Extraídos por GPT-OSS-120B
2. **Resumen Integral**: Desarrollado por Claude CLI (500+ palabras)
3. **Quiz de Evaluación**: 10 preguntas de opción múltiple
4. **Metadatos**: Información del proceso colaborativo
## 🐳 Docker
### Estructura de Contenedores
- **app**: Servicio principal con soporte GPU
- **ollama**: Servidor Ollama para modelos locales
### Personalización
### Instalación de las CLIs externas
```bash
# Reconstruir contenedores
docker-compose build
# Reiniciar servicios
docker-compose restart
# Ver logs en tiempo real
docker-compose logs -f app
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.
## 🚨 Troubleshooting
## 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=...
### Problemas Comunes
GEMINI_API_KEY=...
DEEPINFRA_API_KEY=...
ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic
ANTHROPIC_AUTH_TOKEN=...
1. **Error de permisos Claude CLI**
- Solución: `CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS=1` en docker-compose.yml
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
```
2. **Timeout en procesamiento**
- Aumentar `MODEL_TIMEOUT_SECONDS` en .env
## 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`.
3. **Problemas de GPU**
- Verificar drivers NVIDIA y CUDA 12.1+
- Comprobar `nvidia-smi`
## 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.
4. **Error de APIs**
- Verificar keys y endpoints en .env
- Comprobar límites de las APIs
## 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.
## 📈 Métricas y Optimización
## 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.
### Rendimiento
- **Tiempo de procesamiento**: ~2-5 minutos por audio de 5min
- **Uso de VRAM**: ~8-12GB con modelos GPU
- **Calidad de resúmenes**: Formato académico con análisis profundo
## 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.
### Optimización
- **VRAM Management**: Limpieza automática cada 5 minutos
- **Error Handling**: Reintentos automáticos con backoff exponencial
- **Timeout Configurable**: Adaptarse a diferentes cargas de trabajo
## 🔐 Seguridad
- **API Keys**: Almacenadas como variables de entorno
- **WebDAV**: Autenticación básica con HTTPS
- **CLI Tools**: Configuración segura sin permisos de root
- **Redes**: Aislamiento de contenedores Docker
## 🤝 Contribuciones
1. Fork del repositorio
2. Crear rama feature
3. Commit con cambios descriptivos
4. Pull Request para revisión
## 📄 Licencia
MIT License - Ver archivo LICENSE para detalles
## 📞 Soporte
Para problemas o preguntas:
- Crear issue en el repositorio
- Revisar logs del sistema
- Verificar documentación de variables de entorno
## 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. |
---
**Versión**: 8.0 Final
**Última Actualización**: Septiembre 2024
**Estado**: Producción estable
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! 💡