Prepare o ambiente
Instale uma versão compatível do Python, confirme que o Git está disponível e crie um ambiente virtual dedicado para manter as dependências do Voxcpm isoladas.
Guia de configuração local
Como instalar o voxcpm na sua máquina local
Como instalar o voxcpm começa com um ambiente Python compatível, os arquivos do projeto e os recursos do modelo exigidos pelo repositório. Siga a sequência abaixo para passar de um espaço de trabalho vazio a uma configuração local funcional sem ignorar as verificações que evitam a maioria dos erros.
- FundamentosPython e o isolamento de pacotes são os dois primeiros requisitos para uma configuração confiável do Voxcpm.
- SequênciaA instalação segue 4 etapas: preparar, clonar, instalar as dependências e verificar o modelo.
- Solução de problemasArquivos de modelo ausentes, pacotes incompatíveis e limites de memória da GPU causam a maioria das falhas ao iniciar o Voxcpm.
- ManutençãoUm ambiente virtual limpo facilita a atualização do Voxcpm sem interferir em outros projetos.
Etapas numeradas
Use este fluxo de quatro etapas para uma instalação reproduzível do Voxcpm. Mantenha o terminal no diretório do projeto sempre que um comando fizer referência a um arquivo local.
Obtenha os arquivos do projeto
Clone o repositório oficial do Voxcpm ou baixe o arquivo do código-fonte e, em seguida, entre na pasta do projeto antes de executar os comandos de instalação.
Instale as dependências
Ative o ambiente e instale a lista de dependências especificada no README do repositório. Se você planeja usar uma GPU, instale primeiro a versão compatível do framework.
Execute um teste de verificação
Carregue o exemplo incluído ou o ponto de entrada de inferência, confirme que os recursos do modelo estão disponíveis e verifique se o áudio gerado é gravado no local de saída esperado.
Pré-requisitos
Confira estes itens antes de instalar o VoxCPM. Os itens obrigatórios evitam falhas na instalação; os opcionais melhoram o desempenho ou facilitam a solução de problemas.
Obrigatório
Um sistema operacional de 64 bits com um terminal ou shell funcional
Use o shell adequado ao seu sistema operacional.
Obrigatório
Python instalado em uma versão compatível com o repositório atual do VoxCPM
Confirme com python --version ou python3 --version.
Obrigatório
Git instalado e disponível na linha de comando
Confirme com git --version.
Obrigatório
Espaço em disco suficiente para os arquivos-fonte, pacotes Python, pesos do modelo e áudio gerado
Os arquivos do modelo podem exigir muito mais espaço do que o próprio repositório.
Obrigatório
Um ambiente virtual dedicado ao VoxCPM
venv ou outro gerenciador de ambientes é adequado.
Opcional
Uma GPU NVIDIA compatível e uma configuração CUDA funcional
Útil para acelerar o processamento quando houver suporte nas instruções atuais do VoxCPM.
Opcional
Uma entrada curta de áudio ou texto para verificação
É preferível usar um exemplo incluído, caso o repositório forneça um.
-
1
voxcpm GitHub
Use a página do VoxCPM no GitHub para consultar a estrutura dos arquivos-fonte, as instruções de instalação e as orientações atuais de uso.
-
2
voxcpm Hugging Face
A página do Voxcpm no Hugging Face é útil quando você precisa identificar os assets publicados do modelo ou detalhes de carregamento.
-
3
voxcpm comfyui
Consulte o guia do Voxcpm para ComfyUI se a configuração pretendida colocar o modelo em um fluxo de trabalho baseado em nós.
Erros comuns e soluções
Os problemas de instalação geralmente vêm do ambiente, e não do próprio modelo. Compare o estado com falha com a configuração esperada e aplique primeiro a menor correção possível.
- Antes da configuração
- Configuração verificada
Use o README do repositório como fonte de referência para comandos específicos de cada versão.
Dicas avançadas
Escolha o painel que corresponde à sua configuração. Essas práticas tornam o Voxcpm mais fácil de reproduzir, atualizar e diagnosticar em diferentes máquinas.
Mantenha a instalação de CPU previsível
Um ambiente exclusivo para CPU é útil para verificar se o repositório, os pacotes Python e o caminho de carregamento do modelo estão corretos antes de investigar problemas específicos da GPU. Espere tempos de inferência mais longos e comece com um teste pequeno em vez de um lote grande.
- Use um ambiente virtual novo para cada experimento importante.
- Execute primeiro o menor exemplo documentado.
- Salve a saída do terminal ao diagnosticar um erro de carregamento ou de dependência.
Verifique a pilha de aceleração
Para inferência em GPU, trate o framework Python, o runtime do CUDA, o driver e a memória disponível como uma única cadeia de compatibilidade. Instale a versão do framework recomendada pelas instruções atuais do Voxcpm em vez de copiar um comando de um tutorial antigo.
- Verifique se o sistema operacional consegue detectar a GPU antes de iniciar o Voxcpm.
- Mantenha as versões do driver e do framework alinhadas.
- Reduza o tamanho da carga de trabalho se o processo parar com um erro de falta de memória.
Torne a instalação reproduzível
Quando o Voxcpm estiver funcionando, registre a versão do Python, o comando de instalação das dependências, a revisão do repositório e o local dos assets do modelo. Esse breve registro da configuração torna as atualizações futuras mais seguras e ajuda a reproduzir o mesmo resultado em outra máquina.
- Mantenha o projeto em seu próprio diretório.
- Não misture pacotes de projetos de voz não relacionados no mesmo ambiente.
- Atualize o repositório e as dependências de forma deliberada, uma alteração por vez.
Execute seu primeiro teste do Voxcpm
O próximo passo mais seguro é realizar um pequeno teste documentado a partir do diretório do projeto. Abra o ambiente de trabalho do Voxcpm, siga as instruções atuais do repositório e verifique o resultado antes de alterar configurações avançadas.
- Comece pelo README atual do repositório.
- Mantenha o primeiro teste pequeno e fácil de inspecionar.
- Salve um ambiente funcional antes de fazer experimentos.
Perguntas frequentes do tutorial
Estas respostas abordam a questão prática de instalação por trás deste guia e mantêm o processo de configuração concentrado nas verificações mais importantes.
Crie um ambiente Python dedicado, obtenha os arquivos do projeto Voxcpm no repositório oficial e instale as dependências listadas no README atual. Em seguida, obtenha os recursos necessários do modelo e execute o menor exemplo de verificação do repositório.
O Git é a maneira mais simples de clonar o repositório do Voxcpm, mas não é a única opção. Se o Git não estiver disponível, um arquivo compactado do código-fonte pode fornecer os arquivos do projeto; ainda assim, você precisará seguir as instruções do repositório sobre dependências e modelos.
Sim. Um ambiente virtual mantém os pacotes do Voxcpm separados de outros aplicativos Python e facilita a remoção ou recriação da configuração. Ele também ajuda a identificar se um erro pertence ao Voxcpm ou a um pacote global não relacionado.
Uma GPU pode melhorar o desempenho da inferência quando a pilha de aceleração compatível está configurada, mas os requisitos exatos de hardware dependem da implementação e do exemplo atuais. Uma configuração com CPU pode ser útil para validar a instalação, embora possa ser mais lenta e exigir testes mais leves.
Verifique a versão do Python, confirme se o ambiente virtual está ativo e compare os pacotes instalados com as instruções atuais do repositório. Em seguida, verifique se os recursos do modelo estão presentes e se o hardware tem memória disponível suficiente antes de alterar as opções de configuração.