PEFT documentation

Contribuir a PEFT

PEFT

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.21.0).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Contribuir a PEFT

Nos complace aceptar contribuciones a PEFT. Si planeas contribuir, lee esto para que el proceso sea lo más fluido posible.

Discutir y obtener aprobación antes de abrir una PR

Antes de abrir una pull request (incluida una borrador), abre o busca un issue en huggingface/peft y discute tu contribución propuesta. Si ya existe un issue y alguien ya está trabajando en él, ha declarado su intención de trabajar en él o tiene una PR abierta, no debes enviar una PR separada. Espera a que un mantenedor de PEFT o un miembro de Hugging Face apruebe explícitamente la propuesta. Si abres un issue, mantén la longitud y la complejidad de la descripción en proporción con la complejidad del issue. A menudo, una descripción corta con un reproductor es más valiosa que una descripción larga.

Un comentario de aprobación contiene el mensaje /peft-triage approved. Puede indicar además el nombre del contribuyente asignado, por ejemplo /peft-triage approved username o /peft-triage approved @username. Abrir una PR para un problema al que no estás asignado provocará el cierre de dicha PR.

En la descripción de tu PR, vincula el problema abierto y aprobado usando #123, huggingface/peft#123 o https://github.com/huggingface/peft/issues/123. Como excepción, los mantenedores pueden designar discusiones específicas de larga duración que se pueden referenciar por su URL completa de GitHub sin un comentario de aprobación separado. Si haces referencia a varios problemas o discusiones, una referencia válida es suficiente.

Un flujo de trabajo automatizado verifica que las PR tengan problemas abiertos o discusiones aprobados. Las PR sin una referencia válida se cierran automáticamente con una explicación. Puedes obtener la aprobación del problema, actualizar la descripción de la PR y reabrir la misma PR; por favor, no crees una de reemplazo. Si crees que tu PR se cerró incorrectamente, notifica a los mantenedores en la PR.

El bot de elementos obsoletos independientes aún puede cerrar elementos inactivos, incluso si están etiquetados como triaged. Si sientes que los mantenedores han pasado por alto tu contribución, puedes enviarles un mensaje, pero no antes de que hayan transcurrido dos semanas de inactividad.

Instalación

Sigue estos pasos para empezar a contribuir:

Crea una bifurcación del repositorio haciendo clic en el botón ‘Fork’ en la página del repositorio. Esto crea una copia del código bajo tu cuenta de usuario de GitHub.
Clona tu bifurcación en tu disco local y añade el repositorio base como un remoto. El siguiente comando asume que tienes tu clave SSH pública cargada en GitHub. Consulta la siguiente guía para obtener más información.
```
git clone git@github.com:<your Github handle>/peft.git
cd peft
git remote add upstream https://github.com/huggingface/peft.git
```
Crea una nueva rama para guardar los cambios de tu desarrollo y hazlo para cada nueva PR en la que trabajes.

Comience sincronizando su rama main con la rama upstream/main (más detalles en la documentación de GitHub):
```
git checkout main
git fetch upstream
git merge upstream/main
```
Una vez que la rama main esté sincronizada, crea una rama nueva a partir de ella:
```
git checkout -b a-descriptive-name-for-my-changes
```
No trabajes en la rama main.
Configura un entorno de desarrollo ejecutando el siguiente comando en un entorno conda o virtual que hayas creado para trabajar en esta biblioteca:
```
pip install -e ".[test]"
```
(Si PEFT ya estaba instalado en el entorno virtual, elimínalo con pip uninstall peft antes de volver a instalarlo.)

Si es nuevo en la creación de una pull request, siga la guía Creating a pull request de GitHub.

Pruebas y comprobaciones de calidad del código

Independientemente del tipo de contribución (a menos que solo se trate de la documentación), debes ejecutar pruebas y comprobaciones de calidad del código antes de crear una PR para asegurarte de que tu contribución no rompa nada y cumpla con los estándares del proyecto.

Ejecución de pruebas y comprobaciones

Proporcionamos un Makefile para ejecutar las pruebas necesarias. Ejecute el siguiente código para la prueba de unidad:

make test

