O Pipeline Meshy e a Vestimenta Que Quebrou a Estimativa de Pose

3D generativo só é tão bom quanto o pipeline que transforma um prompt em um ativo pronto para o runtime. A RakuAI construiu um que sobrevive a endpoints de fornecedor que desaparecem, travamentos por Unicode e o atrito que os demos nunca mostram.

O pipeline de ativos é uma das peças chatas-mas-fundamentais do engine. É a coisa que transforma a ideia de um designer (“quero vinte inimigos para o pacote de tower defense”) em uma pasta de ativos 3D texturizados, com rig e com LOD, que o runtime consegue carregar. Nas últimas seis semanas, o pipeline que vem fazendo esse trabalho é o Meshy.ai, conectado através de um script de sete estágios que vive em scripts/meshy_asset_pipeline.py no repositório do runtime.

Neste sábado de manhã, a ponte v1 entre o pipeline Meshy e o formato de pacote do SDK está estável o suficiente para eu escrever o que aprendemos. Três coisas. Nenhuma delas está na documentação da API.

O que os sete estágios realmente fazem

Em ordem, para cada ativo:

1. Geração texto-para-3D em modo de prévia.
2. Geração de mapas de textura PBR: albedo, metálico, rugosidade, normal.
3. Consulta e download do LOD0.
4. Criação da tarefa de remesh contra a API v1.
5. Consulta e download do remesh do LOD1.
6. Organização dos arquivos de ativo em disco.
7. Montagem do pacote de conteúdo.

O pipeline conduz um ativo até o fim, depois passa para o próximo. Não processa em lote. O motivo de não processar em lote veio da terceira lição abaixo, de forma dolorosa.

Lição um: vestimentas quebram a estimativa de pose

A saída texto-para-3D do Meshy é boa para uma ampla gama de designs humanoides. Esqueleto, soldado, cavaleiro, mago de braços à mostra. O pipeline faz o rig deles, o rig funciona, o ativo é entregue.

Não é bom para humanoides com vestimentas longas e pesadas. O pacote de conteúdo de RPG bateu nisso no Sprint 2. Quatro ativos que deveriam ter recebido rig de forma limpa falharam na extração de silhueta durante a estimativa de pose. Dois eram esperados (slime e wolf_enemy não são humanoides, o estimador de pose não deveria encontrar braços neles). Dois foram uma surpresa: mage_hero e blacksmith. Ambos humanoides. Ambos falharam.

O modo de falha é a silhueta. O estimador de pose do Meshy olha o contorno renderizado do modelo para encontrar membros. Um mago em uma túnica longa não tem pernas visíveis na silhueta, então não há pontos-chave de perna para ancorar um esqueleto. Um ferreiro com avental não tem costura visível de torso entre peito e quadril, então a articulação da coluna é adivinhada errada. O modelo está bom. O rig está errado.

A correção no pipeline é registrar a falha, salvar a geometria sem rig, e sinalizar uma flag no manifesto do ativo dizendo “este precisa de uma passagem manual de rig.” A correção nos prompts é especificar “roupas justas, membros expostos” no prompt de texto para qualquer humanoide que precise de rig automático. A correção mais duradoura está do lado do Meshy, e não cabe a nós fazê-la.

Entre treze gêneros, a taxa de falha é desigual. Tower defense tem uma falha de rig em cinco. Platformer tem uma em seis. RPG tem quatro em onze, e três dessas quatro são geometria de roupa. A lição generaliza: quando um modelo generativo falha, a falha geralmente não é aleatória, e o modo de falha te diz algo sobre os dados de treinamento com os quais o modelo foi construído.

Lição dois: Unicode derruba qualquer coisa que direcione stdout para um arquivo

A facção Oni no pacote de RPG usa nomes de personagens em japonês. 風 para vento, 雷 para trovão, 金剛 para diamante. Esses são os nomes de ativo nos envios de tarefa ao Meshy. O pipeline roda em segundo plano, redireciona stdout para um arquivo de log, e analisa o log depois para ver quais ativos tiveram sucesso.

