Este guia demonstra como implantar este modelo de forma rápida e sem complicações usando Python 3.10 e a biblioteca Gradio para criar uma interface web intuitiva.

1. Preparação do Ambiente e Obtenção do Projeto

Para garantir o funcionamento correto, é essencial configurar um ambiente adequado.

1.1 Requisitos do Sistema e Python

O projeto foi construído e testado especificamente para Python 3.10. Versões diferentes podem causar conflitos de dependências.

• Sistema Operacional: Linux (Ubuntu, CentOS), macOS ou Windows via WSL2.
• Versão Python: 3.10.x (Obrigatório).
• Memória RAM: Mínimo de 4GB livres.
• Armazenamento: Cerca de 2GB para os arquivos do modelo.

Para verificar sua versão atual do Python, execute no terminal:

python3 -V
# ou
python -V

Caso não esteja na versão 3.10, utilize ferramentas como pyenv ou conda para isolar o ambiente.

1.2 Configuração de Arquivos e Código do Modelo

Primeiro, obtenha o código-fonte do projeto e coloque-o em um diretório de trabalho, por exemplo, ~/projetos/gerador_chunlian.

O passo mais crítico é o posicionamento dos pesos do modelo. O script principal espera encontrar os arquivos do modelo em um caminho absoluto específico. Recomenda-se colocar os arquivos baixados do ModelScope no seguinte diretório:

/root/modelos_ai/damo/chunlian_base

Se você não tem permissão de escrita em /root, precisará ajustar a constante de caminho no código-fonte. Para uma implantação "zero configuração", mantenha a estrutura de diretórios acima.

A estrutura final esperada é:

/root/modelos_ai/damo/chunlian_base/
    ├── configuration.json
    ├── model_weights.bin
    └── vocab.txt

~/projetos/gerador_chunlian/
    ├── main_app.py
    ├── dependencies.txt
    ├── run.sh

2. Instalação de Dependências e Inicialização

2.1 Configurando Pacotes Python

Navegue até a pasta do projeto e instale as bibliotecas necessárias listadas no arquivo de dependências.

cd ~/projetos/gerador_chunlian

# Instalação usando um mirror para acelerar o download
pip3 install -r dependencies.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

As principais bibliotecas incluem gradio (versão 6 ou superior), transformers e torch.

2.2 Iniciando o Serviço Web

Você pode eniciar o aplicativo através de um script de shell pré-configurado ou diretamente via comando Python.

Opção 1: Script de Inicialização

# Garante permissões de execução
chmod +x run.sh

# Executa o script
./run.sh

Opção 2: Execução Direta

python3 main_app.py

Ao executar, o terminal exibirá:

Running on local URL:  http://127.0.0.1:7860

3. Utilizando o Gerador de Couplets

Acesse http://localhost:7860 no navegador. A interface é direta:

1. Entrada de Texto: Insira duas palavras temáticas, como "saúde" ou "fortuna".
2. Botão de Envio: Aciona a inferência do modelo.
3. Saída: Exibe o couplet gerado (linha superior, inferior e horizontal).
4. Copiar: Botão para transferir o resultado para a área de transferência.

Experimante palavras relacionadas a festas, zodíaco (ex: "Dragão"), ou termos modernos para ver a criatividade da IA.

4. Resolução de Problemas Comuns

• Erro de Carregamento do Modelo: Verifique se o caminho /root/modelos_ai/damo/chunlian_base está correto e se os arquivos de peso estão completos. Ajuste as permissões de leitura se necessário.
• Porta em Uso: Se a porta padrão estiver ocupada, altere o parâmetro server_port na função launch() no arquivo main_app.py para outra, como 8080.
• Conflitos de Versão: Sempre use Python 3.10. Se a instalação falhar, atualize o pip (pip install --upgrade pip) ou use ambientes virtuais.
• Lentidão ou Falta de Memória: O primeiro carregamento exige mais recursos. Certifique-se de ter mais de 4GB de RAM livre. Se a geração demorar mais de 10 segundos, considere fazer upgrade do hardware.