Hugging Face Hub 타임아웃? Clash 모델·API 분기(2026)

증상: 웹은 되는데 모델 파일·API만 끊길 때

2024년부터 2026년까지 오픈 가중치와 Hugging Face Hub는 연구·제품 양쪽에서 사실상 표준 워크플로에 가깝습니다. 그런데 네트워크 환경에 따라 증상이 이렇게 갈라지는 경우가 많습니다. 첫째, 모델 카드·문서 페이지는 HTML이 빨리 뜨는데 수십 GB짜리 샤드를 받다가 중간에 연결 리셋·타임아웃이 난다. 둘째, git clone은 끝났는데 Git LFS 객체를 가져올 때만 재시도 루프에 빠진다. 셋째, 브라우저는 괜찮은데 Python의 huggingface_hub·transformers가 hf.co 단축 URL이나 Hub API 호스트로 나가는 구간에서만 실패한다. 넷째, Inference API(또는 엔드포인트형 호스팅) 호출이 간헐적으로 5xx·타임아웃으로 끊기고, 같은 노드로 일반 웹만 다시 열어보면 또 된다.

이 패턴의 공통점은 한 서비스 안에서도 호스트·경로·프로토콜이 여럿으로 쪼개진다는 것입니다. Hub 웹 UI, 모델 저장소 API, LFS·CDN성 호스트, 추론 게이트웨이는 서로 다른 FQDN으로 TLS 핸드셰이크를 열고, 클라이언트는 짧은 시간에 다수의 병렬 연결을 만듭니다. 그중 일부만 DIRECT로 새거나, 지나치게 넓은 GEOIP·RULE-SET에 먼저 걸려 원치 않는 출구로 나가면 체감상 「가끔만」 실패하는 것처럼 보입니다. 따라서 Clash 분류 규칙으로 Hugging Face 관련 접미사를 한 프록시 그룹(또는 대용량 전용과 API 전용으로 분리한 두 그룹)에 고정하고, 연결 로그·DNS로 기대한 노드가 맞는지 확인하는 흐름이 필요합니다.

벤더 브랜드가 다른 ChatGPT·OpenAI, Gemini·Google AI 글과 겹치지 않게, 여기서는 Hugging Face 도메인·모델 다운로드·HF Hub API·Inference 축에만 초점을 맞춥니다. 호스트 표는 제품 업데이트로 늘 수 있으니 아래는 출발점이며, 본인 클라이언트의 최근 연결 목록을 기준으로 룰셋을 유지보수하세요.

⚠️

준수 안내: 프록시 사용과 Hugging Face 서비스 이용은 거주 지역 법령과 Hugging Face 이용약관·모델 라이선스를 따라야 합니다. 본문은 네트워크 경로와 Clash 설정 기술만 다루며, 규제 회피나 약관 위반을 조장하지 않습니다.

묶을 호스트: Hub, 단축 도메인, LFS, Inference

실무에서 반복되는 축은 대략 다음과 같습니다. 웹·저장소 UI는 huggingface.co 아래에 모이고, 링크·리다이렉트에 hf.co 단축 호스트가 자주 등장합니다. 대용량 아티팩트는 LFS·스토리지·CDN 성격의 서브도메인으로 퍼지며, 클라이언트와 리전에 따라 서로 다른 FQDN이 찍히기도 합니다. Inference API 계열은 api-inference.huggingface.co 같은 호스트명으로 정리되는 경우가 많고, 팀에서 프라이빗 게이트웨이나 엔터프라이즈 엔드포인트를 쓰면 목록이 더 늘어납니다.

그래서 첫 단계에서는 DOMAIN-SUFFIX,huggingface.co와 DOMAIN-SUFFIX,hf.co처럼 접미사 단위로 넓게 잡고, 연결 패널에서 실제로 트래픽이 새는 호스트를 확인한 뒤 필요하면 rule-providers YAML에 한 줄씩 좁히는 방식이 재현성이 높습니다. DOMAIN-KEYWORD,hugging처럼 지나치게 모호한 규칙은 다른 사이트까지 끌어올 수 있으니 피하는 편이 낫습니다. 반대로 huggingface.co만 넣고 hf.co를 빼 두면, 라이브러리가 단축 URL로만 나가는 경로에서 다시 증상이 재발하기 쉽습니다.

