26S29a
#repo_id = "Qwen/Qwen3-32B" (17ea)
#repo_id = "deepseek-ai/DeepSeek-R1" (163ea)
repo_id = "openai/gpt-oss-120b" (14ea)
기본 huggingface-cli는 파이썬의 requests 및 urllib3 라이브러리를 기반으로 통신하므로, 쉘에 설정된 표준 프록시 환경변수(http_proxy, https_proxy, HTTP_PROXY, HTTPS_PROXY)를 그대로 인식하여 정상 동작합니다.
다만, 사내 Squid 프록시 환경에서 대용량 가중치(safetensors 등 LFS 파일)를 받을 때 반드시 주의해야 할 3가지 병목/오류 포인트가 있습니다.
1. hf_transfer 사용 시 프록시 인식 문제 (가장 중요)
앞서 추천드린 초고속 다운로더인 hf_transfer(HF_HUB_ENABLE_HF_TRANSFER=1)는 Python이 아닌 Rust의 reqwest 기반으로 동작합니다.
hf_transfer구버전이나 특정 빌드에서는 시스템의https_proxy환경변수를 제대로 파싱하지 못하고 타임아웃/연결 거부(Connection refused) 에러를 뱉는 이슈가 종종 발생합니다.- 대응책:
- 우선 기본 옵션(
HF_HUB_ENABLE_HF_TRANSFER미설정) 상태에서huggingface-cli가 Squid를 통해 잘 동작하는지 먼저 확인하세요. - 고속 전송이 필요해
export HF_HUB_ENABLE_HF_TRANSFER=1을 켰을 때 프록시 연결 에러가 난다면, 해당 옵션을 끄고 기본 다운로더(내장 멀티스레딩)로 받으셔야 합니다.
2. Squid 프록시의 타임아웃 및 요청 바디 크기 제한
DeepSeek 모델의 단일 샤드 파일(safetensors)은 개당 4GB ~ 8GB에 달합니다.
- Squid 설정(
squid.conf)에 다음과 같은 제약이 걸려 있으면 다운로드 도중 연결이 강제로 끊어질 수 있습니다. read_timeout,request_timeout: 대용량 다운로드 중 스트림이 조금만 지연되어도 Squid가 커넥션을 드롭함.maximum_object_size: 캐싱 프록시의 경우 단일 객체 허용 용량을 초과하면 에러 발생.
- 대응책:
- 프록시가
CONNECT터널링(HTTPS Passthrough)을 허용하는 형태라면 문제없으나, 중간에서 응답을 검사/버퍼링하는 구조라면 끊김이 발생할 수 있습니다. - 끊기더라도 이어서 받을 수 있도록 명령어에 재시도 로직을 염두에 두어야 합니다.
3. 사내 사설 SSL/TLS 인증서(CA) 인터셉트 여부
Squid가 SSL Bumping (SSL/TLS 복호화 검사)을 수행하는 환경이라면, curl이나 wget에는 사내 사설 루트 CA 인증서가 등록되어 있어 통과했더라도 파이썬(requests/certifi) 환경에서는 SSL: CERTIFICATE_VERIFY_FAILED 에러가 발생합니다.
- 에러 발생 시 해결법:
사내 루트 CA 인증서 파일 경로를 파이썬 인증서 환경변수에 지정해 주어야 합니다.
export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-bundle.crt # OS별 사내 인증서 bundle 경로
export SSL_CERT_FILE=/etc/ssl/certs/ca-bundle.crt
(보안상 권장하진 않지만, 테스트 목적으로 SSL 검증을 우회해야 한다면 export CURL_CA_BUNDLE="" 등이 사용되기도 합니다.)
권장 실행 스크립트 (점검 및 다운로드)
본격적인 수백 GB 다운로드 전에 경량 설정 파일만 먼저 받아 프록시 통신 여부를 검증하는 것이 좋습니다.
# 1. 대소문자 프록시 환경변수 확인
export http_proxy="http://<squid-ip>:<port>"
export https_proxy="http://<squid-ip>:<port>"
export HTTP_PROXY="http://<squid-ip>:<port>"
export HTTPS_PROXY="http://<squid-ip>:<port>"
# 2. 사내 프록시 관통 테스트 (config.json 파일 하나만 먼저 다운로드)
huggingface-cli download deepseek-ai/DeepSeek-R1 config.json --local-dir ./test-r1
# 3. 2번이 정상 완료되면 본 다운로드 실행
# (안정성을 위해 symlink 없이, 백그라운드 tmux/screen 세션에서 실행 권장)
huggingface-cli download deepseek-ai/DeepSeek-R1 \
--local-dir /target/path/DeepSeek-R1 \
--local-dir-use-symlinks False
===
네, huggingface_hub 최신 버전에서 CLI 진입점이 hf로 통합 및 개편되었습니다. 이 hf download 명령어 역시 내부적으로 동일한 Python 다운로드 엔진을 사용하므로, 기존에 설정해 두신 Squid 프록시 환경변수(http_proxy, https_proxy)가 그대로 적용됩니다.
다만, 제공해주신 템플릿을 DeepSeek-R1(또는 R1-Distill)에 적용할 때 Squid 환경에서 문제없이 돌리기 위한 몇 가지 핵심 체크포인트가 있습니다.
1. DeepSeek-R1에 맞춘 다운로드 스크립트 작성
DeepSeek-R1 Full 모델은 총 163개의 safetensors 샤드(model-00001-of-00163.safetensors ~ model-00163-of-00163.safetensors)로 구성되어 있습니다. Qwen3-32B처럼 특정 범위 패턴을 수동 지정하면 샤드를 누락할 위험이 있으므로, 샤드 전체를 받거나 필요 없는 파일만 제외하는 방식이 안전합니다.
#!/usr/bin/env bash
# 1. 사내 Squid Proxy 환경변수 (소문자/대문자 모두 세팅)
export http_proxy="http://<squid-ip>:<port>"
export https_proxy="http://<squid-ip>:<port>"
export HTTP_PROXY="http://<squid-ip>:<port>"
export HTTPS_PROXY="http://<squid-ip>:<port>"
# (사내 SSL Bumping/인증서 검사가 있는 경우 인증서 경로 지정)
# export REQUESTS_CA_BUNDLE=/etc/pki/tls/certs/ca-bundle.crt
EXPORT_DIR="/data"
MODEL_ID="deepseek-ai/DeepSeek-R1"
TARGET_DIR="${EXPORT_DIR}/models/DeepSeek-R1"
# 2. hf download 실행
hf download "${MODEL_ID}" \
--local-dir "${TARGET_DIR}" \
--exclude "original/*" "*.pt" "*.bin" \
--include "*.json" "*.txt" "*.py" "*.safetensors" \
--token "$HF_TOKEN"
참고: Distill 모델(예:
deepseek-ai/DeepSeek-R1-Distill-Qwen-32B)을 받는 경우라면 파일 개수가 적으므로 위 룰 그대로 바로 받으시면 됩니다.
2. Squid 프록시 환경에서 hf download 실행 시 주의점
--exclude/--include패턴 적용 시:
- 위 예시처럼 작성하셨던
model-0000[1-9]-*.safetensors같은 glob 패턴은 파일이 수십~수백 개로 쪼개진 대형 모델에서 잘못 설정하면 중간 샤드가 통째로 스킵될 수 있습니다.*.safetensors로 와일드카드를 주거나, 필요 없는 대용량 형식(*.pt,*.bin)을--exclude로 걸러내는 형태가 누락 방지에 유리합니다.
- Squid 장시간 커넥션 끊김 대비 (Resume 기능):
- 대용량 다운로드 중 Squid 프록시의 세션 타임아웃 등으로 연결이 끊기더라도,
hf download는 이미 받은 블록의 해시를 비교하여 자동 이어받기(Resume)를 지원합니다. 스크립트가 도중에 죽더라도 같은 명령어를 다시 실행하면 받은 부분 이후부터 계속 내려받습니다.
- Rust
hf_transfer사용 주의:
hf명령어로 바뀌었어도HF_HUB_ENABLE_HF_TRANSFER=1환경변수가 활성화되어 있으면 내부적으로 Rust 백엔드를 호출합니다. 프록시 환경에서 핸드셰이크 오류나 커넥션 거부가 뜬다면 이 환경변수를unset하고 기본 파이썬 세션으로 진행하세요.
