Docs / Instalação e solução de problemas
Solução de problemas
Meu Mac vai rodar isso? Memória, chip, disco e tempos de renderização de cada Mac Apple Silicon, em uma só página.
Quando o Phosphene recusa uma renderização, ele diz por quê e o que fazer. Estas são as mensagens que as pessoas realmente veem. Para problemas durante a Instalação ou a Atualização (uma linha FATAL error: no Pinokio, falta de espaço em disco), veja Instalar, atualizar e espaço em disco.
Memória e o nível deste Mac
O indicador de saúde no cabeçalho mostra a memória num relance; clique nele para ver as linhas Nível, Memória, Auxiliar, Modelos, Fila e Renderização. Clique em Nível para ver o que este Mac consegue rodar.
- “Helper killed by the OS - out of memory” (o auxiliar foi encerrado pelo sistema por falta de memória): o macOS interrompeu a renderização. Feche apps que usam muita memória (navegadores, Slack, o Simulador de iOS) e tente de novo, ou troque a Qualidade para Veloz, que usa cerca de metade da memória.
- “Image pre-flight: … needs a N GB Mac”: esse motor de imagem não cabe neste Mac. Em Macs com 16 GB ou menos, o Auto usa o FLUX.2 [klein] 4B quando o motor definido em Ajustes exige um Mac maior, sem alterar os Ajustes. Isso exige uma renderização sem imagens de referência: remova as referências para o Auto poder usar o Klein, ou escolha um motor mais leve em Ajustes. ”… needs ~N GB free” significa que o motor cabe, mas a memória está em uso no momento; essa verificação agora leva em conta a memória que o macOS consegue liberar e as necessidades reais de memória do Auto.
- “Training needs at least 24 GB of memory”: o treinamento de personagem não pode rodar neste Mac.
Hailuo H3 em um Mac de 16 a 60 GB
O motor completo do H3 precisa de 60 GB. A partir de 16 GB, ele roda no motor compacto Q8, que é montado no seu Mac uma única vez (abaixo de 36 GB ele lê o modelo do seu disco enquanto renderiza):
- H3 ainda não instalado: no Pinokio, abra Phosphene na barra lateral e clique em Install Hailuo H3 (second video engine, ~75 GB). A instalação monta o motor compacto sozinha no final (cerca de 5 minutos a mais).
- H3 instalado, motor compacto ausente, com a mensagem “Hailuo H3 runs on this Mac - on its reduced-RAM lane … it is not built here yet”: clique em Build Hailuo H3 compact engine na mesma barra lateral (~5 minutos, sem download).
As duas entradas ficam na barra lateral enquanto o painel está rodando.
Feito isso, escolha Ajustes → Modelo Hailuo H3 → Automático ou Compacto. Abaixo de 16 GB, o H3 não está disponível: renderize no LTX, que atende a todos os modos.
Um modelo ou complemento não foi baixado
- “Enhance needs its language model, Gemma 3 (8.1 GB)” e o mesmo para os adaptadores: em uma instalação nova, eles são baixados em segundo plano depois do primeiro Start. A mensagem diz se o download está em andamento, na fila ou esperando espaço em disco; Download now o baixa na hora.
- “Extend needs the LTX-2.5 High add-on (the Q8 model), which isn’t downloaded on this Mac yet”: o mesmo vale para Quadros-chave e para a qualidade Alta. Instale-o na janela Modelos (clique no indicador de saúde e depois em Modelos).
- “Upscale & Face Fix needs the LTX-2.5 Pixel Spatial Upscaler adapter”: baixe-o na janela Modelos e renderize de novo.
- “Stopped before rendering - the model weights are incomplete”: um download foi interrompido. Abra a janela Modelos e retome-o. Em Ajustes, Verificar arquivos do modelo confere cada arquivo e oferece baixar de novo os que estiverem danificados.
A atualização para logo no início
Em alguns Macs, a Atualização do Pinokio em versões anteriores à 4.19.7 parava no primeiro segundo: o terminal do Pinokio lia as palavras “error:” no próprio texto de comando da Atualização como uma falha (#114). O Pinokio executa o script de Atualização da versão que você já tem, então a correção só passa a valer depois de uma atualização.
Atualize uma vez de dentro do Phosphene: clique em Atualizar agora no aviso de atualização (ou na etiqueta de versão no cabeçalho), espere até ele dizer que a atualização terminou e reinicie. Ou abra um terminal na pasta do Phosphene (~/pinokio/api/<your Phosphene folder>), execute git pull e clique em Update no Pinokio de novo: ele então roda o script novo, já corrigido. Depois disso, o botão funciona.
“Click Update”: um motor mais antigo que o painel
“This install’s vendored engine predates LTX-2.5’s text encoder … Click Update - and if the first click only moves the panel, click it once more.”
O painel foi atualizado, mas o motor por baixo dele não. Clique em Update na barra lateral do Phosphene no Pinokio. Se nada parecer mudar, clique uma segunda vez: uma atualização iniciada por uma versão antiga atualiza primeiro a si mesma. No caso do H3, “the installed Hailuo H3 runner is behind this panel” significa: execute Install Hailuo H3 de novo, e todo peso que já está no disco é mantido.
Se você atualizou e o painel ainda se comporta como a versão antiga, ele ainda está rodando o código antigo. A etiqueta de versão no cabeçalho passa então a dizer Reiniciar o Phosphene: clique nela, ou clique em Stop e depois em Start no Pinokio.
O watchdog da GPU
“the macOS GPU watchdog killed a Metal command buffer”: o próprio macOS interrompeu uma tarefa da GPU que durou demais. É uma interrupção no nível do driver, não um relatório de bug do Phosphene, e é mais comum em Macs M1 e M2. O Phosphene renderiza o mesmo job de novo uma vez, na hora, em passos curtos de GPU (pedaços menores de trabalho da GPU, um pouco mais lentos), e lembra o tamanho: a próxima renderização neste Mac começa em passos curtos, e a linha da Fila avisa. Se o macOS interrompe mesmo em passos curtos, esse tamanho fica pausado neste Mac por 24 horas (ou até a próxima atualização) e o cartão oferece Tentar com tamanho menor. Se continuar acontecendo, a mensagem leva ao issue do GitHub, onde o chip, a versão do macOS e o log de falha ajudam mais.
Uma execução de treinamento de personagem falhou
“training exited with code 1”: o treinador parou antes de terminar. Veja o motivo real na aba Registros: uma interrupção por falta de memória (use um Mac com mais RAM, ou uma predefinição menor, se houver), um download de treinamento do LTX-2.3 ausente (o cartão de verificação prévia da aba Treinar o oferece) ou um timeout na codificação de uma legenda muito longa. O treinamento com menos de 24 GB sempre falha: esse Mac não consegue rodá-lo.
O painel diz que está offline
“Phosphene offline”, e clicar em Gerar não faz nada: o processo do painel não está respondendo. Nada do que você digitava se perde: o prompt fica como você o deixou, e a página se reconecta e retoma a fila sozinha assim que o painel voltar a rodar. Inicie-o pela barra lateral do Phosphene no Pinokio se ele não voltar em alguns segundos.
A fila se pausou sozinha
“Queue paused: the last N renders failed the same way”: depois de três renderizações seguidas falharem com o mesmo problema, o Phosphene para de gastar o resto da fila com algo que uma nova tentativa não resolve. Corrija a causa que a mensagem aponta e clique em Retomar; ou em Limpar fila para descartar o resto e recomeçar.
A fila depois de reiniciar
Reiniciar o painel retoma a fila: uma fila que estava pausada quando o painel parou volta a rodar sozinha, e o log informa isso.
Lendo o log
A aba Registros no painel inferior mostra o log de renderização. Quando uma renderização morre, a última linha que começa com step: nomeia a etapa que ela alcançou: essa linha é a coisa mais útil para incluir em um relatório. O Terminal do Pinokio mostra a mesma saída.
Relatar um problema
O botão do bug no cabeçalho abre Relatar um bug. Escreva uma ou duas frases em O que aconteceu? (são necessários pelo menos 10 caracteres, pois o log não sabe dizer o que você viu); ele preenche a versão, os detalhes do seu Mac e o log recente, com as linhas de erro à frente das rotineiras, e abre um issue do GitHub em uma nova aba para você concluir: nada é enviado até você enviar lá. Os issues ficam em github.com/mrbizarro/phosphene/issues.
Fonte: webapp/docs/troubleshooting.md no repositório público. Revisado para este site antes da publicação. Traduzido do original em inglês. Sugerir uma edição.