Cómo Instalar OpenCluely con Reconocimiento de Voz Local Optimizado

Aprende a desplegar OpenCluely Community Edition con transcripción Whisper local, aceleración GPU NVIDIA CUDA opcional y respuesta multimodal.

Aprender a instalar OpenCluely con voz local optimizada es una de las mejores alternativas para los desarrolladores e ingenieros que buscan un asistente multimodal de código abierto sin depender de servicios de transcripción en la nube de pago. Mediante la integración local de OpenAI Whisper, OpenCluely permite procesar comandos y consultas por voz directamente en tu hardware, canalizando únicamente el texto resultante a la API de Google Gemini.

Esta guía práctica abarca la instalación completa de la variante comunitaria optimizada, la configuración del entorno Python con PyTorch/CUDA, el soporte para fallbacks en CPU y la resolución de problemas frecuentes en Windows, Linux y macOS.

📌 Declaración de la Edición Comunitaria:
Esta variante se distribuye de forma independiente desde el repositorio público de configurowebmax/OpenCluely. Las mejoras fueron introducidas al proyecto original mediante el PR #29. No constituye un release oficial de TechyCSR, pero conserva los créditos, la licencia abierta y la atribución original del autor.

Requisitos del Sistema para OpenCluely Local

Para garantizar una ejecución fluida de Whisper y el cliente de OpenCluely, asegúrate de contar con las siguientes herramientas y especificaciones de hardware:

Componente	Mínimo Requerido	Recomendado
Sistema Operativo	Windows 10, Ubuntu 20.04+, macOS 12+	Windows 11 / Linux (64-bits)
Memoria RAM	8 GB de RAM	16 GB de RAM o superior
Entorno de Desarrollo	Git, Node.js 18 LTS, Python 3.10 x64	Node.js 20 LTS, Python 3.11 x64
Aceleración por Hardware	CPU x86_64 / ARM (Apple Silicon)	GPU NVIDIA con 2 GB – 4 GB+ VRAM (CUDA)
Clave de API	Una API Key personal de Gemini obtenida en Google AI Studio.

Instalación Paso a Paso en Windows

1. Verificar Herramientas de Entorno

Abre tu terminal de Git Bash y confirma que las dependencias base estén correctamente añadidas al PATH de tu sistema:

git --version node --version npm --version python --version python -m pip --version

2. Clonar el Repositorio Comunitario

Obtén la rama optimizada feat/configurable-local-whisper directamente desde GitHub:

git clone --branch feat/configurable-local-whisper --single-branch https://github.com/configurowebmax/OpenCluely.git cd OpenCluely git branch --show-current

3. Desplegar el Script de Automatización

Ejecuta el script de aprovisionamiento. Este comando configurará las dependencias de Node.js, preparará el entorno aislado de Python (.venv-whisper) y descargará las bibliotecas de reconocimiento de voz:

./setup.sh --ci --no-run npm start

Configuración Recomenda de Speech Recognition

Una vez iniciada la interfaz de OpenCluely, dirígete al menú de Settings → Speech Recognition y establece los siguientes parámetros para equilibrar rendimiento y precisión:

Parámetro	Valor Recomendado	Notas del Sistema
Speech Provider	`Local Whisper`	Procesamiento 100% privado en tu equipo.
Whisper Model	`small`	Ocupa ~461 MB en disco. Ideal para 2 GB VRAM o CPU.
Whisper Language	`auto` (o `es`)	Detección automática del idioma de entrada.
Compute Device	`Auto`	Aplica aceleración CUDA si está disponible; si no, usa CPU.
Capture Mode	`Manual start/stop`	Evita cortes prematuros al hablar.

Aceleración por GPU NVIDIA CUDA (Opcional)

Si dispones de una tarjeta gráfica NVIDIA, puedes habilitar la aceleración por hardware para reducir el tiempo de transcripción a milisegundos. Verifica el estado de tus controladores abriendo PowerShell:

nvidia-smi

Para actualizar las bibliotecas de PyTorch con soporte CUDA en el entorno virtual de OpenCluely, utiliza el ejecutador de Python asignado al entorno:

.\.venv-whisper\Scripts\python.exe -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

Verifica que PyTorch reconozca tu GPU ejecutando:

.\.venv-whisper\Scripts\python.exe -c "import torch; print('CUDA Disponible:', torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'Modo CPU')"

Despliegue en Linux y macOS

Despliegue en Ubuntu / Debian

sudo apt update sudo apt install -y git python3 python3-venv python3-pip ffmpeg sox libgtk-3-0 libnotify4 libnss3 libxss1 libxtst6 libasound2 git clone --branch feat/configurable-local-whisper --single-branch https://github.com/configurowebmax/OpenCluely.git cd OpenCluely chmod +x setup.sh ./setup.sh --ci --install-system-deps --no-run npm start

Despliegue en macOS (Apple Silicon & Intel)

xcode-select --install git clone --branch feat/configurable-local-whisper --single-branch https://github.com/configurowebmax/OpenCluely.git cd OpenCluely chmod +x setup.sh ./setup.sh --ci --no-run npm start

Nota: En macOS la ejecución se realiza mediante la CPU; asegúrate de conceder permisos de micrófono en System Settings → Privacy & Security.

Resolución de Problemas Frecuentes (Troubleshooting)

🔍 Errores Comunes de Diagnóstico:

CUDA Out of Memory: Si tu GPU tiene 2 GB o 4 GB de VRAM, evita usar el modelo turbo o large. Cambia a small o base.
El Micrófono no captura audio: Asegúrate de que las aplicaciones de escritorio tengan permiso de acceso al micrófono en la configuración de privacidad de tu sistema operativo.
Error de Clave de Gemini (HTTP 429): Este código responde a una restricción de cuotas de la API de Google, no a un problema de la transcripción local con Whisper.
Python redirige a Microsoft Store: Crea el entorno virtual forzando el ejecutable directo mediante py -3.11 -m venv .venv-whisper.

Si requieres implementar soluciones avanzadas de inteligencia artificial, modelos locales o desarrollo a medida, puedes consultar nuestro artículo sobre despliegue de arquitecturas web y software personalizado.