# Migrar a huggingface_hub v1.0 La versión v1.0 es un hito importante para la biblioteca `huggingface_hub`. Marca nuestro compromiso con la estabilidad de la API y la madurez de la biblioteca. Hemos realizado varias mejoras y cambios que rompen la compatibilidad para hacer la biblioteca más robusta y fácil de usar. Esta guía está destinada a ayudarte a migrar tu código existente a la nueva versión. Si tienes alguna pregunta o comentario, por favor, hazlo saber [abriendo un issue en GitHub](https://github.com/huggingface/huggingface_hub/issues). ## Python 3.9+ `huggingface_hub` ahora requiere Python 3.9 o superior. Python 3.8 ya no se admite. ## Migración a HTTPX La biblioteca `huggingface_hub` ahora utiliza [`httpx`](https://www.python-httpx.org/) en lugar de `requests` para las solicitudes HTTP. Este cambio se realizó para mejorar el rendimiento y para soportar tanto las solicitudes síncronas como las asíncronas de la misma manera. Por lo tanto, eliminamos las dependencias de `requests` y `aiohttp`. ### Cambios que rompen la compatibilidad Este es un cambio importante que afecta a toda la biblioteca. Aunque hemos intentado hacer este cambio lo más transparente posible, es posible que necesites actualizar tu código en algunos casos. A continuación se muestra una lista de los cambios incompatibles introducidos en el proceso: - **Configuración del proxy**: ya no se admiten los proxies "por método". Los proxies deben configurarse de forma global mediante las variables de entorno `HTTP_PROXY` y `HTTPS_PROXY`. - **Backend HTTP personalizado**: se ha eliminado la función `configure_http_backend`. Ahora debe usar [set_client_factory()](/docs/huggingface_hub/v2.4.0/es/package_reference/utilities#huggingface_hub.set_client_factory) y [set_async_client_factory()](/docs/huggingface_hub/v2.4.0/es/package_reference/utilities#huggingface_hub.set_async_client_factory) para configurar los clientes HTTP. - **Gestión de errores**: los errores HTTP ya no se heredan de `requests.HTTPError`, sino de `httpx.HTTPError`. Recomendamos capturar [HfHubHTTPError](/docs/huggingface_hub/v2.4.0/es/package_reference/utilities#huggingface_hub.errors.HfHubHTTPError) (importado con `from huggingface_hub.utils import HfHubHTTPError`), que es una subclase de `requests.HTTPError` en v0.x y de `httpx.HTTPError` en v1.x. Capturar desde el error de `huggingface_hub` garantiza que tu código sea compatible con ambas versiones, la antigua y la nueva, de la biblioteca. - **SSLError**: `httpx` no tiene el concepto de `SSLError`. Ahora es un `httpx.ConnectError` genérico. - **`LocalEntryNotFoundError`**: Este error ya no hereda de `HTTPError`. Ahora definimos un `EntryNotFoundError` (nuevo) del que heredan tanto `LocalEntryNotFoundError` (si el archivo no se encuentra en la caché local) como `RemoteEntryNotFoundError` (si el archivo no se encuentra en el repositorio del Hub). Solo el error remoto hereda de `HTTPError`. - **`InferenceClient`**: Ahora se puede usar `InferenceClient` como un gestor de contexto. Esto resulta especialmente útil al transmitir tokens de un modelo de lenguaje para garantizar que la conexión se cierre correctamente. - **`AsyncInferenceClient`**: El parámetro `trust_env` se ha eliminado del constructor de `AsyncInferenceClient`. Las variables de entorno se confían de forma predeterminada en `httpx`. Si no desea confiar explícitamente en el entorno, debe configurarlo con [set_async_client_factory()](/docs/huggingface_hub/v2.4.0/es/package_reference/utilities#huggingface_hub.set_async_client_factory). Para más detalles, puedes consultar [PR #3328](https://github.com/huggingface/huggingface_hub/pull/3328), que introdujo `httpx`. ### ¿Por qué `httpx`? La migración de `requests` a `httpx` aporta varias mejoras clave que aumentan el rendimiento, la fiabilidad y la mantenibilidad de la biblioteca: **Seguridad de hilos y reutilización de conexiones**: `httpx` es seguro para hilos por diseño, lo que nos permite reutilizar el mismo cliente de forma segura entre varios hilos. Esta reutilización de conexiones reduce la sobrecarga de establecer nuevas conexiones para cada solicitud HTTP, mejorando el rendimiento, especialmente al realizar solicitudes frecuentes al Hub. **Soporte de HTTP/2**: `httpx` ofrece soporte nativo para HTTP/2, lo que proporciona una mayor eficiencia al realizar múltiples solicitudes al mismo servidor (nuestro caso de uso exacto). Esto se traduce en una latencia más baja y un menor consumo de recursos en comparación con HTTP/1.1. **API unificada síncrona/asíncrona**: A diferencia de nuestra configuración anterior, que dependía de `requests` (síncrono) y `aiohttp` (asíncrono) por separado, `httpx` ofrece clientes síncronos y asíncronos con un comportamiento idéntico. Esto garantiza que `InferenceClient` y `AsyncInferenceClient` tengan una funcionalidad coherente y elimina las sutiles diferencias de comportamiento que existían entre ambas implementaciones. **Mejor manejo de errores SSL**: `httpx` maneja los errores SSL de manera más adecuada, lo que facilita y hace más fiable la depuración de problemas de conexión. **Arquitectura a prueba de futuro**: `httpx` se mantiene de forma activa y está diseñado para aplicaciones modernas de Python. En contraste, `requests` está en modo de mantenimiento y no recibirá actualizaciones importantes, como mejoras en la seguridad de hilos o soporte para HTTP/2. **Mejor manejo de variables de entorno**: `httpx` ofrece un manejo más consistente de las variables de entorno en ambos contextos, síncrono y asíncrono, eliminando las inconsistencias previas en las que `requests` leía las variables de entorno locales de forma predeterminada, mientras que `aiohttp` no lo hacía. La transición a `httpx` posiciona a `huggingface_hub` con un backend HTTP moderno, eficiente y mantenible. Si bien la mayoría de los usuarios debería experimentar un funcionamiento sin interrupciones, las mejoras subyacentes proporcionan un mejor rendimiento y fiabilidad para todas las interacciones con el Hub. ## `hf_transfer` Ahora que todos los repositorios del Hub tienen habilitado Xet y que `hf_xet` es la forma predeterminada de descargar/subir archivos, hemos eliminado el soporte para el paquete opcional `hf_transfer`. Por lo tanto, la variable de entorno `HF_HUB_ENABLE_HF_TRANSFER` se ignora. Utilice [`HF_XET_HIGH_PERFORMANCE`](../package_reference/environment_variables) en su lugar. ## clase `Repository` La clase `Repository` se eliminó en la v1.0. Era un envoltorio ligero alrededor de la CLI de `git` para gestionar repositorios. Aún puedes usar `git` directamente en la terminal, pero el enfoque recomendado es utilizar la API basada en HTTP de la biblioteca `huggingface_hub` para una experiencia más fluida, especialmente al trabajar con archivos grandes. Aquí hay una correspondencia entre la clase `Repository` heredada y la nueva clase `HfApi`: | método `Repository` | método de `HfApi` | | ------------------------------------------ | ----------------------------------------------------- | | `repo.clone_from` | `snapshot_download` | | `repo.git_add` + `git_commit` + `git_push` | [upload_file()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_api#huggingface_hub.HfApi.upload_file), [upload_folder()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_api#huggingface_hub.HfApi.upload_folder), [create_commit()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_api#huggingface_hub.HfApi.create_commit) | | `repo.git_tag` | `create_tag` | | `repo.git_branch` | `create_branch` | ## clase `HfFolder` `HfFolder` se usaba para gestionar el token de acceso del usuario. Use [login()](/docs/huggingface_hub/v2.4.0/es/package_reference/authentication#huggingface_hub.login) para guardar un token nuevo, [logout()](/docs/huggingface_hub/v2.4.0/es/package_reference/authentication#huggingface_hub.logout) para eliminarlo y [whoami()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_api#huggingface_hub.HfApi.whoami) para comprobar el usuario asociado al token actual. Finalmente, use `get_token()` para recuperar el token del usuario en un script. ## clase `InferenceApi` `InferenceApi` era una clase para interactuar con la Inference API. Ahora se recomienda usar la clase [InferenceClient](/docs/huggingface_hub/v2.4.0/es/package_reference/inference_client#huggingface_hub.InferenceClient) en su lugar. ## Otras funciones obsoletas Algunos métodos y parámetros se han eliminado en v1.0. Los enumerados a continuación ya estaban obsoletos con un mensaje de advertencia en v0.x. - `constants.hf_cache_home` ha sido eliminado. Utiliza `HF_HOME` en su lugar. - Los parámetros `use_auth_token` se han eliminado de todos los métodos. Utilice `token` en su lugar. - El método `get_token_permission` ha sido eliminado. - El método `update_repo_visibility` se ha eliminado. Utilice `update_repo_settings` en su lugar. - El parámetro `is_write_action` se ha eliminado de `build_hf_headers`, al igual que `write_permission` de `login`. El concepto de "permiso de escritura" se ha eliminado y ya no es relevante ahora que los tokens de granularidad fina son el enfoque recomendado. - El parámetro `new_session` en `login` se ha renombrado a `skip_if_logged_in` para mayor claridad. - Los parámetros `resume_download`, `force_filename` y `local_dir_use_symlinks` se han eliminado de `hf_hub_download` y `snapshot_download`. - Los parámetros `library`, `language`, `tags` y `task` se han eliminado de `list_models`. ## Comandos de caché de la CLI La gestión de la caché desde la CLI se ha rediseñado para seguir un flujo de trabajo inspirado en Docker. El obsoleto `huggingface-cli` se ha eliminado, y `hf` (introducido en v0.34) lo reemplaza con una CLI de recurso-acción más clara. Los comandos heredados `hf cache scan` y `hf cache delete` también se eliminan en v1.0 y se reemplazan con el nuevo trío a continuación: - `hf cache ls` lista las entradas de la caché con una salida en tabla concisa, JSON o CSV. Use `--revisions` para inspeccionar revisiones individuales, agregue expresiones de `--filter` como `size>1GB` o `accessed>30d` y combínelas con `--quiet` cuando solo necesite los identificadores. - `hf cache rm` elimina las entradas de caché seleccionadas. Pase uno o más IDs de repositorio (por ejemplo, `model/bert-base-uncased`) o hashes de revisión, y opcionalmente agregue `--dry-run` para previsualizar o `--yes` para omitir el mensaje de confirmación. Esto reemplaza tanto los flujos de trabajo de la TUI interactiva como los de `--disable-tui` del comando anterior. - `hf cache prune` realiza la tarea habitual de limpieza de eliminar las revisiones no referenciadas de una sola vez. Añada `--dry-run` o `--yes` de la misma manera que con `hf cache rm`. Por último, se ha eliminado el extra `[cli]`: la CLI ahora se distribuye con el paquete principal `huggingface_hub`. ## Soporte para TensorFlow y Keras 2.x Todo el código y las dependencias relacionados con TensorFlow se han eliminado en v1.0. Esto incluye los siguientes cambios incompatibles: - `huggingface_hub[tensorflow]` ya no es una dependencia adicional compatible - Las funciones utilitarias `split_tf_state_dict_into_shards` y `get_tf_storage_size` han sido eliminadas. - Las versiones de `tensorflow`, `fastai` y `fastcore` ya no están incluidas en las cabeceras integradas. La integración con Keras 2.x también se ha eliminado. Esto incluye la clase `KerasModelHubMixin` y las utilidades `save_pretrained_keras`, `from_pretrained_keras` y `push_to_hub_keras`. Keras 2.x es una biblioteca legada y sin mantenimiento. El enfoque recomendado es utilizar Keras 3.x, que está estrechamente integrado con el Hub (es decir, contiene un método integrado para cargar/pushear en el Hub). Si aún deseas trabajar con Keras 2.x, debes degradar `huggingface_hub` a una versión v0.x. ## Los valores devueltos por `upload_file` y `upload_folder` Las funciones [upload_file()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_api#huggingface_hub.HfApi.upload_file) y [upload_folder()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) ahora devuelven la URL del commit creado en el Hub. Anteriormente, devolvían la URL del archivo o la carpeta. Esto se hace para alinearse con el valor de retorno de [create_commit()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_api#huggingface_hub.HfApi.create_commit), [delete_file()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_api#huggingface_hub.HfApi.delete_file) y [delete_folder()](/docs/huggingface_hub/v2.4.0/es/package_reference/hf_api#huggingface_hub.HfApi.delete_folder).