본 가이드는 JFrog Artifactory의 Hugging Face ML Remote Repository를 통해 공개 모델을 다운로드하고, Xray 인덱싱 및 분석 상태를 확인하는 방법을 설명합니다.


1. 개요 및 구성

Hugging Face 모델 다운로드는 Hugging Face SDK(huggingface_hub) 사용을 기본 검증 방식으로 합니다. 단일 파일을 curl로 요청하는 방식은 파일 수신과 캐시 여부의 점검에는 사용할 수 있으나, 모델 단위의 메타데이터·인덱싱 검증을 대체하지 않습니다.

Hugging Face (Public)
         ↓
Artifactory Hugging Face ML Remote
         ↓
     개발자 / CI (huggingface_hub)
         ↓
Artifactory Cache → Xray Indexed Resources → Scan List

설치환경

구분예시 및 확인 사항
운영체제Ubuntu / RHEL 9.x / Python 3
패키지 유형Hugging Face ML (huggingfaceml)
Repository Keyhuggingface-remote (환경에 맞게 변경)
Artifactory URLhttps://<JFROG_HOST>
Xray설치 버전, 라이선스, Indexed Resources 상태는 환경별 확인

2. 사전 준비

다운로드를 실행할 호스트에서 Artifactory 엔드포인트에 접근할 수 있어야 합니다.

Anonymous 다운로드를 사용하려면 Artifactory의 Allow Anonymous Access를 활성화하고, 대상 Hugging Face ML Repository에 anonymous 사용자의 Read 권한을 부여해야 합니다.
Administration → User Management → Permissions에서 대상 Repository에 대한 Anonymous 전용 Read Permission을 구성합니다. 

예시)

설정

값

Permission Name

HF_Anonymous_Read_Test (테스트용 예시)

Resources

hf-remote

Users

anonymous

권한

Read만 허용


정확한 SDK 접속 주소는 해당 Repository의 Set Me Up 화면을 우선 확인합니다.

python3 --version
python3 -m pip --version
# Repository 별 Set Me Up 값 확인
# https://<JFROG_HOST>/artifactory/api/huggingfaceml/<REPO_KEY>
export HF_HUB_ETAG_TIMEOUT=86400
export HF_HUB_DOWNLOAD_TIMEOUT=86400

Access Token, 암호, 인증서 비밀키를 Confluence 본문이나 명령행 기록에 저장하지 않습니다. HTTP 주소는 인증 토큰을 암호화하지 않으므로 승인된 실험망이 아니라면 HTTPS를 사용합니다.

3. Python 가상환경 및 SDK 설치

운영 서버에서는 패키지 설치 승인 및 사내 미러 정책을 따릅니다.

Python 가상환경 구성 (RHEL예시)

# 환경의 패키지 제공 여부 확인 후 설치
sudo dnf install -y python3.11 python3.11-pip
umask 077
mkdir -p ~/hf-sdk-test
cd ~/hf-sdk-test
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "huggingface_hub==0.36.0"
python -c 'import sys, huggingface_hub; print(sys.version); print(huggingface_hub.__version__)'

Python 가상환경 구성 (Ubuntu 예시)

sudo apt-get update
sudo apt-get install -y python3 python3-venv python3-pip
umask 077
mkdir -p ~/hf-sdk-test
cd ~/hf-sdk-test
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "huggingface_hub==0.36.0"
python -c 'import sys, huggingface_hub; print(sys.version); print(huggingface_hub.__version__)'



4. Hugging Face 모델 다운로드

아래는 검증용 경량 모델 sshleifer/tiny-distilbert-base-cased의 설정 파일과 가중치 파일을 다운로드하는 예시입니다. 실제 주소는 환경의 Set Me Up 값으로 교체합니다.

# Hugging Face Repository 설정
export HF_ENDPOINT="https://<JFROG_HOST>/artifactory/api/huggingfaceml/huggingface-remote"

# 네트워크 타임아웃 설정 (선택)
export HF_HUB_ETAG_TIMEOUT=86400
export HF_HUB_DOWNLOAD_TIMEOUT=86400

# Xet 호환성 문제 발생 시 설정 (선택)
export HF_HUB_DISABLE_XET=1

# 기존 인증 환경변수 사용 방지
unset HF_TOKEN HUGGING_FACE_HUB_TOKEN
export HF_HUB_DISABLE_IMPLICIT_TOKEN=1