Ejecuta una de las siguientes opciones para solo comprobar o para comprobar y corregir la calidad y el estilo del código:

make quality  # just check
make style  # check and fix

Ejecutar make quality también comprueba si todos los métodos/clases de la API pública de PEFT (es decir, todo lo que se menciona en peft.__all__) están mencionados en la documentación. Estos errores no se pueden corregir con make style; es necesario asegurarse de documentar los nuevos elementos de la API pública en la documentación para corregir este error.

También puedes configurar pre-commit para ejecutar estas correcciones automáticamente como hooks de commit de Git.

$ pip install pre-commit
$ pre-commit install

Ejecutar todas las pruebas puede llevar un tiempo, por lo que durante el desarrollo puede ser más eficiente ejecutar solo las pruebas específicas de tu cambio, por ejemplo, mediante:

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

Esto debería terminar mucho más rápido y permitir una iteración más veloz.

Añadiendo pruebas

Para una guía general sobre cómo agregar nuevas pruebas, consulte tests/README.md.

Si tu cambio es específico de una configuración de hardware (p. ej., requiere CUDA), revisa tests/test_gpu_examples.py y tests/test_common_gpu.py para ver si tiene sentido añadir pruebas allí. Si tu cambio podría afectar al guardado y la carga de modelos, ejecuta las pruebas con la bandera --regression para activar las pruebas de regresión.

PRs obsoletos

Puede ocurrir que, mientras trabajas en tu PR, la base de código subyacente cambie debido a otras modificaciones que se hayan fusionado. Si eso sucede, especialmente cuando hay un conflicto de fusión, actualiza tu rama con los últimos cambios. Esto puede ser una fusión o un rebase, y fusionaremos la PR con squash cuando esté lista. Evita las force pushes para facilitar las revisiones.

Descripción de la PR

Al abrir un PR, proporciona una descripción clara del cambio que estás proponiendo y referencia el problema aprobado tal como se describió anteriormente. Si está relacionado con otros problemas o PRs, refiérete a ellos también. Proporcionar una buena descripción no solo ayuda a los revisores a revisar tu código de manera más eficiente y rápida, sino que también puede utilizarse más adelante (como base) para el mensaje de commit, lo cual facilita el mantenimiento a largo plazo del proyecto.

Mantén la longitud y la complejidad de la descripción de la PR en consonancia con el cambio. No necesitamos diez párrafos de explicación para un cambio trivial de una línea. No repitas lo que es obvio al mirar el diff (p. ej., “Corregí el error tipográfico en ‘foobaar’”).

Si tu código realiza algunos cambios no triviales, también puede ser una buena idea añadir comentarios al código para explicar esos cambios. Por ejemplo, si tuviste que iterar sobre tu implementación varias veces porque la forma más obvia no funcionó, es una buena indicación de que se necesita un comentario de código.

Si es relevante, indica cómo probaste el cambio, por ejemplo, mostrando el comando de prueba de pytest o el código para reproducir el problema.

Comentarios del revisor

Tras enviar tu PR, un mantenedor suele dar feedback en un par de días. Si no recibes ningún feedback en dos semanas, es posible que tu PR se haya pasado por alto; en ese caso, no dudes en avisar a los mantenedores, pero no antes.

Si el revisor proporciona comentarios en línea, no los marques como resueltos si los has atendido. Deja estos comentarios abiertos, ya que ayudan al revisor a retomar su trabajo.

Tras trabajar en la retroalimentación de los revisores, avísalos para que sepan que la PR está lista para su revisión.

Correcciones de errores

