Contribuir para o PEFT

Temos prazer em aceitar contribuições para o PEFT. Se você planeja contribuir, leia este documento para tornar o processo o mais tranquilo possível.

Discuta e obtenha aprovação antes de abrir um PR

Antes de abrir um pull request (incluindo um rascunho), abra ou encontre uma issue em huggingface/peft e discuta sua contribuição proposta. Se já existir uma issue e alguém já estiver trabalhando nela, tiver declarado a intenção de trabalhar nela ou tiver um PR aberto, você não deve enviar um PR separado. Aguarde a aprovação explícita de um mantenedor do PEFT ou de um membro da Hugging Face para a proposta. Se você abrir uma issue, mantenha o comprimento e a complexidade da descrição proporcionais à complexidade da issue. Frequentemente, uma descrição curta com um reproduzível é mais valiosa do que uma descrição longa.

Um comentário de aprovação contém a mensagem /peft-triage approved. Ele pode, adicionalmente, indicar o nome do contribuidor designado, por exemplo /peft-triage approved username ou /peft-triage approved @username. Abrir um PR para uma issue à qual você não foi designado resultará no fechamento do referido PR.

Vincule a issue aberta e aprovada na descrição do seu PR usando #123, huggingface/peft#123 ou https://github.com/huggingface/peft/issues/123. Como exceção, os mantenedores podem designar discussões específicas de longa duração que podem ser referenciadas por sua URL completa do GitHub sem um comentário de aprovação separado. Se você referenciar várias issues ou discussões, uma referência válida é suficiente.

Um fluxo de trabalho automatizado verifica as PRs em busca de problemas ou discussões abertas aprovados. PRs sem uma referência válida são fechadas automaticamente com uma explicação. Você pode obter a aprovação do problema, atualizar a descrição da PR e reabrir a mesma PR; por favor, não crie uma substituta. Se você acredita que sua PR foi fechada incorretamente, pingue os mantenedores na PR.

O bot de itens obsoletos independentes ainda pode fechar itens inativos, mesmo que estejam rotulados como triaged. Se você sentir que os mantenedores ignoraram sua contribuição, pode enviá-los um ping, mas não antes de duas semanas de inatividade.

Instalação

Siga estas etapas para começar a contribuir:

1. Faça o fork do repositório clicando no botão “Fork” na página do repositório. Isso cria uma cópia do código na sua conta de usuário do GitHub.

2. Clone seu fork para o disco local e adicione o repositório base como um remote. O comando a seguir pressupõe que você tenha sua chave SSH pública enviada ao GitHub. Consulte o guia a seguir para mais informações.

   Copiado

   git clone git@github.com:<your Github handle>/peft.git
   cd peft
   git remote add upstream https://github.com/huggingface/peft.git

3. Crie um novo branch para conter suas alterações de desenvolvimento e faça isso para cada novo PR em que você trabalhar.

   Comece sincronizando seu ramo main com o ramo upstream/main (mais detalhes na Documentação do GitHub):

   Copiado

   git checkout main
   git fetch upstream
   git merge upstream/main

   Depois que o seu ramo main estiver sincronizado, crie um novo ramo a partir dele:

   Copiado

   git checkout -b a-descriptive-name-for-my-changes

   Não trabalhe no ramo main.

4. Configure um ambiente de desenvolvimento executando o seguinte comando em um ambiente conda ou virtual que você criou para trabalhar nesta biblioteca:

   Copiado

   pip install -e ".[test]"

   (Se o PEFT já estiver instalado no ambiente virtual, remova-o com pip uninstall peft antes de reinstalá-lo.)

Se você está começando a criar um pull request, siga o guia Creating a pull request do GitHub.

Testes e verificações de qualidade de código

Independentemente do tipo de contribuição (a menos que se trate apenas de documentação), você deve executar testes e verificações de qualidade de código antes de criar um PR para garantir que sua contribuição não quebre nada e siga os padrões do projeto.

Executando testes e verificações

Fornecemos um Makefile para executar os testes necessários. Execute o código abaixo para o teste de unidade:

make test

Execute um dos comandos a seguir para apenas verificar ou verificar e corrigir a qualidade e o estilo do código:

make quality  # just check
make style  # check and fix

Executar make quality também verifica se todos os métodos/classes da API pública do PEFT (ou seja, tudo que é mencionado em peft.__all__) estão mencionados na documentação. Esses erros não podem ser corrigidos por make style; é necessário garantir que os novos itens da API pública sejam documentados na documentação para corrigir esse erro.