# JFrog Access Token 입력 (선택)
read -rsp "JFrog Token: " HF_TOKEN
echo
export HF_TOKEN

# Hugging Face 모델 다운로드
python - <<'PY'
from huggingface_hub import snapshot_download

path = snapshot_download(
    repo_id="sshleifer/tiny-distilbert-base-cased",
    revision="main",
    allow_patterns=["config.json", "pytorch_model.bin"],
    local_dir="./hf-model-test"
)

print("Download Success:", path)
PY

# 다운로드 결과 확인
ls -lh ./hf-model-test/

# Token 제거 (선택 : Token 셋팅한 경우)
unset HF_TOKEN

다운로드 명령이 정상 종료하고 config.json, pytorch_model.bin이 존재하는지 확인합니다. 토큰 인증 방식은 Artifactory 서버와 SDK 버전에 따라 조정될 수 있습니다.


5. Scans List 확인

1. Artifactory 캐시 확인

Artifactory의 Artifacts 메뉴에서 해당 Remote Repository의 캐시를 확인합니다. 다음 Storage API는 운영 관리자가 파일의 존재와 체크섬을 확인하는 데 사용합니다.

# Token 설정시 (선택)
read -rsp "JFrog Access Token: " TOKEN; echo

BASE="https://<JFROG_HOST>"
REPO="huggingface-remote"
FILE="sshleifer/tiny-distilbert-base-cased/resolve/main/pytorch_model.bin"

# Token 사용 여부에 따라서 A나 B중에서 진행
# A: Token 인증 있는 캐시 조회 
curl -fsS -H "Authorization: Bearer ${TOKEN}"   "$BASE/artifactory/api/storage/$REPO/$FILE"
# B : 인증 없는 캐시 조회
curl -fsS \
  "$BASE/artifactory/api/storage/$REPO/$FILE"

# Token 설정시 (선택)
unset TOKEN

repo, path, size, checksums가 반환되면 해당 경로의 파일 캐싱을 확인한 것입니다. 실제 내부 캐시 키는 hf-remote-cache로 나타날 수 있습니다.


2. Xray 인덱싱 확인

  1. JFrog 관리자 화면에서 Administration → Xray → Indexed Resources를 엽니다.
  2. 대상 Hugging Face ML Repository가 포함되어 있는지 확인합니다.
  3. 기존 파일을 확인해야 하는 경우 Index Existing을 실행합니다.
  4. 진행 수치와 인덱싱 완료 여부를 확인한 뒤 Xray → Scans List에서 해당 모델 또는 Repository를 조회합니다.
  5. 필요하면 Xray System Messages 및 Indexer 로그를 확인합니다.


# Docker Compose 운영 환경의 컨테이너명 확인 후 실행
docker ps --format '{{.Names}}'
docker logs --since 30m xray_indexer 2>&1   | grep -Ei 'hf-remote|huggingface|index|error|fail|skip'

다운로드 성공, 캐시 생성, Indexed Resources 등록, 인덱싱 완료, Scan List 등록은 각각 별도 확인 항목입니다. 0/0이나 NOT_SUPPORTED만으로 라이선스 부족 또는 장애 원인을 단정하지 않습니다.


3. 운영 시 주의사항

  • 실제 운영 저장소 변경이나 대규모 Index Existing 작업은 영향도를 확인한 뒤 수행합니다.
  • 공개 모델도 파일 형식, 버전, 보안 정책에 따라 분석 범위가 달라질 수 있습니다.
  • ML 모델 자체에 일반 CVE가 표시되지 않을 수 있으며, 모델 식별·라이선스·악성 모델 탐지와 일반 패키지 SCA는 구분합니다.
  • 고객 환경의 HTTPS 및 신뢰 CA를 사용하고, 테스트 목적의 curl -k를 운영 기본 명령으로 사용하지 않습니다.
  • 실패 시 반복 다운로드보다는 별도 Hugging Face Xray 인덱싱 트러블슈팅 가이드를 참고합니다.

4. 관련 문서

검증 기록 작성 시 실행 환경, Repository Key, SDK/Xray 버전, 다운로드·인덱싱·Scan List 결과를 구분하여 기록합니다.

  • 레이블 없음