Hub Python Library documentation
Biến môi trường
Biến môi trường
huggingface_hub có thể được cấu hình bằng các biến môi trường.
Nếu bạn chưa quen thuộc với biến môi trường, dưới đây là các bài viết tổng quát về chúng trên macOS và Linux và trên Windows.
Trang này sẽ hướng dẫn bạn qua tất cả các biến môi trường đặc thù của huggingface_hub và ý nghĩa của chúng.
Tất cả các biến môi trường được đọc vào thời điểm import
huggingface_hub. Mọi thay đổi được thực hiện sau đó sẽ không được tính đến. Hãy đảm bảo thiết lập các biến môi trường của bạn trước khi importhuggingface_hub.
Tổng quát
HF_INFERENCE_ENDPOINT
Để cấu hình địa chỉ URL cơ sở của inference api. Bạn có thể muốn đặt biến này nếu tổ chức của bạn đang trỏ đến API Gateway thay vì trỏ trực tiếp đến inference api.
Mặc định là "https://huggingface.co/proxy/api-inference.huggingface.co".
HF_HOME
Để cấu hình nơi huggingface_hub sẽ lưu trữ dữ liệu cục bộ. Cụ thể, token và bộ đệm của bạn sẽ được lưu trong thư mục này.
Mặc định là "~/.cache/huggingface" trừ khi XDG_CACHE_HOME được đặt.
HF_HUB_CACHE
Để cấu hình vị trí lưu bộ nhớ đệm cục bộ cho các kho từ Hub (mô hình, bộ dữ liệu và spaces).
Mặc định là "$HF_HOME/hub" (ví dụ "~/.cache/huggingface/hub" theo mặc định).
HF_XET_CACHE
Để cấu hình nơi Xet lưu trữ bộ nhớ đệm shard và dữ liệu tạm thời cho việc tải lên cục bộ. Xem Xet caching để biết thêm chi tiết.
Mặc định là "$HF_HOME/xet" (ví dụ "~/.cache/huggingface/xet" theo mặc định).
HF_ASSETS_CACHE
Để cấu hình vị trí lưu bộ nhớ đệm cục bộ cho các tài nguyên được tạo bởi các thư viện hạ nguồn. Các tài nguyên này có thể là dữ liệu đã tiền xử lý, các tệp được tải xuống từ GitHub, nhật ký,…
Mặc định là "$HF_HOME/assets" (ví dụ "~/.cache/huggingface/assets" theo mặc định).
HF_TOKEN
Để cấu hình User Access Token nhằm xác thực với Hub. Nếu được đặt, giá trị này sẽ ghi đè lên token được lưu trên máy (trong $HF_TOKEN_PATH hoặc "$HF_HOME/token" nếu cái trước không được đặt).
Để biết thêm chi tiết về xác thực, hãy xem mục này.
HF_TOKEN_PATH
Để cấu hình nơi huggingface_hub sẽ lưu trữ User Access Token. Mặc định là "$HF_HOME/token" (ví dụ ~/.cache/huggingface/token theo mặc định).
HF_HUB_VERBOSITY
Đặt mức độ chi tiết của trình ghi log của huggingface_hub. Phải là một trong {"debug", "info", "warning", "error", "critical"}.
Mặc định là "warning".
Để biết thêm chi tiết, hãy xem tham chiếu ghi log.
HF_HUB_ETAG_TIMEOUT
Giá trị nguyên để xác định số giây chờ phản hồi từ máy chủ khi lấy metadata mới nhất từ một repo trước khi tải xuống một tệp. Nếu yêu cầu hết thời gian chờ, huggingface_hub sẽ mặc định sử dụng các tệp được cache cục bộ. Đặt giá trị thấp hơn sẽ tăng tốc quy trình làm việc cho các máy có kết nối chậm và đã có sẵn tệp trong cache. Giá trị cao hơn đảm bảo rằng cuộc gọi metadata thành công trong nhiều trường hợp hơn. Mặc định là 10 giây.
HF_HUB_DOWNLOAD_TIMEOUT
Giá trị nguyên để xác định số giây chờ phản hồi từ máy chủ khi tải xuống một tệp. Nếu yêu cầu hết thời gian chờ, một TimeoutError sẽ được ném ra. Việc đặt giá trị cao hơn sẽ có lợi trên các máy có kết nối chậm. Giá trị nhỏ hơn sẽ khiến quá trình thất bại nhanh hơn trong trường hợp mất mạng hoàn toàn. Mặc định là 10 giây.
Xét
Các biến môi trường Xet khác
HF_XET_CHUNK_CACHE_SIZE_BYTES
Biến này không còn có hiệu lực. hf_xet không còn sử dụng bộ nhớ đệm chunk cục bộ cho các lượt tải xuống, và việc đặt biến này sẽ không kích hoạt bộ nhớ đệm đó. Xem xet-core#715 để biết thêm chi tiết.
HF_XET_SHARD_CACHE_SIZE_LIMIT
Để đặt kích thước bộ nhớ đệm shard Xet cục bộ. Việc tăng giá trị này sẽ cải thiện hiệu quả tải lên vì các khối được tham chiếu trong các tệp shard được đệm sẽ không được tải lên lại. Lưu ý rằng giới hạn mềm mặc định có khả năng là đủ cho hầu hết các khối lượng công việc.
Mặc định là 16000000000 (16GB).
HF_XET_NUM_CONCURRENT_RANGE_GETS
Biến này không còn được sử dụng nữa. Kể từ hf_xet 1.3.0, mức độ song song tải xuống được kiểm soát một cách thích ứng.
Giá trị Boolean
Các biến môi trường sau đây nhận giá trị boolean. Biến sẽ được coi là True nếu giá trị của nó là một trong {"1", "ON", "YES", "TRUE"} (không phân biệt hoa thường). Mọi giá trị khác
(hoặc chưa xác định) sẽ được coi là False.
HF_DEBUG
Nếu được đặt, mức ghi log của trình ghi log huggingface_hub sẽ được đặt thành DEBUG. Ngoài ra, tất cả các yêu cầu do các thư viện HF thực hiện sẽ được ghi log dưới dạng các lệnh cURL tương đương để dễ dàng gỡ lỗi và tái lập.
HF_HUB_OFFLINE
Nếu được đặt, sẽ không có bất kỳ cuộc gọi HTTP nào được thực hiện đến Hugging Face Hub. Nếu bạn cố gắng tải xuống các tệp, chỉ các tệp trong bộ nhớ đệm sẽ được truy cập. Nếu không phát hiện tệp bộ nhớ đệm, một lỗi sẽ được ném ra. Điều này hữu ích trong trường hợp mạng của bạn chậm và bạn không quan tâm đến việc có phiên bản mới nhất của một tệp.
Nếu biến môi trường HF_HUB_OFFLINE=1 được đặt và bạn gọi bất kỳ phương thức nào của HfApi, một ngoại lệ OfflineModeIsEnabled sẽ được ném ra.
Lưu ý: ngay cả khi phiên bản mới nhất của một tệp đã được lưu trong bộ nhớ đệm, việc gọi hf_hub_download vẫn sẽ kích hoạt một yêu cầu HTTP để kiểm tra xem có phiên bản mới nào khả dụng hay không. Việc đặt HF_HUB_OFFLINE=1 sẽ bỏ qua cuộc gọi này, giúp rút ngắn thời gian tải của bạn.
Nếu bạn muốn kiểm tra xem chế độ ngoại tuyến có được bật hay không, bạn có thể sử dụng tiện ích is_offline_mode().
HF_HUB_DISABLE_IMPLICIT_TOKEN
Xác thực không bắt buộc cho mọi yêu cầu đến Hub. Ví dụ, việc yêu cầu chi tiết về model "gpt2" không cần xác thực. Tuy nhiên, nếu người dùng đã đăng nhập, hành vi mặc định sẽ luôn gửi token để cải thiện trải nghiệm người dùng (không bao giờ nhận được HTTP 401 Unauthorized) khi truy cập các repository riêng tư hoặc có kiểm soát. Vì lý do riêng tư, bạn có thể tắt hành vi này bằng cách đặt HF_HUB_DISABLE_IMPLICIT_TOKEN=1. Trong trường hợp này, token chỉ được gửi cho các cuộc gọi “write-access” (ví dụ: tạo một commit).
Lưu ý: việc tắt gửi token ngầm có thể gây ra các tác dụng phụ kỳ lạ. Ví dụ,
nếu bạn muốn liệt kê tất cả các model trên Hub, các model riêng tư của bạn sẽ không được liệt kê. Bạn
cần truyền rõ ràng đối số token=True trong script của mình.
HF_HUB_DISABLE_PROGRESS_BARS
Đối với các tác vụ tốn nhiều thời gian, huggingface_hub hiển thị thanh tiến trình theo mặc định (sử dụng tqdm).
Bạn có thể tắt tất cả các thanh tiến trình cùng lúc bằng cách đặt HF_HUB_DISABLE_PROGRESS_BARS=1.
HF_HUB_DISABLE_SYMLINKS
Nếu được đặt, huggingface_hub sẽ không bao giờ tạo symlink trong cache. Thay vào đó, các tệp sẽ được sao chép hoặc di chuyển trực tiếp vào các thư mục snapshot. Đây là tính năng dành cho người dùng nâng cao, khiến thư mục cache chạy ở chế độ suy giảm, trong đó các tệp lớn sẽ bị sao chép trùng lặp trên ổ cứng của bạn.
Một ví dụ về trường hợp sử dụng là khi ổ đĩa mạng dùng chung (ví dụ: NAS) được dùng làm HF_HUB_CACHE trên các máy chạy các hệ điều hành khác nhau. Các symlink được tạo trên Linux không phải lúc nào cũng có thể truy cập được trên Windows, dẫn đến lỗi. Việc đặt HF_HUB_DISABLE_SYMLINKS=1 giúp tránh vấn đề này với cái giá là mất đi khả năng khử trùng lặp dung lượng đĩa.
HF_HUB_DISABLE_SYMLINKS_WARNING
Nếu bạn đang sử dụng máy Windows, được khuyến nghị bật chế độ developer hoặc chạy huggingface_hub ở chế độ admin. Nếu không, huggingface_hub sẽ không thể tạo symlink trong hệ thống cache của bạn. Bạn vẫn có thể thực thi bất kỳ script nào nhưng trải nghiệm người dùng sẽ bị giảm vì một số tệp lớn có thể bị nhân đôi trên ổ cứng. Một thông báo cảnh báo sẽ được kích hoạt để cảnh báo bạn về hành vi này. Đặt HF_HUB_DISABLE_SYMLINKS_WARNING=1 để tắt cảnh báo này.
Để biết thêm chi tiết, xem giới hạn của bộ nhớ đệm.
HF_HUB_DISABLE_EXPERIMENTAL_WARNING
Một số tính năng của huggingface_hub mang tính thử nghiệm. Điều này có nghĩa là bạn có thể sử dụng chúng nhưng chúng tôi không đảm bảo chúng sẽ được duy trì trong tương lai. Cụ thể, chúng tôi có thể cập nhật API hoặc hành vi của các tính năng này mà không có chu kỳ loại bỏ (deprecation) nào. Một thông báo cảnh báo sẽ được kích hoạt khi bạn sử dụng một tính năng thử nghiệm để cảnh báo bạn về điều này. Nếu bạn sẵn sàng gỡ lỗi bất kỳ vấn đề tiềm ẩn nào khi sử dụng tính năng thử nghiệm, bạn có thể đặt HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1 để tắt cảnh báo.
Nếu bạn đang sử dụng một tính năng thử nghiệm, vui lòng cho chúng tôi biết! Phản hồi của bạn có thể giúp chúng tôi thiết kế và cải thiện tính năng đó.
HF_HUB_DISABLE_TELEMETRY
Mặc định, một số dữ liệu được thu thập bởi các thư viện HF (transformers, datasets, gradio,..) để theo dõi mức độ sử dụng, gỡ lỗi và hỗ trợ ưu tiên các tính năng.
Mỗi thư viện định nghĩa chính sách riêng của mình (tức là theo dõi mức độ sử dụng nào) nhưng phần triển khai cốt lõi được thực hiện trong huggingface_hub (xem send_telemetry).
Bạn có thể đặt HF_HUB_DISABLE_TELEMETRY=1 dưới dạng biến môi trường để vô hiệu hóa telemetry trên toàn cục.
HF_HUB_DISABLE_UPDATE_CHECK
Mặc định, CLI hf kiểm tra PyPI để tìm phiên bản mới hơn khi khởi động (tối đa một lần mỗi 24 giờ) và in một dòng cảnh báo màu vàng ra stderr khi có phiên bản mới, gợi ý chạy hf update. Việc kiểm tra này vốn đã không thực hiện gì trên các phiên bản dev và pre-release.
Nó cũng kiểm tra (tối đa một lần mỗi 24 giờ, hoàn toàn cục bộ) xem kỹ năng hf-cli đã được cài đặt và tạo bởi phiên bản đang chạy hay chưa, và đề xuất hf skills add / hf skills update nếu chưa. Việc kiểm tra chỉ in ra một gợi ý, không bao giờ chạm vào các thư mục kỹ năng của bạn.
Trước khi chạy một mở rộng CLI đã được cài đặt, hệ thống sẽ kiểm tra (tối đa một lần mỗi 24 giờ cho mỗi mở rộng) xem có commit mới hơn trên GitHub hay không, và nếu có sẽ đề xuất hf extensions update <name>. hf extensions list sử dụng cùng một cơ chế kiểm tra cho cột LATEST của nó.
Đặt HF_HUB_DISABLE_UPDATE_CHECK=1 để bỏ qua các yêu cầu này và tắt toàn bộ các gợi ý này. Hữu ích trong môi trường CI ngoại tuyến hoặc khi bạn muốn đầu ra shell ít thông báo hơn.
HF_HUB_DISABLE_XET
Đặt để vô hiệu hóa việc sử dụng hf-xet, ngay cả khi nó có sẵn trong môi trường Python của bạn. Điều này là do hf-xet sẽ được sử dụng tự động nếu được tìm thấy, và tùy chọn này cho phép vô hiệu hóa việc sử dụng nó một cách rõ ràng. Nếu bạn đang vô hiệu hóa Xet, vui lòng cân nhắc gửi một issue và bao gồm thông tin chẩn đoán để giúp chúng tôi hiểu lý do tại sao Xet không hoạt động cho bạn.
HF_HUB_ENABLE_HF_TRANSFER
Đây là một biến môi trường đã bị ngừng hỗ trợ. Bây giờ, Hugging Face Hub đã được vận hành hoàn toàn bởi backend lưu trữ Xet, tất cả các thao tác chuyển tệp đều đi qua gói binary
hf-xet. Gói này cung cấp các thao tác chuyển tệp hiệu quả bằng cách sử dụng chiến lược khử trùng lặp dựa trên chunk và tích hợp liền mạch vớihuggingface_hub. Điều này có nghĩa làhf_transferkhông thể được sử dụng nữa. Nếu bạn quan tâm đến hiệu suất cao hơn, hãy xem phầnHF_XET_HIGH_PERFORMANCE
HF_HUB_DISABLE_SHARED_BLOBS
Đặt thành 1 để tắt kho blob dùng chung trên toàn bộ cache. Mặc định, các tệp Xet đã tải xuống thành công được lưu trong <CACHE_DIR>/blobs/<prefix>/<xet_hash> và được liên kết bằng symlink vào các cache của repo, nhờ đó các tệp giống hệt nhau chỉ được lưu trên đĩa một lần xuyên suốt các repo và có thể tái sử dụng mà không cần tải lại. Tối ưu hóa này được bật theo mặc định, nhưng sẽ bị tắt nếu Xet không khả dụng (ví dụ khi HF_HUB_DISABLE_XET=1 được đặt) hoặc nếu symlink không được hỗ trợ cục bộ. Trong những trường hợp đó, hệ thống sẽ tự động chuyển sang lưu trữ cục bộ theo repo thông thường. Xem hướng dẫn về cache để biết thêm chi tiết.
HF_XET_HIGH_PERFORMANCE
Đặt hf-xet để hoạt động với các cài đặt tăng cường nhằm tối đa hóa tài nguyên mạng và ổ đĩa trên máy. Bật chế độ hiệu năng cao sẽ cố gắng bão hòa băng thông mạng của máy này và sử dụng tất cả các lõi CPU cho hoạt động tải lên/tải xuống song song.
Hãy xem điều này tương đương với biến môi trường cũ HF_HUB_ENABLE_HF_TRANSFER=1 nhưng được áp dụng cho hf-xet.
Để tìm hiểu thêm về các lợi ích của lưu trữ Xet và hf_xet, hãy tham khảo phần này.
HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY
Biến này không còn được sử dụng nữa. Kể từ hf_xet 1.3.0, các tệp luôn được ghi tuần tự vào ổ đĩa cục bộ (xem trình ghi tệp trong v1.3.0).
Biến môi trường đã bị ngừng hỗ trợ
Để chuẩn hóa tất cả các biến môi trường trong hệ sinh thái Hugging Face, một số biến đã được đánh dấu là không còn được khuyến khích sử dụng. Mặc dù chúng vẫn hoạt động, nhưng chúng không còn có độ ưu tiên cao hơn so với các biến thay thế. Bảng dưới đây liệt kê các biến không còn được khuyến khích sử dụng và các biến thay thế tương ứng:
| Biến đã bị ngừng hỗ trợ | Thay thế |
|---|---|
HUGGINGFACE_HUB_CACHE | HF_HUB_CACHE |
HUGGINGFACE_ASSETS_CACHE | HF_ASSETS_CACHE |
HUGGING_FACE_HUB_TOKEN | HF_TOKEN |
Từ các công cụ bên ngoài
Một số biến môi trường không đặc thù cho huggingface_hub nhưng vẫn được tính đến khi chúng được đặt.
DO_NOT_TRACK
Giá trị Boolean. Tương đương với HF_HUB_DISABLE_TELEMETRY. Khi được đặt thành true, telemetry sẽ bị vô hiệu hóa toàn cục trong hệ sinh thái Python của Hugging Face (transformers, diffusers, gradio, v.v.). Xem https://donottrack.sh/ để biết thêm chi tiết.
NO_COLOR
Giá trị Boolean. Khi được đặt, CLI hf sẽ không in bất kỳ màu ANSI nào.
Xem no-color.org.
XDG_CACHE_HOME
Chỉ được sử dụng khi HF_HOME không được đặt!
Đây là cách mặc định để cấu hình vị trí ghi dữ liệu không thiết yếu (được đệm) cụ thể cho người dùng trên các máy linux.
Nếu HF_HOME không được đặt, thư mục home mặc định sẽ là "$XDG_CACHE_HOME/huggingface" thay vì "~/.cache/huggingface".