Você também pode configurar o pre-commit para executar essas correções automaticamente como hooks de commit do Git.

$ pip install pre-commit
$ pre-commit install

Executar todos os testes pode levar um tempo, então, durante o desenvolvimento, pode ser mais eficiente executar apenas testes específicos para a sua alteração, por exemplo, via:

pytest tests/<test-file-name> -k <name-of-test>

Isso deve terminar muito mais rápido e permitir uma iteração mais ágil.

Adicionando testes

Para um guia geral sobre como adicionar novos testes, consulte tests/README.md.

Se sua alteração é específica para uma configuração de hardware (por exemplo, requer CUDA), verifique tests/test_gpu_examples.py e tests/test_common_gpu.py para ver se faz sentido adicionar testes lá. Se sua alteração puder ter um efeito no salvamento e carregamento de modelos, execute os testes com a flag --regression para acionar os testes de regressão.

PRs obsoletos

Pode acontecer de, enquanto você trabalha em seu PR, a base de código subjacente mude devido a outras alterações que foram mescladas. Se isso acontecer – especialmente quando há um conflito de mesclagem – por favor, atualize seu ramo com as alterações mais recentes. Isso pode ser uma mesclagem ou um rebase, e faremos squash e merge do PR assim que ele estiver pronto. Evite force pushes para facilitar as revisões.

Descrição do PR

Ao abrir um PR, forneça uma boa descrição da alteração que você está propondo e faça referência à issue aprovada, conforme descrito acima. Se estiver relacionado a outras issues ou PRs, faça referência a eles também. Fornecer uma boa descrição não apenas ajuda os revisores a revisar seu código de forma melhor e mais rápida, mas também pode ser usado posteriormente (como base) para a mensagem de commit, o que ajuda na manutenção de longo prazo do projeto.

Mantenha o comprimento e a complexidade da descrição do PR de acordo com a alteração. Não precisamos de dez parágrafos de explicação para uma mudança trivial de uma linha. Não repita o que é óbvio ao olhar para o diff (por exemplo, “Corrigi o erro de digitação em ‘foobaar’”).

Se o seu código faz algumas alterações não triviais, também pode ser uma boa ideia adicionar comentários ao código para explicar essas alterações. Por exemplo, se você teve que iterar na sua implementação várias vezes porque a maneira mais óbvia não funcionou, é um bom indicativo de que um comentário de código é necessário.

Se relevante, indique como você testou a alteração, por exemplo, mostrando o comando de teste pytest ou o código de reprodução.

Feedback do revisor

Após enviar seu PR, um mantenedor geralmente fornecerá feedback em alguns dias. Se você não receber nenhum feedback em duas semanas, é possível que seu PR tenha passado despercebido; nesse caso, sinta-se à vontade para chamar os mantenedores, mas não antes disso.

Se o revisor fornecer comentários em linha, não os marque como resolvidos se você os tiver endereçado. Deixe esses comentários abertos, pois eles ajudam o revisor a retomar seu trabalho.

Depois de tratar do feedback dos revisores, avise o revisor para que ele saiba que a PR está pronta para revisão.

Correções