Na primeira vez que os ativos Oni rodaram, todos e cada um deles falharam. O erro era um UnicodeEncodeError vindo do stdout do Python. A codificação padrão nas máquinas de build é ASCII para stdout quando stdout não é um TTY. Os caracteres japoneses não são ASCII. O comando print trava antes mesmo de o ativo ser enviado ao Meshy.

A correção é uma linha no script de lançamento: PYTHONIOENCODING=utf-8. Uma vez que essa variável de ambiente é definida, os comandos print funcionam e os ativos são gerados.

A lição é mais antiga do que eu: qualquer coisa que direcione Unicode através de um pipeline com stdout redirecionado precisa ter a codificação definida explicitamente. Dois dias perdidos com um problema documentado há vinte anos. Registrado no diário de comportamento. Corrigido no lançador. Não corrigido pelo Meshy porque não é problema do Meshy corrigir.

Lição três: APIs de fornecedores desaparecem

No meio do Sprint 2, o endpoint /remesh da v2 do Meshy começou a retornar 404. Não para um ativo específico. Para toda chamada.

O estágio de remesh é o que transforma o LOD0 (alto polígono, caro de renderizar) em LOD1 (baixo polígono, barato de renderizar). Sem remesh, os ativos são entregues apenas com LOD0. Renderizam bem nas máquinas de desenvolvimento e matam a taxa de quadros no alvo dos óculos de AR.

Não sei se o endpoint foi descontinuado, bloqueado atrás de um plano de nível superior, movido sem redirecionamento, ou temporariamente fora do ar. A documentação do Meshy ainda faz referência a ele. Chamadas a ele retornam 404. O pipeline não pode esperar o fornecedor descobrir qual é o caso.

A correção está em meshy_asset_pipeline.py, no estágio de remesh. Um try/except em volta da chamada de remesh. Em caso de falha, registra o ativo como apenas-LOD0, grava esse fato no manifesto do ativo, e continua com o resto do pipeline. Todo ativo tem LOD0. Alguns têm LOD1. O pacote é entregue de qualquer jeito.

A lição é a que todo projeto que depende de uma API de fornecedor aprende eventualmente: a API da qual você depende não é sua, e ela pode mudar debaixo dos seus pés, e a única defesa é a degradação graciosa. Agora nós temos isso.

Onde o pipeline está agora

Oito dos treze gêneros completos. Space shooter, puzzle, card battle, runner, platformer, racing, tower defense, RPG. Cinco restantes (esportes, simulação, sandbox, luta, MMO-lite) na fila.

O orçamento de créditos é a vitória surpresa. A estimativa para o Sprint 2 era de cerca de 510 créditos entre as duas facções do gênero. O gasto real ficou de 25 a 35 por cento abaixo da estimativa, consistentemente. Isso dá ao programa espaço suficiente para avançar pelos cinco gêneros restantes sem uma conversa sobre orçamento.

A ponte v1 que chegou no início deste mês, scripts/generate_rakupack.py com vinte e quatro testes de conformidade, é o que torna tudo isso endereçável a partir do lado do SDK. Um desenvolvedor usando o SDK não precisa saber se um ativo veio do Meshy ou de um pipeline modelado à mão. O formato de pacote é o contrato. O pipeline Meshy produz pacotes. O SDK carrega pacotes.

Por que estou registrando isso

Duas razões.

A primeira é que as três lições acima são o tipo de atrito que não aparece em demos de fornecedor e não aparece em páginas de marketing. Vestimentas e estimativa de pose. Unicode e stdout. Remesh e 404. Se você está avaliando um fornecedor de 3D generativo e lê isso e pensa “é esse o tipo de coisa que eu gostaria de saber antes de me comprometer com isso”, então o texto cumpriu seu papel.

A segunda é que o pipeline agora está estável o suficiente para que a próxima conversa não seja “o Meshy funciona para nós”. É “o que queremos que a biblioteca de ativos seja”. Essa é uma conversa de designer, não de engenharia. O lado de engenharia fez seu trabalho ao sair do caminho.

Oito gêneros concluídos. Cinco pela frente. O pipeline sobrevive a um 404. O pipeline sobrevive a um caractere japonês. O pipeline ainda não sobrevive a uma vestimenta longa. Sábado bem aproveitado.