Preparar el entorno
Instala una versión compatible de Python, comprueba que Git esté disponible y crea un entorno virtual dedicado para mantener aisladas las dependencias de VoxCPM.
Guía de configuración local
Cómo instalar voxcpm en tu equipo local
Para instalar voxcpm, primero necesitas un entorno Python compatible, los archivos del proyecto y los recursos del modelo requeridos por el repositorio. Sigue la secuencia siguiente para pasar de un espacio de trabajo vacío a una instalación local funcional, sin omitir las comprobaciones que evitan la mayoría de los errores.
- FundamentosPython y el aislamiento de paquetes son los dos primeros requisitos para una instalación fiable de VoxCPM.
- SecuenciaLa instalación consta de 4 etapas: preparar el entorno, clonar el repositorio, instalar las dependencias y verificar el modelo.
- Solución de problemasLa falta de archivos del modelo, los paquetes incompatibles y los límites de memoria de la GPU causan la mayoría de los fallos al iniciar VoxCPM.
- MantenimientoUn entorno virtual limpio facilita la actualización de VoxCPM sin afectar a otros proyectos.
Pasos numerados
Sigue este proceso de cuatro etapas para instalar VoxCPM de forma reproducible. Mantén la terminal en el directorio del proyecto siempre que un comando haga referencia a un archivo local.
Obtener los archivos del proyecto
Clona el repositorio oficial de VoxCPM o descarga su archivo de código fuente. Después, entra en la carpeta del proyecto antes de ejecutar los comandos de instalación.
Instalar las dependencias
Activa el entorno e instala la lista de dependencias indicada en el README del repositorio. Si tienes previsto usar una GPU, instala primero una versión compatible del framework.
Ejecutar una prueba de verificación
Carga el ejemplo incluido o el punto de entrada de inferencia, confirma que los recursos del modelo estén disponibles y comprueba que el audio generado se guarde en la ubicación de salida prevista.
Requisitos previos
Consulta estos elementos antes de instalar Voxcpm. Los elementos obligatorios evitan una configuración fallida; los opcionales mejoran el rendimiento o facilitan la solución de problemas.
Obligatorio
Un sistema operativo de 64 bits con una terminal o shell funcional
Usa el shell adecuado para tu sistema operativo.
Obligatorio
Python instalado en una versión compatible con el repositorio actual de Voxcpm
Confírmalo con python --version o python3 --version.
Obligatorio
Git instalado y disponible en la línea de comandos
Confírmalo con git --version.
Obligatorio
Suficiente espacio en disco para los archivos de origen, los paquetes de Python, los pesos del modelo y el audio generado
Los recursos del modelo pueden requerir mucho más espacio que el propio repositorio.
Obligatorio
Un entorno virtual dedicado para Voxcpm
venv u otro gestor de entornos es adecuado.
Opcional
Una GPU NVIDIA compatible y una pila de CUDA configurada
Útil para la aceleración cuando sea compatible con las instrucciones actuales de Voxcpm.
Opcional
Un breve audio o texto de prueba para la verificación
Es preferible usar un ejemplo incluido cuando el repositorio proporcione uno.
-
1
voxcpm github
Usa la página de GitHub de Voxcpm para revisar el árbol de código fuente, las notas de instalación y las instrucciones de uso actuales.
-
2
voxcpm huggingface
La página de VoxCPM en Hugging Face es útil cuando necesitas identificar los recursos publicados del modelo o los detalles de carga.
-
3
voxcpm comfyui
Consulta la guía de VoxCPM para ComfyUI si tu configuración prevista coloca el modelo dentro de un flujo de trabajo basado en nodos.
Errores comunes y soluciones
Los problemas de instalación suelen deberse al entorno y no al modelo en sí. Compara el estado en el que se produce el error con la configuración esperada y aplica primero la solución más pequeña.
- Antes de la configuración
- Configuración verificada
Usa el README del repositorio como fuente de referencia para los comandos específicos de cada versión.
Consejos avanzados
Elige el panel que coincida con tu configuración. Estas prácticas facilitan reproducir, actualizar y diagnosticar VoxCPM en diferentes máquinas.
Mantén predecible la instalación en CPU
Un entorno que use solo la CPU es útil para comprobar que el repositorio, los paquetes de Python y la ruta de carga del modelo son correctos antes de investigar problemas específicos de la GPU. Espera tiempos de inferencia más largos y comienza con una prueba pequeña en lugar de un lote grande.
- Usa un entorno virtual nuevo para cada experimento importante.
- Ejecuta primero el ejemplo documentado más pequeño.
- Guarda la salida de la terminal al diagnosticar un error de carga o de dependencias.
Verifica la pila de aceleración
Para la inferencia en GPU, considera el framework de Python, el entorno de ejecución de CUDA, el controlador y la memoria disponible como una única cadena de compatibilidad. Instala la compilación del framework recomendada por las instrucciones actuales de VoxCPM en lugar de copiar un comando de un tutorial antiguo.
- Comprueba que el sistema operativo pueda detectar la GPU antes de iniciar VoxCPM.
- Mantén alineadas las versiones del controlador y del framework.
- Reduce el tamaño de la carga de trabajo si el proceso se detiene por un error de memoria insuficiente.
Haz que la instalación sea repetible
Una vez que VoxCPM funcione, registra la versión de Python, el comando de instalación de dependencias, la revisión del repositorio y la ubicación de los recursos del modelo. Este breve registro de configuración hace que las actualizaciones futuras sean más seguras y ayuda a reproducir el mismo resultado en otra máquina.
- Mantén el proyecto en su propio directorio.
- No mezcles paquetes de proyectos de voz no relacionados en el mismo entorno.
- Actualiza el repositorio y las dependencias de forma deliberada, un cambio a la vez.
Ejecuta tu primera prueba de VoxCPM
El siguiente paso más seguro es hacer una pequeña prueba documentada desde el directorio del proyecto. Abre el espacio de trabajo de VoxCPM, sigue las instrucciones actuales del repositorio y verifica el resultado antes de cambiar la configuración avanzada.
- Empieza por el README actual del repositorio.
- Haz que la primera prueba sea pequeña y fácil de revisar.
- Guarda un entorno que funcione antes de experimentar.
Preguntas frecuentes del tutorial
Estas respuestas abordan las dudas prácticas sobre la instalación que motivan esta guía y centran el proceso de configuración en las comprobaciones más importantes.
Crea un entorno de Python dedicado, obtén los archivos del proyecto VoxCPM del repositorio oficial e instala las dependencias indicadas en su README actual. Después, obtén los archivos necesarios del modelo y ejecuta el ejemplo de verificación más sencillo del repositorio.
Git es la forma más sencilla de clonar el repositorio de VoxCPM, pero no es la única opción. Si Git no está disponible, puedes obtener los archivos del proyecto mediante un archivo comprimido del código fuente; aun así, debes seguir las instrucciones del repositorio sobre dependencias y modelos.
Sí. Un entorno virtual mantiene los paquetes de VoxCPM separados de otras aplicaciones de Python y facilita eliminar o recrear la instalación. También te ayuda a determinar si un error se debe a VoxCPM o a un paquete global no relacionado.
Una GPU puede mejorar el rendimiento de la inferencia cuando está configurado el sistema de aceleración compatible, pero los requisitos de hardware exactos dependen de la implementación y del ejemplo actuales. Una configuración con CPU puede servir para validar la instalación, aunque podría funcionar más lentamente y requerir pruebas más ligeras.
Comprueba la versión de Python, confirma que el entorno virtual esté activo y compara los paquetes instalados con las instrucciones actuales del repositorio. Después, verifica que los archivos del modelo estén presentes y que tu hardware tenga suficiente memoria disponible antes de cambiar las opciones de configuración.