Forneça uma descrição das circunstâncias que levaram ao bug. Se já existir uma issue, faça um link para ela (por exemplo, “Resolves #12345”).

Idealmente, quando uma correção de bug é fornecida, ela deve ser acompanhada por um teste para o bug. O teste deve falhar com o código atual e passar com a correção. Adicione um comentário ao teste que faça referência à issue ou ao PR. Sem um teste, é mais difícil prevenir regressões no futuro.

Melhorias na documentação

Temos prazer em receber correções para links quebrados e documentação ausente ou pouco clara. Cuidar dos exemplos, garantindo que estejam atualizados e funcionando corretamente neste ambiente em rápida evolução, também é muito apreciado.

Por favor, evite enviar pull requests que apenas corrigem erros de digitação, pois eles geralmente geram mais trabalho do que economizam. Essas alterações são melhores quando combinadas com correções mais substanciais (como corrigir links quebrados ou estender/atualizar a documentação).

Adicione um novo método de ajuste fino PEFT

Novos métodos de ajuste fino eficientes em parâmetros são desenvolvidos o tempo todo. Se você deseja adicionar um novo e promissor método ao PEFT, siga estas etapas.

1. Se você não for o autor do artigo original, verifique se já existem implementações e confirme com os autores que eles não pretendem enviar um PR por conta própria.
2. Abra uma issue de proposta e aguarde a aprovação explícita, conforme descrito acima, antes de iniciar o trabalho de integração principal listado abaixo.
3. Verifique os commits recentes para novos métodos PEFT sendo adicionados, para usar como inspiração.
4. Após a aprovação da proposta, pode ser útil abrir um PR em rascunho cedo, assim que o método basicamente funcionar e os primeiros testes passarem, e então solicitar feedback. Refira a issue aprovada na descrição do PR em rascunho.

Integração central de um novo método PEFT

• Abra uma issue em huggingface/peft e obtenha aprovação explícita antes de investir muito trabalho.
• Vincule a fonte do método, geralmente o artigo final ou outra referência primária estável. Queremos evitar trabalhos que ainda estão em revisão, pois a implementação deve ser estável.
• Adicione uma nova entrada PeftType em src/peft/utils/peft_types.py.
• Crie um novo pacote de tuner em src/peft/tuners/ com os arquivos necessários para o seu método (tipicamente: config.py, model.py, layer.py e __init__.py).
• Registre o método no __init__.py do tuner com register_peft_method(...).
• Exporte a nova configuração/modelo de src/peft/tuners/__init__.py e src/peft/__init__.py.
• Se o método precisar de módulos de destino padrão para modelos do Transformers, adicione o mapeamento em src/peft/utils/constants.py.
• Adicione o método à matriz de testes em tests/test_custom_models.py, pois são os testes mais abrangentes e rápidos. Verifique se os testes passam com pytest tests/test_custom_models.py -k <method-name> -v e corrija as falhas, se houver.
• Execute verificações de estilo/qualidade com make style antes de enviar.
• Na descrição do PR, explique o método, inclua o link para o artigo, resuma os tradeoffs e liste o que foi adicionado.

PR completo para adicionar um novo método PEFT

• Certifique-se de que os argumentos de configuração específicos do método estejam bem nomeados e explicados, sem presumir que o usuário conhece o artigo a fundo.
• Siga as convenções de nomenclatura e codificação do PEFT.
• Verifique se você não cometeu acidentalmente alterações não relacionadas, por exemplo, o formatador de código alterando arquivos não relacionados.
• Se algumas escolhas de implementação não forem triviais, documente-as com um comentário de código.
• Complete a suíte de testes completa (test_config.py, test_decoder_models.py, etc.) adicionando o método PEFT à matriz de testes. Certifique-se de que os testes sejam aprovados.
• Adicione a documentação em docs/source/package_reference/ com uma breve explicação, link para o paper, um trecho de uso e blocos de autodoc. Explante os prós e contras em comparação com outros métodos, como LoRA. Registre essa página de documentação em docs/source/_toctree.yml.
• Adicione um exemplo executável em examples/ (pode ser uma cópia de um exemplo existente), com um breve README.md.
• Verifique os benchmarks em method_comparison/ e adicione as configurações de experimento para o seu novo método. Este é um bom lugar para fazer uma verificação de sanidade de que o método PEFT treina conforme o esperado. Inclua uma ou duas configurações de benchmark razoáveis (uma padrão, uma otimizada para o benchmark).
• Recomendado: Adicione suporte a quantização genérica. Em vez de ter que adicionar explicitamente os tipos de camadas de quantização para cada método de quantização, suporte a quantização genérica. Como exemplo, verifique como isso é implementado no BOFT. Estenda o https://github.com/huggingface/peft/blob/main/tests/test_quantization.py adicionando seu método PEFT lá. Peça ajuda aos mantenedores, se necessário.

Fazendo alterações em métodos PEFT existentes

Se você fizer uma alteração em um método PEFT que possa potencialmente alterar suas saídas, invalidando assim checkpoints já treinados, precisamos tomar precauções extras. Consulte a descrição em https://github.com/huggingface/peft/blob/main/.ai/skills/peft-method-changes/SKILL.md para mais detalhes. As instruções ali são destinadas tanto a humanos quanto a IAs.

Adicionar outros recursos

Primeiro, abra uma issue no GitHub com uma proposta para adicionar o novo recurso e aguarde a aprovação explícita, conforme descrito acima. Dessa forma, você pode discutir com os mantenedores se faz sentido adicionar o recurso antes de gastar muito tempo implementando-o.

Novos recursos devem, em geral, ser acompanhados de testes e documentação ou exemplos. Sem estes, os usuários terão dificuldade em descobrir seu novo recurso incrível.

As alterações no código devem ser implementadas de forma compatível com versões anteriores. Por exemplo, o código existente deve continuar funcionando da mesma maneira após a incorporação do recurso.