대용량 다운로드와 짧은 API 호출을 같은 물리 회선에 얹고 싶지 않다면, 규칙을 두 층으로 나누는 것도 방법입니다. 예를 들어 LFS·스토리지 후보만 HF-LFS 그룹, 나머지 Hub·Inference는 HF-HUB 그룹으로 보내면, 장시간 전송이 짧은 요청의 지연·재시도를 흔들 가능성을 줄일 수 있습니다. 다만 호스트 경계가 흐릿하면 오히려 규칙이 복잡해지므로, 우선은 단일 그룹으로 고정해 로그를 모은 뒤 분리하는 순서를 추천합니다.

규칙 순서: GEOIP·거대 룰셋보다 앞에 둘 것

rules에서 가장 흔한 실수는 순서입니다. GEOIP,CN,DIRECT나 거대한 RULE-SET이 Hugging Face 호스트를 먼저 직결이나 다른 그룹으로 보내버리면, 아래에 정교한 규칙을 아무리 추가해도 도달하지 못합니다. 중국 본토 직결과 해외 프록시를 함께 쓰는 패턴은 규칙 분류 실무 글과 함께 읽으면 전체 그림이 잡힙니다. 구독을 막 넣었다면 구독 가져오기에서 노드·그룹 이름이 실제로 로드됐는지도 먼저 확인하세요.

HF 전용 그룹 이름(예: HF-HUB)을 규칙에 쓸 때는 YAML 전체에서 오타 없이 동일한 문자열인지 확인합니다. 존재하지 않는 그룹을 가리키면 프로필이 로드되지 않습니다. MATCH 직전까지 Hub 관련 규칙이 올라와 있는지 한 번 더 훑는 습관이 안정적 모델 다운로드에 도움이 됩니다.

전략 그룹: 대용량 전송과 짧은 API 호출

proxy-groups 설계에서 Hub는 두 가지 부하가 겹칩니다. 하나는 수 GB~수십 GB 연속 스트림, 다른 하나는 짧은 HTTPS JSON입니다. (1) select로 지금 쓸 회선을 수동 고정하면 재현성이 좋습니다. (2) url-test로 자동 선택할 때는 너무 짧은 interval이 긴 다운로드 중간에 노드를 바꿔 세션을 끊을 수 있으니 값은 보수적으로 잡습니다. (3) fallback은 장애 대비에 유용하지만, 전송 중 빈번한 페일오버는 재개(resume) 없는 클라이언트에서 처음부터 다시 받게 만들 수 있습니다.

그룹 안에 DIRECT를 남겨 두면 비교 실험에는 유용하지만, 「브라우저만 되고 CLI만 실패한다」는 신고가 있을 때 직행이 섞였는지 가리기 어렵습니다. 진단 단계에서는 한동안 DIRECT를 빼고 동일 시나리오를 반복해 보는 것도 방법입니다.

CLI·라이브러리: 시스템 프록시를 안 탈 때

브라우저는 시스템 프록시를 따르는데, 터미널의 git·python만 프록시를 타지 않고 나가면 증상이 더 미묘해집니다. Mihomo 계열에서는 PROCESS-NAME 규칙으로 특정 실행 파일을 전용 그룹에 매핑할 수 있습니다. 다만 프로세스 이름은 OS·가상환경마다 달라지므로 실측 로그를 기준으로 유지보수하세요.

앱 전체를 코어에 넣고 싶다면 TUN 모드로 트래픽을 일괄 흡수하는 방법도 있습니다. macOS·Linux에서 환경 변수를 쓰는 흐름은 터미널·Homebrew 프록시 환경 변수 글과 짝을 이루도록 읽을 수 있습니다. Hugging Face 공식 클라이언트는 프록시 환경 변수를 존중하는 편이라, 규칙이 맞는데도 라이브러리만 실패하면 터미널 측 프록시 계층을 우선 의심합니다.

YAML 스케치(이름·접미사는 실측으로 교체)

아래는 구조를 보여 주는 예시입니다. HF-HUB, 멤버 프록시 이름, 접미사는 반드시 본인 프로필과 연결 로그에 맞게 바꿔야 합니다.

# Example only — replace names and suffixes with your profile and logs
proxy-groups:
  - name: HF-HUB
    type: select
    proxies:
      - Proxy
      - AUTO
      - DIRECT