Proporcione una descripción de las circunstancias que dieron lugar al error. Si ya existe un problema relacionado, enlázelo (p. ej., “Resuelve #12345”).

Idealmente, cuando se proporciona una corrección de errores, debe ir acompañada de una prueba para dicho error. La prueba debe fallar con el código actual y aprobarse con la corrección. Añade un comentario a la prueba que haga referencia al problema o a la solicitud de extracción (PR). Sin una prueba, resulta más difícil prevenir regresiones en el futuro.

Mejoras en la documentación

Nos complace recibir correcciones para enlaces rotos y documentación ausente o poco clara. También se valora mucho cuidar los ejemplos, asegurándose de que estén actualizados y funcionen correctamente en este entorno de rápida evolución.

Por favor, absténgase de enviar solicitudes de extracción que solo corrigen errores de escritura, ya que generalmente generan más trabajo del que ahorran. Es mejor combinar estos cambios con correcciones más sustanciales (como corregir enlaces rotos o ampliar/actualizar la documentación).

Agregar un nuevo método de ajuste fino de PEFT

Se desarrollan constantemente nuevos métodos de ajuste fino eficientes en parámetros. Si deseas agregar un nuevo método prometedor a PEFT, sigue estos pasos.

Si no eres autor del artículo original, busca implementaciones existentes y comprueba con los autores que no tienen previsto enviar un PR ellos mismos.
Abre un problema de propuesta y espera la aprobación explícita descrita anteriormente antes de comenzar con el trabajo de integración central enumerado a continuación.
Revisa los commits recientes para ver los nuevos métodos de PEFT que se están añadiendo y tomarlos como inspiración.
Una vez que la propuesta se aprueba, puede ser útil abrir un PR en borrador de forma temprana cuando el método funcione básicamente y las primeras pruebas pasen, y luego solicitar comentarios. Referencia el problema aprobado en la descripción del PR en borrador.

Integración principal de un nuevo método PEFT

PR completo para añadir un nuevo método PEFT

Asegúrate de que los argumentos de configuración específicos del método estén bien nombrados y explicados; no asumas que el usuario conoce el paper a fondo.
Siga las convenciones de nomenclatura y codificación de PEFT.
Asegúrate de que no hayas verificado accidentalmente cambios no relacionados, por ejemplo, que el formateador de código haya modificado archivos no relacionados.
Si algunas decisiones de implementación no son triviales, documéntalas con un comentario de código.
Complete la suite de pruebas completa (test_config.py, test_decoder_models.py, etc.) añadiendo el método PEFT a la matriz de pruebas. Asegúrate de que las pruebas se ejecuten correctamente.
Añade documentación en docs/source/package_reference/ con una breve explicación, un enlace al paper, un fragmento de uso y bloques de autodoc. Explica las ventajas y desventajas en comparación con otros métodos como LoRA. Registra esa página de documentación en docs/source/_toctree.yml.
Añade un ejemplo ejecutable en examples/ (puede ser una copia de un ejemplo existente), con un breve README.md.
Comprueba los benchmarks en method_comparison/ y añade la configuración de experimentos para tu nuevo método. Este es un buen lugar para verificar que el método PEFT se entrena como se espera. Incluye una o dos configuraciones de benchmark razonables (una predeterminada y otra optimizada para el benchmark).
Recomendado: añadir soporte para cuantización genérica. En lugar de tener que añadir explícitamente los tipos de capas de cuantización para cada método de cuantización, se debe admitir la cuantización genérica. Como ejemplo, consulta cómo se implementa en BOFT. Amplía https://github.com/huggingface/peft/blob/main/tests/test_quantization.py añadiendo tu método de PEFT allí. Pide ayuda a los mantenedores si es necesario.

Realizar cambios en los métodos PEFT existentes

Si realizas un cambio en un método de PEFT que podría alterar sus salidas, invalidando así los puntos de control ya entrenados, debemos tomar precauciones adicionales. Consulta la descripción en https://github.com/huggingface/peft/blob/main/.ai/skills/peft-method-changes/SKILL.md para obtener más detalles. Las instrucciones allí están destinadas tanto a humanos como a IA.

Agregar otras funciones

Primero, abre un issue en GitHub con una propuesta para agregar la nueva funcionalidad y espera la aprobación explícita descrita anteriormente. De esta manera, puedes discutir con los mantenedores si tiene sentido agregar la funcionalidad antes de dedicar demasiado tiempo a su implementación.

Las nuevas funciones deben ir generalmente acompañadas de pruebas y documentación o ejemplos. Sin estos últimos, a los usuarios les resultará difícil descubrir tu nueva y genial función.

Los cambios en el código deben implementarse de manera compatible hacia atrás. Por ejemplo, el código existente debe seguir funcionando de la misma manera después de que se integre la funcionalidad.

Update on GitHub

←torch.compile Solución de problemas→