Hub Python Library documentation
Variables de entorno
Variables de entorno
huggingface_hub se puede configurar mediante variables de entorno.
Si no está familiarizado con las variables de entorno, aquí hay artículos genéricos sobre ellas en macOS y Linux y en Windows.
Esta página te guiará a través de todas las variables de entorno específicas de huggingface_hub y su significado.
Todas las variables de entorno se leen en el momento de importar
huggingface_hub. Cualquier modificación realizada después no se tendrá en cuenta. Asegúrate de establecer tus variables de entorno antes de importarhuggingface_hub.
Genérico
HF_INFERENCE_ENDPOINT
Para configurar la URL base de la API de inferencia. Es posible que desee establecer esta variable si su organización apunta a una API Gateway en lugar de directamente a la API de inferencia.
Por defecto, es "https://huggingface.co/static-proxy/api-inference.huggingface.co".
HF_HOME
Para configurar dónde huggingface_hub almacenará los datos localmente. En particular, tu token y la caché se almacenarán en esta carpeta.
Por defecto es "~/.cache/huggingface" a menos que XDG_CACHE_HOME esté definido.
HF_HUB_CACHE
Para configurar dónde se almacenarán en caché localmente los repositorios del Hub (modelos, conjuntos de datos y espacios).
Por defecto, es "$HF_HOME/hub" (p. ej., "~/.cache/huggingface/hub" por defecto).
HF_XET_CACHE
Para configurar dónde Xet almacena localmente su caché de fragmentos y los datos de preparación para la carga. Consulte Xet caching para obtener más detalles.
Por defecto, es "$HF_HOME/xet" (p. ej., "~/.cache/huggingface/xet" por defecto).
HF_ASSETS_CACHE
Para configurar dónde se almacenarán en caché localmente los assets creados por las bibliotecas de nivel inferior. Esos assets pueden ser datos preprocesados, archivos descargados de GitHub, registros, etc.
Por defecto, es "$HF_HOME/assets" (p. ej., "~/.cache/huggingface/assets" por defecto).
HF_TOKEN
Para configurar el User Access Token para autenticarse en el Hub. Si se establece, este valor sobrescribirá el token almacenado en la máquina (en $HF_TOKEN_PATH o en "$HF_HOME/token" si el primero no está configurado).
Para más detalles sobre la autenticación, consulte esta sección.
HF_TOKEN_PATH
Para configurar dónde huggingface_hub debe almacenar el User Access Token. El valor predeterminado es "$HF_HOME/token" (p. ej., ~/.cache/huggingface/token de forma predeterminada).
HF_HUB_VERBOSITY
Establece el nivel de verbosidad del registrador de huggingface_hub. Debe ser uno de {"debug", "info", "warning", "error", "critical"}.
Por defecto, es "warning".
Para más detalles, consulte la referencia de registro.
HF_HUB_ETAG_TIMEOUT
Valor entero para definir el número de segundos de espera de la respuesta del servidor al obtener los metadatos más recientes de un repositorio antes de descargar un archivo. Si la solicitud expira, huggingface_hub utilizará los archivos en caché local. Establecer un valor más bajo acelera el flujo de trabajo en máquinas con una conexión lenta que ya tienen archivos en caché. Un valor más alto garantiza que la llamada de metadatos tenga éxito en más casos. El valor predeterminado es de 10 s.
HF_HUB_DOWNLOAD_TIMEOUT
Valor entero para definir el número de segundos a esperar la respuesta del servidor al descargar un archivo. Si la solicitud expira, se lanza un TimeoutError. Establecer un valor más alto es beneficioso en máquinas con una conexión lenta. Un valor más pequeño hace que el proceso falle más rápido en caso de una interrupción total de la red. El valor predeterminado es de 10 s.
Xet
Otras variables de entorno de Xet
HF_XET_CHUNK_CACHE_SIZE_BYTES
Esta variable ya no tiene ningún efecto. hf_xet ya no utiliza una caché local de fragmentos para las descargas, y establecer esta variable no la habilita. Consulte xet-core#715 para obtener más detalles.
HF_XET_SHARD_CACHE_SIZE_LIMIT
Para establecer el tamaño de la caché de fragmentos Xet localmente. Aumentar este valor mejorará la eficiencia de la carga, ya que los fragmentos referenciados en los archivos de fragmentos en caché no se volverán a cargar. Tenga en cuenta que el límite blando predeterminado probablemente sea suficiente para la mayoría de las cargas de trabajo.
Por defecto, es 16000000000 (16 GB).
HF_XET_NUM_CONCURRENT_RANGE_GETS
Esta variable ya no se utiliza. Desde hf_xet 1.3.0, la concurrencia de descargas se controla de forma adaptativa.
Valores booleanos
Las siguientes variables de entorno esperan un valor booleano. La variable se considerará
True si su valor es uno de {"1", "ON", "YES", "TRUE"} (sin distinción entre mayúsculas y minúsculas). Cualquier otro valor
(o uno no definido) se considerará como False.
HF_DEBUG
Si se establece, el nivel de registro del registrador huggingface_hub se fija en DEBUG. Además, todas las solicitudes realizadas por las bibliotecas de HF se registrarán como comandos cURL equivalentes para facilitar la depuración y la reproducibilidad.
HF_HUB_OFFLINE
Si se establece, no se realizarán llamadas HTTP al Hugging Face Hub. Si intentas descargar archivos, solo se accederá a los archivos en caché. Si no se detecta ningún archivo en caché, se generará un error. Esto es útil en caso de que tu red sea lenta y no te importe tener la última versión de un archivo.
Si HF_HUB_OFFLINE=1 se establece como variable de entorno y se llama a cualquier método de HfApi, se lanzará una excepción OfflineModeIsEnabled.
Nota: aunque la última versión de un archivo esté en caché, llamar a hf_hub_download sigue generando una solicitud HTTP para comprobar que no hay una nueva versión disponible. Establecer HF_HUB_OFFLINE=1 omitirá esta llamada, lo que acelera el tiempo de carga.
Si deseas comprobar si el modo sin conexión está habilitado o no, puedes usar el helper is_offline_mode().
HF_HUB_DISABLE_IMPLICIT_TOKEN
La autenticación no es obligatoria para cada solicitud al Hub. Por ejemplo, solicitar detalles sobre el modelo "gpt2" no requiere estar autenticado. Sin embargo, si un usuario está iniciado sesión, el comportamiento predeterminado será enviar siempre el token para facilitar la experiencia del usuario (evitar siempre un HTTP 401 No autorizado) al acceder a repositorios privados o con acceso restringido. Por privacidad, puede deshabilitar este comportamiento estableciendo HF_HUB_DISABLE_IMPLICIT_TOKEN=1. En este caso, el token solo se enviará para las llamadas de “acceso de escritura” (ejemplo: crear un commit).
Nota: deshabilitar el envío implícito del token puede tener efectos secundarios extraños. Por ejemplo, si quieres listar todos los modelos del Hub, tus modelos privados no se listarán. Necesitarás pasar explícitamente el argumento token=True en tu script.
HF_HUB_DISABLE_PROGRESS_BARS
Para las tareas que requieren mucho tiempo, huggingface_hub muestra una barra de progreso de forma predeterminada (usando tqdm).
Puedes desactivar todas las barras de progreso a la vez estableciendo HF_HUB_DISABLE_PROGRESS_BARS=1.
HF_HUB_DISABLE_SYMLINKS
Si se establece, huggingface_hub nunca creará enlaces simbólicos en la caché. En su lugar, los archivos se duplicarán o se moverán directamente a los directorios de instantánea. Esta es una función para usuarios avanzados que hace que el directorio de caché funcione en un modo degradado, donde los archivos enormes terminan duplicados en el disco duro.
Un caso de uso es cuando una unidad de red compartida (p. ej., NAS) se utiliza como HF_HUB_CACHE entre máquinas que ejecutan diferentes sistemas operativos. Los enlaces simbólicos creados en Linux no siempre son navegables en Windows, lo que provoca errores. Establecer HF_HUB_DISABLE_SYMLINKS=1 evita este problema a costa de la deduplicación del espacio en disco.
HF_HUB_DISABLE_SYMLINKS_WARNING
Si estás en una máquina con Windows, se recomienda habilitar el modo de desarrollador o ejecutar huggingface_hub en modo de administrador. De lo contrario, huggingface_hub no podrá crear enlaces simbólicos en tu sistema de caché. Podrás ejecutar cualquier script, pero tu experiencia de usuario se verá degradada, ya que algunos archivos grandes podrían terminar duplicados en tu disco duro. Se emite un mensaje de advertencia para informarte sobre este comportamiento. Establece HF_HUB_DISABLE_SYMLINKS_WARNING=1 para desactivar esta advertencia.
Para más detalles, consulte limitaciones de la caché.
HF_HUB_DISABLE_EXPERIMENTAL_WARNING
Algunas funciones de huggingface_hub son experimentales. Esto significa que puedes usarlas, pero no garantizamos que se mantengan en el futuro. En particular, es posible que actualicemos la API o el comportamiento de dichas funciones sin ningún ciclo de deprecación. Se emite un mensaje de advertencia al usar una función experimental para informarte de ello. Si no te importa depurar cualquier problema potencial al usar una función experimental, puedes establecer HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1 para desactivar la advertencia.
Si estás utilizando una función experimental, ¡avísanos! Tus comentarios nos ayudan a diseñarla y mejorarla.
HF_HUB_DISABLE_TELEMETRY
Por defecto, algunas bibliotecas de HF (transformers, datasets, gradio,..) recopilan datos para supervisar el uso, depurar problemas y ayudar a priorizar funciones.
Cada biblioteca define su propia política (es decir, qué uso supervisar), pero la implementación central se realiza en huggingface_hub (ver send_telemetry).
Puede establecer HF_HUB_DISABLE_TELEMETRY=1 como variable de entorno para deshabilitar la telemetría de forma global.
HF_HUB_DISABLE_UPDATE_CHECK
Por defecto, la CLI hf comprueba en PyPI si hay una versión más reciente al iniciar (como máximo una vez cada 24 horas) e imprime una advertencia de una línea en amarillo en stderr cuando está disponible, sugiriendo hf update. La comprobación ya es un no-op en las versiones de desarrollo y pre-lanzamiento.
También comprueba (como máximo una vez cada 24 horas, de forma puramente local) si la habilidad hf-cli está instalada y generada por la versión en ejecución, y sugiere hf skills add / hf skills update si no es así. La comprobación solo imprime una pista; nunca modifica tus directorios de habilidades.
Antes de ejecutar una extensión de CLI instalada, comprueba (como máximo una vez cada 24 horas por extensión) si hay un commit más reciente disponible en GitHub y, en tal caso, sugiere hf extensions update <name>. hf extensions list utiliza la misma comprobación para su columna LATEST.
Establezca HF_HUB_DISABLE_UPDATE_CHECK=1 para omitir estas solicitudes y silenciar todas estas sugerencias. Útil en entornos de CI sin conexión o cuando prefiere una salida de shell más silenciosa.
HF_HUB_DISABLE_XET
Establecerlo para deshabilitar el uso de hf-xet, incluso si está disponible en su entorno de Python. Esto se debe a que hf-xet se utilizará automáticamente si se encuentra, lo que permite deshabilitar su uso de forma explícita. Si está deshabilitando Xet, considere abrir un problema e incluir la información de diagnóstico para ayudarnos a entender por qué Xet no funciona para usted.
HF_HUB_ENABLE_HF_TRANSFER
Esta es una variable de entorno obsoleta. Ahora que el Hugging Face Hub funciona completamente con el backend de almacenamiento Xet, todas las transferencias de archivos se realizan a través del paquete binario
hf-xet. Proporciona transferencias eficientes mediante una estrategia de deduplicación basada en fragmentos y se integra a la perfección conhuggingface_hub. Esto significa quehf_transferya no se puede utilizar. Si te interesa un mayor rendimiento, consulta la secciónHF_XET_HIGH_PERFORMANCE
HF_HUB_DISABLE_SHARED_BLOBS
Establezca 1 para deshabilitar el almacén de blobs compartido a nivel de caché. De forma predeterminada, los archivos Xet descargados con éxito se almacenan en <CACHE_DIR>/blobs/<prefix>/<xet_hash> y se enlazan simbólicamente en las cachés de los repositorios, de modo que los archivos idénticos se guardan en disco solo una vez entre repositorios y pueden reutilizarse sin volver a descargarlos. Esta optimización está habilitada de forma predeterminada, pero se deshabilita si Xet no está disponible (por ejemplo, si se establece HF_HUB_DISABLE_XET=1) o si los enlaces simbólicos no son compatibles localmente. En esos casos, se recurre silenciosamente al almacenamiento local regular del repositorio. Consulte la guía de caché para obtener más detalles.
HF_XET_HIGH_PERFORMANCE
Configura hf-xet para que funcione con ajustes aumentados y maximice los recursos de red y disco de la máquina. Al habilitar el modo de alto rendimiento, se intentará saturar el ancho de banda de red de esta máquina y utilizar todos los núcleos de CPU para la actividad de carga y descarga en paralelo.
Considere esto como análogo a la variable de entorno heredada HF_HUB_ENABLE_HF_TRANSFER=1, pero aplicada a hf-xet.
Para obtener más información sobre los beneficios del almacenamiento de Xet y hf_xet, consulte esta sección.
HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY
Esta variable ya no se utiliza. Desde hf_xet 1.3.0, los archivos siempre se escriben en el disco local de forma secuencial (consulte el escritor de archivos en v1.3.0).
Variables de entorno obsoletas
Para estandarizar todas las variables de entorno dentro del ecosistema de Hugging Face, algunas variables se han marcado como obsoletas. Aunque siguen siendo funcionales, ya no tienen prioridad sobre sus reemplazos. La siguiente tabla detalla las variables obsoletas y sus alternativas correspondientes:
| Variable obsoleta | Sustitución |
|---|---|
HUGGINGFACE_HUB_CACHE | HF_HUB_CACHE |
HUGGINGFACE_ASSETS_CACHE | HF_ASSETS_CACHE |
HUGGING_FACE_HUB_TOKEN | HF_TOKEN |
Desde herramientas externas
Algunas variables de entorno no son específicas de huggingface_hub, pero se tienen en cuenta cuando están definidas.
DO_NOT_TRACK
Valor booleano. Equivalente a HF_HUB_DISABLE_TELEMETRY. Cuando se establece en true, la telemetría se deshabilita globalmente en el ecosistema de Python de Hugging Face (transformers, diffusers, gradio, etc.). Consulte https://donottrack.sh/ para más detalles.
NO_COLOR
Valor booleano. Cuando se establece, la CLI hf no imprimirá ningún color ANSI.
Vea no-color.org.
XDG_CACHE_HOME
¡Se usa solo cuando HF_HOME no está definido!
Esta es la forma predeterminada de configurar dónde se debe escribir los datos no esenciales (en caché) específicos del usuario en máquinas con Linux.
Si HF_HOME no está definido, el directorio principal predeterminado será "$XDG_CACHE_HOME/huggingface" en lugar de "~/.cache/huggingface".