# 명령줄 인터페이스(CLI) `huggingface_hub` Python 패키지에는 `hf`라는 내장 CLI가 포함되어 있습니다. 이 도구를 사용하면 터미널에서 Hugging Face Hub와 직접 상호작용할 수 있습니다. 예를 들어, 계정에 로그인하거나 저장소를 생성하고, 파일을 업로드 및 다운로드하는 등의 작업을 수행할 수 있습니다. 또한 머신을 구성하거나 캐시를 관리하는 데 유용한 기능도 제공합니다. 이 가이드에서는 CLI의 주요 기능과 사용법을 살펴보겠습니다. > [!TIP] > 이 가이드는 `hf` CLI의 가장 중요한 기능을 다룹니다. 모든 명령어와 옵션에 대한 전체 참고 문서는 [CLI 참고 문서를](../package_reference/cli) 참조하세요. > [!TIP] > AI 에이전트와 함께 `hf` CLI를 사용하시나요? Skill을 설치하고 [Hugging Face CLI for AI Agents](https://huggingface.co/docs/hub/agents-cli) 가이드를 확인해 보세요. > ```bash > # works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills` > hf skills add > ``` > 독립 설치 프로그램이 이를 설치해 줍니다(아래 참조). `hf update`로 업데이트할 수 있습니다. ## 시작하기 ### 독립 설치 프로그램 (권장) `hf` CLI를 하나의 명령어로 설치할 수 있습니다: macOS 및 Linux에서: ```bash >>> curl -LsSf https://hf.co/cli/install.sh | bash ``` Windows에서: ```powershell >>> powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex" ``` 설치 프로그램은 Claude Code 및 `~/.agents/skills`를 읽는 모든 에이전트를 위해 [`hf-cli` 스킬](https://huggingface.co/docs/hub/agents-cli)을 전역으로 설치합니다. 이를 건너뛰려면 `--exclude-skill`를 전달하세요: ```bash >>> curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skill ``` ```powershell >>> powershell -ExecutionPolicy ByPass -c "& ([scriptblock]::Create((irm https://hf.co/cli/install.ps1))) -ExcludeSkill" ``` 설치 후 CLI가 올바르게 설정되었는지 확인할 수 있습니다: ```bash >>> hf --help Usage: hf [OPTIONS] COMMAND [ARGS]... Hugging Face Hub CLI Options: --skills Print the `hf-cli` SKILL.md to stdout (alias for `hf skills preview`). --install-completion Install completion for the current shell. --show-completion Show completion for the current shell, to copy it or customize the installation. -h, --help Show this message and exit. Main commands: auth Manage authentication (login, logout, etc.). buckets Commands to interact with buckets. cache Manage local cache directory. collections Interact with collections on the Hub. datasets Interact with datasets on the Hub. download Download files from the Hub. endpoints Manage Hugging Face Inference Endpoints. extensions Manage hf CLI extensions. jobs Run and manage Jobs on the Hub. models Interact with models on the Hub. papers Interact with papers on the Hub. repos Manage repos on the Hub. skills Manage skills for AI assistants. spaces Interact with spaces on the Hub. sync Sync files between local directory and a bucket. upload Upload a file or a folder to the Hub. Help commands: env Print information about the environment. version Print information about the hf version. ``` CLI가 올바르게 설치되어 있다면 CLI에서 사용할 수 있는 모든 옵션 목록이 표시됩니다. `command not found: hf`와 같은 오류 메시지가 표시되면 [설치](../installation) 가이드를 참고하세요. > [!TIP] > `--help` 옵션은 명령에 대한 더 자세한 정보를 얻는 데 매우 유용합니다. 언제든지 사용 가능한 모든 옵션과 그 세부 사항을 나열하는 데 사용할 수 있습니다. 예를 들어, `hf upload --help`는 CLI를 사용하여 파일을 업로드하는 방법에 대한 추가 정보를 제공합니다. ### uv 사용 `hf` CLI를 사용하는 가장 쉬운 방법은 [`uvx`](https://docs.astral.sh/uv/concepts/tools/)를 사용하는 것입니다. 항상 격리된 환경에서 최신 버전을 실행하므로 설치 과정이 필요 없습니다! `uv`가 먼저 설치되어 있는지 확인하세요. 설치 방법은 [uv 설치 가이드](https://docs.astral.sh/uv/getting-started/installation/)를 참고하세요. 그 후 CLI를 직접 사용합니다: ```bash >>> uvx hf auth login >>> uvx hf download >>> uvx hf ... ``` > [!TIP] > `uvx hf`는 [`hf` PyPI 패키지](https://pypi.org/project/hf/)를 사용합니다. ### pip으로 설치 CLI는 또한 핵심 `huggingface_hub` 패키지와 함께 제공됩니다: ```bash >>> pip install -U "huggingface_hub" ``` ### Homebrew 사용 [Homebrew](https://brew.sh/)를 사용하여 CLI를 설치할 수도 있습니다: ```bash >>> brew install hf ``` 자세한 내용은 [여기](https://formulae.brew.sh/formula/hf)의 Homebrew huggingface 페이지를 확인하세요. ### 업데이트 최신 버전으로 업그레이드하려면 다음을 실행하세요: ```bash >>> hf update ``` 이 명령은 `hf`가 어떤 방식으로 설치되었는지(Homebrew, 독립 설치 프로그램, 또는 pip)를 감지하고 그에 맞는 업데이트 명령을 실행합니다. `hf-cli` 스킬이 전역으로 설치되어 있다면 에이전트가 새로운 명령 인터페이스를 인식할 수 있도록 함께 새로고침됩니다. 설치되어 있지 않은 경우에도 설치되지 않은 상태로 유지됩니다. 사용자가 스킬을 건너뛰거나 제거한 경우, 업데이트를 실행해도 다시 설치되지 않습니다. 기본적으로 CLI는 PyPI에서 더 새로운 버전이 사용 가능한 경우 stderr에 한 줄의 노란색 경고를 출력합니다. 이를 비활성화하려면(예: 오프라인 CI 환경에서) `HF_HUB_DISABLE_UPDATE_CHECK=1`을 설정하십시오. ## 출력 형식 대부분의 `hf` 명령은 동일한 전역 포맷 플래그 세트를 지원합니다. 이러한 플래그는 모든 `--help` 페이지의 전용 `Formatting options` 섹션에 문서화되어 있으며, 명령별로 선언할 필요 없이 어떤 명령에든 추가할 수 있습니다: | 플래그 | 동등 | 설명 | | ---- | ---------- | ----------- | | `--format ` | — | 출력 형식을 명시적으로 선택합니다. 허용되는 값: `auto` (기본값), `human`, `agent`, `json`, `quiet`. | | `--json` | `--format json` | 구조화된 JSON을 출력합니다. `jq` 또는 다른 스크립트로 파이프할 때 유용합니다. | | `-q`, `--quiet` | `--format quiet` | Print only IDs (one per line) - ID만 출력합니다(한 줄에 하나씩). ID를 다른 명령으로 파이프할 때 유용합니다. | | `--no-truncate` | — | `...`로 긴 값을 줄이는 대신, human 테이블에서 전체 값을 표시합니다. 테이블이 터미널 너비를 초과할 수 있습니다. list/dict 열의 구조화된 출력을 사용하려면 `--format json`을 사용하세요. | `auto`(기본값)는 인터랙티브 터미널에서는 `human`을, AI 에이전트가 CLI를 호출하는 경우에는 `agent`를 선택합니다. `human`은 색상과 잘 포맷된 테이블을 추가하고, `agent`는 잘리지 않는 탭 구분 값을 생성하며, `json`은 컴팩트한 JSON 객체 또는 배열을 출력합니다. 두 개의 출력 모드 플래그를 함께 사용하는 경우(예: `--json`와 `--format human`를 함께 사용하는 경우) 사용 오류가 발생합니다. Human 테이블은 터미널 너비에 자동으로 맞춰집니다: 가장 넓은 열은 자연스러운 너비가 화면을 초과할 때만 줄어듭니다(따라서 넓은 터미널에서는 `...` 없이 전체 값을 보는 것이 일반적입니다). 너비에 관계없이 전체 값을 표시하려면 `--no-truncate`를 전달하고, list/dict 열의 구조화된 출력을 얻으려면 `--format json`을 사용하세요. ```bash # JSON output for scripting >>> hf models ls --search bert --limit 2 --json | jq '.[].id' # IDs only, one per line >>> hf collections ls --owner nvidia -q nvidia/nemotron-supervised-fine-tuning-69eab9824c9120a3a3b1e25e nvidia/nvidia-nemotron-v3-69388dda16167bb1607171ea ``` > [!TIP] ## hf auth login 많은 경우, Hub(비공개 저장소 다운로드, 파일 업로드, PR 생성 등)와 상호작용하려면 Hugging Face 계정에 로그인되어 있어야 합니다. 이를 위해 터미널에서 다음 명령을 실행하세요: ```bash >>> hf auth login ``` 이미 로그인되어 있으면 이 명령은 프롬프트를 건너뛰고 메시지를 표시합니다. 다시 로그인하려면(예: 토큰을 전환하려면) `--force`를 사용하세요: ```bash >>> hf auth login --force ``` 기본적으로 이 명령은 브라우저를 통해 로그인합니다: URL과 짧은 코드를 출력합니다. 해당 URL을 열고 코드를 입력한 후 요청을 승인하면, CLI가 액세스 토큰을 가져와서 사용자의 머신에 저장합니다. 토큰은 일정 시간 후 만료되지만, 계속 사용하는 동안에는 자동으로 갱신됩니다. ``` ? How would you like to log in? [Use arrows, Enter to confirm] > Log in with your browser Paste an access token Open this URL in your browser: https://huggingface.co/oauth/device And enter the code: ABCD-EFGH Waiting for authorization... Token is valid. The token `oauth-wauplin` has been saved to /home/wauplin/.cache/huggingface/stored_tokens Your token has been saved to /home/wauplin/.cache/huggingface/token Login successful. ``` [User Access Token](https://huggingface.co/docs/hub/security-tokens)을 [Settings page](https://huggingface.co/settings/tokens)에서 생성하여 붙여넣을 수도 있습니다. 이는 인터랙티브 모드( *Paste an access token* 선택) 또는 커맨드 라인에서 직접 수행할 수 있습니다. 보안 강화를 위해 커맨드 히스토리에 토큰이 기록되지 않도록 환경 변수로 토큰을 전달하는 것을 권장합니다. ```bash # Or using an environment variable >>> hf auth login --token $HF_TOKEN --add-to-git-credential Token is valid (permission: write). The token `token_name` has been saved to /home/wauplin/.cache/huggingface/stored_tokens Your token has been saved in your configured git credential helpers (store). Your token has been saved to /home/wauplin/.cache/huggingface/token Login successful The current active token is: `token_name` ``` AI 에이전트에 의해 실행될 때(자동 감지 또는 `--format agent` 사용), 이 명령은 프롬프트를 표시하지 않습니다. 브라우저 플로우를 실행한 후 에이전트가 사용자에게 전달할 수 있는 일반 텍스트 지침을 출력하고, 승인 대기 상태로 전환됩니다: ```bash >>> hf auth login --format agent Ask the user to open https://huggingface.co/oauth/device in a browser and enter the code ABCD-EFGH. The code expires in 900 seconds. Waiting for authorization... Login successful: logged in as wauplin (token saved as 'oauth-wauplin'). ``` `hf auth login`은 인터랙티브 방식이므로 `--format json` 및 `--format quiet`는 지원되지 않습니다. 스크립트 기반의 비인터랙티브 로그인을 수행하려면 `--token`을 전달하세요. 인증에 대한 자세한 내용은 [이 섹션](../quick-start#authentication)을 확인하세요. ## hf auth whoami 로그인 상태인지 확인하려면 `hf auth whoami`를 사용할 수 있습니다. 이 명령어는 옵션이 없으며 Hub에서 사용 중인 사용자 이름과 소속된 조직을 출력합니다: ```bash hf auth whoami Wauplin orgs: huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolCluster ``` 로그인이 되어 있지 않으면 오류 메시지가 출력됩니다. ## hf auth logout 이 명령은 로그아웃을 수행합니다. 실제로는 머신에 저장된 모든 토큰을 삭제합니다. 특정 토큰만 제거하려면 토큰 이름을 인수로 지정할 수 있습니다. `HF_TOKEN` 환경 변수로 로그인한 경우([참고](../package_reference/environment_variables#hftoken)) 이 명령어로 로그아웃되지 않습니다. 해당 상황이라면 머신 구성에서 환경 변수를 해제해야 합니다. ## hf download `hf download` 명령어를 사용하면 Hub에서 파일을 직접 다운로드할 수 있습니다. 내부적으로 [Download](./download) 가이드에 설명된 [hf_hub_download()](/docs/huggingface_hub/main/ko/package_reference/file_download#huggingface_hub.hf_hub_download) 및 [snapshot_download()](/docs/huggingface_hub/main/ko/package_reference/file_download#huggingface_hub.snapshot_download) 헬퍼를 동일하게 사용하며, 반환된 경로를 터미널에 출력합니다. 아래 예시에서는 가장 일반적인 사용 사례를 살펴봅니다. 사용 가능한 모든 옵션을 확인하려면 다음을 실행할 수 있습니다: ```bash hf download --help ``` ### Download a single file repo에서 단일 파일을 다운로드하려면 repo_id와 파일 이름을 다음과 같이 제공하면 됩니다: ```bash >>> hf download gpt2 config.json downloading https://huggingface.co/gpt2/resolve/main/config.json to /home/wauplin/.cache/huggingface/hub/tmpwrq8dm5o (…)ingface.co/gpt2/resolve/main/config.json: 100%|██████████████████████████████████| 665/665 [00:00<00:00, 2.49MB/s] /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json ``` 명령은 항상 마지막 줄에 로컬 머신에 있는 파일의 경로를 출력합니다. 리포지토리의 하위 디렉토리에 있는 파일을 다운로드하려면, 파일의 경로를 posix 형식으로 다음과 같이 제공해야 합니다: ```bash >>> hf download HiDream-ai/HiDream-I1-Full text_encoder/model.safetensors ``` ### 전체 저장소 다운로드 일부 경우에는 저장소의 모든 파일을 다운로드하는 것만 원할 수 있습니다. 이는 저장소 ID만 지정하면 됩니다: ```bash >>> hf download HuggingFaceH4/zephyr-7b-beta Fetching 23 files: 0%| | 0/23 [00:00>> hf download gpt2 config.json model.safetensors Fetching 2 files: 0%| | 0/2 [00:00>> hf download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"* Fetching 8 files: 0%| | 0/8 [00:00>> hf download HuggingFaceH4/ultrachat_200k --repo-type dataset # https://huggingface.co/spaces/HuggingFaceH4/zephyr-chat >>> hf download HuggingFaceH4/zephyr-chat --repo-type space ... ``` ### 특정 리비전 다운로드 위 예시들은 main 브랜치의 최신 커밋에서 다운로드하는 방법을 보여줍니다. 특정 리비전(커밋 해시, 브랜치 이름 또는 태그)에서 다운로드하려면 `--revision` 옵션을 사용하세요: ```bash >>> hf download bigcode/the-stack --repo-type dataset --revision v1.1 ... ``` ### hf:// URI 사용 리포지토리 유형, 리비전, 파일 경로를 개별 인자와 옵션으로 전달하는 대신, 단일 `hf://` URI를 제공할 수 있습니다. URI는 문법 `hf://[/][@][/]`에 따라 모든 정보를 한 번에 인코딩합니다(전체 문법은 [HF URIs reference](../package_reference/hf_uris)를 참조): ```bash # Equivalent to: hf download bigcode/the-stack --repo-type dataset --revision v1.1 >>> hf download hf://datasets/bigcode/the-stack@v1.1 # Download a single file from a specific revision >>> hf download hf://datasets/HuggingFaceM4/FineVision@refs/pr/1/data/train.parquet # Download a subfolder (note the trailing slash) >>> hf download hf://datasets/HuggingFaceM4/FineVision/art/ # A bare id still works and defaults to a model repo >>> hf download hf://openai-community/gpt2/config.json ``` URI가 지정된 경우, `--repo-type`와 `--revision`도 URI에 이미 포함되어 있기 때문에 설정할 수 없습니다(그렇지 않으면 오류가 발생합니다). 또한 URI에 내장된 파일 경위는 위치 인자 파일명과 함께 사용할 수 없습니다. 경로 끝의 `/`는 하위 폴더를 나타냅니다(위치 인자와 동일). `/`를 포함하는 브랜치 이름은 `%2F`로 URL 인코딩해야 합니다(예: `hf://my-org/my-model@feature%2Ffoo`). ### 로컬 폴더로 다운로드 Hub에서 파일을 다운로드하는 권장(기본) 방식은 캐시 시스템을 사용하는 것입니다. 그러나 일부 경우에는 파일을 다운로드한 후 특정 폴더로 이동하고 싶을 수 있습니다. 이는 git 명령이 제공하는 워크플로에 더 가깝게 작업하기 위해 유용합니다. `--local-dir` 옵션을 사용하여 이를 수행할 수 있습니다. 로컬 디렉터리의 루트에 `.cache/huggingface/` 폴더가 생성되며, 다운로드된 파일에 대한 메타데이터를 포함합니다. 이미 최신 상태인 파일은 다시 다운로드하지 않도록 방지합니다. 메타데이터가 변경된 경우, 새로운 파일 버전이 다운로드됩니다. 이를 통해 `local-dir`은 최신 변경 사항만 가져오도록 최적화됩니다. > [!TIP] > 로컬 파일로 다운로드하는 방식에 대한 자세한 내용은 [download](./download#download-files-to-a-local-folder) 가이드를 참고하세요. ```bash >>> hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu ... fuyu/model-00001-of-00002.safetensors ``` ### Dry-run 모드 일부 경우, 실제로 파일을 다운로드하기 전에 어떤 파일이 다운로드될지 확인하고 싶을 수 있습니다. `--dry-run` 매개변수를 사용하여 이를 확인할 수 있습니다. 이 매개변수는 저장소의 모든 다운로드 대상 파일을 나열하고, 해당 파일이 이미 다운로드되었는지 여부를 확인합니다. 이를 통해 다운로드해야 하는 파일의 수와 크기를 파악할 수 있습니다. ```sh >>> hf download openai-community/gpt2 --dry-run [dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00, 6.26it/s] [dry-run] Will download 11 files (out of 26) totalling 5.6G. File Bytes to download --------------------------------- ----------------- .gitattributes - 64-8bits.tflite 125.2M 64-fp16.tflite 248.3M 64.tflite 495.8M README.md - config.json - flax_model.msgpack 497.8M generation_config.json - merges.txt - model.safetensors 548.1M onnx/config.json - onnx/decoder_model.onnx 653.7M onnx/decoder_model_merged.onnx 655.2M onnx/decoder_with_past_model.onnx 653.7M onnx/generation_config.json - onnx/merges.txt - onnx/special_tokens_map.json - onnx/tokenizer.json - onnx/tokenizer_config.json - onnx/vocab.json - pytorch_model.bin 548.1M rust_model.ot 702.5M tf_model.h5 497.9M tokenizer.json - tokenizer_config.json - vocab.json - ``` 자세한 내용은 [다운로드 가이드](./download#dry-run-mode)를 확인하세요. ### 캐시 디렉터리 지정 `--local-dir`를 사용하지 않으면, 모든 파일은 기본적으로 `HF_HOME` [환경 변수](../package_reference/environment_variables#hfhome)로 정의된 캐시 디렉토리에 다운로드됩니다. `--cache-dir`를 사용하여 사용자 지정 캐시를 지정할 수 있습니다: ```bash >>> hf download adept/fuyu-8b --cache-dir ./path/to/cache ... ./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745 ``` ### 토큰 지정 비공개 또는 게이트된 저장소에 액세스하려면 토큰을 사용해야 합니다. 기본적으로 로컬에 저장된 토큰(`hf auth login`을 사용하여 저장됨)이 사용됩니다. 명시적으로 인증하려면 `--token` 옵션을 사용하세요: ```bash >>> hf download gpt2 config.json --token=hf_**** /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json ``` ### 조용 모드 기본적으로 `hf download` 명령은 상세한 출력을 제공합니다. 경고 메시지, 다운로드된 파일에 대한 정보, 진행률 표시줄과 같은 세부 사항을 출력합니다. 이러한 모든 출력을 비활성화하려면 `--quiet` 옵션을 사용하세요. 이 경우 마지막 줄(즉, 다운로드된 파일의 경로)만 출력됩니다. 스크립트에서 출력을 다른 명령으로 전달하려는 경우 유용할 수 있습니다. ```bash >>> hf download gpt2 --quiet /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 ``` ### 다운로드 시간 초과 연속 속도가 느린 머신에서는 다음과 같은 타임아웃 문제가 발생할 수 있습니다: ```bash `httpx2.TimeoutException: (TimeoutException("HTTPSConnectionPool(host='cdn-lfs-us-1.huggingface.co', port=443): Read timed out. (read timeout=10)"), '(Request ID: a33d910c-84c6-4514-8362-c705e2039d38)')` ``` 이 문제를 완화하려면 `HF_HUB_DOWNLOAD_TIMEOUT` 환경 변수를 더 높은 값으로 설정할 수 있습니다(기본값은 10): ```bash export HF_HUB_DOWNLOAD_TIMEOUT=30 ``` 자세한 내용은 [환경 변수 참조](../package_reference/environment_variables#hfhubdownloadtimeout)를 확인하세요. 그리고 다운로드 명령을 다시 실행하세요. ## hf upload `hf upload` 명령어를 사용하여 파일을 Hub에 직접 업로드할 수 있습니다. 내부적으로 [Upload](./upload) 가이드에 설명된 [upload_file()](/docs/huggingface_hub/main/ko/package_reference/hf_api#huggingface_hub.HfApi.upload_file) 및 [upload_folder()](/docs/huggingface_hub/main/ko/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) 헬퍼를 동일하게 사용합니다. 아래 예시에서는 가장 일반적인 사용 사례를 살펴봅니다. 사용 가능한 모든 옵션을 확인하려면 다음을 실행할 수 있습니다: ```bash >>> hf upload --help ``` ### 전체 폴더 업로드 이 명령어의 기본 사용법은 다음과 같습니다: ```bash # Usage: hf upload [repo_id] [local_path] [path_in_repo] ``` 리포지토리의 루트에 현재 디렉터리를 업로드하려면 다음을 사용하세요: ```bash >>> hf upload my-cool-model . . https://huggingface.co/Wauplin/my-cool-model/tree/main/ ``` > [!TIP] > 리포지토리가 아직 없으면 자동으로 생성됩니다. 특정 폴더를 업로드할 수도 있습니다: ```bash >>> hf upload my-cool-model ./models . https://huggingface.co/Wauplin/my-cool-model/tree/main/ ``` 마지막으로, 폴더를 저장소의 특정 위치에 업로드할 수 있습니다: ```bash >>> hf upload my-cool-model ./path/to/curated/data /data/train https://huggingface.co/Wauplin/my-cool-model/tree/main/data/train ``` ### Upload a single file `local_path`를 로컬 머신에 있는 파일로 지정하여 단일 파일만 업로드할 수도 있습니다. 이 경우 `path_in_repo`는 선택 사항이며, 기본값으로 로컬 파일 이름이 사용됩니다: ```bash >>> hf upload Wauplin/my-cool-model ./models/model.safetensors https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors ``` 특정 디렉토리에 단일 파일을 업로드하려면 `path_in_repo`를 다음과 같이 설정하세요: ```bash >>> hf upload Wauplin/my-cool-model ./models/model.safetensors /vae/model.safetensors https://huggingface.co/Wauplin/my-cool-model/blob/main/vae/model.safetensors ``` ### 여러 파일 업로드 폴더 전체를 업로드하지 않고 폴더에서 여러 파일을 한 번에 업로드하려면 `--include` 및 `--exclude` 패턴을 사용합니다. `--delete` 옵션과 함께 사용하여 새 파일을 업로드하는 동안 리포지토리의 파일을 삭제할 수도 있습니다. 아래 예시에서는 `/logs`에 있는 파일을 제외한 모든 파일을 업로드하고 원격 파일을 삭제하여 로컬 Space를 동기화합니다: ```bash # Sync local Space with Hub (upload new files except from logs/, delete removed files) >>> hf upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub" ... ``` ### 데이터셋 또는 Space에 업로드 데이터셋 또는 Space에 업로드하려면 `--repo-type` 옵션을 사용하세요: ```bash >>> hf upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset ... ``` ### 조직에 업로드 개인 저장소가 아닌 조직 소유의 저장소에 콘텐츠를 업로드하려면 `repo_id`에 명시적으로 지정해야 합니다: ```bash >>> hf upload MyCoolOrganization/my-cool-model . . https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/ ``` ### 특정 리비전으로 업로드 기본적으로 파일은 `main` 브랜치에 업로드됩니다. 다른 브랜치 또는 참조에 파일을 업로드하려면 `--revision` 옵션을 사용하세요: ```bash # Upload files to a PR >>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104 ... ``` **참고:** `revision`이 존재하지 않고 `--create-pr`가 설정되지 않은 경우, `main` 브랜치에서 브랜치가 자동으로 생성됩니다. ### hf:// URI 사용 `hf download`와 마찬가지로, 대상은 `hf://[/][@][/]` 문법을 따르는 단일 `hf://` URI로 표현할 수 있습니다(전체 문법은 [HF URIs reference](../package_reference/hf_uris)를 참조). 리포지토리 유형, 리비전 및 `path_in_repo`는 모두 URI에서 읽힙니다: ```bash # Equivalent to: hf upload Wauplin/my-cool-dataset ./train.csv data/train.csv --repo-type dataset --revision my-branch >>> hf upload hf://datasets/Wauplin/my-cool-dataset@my-branch/data/train.csv ./train.csv # Upload a whole folder to the root of a model repo >>> hf upload hf://Wauplin/my-cool-model ./models ``` URI가 지정된 경우, `--repo-type`와 `--revision`도 URI에 이미 포함되어 있기 때문에 설정할 수 없습니다(그렇지 않으면 오류가 발생함). 또한 URI에 내장된 경로와 `path_in_repo` 인수를 함께 사용할 수 없습니다. ### 업로드 및 PR 생성 리포지토리에 push할 권한이 없다면 PR을 열고 변경하려는 내용을 작성자에게 알려야 합니다. `--create-pr` 옵션을 설정하여 수행할 수 있습니다: ```bash # Create a PR and upload the files to it >>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104 https://huggingface.co/datasets/bigcode/the-stack/blob/refs%2Fpr%2F104/ ``` ### 정해진 간격으로 업로드 일부 경우에는 저장소에 정기적으로 업데이트를 푸시하고 싶을 수 있습니다. 예를 들어, 모델을 학습 중이고 10분마다 logs 폴더를 업로드하고 싶다면 유용합니다. `--every` 옵션을 사용하여 이를 수행할 수 있습니다: ```bash # Upload new logs every 10 minutes hf upload training-model logs/ --every=10 ``` ### 커밋 메시지를 지정합니다 기본 메시지 대신 커밋에 사용자 지정 메시지와 설명을 설정하려면 `--commit-message`와 `--commit-description`를 사용하세요 ```bash >>> hf upload Wauplin/my-cool-model ./models . --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%. Check tensorboard for more details." ... https://huggingface.co/Wauplin/my-cool-model/tree/main ``` ### 토큰 지정 파일을 업로드하려면 토큰을 사용해야 합니다. 기본적으로 로컬에 저장된 토큰(`hf auth login`을 사용하여 저장)이 사용됩니다. 명시적으로 인증하려면 `--token` 옵션을 사용하세요: ```bash >>> hf upload Wauplin/my-cool-model ./models . --token=hf_**** ... https://huggingface.co/Wauplin/my-cool-model/tree/main ``` ### 조용 모드 기본적으로 `hf upload` 명령은 상세한 출력을 제공합니다. 경고 메시지, 업로드된 파일에 대한 정보, 진행률 표시줄과 같은 세부 사항을 출력합니다. 이러한 모든 출력을 비활성화하려면 `--quiet` 옵션을 사용하세요. 이 경우 마지막 줄(즉, 업로드된 파일의 URL)만 출력됩니다. 스크립트에서 출력을 다른 명령으로 전달하려는 경우 유용할 수 있습니다. ```bash >>> hf upload Wauplin/my-cool-model ./models . --quiet https://huggingface.co/Wauplin/my-cool-model/tree/main ``` ## hf buckets `hf buckets`를 사용하여 Hugging Face Hub의 버킷을 관리합니다. 버킷은 Xet 스토리지 백엔드로 구동되는 Hugging Face의 S3 유사 객체 스토리지입니다. 리포지토리(기반이 git이며 파일 히스토리를 추적)와 달리, 버킷은 콘텐츠 주소 기반 중복 제거를 지원하는 대규모 파일을 위한 원격 객체 스토리지 컨테이너입니다. 버전 관리가 필요하지 않은 학습 체크포인트, 로그, 중간 산출물 또는 대규모 파일 컬렉션과 같이 단순하고 빠르며 변경 가능한 스토리지가 필요한 사용 사례를 위해 설계되었습니다. 아래 예제에서는 가장 일반적인 사용 사례를 안내합니다. 전체 가이드는 [Buckets guide](./buckets)를 참고하세요. ### 버킷 생성 새 버킷을 만들려면 `hf buckets create`를 사용하세요. 기본적으로 버킷은 사용자의 네임스페이스 아래에 생성됩니다: ```bash >>> hf buckets create my-bucket ``` `--private` 플래그를 사용하여 개인 버킷을 만들 수도 있습니다: ```bash >>> hf buckets create my-bucket --private ``` ### 버킷 목록 및 검사 모든 버킷을 나열하려면 `hf buckets list`(또는 약어 `hf buckets ls`)를 사용하세요. 특정 조직의 버킷을 나열할 수도 있습니다: ```bash >>> hf buckets list ID PRIVATE SIZE TOTAL_FILES CREATED_AT -------------------- ------- ---------- ----------- ---------- username/my-bucket 32 5 2026-02-16 username/checkpoints 117609095 700 2026-02-13 username/logs 321757477 2000 2026-02-13 # Human-readable sizes >>> hf buckets list -h ID PRIVATE SIZE TOTAL_FILES CREATED_AT -------------------- ------- -------- ----------- ---------- username/my-bucket 32 B 5 2026-02-16 username/checkpoints 117.6 MB 700 2026-02-13 username/logs 321.8 MB 2000 2026-02-13 # List buckets in a specific namespace >>> hf buckets ls my-org # Filter buckets by name >>> hf buckets list --search "checkpoint" ``` 특정 버킷에 대한 상세 정보(JSON으로 반환)를 확인하려면 `hf buckets info`를 사용하세요: ```bash >>> hf buckets info username/my-bucket { "id": "username/my-bucket", "private": false, "created_at": "2026-02-16T15:28:32+00:00", "size": 32, "total_files": 5 } ``` ### 버킷 가시성 변경 버킷을 비공개와 공개로 전환하려면 `hf buckets settings`를 사용하세요: ```bash # Make a bucket private >>> hf buckets settings username/my-bucket --private # Make it public again >>> hf buckets settings username/my-bucket --public ``` ### 버킷 삭제 버킷을 삭제하려면 `hf buckets delete`를 사용합니다. `--yes`를 전달하지 않으면 확인을 요청합니다: ```bash >>> hf buckets delete username/my-bucket --yes ``` ### 파일 제거 `hf buckets remove`(또는 그 약어 `hf buckets rm`)를 사용하여 버킷에서 파일을 삭제합니다. … ```bash >>> hf buckets rm username/my-bucket/old-model.bin ``` 접두어 아래에 있는 모든 파일을 삭제하려면 `--recursive`를 사용하세요: ```bash >>> hf buckets rm username/my-bucket/logs/ --recursive ``` prefix가 없는 bucket의 모든 파일을 대상으로 지정할 수도 있습니다: ```bash >>> hf buckets rm username/my-bucket --recursive --include "*.tmp" ``` `--dry-run`를 사용하여 실제로 삭제하지 않고 삭제될 항목을 미리 확인합니다: ```bash >>> hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-run ``` ### 파일 탐색 `hf buckets list`를 버킷 ID와 함께 사용하여 버킷 내 파일을 나열합니다: ```bash >>> hf buckets list username/my-bucket 2048 2026-01-15 10:30:00 big.bin 5 2026-01-15 10:30:00 file.txt 2026-01-15 10:30:00 sub/ ``` 재귀 목록을 보려면 `-R`를, 사람이 읽기 쉬운 파일 크기와 짧은 날짜 형식을 보려면 `-h`를 추가하세요. `--tree`를 사용하여 ASCII 트리 뷰를 표시하거나, 메타데이터가 없는 깔끔한 트리를 보려면 `--tree --quiet`를 사용할 수도 있습니다: ```bash # Recursive with human-readable sizes >>> hf buckets list username/my-bucket -R -h 2.0 KB Jan 15 10:30 big.bin 5 B Jan 15 10:30 file.txt 14 B Jan 15 10:30 sub/nested.txt 4 B Jan 15 10:30 sub/deep/file.txt # Tree with human-readable sizes >>> hf buckets list username/my-bucket --tree -h -R 2.0 KB Jan 15 10:30 ├── big.bin 5 B Jan 15 10:30 ├── file.txt └── sub/ ├── deep/ 4 B Jan 15 10:30 │ └── file.txt 14 B Jan 15 10:30 └── nested.txt # Clean tree without metadata >>> hf buckets list username/my-bucket --tree --quiet -R ├── big.bin ├── file.txt └── sub/ ├── deep/ │ └── file.txt └── nested.txt ``` 접두사로 필터링하려면 버킷 경로에 접두사를 추가합니다: ```bash >>> hf buckets list username/my-bucket/sub -R ``` ### 파일 복사 `hf cp`를 사용하여 로컬 머신, 저장소, 버킷 간에 단일 파일을 복사합니다. 소스와 대상은 각각 로컬 경로, `hf://` URI(저장소 또는 버킷), 또는 `-`(stdin/stdout)일 수 있습니다. > [!TIP] > `hf cp`는 `hf repos cp` 및 `hf buckets cp`로도 노출되며, 세 명령어는 완전히 동일합니다. 워크플로우에 따라 읽기 편한 것을 선택해 사용하세요. … ```bash # To a repository >>> hf cp ./model.safetensors hf://username/my-model/model.safetensors # To a bucket (uses the local filename when the destination ends with /) >>> hf cp ./data.csv hf://buckets/username/my-bucket/logs/ ``` repo 또는 bucket에서 로컬로 파일을 다운로드하려면: ```bash # From a repository >>> hf cp hf://datasets/username/my-dataset@refs/pr/1/data.csv ./data.csv # From a bucket, to the current directory (destination omitted) >>> hf cp hf://buckets/username/my-bucket/config.json ``` `-`를 사용하여 stdout으로 스트리밍하거나 stdin에서 스트리밍할 수도 있습니다: ```bash # Download to stdout >>> hf cp hf://buckets/username/my-bucket/config.json - | jq . # Upload from stdin >>> echo "hello" | hf cp - hf://username/my-model/hello.txt ``` Hub의 두 위치(리포지토리/버킷 → 리포지토리/버킷) 간에 복사하려면: ```bash # Repo to repo >>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json # Repo to bucket >>> hf cp hf://datasets/username/my-dataset/data/train/ hf://buckets/username/my-bucket/datasets/train/ # Bucket to bucket >>> hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/archive-bucket/logs/ ``` 두 Hub 위치 간 폴더를 복사할 때, 소스 경로 끝의 `/`는 폴더 자체를 중첩하여 복사할지 아니면 내용만 복사할지를 결정합니다(rsync 스타일): ```bash # Without trailing slash: "logs" dir is nested => archive/logs/... >>> hf cp hf://buckets/username/my-bucket/logs hf://buckets/username/archive-bucket/ # With trailing slash: only contents of "logs" are copied => archive/... >>> hf cp hf://buckets/username/my-bucket/logs/ hf://buckets/username/archive-bucket/ ``` 참고: - 로컬 경로가 포함된 경우 `hf cp`는 단일 파일만 복사합니다. 디렉터리 전체를 로컬로 복사하거나 로컬에서 복사하려면 `hf upload`/`hf download`(리포지토리) 또는 `hf buckets sync`(버킷)를 사용하세요. - Bucket-to-repo 복사는 아직 지원되지 않습니다. - 로컬에서 로컬로의 복사는 지원되지 않습니다(셸의 `cp`를 사용하세요). - 두 Hub 위치 간의 복사는 동일한 [스토리지 리전](https://huggingface.co/docs/hub/storage-regions) 내에서만 작동합니다. ### 디렉터리 동기화 `hf buckets sync`를 사용하여 로컬 머신과 버킷 간 디렉터리를 동기화합니다. 소스와 대상의 차이를 비교하여 변경된 파일만 전송합니다. 로컬 디렉토리를 버킷에 업로드하려면: ```bash >>> hf buckets sync ./data hf://buckets/username/my-bucket ``` … ```bash >>> hf buckets sync hf://buckets/username/my-bucket ./data ``` `--delete`를 사용하여 소스에 없는 대상 파일을 삭제합니다: ```bash >>> hf buckets sync ./data hf://buckets/username/my-bucket --delete ``` `--include`와 `--exclude` 패턴을 사용하여 동기화할 파일을 필터링할 수 있습니다: ```bash >>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.safetensors" --exclude "*.tmp" ``` 기존 파일만 업데이트하려면(새 파일은 건너뛰려면) `--existing`를 사용하세요. 새 파일만 생성하려면(기존 파일은 건너뛰려면) `--ignore-existing`을 사용하세요: ```bash >>> hf buckets sync ./data hf://buckets/username/my-bucket --existing >>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-existing ``` 추가 안전을 위해, 실행 전에 검토할 계획을 생성한 후 적용할 수 있습니다: ```bash # Generate a plan >>> hf buckets sync ./data hf://buckets/username/my-bucket --plan sync-plan.jsonl # Review and apply the plan >>> hf buckets sync --apply sync-plan.jsonl ``` `--dry-run`를 사용하면 아무 작업도 실행하지 않고 동기화 계획을 JSONL 형식으로 표준 출력(stdout)에 인쇄합니다. `jq`나 기타 도구로 파이프할 때 유용합니다: ```bash >>> hf buckets sync ./data hf://buckets/username/my-bucket --dry-run | jq . ``` > [!TIP] > `hf sync`는 `hf buckets sync`의 편리한 최상위 별칭입니다. 모든 동기화 옵션에 대한 자세한 내용은 [Buckets 가이드](./buckets#sync-directories)를 참고하세요. ## hf models `hf models`를 사용하여 Hub에 있는 모델을 나열하고 특정 모델에 대한 상세 정보를 가져옵니다. ### 모델 목록 ```bash # List trending models >>> hf models ls # Search for models >>> hf models ls --search "lora" # Filter by author >>> hf models ls --author Qwen # Filter by pipeline tag >>> hf models ls --pipeline-tag summarization # Filter by parameter count >>> hf models ls --num-parameters min:6B,max:128B # Only non-gated models >>> hf models ls --no-gated --author google # Only models runnable by a given app >>> hf models ls --apps llama.cpp # Sort by downloads >>> hf models ls --sort downloads --limit 10 ``` 모델 ID로 호출하면 `hf models ls`는 해당 모델 저장소의 파일 목록을 표시합니다: ```bash # List files in a model repo >>> hf models ls meta-llama/Llama-3.2-1B-Instruct # List files recursively >>> hf models ls meta-llama/Llama-3.2-1B-Instruct -R # Tree view with human-readable sizes >>> hf models ls meta-llama/Llama-3.2-1B-Instruct --tree -h # List files at a specific revision >>> hf models ls meta-llama/Llama-3.2-1B-Instruct --revision main ``` ### 모델 정보 가져오기 ```bash >>> hf models info Lightricks/LTX-2 ``` `--expand`를 사용하여 `downloads`, `likes`, `tags`와 같은 추가 속성을 가져옵니다. ### 모델 카드 가져오기 `hf models card`를 사용하여 모델의 모델 카드(README)를 가져옵니다. 기본적으로 전체 카드 내용을 stdout에 출력합니다. ```bash # Full card (metadata + text) >>> hf models card google/gemma-4-31B-it # Just the metadata (from the YAML frontmatter) >>> hf models card google/gemma-4-31B-it --metadata # Metadata as JSON (useful for scripting and agents) >>> hf models card google/gemma-4-31B-it --metadata --format json # Just the text body (no YAML frontmatter) >>> hf models card google/gemma-4-31B-it --text ``` ## hf datasets `hf datasets`를 사용하여 Hub에 있는 데이터셋을 나열하고 특정 데이터셋에 대한 상세 정보를 가져옵니다. ### 데이터셋 목록 ```bash # List trending datasets >>> hf datasets ls # Search for datasets >>> hf datasets ls --search "code" # List official benchmark datasets >>> hf datasets ls --filter benchmark:official # Sort by downloads >>> hf datasets ls --sort downloads --limit 10 ``` dataset ID로 호출하면 `hf datasets ls`는 해당 dataset 저장소의 파일 목록을 표시합니다: ```bash # List files in a dataset repo >>> hf datasets ls HuggingFaceFW/fineweb # List files recursively with human-readable sizes >>> hf datasets ls HuggingFaceFW/fineweb -R -h # Tree view >>> hf datasets ls HuggingFaceFW/fineweb --tree ``` ### 데이터셋 리더보드 나열 벤치마크 데이터셋에 제출된 모델 점수를 표시하려면 `hf datasets leaderboard`를 사용하세요. 이를 통해 특정 작업에 가장 적합한 모델을 찾거나 벤치마크 점수로 모델을 비교할 수 있습니다. ```bash >>> hf datasets leaderboard SWE-bench/SWE-bench_Verified >>> hf datasets leaderboard SWE-bench/SWE-bench_Verified --limit 5 --format json ``` ### 데이터셋 정보 가져오기 ```bash >>> hf datasets info HuggingFaceFW/fineweb ``` ### 데이터셋 카드 가져오기 `hf datasets card`를 사용하여 데이터셋 카드(README)를 가져옵니다. 기본적으로 전체 카드 내용을 stdout에 출력합니다. ```bash # Full card (metadata + text) >>> hf datasets card HuggingFaceFW/fineweb # Just the metadata (from the YAML frontmatter) >>> hf datasets card HuggingFaceFW/fineweb --metadata # Metadata as JSON (useful for scripting and agents) >>> hf datasets card HuggingFaceFW/fineweb --metadata --format json # Just the text body (no YAML frontmatter) >>> hf datasets card HuggingFaceFW/fineweb --text ``` ### parquet URL 목록 SQL 쿼리를 작성하기 전에 데이터셋의 parquet 파일 URL을 확인하려면 `hf datasets parquet`를 사용하세요. Hub의 데이터셋은 대상이 되는 데이터셋에 대해 Dataset Viewer 서비스에서 백엔드에서 자동으로 Parquet로 변환됩니다. 자세한 내용은 [Parquet 변환 가이드](https://huggingface.co/docs/dataset-viewer/parquet)를 참조하세요. ```bash >>> hf datasets parquet cfahlgren1/hub-stats >>> hf datasets parquet cfahlgren1/hub-stats --subset models >>> hf datasets parquet cfahlgren1/hub-stats --split train >>> hf datasets parquet cfahlgren1/hub-stats --format json ``` 기본 테이블 출력에는 Hub API의 subset, split, parquet 파일 URL이 포함됩니다. ### dataset parquet에서 SQL 실행 `hf datasets sql`을 사용하여 DuckDB로 dataset parquet URL에 대해 원시 SQL 쿼리를 실행합니다. 먼저 `hf datasets parquet`로 URL을 확인한 후, `read_parquet(...)`로 직접 쿼리합니다. ```bash >>> hf datasets sql "SELECT COUNT(*) AS rows FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet')" >>> hf datasets sql "SELECT * FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet') LIMIT 5" --format json ``` 필요한 경우 먼저 DuckDB를 설치하세요: ```bash # Python package >>> pip install duckdb # or standalone DuckDB CLI (Homebrew: macOS/Linux) >>> brew install duckdb ``` ## hf spaces `hf spaces`를 사용하여 Hub에 있는 Spaces를 나열하고 특정 Space에 대한 상세 정보를 가져옵니다. ### Spaces 목록 ```bash # List trending Spaces >>> hf spaces ls # Search for Spaces >>> hf spaces ls --search "3d" # Sort by likes >>> hf spaces ls --sort likes --limit 10 ``` Space ID로 호출하면 `hf spaces ls`는 해당 Space 저장소의 파일 목록을 표시합니다: ```bash # List files in a Space repo >>> hf spaces ls victor/deepsite # List files recursively with tree view >>> hf spaces ls victor/deepsite --tree -R -h ``` ### Space 정보 가져오기 ```bash >>> hf spaces info victor/deepsite ``` ### Space 카드 가져오기 `hf spaces card`를 사용하여 Space의 카드(README)를 가져옵니다. 기본적으로 전체 카드 내용을 stdout에 출력합니다. ```bash # Full card (metadata + text) >>> hf spaces card mteb/leaderboard # Just the card metadata (from the YAML frontmatter) >>> hf spaces card mteb/leaderboard --metadata # Card metadata as JSON >>> hf spaces card mteb/leaderboard --metadata --format json # Just the text body (no YAML frontmatter) >>> hf spaces card mteb/leaderboard --text ``` > [!TIP] > Space를 일시 중지하거나 다시 시작하면 컨테이너가 종료되므로 임시 파일 시스템에 작성된 모든 데이터가 손실됩니다. 재시작 후에도 데이터를 유지하려면 `hf spaces volumes set`를 사용하여 볼륨 또는 버킷을 마운트하세요(자세한 내용은 `hf spaces volumes --help`를 실행하여 확인하세요). ### Space 일시 정지 사용하지 않을 때 `hf spaces pause`를 사용하여 Space를 일시 중지할 수 있습니다(일시 중지된 시간은 과금되지 않음). 나중에 `hf spaces restart`를 사용하여 다시 시작할 수 있습니다. ```bash >>> hf spaces pause username/my-space ``` ### Space 재시작 `hf spaces restart`를 사용하여 Space를 재시작합니다. 빌드 캐시를 사용하지 않고 Space를 처음부터 다시 구축하려면 `--factory-reboot`를 전달합니다. ```bash >>> hf spaces restart username/my-space >>> hf spaces restart username/my-space --factory-reboot ``` ### Space 대기 `hf spaces wait`를 사용하면 Space가 빌드/시작을 완료하고 안정된 단계에 도달할 때까지 블로킹됩니다. Space가 `RUNNING` 상태이면 종료 코드 0을 반환하고, 그렇지 않으면(예: `BUILD_ERROR`) 0이 아닌 코드를 반환합니다. 재시작 또는 하드웨어 변경 후 스크립팅에 유용합니다. ```bash >>> hf spaces wait username/my-space # With a timeout >>> hf spaces wait username/my-space --timeout 5m # Chain with restart >>> hf spaces restart username/my-space && hf spaces wait username/my-space ``` ### 사용 가능한 하드웨어 목록 Spaces에서 사용할 수 있는 모든 하드웨어 옵션과 가격을 확인하려면 `hf spaces hardware`를 사용하세요. ```bash >>> hf spaces hardware ``` ### ZeroGPU 할당량 확인 `hf spaces zero-gpu quota`를 사용하여 [ZeroGPU](https://huggingface.co/docs/hub/spaces-zerogpu) 할당량 중 남은 양과 리셋 시점을 확인할 수 있습니다. 스크립트, 앱 또는 에이전트에서 ZeroGPU Spaces를 호출할 때 사용량을 추적하는 데 유용합니다. ```bash >>> hf spaces zero-gpu quota ✓ ZeroGPU quota (in GPU-seconds) remaining: 1810 base: 2400 resets_at: 2026-09-30T18:12:03+00:00 overquota_used: 0 >>> hf spaces zero-gpu quota --format json {"remaining": 1810, "base": 2400, "resets_at": "2026-09-30T18:12:03+00:00", "overquota_used": 0} ``` 할당이 부족하면, [결제 설정](https://huggingface.co/settings/billing?add-credits=true)에서 크레딧을 구매하여 일일 할당량을 초과해도 ZeroGPU를 계속 사용할 수 있도록 명령이 제안됩니다 (PRO, Team, Enterprise 사용자만 해당). ### Space 설정 업데이트 `hf spaces settings`를 사용하여 Space의 설정을 업데이트합니다. ```bash >>> hf spaces settings username/my-space --sleep-time 3600 >>> hf spaces settings username/my-space --hardware t4-medium ``` - `--sleep-time`: Space가 수면 상태로 전환되기 전의 대기 시간(초). `-1`을 사용하면 수면 상태로 전환되지 않습니다. 업그레이드된 하드웨어에서만 사용할 수 있습니다([Spaces 수면 시간 문서](https://huggingface.co/docs/hub/spaces-gpus#sleep-time) 참고). - `--hardware`: 하드웨어 유형(예: `cpu-basic`, `t4-medium`, `l4x4`). 모든 옵션을 보려면 `hf spaces hardware`를 실행하세요. ### Space 시크릿 관리 Space의 시크릿 목록을 보려면 `hf spaces secrets ls`, 하나 이상의 시크릿을 추가하거나 업데이트하려면 `hf spaces secrets add`, 하나를 삭제하려면 `hf spaces secrets delete`를 사용합니다. `--secrets-file PATH`를 전달하면 `.env` 스타일 파일에서 시크릿을 로드합니다. 기존 키는 덮어쓰기됩니다. ```bash >>> hf spaces secrets ls username/my-space >>> hf spaces secrets add username/my-space -s OPENAI_API_KEY=sk-... >>> hf spaces secrets add username/my-space --secrets-file .env.secrets >>> hf spaces secrets delete username/my-space OPENAI_API_KEY --yes ``` > [!NOTE] > Secret 값은 쓰기 전용이므로 `hf spaces secrets ls`는 키, 설명, 업데이트 시각만 표시하며 secret 값 자체는 절대 표시하지 않습니다. ### Space 환경 변수 관리 `hf spaces variables`를 사용하여 Space의 비비밀 환경 변수를 관리합니다. Secrets와 달리 변수는 읽을 수 있으므로 `ls` 명령으로 키와 값이 모두 표시됩니다. `add`에 `--env-file PATH`를 전달하여 `.env` 스타일 파일에서 로드할 수 있습니다. ```bash >>> hf spaces variables ls username/my-space >>> hf spaces variables add username/my-space -e MODEL_ID=gpt2 -e MAX_TOKENS=512 >>> hf spaces variables add username/my-space --env-file .env >>> hf spaces variables delete username/my-space MAX_TOKENS --yes ``` ### Space에 SSH 접속(개발 모드) `hf spaces ssh`를 사용하여 Space의 Dev Mode 컨테이너에 SSH 세션을 엽니다. Dev Mode가 활성화되어 있지 않으면 CLI가 활성화하도록 프롬프트를 표시합니다(또는 `--auto`를 사용하여 프롬프트를 건너뜁니다). SSH 공개 키는 [설정](https://huggingface.co/settings/keys)에 등록되어 있어야 합니다. 자세한 내용은 [Dev Mode 문서](https://huggingface.co/docs/hub/spaces-dev-mode)를 참조하세요. ```bash # SSH into a Space >>> hf spaces ssh username/my-space # Print the SSH command without running it >>> hf spaces ssh username/my-space --dry-run # Auto-enable Dev Mode if disabled >>> hf spaces ssh username/my-space --auto # Use a specific SSH key >>> hf spaces ssh username/my-space -i ~/.ssh/id_ed25519 ``` ## hf papers `hf papers`를 사용하여 Hub의 논문을 나열하고, 검색하고, 구조화된 정보를 가져오며, 마크다운 콘텐츠를 읽을 수 있습니다. ### 논문 목록 ```bash # List most recent daily papers >>> hf papers ls # List trending papers >>> hf papers ls --sort=trending # List papers from a specific date >>> hf papers ls --date=2025-01-23 # List today's papers >>> hf papers ls --date=today # List papers from a specific week >>> hf papers ls --week=2025-W09 # List papers from a specific month >>> hf papers ls --month=2025-02 # List papers submitted by a specific user >>> hf papers ls --submitter=akhaliq # Limit results >>> hf papers ls --sort=trending --limit=5 ``` ### 논문 검색 ```bash # Search papers by keyword >>> hf papers search "vision language" # Limit search results >>> hf papers search "diffusion models" --limit=10 # Output as JSON >>> hf papers search "attention" --format=json ``` ### 논문 정보 가져오기 ```bash # Get structured metadata for a paper (returns JSON) >>> hf papers info 2601.15621 ``` ### Read paper as markdown ```bash # Read the full paper content as markdown >>> hf papers read 2601.15621 ``` ## hf 토론 `hf discussions`를 사용하면 터미널에서 Hub 저장소의 토론과 pull request를 직접 관리할 수 있습니다. 토론과 PR 모두를 나열, 보기, 생성, 댓글 작성, 닫기, 다시 열기, 병합할 수 있습니다. Hub의 커뮤니티 기능이 어떻게 작동하는지에 대한 전체 가이드는 [Discussions and Pull Requests guide](./community)를 참고하세요. ### 토론 목록 리포지토리의 열린 토론과 PR을 나열하려면 리포지토리 ID를 `hf discussions list`(또는 약어 `hf discussions ls`)에 전달하세요: ```bash >>> hf discussions list username/my-model ``` 종류(`discussion` 또는 `pull_request`), 상태(`open`, `closed`, `merged`, 또는 `all`), 또는 작성자로 결과를 좁힐 수 있습니다: ```bash >>> hf discussions list username/my-model --kind pull_request --status merged >>> hf discussions list username/my-model --author alice ``` 스크립팅을 위해 구조화된 출력을 얻으려면 `--format json`을, 토론 번호만(한 줄에 하나씩) 출력하려면 `--quiet`를 사용하세요: ```bash >>> hf discussions list username/my-model --format json >>> hf discussions ls username/my-model --quiet ``` ### 토론 또는 PR에 대한 정보 가져오기 특정 토론이나 PR을 확인하려면 저장소 ID와 토론 번호를 전달하세요: ```bash >>> hf discussions info username/my-model 5 ``` 출력에는 토론 메타데이터(제목, 상태, 작성자 등)와 대화 이벤트 전체 목록이 함께 포함됩니다. pull request의 diff를 표시하려면 대신 `hf discussions diff`를 사용하세요. 기계가 읽을 수 있는 출력을 얻으려면 `--format json`을 사용하고, 다른 도구로 파이프할 때 ANSI 색상을 제거하려면 `NO_COLOR=1`을 설정하세요. ### 토론 또는 PR 생성 새로운 토론을 열려면 `--title`로 제목을 제공하세요. `--body`로 설명을 인라인으로 포함하거나, `--body-file`로 파일에서 불러올 수 있습니다: ```bash >>> hf discussions create username/my-model --title "Bug report" >>> hf discussions create username/my-model --title "Feature request" --body "Please add X" >>> hf discussions create username/my-model --title "Report" --body-file report.md ``` 일반 토론 대신 pull request를 생성하려면 `--pull-request` 플래그를 추가합니다: ```bash >>> hf discussions create username/my-model --title "Fix typo" --pull-request ``` ### 토론이나 PR에 댓글 달기 번호를 지정하여 기존 토론이나 PR에 댓글을 추가합니다. 댓글 본문은 `--body`로 인라인으로 전달하거나, `--body-file`로 파일에서 읽거나, `--body-file -`를 사용하여 stdin에서 파이프할 수 있습니다: ```bash >>> hf discussions comment username/my-model 5 --body "Thanks for reporting!" >>> hf discussions comment username/my-model 5 --body-file review.md >>> echo "LGTM" | hf discussions comment username/my-model 5 --body-file - ``` ### 댓글 수정 discussion 번호와 comment ID를 전달하여 기존 comment를 해당 위치에서 수정합니다. comment ID는 `hf discussions info`로 가져올 수 있습니다: ```bash >>> hf discussions edit username/my-model 5 abc123 --body "Updated comment." >>> hf discussions edit username/my-model 5 abc123 --body-file fixed.md ``` ### 이미지와 비디오 첨부 `hf discussions create`, `comment` 또는 `edit`에 `--attach`를 전달하면 이미지, 비디오 또는 오디오 파일을 업로드하여 본문에 삽입할 수 있습니다. 이는 Hub에서 파일을 댓글 상자로 드래그 앤 드롭하는 것과 동일한 동작입니다. 본문에 이미 파일이 참조되어 있는 경우, 예를 들어 `![Before the fix](./before.png)`와 같이, 해당 참조는 업로드된 파일을 가리킵니다. 그렇지 않으면 파일이 본문에 추가됩니다. 추가된 이미지의 대체 텍스트를 설정하려면 `#` 뒤에 텍스트를 추가합니다: ```bash >>> hf discussions create username/my-model --title "Fix rendering" --pr --body "Before: ![Before the fix](./before.png)" --attach ./before.png --attach "./after.png#After the fix" >>> hf discussions comment username/my-model 5 --body "Here is a demo:" --attach demo.mp4 ``` 지원되는 형식은 PNG, JPEG, GIF, WebP, MP4, MOV, WebM, MP3, WAV이며, 최대 10MB(영상은 50MB)까지입니다. ### 닫기, 다시 열기, 병합 `hf discussions close`를 사용하여 토론이나 PR을 닫을 수 있습니다. 기본적으로 확인을 요청하는 프롬프트가 표시됩니다. 프롬프트를 건너뛰려면 `--yes`를, 종료 메시지를 남기려면 `--comment`를 전달하세요: ```bash >>> hf discussions close username/my-model 5 >>> hf discussions close username/my-model 5 --yes --comment "Resolved" ``` 이전에 닫힌 토론을 다시 열려면 `hf discussions reopen`을 사용하세요: ```bash >>> hf discussions reopen username/my-model 5 --yes ``` Pull request를 병합하려면 `hf discussions merge`를 사용하세요: ```bash >>> hf discussions merge username/my-model 5 --yes ``` ### 이름 변경 및 diff 새 제목을 제공하여 토론을 이름 변경할 수 있습니다: ```bash >>> hf discussions rename username/my-model 5 "Updated title" ``` 터미널에서 pull request의 diff를 바로 보려면 `hf discussions diff`를 사용하세요: ```bash >>> hf discussions diff username/my-model 5 ``` ## hf repos `hf repos`를 사용하면 Hugging Face Hub에서 저장소를 나열, 생성, 복제, 삭제, 이동하고 설정을 업데이트하며 파일을 삭제할 수 있습니다. 브랜치와 태그를 관리하는 하위 명령도 포함됩니다. ### 리포지토리 목록 `hf repos ls`를 사용하여 저장 공간 정보를 포함하여 모든 저장소(모델, 데이터셋, 스페이스, 버킷)를 저장 공간 사용량 기준으로 정렬하여 나열할 수 있습니다. 기본적으로 첫 30개 저장소만 표시됩니다: ```bash # List all your repos (first 30) >>> hf repos ls REPOSITORY TYPE UPDATED VISIBILITY STORAGE % OF TOTAL ------------------------ ------- ---------- ---------- -------- ---------- username/bucket-raw bucket 2026-04-29 public 1.7 TB 72.3% username/my-model model 2026-05-06 public 4.8 GB 18.1% username/my-dataset dataset 2024-09-14 private 598.4 MB 5.2% Hint: Showing 30 of 42 repos. Use `--limit 0` to list all. ``` 저장소 유형으로 필터링하거나, 이름으로 검색하거나, 한도를 조정합니다: ```bash # List only models >>> hf repos ls --type model # Search by name >>> hf repos ls --search "bert" # List repos from an organization >>> hf repos ls --namespace my-org # Combine filters >>> hf repos ls --namespace my-org --type dataset --search "train" # List all repos (no limit) >>> hf repos ls --limit 0 ``` 스크립팅에는 `--format json`을, ID만 출력하려면 `-q`를 사용합니다. 파이프를 사용할 때는 모든 리포지토리를 내보내기 위해 `--limit 0`를 사용합니다: ```bash >>> hf repos ls --limit 0 --format json | jq '.[].id' >>> hf repos ls -q ``` ### 리포지토리 생성 ```bash >>> hf repos create Wauplin/my-cool-model Successfully created Wauplin/my-cool-model on the Hub. Your repo is now available at https://huggingface.co/Wauplin/my-cool-model ``` 프라이빗 데이터셋 또는 Space를 생성합니다: ```bash >>> hf repos create my-cool-dataset --repo-type dataset --private >>> hf repos create my-gradio-space --repo-type space --sdk gradio ``` 리포지토리가 이미 존재할 수 있는 경우 `--exist-ok`를 사용하고, Enterprise 리소스 그룹을 대상으로 하려면 `--resource-group-id`를 사용하세요. 특정 리전에 저장소를 생성합니다: ```bash >>> hf repos create my-model --region us ``` ### 리포지토리 복제 `hf repos duplicate`를 사용하여 기존 모델, 데이터셋 또는 Space를 내 계정(또는 조직)으로 복사할 수 있습니다. 복사는 서버에서 수행되며 git 히스토리가 유지됩니다: ```bash >>> hf repos duplicate openai/gdpval --type dataset >>> hf repos duplicate openai/gdpval myorg/my-gdpval --type dataset --private ``` 명령이 반환된 후에도 새 저장소의 LFS/Xet 파일이 백그라운드에서 복사될 수 있습니다. 이 경우 경고가 출력되며, 복사가 완료될 때까지 새 저장소에서 해당 파일을 다운로드하는 작업이 실패할 수 있습니다. ### 리포지토리 삭제 ```bash >>> hf repos delete Wauplin/my-cool-model ``` 데이터셋과 스페이스: ```bash >>> hf repos delete my-cool-dataset --repo-type dataset >>> hf repos delete my-gradio-space --repo-type space ``` ### 리포지토리 이동 ```bash >>> hf repos move old-namespace/my-model new-namespace/my-model ``` ### 레포지토리 설정 업데이트 ```bash >>> hf repos settings Wauplin/my-cool-model --gated auto >>> hf repos settings Wauplin/my-cool-model --private true >>> hf repos settings Wauplin/my-cool-model --private false ``` - `--gated`: `auto`, `manual`, `false` 중 하나 - `--private true|false`: 저장소 비공개 설정 ### 레포지토리에서 파일 삭제 `hf repos delete-files ` 하위 명령을 사용하면 저장소에서 파일을 삭제할 수 있습니다. 사용 예시는 다음과 같습니다. 폴더 삭제: ```bash >>> hf repos delete-files Wauplin/my-cool-model folder/ Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo... ``` 여러 파일 삭제: ```bash >>> hf repos delete-files Wauplin/my-cool-model file.txt folder/pytorch_model.bin Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo... ``` 와일드카드 패턴을 사용하여 파일 집합을 삭제합니다. 패턴은 [여기](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm)에 문서화된 표준 와일드카드(글로빙 패턴)입니다. 패턴 매칭은 [`fnmatch`](https://docs.python.org/3/library/fnmatch.html)에 기반합니다. > [!WARNING] > `fnmatch`은 전통적인 Unix 셸 글로빙과 달리 `*`이 경로 경계를 넘어 매칭된다는 점에 유의하세요. 예를 들어, `"data/*.json"`은 `data/file.json`과 **그리고** `data/subdir/file.json` 모두에 매칭됩니다. 현재 디렉토리의 파일만 매칭하려면 파일을 명시적으로 나열하거나 더 구체적인 패턴을 사용해야 합니다. ```bash >>> hf repos delete-files Wauplin/my-cool-model "*.txt" "folder/*.bin" Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo... ``` 리포지토리에서 파일을 삭제하려면 인증 및 권한이 필요합니다. 기본적으로 로컬에 저장된 토큰(`hf auth login`을 사용하여 저장)이 사용됩니다. 명시적으로 인증하려면 `--token` 옵션을 사용하세요: ```bash >>> hf repos delete-files --token=hf_**** Wauplin/my-cool-model file.txt ``` ### hf repos branch Hub의 저장소에서 브랜치를 생성하고 삭제하려면 `hf repos branch`를 사용하세요. ```bash # Create a branch >>> hf repos branch create Wauplin/my-cool-model dev # Create a branch from a specific revision >>> hf repos branch create Wauplin/my-cool-model release-1 --revision refs/pr/104 # Delete a branch >>> hf repos branch delete Wauplin/my-cool-model dev ``` > [!TIP] > 모든 명령은 명시적으로 인증이 필요한 경우 `--repo-type`(`model`, `dataset`, `space` 중 하나)과 `--token`을 받아들입니다. 모든 옵션을 보려면 어떤 명령이든 `--help`를 사용하세요. ## hf cache `hf cache`를 사용하여 로컬 Hugging Face 캐시 디렉터리를 관리합니다. 캐시에는 Hub에서 다운로드한 모델, 데이터셋, Spaces, 커널이 저장됩니다. ```bash # List cached repositories >>> hf cache ls # List cached revisions >>> hf cache ls --revisions # Remove specific items from cache >>> hf cache rm model/gpt2 # Remove unreferenced revisions >>> hf cache prune # Verify cached file checksums >>> hf cache verify gpt2 ``` ### hf cache ls `hf cache ls`를 사용하여 Hugging Face 캐시에 로컬로 저장된 내용을 확인합니다. 기본적으로 저장소별로 정보를 집계합니다: ```bash >>> hf cache ls ID SIZE LAST_ACCESSED LAST_MODIFIED REFS --------------------------- -------- ------------- ------------- ----------- dataset/nyu-mll/glue 157.4M 2 days ago 2 days ago main script model/LiquidAI/LFM2-VL-1.6B 3.2G 4 days ago 4 days ago main model/microsoft/UserLM-8b 32.1G 4 days ago 4 days ago main Found 3 repo(s) for a total of 5 revision(s) and 35.5G on disk. ``` `--revisions`를 추가하여 특정 스냅샷으로 자세히 살펴보고, 필터를 체인하여 중요한 부분에 집중할 수 있습니다: ```bash >>> hf cache ls --filter "size>30g" --revisions ID REVISION SIZE LAST_MODIFIED REFS ------------------------- ---------------------------------------- -------- ------------- ---- model/microsoft/UserLM-8b be8f2069189bdf443e554c24e488ff3ff6952691 32.1G 4 days ago main Found 1 repo(s) for a total of 1 revision(s) and 32.1G on disk. ``` 이 명령은 스크립팅을 위한 여러 출력 형식을 지원합니다. `--format json`은 구조화된 객체를 출력하고, `--format csv`은 쉼표로 구분된 행을 작성하며, `--quiet`는 ID만 출력합니다. `--sort`를 사용하여 `accessed`, `modified`, `name`, 또는 `size` 기준으로 항목을 정렬할 수 있으며(순서를 제어하려면 `:asc` 또는 `:desc`를 추가합니다), `--limit`을 사용하여 결과를 상위 N개 항목으로 제한할 수 있습니다. 이 옵션들을 `--cache-dir`과 결합하여 대체 캐시 위치를 지정할 수 있습니다. 고급 워크플로에 대해서는 [캐시 관리](./manage-cache) 가이드를 참조하세요. `hf cache ls --q`로 선택한 캐시 항목의 ID를 `hf cache rm`에 파이프하여 삭제합니다: ```bash >>> hf cache rm $(hf cache ls --filter "accessed>1y" -q) -y About to delete 2 repo(s) totalling 5.31G. - model/meta-llama/Llama-3.2-1B-Instruct (entire repo) - model/hexgrad/Kokoro-82M (entire repo) Deleted 2 repo(s) and 2 revision(s); freed 5.31G. ``` ### hf cache rm `hf cache rm`은 캐시된 저장소, 개별 리비전 또는 단일 파일을 삭제합니다. 하나 이상의 저장소 ID(`model/bert-base-uncased`), `hf://` URI 또는 리비전 해시를 전달합니다: ```bash >>> hf cache rm model/LiquidAI/LFM2-VL-1.6B About to delete 1 repo(s) totalling 3.2G. - model/LiquidAI/LFM2-VL-1.6B (entire repo) Proceed with deletion? [y/N]: y Deleted 1 repo(s) and 2 revision(s); freed 3.2G. ``` 레포지토리 수준의 `hf://` URI도 지원됩니다: ```bash >>> hf cache rm hf://models/openai-community/gpt2 --dry-run About to delete 1 repo(s) totalling 1.1G. - model/openai-community/gpt2 (entire repo) Dry run: no files were deleted. ``` 전체 저장소가 아닌 단일 파일, 예를 들어 GGUF 양자화 파일을 삭제하려면 `hf://` 파일 URI를 전달하세요. 해당 파일은 저장소의 모든 캐시된 리비전에서 제거되며, 다른 캐시된 파일이 여전히 참조하지 않는 경우에만 해당 blob이 삭제됩니다: ```bash >>> hf cache rm hf://models/unsloth/gemma-3-27b-it-GGUF/gemma-3-27b-it-Q4_K_M.gguf --dry-run About to delete 1 file(s) totalling 16.5G. - model/unsloth/gemma-3-27b-it-GGUF@3f4b5c1d2e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c/gemma-3-27b-it-Q4_K_M.gguf Dry run: no files were deleted. ``` 수정판은 계속 사용 가능하며, 삭제된 파일은 다음에 필요할 때 다시 다운로드됩니다. 경로는 정확히 일치해야 합니다: 폴더와 glob 패턴은 지원되지 않으며, 파일 대상은 같은 호출에서 저장소나 수정판과 혼합할 수 없습니다. 같은 호출에서 저장소와 특정 리비전을 혼합하여 사용할 수 있습니다. `--dry-run`을 사용하면 영향을 미리 확인하고, `--yes`를 사용하면 확인 프롬프트를 건너뜁니다. 자동화 스크립트에서 유용합니다: ```bash >>> hf cache rm model/t5-small 8f3ad1c --dry-run About to delete 1 repo(s) and 1 revision(s) totalling 1.1G. - model/t5-small: 8f3ad1c [main] 1.1G Dry run: no files were deleted. ``` 기본 캐시 위치 이외의 위치에서 작업할 경우, 해당 명령에 `--cache-dir PATH`를 함께 사용하세요. ### hf cache prune `hf cache prune`는 캐시 가비지가 차지하는 공간을 회수하는 편의용 단축 명령입니다. 분리된(참조되지 않는) 리비전(브랜치 또는 태그를 통해 여전히 도달 가능한 리비전만 유지), 중단된 다운로드에서 남은 `.incomplete` 파일, 그리고 더 이상 어떤 캐시된 저장소에서도 참조되지 않는 공유 블롭을 모두 제거합니다: ```bash >>> hf cache prune About to delete 3 unreferenced revision(s) and 2 incomplete download(s) (2.4G total). - model/t5-small: 1c610f6b [refs/pr/1] 820.1M d4ec9b72 [(detached)] 640.5M - dataset/google/fleurs: 2b91c8dd [(detached)] 937.6M Proceed? [y/N]: y Deleted 3 unreferenced revision(s) and 2 incomplete download(s); freed 2.4G. ``` `.incomplete` 파일은 다운로드가 중단될 때 남아 있는 부분 다운로드 파일입니다. `hf cache ls`/`rm`는 리비전 수준에서 작동하므로 이 파일들을 추적하지 않으며, `hf cache ls`는 힌트로 이를 표시하고 `hf cache prune`는 자동으로 삭제합니다. 다른 캐시 명령과 마찬가지로 `--dry-run`, `--yes`, `--cache-dir`를 사용할 수 있습니다. 자세한 예제는 [캐시 관리](./manage-cache) 가이드를 참고하세요. ### hf cache verify `hf cache verify`를 사용하여 Hub의 체크섬과 로컬 파일을 검증할 수 있습니다. 캐시 스냅샷이나 일반 로컬 디렉터리를 검증할 수 있습니다. 예: ```bash # Verify main revision of a model in cache >>> hf cache verify deepseek-ai/DeepSeek-OCR # Verify a specific revision >>> hf cache verify deepseek-ai/DeepSeek-OCR --revision refs/pr/5 >>> hf cache verify deepseek-ai/DeepSeek-OCR --revision ef93bf4a377c5d5ed9dca78e0bc4ea50b26fe6a4 # Verify a private repo >>> hf cache verify me/private-model --token hf_*** # Verify a dataset >>> hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type dataset # Verify files in a local directory >>> hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repo ``` 기본적으로 이 명령은 누락되거나 추가된 파일에 대해 경고를 표시합니다. 이러한 경고를 오류로 전환하려면 플래그를 사용하세요: ```bash >>> hf cache verify deepseek-ai/DeepSeek-OCR --fail-on-missing-files --fail-on-extra-files ``` 성공하면 요약이 표시됩니다: ```text ✅ Verified 13 file(s) for 'deepseek-ai/DeepSeek-OCR' (model) in ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct/snapshots/9213176726f574b556790deb65791e0c5aa438b6 All checksums match. ``` 불일치가 감지되면, 해당 명령은 상세한 목록을 출력하고 0이 아닌 상태로 종료됩니다. ### hf repos tag `hf repos tag`를 사용하여 Hub의 저장소에 대한 태그를 생성, 목록 및 삭제합니다. ```bash # Create a tag >>> hf repos tag create my-model v1.0 # List tags >>> hf repos tag list my-model # Delete a tag >>> hf repos tag delete my-model v1.0 ``` ### 모델에 태그 지정 리포지토리에 태그를 지정하려면 `repo_id`와 `tag` 이름을 제공해야 합니다: ```bash >>> hf repos tag create Wauplin/my-cool-model v1.0 You are about to create tag v1.0 on model Wauplin/my-cool-model Tag v1.0 created on Wauplin/my-cool-model ``` ### 특정 리비전으로 모델을 태그 특정 리비전을 태그하려면 `--revision` 옵션을 사용할 수 있습니다. 기본적으로 태그는 `main` 브랜치에 생성됩니다: ```bash >>> hf repos tag create Wauplin/my-cool-model v1.0 --revision refs/pr/104 You are about to create tag v1.0 on model Wauplin/my-cool-model Tag v1.0 created on Wauplin/my-cool-model ``` ### 데이터셋 또는 Space에 태그를 지정 데이터셋 또는 Space에 태그를 지정하려면 `--repo-type` 옵션을 지정해야 합니다: ```bash >>> hf repos tag create bigcode/the-stack v1.0 --repo-type dataset You are about to create tag v1.0 on dataset bigcode/the-stack Tag v1.0 created on bigcode/the-stack ``` ### 태그 목록 리포지토리의 모든 태그를 나열하려면 `list`(또는 `ls`) 하위 명령을 사용합니다: ```bash >>> hf repos tag list Wauplin/gradio-space-ci --repo-type space Tags for space Wauplin/gradio-space-ci: 0.2.2 0.2.1 0.2.0 0.1.2 0.0.2 0.0.1 ``` ### 태그 삭제 태그를 삭제하려면 `delete` 하위 명령을 사용합니다: ```bash >>> hf repos tag delete Wauplin/my-cool-model v1.0 You are about to delete tag v1.0 on model Wauplin/my-cool-model Proceed? [Y/n] y Tag v1.0 deleted on Wauplin/my-cool-model ``` 확인 단계를 건너뛰려면 `-y`를 전달할 수도 있습니다. ## hf env `hf env` 명령은 머신 설정에 대한 세부 정보를 출력합니다. [GitHub](https://github.com/huggingface/huggingface_hub)에서 이슈를 열 때 유지보수자가 문제를 조사하는 데 도움이 됩니다. ```bash >>> hf env Copy-and-paste the text below in your GitHub issue. - huggingface_hub version: 1.0.0.rc6 - Platform: Linux-6.8.0-85-generic-x86_64-with-glibc2.35 - Python version: 3.11.14 - Running in iPython ?: No - Running in notebook ?: No - Running in Google Colab ?: No - Running in Google Colab Enterprise ?: No - Token path ?: /home/wauplin/.cache/huggingface/token - Has saved token ?: True - Who am I ?: Wauplin - Configured git credential helpers: store - Installation method: unknown - Torch: N/A - httpx2: 2.0.0 - hf_xet: 1.1.10 - gradio: 5.41.1 - tensorboard: N/A - pydantic: 2.11.7 - ENDPOINT: https://huggingface.co - HF_HUB_CACHE: /home/wauplin/.cache/huggingface/hub - HF_ASSETS_CACHE: /home/wauplin/.cache/huggingface/assets - HF_TOKEN_PATH: /home/wauplin/.cache/huggingface/token - HF_STORED_TOKENS_PATH: /home/wauplin/.cache/huggingface/stored_tokens - HF_HUB_OFFLINE: False - HF_HUB_DISABLE_TELEMETRY: False - HF_HUB_DISABLE_PROGRESS_BARS: None - HF_HUB_DISABLE_SYMLINKS_WARNING: False - HF_HUB_DISABLE_EXPERIMENTAL_WARNING: False - HF_HUB_DISABLE_IMPLICIT_TOKEN: False - HF_HUB_DISABLE_XET: False - HF_HUB_DISABLE_SHARED_BLOBS: False - HF_HUB_ETAG_TIMEOUT: 10 - HF_HUB_DOWNLOAD_TIMEOUT: 10 ``` ## hf jobs Docker와 유사한 친숙한 인터페이스를 사용하여 Hugging Face 인프라에서 compute 작업을 실행합니다. `hf jobs`는 간단한 명령어로 Hugging Face 인프라(그래픽 처리 장치(GPU)와 텐서 처리 장치(TPU) 포함!)에서 모든 것을 실행할 수 있는 명령줄 도구입니다. `docker run`처럼 생각하되, A100에서 코드를 실행하는 용도로 보시면 됩니다. **Jobs와 가격에 대한 일반적인 개요는 [Hub Jobs 문서](https://huggingface.co/docs/hub/jobs)를 참고하세요.** CLI와 함께 Python API를 사용하는 방법은 [Jobs 실행 및 관리 가이드](./jobs)를 참고하세요. ```bash # Directly run Python code >>> hf jobs run --name hello-world python:3.12 python -c 'print("Hello from the cloud!")' # Use GPUs without any setup >>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \ ... python -c "import torch; print(torch.cuda.get_device_name())" # Run in an organization account >>> hf jobs run --namespace my-org-name python:3.12 python -c 'print("Running in an org account")' # Run from Hugging Face Spaces >>> hf jobs run hf.co/spaces/lhoestq/duckdb duckdb -c 'select "hello world"' # Run a Python script with `uv` (experimental) >>> hf jobs uv run --name my-script my_script.py ``` > [!TIP] > **Hugging Face Jobs**는 [선불 크레딧](https://huggingface.co/settings/billing)이 있는 모든 사용자 또는 조직에서 사용할 수 있습니다. ### 빠른 시작 #### 1. 첫 번째 작업 실행 ```bash # Run a simple Python script >>> hf jobs run python:3.12 python -c 'print("Hello from HF compute!")' ``` 이 명령은 작업을 실행하고 로그를 표시합니다. `--detach`를 전달하면 작업을 백그라운드에서 실행하고 Job ID만 출력합니다. `-q`를 추가하면 Job ID만 출력하므로 스크립트에서 이를 캡처하는 데 유용합니다: ```bash >>> JOB_ID=$(hf jobs run -dq python:3.12 python train.py) >>> hf jobs wait "$JOB_ID" ``` #### 2. 작업 상태 확인 ```bash # List your running jobs >>> hf jobs ls # List all jobs >>> hf jobs ls -a # Inspect the status of a job >>> hf jobs inspect # View logs from a job >>> hf jobs logs # View resources usage stats and metrics of running jobs >>> hf jobs stats # View resources usage stats and metrics of some jobs >>> hf jobs stats [job_ids]... # Follow live stats until the jobs complete >>> hf jobs stats -f [job_ids]... # Cancel a job >>> hf jobs cancel # Wait until one or more jobs finish (exit code 0 only if all jobs completed successfully) >>> hf jobs wait [...] # Wait for all currently running jobs >>> hf jobs ls -q | xargs hf jobs wait ``` Non-detached `hf jobs run` 및 `hf jobs wait`은 Job이 실패하면 0이 아닌 코드로 종료되므로, `&&`를 사용하여 명령을 연결할 수 있습니다: ```bash >>> hf jobs run python:3.12 python train.py && echo "training succeeded" ``` #### 3. GPU에서 실행 `--flavor` 옵션을 사용하여 GPU 또는 TPU에서 작업을 실행할 수도 있습니다. 예를 들어, A10G GPU에서 PyTorch 작업을 실행하려면: ```bash # Use an A10G GPU to check PyTorch CUDA >>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \ ... python -c 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")' ``` 이것을 실행하면 다음과 같은 출력이 표시됩니다! ```bash This code ran with the following GPU: NVIDIA A10G ``` `--`를 사용하여 Jobs 옵션과 명령어나 스크립트에 전달되는 인수를 구분합니다. `--` 이후의 옵션은 Jobs가 해석하지 않습니다. ```bash >>> hf jobs run --flavor cpu-basic python:3.12 -- python --help ``` 이것으로 끝입니다! 이제 Hugging Face의 인프라에서 코드를 실행하고 있습니다. ### 일반적인 사용 사례 - **모델 학습**: 인프라를 관리하지 않고 GPU(T4, A10G, A100)에서 모델을 파인튜닝하거나 학습합니다 - **합성 데이터 생성**: 강력한 하드웨어에서 LLM을 사용하여 대규모 데이터셋 생성 - **데이터 처리**: 대규모 데이터셋을 병렬 워크로드를 위해 고 CPU 구성으로 처리 - **배치 추론**: 최적화된 GPU 구성을 사용하여 수천 개의 샘플에 대해 오프라인 추론을 실행 - **실험 및 벤치마크**: 재현 가능한 결과를 위해 일관된 하드웨어에서 ML 실험을 실행합니다 - **개발 및 디버깅**: 로컬 CUDA 설정 없이 GPU 코드 테스트 ### 환경 변수 및 Secrets 전달 …를 사용하여 작업에 환경 변수를 전달할 수 있습니다 ```bash # Pass environment variables >>> hf jobs run -e FOO=foo -e BAR=bar python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])' ``` ```bash # Pass an environment from a local .env file >>> hf jobs run --env-file .env python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])' ``` ```bash # Pass secrets by name - the value is read from your environment, never from the command line >>> hf jobs run -s MY_SECRET python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])' ``` ```bash # Pass secrets from a local .env.secrets file - they will be encrypted server side >>> hf jobs run --secrets-file .env.secrets python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])' ``` ```bash # Or pipe them in, so the values touch neither the command line nor the disk >>> printf 'MY_SECRET=psswrd\n' | hf jobs run --secrets-file - python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])' ``` Secrets는 세 가지 형태 모두에서 서버 측에서 암호화됩니다. `-s MY_SECRET=psswrd`도 작동하지만, 이 경우 값이 셸 히스토리와 프로세스 목록(`/proc//cmdline`, Linux)에 기록되므로 CLI는 이를 사용할 때 stderr에 경고를 출력합니다. 이 형태는 실제로 민감하지 않은 값에만 사용하세요. `--token `에도 동일한 규칙이 적용됩니다: `hf auth login` 또는 `HF_TOKEN` 환경 변수를 사용하는 것이 좋습니다. env 또는 secrets 파일은 본인만 읽을 수 있어야 합니다(`chmod 600`) — 그렇지 않으면 CLI가 경고를 표시합니다. > [!TIP] > `--secrets HF_TOKEN`를 사용하여 로컬 Hugging Face 토큰을 암시적으로 전달할 수 있습니다. 이 구문을 사용하면 시크릿은 환경 변수에서 가져옵니다. `HF_TOKEN`의 경우, 환경 변수가 설정되지 않았다면 Hugging Face 홈 폴더에 있는 토큰 파일을 읽을 수 있습니다. #### 내장 환경 변수 컨테이너 내부에서 다음 환경 변수가 자동으로 사용 가능합니다: | 변수 | 설명 | | ------------- | ------------------------------------------------------------------------------------------------------- | | `JOB_ID` | 현재 작업의 고유 식별자입니다. 이를 사용하여 작업을 프로그래밍 방식으로 참조합니다. | | `ACCELERATOR` | 사용 가능한 가속기의 유형(예: `t4-medium`, `a10g-small`, `a100x4`). 가속기가 없으면 비어 있습니다. | | `CPU_CORES` | 작업에 사용할 수 있는 CPU 코어의 수 (예: `2`, `4`, `8`). | | `MEMORY` | 작업에 사용할 수 있는 메모리 양(예: `16Gi`, `32Gi`). | ```bash # Access job environment information >>> hf jobs run python:3.12 python -c "import os; print(f'Job: {os.environ.get(\"JOB_ID\")}, CPU: {os.environ.get(\"CPU_CORES\")}, Mem: {os.environ.get(\"MEMORY\")}')" ``` ### 작업 시간 초과 Jobs에는 기본적으로 30분의 타임아웃이 설정되어 있으며, 이 시간이 지나면 자동으로 중지됩니다. 모델 학습과 같은 장기 실행 작업의 경우, `--timeout` 옵션을 사용하여 사용자 지정 타임아웃을 설정하세요: ```bash # Set timeout in seconds (default unit) >>> hf jobs run --timeout 7200 python:3.12 python train.py # Use time units: s (seconds), m (minutes), h (hours), d (days) >>> hf jobs run --timeout 2h pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel python train.py >>> hf jobs run --timeout 90m python:3.12 python process_data.py >>> hf jobs run --timeout 1.5h python:3.12 python train.py # floats are supported ``` `--timeout` 옵션은 UV 스크립트와 예약 작업에서도 작동합니다: ```bash # UV script with timeout >>> hf jobs uv run --timeout 2h training_script.py # Scheduled job with timeout >>> hf jobs scheduled run @daily --timeout 4h python:3.12 python daily_task.py ``` > [!WARNING] > 작업이 시간 초과를 초과하면 자동으로 종료됩니다. 예상치 못한 작업 종료를 방지하려면 긴 실행 시간의 작업에 대해 충분한 여유를 두고 적절한 시간 초과를 설정하세요. ### Job 재시도 및 재실행 `--attempts`는 첫 실행을 포함하여 최대 시도 횟수를 설정합니다. Docker, UV, 예약된 Job과 함께 작동합니다. Job을 다시 실행하면 동일한 저장된 spec로 새 Job이 시작됩니다: ```bash >>> hf jobs run --attempts 3 --detach python:3.12 python train.py >>> hf jobs rerun ``` 시도 횟수가 3이면 Job이 실패할 때 최대 2회까지 재시도할 수 있습니다. `hf jobs rerun`도 원래의 시도 횟수를 재사용합니다. `hf jobs run`과 마찬가지로, 새 Job이 완료될 때까지 로그를 스트리밍합니다. 즉시 반환하려면 `--detach`를 사용하세요. ### 하드웨어 사용 가능한 `--flavor` 옵션: - CPU: `cpu-basic`, `cpu-upgrade` - GPU: `t4-small`, `t4-medium`, `l4x1`, `l4x4`, `a10g-small`, `a10g-large`, `a10g-largex2`, `a10g-largex4`,`a100-large` - TPU: `v5e-1x1`, `v5e-2x2`, `v5e-2x4` (2025년 7월 업데이트, Hugging Face [suggested_hardware 문서](https://huggingface.co/docs/hub/en/spaces-config-reference)에서 가져옴) ## 볼륨 `-v` 또는 `--volume`를 사용하여 Job의 디스크에 볼륨을 마운트합니다. Hugging Face 리포지토리(모델/데이터셋/스페이스) 또는 [Storage Bucket](/docs/hub/storage-buckets)를 `hf://` URL 스키마를 사용하여 마운트할 수 있습니다. 예를 들어: * 모델 저장소 마운트: `-v hf://openai/gpt-oss-120b:/model` * 데이터셋 저장소를 마운트: `-v hf://datasets/HuggingFaceFW/fineweb:/data` * 스토리지 버킷 마운트: `-v hf://buckets/username/my-bucket:/mnt` * space 마운트: `-v hf://spaces/username/my-space:/app` * 리포지토리 내부의 하위 폴더를 마운트: `-v hf://datasets/org/ds/train:/data` 그런 다음 마운트된 볼륨을 로컬 디렉터리로 사용할 수 있습니다: ```bash # Docker Job with a mounted volume as input >>> hf jobs run -v hf://datasets/HuggingFaceFW/fineweb:/dataset \ ... duckdb/duckdb duckdb -c "SELECT * FROM '/dataset/**/*.parquet' LIMIT 5" # UV Job with a mounted volume to save checkpoints when training a model >>> hf jobs uv run -v hf://buckets/username/my-bucket:/training-outputs \ ... sft.py --output-dir /training-outputs/training-v3-final ... ``` 모델, 데이터셋, 스페이스는 항상 읽기 전용으로 마운트됩니다. 스토리지 버킷은 기본적으로 읽기+쓰기 권한을 가지며, 이는 자주 변경되는 데이터에 특히 유용합니다. 파일을 원위치에서 덮어쓰기하거나 삭제할 수 있기 때문입니다. 읽기 전용을 활성화하려면 `:ro`를 사용하세요: * 읽기 전용으로 스토리지 버킷 마운트: `-v hf://buckets/username/my-bucket:/mnt:ro` ### 로컬 데이터 마운트 `-v`의 소스 측도 로컬 디렉터리일 수 있습니다. 먼저 `jobs-artifacts` [Storage Bucket](/docs/hub/storage-buckets)에 동기화되고, 생성된 버킷 폴더가 Job에 마운트됩니다: ```bash >>> hf jobs uv run -v ./my-data:/data process.py ``` 명령을 다시 실행하면 새 파일 또는 수정된 파일만 업로드됩니다. 로컬 디렉터리는 기본적으로 읽기 전용으로 마운트됩니다. Job이 볼륨에 쓸 수 있도록 하려면 `:rw`를 사용하세요. 예를 들어, Job이 완료된 후 출력을 가져오는 경우(빈 로컬 디렉터리도 사용 가능)에 사용할 수 있습니다: ```bash >>> hf jobs uv run -v ./pdfs:/input -v ./md-out:/output:rw ocr.py ... Hint: Volume '/output' is mounted read-write. Once the job is over, pull back its data with: hf buckets sync hf://buckets/username/jobs-artifacts/md-out-a1b2c3d4 ./md-out ``` ### 레이블 `-l` 또는 `--label`을 사용하여 Job에 라벨을 추가합니다. 라벨은 Job에 메타데이터를 적용하는 key=value 쌍입니다. Job에 두 개의 라벨을 지정하려면 라벨 플래그(`-l` 또는 `--label`)를 반복합니다: ```bash >>> hf jobs run -l my-label --label foo=bar ubuntu echo "This Job has multiple labels" ``` my-label 키에는 값이 지정되지 않았으므로 기본값은 빈 문자열("")입니다. Job을 생성할 때 `--name`을 사용하여 `name` 라벨을 추가합니다. 이름은 UI에서 Job을 더 쉽게 찾고 식별할 수 있게 해주며, 선택 사항이고 고유할 필요가 없습니다. `--name`를 전달하지 않으면 Docker 이미지나 스크립트에서 자동으로 이름이 유도되며, 명령어와 해석된 런타임 설정(flavor, timeout, environment values, ...)의 짧은 해시가 추가됩니다. 따라서 동일한 구성은 항상 동일한 이름(e.g. `python:3.12 foo --truc` → `python-3-12-1a2b3c4d`)을 생성합니다. 명령어가 동일하더라도 설정을 변경하면 이름이 변경됩니다. 기존 Job의 이름을 변경할 수도 있습니다: ```bash >>> hf jobs run --name training-v2 python:3.12 python train.py >>> hf jobs labels --name training-v2 ``` `hf jobs ls`에서 `--status`, `--label`, `--name`를 사용하여 Jobs를 필터링할 수 있습니다. `--status`는 하나 이상의 상태를, `--label`는 `key=value` 쌍을, `--name`은 `--label name=NAME`의 단축어입니다. Job은 모든 필터에 일치해야 목록에 표시됩니다. Job 이름은 자체 `NAME` 컬럼으로도 표시됩니다: ```bash # Show completed Jobs >>> hf jobs ls -a --status completed # Show running or scheduling Jobs >>> hf jobs ls --status running,scheduling # Show Jobs named `training-v2` >>> hf jobs ls -a --name training-v2 # Show Jobs with the `model=Qwen3-06B` label >>> hf jobs ls -a --label model=Qwen3-06B # Combine filters: running Jobs labelled both `env=prod` and `team=ml` >>> hf jobs ls --status running --label env=prod --label team=ml ``` 기본적으로 `hf jobs ps`는 터미널이 과도하게 커지는 것을 방지하기 위해 최대 100개의 Job만 표시합니다. `--limit`을 사용하여 이 값을 변경하거나, `--limit 0`을 사용하여 모든 Job을 표시할 수 있습니다: ```bash # Show up to 500 Jobs >>> hf jobs ps -a --limit 500 # Show all Jobs (no limit) >>> hf jobs ps -a --limit 0 ``` ### Job 포트 노출 토큰으로 보호되는 포트에는 `--expose`를, 인증 없이 접근을 허용해야 하는 포트에는 `--expose-public`를 사용합니다. 두 플래그는 반복 및 조합이 가능하며 Docker, UV, 예약된 Jobs와 함께 작동합니다. ```bash # Start a Job with a public HTTP server >>> hf jobs run --detach --expose-public 8000 python:3.12 python -m http.server 8000 # Replace the configuration on a running Job: port 8000 is private, 9000 is public >>> hf jobs expose 8000 --public 9000 # Close all exposed ports >>> hf jobs expose --clear ``` `hf jobs expose`는 토큰으로 보호되는 포트를 위치 인수로, `--public` 플래그를 사용하여 공개 포트를 지정합니다. 이 명령은 Job을 다시 실행하지 않고 변경 사항을 적용합니다. 교체 목록에서 생략된 포트는 닫힙니다. ### Job에 SSH로 접속 `hf jobs run`(또는 `hf jobs uv run`)에 `--ssh`를 전달하여 Job 컨테이너를 SSH로 접근 가능하게 한 다음, `hf jobs ssh`로 연결합니다: ```bash # Start a job with SSH enabled >>> hf jobs run --ssh --detach python:3.12 sleep infinity # Open an SSH session into it >>> hf jobs ssh # Print the SSH command instead of running it >>> hf jobs ssh --dry-run # Use a specific identity file >>> hf jobs ssh -i ~/.ssh/id_ed25519 ``` Job의 namespace에 쓰기 권한이 있는 사용자만(즉, Job 생성자 또는 소유 조직의 멤버) https://huggingface.co/settings/keys에 등록된 SSH 공개 키로 인증되어 접근할 수 있습니다. ### 네트워크 그룹 `hf jobs run`(또는 `hf jobs uv run`)에 `--network-group `를 전달하면, 동일한 namespace와 resource group에 있는 Jobs가 모든 포트에서 서로 통신할 수 있습니다. 각 멤버 내부에서 `$HF_NETWORK_GROUP_HOSTNAME`은 그룹 내 모든 Job으로 해석되며, `--network-alias `로 별명을 선언한 멤버는 `${HF_NETWORK_GROUP_PREFIX}`로 해석됩니다: ```bash # Start a server, reachable by the other members of the group as "master" >>> hf jobs run --detach --network-group train --network-alias master python:3.12 python -m http.server 8000 # Start a client in the same group >>> hf jobs run --detach --network-group train python:3.12 sh -c 'curl --retry 10 --retry-connrefused "http://${HF_NETWORK_GROUP_PREFIX}master:8000/"' ``` 멤버는 준비가 완료되기 전에도 해석될 수 있으므로, 재시도(retry)를 사용하여 연결하세요. 그룹 이름과 별칭은 소문자 영숫자 및 대시(-)로만 구성되며, 최대 길이는 각각 46자 및 34자입니다. ### UV 스크립트 (실험적) HF 인프라에서 UV 스크립트(인라인 의존성이 포함된 Python 스크립트)를 실행합니다. UV 스크립트는 특수한 주석 문법을 사용하여 파일 내에 의존성을 직접 포함하는 Python 스크립트입니다. ```bash # Run a UV script (creates temporary repo) >>> hf jobs uv run my_script.py # Run with persistent repo >>> hf jobs uv run --repo my-uv-scripts my_script.py # Run with GPU >>> hf jobs uv run --flavor t4-small ml_training.py # Pass arguments to script >>> hf jobs uv run process.py input.csv output.parquet # Add dependencies >>> hf jobs uv run --with transformers --with torch train.py # Run a script directly from a URL >>> hf jobs uv run https://huggingface.co/datasets/username/scripts/resolve/main/example.py # Run a command >>> hf jobs uv run --with lighteval python -c 'import lighteval' ``` UV 스크립트는 특수한 주석 문법을 사용하여 의존성을 파일 내에 직접 포함하는 Python 스크립트입니다. 이는 복잡한 프로젝트 설정이 필요하지 않은 자체 완결형 작업에 적합합니다. [UV 문서](https://docs.astral.sh/uv/guides/scripts/)에서 UV 스크립트에 대해 자세히 알아보세요. `--`를 사용하여 충돌하는 옵션을 스크립트로 전달합니다. 여기서는 `--help`가 Jobs 도움말을 표시하는 대신 `train.py`로 전달됩니다: ```bash >>> hf jobs uv run --flavor t4-small train.py -- --help ``` 포맷팅 플래그에도 동일하게 적용됩니다: `hf jobs run`, `hf jobs uv run` 및 이들의 `scheduled` 변형은 `--format`, `--json`, `-q`가 어디에 나타나든 이를 소비하므로, 스크립트가 이러한 플래그를 필요로 할 때는 `--`를 사용하세요. #### launch config를 스크립트와 함께 배포 일부 스크립트는 특정 런타임(특정 이미지, GPU flavor, 시스템 인터프리터 등)에서만 올바르게 실행됩니다. 스크립트는 PEP 723 헤더의 선택적 `[tool.hf-jobs]` 테이블에 해당 구성을 포함할 수 있습니다: ```python # /// script # requires-python = ">=3.11" # dependencies = ["vllm", "datasets"] # # [tool.hf-jobs] # name = "unlimited-ocr" # image = "vllm/vllm-openai:unlimited-ocr" # flavor = "l4x1" # python = "/usr/bin/python3" # timeout = "2h" # env = { PYTHONPATH = "/usr/local/lib/python3.12/dist-packages", BATCH_SIZE = "64" } # secrets = ["HF_TOKEN"] # labels = { task = "ocr" } # volumes = ["hf://datasets/org/pdfs:/input"] # /// ``` `hf jobs uv run ocr.py in_ds out_ds`를 실행하면 잘못된 인터프리터가 포함된 CPU 이미지에서 조용히 실행되는 대신, 올바른 런타임으로 시작됩니다. 일반 `uv run`에서는 이 테이블이 보이지 않습니다. `[tool.*]` 테이블은 PEP 723의 일부이며, 도구는 자신이 관리하지 않는 테이블을 무시합니다. 지원되는 키는 모두 선택 사항입니다: `image`, `flavor`, `python`, `timeout`, `name`, `namespace`, `env`, `secrets`, `labels`, `volumes`, `network_group` 및 `network_aliases`. 이들은 동일한 이름의 플래그에 매핑됩니다(`name`은 `name` 레이블로 저장되고, `volumes`는 `-v`와 동일한 `hf://...:/MOUNT_PATH` 스펙을 사용하며, `network_aliases`는 `--network-alias` 값의 목록입니다). 알려지지 않은 키는 조용히 무시되는 것이 아니라 오류로 처리됩니다. `flavour`와 같은 오타는 이 기능이 존재하는 것을 방지하려는 실패 사례입니다. 모든 값은 문자열이어야 하며, `env`와 `labels`의 값도 포함됩니다: `-e BATCH_SIZE=64`는 `env = { BATCH_SIZE = "64" }`로 변환되며, `env = { BATCH_SIZE = 64 }`가 아닙니다 (TOML은 후자를 정수로 해석하여 테이블을 거부합니다). 유일한 예외는 `timeout`이며, 이는 초 단위의 정수도 허용합니다(`timeout = 7200`은 `timeout = "2h"`와 동일합니다). 스크립트의 값은 *기본값*입니다. 명시된 플래그가 항상 우선하며, `env`, `secrets`, `labels`, `volumes`는 항목별로 병합되므로 `-e`와 `-v`를 사용하여 스크립트가 선언한 내용에 추가할 수 있습니다: ```bash # Same script, on bigger hardware, with one extra env var >>> hf jobs uv run --flavor a10g-large -e BATCH_SIZE=64 ocr.py in_ds out_ds ``` `network_aliases`는 예외입니다. Job이 주장하는 alias는 집합을 형성하므로, `--network-alias`는 스크립트의 목록에 추가하는 대신 이를 대체합니다. 예약된 Job에는 네트워크 그룹이 전혀 없으므로, `hf jobs scheduled uv run`는 `network_group` 또는 `network_aliases`를 선언하는 스크립트를 거부합니다. `secrets`는 시크릿 *이름*만 나열합니다. 값은 항상 스크립트를 실행하는 사용자의 환경에서 가져오며, 스크립트 자체에서는 가져오지 않습니다(`HF_TOKEN`도 `hf auth login`에서 해석됩니다). 요청되었지만 로컬에 설정되지 않은 시크릿은 Job이 빈 값을 조용히 받는 대신 오류로 처리됩니다. `--dry-run`을 사용하면 대신 ``로 표시되므로, 시크릿이 아직 프로비저닝되지 않은 스크립트의 구성도 확인할 수 있습니다. 모든 실행은 제출된 구성을 출력하며, 스크립트에서 가져온 값을 표시합니다. 아무것도 시작하지 않고 출력하려면 `--dry-run`을 사용하세요: ```bash >>> hf jobs uv run --dry-run --flavor a10g-large ocr.py in_ds out_ds Warning: The script's [tool.hf-jobs] table requests HF_TOKEN: the value(s) from your local environment would be sent to the Job. Job configuration: script ocr.py args in_ds out_ds image vllm/vllm-openai:unlimited-ocr (from script) flavor a10g-large python /usr/bin/python3 (from script) timeout 2h (from script) env PYTHONPATH=/usr/local/lib/python3.12/dist-packages (from script) BATCH_SIZE=64 (from script) secrets HF_TOKEN=*** (from script) volumes hf://datasets/org/pdfs:/input (from script) labels task=ocr (from script) name=unlimited-ocr (from script) (dry run) Job not submitted. ``` > [!TIP] > URL 뒤에 있는 스크립트에도 적용됩니다. Job이 제출될 때 스크립트가 한 번만 다운로드되어(헤더를 읽기 위해) 컨테이너가 다시 다운로드하지 않고 로컬 스크립트처럼 Job에 전달됩니다. URL은 사용자의 머신에서 접근 가능해야 합니다. 로컬 스크립트와 마찬가지로 URL 스크립트는 예약된 `/data` 아티팩트 마운트를 사용하므로, 입력 볼륨에는 다른 마운트 경로를 사용하세요. `hf jobs scheduled uv run`의 경우, 이 설정은 스크립트를 생성 시점의 콘텐츠에 고정합니다. 소스 URL을 업데이트해도 향후 실행이 변경되지 않습니다. 새 버전을 적용하려면 예약된 Job을 다시 생성해야 합니다. `--dry-run`은 `hf jobs run`, `hf jobs scheduled run`, `hf jobs scheduled uv run`에서도 사용할 수 있습니다. 이 옵션은 제출 및 로컬 볼륨 업로드를 건너뜁니다. Docker Jobs와 UV Jobs 모두에 자동 생성되는 이름에는 해석된 런치 구성이 포함되므로, 런타임 설정이나 환경 값을 변경하면 이름도 변경됩니다. ### hf jobs scheduled HF 인프라에서 실행될 작업을 예약하고 관리합니다. 스케줄은 `@annually`, `@yearly`, `@monthly`, `@weekly`, `@daily`, `@hourly` 중 하나이거나 CRON 스케줄 표현식(예: 매주 월요일 오전 9시를 나타내는 `"0 9 * * 1"`)이어야 합니다. ```bash # Schedule a job that runs every hour >>> hf jobs scheduled run @hourly --name hourly-task python:3.12 python -c 'print("This runs every hour!")' # Use the CRON syntax >>> hf jobs scheduled run "*/5 * * * *" python:3.12 python -c 'print("This runs every 5 minutes!")' # Schedule with GPU >>> hf jobs scheduled run @hourly --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \ ... python -c 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")' # Schedule a UV script >>> hf jobs scheduled uv run @hourly --name hourly-script my_script.py ``` 환경 변수, 시크릿, 타임아웃 등을 전달하려면 `hf jobs run`과 동일한 매개변수를 사용하세요. 를 사용하여 예약된 작업을 관리합니다 ```bash # List your active scheduled jobs >>> hf jobs scheduled ls # Same filters as `hf jobs ls`: --status, --label and --name >>> hf jobs scheduled ls --all >>> hf jobs scheduled ls --status suspended >>> hf jobs scheduled ls --name hourly-task --label env=prod # Inspect the status of a job >>> hf jobs scheduled inspect # Suspend (pause) a scheduled job >>> hf jobs scheduled suspend # Resume a scheduled job >>> hf jobs scheduled resume # Change future run times (Mondays at 9:00) >>> hf jobs scheduled reschedule "0 9 * * 1" # Trigger a scheduled job to run right now (does not change the schedule) >>> hf jobs scheduled trigger # Delete a scheduled job >>> hf jobs scheduled delete ``` ## hf 샌드박스 `hf sandbox`는 Jobs 기반의 격리된 클라우드 머신을 생성합니다. 하나를 만들고, 실시간 스트리밍되는 출력을 가진 명령을 실행하며, 파일을 복사해 넣거나 꺼낼 수 있습니다. `/bin/sh`가 포함된 모든 Docker 이미지가 작동합니다. Python API는 [Sandboxes 가이드](./sandbox)를, 내부 작동 원리는 [개념 가이드](../concepts/sandbox)를 참고하세요. > [!NOTE] > Sandboxes는 실험적이며, API와 동작이 사전 통보 없이 변경될 수 있습니다. 공유 샌드박스는 동일한 신뢰 경계 내의 워크로드를 위해 설계되었습니다. 서로를 신뢰하지 않는 워크로드의 경우 전용 샌드박스를 사용하세요. ```bash # Create a sandbox (waits until it is ready, prints its id) >>> hf sandbox create ✓ Sandbox ready id=687f911eaea852de79c4a50a image=python:3.12 elapsed=6.0s # Attach labels to the underlying Job >>> hf sandbox create --label controller-run=run-42 --label team=data-infra # Run commands inside it (output is streamed, exit code is propagated) >>> hf sandbox exec 687f911eaea852de79c4a50a -- python -c "print('hi')" hi # Copy files in and out (docker-style) >>> hf sandbox cp data.csv 687f911eaea852de79c4a50a:/data/data.csv >>> hf sandbox cp 687f911eaea852de79c4a50a:/app/results.json results.json # Terminate a sandbox >>> hf sandbox kill 687f911eaea852de79c4a50a ``` `--flavor`로 하드웨어(예: `a10g-small`)를 선택하고, `--idle-timeout`으로 샌드박스 수명 상한을 설정하며, `-l` / `--label`로 해당 Job에 라벨을 붙입니다. 저렴한 CPU 샌드박스를 대량으로 배포하려면 `hf sandbox pool create`로 풀을 미리 준비하고, `hf sandbox create --pool `로 해당 풀에 생성합니다([Sandboxes 가이드](./sandbox#from-the-cli) 참고). ### 샌드박스에 환경 변수와 시크릿 전달 저장 속성이 다른 두 개의 독립된 채널이 있습니다: | 채널 | flags | 전용 샌드박스 | 풀된 샌드박스 (`--pool`) | | ----------- | ------------------------------------ | -------------------------- | ----------------------------------------------------------------- | | environment | `-e` / `--env`, `--env-file` | 에 저장 | 생성 시 호스트에 전달되며, 작업 메타데이터에 저장되지 않습니다 | | secrets | `-s` / `--secrets`, `--secrets-file` | 서버 측 암호화 | **사용 불가** — `--env` 사용 | ```bash # Plain environment variables >>> hf sandbox create -e LOG_LEVEL=debug --env-file .env # Secrets, read from your environment by name (nothing sensitive on the command line) >>> hf sandbox create -s OPENAI_API_KEY -s HF_TOKEN # Secrets from a file, or piped in on stdin >>> hf sandbox create --secrets-file .env.secrets >>> printf 'OPENAI_API_KEY=sk-...\n' | hf sandbox create --secrets-file - ``` `-s KEY=value`도 작동하지만, 값이 셸 히스토리와 프로세스 목록에 기록되므로 CLI는 조용 모드(quiet mode)를 포함하여 stderr로 이에 대해 경고를 표시합니다. 풀링된 샌드박스는 `--secrets`을 완전히 거부합니다. 풀에는 암호화 시크릿 채널이 없으며, `hf sandbox create --pool -s KEY=value`를 실행하면 `--env`를 가리키는 오류가 발생합니다. ## hf webhooks `hf webhooks`는 터미널에서 Hugging Face Hub의 웹훅을 직접 관리할 수 있게 해 줍니다. 웹훅을 사용하면 저장소, 사용자 또는 조직의 이벤트(push, discussion 등)를 수신하고, 원격 URL을 호출하거나 Hugging Face 인프라에서 Job을 실행하는 방식으로 작업을 트리거할 수 있습니다. ### Webhook 목록 ```bash >>> hf webhooks ls ID URL DISABLED DOMAINS WATCHED wh-abc123 https://example.com/hook False repo model:bert-base-uncased wh-def456 https://example.com/other-hook False repo org:HuggingFace ``` 기계가 읽을 수 있는 출력을 얻으려면 `--format json`을, ID만 출력하려면 `-q`를 사용하세요: ```bash >>> hf webhooks ls --format json >>> hf webhooks ls -q ``` ### Webhook 정보 가져오기 ```bash >>> hf webhooks info wh-abc123 ``` JSON 형식으로 웹훅 세부 정보를 전체 출력합니다. ### Webhook 생성 URL로 페이로드를 전송하는 웹훅을 생성합니다: ```bash >>> hf webhooks create --url https://example.com/hook --watch model:bert-base-uncased >>> hf webhooks create --url https://example.com/hook --watch org:HuggingFace --watch model:gpt2 --domain repo ``` 또는 Job을 트리거하는 웹훅을 생성합니다: ```bash >>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch user:julien-c ``` 소스 Job의 secrets는 webhook으로 복사되지 않습니다. 트리거된 Job에 secrets를 전달하려면 `--secrets` 또는 `--secrets-file`(`hf jobs run`와 동일한 구문)을 사용하세요. 예를 들어, `--secrets HF_TOKEN`은 로컬 Hugging Face 토큰을 전달합니다: ```bash >>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch bucket:my-org/my-bucket --secrets HF_TOKEN ``` `--watch` 옵션은 `type:name` 형식을 사용하며, type은 `model`, `dataset`, `space`, `bucket`, `org`, `user` 중 하나입니다. 여러 항목을 감시하려면 이 옵션을 반복하여 사용할 수 있습니다. `--domain`을 사용하여 이벤트를 `repo` 또는 `discussion`으로 필터링하고, `--secret`을 사용하여 서명 시크릿을 설정합니다. ### Webhook 업데이트 ```bash >>> hf webhooks update wh-abc123 --url https://new-url.com/hook >>> hf webhooks update wh-abc123 --watch model:gpt2 --domain repo ``` 제공된 옵션만 변경됩니다. `--watch`가 지정되면 전체 감시 목록이 대체됩니다. Job 트리거 웹훅의 secrets를 업데이트하려면 `--job-id`와 `--secrets`를 함께 전달하세요. 나열된 secrets는 저장된 값을 대체하고, 다른 모든 secrets는 유지됩니다: ```bash >>> hf webhooks update wh-abc123 --job-id 687f911eaea852de79c4a50a --secrets HF_TOKEN ``` ### 웹훅 활성화/비활성화 ```bash >>> hf webhooks enable wh-abc123 >>> hf webhooks disable wh-abc123 ``` ### Webhook 삭제 ```bash >>> hf webhooks delete wh-abc123 Are you sure you want to delete webhook 'wh-abc123'? [y/N]: y Webhook deleted: wh-abc123 ``` 확인 프롬프트를 건너뛰려면 `--yes`를 사용하세요: ```bash >>> hf webhooks delete wh-abc123 --yes ``` > [!TIP] > 모든 명령은 `--token`을 받아 인증을 덮어쓸 수 있습니다. 모든 옵션을 보려면 어떤 명령이든 `--help`를 사용하세요. ## hf 엔드포인트 `hf endpoints`를 사용하여 터미널에서 Inference Endpoints를 나열, 배포, 설명 및 관리할 수 있습니다. 호환성을 위해 기존 `hf inference-endpoints` 별칭이 계속 사용할 수 있습니다. ```bash # Lists endpoints in your namespace >>> hf endpoints ls # List the hardware you can deploy on >>> hf endpoints hardware # Deploy an endpoint from Model Catalog >>> hf endpoints catalog deploy --repo openai/gpt-oss-120b --name my-endpoint # Deploy an endpoint from the Hugging Face Hub >>> hf endpoints deploy my-endpoint --repo gpt2 --framework pytorch --accelerator cpu --instance-size x2 --instance-type intel-icl # List catalog entries >>> hf endpoints catalog ls # Show status and metadata >>> hf endpoints describe my-endpoint # Pause the endpoint >>> hf endpoints pause my-endpoint # Delete without confirmation prompt >>> hf endpoints delete my-endpoint --yes ``` > [!TIP] > 조직을 대상으로 하려면 `--namespace`를, 인증을 재정의하려면 `--token`을 추가하세요. #### 배포할 하드웨어 찾기 `hf endpoints deploy`에는 다섯 개의 하드웨어 플래그(`--vendor`, `--region`, `--accelerator`, `--instance-type`, `--instance-size`)가 필요합니다. `hf endpoints hardware`는 유효한 조합을 나열하며, 리플리카당 시간당 USD 가격과 네임스페이스의 가속기 할당량을 보여줍니다: ```bash >>> hf endpoints hardware --vendor aws --region eu-west-1 VENDOR REGION ACCELERATOR INSTANCE_TYPE INSTANCE_SIZE MEMORY_GB GPU_MEMORY_GB PRICE_PER_HOUR QUOTA STATUS ------ --------- ----------- ------------- ------------- --------- ------------- -------------- ----- --------- aws eu-west-1 cpu intel-spr x1 2.0 0.033 0/60 available aws eu-west-1 cpu intel-spr x2 4.0 0.067 0/60 available aws eu-west-1 cpu intel-spr x4 8.0 0.134 0/60 available aws eu-west-1 cpu intel-spr x8 16.0 0.268 0/60 available aws eu-west-1 cpu intel-spr x16 32.0 0.536 0/60 available aws eu-west-1 gpu nvidia-a10g x1 30.0 24 1.0 0/16 available aws eu-west-1 gpu nvidia-t4 x1 15.0 16 0.5 1/30 available Hint: Deploy on one of these, e.g.: hf endpoints deploy my-endpoint --repo --framework --vendor aws --region eu-west-1 --accelerator cpu --instance-type intel-spr --instance-size x1 ``` 필터 플래그는 배포 플래그(`--vendor`, `--region`, `--accelerator`, `--instance-type`)와 동일하므로, 필터링하는 항목이 곧 `deploy`에 전달되는 값입니다. 현재 배포할 수 있는 하드웨어만 나열됩니다: 사용 가능한 상태이며, 네임스페이스에 1개의 리플리카를 위한 충분한 가속기 할당량이 남아 있어야 합니다. `--all`를 추가하면 비활성화(deprecated)된 항목, 일시적으로 사용할 수 없는 항목, 할당량을 초과한 항목도 함께 표시됩니다. `--format json`을 사용하면 각 항목에 리플리카별 나머지 사양(vCPU, 아키텍처, 가속기 수)이 추가됩니다. > [!TIP] > Quota는 namespace별로 적용되며, 어떤 행이 목록에 표시되는지를 결정합니다. 조직에 배포하는 경우, `deploy`에 전달할 `--namespace`와 동일한 값을 전달해야 합니다. 그렇지 않으면 개인 Quota를 확인하게 되며, 이는 조직이 배포할 수 있는 하드웨어를 숨기거나 배포할 수 없는 하드웨어를 표시할 수 있습니다. #### 커스텀 컨테이너 배포 Hugging Face가 관리하는 이미지 대신 자체 Docker 이미지를 배포하려면 `--framework custom`와 함께 `--custom-image`를 전달하세요. 모델 저장소는 컨테이너 내부의 `/repository`에 마운트됩니다. `--container-args`(그리고 선택적으로 `--container-command`)를 사용하여 따옴표로 묶은 시작 문자열을 전달하고, `--env`/`--secrets`를 사용하여 환경 변수를 주입하며, `--type`을 사용하여 액세스 유형(`public`, `authenticated` 또는 `private`)을 설정합니다: ```bash >>> hf endpoints deploy nex-n2-pro \ --repo nex-agi/Nex-N2-Pro \ --framework custom \ --accelerator gpu --vendor aws --region us-east-1 \ --instance-type nvidia-h200 --instance-size x8 \ --custom-image nexagi/sglang:v0.5.12 \ --health-route /health --port 30000 \ --container-args "--reasoning-parser qwen3 --tool-call-parser qwen3_coder --mamba-scheduler-strategy extra_buffer --tp 8" \ --env MODEL_ID=/repository \ --type authenticated ``` `--container-args`와 `--container-command`는 커스텀 이미지로만 제한되지 않습니다. 이 플래그들은 API 페이로드의 `model.args`와 `model.command`에 매핑되며, 관리형 이미지에도 적용됩니다. 기존 엔드포인트에서 이 두 플래그는 현재 값을 추가하는 것이 아니라 대체하므로, 원하는 전체 목록을 전달하고 비어 있는 문자열을 사용하여 값을 지우세요. 카탈로그에서 배포된 엔드포인트는 이미 조정된 엔진 플래그가 포함되어 있으므로, 덮어쓰기 전에 `hf endpoints describe`를 확인하세요: ```bash >>> hf endpoints update my-endpoint \ --container-args "--enable-auto-tool-choice --tool-call-parser lfm2" ``` #### 관리형 엔진 이미지 배포 `--custom-image`만 사용하면 임의의 컨테이너를 배포합니다. `--engine`를 추가하면 API가 관리하는 엔진(`vllm`, `sglang`, `tgi`, `tei`, `llamacpp`, `hf-serve`, ...) 중 하나로 실행되며, `--tensor-parallel-size`와 `--data-parallel-size`를 포함한 해당 엔진의 설정이 활성화됩니다. vLLM과 SGLang은 기본적으로 가속기 1개를 사용하는 반면 엔드포인트는 인스턴스의 모든 가속기를 사용하므로, 두 값을 모두 설정하지 않으면 모델이 가속기 1개에만 로드되고 나머지는 유휴 상태가 되면서도 정상으로 보고됩니다. 이러한 이유로 API는 이제 해당 구성을 거부합니다: ```bash >>> hf endpoints deploy gpt-oss-120b-vllm \ --repo openai/gpt-oss-120b \ --framework custom \ --accelerator gpu --vendor aws --region us-east-1 \ --instance-type nvidia-h200 --instance-size x8 \ --engine vllm --custom-image vllm/vllm-openai:v0.23.0 \ --tensor-parallel-size 8 ``` 위의 `--container-args "... --tp 8"`와 동일하지 않습니다: `--tensor-parallel-size`는 엔진의 `model.image` 설정에 값을 기록하며, 이는 API가 인스턴스의 가속기 수와 대조하여 검증하는 항목입니다. 반면 `--container-args`는 명령줄에 플래그를 추가할 뿐입니다. 이미지 필드가 없는 엔진 플래그와 병렬성 필드가 없는 일반 커스텀 컨테이너에는 `--container-args`를 사용하세요. 실행 중인 엔드포인트를 다시 조정하려면 크기를 단독으로 전달합니다. `model.image`는 전체로 전송되며 `url`이 필요하므로, 엔드포인트의 현재 이미지가 가져와져 제자리에서 업데이트됩니다: ```bash >>> hf endpoints update gpt-oss-120b-vllm --tensor-parallel-size 4 --data-parallel-size 2 ``` `hf endpoints update` 명령어도 `--custom-image`와 `--engine`를 지원하며, CLI에서 엔드포인트의 이미지를 변경할 수 있는 유일한 방법입니다. 이 경로는 `model.image`를 패치하는 대신 교체하므로, 먼저 `hf endpoints describe`를 실행한 후 유지하려는 값을 전달해야 합니다. ### hf 엔드포인트 카탈로그 `hf endpoints catalog`을 사용하여 Inference Endpoints Model Catalog와 상호작용합니다. 최적화된 구성으로 카탈로그에서 모델을 직접 배포합니다. 각 카탈로그 모델에는 하나 이상의 *레시피*가 제공됩니다. 레시피는 해당 모델에 대해 테스트가 완료된 하드웨어와 엔진의 조합을 의미합니다. `hf endpoints catalog ls`는 레시피별로 한 줄씩 출력하므로, GPU와 Neuron 레시피를 모두 갖춘 모델은 두 번 표시됩니다: ```bash # List available catalog models >>> hf endpoints catalog ls REPO_ID TASK LICENSE ACCELERATOR ENGINE GGUF_FILE RECIPE_ID ----------------------------------- ------------------ ---------- ----------- -------- ----------------------------- ------------------------- meta-llama/Llama-3.1-8B-Instruct text-generation Llama 3.1 gpu vllm sizzling-biryani-g4xsi1ac meta-llama/Llama-3.1-8B-Instruct text-generation Llama 3.1 neuron vllmNeuron artisanal-quinoa-yz9ynamx bartowski/QwQ-32B-Preview-GGUF text-generation Apache 2.0 gpu llamacpp QwQ-32B-Preview-Q8_0.gguf baked-orange-m863gx7d # Narrow it down >>> hf endpoints catalog ls --engine vllm --task text-generation --search llama --limit 10 ``` `--accelerator`, `--engine`, `--license`, `--task`, `--search`, `--limit`는 모두 서버 측에서 필터링됩니다. ```bash # Deploy the default recipe of a model >>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct # Deploy an exact recipe listed above >>> hf endpoints catalog deploy --recipe artisanal-quinoa-yz9ynamx # Deploy with a custom name >>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct --name my-llama-endpoint ``` `--repo`를 사용하면 `--accelerator`(`cpu`, `gpu`, `neuron`) 및 `--gguf-file`(양자화별로 레시피가 하나씩 있는 모델의 경우)로 기본 레시피를 좁혀서 지정할 수 있습니다. 둘 다 단일 레시피를 이미 지정하는 `--recipe`와 함께 사용되면 거부됩니다.