rules:
  - DOMAIN-SUFFIX,huggingface.co,HF-HUB
  - DOMAIN-SUFFIX,hf.co,HF-HUB
  - DOMAIN,api-inference.huggingface.co,HF-HUB
  # Optional: split LFS-heavy hosts when logs show distinct FQDNs
  # - DOMAIN-SUFFIX,cdn-lfs.huggingface.co,HF-LFS
  # Optional: pin a CLI when system proxy is ignored
  # - PROCESS-NAME,git,HF-HUB
  # - PROCESS-NAME,python3,HF-HUB
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

실제 환경에서는 Inference 전용 호스트가 추가로 보이거나, 팀 게이트웨이가 별도 도메인을 쓸 수 있습니다. 외부 rule-providers를 쓴다면 갱신 주기와 로컬 규칙과의 우선순위를 함께 점검하세요.

DNS·fake-ip: 간헐 실패의 숨은 원인

fake-ip 모드에서는 규칙 매칭은 빠르지만, 특정 호스트에서 해석·캐시가 어긋나면 클라이언트가 보기에도 「가끔만」 실패합니다. 긴 다운로드는 중간에 DNS 재해석·재연결이 섞이면 더 드물게 끊깁니다. 반복되는 FQDN은 fake-ip-filter에 넣거나, nameserver와 fallback 체인을 재검토하세요. 자세한 절차는 Fake-IP·DNS 실측 가이드와 함께 보는 것이 좋습니다.

브라우저와 CLI의 DNS 경로가 다르면, 같은 규칙이라도 서로 다른 IP로 붙어 출구가 갈라지는 일이 생깁니다. 이때는 코어 DNS와 OS DNS를 한 흐름으로 맞추는지부터 확인합니다.

연결·다운로드 자가 점검 절차

모델 페이지에서 작은 파일과 큰 샤드를 나눠 받아 보고, 최근 연결에 뜬 FQDN을 메모합니다.
git lfs pull 또는 huggingface-cli download를 한 번 돌려, LFS·Hub API 호스트가 어떤 규칙·그룹으로 잡히는지 비교합니다.
Inference 호출 한 번을 보내 api-inference.huggingface.co(또는 로그에 찍힌 호스트)가 의도한 그룹인지 확인합니다.
지연이 큰 노드로 바꿔 보고 오류 패턴이 따라오는지 봅니다. 변하지 않으면 규칙·DNS·터미널 프록시 쪽을 우선 의심합니다.
기업 VPN·보안 에이전트와 경로가 겹치지 않는지 확인합니다.

보안·운영 메모

프록시 노드는 트래픽을 중계할 수 있으므로 신뢰할 수 있는 구독을 전제로 합니다. 회사 장비에서는 정책 위반이 될 수 있으니 사내 가이드를 우선합니다. Hub 토큰·API 키는 저장소와 로그에 남지 않게 관리하고, 팀과 룰셋을 공유할 때는 변경 이력을 남기세요. 모델 라이선스·사용 조건은 저장소 README와 카드 메타데이터를 함께 확인합니다.

체크리스트

huggingface.co·hf.co 규칙이 넓은 GEOIP·MATCH보다 앞에 있는가.
Inference·LFS 후보 호스트가 의도한 그룹으로 매칭되는가.
프록시 그룹 이름이 YAML 전체에서 일관되는가.
DNS 모드·fake-ip-filter가 최근 로그와 모순되지 않는가.
TUN·시스템 프록시·프로세스 규칙·터미널 환경 변수 중 무엇을 쓰는지 일치하는가.

정리

Hugging Face Hub는 웹 UI·모델 API·LFS·Inference가 서로 다른 호스트 패턴을 씁니다. 도메인 분류로 출구를 고정하고, 필요하면 PROCESS-NAME이나 TUN으로 CLI까지 묶으며, 연결 로그와 DNS로 기대한 경로인지 검증하면, 대용량 모델 다운로드와 HF Hub·Inference API 호출이 끊기는 간헐 증상을 줄이기 쉽습니다. 목록은 한 번에 완벽할 필요가 없고, 클라이언트가 알려 주는 새 호스트를 주기적으로 룰셋에 반영하는 방식이 장기적으로 가장 덜 깨집니다.

클라이언트를 최신 Mihomo 계열로 맞추는 일도 체감에 영향을 줍니다. 플랫폼별 패키지는 공식 다운로드 페이지에서 고를 수 있습니다. 기본 개념은 문서 섹션과 함께 보시면 설정 속도가 빨라집니다. → Clash를 무료로 내려받아 규칙을 적용한 뒤, 브라우저와 터미널에서 Hub·Inference 호출을 다시 시험해 보세요.