8.3. 모델 허브 미러 (내부 Hugging Face)¶

Backend.AI GO는 기본적으로 공개 Hugging Face 허브(https://huggingface.co)에서 모델을 검색하고 다운로드합니다. 관리자는 모델 허브를 내부 미러(자체 호스팅한 Hugging Face 호환 서버)로 연결하거나, 모델 검색과 다운로드를 완전히 끌 수 있습니다. 이 기능은 관리형 서비스 엔드포인트 설정(endpoints.modelHub)의 일부이며, 커스텀 미러나 비활성화 모드가 적용되면 egress 방화벽이 공개 허브로 향하는 요청을 차단합니다.

이 문서에서 다루는 내용:

모델 허브의 세 가지 모드(기본 / 커스텀 미러 / 비활성화).
설정 화면이나 관리형 정책에서 구성하는 방법.
미러 레이아웃 규약: 검색, 둘러보기, 모델 상세, 파일 목록, 다운로드가 동작하도록 내부 미러가 노출해야 하는 정확한 URL 경로.

사용 상황¶

huggingface.co에 접근할 수 없거나 차단되어 있고, 승인된 모델을 내부 미러가 보유하는 에어갭 또는 제한된 네트워크. (완전 오프라인 .baimodel 워크플로는 오프라인 전용 설정도 참고하세요.)
모든 모델 트래픽이 검증된 내부 호스트를 거쳐야 하는 규정 준수 환경.
사용자가 조직이 이미 준비한 모델만 실행하도록 모델 획득을 비활성화하려는 경우.

모드¶

모델 허브는 관리형 서비스 엔드포인트 중 하나이며 세 가지 모드를 가집니다.

모드	동작
`default`	공개 Hugging Face 허브(`https://huggingface.co`)를 사용합니다. 기존 동작과 동일합니다.
`custom`	운영자가 지정한 기본 URL(내부 미러)을 사용합니다. 모든 API와 다운로드 트래픽이 해당 호스트로 향합니다.
`disabled`	모델 검색, 둘러보기, 상세, 파일 목록, 다운로드가 모두 꺼집니다. 모델 브라우저는 "모델 허브가 비활성화됨" 상태를 표시하고 네트워크 요청을 보내지 않습니다.

강제 적용 중인 관리형 배포에서 custom 미러를 구성하면 미러 호스트가 egress 허용 목록에 자동으로 추가되며, default 모드에서는 공개 huggingface.co 호스트가 계속 차단됩니다. egress.allowedHosts를 직접 편집할 필요가 없습니다.

설정 화면에서 구성¶

설정 → 관리형 엔드포인트를 엽니다.
모델 허브 엔드포인트를 찾습니다.
모드를 선택합니다.
커스텀: 미러 기본 URL(예: https://hf.internal.example)을 입력합니다. 필요하면 인증 방식, 엔드포인트별 CA 번들, 프록시를 설정합니다.
비활성화: 허브를 끕니다.
테스트로 구성한 기본 URL이 방화벽을 통해 도달 가능한지 확인합니다.

모델 허브가 중앙 정책으로 관리되는 경우, 해당 필드에는 "조직에서 관리함" 배지가 표시되고 읽기 전용이 됩니다.

관리형 정책에서 구성¶

모델 허브는 AppSettings 필드이므로, 관리형 정책은 표준 settingsOverrides 병합 패치와 lockedPaths를 통해 이를 제어합니다. 예를 들어 모든 장치를 내부 미러로 고정하고 잠그려면 다음과 같이 작성합니다.

{
  "settingsOverrides": {
    "endpoints": {
      "modelHub": {
        "mode": "custom",
        "baseUrl": "https://hf.internal.example",
        "authMethod": "bearer"
      }
    }
  },
  "lockedPaths": ["endpoints.modelHub"]
}

모델 획득을 완전히 끄려면 다음과 같이 작성합니다.

{
  "settingsOverrides": {
    "endpoints": { "modelHub": { "mode": "disabled" } }
  },
  "lockedPaths": ["endpoints.modelHub"]
}

인증¶

미러는 인증을 요구할 수 있습니다. 모델 허브 엔드포인트는 표준 엔드포인트 인증 방식(bearer, api_key, basic, mtls)을 그대로 사용합니다. 기존 Hugging Face 토큰(설정 → Hugging Face)은 Bearer 헤더로 매핑되며, 공개 허브와 미러 모두에서 게이트된 모델에 계속 사용됩니다. 자격 증명 값 자체는 OS 키체인에만 저장되며, 설정 파일이나 list/get 응답에는 기록되지 않습니다.

미러 레이아웃 규약¶

내부 미러는 공개 Hugging Face 허브와 동일한 URL 레이아웃을 노출해야 합니다. Backend.AI GO가 구성한 하나의 기본 URL에서 API 기본 주소와 다운로드 기본 주소를 모두 만들어 내기 때문입니다.

API 기본 주소 = <baseUrl>/api
다운로드 기본 주소 = <baseUrl>

따라서 baseUrl = https://hf.internal.example이면 API 기본 주소는 https://hf.internal.example/api, 다운로드 기본 주소는 https://hf.internal.example입니다.

미러는 다음 경로를 제공해야 합니다. {id}는 publisher/name 형식의 모델 id입니다(예: TheBloke/Llama-2-7B-GGUF).

API 엔드포인트 (`<baseUrl>/api` 하위)¶

메서드	경로	용도	응답 형태
`GET`	`/api/models?search={query}&filter={tag}&sort=downloads&direction=-1&limit={n}&skip={n}`	검색	모델 객체의 JSON 배열. `filter`는 `gguf` 또는 포맷 태그이며, 둘러보기 시 `pipeline_tag={tag}`가 추가될 수 있습니다.
`GET`	`/api/models?filter={tag}&sort={field}&direction=-1&limit={n}&skip={n}`	둘러보기(쿼리 없음)	동일한 JSON 배열. `sort`는 `downloads`, `likes`, `lastModified`, `trendingScore` 중 하나입니다.
`GET`	`/api/models/{id}`	모델 상세	단일 모델 JSON 객체.
`GET`	`/api/models/{id}/tree/main?recursive=true`	파일 트리	파일 항목의 JSON 배열(`{ "type": "file", "path": "...", "size": N, "lfs": { "size": N, "oid": "sha256:..." } }`).

모델 JSON 객체와 파일 JSON 객체는 공개 허브가 반환하는 것과 동일한 필드 이름을 가져야 합니다(클라이언트는 id, modelId, author, downloads, likes, tags, siblings/파일 항목, lfs.size, lfs.oid/sha256 등을 역직렬화합니다). 호환성을 보장하는 가장 간단한 방법은 제공하는 모델에 대해 업스트림 JSON을 그대로 미러링하는 것입니다.

다운로드 엔드포인트 (`<baseUrl>` 하위)¶

메서드	경로	용도
`GET`	`/{id}/resolve/main/{file}`	모델 파일(GGUF / safetensors 샤드) 다운로드. 파일 바이트를 스트리밍하고 재개를 위해 HTTP range 요청을 지원해야 합니다.
`GET`	`/{id}/raw/main/README.md`	모델 카드(README) 표시. 없으면 `404`를 반환합니다.
`GET`	`/{id}/raw/main/tokenizer_config.json`	채팅 템플릿 추출 대체 경로. 없으면 `404`를 반환합니다.

스킴과 호스트 규칙¶

루프백이 아닌 미러는 반드시 https://를 사용해야 합니다. 다운로드 URL 허용 목록은 huggingface.co / cdn.huggingface.co에 더해 구성한 미러 호스트를 허용합니다.
루프백 인터페이스(127.0.0.1, localhost, ::1)의 미러는 TLS가 없는 내부 에어갭 서버를 위해 http://를 사용할 수 있습니다.
중단된 다운로드가 올바르게 재개되도록 미러는 resolve 경로에서 HTTP range 요청을 지원해야 합니다.

최소 미러 체크리스트¶

검색과 둘러보기를 위해 Hugging Face 형태의 JSON 배열을 반환하는 GET /api/models?... 제공.
모델 상세 객체를 반환하는 GET /api/models/{id} 제공.
크기와 LFS 해시를 포함한 파일 트리를 반환하는 GET /api/models/{id}/tree/main?recursive=true 제공.
바이트 스트리밍과 range를 지원하는 GET /{id}/resolve/main/{file} 제공.
GET /{id}/raw/main/README.md와 GET /{id}/raw/main/tokenizer_config.json 제공(또는 404).
HTTPS 사용(미러가 루프백 전용인 경우 제외).

비활성화 모드 동작¶

모델 허브가 disabled이면 다음과 같이 동작합니다.

모델 → 둘러보기 탭은 검색 상자 대신 엔드포인트 설정으로 이동하는 링크가 있는 "모델 허브가 비활성화됨" 패널을 표시합니다.
검색, 둘러보기, 모델 상세, 파일 목록, 다운로드는 어떤 호스트에도 접속하지 않고 명확한 "정책에 의해 비활성화됨" 결과를 반환합니다.
이미 다운로드한 모델은 정상적으로 로드되고 실행됩니다. 새 모델의 획득만 꺼집니다.