pax_global_header00006660000000000000000000000064151076341430014516gustar00rootroot0000000000000052 comment=fdc11699305d5947725a6ad48907746ec95eefa1 huggingface_hub-1.1.5/000077500000000000000000000000001510763414300146275ustar00rootroot00000000000000huggingface_hub-1.1.5/.github/000077500000000000000000000000001510763414300161675ustar00rootroot00000000000000huggingface_hub-1.1.5/.github/ISSUE_TEMPLATE/000077500000000000000000000000001510763414300203525ustar00rootroot00000000000000huggingface_hub-1.1.5/.github/ISSUE_TEMPLATE/bug-report.yml000066400000000000000000000031701510763414300231640ustar00rootroot00000000000000name: "\U0001F41B Bug Report" description: Report a bug on huggingface_hub labels: ["bug"] body: - type: markdown attributes: value: | Thanks for taking the time to fill out this bug report! - type: textarea id: bug-description attributes: label: Describe the bug description: A clear and concise description of what the bug is. If you intend to submit a pull request for this issue, tell us in the description. Thanks! placeholder: Bug description validations: required: true - type: textarea id: reproduction attributes: label: Reproduction description: Please provide a minimal reproducible code which we can copy/paste and reproduce the issue. placeholder: Reproduction - type: textarea id: logs attributes: label: Logs description: "Please include the Python logs if you can. If possible, run the code with `HF_DEBUG=1` as environment variable." render: shell - type: textarea id: system-info attributes: label: System info description: | Please dump your environment info by running the following command and copy-paste the result here: ```txt hf env ``` If you are working in a notebook, please run it in a code cell: ```py from huggingface_hub import dump_environment_info dump_environment_info() ``` render: shell placeholder: | - huggingface_hub version: 0.11.0.dev0 - Platform: Linux-5.15.0-52-generic-x86_64-with-glibc2.35 - Python version: 3.10.6 ... validations: required: true huggingface_hub-1.1.5/.github/ISSUE_TEMPLATE/config.yml000066400000000000000000000012061510763414300223410ustar00rootroot00000000000000blank_issues_enabled: true contact_links: - name: api-inference-community url: https://github.com/huggingface/api-inference-community/issues about: For all issues related to the inference API - name: Website Related url: https://github.com/huggingface/hub-docs/issues about: Feature requests and bug reports related to the website - name: Forum url: https://discuss.huggingface.co/ about: General usage questions and community discussions - name: Blank issue url: https://github.com/huggingface/huggingface_hub/issues/new about: Please note that the Forum is in most places the right place for discussions huggingface_hub-1.1.5/.github/ISSUE_TEMPLATE/feature_request.md000066400000000000000000000011401510763414300240730ustar00rootroot00000000000000--- name: "\U0001F680 Feature request" about: Suggest an idea for this project title: '' labels: '' assignees: '' --- **Is your feature request related to a problem? Please describe.** A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] **Describe the solution you'd like** A clear and concise description of what you want to happen. **Describe alternatives you've considered** A clear and concise description of any alternative solutions or features you've considered. **Additional context** Add any other context or screenshots about the feature request here. huggingface_hub-1.1.5/.github/ISSUE_TEMPLATE/i18n.md000066400000000000000000000072421510763414300214600ustar00rootroot00000000000000--- name: 🌐 Translating a new language? about: Start a new translation effort in your language title: '[i18n-] Translating docs to ' labels: WIP assignees: '' --- Hi! Let's bring the documentation to all the -speaking community 🌐 Who would want to translate? Please follow the 🤗 [TRANSLATING guide](https://github.com/huggingface/huggingface_hub/blob/main/docs/TRANSLATING.md). Here is a list of the files ready for translation. Let us know in this issue if you'd like to translate any, and we'll add your name to the list. Some notes: * Please translate using an informal tone (imagine you are talking with a friend about huggingface_hub 🤗). * Please translate in a gender-neutral way. * Add your translations to the folder called `` inside the [source folder](https://github.com/huggingface/huggingface_hub/tree/main/docs/source). * Register your translation in `/_toctree.yml`; please follow the order of the [English version](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/_toctree.yml). * Once you're finished, open a pull request and tag this issue by including #issue-number in the description, where issue-number is the number of this issue. Please ping @Wauplin @stevhliu for review. * 🙋 If you'd like others to help you with the translation, you can also post in the 🤗 [forums](https://discuss.huggingface.co/). ## README - [ ] [README.md](https://github.com/huggingface/huggingface_hub/blob/main/README.md) ## Get Started section - [ ] [index.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/index.md) - [ ] [quick-start.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/quick-start.md) - [ ] [installation.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/installation.md). ## How-to guides section - [ ] [community.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/community.md) - [ ] [download.md](https://github.com/huggingface/huggingface_hub/blob/master/docs/source/guides/download.md) - [ ] [hf_file_system.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/hf_file_system.md) - [ ] [inference.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/inference.md) - [ ] [integrations.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/integrations.md) - [ ] [manage-cache.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/manage-cache.md) - [ ] [manage-spaces.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/manage-spaces.md) - [ ] [model-cards.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/model-cards.md) - [ ] [overview.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/overview.md) - [ ] [repository.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/repository.md) - [ ] [search.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/search.md) - [ ] [upload.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/upload.md) - [ ] [webhooks_server.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/guides/webhooks_server.md) ## Conceptual guides section - [ ] [git_vs_http.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/concepts/git_vs_http.md) huggingface_hub-1.1.5/.github/conda/000077500000000000000000000000001510763414300172535ustar00rootroot00000000000000huggingface_hub-1.1.5/.github/conda/build.sh000066400000000000000000000001051510763414300207020ustar00rootroot00000000000000$PYTHON setup.py install # Python command to install the script. huggingface_hub-1.1.5/.github/conda/meta.yaml000066400000000000000000000012521510763414300210650ustar00rootroot00000000000000{% set name = "huggingface_hub" %} package: name: "{{ name|lower }}" version: "{{ HUB_VERSION }}" source: path: ../../ build: noarch: python requirements: host: - python - pip - fsspec - filelock - httpx - tqdm - typing-extensions - packaging - pyyaml - hf-xet run: - python - pip - filelock - httpx - tqdm - typing-extensions - packaging - pyyaml - hf-xet test: imports: - huggingface_hub about: home: https://huggingface.co license: Apache License 2.0 license_file: LICENSE summary: "Client library to download and publish models and other files on the huggingface.co hub" huggingface_hub-1.1.5/.github/workflows/000077500000000000000000000000001510763414300202245ustar00rootroot00000000000000huggingface_hub-1.1.5/.github/workflows/build_documentation.yaml000066400000000000000000000006021510763414300251360ustar00rootroot00000000000000name: Build documentation on: push: branches: - main - doc-builder* - v*-release jobs: build: uses: huggingface/doc-builder/.github/workflows/build_main_documentation.yml@main with: commit_sha: ${{ github.sha }} package: huggingface_hub languages: cn de fr en hi ko tm secrets: hf_token: ${{ secrets.HF_DOC_BUILD_PUSH }} huggingface_hub-1.1.5/.github/workflows/build_pr_documentation.yaml000066400000000000000000000006751510763414300256510ustar00rootroot00000000000000name: Build PR Documentation on: pull_request concurrency: group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} cancel-in-progress: true jobs: build: uses: huggingface/doc-builder/.github/workflows/build_pr_documentation.yml@main with: commit_sha: ${{ github.event.pull_request.head.sha }} pr_number: ${{ github.event.number }} package: huggingface_hub languages: cn de fr en hi ko tm huggingface_hub-1.1.5/.github/workflows/build_repocard_examples.yaml000066400000000000000000000012051510763414300257620ustar00rootroot00000000000000name: Build and push Model Card and Dataset Card examples on: push: branches: - main env: HF_TOKEN: ${{ secrets.HUGGINGFACE_PRODUCTION_USER_TOKEN }} jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Set up Python uses: actions/setup-python@v2 with: python-version: 3.13 # Install dependencies - name: Configure and install dependencies run: | pip install --upgrade pip pip install . pip install Jinja2 # Push cards - name: Push cards run: python utils/push_repocard_examples.py huggingface_hub-1.1.5/.github/workflows/check-installers.yml000066400000000000000000000044701510763414300242070ustar00rootroot00000000000000name: Check CLI installers on: push: branches: - main paths: - "utils/installers/**" - ".github/workflows/check-installers.yml" pull_request: paths: - "utils/installers/**" - ".github/workflows/check-installers.yml" workflow_dispatch: {} permissions: contents: read jobs: linux-installer: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Run installer shell: bash run: | set -euo pipefail HF_TEST_ROOT=$(mktemp -d) INSTALL_DIR="$HF_TEST_ROOT/install" BIN_DIR="$HF_TEST_ROOT/bin" HF_HOME="$INSTALL_DIR" HF_CLI_BIN_DIR="$BIN_DIR" utils/installers/install.sh --no-modify-path export PATH="$BIN_DIR:$PATH" if ! hf version | tee /dev/stderr | grep -Eq '[0-9]+(\.[0-9]+){1,2}(\.[a-zA-Z]+[0-9]+)?'; then echo "incorrect hf version output" >&2 exit 1 fi NO_COLOR=1 hf --help rm -rf "$HF_TEST_ROOT" windows-installer: runs-on: windows-latest steps: - name: Checkout repository uses: actions/checkout@v4 - name: Run installer shell: pwsh run: | $hfTestRoot = Join-Path $env:TEMP ([System.Guid]::NewGuid().ToString()) $installDir = Join-Path $hfTestRoot 'install' $binDir = Join-Path $hfTestRoot 'bin' New-Item -ItemType Directory -Path $installDir -Force | Out-Null New-Item -ItemType Directory -Path $binDir -Force | Out-Null $env:HF_HOME = $installDir $env:HF_CLI_BIN_DIR = $binDir & "$PWD/utils/installers/install.ps1" -NoModifyPath $env:PATH = "$binDir;$env:PATH" $hfVersionOutput = & hf.exe version 2>&1 $hfVersionOutput | Out-Host # Show the output if ($LASTEXITCODE -ne 0) { throw 'hf version failed' } if (-not ($hfVersionOutput -match '[0-9]+(\.[0-9]+){1,2}(\.[a-zA-Z]+[0-9]+)?')) { throw 'incorrect hf version output' } $env:NO_COLOR = '1' & hf.exe --help if ($LASTEXITCODE -ne 0) { throw 'hf --help failed' } Remove-Item Env:NO_COLOR Remove-Item -Path $hfTestRoot -Recurse -Force huggingface_hub-1.1.5/.github/workflows/claude.yml000066400000000000000000000021001510763414300221750ustar00rootroot00000000000000name: Claude PR Assistant on: issue_comment: types: [created] pull_request_review_comment: types: [created] issues: types: [opened, assigned] pull_request_review: types: [submitted] jobs: claude-code-action: if: | (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) || (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) || (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) || (github.event_name == 'issues' && contains(github.event.issue.body, '@claude')) runs-on: ubuntu-latest permissions: contents: read pull-requests: read issues: read id-token: write steps: - name: Checkout repository uses: actions/checkout@v4 with: fetch-depth: 1 - name: Run Claude PR Action uses: anthropics/claude-code-action@beta with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} timeout_minutes: "60" huggingface_hub-1.1.5/.github/workflows/model_card_consistency_reminder.yml000066400000000000000000000035051510763414300273510ustar00rootroot00000000000000name: Model and Dataset Card consistency reminder on: pull_request: paths: - src/huggingface_hub/repocard.py - src/huggingface_hub/templates/modelcard_template.md - src/huggingface_hub/templates/datasetcard_template.md jobs: comment: runs-on: ubuntu-latest steps: - name: maintain-comment uses: actions-cool/maintain-one-comment@v3 with: body: | It looks like you've updated code related to model or dataset cards in this PR. Some content is duplicated among the following files. Please make sure that everything stays consistent. - [src/.../repocard.py](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/repocard.py) - [src/.../datasetcard_template.md](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/datasetcard_template.md) - [src/.../modelcard_template.md](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md) - [modelcard.md](https://github.com/huggingface/hub-docs/blob/main/modelcard.md) (`hub-docs` repo) - [docs/hub/model-cards.md](https://github.com/huggingface/hub-docs/blob/main/docs/hub/model-cards.md) (`hub-docs` repo) - [docs/hub/model-card-annotated.md](https://github.com/huggingface/hub-docs/blob/main/docs/hub/model-card-annotated.md) (`hub-docs` repo) - [datasetcard.md](https://github.com/huggingface/hub-docs/blob/main/datasetcard.md) (`hub-docs` repo) - [docs/hub/datasets-cards.md](https://github.com/huggingface/hub-docs/blob/main/docs/hub/datasets-cards.md) (`hub-docs` repo) token: ${{ secrets.comment_bot_token }} body-include: '' huggingface_hub-1.1.5/.github/workflows/python-prerelease.yml000066400000000000000000000067301510763414300244230ustar00rootroot00000000000000name: Python prerelease on: push: tags: - v*rc* workflow_dispatch: inputs: tag: description: "Tag to test (e.g., 0.30.0rc2)" required: true jobs: trigger_rc_testing: runs-on: ubuntu-latest strategy: fail-fast: false matrix: target-repo: ["transformers", "datasets", "diffusers"] steps: - name: Determine version from tag id: get-version env: TAG : ${{ inputs.tag }} run: | if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then echo "VERSION=$TAG" >> $GITHUB_OUTPUT else echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT fi - name: Checkout target repo uses: actions/checkout@v4 with: repository: huggingface/${{ matrix.target-repo }} path: ${{ matrix.target-repo }} token: ${{ secrets.HUGGINGFACE_HUB_AUTOMATIC_RC_TESTING }} - name: Configure Git run: | cd ${{ matrix.target-repo }} git config user.name "Hugging Face Bot (RC Testing)" git config user.email "bot@huggingface.co" - name: Wait for prerelease to be out on PyPI run: | VERSION=${{ steps.get-version.outputs.VERSION }} echo "Waiting for huggingface-hub==${VERSION} to be available on PyPI" while ! pip install huggingface-hub==${VERSION}; do echo "huggingface-hub==${VERSION} not available yet, retrying in 15s" sleep 15 done - name: Create test branch and update dependencies id: create-pr run: | cd ${{ matrix.target-repo }} VERSION=${{ steps.get-version.outputs.VERSION }} BRANCH_NAME="ci-test-huggingface-hub-${VERSION}-release" # Create and checkout new branch git checkout -b $BRANCH_NAME # Update dependencies using sed - match both >= and == patterns sed -i -E "s/\"huggingface-hub(>=|==)[^\"]*\"/\"huggingface-hub==${VERSION}\"/" setup.py git add setup.py # Only if the target repo is transformers if [ "${{ matrix.target-repo }}" = "transformers" ]; then sed -i -E "s/\"huggingface-hub(>=|==)[^\"]*\"/\"huggingface-hub==${VERSION}\"/" src/transformers/dependency_versions_table.py git add src/transformers/dependency_versions_table.py fi # Only if the target repo is diffusers if [ "${{ matrix.target-repo }}" = "diffusers" ]; then sed -i -E "s/\"huggingface-hub\":.*/\"huggingface-hub\": \"huggingface-hub==${VERSION}\",/" src/diffusers/dependency_versions_table.py git add src/diffusers/dependency_versions_table.py fi # Any line with `uv pip install --prerelease=allow` in the `.github/` folder must be updated with `--prerelease=allow` flag find .github/workflows/ -type f -exec sed -i 's/uv pip install /uv pip install --prerelease=allow /g' {} + git add .github/workflows/ # Commit and push changes git --no-pager diff --staged git commit -m "Test hfh ${VERSION}" git push --set-upstream origin $BRANCH_NAME - name: Print URLs for manual check run: | VERSION=${{ steps.get-version.outputs.VERSION }} echo "https://github.com/huggingface/${{ matrix.target-repo }}/actions" echo "https://github.com/huggingface/${{ matrix.target-repo }}/compare/main...${BRANCH_NAME}" huggingface_hub-1.1.5/.github/workflows/python-quality.yml000066400000000000000000000033201510763414300237540ustar00rootroot00000000000000name: Python quality on: push: branches: - main paths-ignore: - "js/**" - "api-inference-community/**" pull_request: types: [assigned, opened, synchronize, reopened] paths-ignore: - "js/**" - "api-inference-community/**" jobs: check_code_quality: runs-on: ubuntu-latest env: UV_HTTP_TIMEOUT: 600 # max 10min to install deps steps: - uses: actions/checkout@v2 - name: Set up Python uses: actions/setup-python@v2 with: python-version: 3.9 # Setup venv # TODO: revisit when https://github.com/astral-sh/uv/issues/1526 is addressed. - name: Setup venv + uv run: | pip install --upgrade uv uv venv - name: Install dependencies run: uv pip install "huggingface_hub[dev] @ ." - run: .venv/bin/ruff check tests src # linter - run: .venv/bin/ruff format --check tests src # formatter - run: .venv/bin/python utils/check_inference_input_params.py - run: .venv/bin/python utils/check_static_imports.py - run: .venv/bin/python utils/check_all_variable.py - run: .venv/bin/python utils/generate_async_inference_client.py - run: .venv/bin/python utils/generate_cli_reference.py --verbose - run: .venv/bin/python utils/generate_inference_types.py - run: .venv/bin/python utils/check_task_parameters.py - run: uvx ty check src # Run type checking at least on huggingface_hub root file to check all modules # that can be lazy-loaded actually exist. - run: .venv/bin/mypy src/huggingface_hub/__init__.py --follow-imports=silent --show-traceback # Run mypy on full package - run: .venv/bin/mypy src huggingface_hub-1.1.5/.github/workflows/python-release-hf.yml000066400000000000000000000014321510763414300243010ustar00rootroot00000000000000name: hf PyPI release on: push: tags: - v* workflow_dispatch: inputs: tag: description: "Tag to release (e.g., v0.30.0)" required: true env: PYPI_TOKEN: ${{ secrets.PYPI_TOKEN_DIST_HF }} jobs: python_release: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - name: Set up Python uses: actions/setup-python@v6 with: python-version: '3.10' - name: Install dependencies run: | pip install --upgrade pip pip install setuptools wheel - run: cd utils/hf && python setup.py sdist bdist_wheel - run: | pip install twine - name: Upload to PyPI run: | cd utils/hf && twine upload dist/* -u __token__ -p "$PYPI_TOKEN" huggingface_hub-1.1.5/.github/workflows/python-release.yml000066400000000000000000000012141510763414300237040ustar00rootroot00000000000000name: Python release on: push: tags: - v* env: PYPI_TOKEN: ${{ secrets.PYPI_TOKEN_DIST_HUGGINGFACE_HUB }} jobs: python_release: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Set up Python uses: actions/setup-python@v2 with: python-version: 3.9 - name: Install dependencies run: | pip install --upgrade pip pip install setuptools wheel - run: python setup.py sdist bdist_wheel - run: | pip install twine - name: Upload to PyPi run: | twine upload dist/* -u __token__ -p "$PYPI_TOKEN" huggingface_hub-1.1.5/.github/workflows/python-tests.yml000066400000000000000000000150621510763414300234340ustar00rootroot00000000000000name: Python tests on: push: branches: - main - ci_* paths-ignore: - "docs/**" pull_request: types: [assigned, opened, synchronize, reopened] paths-ignore: - "docs/**" jobs: build-ubuntu: runs-on: ubuntu-latest env: UV_HTTP_TIMEOUT: 600 # max 10min to install deps strategy: fail-fast: false matrix: python-version: ["3.9", "3.14"] test_name: ["Everything else", "Inference only", "Xet only"] include: - python-version: "3.14" # LFS not ran on 3.9 test_name: "lfs" - python-version: "3.9" test_name: "fastai" - python-version: "3.10" # fastai not supported on 3.12 and 3.11 -> test it on 3.10 test_name: "fastai" - python-version: "3.9" # test torch~=1.11 on python 3.9 only. test_name: "Python 3.9, torch_1.11" - python-version: "3.12" # test torch latest on python 3.12 only. test_name: "torch_latest" - python-version: "3.13" # gradio not supported on 3.14 -> test it on 3.13 test_name: "gradio" steps: - uses: actions/checkout@v2 - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v2 with: python-version: ${{ matrix.python-version }} # Setup venv # TODO: revisit when https://github.com/astral-sh/uv/issues/1526 is addressed. - name: Setup venv + uv run: | pip install --upgrade uv uv venv # Install dependencies - name: Install dependencies run: | uv pip install "huggingface_hub[testing] @ ." case "${{ matrix.test_name }}" in "Everything else" | "Inference only") sudo apt update sudo apt install -y libsndfile1-dev ;; lfs) git config --global user.email "ci@dummy.com" git config --global user.name "ci" ;; fastai) uv pip install "huggingface_hub[fastai] @ ." ;; gradio) uv pip install "huggingface_hub[gradio] @ ." ;; torch_latest) uv pip install "huggingface_hub[torch] @ ." uv pip install --upgrade torch ;; "Python 3.9, torch_1.11") uv pip install "huggingface_hub[torch] @ ." uv pip install torch~=1.11 ;; esac # If not "Xet only", we want to test upload/download with regular LFS workflow # => uninstall hf_xet to make sure we are not using it. if [[ "${{ matrix.test_name }}" != "Xet only" ]]; then uv pip uninstall hf_xet fi # Run tests - name: Run tests working-directory: ./src # For code coverage to work run: | source ../.venv/bin/activate PYTEST="python -m pytest --cov=./huggingface_hub --cov-report=xml:../coverage.xml --vcr-record=none --reruns 8 --reruns-delay 2 --only-rerun '(OSError|Timeout|HTTPError.*502|HTTPError.*504||not less than or equal to 0.01)'" case "${{ matrix.test_name }}" in "Inference only") # Run inference tests concurrently PYTEST="$PYTEST ../tests -k 'test_inference' -n 4" echo $PYTEST eval $PYTEST ;; "Everything else") PYTEST="$PYTEST ../tests -k 'not TestRepository and not test_inference and not test_xet' -n 4" echo $PYTEST eval $PYTEST ;; lfs) eval "RUN_GIT_LFS_TESTS=1 $PYTEST ../tests -k 'HfLargefilesTest'" ;; fastai) eval "$PYTEST ../tests/test_fastai*" ;; gradio) eval "$PYTEST ../tests/test_webhooks_server.py" ;; "Python 3.9, torch_1.11" | torch_latest) eval "$PYTEST ../tests/test_hub_mixin*" eval "$PYTEST ../tests/test_serialization.py" ;; "Xet only") PYTEST="$PYTEST ../tests -k 'test_xet' -n 4" echo $PYTEST eval $PYTEST ;; esac # Upload code coverage - name: Upload coverage reports to Codecov with GitHub Action uses: codecov/codecov-action@v3 with: files: ./coverage.xml verbose: true build-windows: # (almost) Duplicate config compared to `build-ubuntu` but running on Windows. # Please make sure to keep it updated as well. runs-on: windows-latest env: DISABLE_SYMLINKS_IN_WINDOWS_TESTS: 1 UV_HTTP_TIMEOUT: 600 # max 10min to install deps GIT_CLONE_PROTECTION_ACTIVE: false # See https://github.com/git-lfs/git-lfs/issues/5754 strategy: fail-fast: false matrix: python-version: ["3.9", "3.14"] test_name: ["Everything else", "Xet only"] steps: - uses: actions/checkout@v2 - name: Set up Python ${{ matrix.python-version }} uses: actions/setup-python@v2 with: python-version: ${{ matrix.python-version }} # Setup venv # TODO: revisit when https://github.com/astral-sh/uv/issues/1526 is addressed. - name: Setup venv + uv run: | pip install --upgrade uv uv venv # Install dependencies - name: Install dependencies run: | uv pip install "huggingface_hub[testing] @ ." if ("${{ matrix.test_name }}" -eq "Xet only") { uv pip install hf_xet } # Run tests - name: Run tests working-directory: ./src # For code coverage to work run: | ..\.venv\Scripts\activate $PYTEST_ARGS = @( "-m", "pytest", "-n", "4", "--cov=./huggingface_hub", "--cov-report=xml:../coverage.xml", "--vcr-record=none", "--reruns", "8", "--reruns-delay", "2", "--only-rerun", "(OSError|Timeout|HTTPError.*502|HTTPError.*504|not less than or equal to 0.01)", "../tests" ) switch ("${{ matrix.test_name }}") { "Xet only" { python $PYTEST_ARGS -k "test_xet" } "Everything else" { python $PYTEST_ARGS -k "not test_xet" } } # Upload code coverage - name: Upload coverage reports to Codecov with GitHub Action uses: codecov/codecov-action@v3 with: files: ./coverage.xml verbose: true huggingface_hub-1.1.5/.github/workflows/release-conda.yml000066400000000000000000000017711510763414300234570ustar00rootroot00000000000000name: Release Conda on: push: tags: - v* branches: - conda_* env: ANACONDA_API_TOKEN: ${{ secrets.ANACONDA_API_TOKEN }} jobs: build_and_package: runs-on: ubuntu-latest defaults: run: shell: bash -l {0} steps: - name: Checkout repository uses: actions/checkout@v1 - name: Install miniconda uses: conda-incubator/setup-miniconda@v2 with: auto-update-conda: true auto-activate-base: false python-version: 3.9 activate-environment: "build-hub" - name: Setup conda env run: | conda install -c defaults anaconda-client conda-build - name: Extract version run: echo "HUB_VERSION=`python setup.py --version`" >> $GITHUB_ENV - name: Build conda packages run: | conda info conda-build .github/conda - name: Upload to Anaconda run: | anaconda upload `conda-build .github/conda --output` --force huggingface_hub-1.1.5/.github/workflows/style-bot-action.yml000066400000000000000000000233441510763414300241520ustar00rootroot00000000000000# This workflow was originally implemented by the diffusers team and ported into huggingface_hub # as a reusable workflow. Related PRs: # - https://github.com/huggingface/diffusers/pull/10274 # - https://github.com/huggingface/diffusers/pull/10931 # - https://github.com/huggingface/diffusers/pull/10908 name: Style Bot Action on: workflow_call: inputs: style_command_type: required: false type: string description: "Which style command to run (options: 'default' (make style && make quality), 'quality_only', 'style_only')" default: "default" python_quality_dependencies: required: true type: string description: "Python package extras to install for quality checks (e.g. '[quality]')" python_version: required: false type: string description: "Python version to run code formatter" default: "3.10" secrets: bot_token: required: true description: "GitHub token with permissions to comment and push to PR" jobs: check-permissions: if: > (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@bot /style') && github.event.issue.pull_request != null) runs-on: ubuntu-latest outputs: is_authorized: ${{ steps.check_user_permission.outputs.has_permission }} steps: - name: Check user permission id: check_user_permission uses: actions/github-script@v6 with: script: | comment_user = context.payload.comment.user.login; const { data: permission } = await github.rest.repos.getCollaboratorPermissionLevel({ owner: context.repo.owner, repo: context.repo.repo, username: comment_user }); const authorized = ['admin', 'maintain', 'push', 'write'].includes(permission.permission); console.log(`User ${comment_user} has permission level: ${permission.permission}, authorized: ${authorized} (only users with at least write access are allowed to run this action)`); core.setOutput('has_permission', authorized); run-style-bot: needs: check-permissions if: needs.check-permissions.outputs.is_authorized == 'true' runs-on: ubuntu-latest steps: - name: Extract PR details id: pr_info uses: actions/github-script@v6 with: script: | const prNumber = context.payload.issue.number; console.log(`PR number from env: "${prNumber}"`); const { data: pr } = await github.rest.pulls.get({ owner: context.repo.owner, repo: context.repo.repo, pull_number: prNumber }); // Set outputs for use in subsequent steps core.setOutput('headRepoFullName', pr.head.repo.full_name); core.setOutput('headRef', pr.head.ref); core.setOutput('baseRef', pr.base.ref); core.setOutput('prNumber', prNumber); console.log('PR Details:', { number: prNumber, headRepo: pr.head.repo.full_name, headRef: pr.head.ref, baseRef: pr.base.ref }); - name: Check out PR branch uses: actions/checkout@v3 env: HEADREPOFULLNAME: ${{ steps.pr_info.outputs.headRepoFullName }} HEADREF: ${{ steps.pr_info.outputs.headRef }} with: # Instead of checking out the base repo, use the contributor's repo name repository: ${{ env.HEADREPOFULLNAME }} ref: ${{ env.HEADREF }} # You may need fetch-depth: 0 for being able to push fetch-depth: 0 token: ${{ secrets.bot_token }} - name: Check commit timestamps env: COMMENT_DATE: ${{ github.event.comment.created_at }} PR_NUMBER: ${{ steps.pr_info.outputs.prNumber }} BASE_REPO_URL: https://github.com/${{ github.repository }} HEADREF: ${{ steps.pr_info.outputs.headRef }} run: | echo "--- Checking remotes ---" git remote -v echo "--- Checking ref on origin (${{ steps.pr_info.outputs.headRepoFullName }}) ---" git ls-remote origin refs/pull/$PR_NUMBER/merge || echo "Ref not found on origin (fork)." echo "--- Checking ref on base (${{ github.repository }}) ---" git ls-remote $BASE_REPO_URL refs/pull/$PR_NUMBER/merge || echo "Ref not found on base repository." echo "--- Proceeding with fetch from base repository ---" git fetch $BASE_REPO_URL refs/pull/$PR_NUMBER/merge:refs/remotes/pull/$PR_NUMBER/merge git checkout refs/remotes/pull/$PR_NUMBER/merge echo "PR_MERGE_SHA: $(git log -1 --format=%H)" PR_MERGE_COMMIT_TIMESTAMP=$(git log -1 --date=unix --format=%cd) echo "PR_MERGE_COMMIT_TIMESTAMP: $PR_MERGE_COMMIT_TIMESTAMP" COMMENT_TIMESTAMP=$(date -d "${COMMENT_DATE}" +"%s") echo "COMMENT_DATE: $COMMENT_DATE" echo "COMMENT_TIMESTAMP: $COMMENT_TIMESTAMP" if [ $COMMENT_TIMESTAMP -le $PR_MERGE_COMMIT_TIMESTAMP ]; then echo "❌ Last commit on the pull request is newer than the issue comment triggering this run! Abort!"; exit -1; fi echo "--- Checking out contributor branch ($HEADREF) ---" git checkout $HEADREF - name: Comment on PR with workflow run link id: init_comment uses: actions/github-script@v6 with: script: | const prNumber = parseInt(process.env.prNumber, 10); const runUrl = `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}` const { data: botComment } = await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: prNumber, body: `Style fix is beginning .... [View the workflow run here](${runUrl}).` }); core.setOutput('comment_id', botComment.id); env: prNumber: ${{ steps.pr_info.outputs.prNumber }} - name: Set up Python uses: actions/setup-python@v4 with: python-version: ${{ inputs.python_version }} - name: Install dependencies env: python_quality_dependencies: ${{ inputs.python_quality_dependencies }} run: | python -m pip install --upgrade pip pip install .$python_quality_dependencies echo ${{ steps.init_comment.outputs.comment_id }} - name: Run style command id: run_style env: STYLECOMMANDTYPE : ${{ inputs.style_command_type }} run: | case "$STYLECOMMANDTYPE" in "default") echo "Running default style and quality checks" make style && make quality ;; "quality_only") echo "Running quality checks only" make quality ;; "style_only") echo "Running style checks only" make style ;; *) echo "Invalid style_command_type: $STYLECOMMANDTYPE" echo "Valid options are: 'default', 'quality_only', 'style_only'" exit 1 ;; esac - name: Commit and push changes id: commit_and_push env: HEADREPOFULLNAME: ${{ steps.pr_info.outputs.headRepoFullName }} HEADREF: ${{ steps.pr_info.outputs.headRef }} PRNUMBER: ${{ steps.pr_info.outputs.prNumber }} GITHUB_TOKEN: ${{ secrets.bot_token }} run: | echo "HEADREPOFULLNAME: $HEADREPOFULLNAME, HEADREF: $HEADREF" # Configure git with the Actions bot user git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" # Make sure your 'origin' remote is set to the contributor's fork git remote set-url origin "https://x-access-token:${GITHUB_TOKEN}@github.com/$HEADREPOFULLNAME.git" # If there are changes after running style/quality, commit them if [ -n "$(git status --porcelain)" ]; then git add . git commit -m "Apply style fixes" # Push to the original contributor's forked branch git push origin HEAD:$HEADREF echo "changes_pushed=true" >> $GITHUB_OUTPUT else echo "No changes to commit." echo "changes_pushed=false" >> $GITHUB_OUTPUT fi - name: Prepare final comment message id: prepare_final_comment run: | if [ "${{ steps.commit_and_push.outputs.changes_pushed }}" = 'true' ]; then echo "final_comment=Style bot fixed some files and pushed the changes." >> $GITHUB_OUTPUT else echo "final_comment=Style fix runs successfully without any file modified." >> $GITHUB_OUTPUT fi - name: Comment on PR uses: actions/github-script@v6 with: script: | const prNumber = parseInt(process.env.prNumber, 10); const runUrl = `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}` await github.rest.issues.updateComment({ owner: context.repo.owner, repo: context.repo.repo, comment_id: ${{ steps.init_comment.outputs.comment_id }}, body: `${{ steps.prepare_final_comment.outputs.final_comment }}` }); env: prNumber: ${{ steps.pr_info.outputs.prNumber }} huggingface_hub-1.1.5/.github/workflows/style-bot.yml000066400000000000000000000005251510763414300226730ustar00rootroot00000000000000name: Style Bot on: issue_comment: types: [created] permissions: contents: write pull-requests: write jobs: style: uses: ./.github/workflows/style-bot-action.yml with: python_quality_dependencies: "[quality]" style_command_type: "style_only" secrets: bot_token: ${{ secrets.HF_STYLE_BOT_ACTION }}huggingface_hub-1.1.5/.github/workflows/trufflehog.yml000066400000000000000000000004721510763414300231170ustar00rootroot00000000000000on: push: name: Secret Leaks jobs: trufflehog: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 with: fetch-depth: 0 - name: Secret Scanning uses: trufflesecurity/trufflehog@main with: extra_args: --results=verified,unknownhuggingface_hub-1.1.5/.github/workflows/update-inference-types.yaml000066400000000000000000000063761510763414300255040ustar00rootroot00000000000000name: Update Inference Types on: workflow_dispatch: schedule: - cron: "0 3 * * *" # Every day at 3am concurrency: group: update-inference-types cancel-in-progress: true jobs: pull_request: runs-on: ubuntu-latest steps: # Setup Python - uses: actions/checkout@v3 with: repository: huggingface/huggingface_hub path: ./huggingface_hub - name: Set up Python uses: actions/setup-python@v2 with: python-version: "3.10" - name: Setup uv run: | pip install --upgrade uv - name: Install dependencies run: uv pip install --system "huggingface_hub[dev] @ ." working-directory: ./huggingface_hub # Setup JS - uses: actions/checkout@v3 with: repository: huggingface/huggingface.js path: huggingface.js - uses: actions/setup-node@v3 with: node-version: "20" - name: Install pnpm uses: pnpm/action-setup@v2 with: package_json_file: ./huggingface.js/packages/tasks-gen/package.json - name: Install dependencies run: pnpm install working-directory: ./huggingface.js/packages/tasks-gen # Generate specs - run: pnpm run inference-codegen working-directory: ./huggingface.js/packages/tasks-gen # Copy Python types to huggingface_hub - run: cp -r ./huggingface.js/packages/tasks/.python_generated/* ./huggingface_hub/src/huggingface_hub/inference/_generated/types # Do not auto-generate chat completion types (now manually maintained) - run: git checkout ./src/huggingface_hub/inference/_generated/types/chat_completion.py working-directory: ./huggingface_hub # Post-process - run: make inference_update working-directory: ./huggingface_hub - run: make style working-directory: ./huggingface_hub # Check changes - run: git status working-directory: ./huggingface_hub # Create or update Pull Request - name: Create Pull Request uses: peter-evans/create-pull-request@v7 with: path: ./huggingface_hub token: ${{ secrets.TOKEN_INFERENCE_SYNC_BOT }} commit-message: Update inference types (automated commit) branch: update-inference-types-automated-pr delete-branch: true title: "[Bot] Update inference types" body: | This PR updates the inference types. It has been generated by running: ```sh # Generate Python code pnpm run inference-codegen # from @huggingface/tasks-gen # Copy to this repository cp -r ./huggingface.js/packages/tasks/.python_generated/* ./huggingface_hub/src/huggingface_hub/inference/_generated/types # Clean things make inference_update make style ``` This PR was automatically created by the [Update Inference Types workflow](https://github.com/huggingface/huggingface_hub/blob/main/.github/workflows/update-inference-types.yaml). Make sure the changes are correct before merging. labels: | specs reviewers: | Wauplin hanouticelina huggingface_hub-1.1.5/.github/workflows/upload_pr_documentation.yaml000066400000000000000000000006051510763414300260270ustar00rootroot00000000000000name: Upload PR Documentation on: workflow_run: workflows: ["Build PR Documentation"] types: - completed jobs: build: uses: huggingface/doc-builder/.github/workflows/upload_pr_documentation.yml@main with: package_name: huggingface_hub secrets: hf_token: ${{ secrets.HF_DOC_BUILD_PUSH }} comment_bot_token: ${{ secrets.COMMENT_BOT_TOKEN }} huggingface_hub-1.1.5/.gitignore000066400000000000000000000036011510763414300166170ustar00rootroot00000000000000# Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] *$py.class # C extensions *.so # Distribution / packaging .Python build/ develop-eggs/ dist/ downloads/ eggs/ .eggs/ lib64/ parts/ sdist/ var/ wheels/ pip-wheel-metadata/ share/python-wheels/ *.egg-info/ .installed.cfg *.egg MANIFEST # PyInstaller # Usually these files are written by a python script from a template # before PyInstaller builds the exe, so as to inject date/other infos into it. *.manifest *.spec # Installer logs pip-log.txt pip-delete-this-directory.txt # Unit test / coverage reports htmlcov/ .tox/ .nox/ .coverage .coverage.* .cache nosetests.xml coverage.xml *.cover *.py,cover .hypothesis/ .pytest_cache/ # Translations *.mo *.pot # Django stuff: *.log local_settings.py db.sqlite3 db.sqlite3-journal # Flask stuff: instance/ .webassets-cache # Scrapy stuff: .scrapy # Sphinx documentation docs/_build/ # PyBuilder target/ # Jupyter Notebook .ipynb_checkpoints # IPython profile_default/ ipython_config.py # pyenv .python-version # pipenv # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. # However, in case of collaboration, if having platform-specific dependencies or dependencies # having no cross-platform support, pipenv may install dependencies that don't work, or not # install all needed dependencies. #Pipfile.lock # PEP 582; used by e.g. github.com/David-OConnor/pyflow __pypackages__/ # Celery stuff celerybeat-schedule celerybeat.pid # SageMath parsed files *.sage.py # Environments .env .venv .venv* env/ venv/ ENV/ env.bak/ venv.bak/ .venv* # Spyder project settings .spyderproject .spyproject # Rope project settings .ropeproject # mkdocs documentation /site # mypy .mypy_cache/ .dmypy.json dmypy.json # Pyre type checker .pyre/ .vscode/ .idea/ .DS_Store # Ruff .ruff_cache # Spell checker config cspell.json tmp* # Claude Code CLAUDE.mdhuggingface_hub-1.1.5/.pre-commit-config.yaml000066400000000000000000000010471510763414300211120ustar00rootroot00000000000000repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.5.0 hooks: - id: check-yaml exclude: .github/conda/meta.yaml|tests/cassettes/ - id: end-of-file-fixer - id: trailing-whitespace - id: check-case-conflict - id: check-merge-conflict - repo: https://github.com/charliermarsh/ruff-pre-commit # https://github.com/charliermarsh/ruff#usage rev: v0.1.13 hooks: - id: ruff - repo: https://github.com/pappasam/toml-sort rev: v0.23.1 hooks: - id: toml-sort-fix huggingface_hub-1.1.5/CODE_OF_CONDUCT.md000066400000000000000000000121521510763414300174270ustar00rootroot00000000000000 # Contributor Covenant Code of Conduct ## Our Pledge We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. ## Our Standards Examples of behavior that contributes to a positive environment for our community include: * Demonstrating empathy and kindness toward other people * Being respectful of differing opinions, viewpoints, and experiences * Giving and gracefully accepting constructive feedback * Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience * Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: * The use of sexualized language or imagery, and sexual attention or advances of any kind * Trolling, insulting or derogatory comments, and personal or political attacks * Public or private harassment * Publishing others' private information, such as a physical or email address, without their explicit permission * Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement Responsibilities Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. ## Scope This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at feedback@huggingface.co. All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the reporter of any incident. ## Enforcement Guidelines Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: ### 1. Correction **Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community. **Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. ### 2. Warning **Community Impact**: A violation through a single incident or series of actions. **Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. ### 3. Temporary Ban **Community Impact**: A serious violation of community standards, including sustained inappropriate behavior. **Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. ### 4. Permanent Ban **Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals. **Consequence**: A permanent ban from any sort of public interaction within the community. ## Attribution This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity). [homepage]: https://www.contributor-covenant.org For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations. huggingface_hub-1.1.5/CONTRIBUTING.md000066400000000000000000000266401510763414300170700ustar00rootroot00000000000000 # How to contribute to huggingface_hub, the GitHub repository? Everyone is welcome to contribute, and we value everybody's contribution. Code is not the only way to help the community. Answering questions, helping others, reaching out and improving the documentations are immensely valuable to the community. It also helps us if you spread the word: reference the library from blog posts on the awesome projects it made possible, shout out on Twitter every time it has helped you, or simply star the repo to say "thank you". Whichever way you choose to contribute, please be mindful to respect our [code of conduct](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md). > Looking for a good first issue to work on? > Please check out our contributing guide below and then select an issue from our [curated list](https://github.com/huggingface/huggingface_hub/contribute). > Pick one and get started with it! ### The client library, `huggingface_hub` This repository hosts the `huggingface_hub`, the client library that interfaces any Python script with the Hugging Face Hub. Its implementation lives in `src/huggingface_hub`, while the tests are located in `tests/`. There are many ways you can contribute to this client library: - Fixing outstanding issues with the existing code; - Contributing to the examples or to the documentation; - Submitting issues related to bugs or desired new features. ## Submitting a new issue or feature request Do your best to follow these guidelines when submitting an issue or a feature request. It will make it easier for us to come back to you quickly and with good feedback. ### Did you find a bug? The `huggingface_hub` library is robust and reliable thanks to the users who notify us of the problems they encounter. So thank you for reporting an issue. First, we would really appreciate it if you could **make sure the bug was not already reported** (use the search bar on Github under Issues). Did not find it? :( So we can act quickly on it, please follow these steps: - A short, self-contained, code snippet that allows us to reproduce the bug in less than 30s; - Provide the _full_ traceback if an exception is raised by copying the text from your terminal in the issue description. - Include information about your local setup. You can dump this information by running `hf env` in your terminal; ### Do you want a new feature? A good feature request addresses the following points: 1. Motivation first: - Is it related to a problem/frustration with the library? If so, please explain why and provide a code snippet that demonstrates the problem best. - Is it related to something you would need for a project? We'd love to hear about it! - Is it something you worked on and think could benefit the community? Awesome! Tell us what problem it solved for you. 2. Write a _full paragraph_ describing the feature; 3. Provide a **code snippet** that demonstrates its future use; 4. In case this is related to a paper, please attach a link; 5. Attach any additional information (drawings, screenshots, etc.) you think may help. If your issue is well written, we're already 80% of the way there by the time you post it! ## Submitting a pull request (PR) Before writing code, we strongly advise you to search through the existing PRs or issues to make sure that nobody is already working on the same thing. If you are unsure, it is always a good idea to open an issue to get some feedback. You will need basic `git` proficiency to be able to contribute to `huggingface_hub`. `git` is not the easiest tool to use but it has the greatest manual. Type `git --help` in a shell and enjoy. If you prefer books, [Pro Git](https://git-scm.com/book/en/v2) is a very good reference. Follow these steps to start contributing: 1. Fork the [repository](https://github.com/huggingface/huggingface_hub) by clicking on the 'Fork' button on the repository's page. This creates a copy of the code under your GitHub user account. 2. Clone your fork to your local disk, and add the base repository as a remote. The following command assumes you have your public SSH key uploaded to GitHub. See the following guide for more [information](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository). ```bash $ git clone git@github.com:/huggingface_hub.git $ cd huggingface_hub $ git remote add upstream https://github.com/huggingface/huggingface_hub.git ``` 3. Create a new branch to hold your development changes, and do this for every new PR you work on. Start by synchronizing your `main` branch with the `upstream/main` branch (more details in the [GitHub Docs](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/syncing-a-fork)): ```bash $ git checkout main $ git fetch upstream $ git merge upstream/main ``` Once your `main` branch is synchronized, create a new branch from it: ```bash $ git checkout -b a-descriptive-name-for-my-changes ``` **Do not** work on the `main` branch. 4. Set up a development environment by running the following command in a [virtual environment](https://docs.python.org/3/library/venv.html#creating-virtual-environments) or a conda environment you've created for working on this library: ```bash $ pip uninstall huggingface_hub # make sure huggingface_hub is not already installed $ pip install -e ".[dev]" # install in editable (-e) mode ``` 5. Develop the features on your branch 6. Test your implementation! To make a good Pull Request you must test the features you have added. To do so, we use the `unittest` framework and run them using `pytest`: ```bash $ pytest tests -k # or $ pytest tests/.py ``` 7. Format your code. `huggingface_hub` relies on [`ruff`](https://github.com/astral-sh/ruff) to format its source code consistently. You can apply automatic style corrections and code verifications with the following command: ```bash $ make style ``` This command will update your code to comply with the standards of the `huggingface_hub` repository. A few custom scripts are also run to ensure consistency. Once automatic style corrections have been applied, you must test that it passes the quality checks: ```bash $ make quality ``` Compared to `make style`, `make quality` will never update your code. In addition to the previous code formatter, it also runs [`ty`](https://docs.astral.sh/ty/) type checker to check for static typing issues. All those tests will also run in the CI once you open your PR but it is recommended to run them locally in order to iterate faster. > For the commands leveraging the `make` utility, we recommend using the WSL system when running on > Windows. More information [here](https://docs.microsoft.com/en-us/windows/wsl/about). 8. (optional) Alternatively, you can install pre-commit hooks so that these styles are applied and checked on files that you have touched in each commit: ```bash pip install pre-commit pre-commit install ``` You only need to do the above once in your repository's environment. If for any reason you would like to disable pre-commit hooks on a commit, you can pass `-n` to your `git commit` command to temporarily disable pre-commit hooks. To permanently disable hooks, you can run the following command: ```bash pre-commit uninstall ``` 9. Once you're happy with your changes, add changed files using `git add` and make a commit with `git commit` to record your changes locally: ```bash $ git add modified_file.py $ git commit ``` Please write [good commit messages](https://chris.beams.io/posts/git-commit/). It is a good idea to sync your copy of the code with the original repository regularly. The following document covers it in length: [github documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) And here's how you can do it quickly from your `git` commandline: ```bash $ git fetch upstream $ git rebase upstream/main ``` Push the changes to your account using: ```bash $ git push -u origin a-descriptive-name-for-my-changes ``` 10. Once you are satisfied (**and the [checklist below](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md#checklist) is happy too**), go to the webpage of your fork on GitHub. Click on 'Pull request' to send your changes to the project maintainers for review. 11. It's ok if maintainers ask you for changes. It happens all the time to core contributors too! So everyone can see the changes in the Pull request, work in your local branch and push the changes to your fork. They will automatically appear in the pull request. 12. Once your changes have been approved, one of the project maintainers will merge your pull request for you. Good job! ### Checklist 1. The title of your pull request should be a summary of its contribution; 2. If your pull request addresses an issue, please mention the issue number in the pull request description to make sure they are linked (and people consulting the issue know you are working on it); 3. To indicate a work in progress please prefix the title with `[WIP]`, or mark the PR as a draft PR. These are useful to avoid duplicated work, and to differentiate it from PRs ready to be merged; 4. Make sure existing tests pass; 5. Add high-coverage tests. No quality testing = no merge. 6. Due to the rapidly growing repository, it is important to make sure that no files that would significantly weigh down the repository are added. This includes images, videos and other non-text files. We prefer to leverage a hf.co hosted `dataset` like the ones hosted on [`hf-internal-testing`](https://huggingface.co/hf-internal-testing) in which to place these files and reference them by URL. We recommend putting them in the following dataset: [huggingface/documentation-images](https://huggingface.co/datasets/huggingface/documentation-images). If an external contribution, feel free to add the images to your PR and ask a Hugging Face member to migrate your images to this dataset. ### Tests An extensive test suite is included to test the library behavior and several examples. Library tests can be found in the [tests folder](https://github.com/huggingface/huggingface_hub/tree/main/tests). We use `pytest` in order to run the tests for the library. From the root of the repository they can be run with the following: ```bash $ python -m pytest ./tests ``` You can specify a smaller set of tests in order to test only the feature you're working on. For example, the following will only run the tests in the `test_repository.py` file: ```bash $ python -m pytest ./tests/test_repository.py ``` And the following will only run the tests that include `tag` in their name: ```bash $ python -m pytest ./tests -k tag ``` huggingface_hub-1.1.5/LICENSE000066400000000000000000000261351510763414300156430ustar00rootroot00000000000000 Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. huggingface_hub-1.1.5/MANIFEST.in000066400000000000000000000002361510763414300163660ustar00rootroot00000000000000include src/huggingface_hub/templates/modelcard_template.md include src/huggingface_hub/templates/datasetcard_template.md include src/huggingface_hub/py.typedhuggingface_hub-1.1.5/Makefile000066400000000000000000000017071510763414300162740ustar00rootroot00000000000000.PHONY: quality style test check_dirs := src tests utils setup.py quality: ruff check $(check_dirs) # linter ruff format --check $(check_dirs) # formatter python utils/check_inference_input_params.py python utils/check_static_imports.py python utils/check_all_variable.py python utils/generate_async_inference_client.py python utils/generate_cli_reference.py ty check src style: ruff format $(check_dirs) # formatter ruff check --fix $(check_dirs) # linter python utils/check_static_imports.py --update python utils/check_all_variable.py --update python utils/generate_async_inference_client.py --update python utils/generate_cli_reference.py --update inference_check: python utils/generate_inference_types.py python utils/check_task_parameters.py inference_update: python utils/generate_inference_types.py --update python utils/check_task_parameters.py --update repocard: python utils/push_repocard_examples.py test: pytest ./tests/ huggingface_hub-1.1.5/README.md000066400000000000000000000162441510763414300161150ustar00rootroot00000000000000

huggingface_hub library logo

The official Python client for the Huggingface Hub.

Documentation GitHub release PyPi version PyPI - Downloads Code coverage

English | Deutsch | Français | हिंदी | 한국어 | 中文 (简体)

--- **Documentation**: https://hf.co/docs/huggingface_hub **Source Code**: https://github.com/huggingface/huggingface_hub --- ## Welcome to the huggingface_hub library The `huggingface_hub` library allows you to interact with the [Hugging Face Hub](https://huggingface.co/), a platform democratizing open-source Machine Learning for creators and collaborators. Discover pre-trained models and datasets for your projects or play with the thousands of machine learning apps hosted on the Hub. You can also create and share your own models, datasets and demos with the community. The `huggingface_hub` library provides a simple way to do all these things with Python. ## Key features - [Download files](https://huggingface.co/docs/huggingface_hub/en/guides/download) from the Hub. - [Upload files](https://huggingface.co/docs/huggingface_hub/en/guides/upload) to the Hub. - [Manage your repositories](https://huggingface.co/docs/huggingface_hub/en/guides/repository). - [Run Inference](https://huggingface.co/docs/huggingface_hub/en/guides/inference) on deployed models. - [Search](https://huggingface.co/docs/huggingface_hub/en/guides/search) for models, datasets and Spaces. - [Share Model Cards](https://huggingface.co/docs/huggingface_hub/en/guides/model-cards) to document your models. - [Engage with the community](https://huggingface.co/docs/huggingface_hub/en/guides/community) through PRs and comments. ## Installation Install the `huggingface_hub` package with [pip](https://pypi.org/project/huggingface-hub/): ```bash pip install huggingface_hub ``` If you prefer, you can also install it with [conda](https://huggingface.co/docs/huggingface_hub/en/installation#install-with-conda). In order to keep the package minimal by default, `huggingface_hub` comes with optional dependencies useful for some use cases. For example, if you want to use the MCP module, run: ```bash pip install "huggingface_hub[mcp]" ``` To learn more installation and optional dependencies, check out the [installation guide](https://huggingface.co/docs/huggingface_hub/en/installation). ## Quick start ### Download files Download a single file ```py from huggingface_hub import hf_hub_download hf_hub_download(repo_id="tiiuae/falcon-7b-instruct", filename="config.json") ``` Or an entire repository ```py from huggingface_hub import snapshot_download snapshot_download("stabilityai/stable-diffusion-2-1") ``` Files will be downloaded in a local cache folder. More details in [this guide](https://huggingface.co/docs/huggingface_hub/en/guides/manage-cache). ### Login The Hugging Face Hub uses tokens to authenticate applications (see [docs](https://huggingface.co/docs/hub/security-tokens)). To log in your machine, run the following CLI: ```bash hf auth login # or using an environment variable hf auth login --token $HUGGINGFACE_TOKEN ``` ### Create a repository ```py from huggingface_hub import create_repo create_repo(repo_id="super-cool-model") ``` ### Upload files Upload a single file ```py from huggingface_hub import upload_file upload_file( path_or_fileobj="/home/lysandre/dummy-test/README.md", path_in_repo="README.md", repo_id="lysandre/test-model", ) ``` Or an entire folder ```py from huggingface_hub import upload_folder upload_folder( folder_path="/path/to/local/space", repo_id="username/my-cool-space", repo_type="space", ) ``` For details in the [upload guide](https://huggingface.co/docs/huggingface_hub/en/guides/upload). ## Integrating to the Hub. We're partnering with cool open source ML libraries to provide free model hosting and versioning. You can find the existing integrations [here](https://huggingface.co/docs/hub/libraries). The advantages are: - Free model or dataset hosting for libraries and their users. - Built-in file versioning, even with very large files, thanks to a git-based approach. - In-browser widgets to play with the uploaded models. - Anyone can upload a new model for your library, they just need to add the corresponding tag for the model to be discoverable. - Fast downloads! We use Cloudfront (a CDN) to geo-replicate downloads so they're blazing fast from anywhere on the globe. - Usage stats and more features to come. If you would like to integrate your library, feel free to open an issue to begin the discussion. We wrote a [step-by-step guide](https://huggingface.co/docs/hub/adding-a-library) with ❤️ showing how to do this integration. ## Contributions (feature requests, bugs, etc.) are super welcome 💙💚💛💜🧡❤️ Everyone is welcome to contribute, and we value everybody's contribution. Code is not the only way to help the community. Answering questions, helping others, reaching out and improving the documentations are immensely valuable to the community. We wrote a [contribution guide](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) to summarize how to get started to contribute to this repository. huggingface_hub-1.1.5/codecov.yml000066400000000000000000000004661510763414300170020ustar00rootroot00000000000000comment: # https://docs.codecov.com/docs/pull-request-comments#requiring-changes require_changes: true # https://docs.codecov.com/docs/pull-request-comments#after_n_builds after_n_builds: 12 coverage: status: # not in PRs patch: false project: false github_checks: annotations: false huggingface_hub-1.1.5/docs/000077500000000000000000000000001510763414300155575ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/README.md000066400000000000000000000255021510763414300170420ustar00rootroot00000000000000 # Generating the documentation To generate the documentation, you have to build it. Several packages are necessary to build the doc. First, you need to install the project itself by running the following command at the root of the code repository: ```bash pip install -e . ``` You also need to install 2 extra packages: ```bash # `hf-doc-builder` to build the docs pip install git+https://github.com/huggingface/doc-builder@main # `watchdog` for live reloads pip install watchdog ``` --- **NOTE** You only need to generate the documentation to inspect it locally (if you're planning changes and want to check how they look before committing for instance). You don't have to commit the built documentation. --- ## Building the documentation Once you have set up the `doc-builder` and additional packages with the pip install command above, you can generate the documentation by typing the following command: ```bash doc-builder build huggingface_hub docs/source/en/ --build_dir ~/tmp/test-build ``` You can adapt the `--build_dir` to set any temporary folder that you prefer. This command will create it and generate the MDX files that will be rendered as the documentation on the main website. You can inspect them in your favorite Markdown editor. ## Previewing the documentation To preview the docs, run the following command: ```bash doc-builder preview huggingface_hub docs/source/en/ ``` The docs will be viewable at [http://localhost:5173](http://localhost:5173). You can also preview the docs once you have opened a PR. You will see a bot add a comment to a link where the documentation with your changes lives. --- **NOTE** The `preview` command only works with existing doc files. When you add a completely new file, you need to update `_toctree.yml` & restart `preview` command (`ctrl-c` to stop it & call `doc-builder preview ...` again). --- ## Adding a new element to the navigation bar Accepted files are Markdown (.md). Create a file with its extension and put it in the source directory. You can then link it to the toc-tree by putting the filename without the extension in the [`_toctree.yml`](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/_toctree.yml) file. ## Renaming section headers and moving sections It helps to keep the old links working when renaming the section header and/or moving sections from one document to another. This is because the old links are likely to be used in Issues, Forums, and Social media and it'd make for a much more superior user experience if users reading those months later could still easily navigate to the originally intended information. Therefore, we simply keep a little map of moved sections at the end of the document where the original section was. The key is to preserve the original anchor. So if you renamed a section from: "Section A" to "Section B", then you can add at the end of the file: ``` Sections that were moved: [ Section A ] ``` and of course, if you moved it to another file, then: ``` Sections that were moved: [ Section A ] ``` Use the relative style to link to the new file so that the versioned docs continue to work. For an example of a rich moved section set please see the very end of [the transformers Trainer doc](https://github.com/huggingface/transformers/blob/main/docs/source/en/main_classes/trainer.md). ## Writing Documentation - Specification The `huggingface/huggingface_hub` documentation follows the [Google documentation](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) style for docstrings, although we can write them directly in Markdown. ### Adding a new tutorial Adding a new tutorial or section is done in two steps: - Add a new Markdown (.md) file under `./source`. - Link that file in `./source/_toctree.yml` on the correct toc-tree. Make sure to put your new file under the proper section. If you have a doubt, feel free to ask in a Github Issue or PR. ### Translating When translating, refer to the guide at [./TRANSLATING.md](https://github.com/huggingface/huggingface_hub/blob/main/docs/TRANSLATING.md). ### Writing source documentation Values that should be put in `code` should either be surrounded by backticks: \`like so\`. Note that argument names and objects like True, None, or any strings should usually be put in `code`. When mentioning a class, function, or method, it is recommended to use our syntax for internal links so that our tool adds a link to its documentation with this syntax: \[\`XXXClass\`\] or \[\`function\`\]. This requires the class or function to be in the main package. If you want to create a link to some internal class or function, you need to provide its path. For instance: \[\`utils.ModelOutput\`\]. This will be converted into a link with `utils.ModelOutput` in the description. To get rid of the path and only keep the name of the object you are linking to in the description, add a ~: \[\`~utils.ModelOutput\`\] will generate a link with `ModelOutput` in the description. The same works for methods so you can either use \[\`XXXClass.method\`\] or \[~\`XXXClass.method\`\]. #### Defining arguments in a method Arguments should be defined with the `Args:` (or `Arguments:` or `Parameters:`) prefix, followed by a line return and an indentation. The argument should be followed by its type, with its shape if it is a tensor, a colon, and its description: ``` Args: n_layers (`int`): The number of layers of the model. ``` If the description is too long to fit in one line, another indentation is necessary before writing the description after the argument. Here's an example showcasing everything so far: ``` Args: input_ids (`torch.LongTensor` of shape `(batch_size, sequence_length)`): Indices of input sequence tokens in the vocabulary. Indices can be obtained using [`AlbertTokenizer`]. See [`~PreTrainedTokenizer.encode`] and [`~PreTrainedTokenizer.__call__`] for details. [What are input IDs?](../glossary#input-ids) ``` For optional arguments or arguments with defaults we follow the following syntax: imagine we have a function with the following signature: ``` def my_function(x: str = None, a: float = 1): ``` then its documentation should look like this: ``` Args: x (`str`, *optional*): This argument controls ... a (`float`, *optional*, defaults to 1): This argument is used to ... ``` Note that we always omit the "defaults to \`None\`" when None is the default for any argument. Also note that even if the first line describing your argument type and its default gets long, you can't break it on several lines. You can however write as many lines as you want in the indented description (see the example above with `input_ids`). #### Writing a multi-line code block Multi-line code blocks can be useful for displaying examples. They are done between two lines of three backticks as usual in Markdown: ```` ``` # first line of code # second line # etc ``` ```` #### Writing a return block The return block should be introduced with the `Returns:` prefix, followed by a line return and an indentation. The first line should be the type of the return, followed by a line return. No need to indent further for the elements building the return. Here's an example of a single value return: ``` Returns: `List[int]`: A list of integers in the range [0, 1] --- 1 for a special token, 0 for a sequence token. ``` Here's an example of a tuple return, comprising several objects: ``` Returns: `tuple(torch.FloatTensor)` comprising various elements depending on the configuration ([`BertConfig`]) and inputs: - ** loss** (*optional*, returned when `masked_lm_labels` is provided) `torch.FloatTensor` of shape `(1,)` -- Total loss is the sum of the masked language modeling loss and the next sequence prediction (classification) loss. - **prediction_scores** (`torch.FloatTensor` of shape `(batch_size, sequence_length, config.vocab_size)`) -- Prediction scores of the language modeling head (scores for each vocabulary token before SoftMax). ``` #### Adding an image Due to the rapidly growing repository, it is important to make sure that no files that would significantly weigh down the repository are added. This includes images, videos, and other non-text files. We prefer to leverage a hf.co hosted `dataset` like the ones hosted on [`hf-internal-testing`](https://huggingface.co/hf-internal-testing) in which to place these files and reference them by URL. We recommend putting them in the following dataset: [huggingface/documentation-images](https://huggingface.co/datasets/huggingface/documentation-images). If an external contribution, feel free to add the images to your PR and ask a Hugging Face member to migrate your images to this dataset. #### Writing documentation examples The syntax for Example docstrings can look as follows: ``` Example: ```python >>> from transformers import Wav2Vec2Processor, Wav2Vec2ForCTC >>> from datasets import load_dataset >>> import torch >>> dataset = load_dataset("hf-internal-testing/librispeech_asr_demo", "clean", split="validation") >>> dataset = dataset.sort("id") >>> sampling_rate = dataset.features["audio"].sampling_rate >>> processor = Wav2Vec2Processor.from_pretrained("facebook/wav2vec2-base-960h") >>> model = Wav2Vec2ForCTC.from_pretrained("facebook/wav2vec2-base-960h") >>> # audio file is decoded on the fly >>> inputs = processor(dataset[0]["audio"]["array"], sampling_rate=sampling_rate, return_tensors="pt") >>> with torch.no_grad(): ... logits = model(**inputs).logits >>> predicted_ids = torch.argmax(logits, dim=-1) >>> # transcribe speech >>> transcription = processor.batch_decode(predicted_ids) >>> transcription[0] 'MISTER QUILTER IS THE APOSTLE OF THE MIDDLE CLASSES AND WE ARE GLAD TO WELCOME HIS GOSPEL' ``` ``` The docstring should give a minimal, clear example of how the respective model is to be used in inference and also include the expected (ideally sensible) output. Often, readers will try out the example before even going through the function or class definitions. Therefore, it is of utmost importance that the example works as expected. huggingface_hub-1.1.5/docs/TRANSLATING.md000066400000000000000000000063551510763414300177000ustar00rootroot00000000000000### Translating the `huggingface_hub` documentation into your language As part of our mission to democratize machine learning, we'd love to make the `huggingface_hub` library available in many more languages! Follow the steps below if you want to help translate the documentation into your language 🙏. **🗞️ Open an issue** To get started, navigate to the [Issues](https://github.com/huggingface/huggingface_hub/issues) page of this repo and check if anyone else has opened an issue for your language. If not, open a new issue by selecting the "Translation template" from the "New issue" button. Once an issue exists, post a comment to indicate which chapters you'd like to work on, and we'll add your name to the list. **🍴 Fork the repository** First, you'll need to [fork the `huggingface_hub` repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo). You can do this by clicking on the **Fork** button on the top-right corner of this repo's page. Once you've forked the repo, you'll want to get the files on your local machine for editing. You can do that by cloning the fork with Git as follows: ```bash git clone https://github.com/YOUR-USERNAME/huggingface_hub.git ``` **📋 Copy-paste the English version with a new language code** The documentation files are in one leading directory: - [`docs/source`](https://github.com/huggingface/huggingface_hub/tree/main/docs/source): All the documentation materials are organized here by language. You'll only need to copy the files in the [`docs/source/en`](https://github.com/huggingface/huggingface_hub/tree/main/docs/source/en) directory, so first navigate to your fork of the repo and run the following: ```bash cd ~/path/to/huggingface_hub/docs cp -r source/en source/LANG-ID ``` Here, `LANG-ID` should be one of the ISO 639-1 or ISO 639-2 language codes -- see [here](https://www.loc.gov/standards/iso639-2/php/code_list.php) for a handy table. **✍️ Start translating** The fun part comes - translating the text! The first thing we recommend is translating the part of the `_toctree.yml` file that corresponds to your doc chapter. This file is used to render the table of contents on the website. > 🙋 If the `_toctree.yml` file doesn't yet exist for your language, you can create one by copy-pasting from the English version and deleting the sections unrelated to your chapter. Just make sure it exists in the `docs/source/LANG-ID/` directory! The fields you should add are `local` (with the name of the file containing the translation; e.g. `guides/manage-spaces`), and `title` (with the title of the doc in your language; e.g. `Manage your Space`) -- as a reference, here is the `_toctree.yml` for [English](https://github.com/huggingface/huggingface_hub/blob/main/docs/source/en/_toctree.yml): ```yaml - title: "How-to guides" # Translate this! sections: - local: guides/manage-spaces # Do not change this! Use the same name for your .md file title: Manage your Space # Translate this! ... ``` Once you have translated the `_toctree.yml` file, you can start translating the Markdown files associated with your docs chapter. > 🙋 If you'd like others to help you with the translation, you should [open an issue](https://github.com/huggingface/huggingface_hub/issues) and tag @Wauplin. huggingface_hub-1.1.5/docs/dev/000077500000000000000000000000001510763414300163355ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/dev/release.md000066400000000000000000000032041510763414300202760ustar00rootroot00000000000000This document covers all steps that need to be done in order to do a release of the `huggingface_hub` library. 1. On a clone of the main repo, not your fork, checkout the main branch and pull the latest changes: ``` git checkout main git pull ``` 2. Checkout a new branch with the version that you'd like to release: v-release, for example `v0.5-release`. All patches will be done to that same branch. 3. Update the `__version__` variable in the `src/huggingface_hub/__init__.py` file to point to the version you're releasing: ``` __version__ = "" ``` 4. Make sure that the conda build works correctly by building it locally: ``` conda install -c defaults anaconda-client conda-build HUB_VERSION= conda-build .github/conda ``` 5. Make sure that the pip wheel works correctly by building it locally and installing it: ``` pip install setuptools wheel python setup.py sdist bdist_wheel pip install dist/huggingface_hub--py3-none-any.whl ``` 6. Commit, tag, and push the branch: ``` git commit -am "Release: v" git tag v -m "Adds tag v for pypi and conda" git push -u --tags origin v-release ``` 7. Verify that the docs have been built correctly. You can check that on the following link: https://huggingface.co/docs/huggingface_hub/v 8. Checkout main once again to update the version in the `__init__.py` file: ``` git checkout main ``` 9. Update the version to contain the `.dev0` suffix: ``` __version__ = ".dev0" # For example, after releasing v0.5.0 or v0.5.1: "0.6.0.dev0". ``` 10. Push the changes! ``` git push origin main ``` huggingface_hub-1.1.5/docs/source/000077500000000000000000000000001510763414300170575ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/cn/000077500000000000000000000000001510763414300174575ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/cn/_toctree.yml000066400000000000000000000010221510763414300220010ustar00rootroot00000000000000- title: "Starten" sections: - local: index title: 索引 - local: quick-start title: 快速入门指南 - local: installation title: 安装 - title: "guides" sections: - local: guides/repository title: 储存库 - local: guides/search title: 搜索 - local: guides/collections title: 集合 - local: guides/community title: 社区 - local: guides/overview title: 概览 - local: guides/hf_file_system title: Hugging Face 文件系统 huggingface_hub-1.1.5/docs/source/cn/guides/000077500000000000000000000000001510763414300207375ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/cn/guides/collections.md000066400000000000000000000224761510763414300236120ustar00rootroot00000000000000 # 集合（Collections） 集合（collection）是 Hub 上将一组相关项目（模型、数据集、Spaces、论文）组织在同一页面上的一种方式。利用集合，你可以创建自己的作品集、为特定类别的内容添加书签，或呈现你想要分享的精选条目。要了解更多关于集合的概念及其在 Hub 上的呈现方式，请查看这篇 [指南](https://huggingface.co/docs/hub/collections) 你可以直接在浏览器中管理集合，但本指南将重点介绍如何以编程方式进行管理。 ## 获取集合 使用 [`get_collection`] 来获取你的集合或任意公共集合。 你需要提供集合的 *slug* 才能检索到该集合。 slug 是基于集合标题和唯一 ID 的标识符。你可以在集合页面的 URL 中找到它。
让我们获取`"TheBloke/recent-models-64f9a55bb3115b4f513ec026"`这个集合: ```py >>> from huggingface_hub import get_collection >>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026") >>> collection Collection( slug='TheBloke/recent-models-64f9a55bb3115b4f513ec026', title='Recent models', owner='TheBloke', items=[...], last_updated=datetime.datetime(2023, 10, 2, 22, 56, 48, 632000, tzinfo=datetime.timezone.utc), position=1, private=False, theme='green', upvotes=90, description="Models I've recently quantized. Please note that currently this list has to be updated manually, and therefore is not guaranteed to be up-to-date." ) >>> collection.items[0] CollectionItem( item_object_id='651446103cd773a050bf64c2', item_id='TheBloke/U-Amethyst-20B-AWQ', item_type='model', position=88, note=None ) ``` [`get_collection`] 返回的 [`Collection`] 对象包含以下信息: - 高级元数据: `slug`, `owner`, `title`, `description`等。 - 一个 [`CollectionItem`] 对象列表; 每个条目代表一个模型、数据集、Space 或论文。 所有集合条目（items）都保证具有： - 唯一的 `item_object_id`: 这是集合条目在数据库中的唯一 ID - 一个 `item_id`: Hub 上底层条目的 ID（模型、数据集、Space、论文）；此 ID 不一定是唯一的，仅当 `item_id` 与 `item_type` 成对出现时才唯一 - 一个 `item_type`: 如`model`, `dataset`, `Space`, `paper` - 该条目在集合中的 `position`, 可通过后续操作 (参加下文的 [`update_collection_item`])来重新排序集合条目 此外，`note` 可选地附加在条目上。这对为某个条目添加额外信息（评论、博客文章链接等）很有帮助。如果条目没有备注，`note` 的值为 `None`。 除了这些基本属性之外，不同类型的条目可能会返回额外属性，如：`author`、`private`、`lastModified`、`gated`、`title`、`likes`、`upvotes` 等。这些属性不保证一定存在。 ## 列出集合 我们也可以使用 [`list_collections`]来检索集合，并通过一些参数进行过滤。让我们列出用户[`teknium`](https://huggingface.co/teknium)的所有集合： ```py >>> from huggingface_hub import list_collections >>> collections = list_collections(owner="teknium") ``` 这将返回一个 Collection 对象的可迭代序列。我们可以遍历它们，比如打印每个集合的点赞数（upvotes）： ```py >>> for collection in collections: ... print("Number of upvotes:", collection.upvotes) Number of upvotes: 1 Number of upvotes: 5 ``` > [!WARNING] > 当列出集合时，每个集合中返回的条目列表最多会被截断为 4 个。若要检索集合中的所有条目，你必须使用 [`get_collection`]. 我们可以进行更高级的过滤。例如，让我们获取所有包含模型 [TheBloke/OpenHermes-2.5-Mistral-7B-GGUF](https://huggingface.co/TheBloke/OpenHermes-2.5-Mistral-7B-GGUF) 的集合，并按照趋势（trending）进行排序，同时将结果限制为 5 个。 ```py >>> collections = list_collections(item="models/TheBloke/OpenHermes-2.5-Mistral-7B-GGUF", sort="trending", limit=5): >>> for collection in collections: ... print(collection.slug) teknium/quantized-models-6544690bb978e0b0f7328748 AmeerH/function-calling-65560a2565d7a6ef568527af PostArchitekt/7bz-65479bb8c194936469697d8c gnomealone/need-to-test-652007226c6ce4cdacf9c233 Crataco/favorite-7b-models-651944072b4fffcb41f8b568 ``` `sort` 参数必须是 `"last_modified"`、`"trending"` 或 `"upvotes"` 之一。`item` 参数接受任意特定条目，例如： * `"models/teknium/OpenHermes-2.5-Mistral-7B"` * `"spaces/julien-c/open-gpt-rhyming-robot"` * `"datasets/squad"` * `"papers/2311.12983"` 详情请查看 [`list_collections`] 的参考文档。 ## 创建新集合 现在我们已经知道如何获取一个 [`Collection`], 让我们自己创建一个吧！ 使用 [`create_collection`]，传入一个标题和描述即可。 若要在组织（organization）名下创建集合，可以通过 `namespace="my-cool-org"` 参数指定。同样，你也可以通过传入 `private=True` 创建私有集合。 ```py >>> from huggingface_hub import create_collection >>> collection = create_collection( ... title="ICCV 2023", ... description="Portfolio of models, papers and demos I presented at ICCV 2023", ... ) ``` 该函数会返回一个包含高级元数据（标题、描述、所有者等）和空条目列表的 [`Collection`] 对象。现在你可以使用返回的 `slug` 来引用该集合。 ```py >>> collection.slug 'owner/iccv-2023-15e23b46cb98efca45' >>> collection.title "ICCV 2023" >>> collection.owner "username" >>> collection.url 'https://huggingface.co/collections/owner/iccv-2023-15e23b46cb98efca45' ``` ## 管理集合中的条目 现在我们有了一个 [`Collection`]，接下来要添加条目并进行管理。 ### 添加条目 使用 [`add_collection_item`] 来向集合中添加条目（一次添加一个）。你只需要提供 `collection_slug`、`item_id` 和 `item_type`。可选参数 `note` 用于为该条目添加附加说明（最多 500 个字符）。 ```py >>> from huggingface_hub import create_collection, add_collection_item >>> collection = create_collection(title="OS Week Highlights - Sept 18 - 24", namespace="osanseviero") >>> collection.slug "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> add_collection_item(collection.slug, item_id="coqui/xtts", item_type="space") >>> add_collection_item( ... collection.slug, ... item_id="warp-ai/wuerstchen", ... item_type="model", ... note="Würstchen is a new fast and efficient high resolution text-to-image architecture and model" ... ) >>> add_collection_item(collection.slug, item_id="lmsys/lmsys-chat-1m", item_type="dataset") >>> add_collection_item(collection.slug, item_id="warp-ai/wuerstchen", item_type="space") # same item_id, different item_type ``` 如果一个条目已存在于集合中（相同的 `item_id` 和 `item_type`），将会引发 HTTP 409 错误。你可以通过设置 `exists_ok=True` 来忽略此错误。 ### 为已存在条目添加备注 你可以使用 [`update_collection_item`] 来为已存在条目添加或修改备注。让我们重用上面的示例： ```py >>> from huggingface_hub import get_collection, update_collection_item # Fetch collection with newly added items >>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> collection = get_collection(collection_slug) # Add note the `lmsys-chat-1m` dataset >>> update_collection_item( ... collection_slug=collection_slug, ... item_object_id=collection.items[2].item_object_id, ... note="This dataset contains one million real-world conversations with 25 state-of-the-art LLMs.", ... ) ``` ### 重新排序条目 集合中的条目是有序的。该顺序由每个条目的 `position` 属性决定。默认情况下，新添加的条目会被追加到集合末尾。你可以通过 [`update_collection_item`] 来更新顺序。 再次使用之前的示例： ```py >>> from huggingface_hub import get_collection, update_collection_item # Fetch collection >>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> collection = get_collection(collection_slug) # Reorder to place the two `Wuerstchen` items together >>> update_collection_item( ... collection_slug=collection_slug, ... item_object_id=collection.items[3].item_object_id, ... position=2, ... ) ``` ### 删除条目 最后，你也可以使用 [`delete_collection_item`] 来删除集合中的条目。 ```py >>> from huggingface_hub import get_collection, update_collection_item # Fetch collection >>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> collection = get_collection(collection_slug) # Remove `coqui/xtts` Space from the list >>> delete_collection_item(collection_slug=collection_slug, item_object_id=collection.items[0].item_object_id) ``` ## 删除集合 可以使用 [`delete_collection`] 来删除集合。 > [!WARNING] > 此操作不可逆。删除的集合无法恢复。 ```py >>> from huggingface_hub import delete_collection >>> collection = delete_collection("username/useless-collection-64f9a55bb3115b4f513ec026", missing_ok=True) ``` huggingface_hub-1.1.5/docs/source/cn/guides/community.md000066400000000000000000000134301510763414300233060ustar00rootroot00000000000000 # 互动讨论与拉取请求（Pull Request） huggingface_hub 库提供了一个 Python 接口，用于与 Hub 上的拉取请求（Pull Request）和讨论互动。 访问 [相关的文档页面](https://huggingface.co/docs/hub/repositories-pull-requests-discussions) ，了解有关 Hub 上讨论和拉取请求（Pull Request）的更深入的介绍及其工作原理。 ## 从 Hub 获取讨论和拉取请求（Pull Request） `HfApi` 类允许您获取给定仓库中的讨论和拉取请求（Pull Request）： ```python >>> from huggingface_hub import get_repo_discussions >>> for discussion in get_repo_discussions(repo_id="bigscience/bloom"): ... print(f"{discussion.num} - {discussion.title}, pr: {discussion.is_pull_request}") # 11 - Add Flax weights, pr: True # 10 - Update README.md, pr: True # 9 - Training languages in the model card, pr: True # 8 - Update tokenizer_config.json, pr: True # 7 - Slurm training script, pr: False [...] ``` `HfApi.get_repo_discussions` 支持按作者、类型（拉取请求或讨论）和状态（`open` 或 `closed`）进行过滤： ```python >>> from huggingface_hub import get_repo_discussions >>> for discussion in get_repo_discussions( ... repo_id="bigscience/bloom", ... author="ArthurZ", ... discussion_type="pull_request", ... discussion_status="open", ... ): ... print(f"{discussion.num} - {discussion.title} by {discussion.author}, pr: {discussion.is_pull_request}") # 19 - Add Flax weights by ArthurZ, pr: True ``` `HfApi.get_repo_discussions` 返回一个 [生成器](https://docs.python.org/3.7/howto/functional.html#generators) 生成 [`Discussion`] 对象。 要获取所有讨论并存储为列表，可以运行： ```python >>> from huggingface_hub import get_repo_discussions >>> discussions_list = list(get_repo_discussions(repo_id="bert-base-uncased")) ``` [`HfApi.get_repo_discussions`] 返回的 [`Discussion`] 对象提供讨论或拉取请求（Pull Request）的高级概览。您还可以使用 [`HfApi.get_discussion_details`] 获取更详细的信息： ```python >>> from huggingface_hub import get_discussion_details >>> get_discussion_details( ... repo_id="bigscience/bloom-1b3", ... discussion_num=2 ... ) DiscussionWithDetails( num=2, author='cakiki', title='Update VRAM memory for the V100s', status='open', is_pull_request=True, events=[ DiscussionComment(type='comment', author='cakiki', ...), DiscussionCommit(type='commit', author='cakiki', summary='Update VRAM memory for the V100s', oid='1256f9d9a33fa8887e1c1bf0e09b4713da96773a', ...), ], conflicting_files=[], target_branch='refs/heads/main', merge_commit_oid=None, diff='diff --git a/README.md b/README.md\nindex a6ae3b9294edf8d0eda0d67c7780a10241242a7e..3a1814f212bc3f0d3cc8f74bdbd316de4ae7b9e3 100644\n--- a/README.md\n+++ b/README.md\n@@ -132,7 +132,7 [...]', ) ``` [`HfApi.get_discussion_details`] 返回一个 [`DiscussionWithDetails`] 对象，它是 [`Discussion`] 的子类，包含有关讨论或拉取请求（Pull Request）的更详细信息。详细信息包括所有评论、状态更改以及讨论的重命名信息，可通过 [`DiscussionWithDetails.events`] 获取。 如果是拉取请求（Pull Request），您可以通过 [`DiscussionWithDetails.diff`] 获取原始的 git diff。拉取请求（Pull Request）的所有提交都列在 [`DiscussionWithDetails.events`] 中。 ## 以编程方式创建和编辑讨论或拉取请求 [`HfApi`] 类还提供了创建和编辑讨论及拉取请求（Pull Request）的方法。 您需要一个 [访问令牌](https://huggingface.co/docs/hub/security-tokens) 来创建和编辑讨论或拉取请求（Pull Request）。 在 Hub 上对 repo 提出修改建议的最简单方法是使用 [`create_commit`] API：只需将 `create_pr` 参数设置为 `True` 。此参数也适用于其他封装了 [`create_commit`] 的方法： * [`upload_file`] * [`upload_folder`] * [`delete_file`] * [`delete_folder`] * [`metadata_update`] ```python >>> from huggingface_hub import metadata_update >>> metadata_update( ... repo_id="username/repo_name", ... metadata={"tags": ["computer-vision", "awesome-model"]}, ... create_pr=True, ... ) ``` 您还可以使用 [`HfApi.create_discussion`]（或 [`HfApi.create_pull_request`]）在仓库上创建讨论（或拉取请求）。以这种方式打开拉取请求在您需要本地处理更改时很有用。以这种方式打开的拉取请求将处于“draft”模式。 ```python >>> from huggingface_hub import create_discussion, create_pull_request >>> create_discussion( ... repo_id="username/repo-name", ... title="Hi from the huggingface_hub library!", ... token="", ... ) DiscussionWithDetails(...) >>> create_pull_request( ... repo_id="username/repo-name", ... title="Hi from the huggingface_hub library!", ... token="", ... ) DiscussionWithDetails(..., is_pull_request=True) ``` 您可以使用 [`HfApi`] 类来方便地管理拉取请求和讨论。例如： * [`comment_discussion`] 添加评论 * [`edit_discussion_comment`] 编辑评论 * [`rename_discussion`] 重命名讨论或拉取请求 * [`change_discussion_status`] 打开或关闭讨论/拉取请求 * [`merge_pull_request`] 合并拉取请求 请访问 [`HfApi`] 文档页面，获取所有可用方法的完整参考 ## 推送更改到拉取请求（Pull Request） *敬请期待！* ## 参见 有关更详细的参考，请访问 [讨论和拉取请求](../package_reference/community) 和 [hf_api](../package_reference/hf_api) 文档页面。 huggingface_hub-1.1.5/docs/source/cn/guides/hf_file_system.md000066400000000000000000000121141510763414300242600ustar00rootroot00000000000000 # 通过文件系统 API 与 Hub 交互 除了 [`HfApi`]，`huggingface_hub` 库还提供了 [`HfFileSystem`]，这是一个符合 [fsspec](https://filesystem-spec.readthedocs.io/en/latest/) 规范的 Python 文件接口，用于与 Hugging Face Hub 交互。[`HfFileSystem`] 基于 [`HfApi`] 构建，提供了典型的文件系统操作，如 `cp`、`mv`、`ls`、`du`、`glob`、`get_file` 和 `put_file`。 > [!WARNING] > [`HfFileSystem`] 提供了 fsspec 兼容性，这对于需要它的库（例如，直接使用 `pandas` 读取 Hugging Face 数据集）非常有用。然而，由于这种兼容性层，会引入额外的开销。为了更好的性能和可靠性，建议尽可能使用 [`HfApi`] 方法。 ## 使用方法 ```python >>> from huggingface_hub import HfFileSystem >>> fs = HfFileSystem() >>> # 列出目录中的所有文件 >>> fs.ls("datasets/my-username/my-dataset-repo/data", detail=False) ['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv'] >>> # 列出仓库中的所有 ".csv" 文件 >>> fs.glob("datasets/my-username/my-dataset-repo/**/*.csv") ['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv'] >>> # 读取远程文件 >>> with fs.open("datasets/my-username/my-dataset-repo/data/train.csv", "r") as f: ... train_data = f.readlines() >>> # 远程文件内容读取为字符串 >>> train_data = fs.read_text("datasets/my-username/my-dataset-repo/data/train.csv", revision="dev") >>> # 写入远程文件 >>> with fs.open("datasets/my-username/my-dataset-repo/data/validation.csv", "w") as f: ... f.write("text,label") ... f.write("Fantastic movie!,good") ``` 可以传递可选的 `revision` 参数，以从特定提交（如分支、标签名或提交哈希）运行操作。 与 Python 内置的 `open` 不同，`fsspec` 的 `open` 默认是二进制模式 `"rb"`。这意味着您必须明确设置模式为 `"r"` 以读取文本模式，或 `"w"` 以写入文本模式。目前不支持追加到文件（模式 `"a"` 和 `"ab"`） ## 集成 [`HfFileSystem`] 可以与任何集成了 `fsspec` 的库一起使用，前提是 URL 遵循以下格式： ``` hf://[][@]/ ```
对于数据集，`repo_type_prefix` 为 `datasets/`，对于Space，`repo_type_prefix`为 `spaces/`，模型不需要在 URL 中使用这样的前缀。 以下是一些 [`HfFileSystem`] 简化与 Hub 交互的有趣集成： * 从 Hub 仓库读取/写入 [Pandas](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#reading-writing-remote-files) DataFrame ： ```python >>> import pandas as pd >>> # 将远程 CSV 文件读取到 DataFrame >>> df = pd.read_csv("hf://datasets/my-username/my-dataset-repo/train.csv") >>> # 将 DataFrame 写入远程 CSV 文件 >>> df.to_csv("hf://datasets/my-username/my-dataset-repo/test.csv") ``` 同样的工作流程也适用于 [Dask](https://docs.dask.org/en/stable/how-to/connect-to-remote-data.html) 和 [Polars](https://pola-rs.github.io/polars/py-polars/html/reference/io.html) DataFrames. * 使用 [DuckDB](https://duckdb.org/docs/guides/python/filesystems) 查询(远程)Hub文件： ```python >>> from huggingface_hub import HfFileSystem >>> import duckdb >>> fs = HfFileSystem() >>> duckdb.register_filesystem(fs) >>> # 查询远程文件并将结果返回为 DataFrame >>> fs_query_file = "hf://datasets/my-username/my-dataset-repo/data_dir/data.parquet" >>> df = duckdb.query(f"SELECT * FROM '{fs_query_file}' LIMIT 10").df() ``` * 使用 [Zarr](https://zarr.readthedocs.io/en/stable/tutorial.html#io-with-fsspec) 将 Hub 作为数组存储： ```python >>> import numpy as np >>> import zarr >>> embeddings = np.random.randn(50000, 1000).astype("float32") >>> # 将数组写入仓库 >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="w") as root: ... foo = root.create_group("embeddings") ... foobar = foo.zeros('experiment_0', shape=(50000, 1000), chunks=(10000, 1000), dtype='f4') ... foobar[:] = embeddings >>> # 从仓库读取数组 >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="r") as root: ... first_row = root["embeddings/experiment_0"][0] ``` ## 认证 在许多情况下，您必须登录 Hugging Face 账户才能与 Hub 交互。请参阅文档的[认证](../quick-start#authentication) 部分，了解有关 Hub 上认证方法的更多信息。 也可以通过将您的 token 作为参数传递给 [`HfFileSystem`] 以编程方式登录： ```python >>> from huggingface_hub import HfFileSystem >>> fs = HfFileSystem(token=token) ``` 如果您以这种方式登录，请注意在共享源代码时不要意外泄露令牌！ huggingface_hub-1.1.5/docs/source/cn/guides/overview.md000066400000000000000000000136261510763414300231370ustar00rootroot00000000000000 # 操作指南 在本节中，您将找到帮助您实现特定目标的实用指南。 查看这些指南，了解如何使用 huggingface_hub 解决实际问题：
仓库

如何在 Hub 上创建仓库？如何配置它？如何与之交互？

下载文件

如何从 Hub 下载文件？如何下载仓库？

上传文件

如何上传文件或文件夹？如何对 Hub 上的现有仓库进行更改？

搜索

如何高效地搜索超过 200k+ 个公共模型、数据集和Space？

HfFileSystem

如何通过一个模仿 Python 文件接口的便捷接口与 Hub 交互？

推理

如何使用加速推理 API 进行预测？

社区

如何与社区（讨论和拉取请求）互动？

集合

如何以编程方式构建集合？

缓存

缓存系统如何工作？如何从中受益？

模型卡片

如何创建和分享模型卡片？

管理您的Space

如何管理您的Space的硬件和配置？

集成库

将库集成到 Hub 中意味着什么？如何实现？

Webhooks 服务器

如何创建一个接收 Webhooks 的服务器并将其部署为一个Space？

huggingface_hub-1.1.5/docs/source/cn/guides/repository.md000066400000000000000000000156061510763414300235100ustar00rootroot00000000000000 # 创建和管理存储库 Hugging Face Hub是一组 Git 存储库。[Git](https://git-scm.com/)是软件开发中广泛使用的工具，可以在协作工作时轻松对项目进行版本控制。本指南将向您展示如何与 Hub 上的存储库进行交互，特别关注以下内容： - 创建和删除存储库 - 管理分支和标签 - 重命名您的存储库 - 更新您的存储库可见性 - 管理存储库的本地副本 > [!WARNING] > 如果您习惯于使用类似于GitLab/GitHub/Bitbucket等平台，您可能首先想到使用 `git`命令行工具来克隆存储库（`git clone`）、提交更改（`git add` , ` git commit`）并推送它们（`git push`）。在使用 Hugging Face Hub 时，这是有效的。然而，软件工程和机器学习并不具有相同的要求和工作流程。模型存储库可能会维护大量模型权重文件以适应不同的框架和工具，因此克隆存储库会导致您维护大量占用空间的本地文件夹。因此，使用我们的自定义HTTP方法可能更有效。您可以阅读我们的[git与HTTP相比较](../concepts/git_vs_http)解释页面以获取更多详细信息 如果你想在Hub上创建和管理一个仓库，你的计算机必须处于登录状态。如果尚未登录，请参考[此部分](../quick-start#login)。在本指南的其余部分，我们将假设你的计算机已登录 ## 仓库创建和删除 第一步是了解如何创建和删除仓库。你只能管理你拥有的仓库（在你的用户名命名空间下）或者你具有写入权限的组织中的仓库 ### 创建一个仓库 使用 [`create_repo`] 创建一个空仓库，并通过 `repo_id`参数为其命名 `repo_id`是你的命名空间，后面跟着仓库名称：`username_or_org/repo_name` 运行以下代码，以创建仓库： ```py >>> from huggingface_hub import create_repo >>> create_repo("lysandre/test-model") 'https://huggingface.co/lysandre/test-model' ``` 默认情况下，[`create_repo`] 会创建一个模型仓库。但是你可以使用 `repo_type`参数来指定其他仓库类型。例如，如果你想创建一个数据集仓库 请运行以下代码： ```py >>> from huggingface_hub import create_repo >>> create_repo("lysandre/test-dataset", repo_type="dataset") 'https://huggingface.co/datasets/lysandre/test-dataset' ``` 创建仓库时，你可以使用 `private`参数设置仓库的可见性 请运行以下代码 ```py >>> from huggingface_hub import create_repo >>> create_repo("lysandre/test-private", private=True) ``` 如果你想在以后更改仓库的可见性，你可以使用[`update_repo_settings`] 函数 ### 删除一个仓库 使用 [`delete_repo`] 删除一个仓库。确保你确实想要删除仓库，因为这是一个不可逆转的过程！做完上述过程后，指定你想要删除的仓库的 `repo_id` 请运行以下代码： ```py >>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset") ``` ### 克隆一个仓库（仅适用于 Spaces） 在某些情况下，你可能想要复制别人的仓库并根据自己的用例进行调整。对于 Spaces，你可以使用 [`duplicate_space`] 方法来实现。它将复制整个仓库。 你仍然需要配置自己的设置（硬件和密钥）。查看我们的[管理你的Space指南](./manage-spaces)以获取更多详细信息。 请运行以下代码： ```py >>> from huggingface_hub import duplicate_space >>> duplicate_space("multimodalart/dreambooth-training", private=False) RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...) ``` ## 上传和下载文件 既然您已经创建了您的存储库，您现在也可以推送更改至其中并从中下载文件 这两个主题有它们自己的指南。请[上传指南](./upload) 和[下载指南](./download)来学习如何使用您的存储库。 ## 分支和标签 Git存储库通常使用分支来存储同一存储库的不同版本。标签也可以用于标记存储库的特定状态，例如，在发布版本这个情况下。更一般地说，分支和标签被称为[git引用](https://git-scm.com/book/en/v2/Git-Internals-Git-References). ### 创建分支和标签 你可以使用[`create_branch`]和[`create_tag`]来创建新的分支和标签: 请运行以下代码： ```py >>> from huggingface_hub import create_branch, create_tag # Create a branch on a Space repo from `main` branch >>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker") # Create a tag on a Dataset repo from `v0.1-release` branch >>> create_branch("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.") ``` 同时,你可以以相同的方式使用 [`delete_branch`] 和 [`delete_tag`] 函数来删除分支或标签 ### 列出所有的分支和标签 你还可以使用 [`list_repo_refs`] 列出存储库中的现有 Git 引用 请运行以下代码： ```py >>> from huggingface_hub import list_repo_refs >>> api.list_repo_refs("bigcode/the-stack", repo_type="dataset") GitRefs( branches=[ GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'), GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714') ], converts=[], tags=[ GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da') ] ) ``` ## 修改存储库设置 存储库具有一些可配置的设置。大多数情况下，您通常会在浏览器中的存储库设置页面上手动配置这些设置。要配置存储库，您必须具有对其的写访问权限（拥有它或属于组织）。在本节中，我们将看到您还可以使用 `huggingface_hub` 在编程方式上配置的设置。 一些设置是特定于 Spaces（硬件、环境变量等）的。要配置这些设置，请参考我们的[管理Spaces](../guides/manage-spaces)指南。 ### 更新可见性 一个存储库可以是公共的或私有的。私有存储库仅对您或存储库所在组织的成员可见。 请运行以下代码将存储库更改为私有： ```py >>> from huggingface_hub import update_repo_settings >>> update_repo_settings(repo_id=repo_id, private=True) ``` ### 重命名您的存储库 您可以使用 [`move_repo`] 在 Hub 上重命名您的存储库。使用这种方法，您还可以将存储库从一个用户移动到一个组织。在这样做时，有一些[限制](https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo)需要注意。例如，您不能将存储库转移到另一个用户。 请运行以下代码： ```py >>> from huggingface_hub import move_repo >>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model") ``` huggingface_hub-1.1.5/docs/source/cn/guides/search.md000066400000000000000000000037141510763414300225330ustar00rootroot00000000000000 # 搜索 Hub 在本教程中，您将学习如何使用 `huggingface_hub` 在 Hub 上搜索模型、数据集和Spaces。 ## 如何列出仓库？ `huggingface_hub`库包括一个 HTTP 客户端 [`HfApi`]，用于与 Hub 交互。 除此之外，它还可以列出存储在 Hub 上的模型、数据集和Spaces： ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> models = api.list_models() ``` [`list_models`] 返回一个迭代器，包含存储在 Hub 上的模型。 同样，您可以使用 [`list_datasets`] 列出数据集，使用 [`list_spaces`] 列出 Spaces。 ## 如何过滤仓库？ 列出仓库是一个好开始，但现在您可能希望对搜索结果进行过滤。 列出时，可以使用多个属性来过滤结果，例如： - `filter` - `author` - `search` - ... 让我们看一个示例，获取所有在 Hub 上进行图像分类的模型，这些模型已在 imagenet 数据集上训练，并使用 PyTorch 运行。 ```py models = hf_api.list_models( task="image-classification", library="pytorch", trained_dataset="imagenet", ) ``` 在过滤时，您还可以对模型进行排序，并仅获取前几个结果。例如，以下示例获取了 Hub 上下载量最多的前 5 个数据集： ```py >>> list(list_datasets(sort="downloads", direction=-1, limit=5)) [DatasetInfo( id='argilla/databricks-dolly-15k-curated-en', author='argilla', sha='4dcd1dedbe148307a833c931b21ca456a1fc4281', last_modified=datetime.datetime(2023, 10, 2, 12, 32, 53, tzinfo=datetime.timezone.utc), private=False, downloads=8889377, (...) ``` 如果您想要在Hub上探索可用的过滤器, 请在浏览器中访问 [models](https://huggingface.co/models) 和 [datasets](https://huggingface.co/datasets) 页面 ，尝试不同的参数并查看URL中的值。 huggingface_hub-1.1.5/docs/source/cn/index.md000066400000000000000000000075111510763414300211140ustar00rootroot00000000000000 # 🤗 Hub 客户端库 通过`huggingface_hub` 库，您可以与面向机器学习开发者和协作者的平台 [Hugging Face Hub](https://huggingface.co/)进行交互，找到适用于您所在项目的预训练模型和数据集，体验在平台托管的数百个机器学习应用，还可以创建或分享自己的模型和数据集并于社区共享。以上所有都可以用Python在`huggingface_hub` 库中轻松实现。 阅读[快速入门指南](快速入门指南)以开始使用huggingface_hub库。您将学习如何从Hub下载文件,创建存储库以及将文件上传到Hub。继续阅读以了解更多关于如何在🤗Hub上管理您的存储库,如何参与讨论或者甚至如何访问推理API的信息。
操作指南

实用指南可帮助您实现特定目标。查看这些指南，了解如何使用 huggingface_hub 解决实际问题。
参考

huggingface_hub 类和方法的详尽技术描述。
概念指南

更好地理解 huggingface_hub 哲学的高级概念。
通过 `huggingface_hub`库，您可以与面向机器学习开发者和协作者的平台 [Hugging Face Hub](https://huggingface.co/)进行交互，找到适用于您所在项目的预训练模型和数据集，体验在平台托管的数百个机器学习应用，还可以创建或分享自己的模型和数据集并于社区共享。以上所有都可以用Python在 `huggingface_hub`库中轻松实现。 ## 贡献 所有对 huggingface_hub 的贡献都受到欢迎和同等重视！🤗 除了在代码中添加或修复现有问题外，您还可以通过确保其准确且最新来帮助改进文档，在问题上帮助回答问题，并请求您认为可以改进库的新功能。请查看[贡献指南](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) 了解有关如何提交新问题或功能请求、如何提交拉取请求以及如何测试您的贡献以确保一切正常运行的更多信息。 当然，贡献者也应该尊重我们的[行为准则](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md)，以便为每个人创建一个包容和欢迎的协作空间。 huggingface_hub-1.1.5/docs/source/cn/installation.md000066400000000000000000000147561510763414300225170ustar00rootroot00000000000000 # 安装 在开始之前，您需要通过安装适当的软件包来设置您的环境 huggingface_hub 在 Python 3.9 或更高版本上进行了测试，可以保证在这些版本上正常运行。如果您使用的是 Python 3.7 或更低版本，可能会出现兼容性问题 ## 使用 pip 安装 我们建议将huggingface_hub安装在[虚拟环境](https://docs.python.org/3/library/venv.html)中. 如果你不熟悉 Python虚拟环境,可以看看这个[指南](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). 虚拟环境可以更容易地管理不同的项目,避免依赖项之间的兼容性问题 首先在你的项目目录中创建一个虚拟环境,请运行以下代码: ```bash python -m venv .env ``` 在Linux和macOS上,请运行以下代码激活虚拟环境: ```bash source .env/bin/activate ``` 在 Windows 上，请运行以下代码激活虚拟环境: ```bash .env/Scripts/activate ``` 现在您可以从[PyPi注册表](https://pypi.org/project/huggingface-hub/)安装 `huggingface_hub`： ```bash pip install --upgrade huggingface_hub ``` 完成后,[检查安装](#check-installation)是否正常工作 ### 安装可选依赖项 `huggingface_hub`的某些依赖项是 [可选](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies) 的，因为它们不是运行`huggingface_hub`的核心功能所必需的.但是，如果没有安装可选依赖项， `huggingface_hub` 的某些功能可能会无法使用 您可以通过`pip`安装可选依赖项,请运行以下代码： ```bash # 安装 Torch 特定功能和 CLI 特定功能的依赖项 pip install 'huggingface_hub[cli,torch]' ``` 这里列出了 `huggingface_hub` 的可选依赖项： - `cli`：为 `huggingface_hub` 提供更方便的命令行界面 - `fastai`,` torch`: 运行框架特定功能所需的依赖项 - `dev`：用于为库做贡献的依赖项。包括 `testing`（用于运行测试）、`typing`（用于运行类型检查器）和 `quality`（用于运行 linter） ### 从源代码安装 在某些情况下，直接从源代码安装`huggingface_hub`会更有趣。因为您可以使用最新的主版本`main`而非最新的稳定版本 `main`版本更有利于跟进平台的最新开发进度，例如，在最近一次官方发布之后和最新的官方发布之前所修复的某个错误 但是，这意味着`main`版本可能不总是稳定的。我们会尽力让其正常运行，大多数问题通常会在几小时或一天内解决。如果您遇到问题，请创建一个 Issue ，以便我们可以更快地解决！ ```bash pip install git+https://github.com/huggingface/huggingface_hub # 使用pip从GitHub仓库安装Hugging Face Hub库 ``` 从源代码安装时，您还可以指定特定的分支。如果您想测试尚未合并的新功能或新错误修复，这很有用 ```bash pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch # 使用pip从指定的GitHub分支（my-feature-branch）安装Hugging Face Hub库 ``` 完成安装后，请[检查安装](#check-installation)是否正常工作 ### 可编辑安装 从源代码安装允许您设置[可编辑安装](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs).如果您计划为`huggingface_hub`做出贡献并需要测试代码更改，这是一个更高级的安装方式。您需要在本机上克隆一个`huggingface_hub`的本地副本 ```bash # 第一，使用以下命令克隆代码库 git clone https://github.com/huggingface/huggingface_hub.git # 然后，使用以下命令启动虚拟环境 cd huggingface_hub pip install -e . ``` 这些命令将你克隆存储库的文件夹与你的 Python 库路径链接起来。Python 现在将除了正常的库路径之外，还会在你克隆到的文件夹中查找。例如，如果你的 Python 包通常安装在`./.venv/lib/python3.13/site-packages/`中，Python 还会搜索你克隆的文件夹`./huggingface_hub/` ## 通过 conda 安装 如果你更熟悉它，你可以使用[conda-forge channel](https://anaconda.org/conda-forge/huggingface_hub)渠道来安装 `huggingface_hub` 请运行以下代码： ```bash conda install -c conda-forge huggingface_hub ``` 完成安装后，请[检查安装](#check-installation)是否正常工作 ## 验证安装 安装完成后，通过运行以下命令检查`huggingface_hub`是否正常工作: ```bash python -c "from huggingface_hub import model_info; print(model_info('gpt2'))" ``` 这个命令将从 Hub 获取有关 [gpt2](https://huggingface.co/gpt2) 模型的信息。 输出应如下所示： ```text Model Name: gpt2 模型名称 Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space'] 标签 Task: text-generation 任务：文本生成 ``` ## Windows局限性 为了实现让每个人都能使用机器学习的目标，我们构建了 `huggingface_hub`库，使其成为一个跨平台的库，尤其可以在 Unix 和 Windows 系统上正常工作。但是，在某些情况下，`huggingface_hub`在Windows上运行时会有一些限制。以下是一些已知问题的完整列表。如果您遇到任何未记录的问题，请打开 [Github上的issue](https://github.com/huggingface/huggingface_hub/issues/new/choose).让我们知道 - `huggingface_hub`的缓存系统依赖于符号链接来高效地缓存从Hub下载的文件。在Windows上，您必须激活开发者模式或以管理员身份运行您的脚本才能启用符号链接。如果它们没有被激活，缓存系统仍然可以工作，但效率较低。有关更多详细信息，请阅读[缓存限制](./guides/manage-cache#limitations)部分。 - Hub上的文件路径可能包含特殊字符（例如:`path/to?/my/file`）。Windows对[特殊字符](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names)更加严格，这使得在Windows上下载这些文件变得不可能。希望这是罕见的情况。如果您认为这是一个错误，请联系存储库所有者或我们，以找出解决方案。 ## 后记 一旦您在机器上正确安装了`huggingface_hub`，您可能需要[配置环境变量](package_reference/environment_variables)或者[查看我们的指南之一](guides/overview)以开始使用。 huggingface_hub-1.1.5/docs/source/cn/quick-start.md000066400000000000000000000130431510763414300222510ustar00rootroot00000000000000 # 快速入门 [Hugging Face Hub](https://huggingface.co/)是分享机器学习模型、演示、数据集和指标的首选平台`huggingface_hub`库帮助你在不离开开发环境的情况下与 Hub 进行交互。你可以轻松地创建和管理仓库,下载和上传文件,并从 Hub 获取有用的模型和数据集元数据 ## 安装 要开始使用,请安装`huggingface_hub`库: ```bash pip install --upgrade huggingface_hub ``` 更多详细信息,请查看[安装指南](installation) ## 下载文件 Hugging Face 平台上的存储库是使用 git 版本控制的，用户可以下载单个文件或整个存储库。您可以使用 [`hf_hub_download`] 函数下载文件。该函数将下载并将文件缓存在您的本地磁盘上。下次您需要该文件时，它将从您的缓存中加载，因此您无需重新下载它 您将需要填写存储库 ID 和您要下载的文件的文件名。例如，要下载[Pegasus](https://huggingface.co/google/pegasus-xsum)模型配置文件，请运行以下代码： ```py >>> from huggingface_hub import hf_hub_download >>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json") repo_id: 仓库的 ID 或路径，这里使用了 "google/pegasus-xsum" filename: 要下载的文件名，这里是 "config.json" ``` 要下载文件的特定版本，请使用`revision`参数指定分支名称、标签或提交哈希。如果您选择使用提交哈希，它必须是完整长度的哈希，而不是较短的7个字符的提交哈希： ```py >>> from huggingface_hub import hf_hub_download >>> hf_hub_download( ... repo_id="google/pegasus-xsum", ... filename="config.json", ... revision="4d33b01d79672f27f001f6abade33f22d993b151" ... ) ``` 有关更多详细信息和选项，请参阅 [`hf_hub_download`] 的 API 参考文档 ## 登录 在许多情况下，您必须使用 Hugging Face 帐户进行登录后才能与 Hugging Face 模型库进行交互，例如下载私有存储库、上传文件、创建 PR 等。如果您还没有帐户，请[创建一个](https://huggingface.co/join),然后登录以获取您的 [用户访问令牌](https://huggingface.co/docs/hub/security-tokens),security-tokens从您的[设置页面](https://huggingface.co/settings/tokens)进入设置,用户访问令牌用于向模型库进行身份验证 运行以下代码，这将使用您的用户访问令牌登录到Hugging Face模型库 ```bash hf auth login hf auth login --token $HUGGINGFACE_TOKEN ``` 或者，你可以在笔记本电脑或脚本中使用 [`login`] 来进行程序化登录,请运行以下代码: ```py >>> from huggingface_hub import login >>> login() ``` 您还可以直接将令牌传递给 [`login`]，如下所示：`login(token="hf_xxx")`。这将使用您的用户访问令牌登录到 Hugging Face 模型库，而无需您输入任何内容。但是，如果您这样做，请在共享源代码时要小心。最好从安全保管库中加载令牌，而不是在代码库/笔记本中显式保存它 您一次只能登录一个帐户。如果您使用另一个帐户登录您的机器，您将会从之前的帐户注销。请确保使用命令 `hf auth whoami`来检查您当前使用的是哪个帐户。如果您想在同一个脚本中处理多个帐户，您可以在调用每个方法时提供您的令牌。这对于您不想在您的机器上存储任何令牌也很有用 > [!WARNING] > 一旦您登录了，所有对模型库的请求（即使是不需要认证的方法）都将默认使用您的访问令牌。如果您想禁用对令牌的隐式使用，您应该设置`HF_HUB_DISABLE_IMPLICIT_TOKEN`环境变量 ## 创建存储库 一旦您注册并登录，请使用 [`create_repo`] 函数创建存储库： ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.create_repo(repo_id="super-cool-model") ``` 如果您想将存储库设置为私有，请按照以下步骤操作： ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.create_repo(repo_id="super-cool-model", private=True) ``` 私有存储库将不会对任何人可见，除了您自己 > [!TIP] > 创建存储库或将内容推送到 Hub 时，必须提供具有`写入`权限的用户访问令牌。您可以在创建令牌时在您的[设置页面](https://huggingface.co/settings/tokens)中选择权限 ## 上传文件 您可以使用 [`upload_file`] 函数将文件添加到您新创建的存储库。您需要指定： 1. 要上传的文件的路径 2. 文件在存储库中的位置 3. 您要将文件添加到的存储库的 ID ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.upload_file( ... path_or_fileobj="/home/lysandre/dummy-test/README.md" ... path_in_repo="README.md" ... repo_id="lysandre/test-model" ... ) ``` 要一次上传多个文件，请查看[上传指南](./guides/upload) ,该指南将向您介绍几种上传文件的方法（有或没有 git）。 ## 下一步 `huggingface_hub`库为用户提供了一种使用Python与Hub 进行交互的简单方法。要了解有关如何在Hub上管理文件和存储库的更多信息，我们建议您阅读我们的[操作方法指南](./guides/overview)： - [管理您的存储库](./guides/repository) - [从Hub下载文件](./guides/download) - [将文件上传到Hub](./guides/upload) - [在Hub中搜索您的所需模型或数据集](./guides/search) - [了解如何使用 Inference API 进行快速推理](./guides/inference) huggingface_hub-1.1.5/docs/source/de/000077500000000000000000000000001510763414300174475ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/de/_toctree.yml000066400000000000000000000017141510763414300220010ustar00rootroot00000000000000- title: "Starten" sections: - local: index title: Home - local: quick-start title: Kurzanleitung - local: installation title: Installation - title: "Anleitungen" sections: - local: guides/overview title: Übersicht - local: guides/download title: Dateien herunterladen - local: guides/upload title: Dateien hochladen - local: guides/hf_file_system title: HfFileSystem - local: guides/repository title: Repository - local: guides/search title: Suche - local: guides/inference title: Inferenz - local: guides/community title: Community-Tab - local: guides/manage-cache title: Cache - local: guides/model-cards title: Model Cards - local: guides/manage-spaces title: Verwalten Ihres Spaces - local: guides/integrations title: Integrieren einer Bibliothek - local: guides/webhooks_server title: Webhooks server huggingface_hub-1.1.5/docs/source/de/guides/000077500000000000000000000000001510763414300207275ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/de/guides/community.md000066400000000000000000000135041510763414300233000ustar00rootroot00000000000000 # Interaktion mit Diskussionen und Pull-Requests Die `huggingface_hub`-Bibliothek bietet eine Python-Schnittstelle, um mit Pull-Requests und Diskussionen auf dem Hub zu interagieren. Besuchen Sie [die spezielle Dokumentationsseite](https://huggingface.co/docs/hub/repositories-pull-requests-discussions), um einen tieferen Einblick in Diskussionen und Pull-Requests auf dem Hub zu erhalten und zu erfahren, wie sie im Hintergrund funktionieren. ## Diskussionen und Pull-Requests vom Hub abrufen Die Klasse `HfApi` ermöglicht es Ihnen, Diskussionen und Pull-Requests zu einem gegebenen Repository abzurufen: ```python >>> from huggingface_hub import get_repo_discussions >>> for discussion in get_repo_discussions(repo_id="bigscience/bloom-1b3"): ... print(f"{discussion.num} - {discussion.title}, pr: {discussion.is_pull_request}") # 11 - Add Flax weights, pr: True # 10 - Update README.md, pr: True # 9 - Training languages in the model card, pr: True # 8 - Update tokenizer_config.json, pr: True # 7 - Slurm training script, pr: False [...] ``` `HfApi.get_repo_discussions` gibt einen [Generator](https://docs.python.org/3.7/howto/functional.html#generators) zurück, der [`Diskussion`]-Objekte liefert. Um alle Diskussionen in einer einzelnen Liste zu erhalten, führen Sie den folgenden Befehl aus: ```python >>> from huggingface_hub import get_repo_discussions >>> discussions_list = list(get_repo_discussions(repo_id="bert-base-uncased")) ``` Das von [`HfApi.get_repo_discussions`] zurückgegebene [`Diskussion`]-Objekt enthält einen Überblick über die Diskussion oder Pull-Requests. Sie können auch detailliertere Informationen mit [`HfApi.get_discussion_details`] abrufen: ```python >>> from huggingface_hub import get_discussion_details >>> get_discussion_details( ... repo_id="bigscience/bloom-1b3", ... discussion_num=2 ... ) DiscussionWithDetails( num=2, author='cakiki', title='Update VRAM memory for the V100s', status='open', is_pull_request=True, events=[ DiscussionComment(type='comment', author='cakiki', ...), DiscussionCommit(type='commit', author='cakiki', summary='Update VRAM memory for the V100s', oid='1256f9d9a33fa8887e1c1bf0e09b4713da96773a', ...), ], conflicting_files=[], target_branch='refs/heads/main', merge_commit_oid=None, diff='diff --git a/README.md b/README.md\nindex a6ae3b9294edf8d0eda0d67c7780a10241242a7e..3a1814f212bc3f0d3cc8f74bdbd316de4ae7b9e3 100644\n--- a/README.md\n+++ b/README.md\n@@ -132,7 +132,7 [...]', ) ``` [`HfApi.get_discussion_details`] gibt ein [`DiskussionMitDetails`]-Objekt zurück, das eine Unterklasse von [`Diskussion`] mit detaillierteren Informationen über die Diskussion oder Pull-Requests ist. Informationen beinhalten alle Kommentare, Statusänderungen und Umbenennungen der Diskussion mittels [`DiskussionMitDetails.events`]. Im Fall eines Pull-Requests können Sie mit [`DiskussionMitDetails.diff`] den rohen git diff abrufen. Alle Commits des Pull-Requests sind in [`DiskussionMitDetails.events`] aufgelistet. ## Diskussion oder Pull-Request programmatisch erstellen und bearbeiten Die [`HfApi`]-Klasse bietet auch Möglichkeiten, Diskussionen und Pull-Requests zu erstellen und zu bearbeiten. Sie benötigen ein [Access Token](https://huggingface.co/docs/hub/security-tokens), um Diskussionen oder Pull-Requests zu erstellen und zu bearbeiten. Die einfachste Möglichkeit, Änderungen an einem Repo auf dem Hub vorzuschlagen, ist über die [`create_commit`]-API: Setzen Sie einfach das `create_pr`-Parameter auf `True`. Dieser Parameter ist auch bei anderen Methoden verfügbar, die [`create_commit`] umfassen: * [`upload_file`] * [`upload_folder`] * [`delete_file`] * [`delete_folder`] * [`metadata_update`] ```python >>> from huggingface_hub import metadata_update >>> metadata_update( ... repo_id="username/repo_name", ... metadata={"tags": ["computer-vision", "awesome-model"]}, ... create_pr=True, ... ) ``` Sie können auch [`HfApi.create_discussion`] (bzw. [`HfApi.create_pull_request`]) verwenden, um eine Diskussion (bzw. einen Pull-Request) für ein Repository zu erstellen. Das Öffnen eines Pull-Requests auf diese Weise kann nützlich sein, wenn Sie lokal an Änderungen arbeiten müssen. Auf diese Weise geöffnete Pull-Requests befinden sich im `"Entwurfs"`-Modus. ```python >>> from huggingface_hub import create_discussion, create_pull_request >>> create_discussion( ... repo_id="username/repo-name", ... title="Hi from the huggingface_hub library!", ... token="", ... ) DiscussionWithDetails(...) >>> create_pull_request( ... repo_id="username/repo-name", ... title="Hi from the huggingface_hub library!", ... token="", ... ) DiscussionWithDetails(..., is_pull_request=True) ``` Das Verwalten von Pull-Requests und Diskussionen kann vollständig mit der [`HfApi`]-Klasse durchgeführt werden. Zum Beispiel: * [`comment_discussion`] zum Hinzufügen von Kommentaren * [`edit_discussion_comment`] zum Bearbeiten von Kommentaren * [`rename_discussion`] zum Umbenennen einer Diskussion oder eines Pull-Requests * [`change_discussion_status`] zum Öffnen oder Schließen einer Diskussion / eines Pull-Requests * [`merge_pull_request`] zum Zusammenführen eines Pull-Requests Besuchen Sie die [`HfApi`]-Dokumentationsseite für eine vollständige Übersicht aller verfügbaren Methoden. ## Änderungen an einen Pull-Request senden *Demnächst verfügbar !* ## Siehe auch Für eine detailliertere Referenz besuchen Sie die [Diskussionen und Pull-Requests](../package_reference/community) und die [hf_api](../package_reference/hf_api)-Dokumentationen. huggingface_hub-1.1.5/docs/source/de/guides/download.md000066400000000000000000000325401510763414300230640ustar00rootroot00000000000000 # Dateien aus dem Hub herunterladen Die `huggingface_hub`-Bibliothek bietet Funktionen zum Herunterladen von Dateien aus den auf dem Hub gespeicherten Repositories. Sie können diese Funktionen unabhängig verwenden oder in Ihre eigene Bibliothek integrieren, um es Ihren Benutzern zu erleichtern, mit dem Hub zu interagieren. In diesem Leitfaden erfahren Sie, wie Sie: * Einzelne Dateien herunterladen und zwischenspeichern. * Ein gesamtes Repository herunterladen und zwischenspeichern. * Dateien in einen lokalen Ordner herunterladen. ## Einzelne Dateien herunterladen Die [`hf_hub_download`]-Funktion ist die Hauptfunktion zum Herunterladen von Dateien aus dem Hub. Sie lädt die Remote-Datei herunter, speichert sie auf der Festplatte (auf eine versionsbewusste Art und Weise) und gibt ihren lokalen Dateipfad zurück. > [!TIP] > Der zurückgegebene Dateipfad verweist auf den lokalen Cache von HF. Es ist daher wichtig, die Datei nicht zu ändern, um einen beschädigten Cache zu vermeiden. Wenn Sie mehr darüber erfahren möchten, wie Dateien zwischengespeichert werden, lesen Sie bitte unseren [Caching-Leitfaden](./manage-cache). ### Von der neuesten Version Wählen Sie die Datei zum Herunterladen anhand der Parameter `repo_id`, `repo_type` und `filename` aus. Standardmäßig wird davon ausgegangen, dass die Datei Teil einer `model`-Repository ist. ```python >>> from huggingface_hub import hf_hub_download >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json") '/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json' # Herunterladen von einem Dataset >>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset") '/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py' ``` ### Von einer spezifischen Version Standardmäßig wird die neueste Version vom Hauptzweig `main` heruntergeladen. In einigen Fällen möchten Sie jedoch eine Datei in einer bestimmten Version herunterladen (z. B. aus einem bestimmten Zweig, einem PR, einem Tag oder einem Commit-Hash). Verwenden Sie dazu den Parameter `revision`: ```python # Herunterladen vom Tag `v1.0` >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0") # Herunterladen vom Zweig `test-branch` >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch") # Herunterladen von Pull Request #3 >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3") # Herunterladen von einem spezifischen Commit-Hash >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a") ``` **Hinweis:** Bei Verwendung des Commit-Hashs muss der vollständige Hash anstelle eines 7-Zeichen-Commit-Hashs verwendet werden. ### URL zum Herunterladen erstellen Falls Sie die URL erstellen möchten, die zum Herunterladen einer Datei aus einem Repo verwendet wird, können Sie [`hf_hub_url`] verwenden, das eine URL zurückgibt. Beachten Sie, dass es intern von [`hf_hub_download`] verwendet wird. ## Gesamte Repository herunterladen [`snapshot_download`] lädt ein gesamtes Repository zu einer bestimmten Revision herunter. Es verwendet intern [`hf_hub_download`], was bedeutet, dass alle heruntergeladenen Dateien auch auf Ihrer lokalen Festplatte zwischengespeichert werden. Die Downloads werden gleichzeitig durchgeführt, um den Prozess zu beschleunigen. Um ein ganzes Repository herunterzuladen, geben Sie einfach die `repo_id` und `repo_type` an: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp") '/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade' # Oder von einem Dataset >>> snapshot_download(repo_id="google/fleurs", repo_type="dataset") '/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34' ``` [`snapshot_download`] lädt standardmäßig die neueste Revision herunter. Wenn Sie eine spezifische Repository-Revision wünschen, verwenden Sie den Parameter `revision`: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1") ``` ### Dateien filtern zum Herunterladen [`snapshot_download`] bietet eine einfache Möglichkeit, ein Repository herunterzuladen. Sie möchten jedoch nicht immer den gesamten Inhalt eines Repositories herunterladen. Beispielsweise möchten Sie möglicherweise verhindern, dass alle `.bin`-Dateien heruntergeladen werden, wenn Sie wissen, dass Sie nur die `.safetensors`-Gewichtungen verwenden werden. Dies können Sie mit den Parametern `allow_patterns` und `ignore_patterns` tun. Diese Parameter akzeptieren entweder ein einzelnes Muster oder eine Liste von Mustern. Muster sind Standard-Wildcards (globbing patterns) wie [hier](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm) dokumentiert. Die Mustervergleichung basiert auf [`fnmatch`](https://docs.python.org/3/library/fnmatch.html). Beispielsweise können Sie `allow_patterns` verwenden, um nur JSON-Konfigurationsdateien herunterzuladen: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json") ``` Andererseits können Sie mit `ignore_patterns` bestimmte Dateien vom Herunterladen ausschließen. Im folgenden Beispiel werden die Dateierweiterungen `.msgpack` und `.h5` ignoriert: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"]) ``` Schließlich können Sie beide kombinieren, um Ihren Download genau zu filtern. Hier ist ein Beispiel, wie man alle json- und markdown-Dateien herunterlädt, außer `vocab.json`. ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json") ``` ## Datei(en) in lokalen Ordner herunterladen Die empfohlene (und standardmäßige) Methode zum Herunterladen von Dateien aus dem Hub besteht darin, das [Cache-System](./manage-cache) zu verwenden. Sie können Ihren Cache-Ort festlegen, indem Sie den `cache_dir`-Parameter setzen (sowohl in [`hf_hub_download`] als auch in [`snapshot_download`]). In einigen Fällen möchten Sie jedoch Dateien herunterladen und in einen bestimmten Ordner verschieben. Dies ist nützlich, um einen Workflow zu erhalten, der den `git`-Befehlen ähnelt. Sie können dies mit den Parametern `local_dir` und `local_dir_use_symlinks` tun: - local_dir muss ein Pfad zu einem Ordner auf Ihrem System sein. Die heruntergeladenen Dateien behalten dieselbe Dateistruktur wie im Repository. Wenn zum Beispiel `filename="data/train.csv"` und `local_dir="pfad/zum/ordner"` ist, wird der zurückgegebene Dateipfad `"pfad/zum/ordner/data/train.csv"` sein. - `local_dir_use_symlinks` definiert, wie die Datei in Ihrem lokalen Ordner gespeichert werden muss. - Das Standardverhalten (`"auto"`) besteht darin, kleine Dateien (<5MB) zu duplizieren und für größere Dateien Symlinks zu verwenden. Symlinks ermöglichen die Optimierung von Bandbreite und Speicherplatz. Das manuelle Bearbeiten einer verlinkten Datei könnte jedoch den Cache beschädigen, daher die Duplizierung für kleine Dateien. Die 5-MB-Schwelle kann mit der `HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD`-Umgebungsvariable konfiguriert werden. - Wenn `local_dir_use_symlinks=True` gesetzt ist, werden alle Dateien verlinkt, um den Speicherplatz optimal zu nutzen. Dies ist zum Beispiel nützlich, wenn ein riesiges Dataset mit Tausenden von kleinen Dateien heruntergeladen wird. - Wenn Sie überhaupt keine Symlinks möchten, können Sie sie deaktivieren (`local_dir_use_symlinks=False`). Das Cache-Verzeichnis wird weiterhin verwendet, um zu überprüfen, ob die Datei bereits im Cache ist oder nicht. Wenn sie bereits im Cache ist, wird die Datei aus dem Cache **dupliziert** (d.h. Bandbreite wird gespart, aber der Speicherplatzverbrauch steigt). Wenn die Datei noch nicht im Cache ist, wird sie heruntergeladen und direkt in das lokale Verzeichnis verschoben. Das bedeutet, dass wenn Sie sie später woanders wiederverwenden müssen, sie **erneut heruntergeladen** wird. Hier ist eine Tabelle, die die verschiedenen Optionen zusammenfasst, um Ihnen zu helfen, die Parameter zu wählen, die am besten zu Ihrem Anwendungsfall passen. | Parameter | Datei schon im Cache | Zurückgegebener Pfad | Pfad lesbar? | Kann im Pfad speichern? | Optimierter Datendurchsatz | Optimierter Speicherplatz | |---|:---:|:---:|:---:|:---:|:---:|:---:| | `local_dir=None` | | Symlink im Cache | ✅ | ❌
_(Speichern würde den Cache beschädigen)_ | ✅ | ✅ | | `local_dir="path/to/folder"`
`local_dir_use_symlinks="auto"` | | Datei oder Symlink im Ordner | ✅ | ✅ _(für kleine Dateien)_
⚠️ _(für große Dateien den Pfad nicht auflösen vor dem Speichern)_ | ✅ | ✅ | | `local_dir="path/to/folder"`
`local_dir_use_symlinks=True` | | Symlink im Ordner | ✅ | ⚠️
_(den Pfad nicht auflösen vor dem Speichern)_ | ✅ | ✅ | | `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | Nein | Datei im Ordner | ✅ | ✅ | ❌
_(bei erneutem Ausführen wird die Datei erneut heruntergeladen)_ | ⚠️
(mehrere Kopien, wenn in mehreren Ordnern ausgeführt) | | `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | Ja | Datei im Ordner | ✅ | ✅ | ⚠️
_(Datei muss zuerst im Cache gespeichert werden)_ | ❌
_(Datei wird dupliziert)_ | **Hinweis**: Wenn Sie einen Windows-Computer verwenden, müssen Sie den Entwicklermodus aktivieren oder `huggingface_hub` als Administrator ausführen, um Symlinks zu aktivieren. Weitere Details finden Sie im Abschnitt über [Cache-Beschränkungen](../guides/manage-cache#limitations). ## Herunterladen mit dem CLI Sie können den `hf download`-Befehl im Terminal verwenden, um Dateien direkt aus dem Hub herunterzuladen. Intern verwendet es die gleichen [`hf_hub_download`] und [`snapshot_download`] Helfer, die oben beschrieben wurden, und gibt den zurückgegebenen Pfad im Terminal aus: ```bash >>> hf download gpt2 config.json /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json ``` Standardmäßig wird das lokal gespeicherte Token (mit `hf auth login`) verwendet. Wenn Sie sich ausdrücklich authentifizieren möchten, verwenden Sie die `--token` Option: ```bash >>> hf download gpt2 config.json --token=hf_**** /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json ``` Sie können mehrere Dateien gleichzeitig herunterladen, wobei eine Fortschrittsleiste angezeigt wird und der Snapshot-Pfad zurückgegeben wird, in dem sich die Dateien befinden: ```bash >>> hf download gpt2 config.json model.safetensors Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s] /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 ``` Wenn Sie die Fortschrittsleisten und mögliche Warnungen stummschalten möchten, verwenden Sie die Option `--quiet`. Dies kann nützlich sein, wenn Sie die Ausgabe an einen anderen Befehl in einem Skript weitergeben möchten. ```bash >>> hf download gpt2 config.json model.safetensors /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 ``` Standardmäßig werden Dateien im Cache-Verzeichnis heruntergeladen, das durch die Umgebungsvariable `HF_HOME` definiert ist (oder `~/.cache/huggingface/hub`, wenn nicht angegeben). Sie können dies mit der Option `--cache-dir` überschreiben: ```bash >>> hf download gpt2 config.json --cache-dir=./cache ./cache/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json ``` Wenn Sie Dateien in einen lokalen Ordner herunterladen möchten, ohne die Cache-Verzeichnisstruktur, können Sie `--local-dir` verwenden. Das Herunterladen in einen lokalen Ordner hat seine Einschränkungen, die in dieser [Tabelle](https://huggingface.co/docs/huggingface_hub/guides/download#download-files-to-local-folder) aufgeführt sind. ```bash >>> hf download gpt2 config.json --local-dir=./models/gpt2 ./models/gpt2/config.json ``` Es gibt weitere Argumente, die Sie angeben können, um aus verschiedenen Repo-Typen oder Revisionen herunterzuladen und Dateien zum Herunterladen mit Glob-Mustern ein- oder auszuschließen: ```bash >>> hf download bigcode/the-stack --repo-type=dataset --revision=v1.2 --include="data/python/*" --exclu de="*.json" --exclude="*.zip" Fetching 206 files: 100%|████████████████████████████████████████████| 206/206 [02:31<2:31, ?it/s] /home/wauplin/.cache/huggingface/hub/datasets--bigcode--the-stack/snapshots/9ca8fa6acdbc8ce920a0cb58adcdafc495818ae7 ``` Für eine vollständige Liste der Argumente führen Sie bitte den folgenden Befehl aus: ```bash hf download --help ``` huggingface_hub-1.1.5/docs/source/de/guides/hf_file_system.md000066400000000000000000000121331510763414300242510ustar00rootroot00000000000000 # Interagieren mit dem Hub über die Filesystem API Zusätzlich zur [`HfApi`] bietet die `huggingface_hub` Bibliothek [`HfFileSystem`], eine pythonische, [fsspec-kompatible](https://filesystem-spec.readthedocs.io/en/latest/) Dateischnittstelle zum Hugging Face Hub. Das [`HfFileSystem`] basiert auf der [`HfApi`] und bietet typische Dateisystemoperationen wie `cp`, `mv`, `ls`, `du`, `glob`, `get_file`, und `put_file`. ## Verwendung ```python >>> from huggingface_hub import HfFileSystem >>> fs = HfFileSystem() >>> # Alle Dateien in einem Verzeichnis auflisten >>> fs.ls("datasets/my-username/my-dataset-repo/data", detail=False) ['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv'] >>> # Alle ".csv"-Dateien in einem Repo auflisten >>> fs.glob("datasets/my-username/my-dataset-repo/**.csv") ['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv'] >>> # Eine entfernte Datei lesen >>> with fs.open("datasets/my-username/my-dataset-repo/data/train.csv", "r") as f: ... train_data = f.readlines() >>> # Den Inhalt einer entfernten Datei als Zeichenkette / String lesen >>> train_data = fs.read_text("datasets/my-username/my-dataset-repo/data/train.csv", revision="dev") >>> # Eine entfernte Datei schreiben >>> with fs.open("datasets/my-username/my-dataset-repo/data/validation.csv", "w") as f: ... f.write("text,label") ... f.write("Fantastic movie!,good") ``` Das optionale Argument `revision` kann übergeben werden, um eine Operation von einem spezifischen Commit auszuführen, wie z.B. einem Branch, Tag-Namen oder einem Commit-Hash. Anders als bei Pythons eingebautem `open`, ist der Standardmodus von `fsspec`'s `open` binär, `"rb"`. Das bedeutet, dass Sie den Modus explizit auf `"r"` zum Lesen und `"w"` zum Schreiben im Textmodus setzen müssen. Das Anhängen an eine Datei (Modi `"a"` und `"ab"`) wird noch nicht unterstützt. ## Integrationen Das [`HfFileSystem`] kann mit jeder Bibliothek verwendet werden, die `fsspec` integriert, vorausgesetzt die URL folgt dem Schema: ``` hf://[][@]/ ``` Der `repo_type_prefix` ist `datasets/` für Datensätze, `spaces/` für Spaces, und Modelle benötigen kein Präfix in der URL. Einige interessante Integrationen, bei denen [`HfFileSystem`] die Interaktion mit dem Hub vereinfacht, sind unten aufgeführt: * Lesen/Schreiben eines [Pandas](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#reading-writing-remote-files) DataFrame aus/in ein Hub-Repository: ```python >>> import pandas as pd >>> # Eine entfernte CSV-Datei in einen DataFrame lesen >>> df = pd.read_csv("hf://datasets/my-username/my-dataset-repo/train.csv") >>> # Einen DataFrame in eine entfernte CSV-Datei schreiben >>> df.to_csv("hf://datasets/my-username/my-dataset-repo/test.csv") ``` Der gleiche Arbeitsablauf kann auch für [Dask](https://docs.dask.org/en/stable/how-to/connect-to-remote-data.html) und [Polars](https://pola-rs.github.io/polars/py-polars/html/reference/io.html) verwendet werden. * Abfrage von (entfernten) Hub-Dateien mit [DuckDB](https://duckdb.org/docs/guides/python/filesystems): ```python >>> from huggingface_hub import HfFileSystem >>> import duckdb >>> fs = HfFileSystem() >>> duckdb.register_filesystem(fs) >>> # Eine entfernte Datei abfragen und das Ergebnis als DataFrame zurückbekommen >>> fs_query_file = "hf://datasets/my-username/my-dataset-repo/data_dir/data.parquet" >>> df = duckdb.query(f"SELECT * FROM '{fs_query_file}' LIMIT 10").df() ``` * Verwendung des Hub als Array-Speicher mit [Zarr](https://zarr.readthedocs.io/en/stable/tutorial.html#io-with-fsspec): ```python >>> import numpy as np >>> import zarr >>> embeddings = np.random.randn(50000, 1000).astype("float32") >>> # Ein Array in ein Repo schreiben >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="w") as root: ... foo = root.create_group("embeddings") ... foobar = foo.zeros('experiment_0', shape=(50000, 1000), chunks=(10000, 1000), dtype='f4') ... foobar[:] = embeddings >>> # Ein Array aus einem Repo lesen >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="r") as root: ... first_row = root["embeddings/experiment_0"][0] ``` ## Authentifizierung In vielen Fällen müssen Sie mit einem Hugging Face-Konto angemeldet sein, um mit dem Hub zu interagieren. Lesen Sie den [Login](../quick-start#login)-Abschnitt der Dokumentation, um mehr über Authentifizierungsmethoden auf dem Hub zu erfahren. Es ist auch möglich, sich programmatisch anzumelden, indem Sie Ihr `token` als Argument an [`HfFileSystem`] übergeben: ```python >>> from huggingface_hub import HfFileSystem >>> fs = HfFileSystem(token=token) ``` Wenn Sie sich auf diese Weise anmelden, seien Sie vorsichtig, das Token nicht versehentlich zu veröffentlichen, wenn Sie Ihren Quellcode teilen! huggingface_hub-1.1.5/docs/source/de/guides/inference.md000066400000000000000000000354031510763414300232140ustar00rootroot00000000000000 # Inferenz auf Servern ausführen Inferenz ist der Prozess, bei dem ein trainiertes Modell verwendet wird, um Vorhersagen für neue Daten zu treffen. Da dieser Prozess rechenintensiv sein kann, kann die Ausführung auf einem dedizierten Server eine interessante Option sein. Die `huggingface_hub` Bibliothek bietet eine einfache Möglichkeit, einen Dienst aufzurufen, der die Inferenz für gehostete Modelle durchführt. Es gibt mehrere Dienste, mit denen Sie sich verbinden können: - [Inferenz API](https://huggingface.co/docs/api-inference/index): ein Service, der Ihnen ermöglicht, beschleunigte Inferenz auf der Infrastruktur von Hugging Face kostenlos auszuführen. Dieser Service ist eine schnelle Möglichkeit, um anzufangen, verschiedene Modelle zu testen und AI-Produkte zu prototypisieren. - [Inferenz Endpunkte](https://huggingface.co/inference-endpoints/index): ein Produkt zur einfachen Bereitstellung von Modellen im Produktivbetrieb. Die Inferenz wird von Hugging Face in einer dedizierten, vollständig verwalteten Infrastruktur auf einem Cloud-Anbieter Ihrer Wahl durchgeführt. > [!TIP] > [`InferenceClient`] ist ein Python-Client, der HTTP-Anfragen an unsere APIs stellt. Wenn Sie die HTTP-Anfragen direkt mit Ihrem bevorzugten Tool (curl, postman,...) durchführen möchten, lesen Sie bitte die Dokumentationsseiten der [Inferenz API](https://huggingface.co/docs/api-inference/index) oder der [Inferenz Endpunkte](https://huggingface.co/docs/inference-endpoints/index). > > Für die Webentwicklung wurde ein [JS-Client](https://huggingface.co/docs/huggingface.js/inference/README) veröffentlicht. Wenn Sie sich für die Spieleentwicklung interessieren, sollten Sie einen Blick auf unser [C#-Projekt](https://github.com/huggingface/unity-api) werfen. ## Erste Schritte Los geht's mit einer Text-zu-Bild-Aufgabe: ```python >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> image = client.text_to_image("An astronaut riding a horse on the moon.") >>> image.save("astronaut.png") ``` Wir haben einen [`InferenceClient`] mit den Standardparametern initialisiert. Das Einzige, was Sie wissen müssen, ist die [Aufgabe](#unterstützte-aufgaben), die Sie ausführen möchten. Standardmäßig wird der Client sich mit der Inferenz API verbinden und ein Modell auswählen, um die Aufgabe abzuschließen. In unserem Beispiel haben wir ein Bild aus einem Textprompt generiert. Der zurückgegebene Wert ist ein `PIL.Image`-Objekt, das in eine Datei gespeichert werden kann. > [!WARNING] > Die API ist darauf ausgelegt, einfach zu sein. Nicht alle Parameter und Optionen sind für den Endbenutzer verfügbar oder beschrieben. Schauen Sie auf [dieser Seite](https://huggingface.co/docs/api-inference/detailed_parameters) nach, wenn Sie mehr über alle verfügbaren Parameter für jede Aufgabe erfahren möchten. ### Verwendung eines spezifischen Modells Was ist, wenn Sie ein bestimmtes Modell verwenden möchten? Sie können es entweder als Parameter angeben oder direkt auf Instanzebene spezifizieren: ```python >>> from huggingface_hub import InferenceClient # Client für ein spezifisches Modell initialisieren >>> client = InferenceClient(model="prompthero/openjourney-v4") >>> client.text_to_image(...) # Oder nutzen Sie einen generischen Client, geben aber Ihr Modell als Argument an >>> client = InferenceClient() >>> client.text_to_image(..., model="prompthero/openjourney-v4") ``` > [!TIP] > Es gibt mehr als 200k Modelle im Hugging Face Hub! Jede Aufgabe im [`InferenceClient`] kommt mit einem empfohlenen Modell. Beachten Sie, dass die HF-Empfehlung sich im Laufe der Zeit ohne vorherige Ankündigung ändern kann. Daher ist es am besten, ein Modell explizit festzulegen, sobald Sie sich entschieden haben. In den meisten Fällen werden Sie daran interessiert sein, ein Modell zu finden, das speziell auf _Ihre_ Bedürfnisse zugeschnitten ist. Besuchen Sie die [Modelle](https://huggingface.co/models)-Seite im Hub, um Ihre Möglichkeiten zu erkunden. ### Verwendung einer spezifischen URL Die oben gesehenen Beispiele nutzen die kostenfrei gehostete Inferenz API. Dies erweist sich als sehr nützlich für Prototyping und schnelles Testen. Wenn Sie bereit sind, Ihr Modell in die Produktion zu übernehmen, müssen Sie eine dedizierte Infrastruktur verwenden. Hier kommen [Inferenz Endpunkte](https://huggingface.co/docs/inference-endpoints/index) ins Spiel. Es ermöglicht Ihnen, jedes Modell zu implementieren und als private API freizugeben. Nach der Implementierung erhalten Sie eine URL, zu der Sie mit genau dem gleichen Code wie zuvor eine Verbindung herstellen können, wobei nur der `Modell`-Parameter geändert wird: ```python >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if") # oder >>> client = InferenceClient() >>> client.text_to_image(..., model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if") ``` ### Authentifizierung Aufrufe, die mit dem [`InferenceClient`] gemacht werden, können mit einem [User Access Token](https://huggingface.co/docs/hub/security-tokens) authentifiziert werden. Standardmäßig wird das auf Ihrem Computer gespeicherte Token verwendet, wenn Sie angemeldet sind (sehen Sie hier, [wie Sie sich anmelden können](https://huggingface.co/docs/huggingface_hub/quick-start#login)). Wenn Sie nicht angemeldet sind, können Sie Ihr Token als Instanzparameter übergeben: ```python >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(token="hf_***") ``` > [!TIP] > Die Authentifizierung ist NICHT zwingend erforderlich, wenn Sie die Inferenz API verwenden. Authentifizierte Benutzer erhalten jedoch ein höheres kostenloses Kontingent, um mit dem Service zu arbeiten. Ein Token ist auch zwingend erforderlich, wenn Sie Inferenz auf Ihren privaten Modellen oder auf privaten Endpunkten ausführen möchten. ## Unterstützte Aufgaben Das Ziel von [`InferenceClient`] ist es, die einfachste Schnittstelle zum Ausführen von Inferenzen auf Hugging Face-Modellen bereitzustellen. Es verfügt über eine einfache API, die die gebräuchlichsten Aufgaben unterstützt. Hier ist eine Liste der derzeit unterstützten Aufgaben: | Domäne | Aufgabe | Unterstützt | Dokumentation | | --------------- | --------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------- | | Audio | [Audio Classification](https://huggingface.co/tasks/audio-classification) | ✅ | [`~InferenceClient.audio_classification`] | | | [Automatic Speech Recognition](https://huggingface.co/tasks/automatic-speech-recognition) | ✅ | [`~InferenceClient.automatic_speech_recognition`] | | | [Text-to-Speech](https://huggingface.co/tasks/text-to-speech) | ✅ | [`~InferenceClient.text_to_speech`] | | Computer Vision | [Image Classification](https://huggingface.co/tasks/image-classification) | ✅ | [`~InferenceClient.image_classification`] | | | [Image Segmentation](https://huggingface.co/tasks/image-segmentation) | ✅ | [`~InferenceClient.image_segmentation`] | | | [Image-to-Image](https://huggingface.co/tasks/image-to-image) | ✅ | [`~InferenceClient.image_to_image`] | | | [Image-to-Text](https://huggingface.co/tasks/image-to-text) | ✅ | [`~InferenceClient.image_to_text`] | | | [Object Detection](https://huggingface.co/tasks/object-detection) | ✅ | [`~InferenceClient.object_detection`] | | | [Text-to-Image](https://huggingface.co/tasks/text-to-image) | ✅ | [`~InferenceClient.text_to_image`] | | | [Zero-Shot-Image-Classification](https://huggingface.co/tasks/zero-shot-image-classification) | ✅ | [`~InferenceClient.zero_shot_image_classification`] | | Multimodal | [Documentation Question Answering](https://huggingface.co/tasks/document-question-answering) | ✅ | [`~InferenceClient.document_question_answering`] | | | [Visual Question Answering](https://huggingface.co/tasks/visual-question-answering) | ✅ | [`~InferenceClient.visual_question_answering`] | | NLP | [Conversational](https://huggingface.co/tasks/conversational) | ✅ | [`~InferenceClient.conversational`] | | | [Feature Extraction](https://huggingface.co/tasks/feature-extraction) | ✅ | [`~InferenceClient.feature_extraction`] | | | [Fill Mask](https://huggingface.co/tasks/fill-mask) | ✅ | [`~InferenceClient.fill_mask`] | | | [Question Answering](https://huggingface.co/tasks/question-answering) | ✅ | [`~InferenceClient.question_answering`] | | | [Sentence Similarity](https://huggingface.co/tasks/sentence-similarity) | ✅ | [`~InferenceClient.sentence_similarity`] | | | [Summarization](https://huggingface.co/tasks/summarization) | ✅ | [`~InferenceClient.summarization`] | | | [Table Question Answering](https://huggingface.co/tasks/table-question-answering) | ✅ | [`~InferenceClient.table_question_answering`] | | | [Text Classification](https://huggingface.co/tasks/text-classification) | ✅ | [`~InferenceClient.text_classification`] | | | [Text Generation](https://huggingface.co/tasks/text-generation) | ✅ | [`~InferenceClient.text_generation`] | | | [Token Classification](https://huggingface.co/tasks/token-classification) | ✅ | [`~InferenceClient.token_classification`] | | | [Translation](https://huggingface.co/tasks/translation) | ✅ | [`~InferenceClient.translation`] | | | [Zero Shot Classification](https://huggingface.co/tasks/zero-shot-classification) | ✅ | [`~InferenceClient.zero_shot_classification`] | | Tabular | [Tabular Classification](https://huggingface.co/tasks/tabular-classification) | ✅ | [`~InferenceClient.tabular_classification`] | | | [Tabular Regression](https://huggingface.co/tasks/tabular-regression) | ✅ | [`~InferenceClient.tabular_regression`] | > [!TIP] > Schauen Sie sich die [Aufgaben](https://huggingface.co/tasks)-Seite an, um mehr über jede Aufgabe zu erfahren, wie man sie verwendet und die beliebtesten Modelle für jede Aufgabe. ## Asynchroner Client Eine asynchrone Version des Clients wird ebenfalls bereitgestellt, basierend auf `asyncio` und `aiohttp`. Sie können entweder `aiohttp` direkt installieren oder das `[inference]` Extra verwenden: ```sh pip install aiohttp # oder pip install --upgrade huggingface_hub[inference] ``` Nach der Installation sind alle asynchronen API-Endpunkte über [`AsyncInferenceClient`] verfügbar. Seine Initialisierung und APIs sind genau gleich wie die synchronisierte Version. ```py # Der Code muss in einem asyncio-konkurrenten Kontext ausgeführt werden. # $ python -m asyncio >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> image = await client.text_to_image("An astronaut riding a horse on the moon.") >>> image.save("astronaut.png") >>> async for token in await client.text_generation("The Huggingface Hub is", stream=True): ... print(token, end="") a platform for sharing and discussing ML-related content. ``` Für weitere Informationen zum `asyncio`-Modul konsultieren Sie bitte die [offizielle Dokumentation](https://docs.python.org/3/library/asyncio.html). ## Fortgeschrittene Tipps Im obigen Abschnitt haben wir die Hauptaspekte von [`InferenceClient`] betrachtet. Lassen Sie uns in einige fortgeschrittene Tipps eintauchen. ### Zeitüberschreitung Bei der Inferenz gibt es zwei Hauptursachen für eine Zeitüberschreitung: - Der Inferenzprozess dauert lange, um abgeschlossen zu werden. - Das Modell ist nicht verfügbar, beispielsweise wenn die Inferenz API es zum ersten Mal lädt. Der [`InferenceClient`] verfügt über einen globalen Zeitüberschreitungsparameter (`timeout`), um diese beiden Aspekte zu behandeln. Standardmäßig ist er auf `None` gesetzt, was bedeutet, dass der Client unendlich lange auf den Abschluss der Inferenz warten wird. Wenn Sie mehr Kontrolle in Ihrem Arbeitsablauf wünschen, können Sie ihn auf einen bestimmten Wert in Sekunden setzen. Wenn die Zeitüberschreitungsverzögerung abläuft, wird ein [`InferenceTimeoutError`] ausgelöst. Sie können diesen Fehler abfangen und in Ihrem Code behandeln: ```python >>> from huggingface_hub import InferenceClient, InferenceTimeoutError >>> client = InferenceClient(timeout=30) >>> try: ... client.text_to_image(...) ... except InferenceTimeoutError: ... print("Inference timed out after 30s.") ``` ### Binäre Eingaben Einige Aufgaben erfordern binäre Eingaben, zum Beispiel bei der Arbeit mit Bildern oder Audiodateien. In diesem Fall versucht der [`InferenceClient] so permissiv wie möglich zu sein und akzeptiert verschiedene Typen: - rohe `Bytes` - ein Datei-ähnliches Objekt, geöffnet als Binär (`with open("audio.flac", "rb") as f: ...`) - ein Pfad (`str` oder `Path`) zu einer lokalen Datei - eine URL (`str`) zu einer entfernten Datei (z.B. `https://...`). In diesem Fall wird die Datei lokal heruntergeladen, bevor sie an die Inferenz API gesendet wird. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.image_classification("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg") [{'score': 0.9779096841812134, 'label': 'Blenheim spaniel'}, ...] ``` huggingface_hub-1.1.5/docs/source/de/guides/integrations.md000066400000000000000000000362471510763414300237730ustar00rootroot00000000000000 # Integrieren Sie jedes ML-Framework mit dem Hub Der Hugging Face Hub erleichtert das Hosten und Teilen von Modellen mit der Community. Er unterstützt [Dutzende von Bibliotheken](https://huggingface.co/docs/hub/models-libraries) im Open Source-Ökosystem. Wir arbeiten ständig daran, diese Unterstützung zu erweitern, um kollaboratives Machine Learning voranzutreiben. Die `huggingface_hub`-Bibliothek spielt eine Schlüsselrolle in diesem Prozess und ermöglicht es jedem Python-Skript, Dateien einfach hochzuladen und zu laden. Es gibt vier Hauptwege, eine Bibliothek mit dem Hub zu integrieren: 1. **Push to Hub**: Implementieren Sie eine Methode, um ein Modell auf den Hub hochzuladen. Dies beinhaltet das Modellgewicht sowie [die Modellkarte](https://huggingface.co/docs/huggingface_hub/how-to-model-cards) und alle anderen relevanten Informationen oder Daten, die für den Betrieb des Modells erforderlich sind (zum Beispiel Trainingsprotokolle). Diese Methode wird oft `push_to_hub()` genannt. 2. **Download from Hub**: Implementieren Sie eine Methode, um ein Modell vom Hub zu laden. Die Methode sollte die Modellkonfiguration/-gewichte herunterladen und das Modell laden. Diese Methode wird oft `from_pretrained` oder `load_from_hub()` genannt. 3. **Widgets**: Zeigen Sie ein Widget auf der Landing Page Ihrer Modelle auf dem Hub an. Dies ermöglicht es Benutzern, ein Modell schnell aus dem Browser heraus auszuprobieren. In diesem Leitfaden konzentrieren wir uns auf die ersten beiden Themen. Wir werden die beiden Hauptansätze vorstellen, die Sie zur Integration einer Bibliothek verwenden können, mit ihren Vor- und Nachteilen. Am Ende des Leitfadens ist alles zusammengefasst, um Ihnen bei der Auswahl zwischen den beiden zu helfen. Bitte beachten Sie, dass dies nur Richtlinien sind, die Sie an Ihre Anforderungen anpassen können. Wenn Sie sich für Inferenz und Widgets interessieren, können Sie [diesem Leitfaden](https://huggingface.co/docs/hub/models-adding-libraries#set-up-the-inference-api) folgen. In beiden Fällen können Sie sich an uns wenden, wenn Sie eine Bibliothek mit dem Hub integrieren und [in unserer Dokumentation](https://huggingface.co/docs/hub/models-libraries) aufgeführt haben möchten. ## Ein flexibler Ansatz: Helfer Der erste Ansatz zur Integration einer Bibliothek in den Hub besteht tatsächlich darin, die `push_to_hub` und `from_pretrained` Methoden selbst zu implementieren. Dies gibt Ihnen volle Flexibilität hinsichtlich der Dateien, die Sie hoch-/herunterladen möchten, und wie Sie Eingaben, die speziell für Ihr Framework sind, behandeln. Sie können sich die beiden Leitfäden [Dateien hochladen](./upload) und [Dateien herunterladen](./download) ansehen, um mehr darüber zu erfahren, wie dies funktioniert. Dies ist zum Beispiel die Art und Weise, wie die FastAI-Integration implementiert ist (siehe [`push_to_hub_fastai`] und [`from_pretrained_fastai`]). Die Implementierung kann zwischen den Bibliotheken variieren, aber der Workflow ist oft ähnlich. ### from_pretrained So sieht eine `from_pretrained` Methode normalerweise aus: ```python def from_pretrained(model_id: str) -> MyModelClass: # Modell vom Hub herunterladen cached_model = hf_hub_download( repo_id=repo_id, filename="model.pkl", library_name="fastai", library_version=get_fastai_version(), ) # Modell laden return load_model(cached_model) ``` ### push_to_hub Die `push_to_hub` Methode erfordert oft etwas mehr Komplexität, um die Repo-Erstellung, die Generierung der Modellkarte und das Speichern von Gewichten zu behandeln. Ein üblicher Ansatz besteht darin, all diese Dateien in einem temporären Ordner zu speichern, ihn hochzuladen und dann zu löschen. ```python def push_to_hub(model: MyModelClass, repo_name: str) -> None: api = HfApi() # Repo erstellen, wenn noch nicht vorhanden und die zugehörige repo_id erhalten repo_id = api.create_repo(repo_name, exist_ok=True) # Modell in temporärem Ordner speichern und in einem enzigen Commit pushen with TemporaryDirectory() as tmpdir: tmpdir = Path(tmpdir) # Gewichte speichern save_model(model, tmpdir / "model.safetensors") # Modellkarte generieren card = generate_model_card(model) (tmpdir / "README.md").write_text(card) # Logs speichern # Diagramme speichern # Evaluationsmetriken speichern # ... # Auf den Hub pushen return api.upload_folder(repo_id=repo_id, folder_path=tmpdir) ``` Dies ist natürlich nur ein Beispiel. Wenn Sie an komplexeren Manipulationen interessiert sind (entfernen von entfernten Dateien, hochladen von Gewichten on-the-fly, lokales Speichern von Gewichten, usw.), beachten Sie bitte den [Dateien hochladen](./upload) Leitfaden. ### Einschränkungen Obwohl dieser Ansatz flexibel ist, hat er einige Nachteile, insbesondere in Bezug auf die Wartung. Hugging Face-Benutzer sind oft an zusätzliche Funktionen gewöhnt, wenn sie mit `huggingface_hub` arbeiten. Zum Beispiel ist es beim Laden von Dateien aus dem Hub üblich, Parameter wie folgt anzubieten: - `token`: zum Herunterladen aus einem privaten Repository - `revision`: zum Herunterladen von einem spezifischen Branch - `cache_dir`: um Dateien in einem spezifischen Verzeichnis zu cachen - `force_download`/`local_files_only`: um den Cache wieder zu verwenden oder nicht - `api_endpoint`/`proxies`: HTTP-Session konfigurieren Beim Pushen von Modellen werden ähnliche Parameter unterstützt: - `commit_message`: benutzerdefinierte Commit-Nachricht - `private`: ein privates Repository erstellen, falls nicht vorhanden - `create_pr`: erstellen Sie einen PR anstatt auf `main` zu pushen - `branch`: auf einen Branch pushen anstatt auf den `main` Branch - `allow_patterns`/`ignore_patterns`: filtern, welche Dateien hochgeladen werden sollen - `token` - `api_endpoint` - ... Alle diese Parameter können den zuvor gesehenen Implementierungen hinzugefügt und an die `huggingface_hub`-Methoden übergeben werden. Wenn sich jedoch ein Parameter ändert oder eine neue Funktion hinzugefügt wird, müssen Sie Ihr Paket aktualisieren. Die Unterstützung dieser Parameter bedeutet auch mehr Dokumentation, die Sie auf Ihrer Seite pflegen müssen. Um zu sehen, wie man diese Einschränkungen mildert, springen wir zu unserem nächsten Abschnitt **Klassenvererbung**. ## Ein komplexerer Ansatz: Klassenvererbung Wie wir oben gesehen haben, gibt es zwei Hauptmethoden, um Ihre Bibliothek mit dem Hub zu integrieren: Dateien hochladen (`push_to_hub`) und Dateien herunterladen (`from_pretrained`). Sie können diese Methoden selbst implementieren, aber das hat seine Tücken. Um dies zu bewältigen, bietet `huggingface_hub` ein Werkzeug an, das Klassenvererbung verwendet. Schauen wir uns an, wie es funktioniert! In vielen Fällen implementiert eine Bibliothek ihr Modell bereits mit einer Python-Klasse. Die Klasse enthält die Eigenschaften des Modells und Methoden zum Laden, Ausführen, Trainieren und Evaluieren. Unser Ansatz besteht darin, diese Klasse zu erweitern, um Upload- und Download-Funktionen mit Mixins hinzuzufügen. Ein [Mixin](https://stackoverflow.com/a/547714) ist eine Klasse, die dazu bestimmt ist, eine vorhandene Klasse mit einem Satz spezifischer Funktionen durch Mehrfachvererbung zu erweitern. `huggingface_hub` bietet sein eigenes Mixin, das [`ModelHubMixin`]. Der Schlüssel hier ist zu verstehen, wie es funktioniert und wie man es anpassen kann. Die Klasse [ModelHubMixin] implementiert 3 *öffentliche* Methoden (`push_to_hub`, `save_pretrained` und `from_pretrained`). Dies sind die Methoden, die Ihre Benutzer aufrufen werden, um Modelle mit Ihrer Bibliothek zu laden/speichern. [`ModelHubMixin`] definiert auch 2 private Methoden (`_save_pretrained` und `_from_pretrained`). Diese müssen Sie implementieren. Um Ihre Bibliothek zu integrieren, sollten Sie: 1. Lassen Sie Ihre Modell-Klasse von [`ModelHubMixin`] erben. 2. Implementieren Sie die privaten Methoden: - [`~ModelHubMixin._save_pretrained`]: Methode, die als Eingabe einen Pfad zu einem Verzeichnis nimmt und das Modell dort speichert. Sie müssen die gesamte Logik zum Speichern Ihres Modells in dieser Methode schreiben: Modellkarte, Modellgewichte, Konfigurationsdateien, Trainingsprotokolle und Diagramme. Alle relevanten Informationen für dieses Modell müssen von dieser Methode behandelt werden. [Model Cards](https://huggingface.co/docs/hub/model-cards) sind besonders wichtig, um Ihr Modell zu beschreiben. Weitere Details finden Sie in [unserem Implementierungsleitfaden](./model-cards). - [~ModelHubMixin._from_pretrained]: **Klassenmethode**, die als Eingabe eine `model_id` nimmt und ein instanziiertes Modell zurückgibt. Die Methode muss die relevanten Dateien herunterladen und laden. 3. Sie sind fertig! Der Vorteil der Verwendung von [`ModelHubMixin`] besteht darin, dass Sie, sobald Sie sich um die Serialisierung/das Laden der Dateien gekümmert haben, bereit sind los zu legen. Sie müssen sich keine Gedanken über Dinge wie Repository-Erstellung, Commits, PRs oder Revisionen machen. All dies wird von dem Mixin gehandhabt und steht Ihren Benutzern zur Verfügung. Das Mixin stellt auch sicher, dass öffentliche Methoden gut dokumentiert und typisiert sind. ### Ein konkretes Beispiel: PyTorch Ein gutes Beispiel für das, was wir oben gesehen haben, ist [`PyTorchModelHubMixin`], unsere Integration für das PyTorch-Framework. Dies ist eine einsatzbereite Integration. #### Wie verwendet man es? Hier ist, wie jeder Benutzer ein PyTorch-Modell vom/auf den Hub laden/speichern kann: ```python >>> import torch >>> import torch.nn as nn >>> from huggingface_hub import PyTorchModelHubMixin # 1. Definieren Sie Ihr Pytorch-Modell genau so, wie Sie es gewohnt sind >>> class MyModel(nn.Module, PyTorchModelHubMixin): # Mehrfachvererbung ... def __init__(self): ... super().__init__() ... self.param = nn.Parameter(torch.rand(3, 4)) ... self.linear = nn.Linear(4, 5) ... def forward(self, x): ... return self.linear(x + self.param) >>> model = MyModel() # 2. (optional) Modell in lokales Verzeichnis speichern >>> model.save_pretrained("path/to/my-awesome-model") # 3. Modellgewichte an den Hub übertragen >>> model.push_to_hub("my-awesome-model") # 4. Modell vom Hub initialisieren >>> model = MyModel.from_pretrained("username/my-awesome-model") ``` #### Implementierung Die Implementierung ist tatsächlich sehr einfach, und die vollständige Implementierung finden Sie [hier](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hub_mixin.py). 1. Zuerst, erben Ihrer Klasse von `ModelHubMixin`: ```python from huggingface_hub import ModelHubMixin class PyTorchModelHubMixin(ModelHubMixin): (...) ``` 2. Implementieren der `_save_pretrained` Methode: ```py from huggingface_hub import ModelCard, ModelCardData class PyTorchModelHubMixin(ModelHubMixin): (...) def _save_pretrained(self, save_directory: Path): """Generiere Modellkarte und speichere Gewichte von einem Pytorch-Modell in einem lokalen Verzeichnis.""" model_card = ModelCard.from_template( card_data=ModelCardData( license='mit', library_name="pytorch", ... ), model_summary=..., model_type=..., ... ) (save_directory / "README.md").write_text(str(model)) torch.save(obj=self.module.state_dict(), f=save_directory / "pytorch_model.bin") ``` 3. Implementieren der `_from_pretrained` Methode: ```python class PyTorchModelHubMixin(ModelHubMixin): (...) @classmethod # Muss eine Klassenmethode sein! def _from_pretrained( cls, *, model_id: str, revision: str, cache_dir: str, force_download: bool, proxies: Optional[dict], local_files_only: bool, token: Union[str, bool, None], map_location: str = "cpu", # zusätzliches Argument strict: bool = False, # zusätzliches Argument **model_kwargs, ): """Load Pytorch pretrained weights and return the loaded model.""" if os.path.isdir(model_id): # Kann entweder ein lokales Verzeichnis sein print("Loading weights from local directory") model_file = os.path.join(model_id, "pytorch_model.bin") else: # Oder ein Modell am Hub model_file = hf_hub_download( # Herunterladen vom Hub, gleiche Eingabeargumente repo_id=model_id, filename="pytorch_model.bin", revision=revision, cache_dir=cache_dir, force_download=force_download, token=token, local_files_only=local_files_only, ) # Modell laden und zurückgeben - benutzerdefinierte Logik je nach Ihrem Framework model = cls(**model_kwargs) state_dict = torch.load(model_file, map_location=torch.device(map_location)) model.load_state_dict(state_dict, strict=strict) model.eval() return model ``` Und das war's! Ihre Bibliothek ermöglicht es Benutzern nun, Dateien vom und zum Hub hoch- und herunterzuladen. ## Kurzer Vergleich Lassen Sie uns die beiden Ansätze, die wir gesehen haben, schnell mit ihren Vor- und Nachteilen zusammenfassen. Die untenstehende Tabelle ist nur indikativ. Ihr Framework könnte einige Besonderheiten haben, die Sie berücksichtigen müssen. Dieser Leitfaden soll nur Richtlinien und Ideen geben, wie Sie die Integration handhaben können. Kontaktieren Sie uns in jedem Fall, wenn Sie Fragen haben! | Integration | Mit Helfern | Mit [`ModelHubMixin`] | | :--------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------: | | Benutzererfahrung | `model = load_from_hub(...)`
`push_to_hub(model, ...)` | `model = MyModel.from_pretrained(...)`
`model.push_to_hub(...)` | | Flexibilität | Sehr flexibel.
Sie haben die volle Kontrolle über die Implementierung. | Weniger flexibel.
Ihr Framework muss eine Modellklasse haben. | | Wartung | Mehr Wartung, um Unterstützung für Konfiguration und neue Funktionen hinzuzufügen. Könnte auch das Beheben von Benutzerproblemen erfordern. | Weniger Wartung, da die meisten Interaktionen mit dem Hub in `huggingface_hub` implementiert sind. | | Dokumentation/Typ-Annotation | Manuell zu schreiben. | Teilweise durch `huggingface_hub` behandelt. | huggingface_hub-1.1.5/docs/source/de/guides/manage-cache.md000066400000000000000000000500441510763414300235450ustar00rootroot00000000000000 # Verwalten des `huggingface_hub` Cache-Systems ## Caching verstehen Das Hugging Face Hub Cache-System wurde entwickelt, um der zentrale Cache zu sein, der zwischen Bibliotheken geteilt wird, welche vom Hub abhängen. Es wurde in v0.8.0 aktualisiert, um das erneute Herunterladen von Dateien zwischen Revisionen zu verhindern. Das Cache-System ist wie folgt aufgebaut: ``` ├─ ├─ ├─ ``` Der `` ist normalerweise das Home-Verzeichnis Ihres Benutzers. Es kann jedoch mit dem `cache_dir`-Argument in allen Methoden oder durch Angabe der Umgebungsvariablen `HF_HOME` oder `HF_HUB_CACHE` angepasst werden. Modelle, Datensätze und Räume teilen eine gemeinsame Wurzel. Jedes dieser Repositories enthält den Repository-Typ, den Namensraum (Organisation oder Benutzername), falls vorhanden, und den Repository-Namen: ``` ├─ models--julien-c--EsperBERTo-small ├─ models--lysandrejik--arxiv-nlp ├─ models--bert-base-cased ├─ datasets--glue ├─ datasets--huggingface--DataMeasurementsFiles ├─ spaces--dalle-mini--dalle-mini ``` Innerhalb dieser Ordner werden nun alle Dateien vom Hub heruntergeladen. Das Caching stellt sicher, dass eine Datei nicht zweimal heruntergeladen wird, wenn sie bereits existiert und nicht aktualisiert wurde; wurde sie jedoch aktualisiert und Sie fordern die neueste Datei an, wird die neueste Datei heruntergeladen (während die vorherige Datei intakt bleibt, falls Sie sie erneut benötigen). Um dies zu erreichen, enthalten alle Ordner dasselbe Grundgerüst: ``` ├─ datasets--glue │ ├─ refs │ ├─ blobs │ ├─ snapshots ... ``` Jeder Ordner ist so gestaltet, dass er das Folgende enthält: ### Refs Der Ordner `refs` enthält Dateien, die die neueste Revision des gegebenen Verweises anzeigen. Zum Beispiel, wenn wir zuvor eine Datei aus dem `main`-Branch eines Repositories abgerufen haben, wird der Ordner `refs` eine Datei namens `main` enthalten, die selbst den Commit-Identifikator der aktuellen HEAD-Branch enthält. Wenn der neueste Commit von `main` den Identifikator `aaaaaa` hat, dann enthält er `aaaaaa`. Wenn derselbe Zweig mit einem neuen Commit aktualisiert wird, der den Identifikator `bbbbbb` hat, wird das erneute Herunterladen einer Datei von diesem Verweis die Datei `refs/main` aktualisieren, um `bbbbbb` zu enthalten. ### Blobs Der Ordner `blobs` enthält die tatsächlichen Dateien, die wir heruntergeladen haben. Der Name jeder Datei ist ihr Hash. ### Snapshots Der Ordner `snapshots` enthält Symlinks zu den oben erwähnten Blobs. Er besteht selbst aus mehreren Ordnern: einem pro bekannter Revision! In der obigen Erklärung hatten wir zunächst eine Datei von der Revision `aaaaaa` abgerufen, bevor wir eine Datei von der Revision `bbbbbb` abgerufen haben. In dieser Situation hätten wir jetzt zwei Ordner im Ordner `snapshots`: `aaaaaa` und `bbbbbb`. In jedem dieser Ordner leben Symlinks, die die Namen der Dateien haben, die wir heruntergeladen haben. Wenn wir zum Beispiel die Datei `README.md` in der Revision `aaaaaa` heruntergeladen hätten, hätten wir den folgenden Pfad: ``` //snapshots/aaaaaa/README.md ``` Diese `README.md`-Datei ist tatsächlich ein Symlink, der auf den Blob verweist, der den Hash der Datei hat. Durch das Erstellen des Grundgerüsts auf diese Weise ermöglichen wir den Mechanismus der Dateifreigabe: Wenn dieselbe Datei in der Revision `bbbbbb` abgerufen wurde, hätte sie denselben Hash und die Datei müsste nicht erneut heruntergeladen werden. ### .no_exist (fortgeschritten) Zusätzlich zu den Ordnern `blobs`, `refs` und `snapshots` könnten Sie in Ihrem Cache auch einen `.no_exist` Ordner finden. Dieser Ordner hält fest, welche Dateien Sie einmal versucht haben herunterzuladen, die jedoch nicht auf dem Hub vorhanden sind. Seine Struktur ist dieselbe wie der `snapshots` Ordner mit einem Unterordner pro bekannter Revision: ``` //.no_exist/aaaaaa/config_that_does_not_exist.json ``` Im Gegensatz zum `snapshots` Ordner handelt es sich bei den Dateien um einfache leere Dateien (keine Symlinks). In diesem Beispiel existiert die Datei `"config_that_does_not_exist.json"` nicht auf dem Hub für die Revision `"aaaaaa"`. Da dieser Ordner nur leere Dateien speichert, ist sein Speicherplatzverbrauch vernachlässigbar. Sie fragen sich jetzt vielleicht, warum diese Information überhaupt relevant ist? In einigen Fällen versucht ein Framework, optionale Dateien für ein Modell zu laden. Das Speichern der Nicht-Existenz optionaler Dateien beschleunigt das Laden eines Modells, da 1 HTTP-Anfrage pro möglicher optionaler Datei gespart wird. Dies ist zum Beispiel bei `transformers` der Fall, wo jeder Tokenizer zusätzliche Dateien unterstützen kann. Beim ersten Laden des Tokenizers auf Ihrem Gerät wird im Cache gespeichert, welche optionalen Dateien vorhanden sind (und welche nicht), um die Ladezeit bei den nächsten Initialisierungen zu beschleunigen. Um zu testen, ob eine Datei lokal im Cache gespeichert ist (ohne eine HTTP-Anfrage zu senden), können Sie die [`try_to_load_from_cache`] Hilfsfunktion verwenden. Sie gibt entweder den Dateipfad zurück (falls vorhanden und im Cache gespeichert), das Objekt `_CACHED_NO_EXIST` (wenn die Nicht-Existenz im Cache gespeichert ist) oder `None` (wenn wir es nicht wissen). ```python from huggingface_hub import try_to_load_from_cache, _CACHED_NO_EXIST filepath = try_to_load_from_cache() if isinstance(filepath, str): # file exists and is cached ... elif filepath is _CACHED_NO_EXIST: # non-existence of file is cached ... else: # file is not cached ... ``` ### In der Praxis In der Praxis sollte Ihr Cache folgendermaßen aussehen: ```text [ 96] . └── [ 160] models--julien-c--EsperBERTo-small ├── [ 160] blobs │ ├── [321M] 403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd │ ├── [ 398] 7cb18dc9bafbfcf74629a4b760af1b160957a83e │ └── [1.4K] d7edf6bd2a681fb0175f7735299831ee1b22b812 ├── [ 96] refs │ └── [ 40] main └── [ 128] snapshots ├── [ 128] 2439f60ef33a0d46d85da5001d52aeda5b00ce9f │ ├── [ 52] README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812 │ └── [ 76] pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd └── [ 128] bbc77c8132af1cc5cf678da3f1ddf2de43606d48 ├── [ 52] README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e └── [ 76] pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd ``` ### Einschränkungen Um ein effizientes Cache-System zu haben, verwendet `huggingface-hub` Symlinks. Allerdings werden Symlinks nicht auf allen Maschinen unterstützt. Dies ist eine bekannte Einschränkung, insbesondere bei Windows. Wenn dies der Fall ist, verwendet `huggingface_hub` nicht das `blobs/` Verzeichnis, sondern speichert die Dateien direkt im `snapshots/` Verzeichnis. Dieser Workaround ermöglicht es den Nutzern, Dateien vom Hub auf genau die gleiche Weise herunterzuladen und zu cachen. Auch Werkzeuge zur Überprüfung und Löschung des Caches (siehe unten) werden unterstützt. Allerdings ist das Cache-System weniger effizient, da eine einzelne Datei möglicherweise mehrmals heruntergeladen wird, wenn mehrere Revisionen des gleichen Repos heruntergeladen werden. Wenn Sie von dem Symlink-basierten Cache-System auf einem Windows-Gerät profitieren möchten, müssen Sie entweder den [Entwicklermodus aktivieren](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) oder Python als Administrator ausführen. Wenn Symlinks nicht unterstützt werden, wird dem Nutzer eine Warnmeldung angezeigt, um ihn darauf hinzuweisen, dass er eine eingeschränkte Version des Cache-Systems verwendet. Diese Warnung kann durch Setzen der Umgebungsvariable `HF_HUB_DISABLE_SYMLINKS_WARNING` auf true deaktiviert werden. ## Assets zwischenspeichern Zusätzlich zum Zwischenspeichern von Dateien aus dem Hub benötigen nachgelagerte Bibliotheken oft das Zwischenspeichern von anderen Dateien, die in Verbindung mit HF stehen, aber nicht direkt von `huggingface_hub` behandelt werden (zum Beispiel: Dateien, die von GitHub heruntergeladen werden, vorverarbeitete Daten, Protokolle,...). Um diese Dateien, die als `assets` bezeichnet werden, zwischenzuspeichern, kann man [`cached_assets_path`] verwenden. Dieser kleine Helfer generiert Pfade im HF-Cache auf eine einheitliche Weise, basierend auf dem Namen der anfragenden Bibliothek und optional auf einem Namensraum und einem Unterordnernamen. Das Ziel ist, dass jede nachgelagerte Bibliothek ihre Assets auf ihre eigene Weise verwaltet (z.B. keine Regelung über die Struktur), solange sie im richtigen Assets-Ordner bleibt. Diese Bibliotheken können dann die Werkzeuge von `huggingface_hub` nutzen, um den Cache zu verwalten, insbesondere um Teile der Assets über einen CLI-Befehl zu scannen und zu löschen. ```py from huggingface_hub import cached_assets_path assets_path = cached_assets_path(library_name="datasets", namespace="SQuAD", subfolder="download") something_path = assets_path / "something.json" # Machen Sie, was Sie möchten, in Ihrem Assets-Ordner! ``` > [!TIP] > [`cached_assets_path`] ist der empfohlene Weg, um Assets zu speichern, ist jedoch nicht verpflichtend. > Wenn Ihre Bibliothek bereits ihren eigenen Cache verwendet, können Sie diesen gerne nutzen! ### Assets in der Praxis In der Praxis sollte Ihr Assets-Cache wie der folgende Verzeichnisbaum aussehen: ```text assets/ └── datasets/ │ ├── SQuAD/ │ │ ├── downloaded/ │ │ ├── extracted/ │ │ └── processed/ │ ├── Helsinki-NLP--tatoeba_mt/ │ ├── downloaded/ │ ├── extracted/ │ └── processed/ └── transformers/ ├── default/ │ ├── something/ ├── bert-base-cased/ │ ├── default/ │ └── training/ hub/ └── models--julien-c--EsperBERTo-small/ ├── blobs/ │ ├── (...) │ ├── (...) ├── refs/ │ └── (...) └── [ 128] snapshots/ ├── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/ │ ├── (...) └── bbc77c8132af1cc5cf678da3f1ddf2de43606d48/ └── (...) ``` ## Cache scannen Derzeit werden zwischengespeicherte Dateien nie aus Ihrem lokalen Verzeichnis gelöscht: Wenn Sie eine neue Revision eines Zweiges herunterladen, werden vorherige Dateien aufbewahrt, falls Sie sie wieder benötigen. Daher kann es nützlich sein, Ihr Cache-Verzeichnis zu scannen, um zu erfahren, welche Repos und Revisionen den meisten Speicherplatz beanspruchen. `huggingface_hub` bietet einen Helfer dafür, der über `hf` oder in einem Python-Skript verwendet werden kann. ### Cache im Terminal prüfen Die bequemste Möglichkeit, Ihren HF-Cache zu untersuchen, ist der Befehl `hf cache ls`. Er listet standardmäßig alle gecachten Repositories zusammen mit Größe, letzter Nutzung und Referenzen auf. ```text ➜ hf cache ls ID SIZE LAST_ACCESSED LAST_MODIFIED REFS ------------------------------------ ------- ------------- ------------- ------------------- dataset/glue 116.3K 4 days ago 4 days ago 2.4.0 main 1.17.0 dataset/google/fleurs 64.9M 1 week ago 1 week ago main refs/pr/1 model/Jean-Baptiste/camembert-ner 441.0M 2 weeks ago 16 hours ago main model/bert-base-cased 1.9G 1 week ago 2 years ago model/t5-base 10.1K 3 months ago 3 months ago main model/t5-small 970.7M 3 days ago 3 days ago main refs/pr/1 Found 6 repo(s) for a total of 12 revision(s) and 3.4G on disk. ``` Mit `--revisions` wechseln Sie zur Ansicht auf Snapshot-Ebene. Filter akzeptieren menschenlesbare Werte, sodass Ausdrücke wie `size>1GB` oder `accessed>30d` sofort funktionieren: ```text ➜ hf cache ls --revisions --filter "size>1GB" --filter "accessed>30d" ID REVISION SIZE LAST_MODIFIED REFS ------------------------------------ ------------------ ------- ------------- ------------------- model/bert-base-cased 6d1d7a1a2a6cf4c2 1.9G 2 years ago model/t5-small 1c610f6b3f5e7d8a 1.1G 3 months ago main Found 2 repo(s) for a total of 2 revision(s) and 3.0G on disk. ``` Brauchen Sie maschinenlesbare Ausgaben? `--format json` liefert strukturierte Objekte, `--format csv` erzeugt durch Komma getrennte Zeilen und `--quiet` gibt nur Kennungen aus. Alle Varianten lassen sich mit `--cache-dir` kombinieren, wenn Ihr Cache nicht unter `HF_HOME` liegt. #### Mit Shell-Tools filtern Die Tabellen-Ausgabe lässt sich weiterhin mit bekannten Tools verarbeiten. Das folgende Beispiel zeigt alle Revisionen für `t5-small`: ```text ➜ eval "hf cache ls --revisions" | grep "t5-small" model/t5-small 1c610f6b3f5e7d8a 1.1G 3 months ago main model/t5-small 8f3ad1c90fed7a62 820.1M 2 weeks ago refs/pr/1 ``` ### Den Cache von Python aus scannen Für eine erweiterte Nutzung verwenden Sie [`scan_cache_dir`], welches das von dem CLI-Tool aufgerufene Python-Dienstprogramm ist. Sie können es verwenden, um einen detaillierten Bericht zu erhalten, der um 4 Datenklassen herum strukturiert ist: - [`HFCacheInfo`]: vollständiger Bericht, der von [`scan_cache_dir`] zurückgegeben wird - [`CachedRepoInfo`]: Informationen über ein gecachtes Repo - [`CachedRevisionInfo`]: Informationen über eine gecachtes Revision (z.B. "snapshot) in einem Repo - [`CachedFileInfo`]: Informationen über eine gecachte Datei in einem Snapshot Hier ist ein einfaches Anwendungs-Beispiel in Python. Siehe Referenz für Details. ```py >>> from huggingface_hub import scan_cache_dir >>> hf_cache_info = scan_cache_dir() HFCacheInfo( size_on_disk=3398085269, repos=frozenset({ CachedRepoInfo( repo_id='t5-small', repo_type='model', repo_path=PosixPath(...), size_on_disk=970726914, nb_files=11, last_accessed=1662971707.3567169, last_modified=1662971107.3567169, revisions=frozenset({ CachedRevisionInfo( commit_hash='d78aea13fa7ecd06c29e3e46195d6341255065d5', size_on_disk=970726339, snapshot_path=PosixPath(...), # No `last_accessed` as blobs are shared among revisions last_modified=1662971107.3567169, files=frozenset({ CachedFileInfo( file_name='config.json', size_on_disk=1197 file_path=PosixPath(...), blob_path=PosixPath(...), blob_last_accessed=1662971707.3567169, blob_last_modified=1662971107.3567169, ), CachedFileInfo(...), ... }), ), CachedRevisionInfo(...), ... }), ), CachedRepoInfo(...), ... }), warnings=[ CorruptedCacheException("Snapshots dir doesn't exist in cached repo: ..."), CorruptedCacheException(...), ... ], ) ``` ## Cache leeren Das Durchsuchen Ihres Caches ist interessant, aber was Sie normalerweise als Nächstes tun möchten, ist einige Teile zu löschen, um Speicherplatz freizugeben. Dies gelingt mit den CLI-Befehlen `hf cache rm` und `hf cache prune`. Alternativ können Sie programmatisch den [`~HFCacheInfo.delete_revisions`]-Helfer des zurückgegebenen [`HFCacheInfo`]-Objekts nutzen. ### Löschstrategie Um einige Cache zu löschen, müssen Sie eine Liste von Revisionen übergeben, die gelöscht werden sollen. Das Tool wird eine Strategie definieren, um den Speicherplatz auf der Grundlage dieser Liste freizugeben. Es gibt ein [`DeleteCacheStrategy`] Objekt zurück, das beschreibt, welche Dateien und Ordner gelöscht werden. Die [`DeleteCacheStrategy`] zeigt Ihnen, wie viel Speicherplatz voraussichtlich frei wird. Sobald Sie mit der Löschung einverstanden sind, müssen Sie sie ausführen, um die Löschung wirksam zu machen. Um Abweichungen zu vermeiden, können Sie ein Strategieobjekt nicht manuell bearbeiten. Die Strategie zur Löschung von Revisionen ist folgende: - Der Ordner `snapshot`, der die Revisions-Symlinks enthält, wird gelöscht. - Blob-Dateien, die nur von zu löschenden Revisionen verlinkt werden, werden ebenfalls gelöscht. - Wenn eine Revision mit 1 oder mehreren `refs` verknüpft ist, werden die Referenzen gelöscht. - Werden alle Revisionen aus einem Repo gelöscht, wird das gesamte zwischengespeicherte Repository gelöscht. > [!TIP] > Revisions-Hashes sind eindeutig über alle Repositories hinweg. `hf cache rm` akzeptiert daher sowohl > Repository-Kennungen (z. B. `model/bert-base-uncased`) als auch einzelne Revisions-Hashes – bei einem Hash > müssen Sie das Repository nicht zusätzlich angeben. > [!WARNING] > Wenn eine Revision im Cache nicht gefunden wird, wird sie stillschweigend ignoriert. Außerdem wird, wenn eine Datei > oder ein Ordner beim Versuch, ihn zu löschen, nicht gefunden wird, eine Warnung protokolliert, aber es wird kein > Fehler ausgelöst. Die Löschung wird für andere Pfade im > [`DeleteCacheStrategy`] Objekt fortgesetzt. ### Cache vom Terminal aus leeren Verwenden Sie `hf cache rm`, um gecachte Repositories oder einzelne Revisionen zu löschen. Übergeben Sie dazu eine oder mehrere Repository-Kennungen (z. B. `model/bert-base-uncased`) oder Revisions-Hashes: ```text ➜ hf cache rm model/bert-base-cased About to delete 1 repo(s) totalling 1.9G. - model/bert-base-cased (entire repo) Proceed with deletion? [y/N]: y Deleted 1 repo(s) and 1 revision(s); freed 1.9G. ``` Sie können Repositories und spezifische Revisionen mischen. Nutzen Sie `--dry-run`, um den Effekt vorab zu prüfen, oder `--yes`, wenn keine Rückfrage erscheinen soll: ```text ➜ 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. ``` Wenn Ihr Cache nicht im Standardverzeichnis liegt, kombinieren Sie den Befehl mit `--cache-dir PFAD`. Zum Aufräumen verwaister Snapshots steht `hf cache prune` bereit. Der Befehl entfernt automatisch alle Revisionen ohne Referenz: ```text ➜ hf cache prune About to delete 3 unreferenced revision(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); freed 2.4G. ``` Beide Befehle unterstützen `--dry-run`, `--yes` und `--cache-dir`, sodass Sie Vorschauen erzeugen, Automatisierungen bauen und alternative Cache-Verzeichnisse angeben können. ### Cache aus Python leeren Für mehr Flexibilität können Sie auch die Methode [`~HFCacheInfo.delete_revisions`] programmatisch verwenden. Hier ist ein einfaches Beispiel. Siehe Referenz für Details. ```py >>> from huggingface_hub import scan_cache_dir >>> delete_strategy = scan_cache_dir().delete_revisions( ... "81fd1d6e7847c99f5862c9fb81387956d99ec7aa" ... "e2983b237dccf3ab4937c97fa717319a9ca1a96d", ... "6c0e6080953db56375760c0471a8c5f2929baf11", ... ) >>> print("Will free " + delete_strategy.expected_freed_size_str) Will free 8.6G >>> delete_strategy.execute() Cache deletion done. Saved 8.6G. ``` huggingface_hub-1.1.5/docs/source/de/guides/manage-spaces.md000066400000000000000000000336731510763414300237710ustar00rootroot00000000000000 # Verwalten Ihres Spaces (Bereiches) In diesem Leitfaden werden wir sehen, wie man den Laufzeitbereich eines Space ([Geheimnisse (Secrets)](https://huggingface.co/docs/hub/spaces-overview#managing-secrets), [Hardware](https://huggingface.co/docs/hub/spaces-gpus) und Speicher (Storage)) mit `huggingface_hub` verwaltet. ## Ein einfaches Beispiel: Konfigurieren von Geheimnissen und Hardware Hier ist ein End-to-End-Beispiel, um einen Space auf dem Hub zu erstellen und einzurichten. **1. Einen Space auf dem Hub erstellen.** ```py >>> from huggingface_hub import HfApi >>> repo_id = "Wauplin/my-cool-training-space" >>> api = HfApi() # Zum Beispiel mit einem Gradio SDK >>> api.create_repo(repo_id=repo_id, repo_type="space", space_sdk="gradio") ``` **1. (bis) Duplizieren eines Space.** Das kann nützlich sein, wenn Sie auf einem bestehenden Space aufbauen möchten, anstatt von Grund auf neu zu beginnen. Es ist auch nützlich, wenn Sie die Kontrolle über die Konfiguration/Einstellungen eines öffentlichen Space haben möchten. Siehe [`duplicate_space`] für weitere Details. ```py >>> api.duplicate_space("multimodalart/dreambooth-training") ``` **2. Code mit bevorzugter Lösung hochladen.** Hier ist ein Beispiel, wie man den lokalen Ordner `src/` von Ihrem Computer in Ihren Space hochlädt: ```py >>> api.upload_folder(repo_id=repo_id, repo_type="space", folder_path="src/") ``` In diesem Schritt sollte Ihre App bereits kostenlos auf dem Hub laufen! Möglicherweise möchten Sie sie jedoch weiterhin mit Geheimnissen und aufgerüsteter Hardware konfigurieren. **3. Konfigurieren von Geheimnissen und Variablen** Ihr Space könnte einige geheime Schlüssel, Tokens oder Variablen benötigen, um zu funktionieren. Siehe [Dokumentation](https://huggingface.co/docs/hub/spaces-overview#managing-secrets) für weitere Details. Zum Beispiel ein HF-Token, um einen Bilddatensatz auf den Hub hochzuladen, sobald er aus Ihrem Space generiert wurde. ```py >>> api.add_space_secret(repo_id=repo_id, key="HF_TOKEN", value="hf_api_***") >>> api.add_space_variable(repo_id=repo_id, key="MODEL_REPO_ID", value="user/repo") ``` Geheimnisse und Variablen können auch gelöscht werden: ```py >>> api.delete_space_secret(repo_id=repo_id, key="HF_TOKEN") >>> api.delete_space_variable(repo_id=repo_id, key="MODEL_REPO_ID") ``` > [!TIP] > Innerhalb Ihres Space sind Geheimnisse als Umgebungsvariablen verfügbar (oder > Streamlit Secrets Management, wenn Streamlit verwendet wird). Keine Notwendigkeit, sie über die API abzurufen! > [!WARNING] > Jede Änderung in der Konfiguration Ihres Space (Geheimnisse oder Hardware) wird einen Neustart Ihrer App auslösen. **Bonus: Geheimnisse und Variablen beim Erstellen oder Duplizieren des Space festlegen!** Geheimnisse und Variablen können beim Erstellen oder Duplizieren eines Space gesetzt werden: ```py >>> api.create_repo( ... repo_id=repo_id, ... repo_type="space", ... space_sdk="gradio", ... space_secrets=[{"key"="HF_TOKEN", "value"="hf_api_***"}, ...], ... space_variables=[{"key"="MODEL_REPO_ID", "value"="user/repo"}, ...], ... ) ``` ```py >>> api.duplicate_space( ... from_id=repo_id, ... secrets=[{"key"="HF_TOKEN", "value"="hf_api_***"}, ...], ... variables=[{"key"="MODEL_REPO_ID", "value"="user/repo"}, ...], ... ) ``` **4. Konfigurieren von Hardware** Standardmäßig wird Ihr Space kostenlos in einer CPU-Umgebung ausgeführt. Sie können die Hardware aktualisieren, um sie auf GPUs laufen zu lassen. Eine Zahlungskarte oder ein Community-Grant wird benötigt, um Ihren Space zu aktualisieren. Siehe [Dokumentation](https://huggingface.co/docs/hub/spaces-gpus) für weitere Details. ```py # Verwenden von `SpaceHardware` Enum >>> from huggingface_hub import SpaceHardware >>> api.request_space_hardware(repo_id=repo_id, hardware=SpaceHardware.T4_MEDIUM) # Oder einfach einen String-Wert angeben >>> api.request_space_hardware(repo_id=repo_id, hardware="t4-medium") ``` Hardware-Aktualisierungen erfolgen nicht sofort, da Ihr Space auf unseren Servern neu geladen werden muss. Jederzeit können Sie überprüfen, auf welcher Hardware Ihr Space läuft, um zu sehen, ob Ihre Anfrage erfüllt wurde. ```py >>> runtime = api.get_space_runtime(repo_id=repo_id) >>> runtime.stage "RUNNING_BUILDING" >>> runtime.hardware "cpu-basic" >>> runtime.requested_hardware "t4-medium" ``` Sie verfügen jetzt über einen vollständig konfigurierten Space. Stellen Sie sicher, dass Sie Ihren Space wieder auf "cpu-classic" zurückstufen, wenn Sie ihn nicht mehr verwenden. **Bonus: Hardware beim Erstellen oder Duplizieren des Space anfordern!** Aktualisierte Hardware wird Ihrem Space automatisch zugewiesen, sobald er erstellt wurde. ```py >>> api.create_repo( ... repo_id=repo_id, ... repo_type="space", ... space_sdk="gradio" ... space_hardware="cpu-upgrade", ... space_storage="small", ... space_sleep_time="7200", # 2 hours in secs ... ) ``` ```py >>> api.duplicate_space( ... from_id=repo_id, ... hardware="cpu-upgrade", ... storage="small", ... sleep_time="7200", # 2 hours in secs ... ) ``` **5. Pausieren und Neustarten des Spaces** Standardmäßig, wenn Ihr Space auf augewerteter Hardware läuft, wird er nie angehalten. Um jedoch zu vermeiden, dass Ihnen Gebühren berechnet werden, möchten Sie ihn möglicherweise anhalten, wenn Sie ihn nicht verwenden. Dies ist mit [`pause_space`] möglich. Ein pausierter Space bleibt inaktiv, bis der Besitzer des Space ihn entweder über die Benutzeroberfläche oder über die API mit [`restart_space`] neu startet. Weitere Informationen zum Pausenmodus finden Sie in [diesem Abschnitt](https://huggingface.co/docs/hub/spaces-gpus#pause). ```py # Pausieren des Space, um Gebühren zu vermeiden >>> api.pause_space(repo_id=repo_id) # (...) # Erneut starten, wenn benötigt >>> api.restart_space(repo_id=repo_id) ``` Eine weitere Möglichkeit besteht darin, für Ihren Space einen Timeout festzulegen. Wenn Ihr Space länger als die Timeout-Dauer inaktiv ist, wird er in den Schlafmodus versetzt. Jeder Besucher, der auf Ihren Space zugreift, wird ihn wieder starten. Sie können ein Timeout mit [`set_space_sleep_time`] festlegen. Weitere Informationen zum Schlafmodus finden Sie in [diesem Abschnitt](https://huggingface.co/docs/hub/spaces-gpus#sleep-time). ```py # Setzen den Space nach 1h Inaktivität in den Schlafmodus >>> api.set_space_sleep_time(repo_id=repo_id, sleep_time=3600) ``` Hinweis: Wenn Sie eine 'cpu-basic' Hardware verwenden, können Sie keine benutzerdefinierte Schlafzeit konfigurieren. Ihr Space wird automatisch nach 48h Inaktivität pausiert. **Bonus: Schlafzeit festlegen, während der Hardwareanforderung** Aufgewertete Hardware wird Ihrem Space automatisch zugewiesen, sobald er erstellt wurde. ```py >>> api.request_space_hardware(repo_id=repo_id, hardware=SpaceHardware.T4_MEDIUM, sleep_time=3600) ``` **Bonus: Schlafzeit beim Erstellen oder Duplizieren des Space festlegen!** ```py >>> api.create_repo( ... repo_id=repo_id, ... repo_type="space", ... space_sdk="gradio" ... space_hardware="t4-medium", ... space_sleep_time="3600", ... ) ``` ```py >>> api.duplicate_space( ... from_id=repo_id, ... hardware="t4-medium", ... sleep_time="3600", ... ) ``` **6. Dem Space dauerhaften Speicherplatz hinzufügen** Sie können den Speicher-Tier Ihrer Wahl auswählen, um auf Festplattenspeicher zuzugreifen, der Neustarts Ihres Space überdauert. Dies bedeutet, dass Sie von der Festplatte lesen und darauf schreiben können, wie Sie es von einer herkömmlichen Festplatte gewöhnt sind. Weitere Informationen finden Sie in der [Dokumentation](https://huggingface.co/docs/hub/spaces-storage#persistent-storage) . ```py >>> from huggingface_hub import SpaceStorage >>> api.request_space_storage(repo_id=repo_id, storage=SpaceStorage.LARGE) ``` Sie können auch Ihren Speicher löschen und dabei alle Daten dauerhaft verlieren. ```py >>> api.delete_space_storage(repo_id=repo_id) ``` Hinweis: Nachdem Ihnen ein Speicher-Tier zugewiesen wurde, können Sie diesen nicht mehr herabsetzen. Um dies zu tun, müssen Sie zuerst den Speicher löschen und dann den gewünschten Tier anfordern. **Bonus: Speicher beim Erstellen oder Duplizieren des Space anfordern!** ```py >>> api.create_repo( ... repo_id=repo_id, ... repo_type="space", ... space_sdk="gradio" ... space_storage="large", ... ) ``` ```py >>> api.duplicate_space( ... from_id=repo_id, ... storage="large", ... ) ``` ## Fortgeschritten: Temporäres Space Upgrade Spaces ermöglichen viele verschiedene Einsatzmöglichkeiten. Manchmal möchten Sie vielleicht einen Space vorübergehend auf einer bestimmten Hardware ausführen, etwas tun und ihn dann herunterfahren. In diesem Abschnitt werden wir untersuchen, wie Sie die Vorteile von Spaces nutzen können, um ein Modell auf Abruf zu finetunen. Dies ist nur eine Möglichkeit, dieses spezielle Problem zu lösen. Es sollte als Vorschlag betrachtet und an Ihren Anwendungsfall angepasst werden. Nehmen wir an, wir haben einen Space, um ein Modell zu finetunen. Es handelt sich um eine Gradio-App, die ein Modell-Id und eine Dataset-Id als Eingabe nimmt. Der Ablauf sieht folgendermaßen aus: 0. (Den Benutzer nach einem Modell und einem Datensatz auffordern) 1. Das Modell aus dem Hub laden. 2. Den Datensatz aus dem Hub laden. 3. Das Modell mit dem Datensatz finetunen. 4. Das neue Modell auf den Hub hochladen. Schritt 3 erfordert eine spezielle Hardware, aber Sie möchten nicht, dass Ihr Space die ganze Zeit auf einer kostenpflichtigen GPU läuft. Eine Lösung besteht darin, dynamisch Hardware für das Training anzufordern und es anschließend herunterzufahren. Da das Anfordern von Hardware Ihren Space neu startet, muss sich Ihre App irgendwie die aktuelle Aufgabe "merken", die sie ausführt. Es gibt mehrere Möglichkeiten, dies zu tun. In diesem Leitfaden sehen wir eine Lösung, bei der ein Datensatz als "Aufgabenplaner (task scheduler)" verwendet wird. ### App-Grundgerüst So würde Ihre App aussehen. Beim Start überprüfen, ob eine Aufgabe geplant ist und ob ja, führen Sie sie auf der richtigen Hardware aus. Ist die Aufgabe erledigt, setzen Sie die Hardware zurück auf den kostenlosen CPU-Plan und fordern den Benutzer auf, eine neue Aufgabe anzufordern. > [!WARNING] > Ein solcher Workflow unterstützt keinen gleichzeitigen Zugriff wie normale Demos. > Insbesondere wird die Schnittstelle deaktiviert, wenn das Training stattfindet. > Es ist vorzuziehen, Ihr Repo auf privat zu setzen, um sicherzustellen, dass Sie der einzige Benutzer sind. ```py # Für den Space wird Ihr Token benötigt, um Hardware anzufordern: Legen Sie es als Geheimnis fest! HF_TOKEN = os.environ.get("HF_TOKEN") # Eigene repo_id des Space TRAINING_SPACE_ID = "Wauplin/dreambooth-training" from huggingface_hub import HfApi, SpaceHardware api = HfApi(token=HF_TOKEN) # Beim Start des Space überprüfen, ob eine Aufgabe geplant ist. Wenn ja, finetunen Sie das Modell. # Wenn nicht, zeigen Sie eine Schnittstelle an, um eine neue Aufgabe anzufordern. task = get_task() if task is None: # Starten der Gradio-App def gradio_fn(task): # Bei Benutzeranfrage, Aufgabe hinzufügen und Hardware anfordern add_task(task) api.request_space_hardware(repo_id=TRAINING_SPACE_ID, hardware=SpaceHardware.T4_MEDIUM) gr.Interface(fn=gradio_fn, ...).launch() else: runtime = api.get_space_runtime(repo_id=TRAINING_SPACE_ID) # Überprüfen, ob der Space mit einer GPU geladen ist. if runtime.hardware == SpaceHardware.T4_MEDIUM: # Wenn ja, finetunen des Basismodells auf den Datensatz! train_and_upload(task) # Dann die Aufgabe als "DONE / ERLEDIGT" markieren mark_as_done(task) # NICHT VERGESSEN: CPU-Hardware zurück setzen api.request_space_hardware(repo_id=TRAINING_SPACE_ID, hardware=SpaceHardware.CPU_BASIC) else: api.request_space_hardware(repo_id=TRAINING_SPACE_ID, hardware=SpaceHardware.T4_MEDIUM) ``` ### Aufgabenplaner (Task scheduler) Das Planen von Aufgaben kann auf viele Arten erfolgen. Hier ist ein Beispiel, wie es mit einer einfachen CSV gemacht werden könnte, die als Datensatz gespeichert ist. ```py # Dataset-ID, in der eine `tasks.csv` Datei die auszuführenden Aufgaben enthält. # Hier ist ein einfaches Beispiel für `tasks.csv`, das Eingaben (Basis-Modell und Datensatz) # und Status (PENDING / AUSSTEHEND oder DONE / ERLEDIGT) enthält. # multimodalart/sd-fine-tunable,Wauplin/concept-1,DONE # multimodalart/sd-fine-tunable,Wauplin/concept-2,PENDING TASK_DATASET_ID = "Wauplin/dreambooth-task-scheduler" def _get_csv_file(): return hf_hub_download(repo_id=TASK_DATASET_ID, filename="tasks.csv", repo_type="dataset", token=HF_TOKEN) def get_task(): with open(_get_csv_file()) as csv_file: csv_reader = csv.reader(csv_file, delimiter=',') for row in csv_reader: if row[2] == "PENDING": return row[0], row[1] # model_id, dataset_id def add_task(task): model_id, dataset_id = task with open(_get_csv_file()) as csv_file: with open(csv_file, "r") as f: tasks = f.read() api.upload_file( repo_id=repo_id, repo_type=repo_type, path_in_repo="tasks.csv", # Schnelle und einfache Möglichkeit, eine Aufgabe hinzuzufügen path_or_fileobj=(tasks + f"\n{model_id},{dataset_id},PENDING").encode() ) def mark_as_done(task): model_id, dataset_id = task with open(_get_csv_file()) as csv_file: with open(csv_file, "r") as f: tasks = f.read() api.upload_file( repo_id=repo_id, repo_type=repo_type, path_in_repo="tasks.csv", # Schnelle und einfache Möglichkeit, die Aufgabe als DONE / ERLEDIGT zu markieren path_or_fileobj=tasks.replace( f"{model_id},{dataset_id},PENDING", f"{model_id},{dataset_id},DONE" ).encode() ) ``` huggingface_hub-1.1.5/docs/source/de/guides/model-cards.md000066400000000000000000000225041510763414300234460ustar00rootroot00000000000000 # Erstellen und Teilen von Model Cards Die `huggingface_hub`-Bibliothek bietet eine Python-Schnittstelle zum Erstellen, Teilen und Aktualisieren von Model Cards. Besuchen Sie [die spezielle Dokumentationsseite](https://huggingface.co/docs/hub/models-cards) für einen tieferen Einblick in das, was Model Cards im Hub sind und wie sie unter der Haube funktionieren. > [!TIP] > [Neu (Beta)! Probieren Sie unsere experimentelle Model Card Creator App aus](https://huggingface.co/spaces/huggingface/Model_Cards_Writing_Tool) ## Eine Model Card vom Hub laden Um eine bestehende Karte vom Hub zu laden, können Sie die Funktion [`ModelCard.load`] verwenden. Hier laden wir die Karte von [`nateraw/vit-base-beans`](https://huggingface.co/nateraw/vit-base-beans). ```python from huggingface_hub import ModelCard card = ModelCard.load('nateraw/vit-base-beans') ``` Diese Karte hat einige nützliche Attribute, auf die Sie zugreifen oder die Sie nutzen möchten: - `card.data`: Gibt eine [`ModelCardData`]-Instanz mit den Metadaten der Model Card zurück. Rufen Sie `.to_dict()` auf diese Instanz auf, um die Darstellung als Wörterbuch zu erhalten. - `card.text`: Gibt den Textinhalt der Karte *ohne den Metadatenkopf* zurück. - `card.content`: Gibt den Textinhalt der Karte, *einschließlich des Metadatenkopfes*, zurück. ## Model Cards erstellen ### Aus Text Um eine Model Card aus Text zu initialisieren, übergeben Sie einfach den Textinhalt der Karte an `ModelCard` beim Initialisieren. ```python content = """ --- language: en license: mit --- # My Model Card """ card = ModelCard(content) card.data.to_dict() == {'language': 'en', 'license': 'mit'} # True ``` Eine andere Möglichkeit besteht darin, dies mit f-Strings zu tun. Im folgenden Beispiel: - Verwenden wir [`ModelCardData.to_yaml`], um die von uns definierten Metadaten in YAML umzuwandeln, damit wir sie in die Model Card einfügen können. - Zeigen wir, wie Sie eine Vorlagenvariable über Python f-Strings verwenden könnten. ```python card_data = ModelCardData(language='en', license='mit', library='timm') example_template_var = 'nateraw' content = f""" --- { card_data.to_yaml() } --- # My Model Card This model created by [@{example_template_var}](https://github.com/{example_template_var}) """ card = ModelCard(content) print(card) ``` Das obige Beispiel würde uns eine Karte hinterlassen, die so aussieht: ``` --- language: en license: mit library: timm --- # My Model Card This model created by [@nateraw](https://github.com/nateraw) ``` ### Aus einem Jinja-Template Wenn Sie `Jinja2` installiert haben, können Sie Model Cards aus einer Jinja-Vorlagendatei erstellen. Schauen wir uns ein einfaches Beispiel an: ```python from pathlib import Path from huggingface_hub import ModelCard, ModelCardData # Definieren Sie Ihre Jinja-Vorlage template_text = """ --- {{ card_data }} --- # Model Card for MyCoolModel This model does this and that. This model was created by [@{{ author }}](https://hf.co/{{author}}). """.strip() # Schreiben Sie die Vorlage in eine Datei Path('custom_template.md').write_text(template_text) # Definieren Sie die Metadaten der Karte card_data = ModelCardData(language='en', license='mit', library_name='keras') # Erstellen Sie eine Karte aus der Vorlage und übergeben Sie dabei alle gewünschten Jinja-Vorlagenvariablen. # In unserem Fall übergeben wir "author" card = ModelCard.from_template(card_data, template_path='custom_template.md', author='nateraw') card.save('my_model_card_1.md') print(card) ``` Das resultierende Karten-Markdown sieht so aus: ``` --- language: en license: mit library_name: keras --- # Model Card for MyCoolModel This model does this and that. This model was created by [@nateraw](https://hf.co/nateraw). ``` Wenn Sie Daten in card.data aktualisieren, wird dies in der Karte selbst widergespiegelt. ``` card.data.library_name = 'timm' card.data.language = 'fr' card.data.license = 'apache-2.0' print(card) ``` Jetzt, wie Sie sehen können, wurde der Metadatenkopf aktualisiert: ``` --- language: fr license: apache-2.0 library_name: timm --- # Model Card for MyCoolModel This model does this and that. This model was created by [@nateraw](https://hf.co/nateraw). ``` Wenn Sie die Karteninformationen aktualisieren, können Sie durch Aufrufen von [`ModelCard.validate`] überprüfen, ob die Karte immer noch gültig für den Hub ist. Dies stellt sicher, dass die Karte alle Validierungsregeln erfüllt, die im Hugging Face Hub eingerichtet wurden. ### Aus dem Standard-Template Anstatt Ihr eigenes Template zu verwenden, können Sie auch das [Standard-Template](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md) verwenden, welches eine vollständig ausgestattete Model Card mit vielen Abschnitten ist, die Sie vielleicht ausfüllen möchten. Unter der Haube verwendet es [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/), um eine Vorlagendatei auszufüllen. > [!TIP] > Beachten Sie, dass Sie Jinja2 installiert haben müssen, um `from_template` zu verwenden. Sie können dies mit `pip install Jinja2` tun. ```python card_data = ModelCardData(language='en', license='mit', library_name='keras') card = ModelCard.from_template( card_data, model_id='my-cool-model', model_description="this model does this and that", developers="Nate Raw", repo="https://github.com/huggingface/huggingface_hub", ) card.save('my_model_card_2.md') print(card) ``` ## Model Cards teilen Wenn Sie mit dem Hugging Face Hub authentifiziert sind (entweder durch Verwendung von `hf auth login` oder [`login`]), können Sie Karten zum Hub hinzufügen, indem Sie einfach [`ModelCard.push_to_hub`] aufrufen. Schauen wir uns an, wie das funktioniert... Zuerst erstellen wir ein neues Repo namens 'hf-hub-modelcards-pr-test' im Namensraum des authentifizierten Benutzers: ```python from huggingface_hub import whoami, create_repo user = whoami()['name'] repo_id = f'{user}/hf-hub-modelcards-pr-test' url = create_repo(repo_id, exist_ok=True) ``` Dann erstellen wir eine Karte aus der Standardvorlage (genau wie die oben definierte): ```python card_data = ModelCardData(language='en', license='mit', library_name='keras') card = ModelCard.from_template( card_data, model_id='my-cool-model', model_description="this model does this and that", developers="Nate Raw", repo="https://github.com/huggingface/huggingface_hub", ) ``` Schließlich laden wir das zum Hub hoch: ```python card.push_to_hub(repo_id) ``` Sie können die resultierende Karte [hier](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/blob/main/README.md) überprüfen. Wenn Sie eine Karte als Pull-Request hinzufügen möchten, können Sie beim Aufruf von `push_to_hub` einfach `create_pr=True` angeben: ```python card.push_to_hub(repo_id, create_pr=True) ``` Ein PR, der mit diesem Befehl erstellt wurde, kann [hier](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/discussions/3) aufgerufen werden. ### Evaluierungsergebnisse einbeziehen Um Evaluierungsergebnisse in den Metadaten `model-index` einzufügen, können Sie ein [`EvalResult`] oder eine Liste von `EvalResult` mit Ihren zugehörigen Evaluierungsergebnissen übergeben. Im Hintergrund wird der `model-index` erstellt, wenn Sie `card.data.to_dict()` aufrufen. Weitere Informationen darüber, wie dies funktioniert, finden Sie in [diesem Abschnitt der Hub-Dokumentation](https://huggingface.co/docs/hub/models-cards#evaluation-results). > [!TIP] > Beachten Sie, dass die Verwendung dieser Funktion erfordert, dass Sie das Attribut `model_name` in [`ModelCardData`] einbeziehen. ```python card_data = ModelCardData( language='en', license='mit', model_name='my-cool-model', eval_results = EvalResult( task_type='image-classification', dataset_type='beans', dataset_name='Beans', metric_type='accuracy', metric_value=0.7 ) ) card = ModelCard.from_template(card_data) print(card.data) ``` Die resultierende `card.data` sollte so aussehen: ``` language: en license: mit model-index: - name: my-cool-model results: - task: type: image-classification dataset: name: Beans type: beans metrics: - type: accuracy value: 0.7 ``` Wenn Sie mehr als ein Evaluierungsergebnis teilen möchten, übergeben Sie einfach eine Liste von `EvalResult`: ```python card_data = ModelCardData( language='en', license='mit', model_name='my-cool-model', eval_results = [ EvalResult( task_type='image-classification', dataset_type='beans', dataset_name='Beans', metric_type='accuracy', metric_value=0.7 ), EvalResult( task_type='image-classification', dataset_type='beans', dataset_name='Beans', metric_type='f1', metric_value=0.65 ) ] ) card = ModelCard.from_template(card_data) card.data ``` Dies sollte Ihnen die folgenden `card.data` hinterlassen: ``` language: en license: mit model-index: - name: my-cool-model results: - task: type: image-classification dataset: name: Beans type: beans metrics: - type: accuracy value: 0.7 - type: f1 value: 0.65 ``` huggingface_hub-1.1.5/docs/source/de/guides/overview.md000066400000000000000000000135601510763414300231240ustar00rootroot00000000000000 # Anleitungen In diesem Abschnitt finden Sie praktische Anleitungen, die Ihnen helfen, ein bestimmtes Ziel zu erreichen. Schauen Sie sich diese Anleitungen an, um zu lernen, wie Sie huggingface_hub verwenden, um reale Probleme zu lösen:
Repository

Wie erstelle ich ein Repository im Hub? Wie konfiguriere ich es? Wie interagiere ich damit?

Dateien herunterladen

Wie lade ich eine Datei vom Hub herunter? Wie lade ich ein Repository herunter?

Dateien hochladen

Wie lade ich eine Datei oder einen Ordner hoch? Wie nehme ich Änderungen an einem bestehenden Repository im Hub vor?

Suche

Wie suche ich effizient in den über 200k öffentlichen Modellen, Datensätzen und Spaces?

HfDateiSystem

Wie interagiere ich mit dem Hub über eine benutzerfreundliche Schnittstelle, die Pythons Dateischnittstelle imitiert?

Inferenz

Wie mache ich Vorhersagen mit der beschleunigten Inference-API?

Community Tab

Wie interagiere ich mit dem Community-Tab (Diskussionen und Pull-Requests)?

Cache

Wie funktioniert das Cache-System? Wie profitiere ich davon?

Model Cards

Wie erstelle und teile ich Model Cards?

Verwalten meines Spaces

Wie verwalte ich die Hardware und Konfiguration meines Spaces?

Als Bibliothek integrieren

Was bedeutet es, eine Bibliothek mit dem Hub zu integrieren? Und wie macht man das?

Webhooks server

Wie erstelle ich einen Server zum Empfangen von Webhooks und setze ihn als Space ein?

huggingface_hub-1.1.5/docs/source/de/guides/repository.md000066400000000000000000000260631510763414300234770ustar00rootroot00000000000000 # Ein Repository erstellen und verwalten Das Hugging Face Hub besteht aus einer Sammlung von Git-Repositories. [Git](https://git-scm.com/) ist ein in der Softwareentwicklung weit verbreitetes Tool, um Projekte bei der Zusammenarbeit einfach zu versionieren. Dieser Leitfaden zeigt Ihnen, wie Sie mit den Repositories auf dem Hub interagieren, insbesondere: - Ein Repository erstellen und löschen. - Zweige (Branches) und Tags verwalten. - Ihr Repository umbenennen. - Die Sichtbarkeit Ihres Repositories aktualisieren. - Eine lokale Kopie Ihres Repositories verwalten. > [!WARNING] > Wenn Sie es gewohnt sind, mit Plattformen wie GitLab/GitHub/Bitbucket zu arbeiten, könnte Ihr erster Instinkt sein, die `git` CLI zu verwenden, um Ihr Repo zu klonen (`git clone`), Änderungen zu übernehmen (`git add`, `git commit`) und diese hochzuladen (`git push`). Dies ist beim Verwenden des Hugging Face Hubs gültig. Softwareentwicklung und maschinelles Lernen haben jedoch nicht dieselben Anforderungen und Arbeitsabläufe. Modell-Repositories könnten große Modellgewichtsdateien für verschiedene Frameworks und Tools beinhalten, sodass das Klonen des Repositories dazu führen kann, dass Sie große lokale Ordner mit massiven Größen pflegen. Daher kann es effizienter sein, unsere benutzerdefinierten HTTP-Methoden zu verwenden. Sie können unsere [Git vs HTTP Paradigma](../concepts/git_vs_http) Erklärungsseite für weitere Details lesen. Wenn Sie ein Repository auf dem Hub erstellen und verwalten möchten, muss Ihr Computer angemeldet sein. Wenn Sie es nicht sind, beziehen Sie sich bitte auf [diesen Abschnitt](../quick-start#login). Im Rest dieses Leitfadens gehen wir davon aus, dass Ihr Computer angemeldet ist. ## Erstellung und Löschung von Repos Der erste Schritt besteht darin, zu wissen, wie man Repositories erstellt und löscht. Sie können nur Repositories verwalten, die Ihnen gehören (unter Ihrem Benutzernamensraum) oder von Organisationen, in denen Sie Schreibberechtigungen haben. ### Ein Repository erstellen Erstellen Sie ein leeres Repository mit [`create_repo`] und geben Sie ihm mit dem Parameter `repo_id` einen Namen. Die `repo_id` ist Ihr Namensraum gefolgt vom Repository-Namen: `username_or_org/repo_name`. ```py >>> from huggingface_hub import create_repo >>> create_repo("lysandre/test-model") 'https://huggingface.co/lysandre/test-model' ``` Standardmäßig erstellt [`create_repo`] ein Modellrepository. Sie können jedoch den Parameter `repo_type` verwenden, um einen anderen Repository-Typ anzugeben. Wenn Sie beispielsweise ein Dataset-Repository erstellen möchten: ```py >>> from huggingface_hub import create_repo >>> create_repo("lysandre/test-dataset", repo_type="dataset") 'https://huggingface.co/datasets/lysandre/test-dataset' ``` Wenn Sie ein Repository erstellen, können Sie mit dem Parameter `private` die Sichtbarkeit Ihres Repositories festlegen. ```py >>> from huggingface_hub import create_repo >>> create_repo("lysandre/test-private", private=True) ``` Wenn Sie die Sichtbarkeit des Repositories zu einem späteren Zeitpunkt ändern möchten, können Sie die Funktion [`update_repo_settings`] verwenden. ### Ein Repository löschen Löschen Sie ein Repository mit [`delete_repo`]. Stellen Sie sicher, dass Sie ein Repository löschen möchten, da dieser Vorgang unwiderruflich ist! Geben Sie die `repo_id` des Repositories an, das Sie löschen möchten: ```py >>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset") ``` ### Ein Repository duplizieren (nur für Spaces) In einigen Fällen möchten Sie möglicherweise das Repo von jemand anderem kopieren, um es an Ihren Anwendungsfall anzupassen. Dies ist für Spaces mit der Methode [`duplicate_space`] möglich. Es wird das gesamte Repository dupliziert. Sie müssen jedoch noch Ihre eigenen Einstellungen konfigurieren (Hardware, Schlafzeit, Speicher, Variablen und Geheimnisse). Weitere Informationen finden Sie in unserem Leitfaden [Verwalten Ihres Spaces](./manage-spaces). ```py >>> from huggingface_hub import duplicate_space >>> duplicate_space("multimodalart/dreambooth-training", private=False) RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...) ``` ## Dateien hochladen und herunterladen Jetzt, wo Sie Ihr Repository erstellt haben, möchten Sie Änderungen daran vornehmen und Dateien daraus herunterladen. Diese 2 Themen verdienen ihre eigenen Leitfäden. Bitte beziehen Sie sich auf die [Hochladen](./upload) und die [Herunterladen](./download) Leitfäden, um zu erfahren, wie Sie Ihr Repository verwenden können. ## Branches und Tags Git-Repositories verwenden oft Branches, um verschiedene Versionen eines gleichen Repositories zu speichern. Tags können auch verwendet werden, um einen bestimmten Zustand Ihres Repositories zu kennzeichnen, z. B. bei der Veröffentlichung einer Version. Allgemeiner gesagt, werden Branches und Tags als [git-Referenzen](https://git-scm.com/book/en/v2/Git-Internals-Git-References) bezeichnet. ### Branches und Tags erstellen Sie können neue Branches und Tags mit [`create_branch`] und [`create_tag`] erstellen: ```py >>> from huggingface_hub import create_branch, create_tag # Erstellen Sie einen Branch auf einem Space-Repo vom `main` Branch >>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker") # Erstellen Sie einen Tag auf einem Dataset-Repo vom `v0.1-release` Branch >>> create_branch("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.") ``` Sie können die Funktionen [`delete_branch`] und [`delete_tag`] auf die gleiche Weise verwenden, um einen Branch oder einen Tag zu löschen. ### Alle Branches und Tags auflisten Sie können auch die vorhandenen git-Referenzen von einem Repository mit [`list_repo_refs`] auflisten: ```py >>> from huggingface_hub import list_repo_refs >>> list_repo_refs("bigcode/the-stack", repo_type="dataset") GitRefs( branches=[ GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'), GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714') ], converts=[], tags=[ GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da') ] ) ``` ## Repository-Einstellungen ändern Repositories verfügen über einige Einstellungen, die Sie konfigurieren können. Die meiste Zeit möchten Sie dies manuell auf der Repo-Einstellungsseite in Ihrem Browser tun. Sie müssen Schreibzugriff auf ein Repo haben, um es zu konfigurieren (entweder besitzen oder Teil einer Organisation sein). In diesem Abschnitt werden wir die Einstellungen sehen, die Sie auch programmgesteuert mit `huggingface_hub` konfigurieren können. Einige Einstellungen sind spezifisch für Spaces (Hardware, Umgebungsvariablen,...). Um diese zu konfigurieren, lesen Sie bitte unseren [Verwalten Ihres Spaces](../guides/manage-spaces) Leitfaden. ### Sichtbarkeit aktualisieren Ein Repository kann öffentlich oder privat sein. Ein privates Repository ist nur für Sie oder die Mitglieder der Organisation sichtbar, in der das Repository sich befindet. Ändern Sie ein Repository wie im Folgenden gezeigt in ein privates: ```py >>> from huggingface_hub import update_repo_settings >>> update_repo_settings(repo_id=repo_id, private=True) ``` ### Benennen Sie Ihr Repository um Sie können Ihr Repository auf dem Hub mit [`move_repo] umbenennen. Mit dieser Methode können Sie das Repo auch von einem Benutzer zu einer Organisation verschieben. Dabei gibt es [einige Einschränkungen](https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo), die Sie beachten sollten. Zum Beispiel können Sie Ihr Repo nicht an einen anderen Benutzer übertragen. ```py >>> from huggingface_hub import move_repo >>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model") ``` ## Verwalten Sie eine lokale Kopie Ihres Repositories Alle oben beschriebenen Aktionen können mit HTTP-Anfragen durchgeführt werden. In einigen Fällen möchten Sie jedoch vielleicht eine lokale Kopie Ihres Repositories haben und damit interagieren, indem Sie die Git-Befehle verwenden, die Sie kennen. Die [`Repository`] Klasse ermöglicht es Ihnen, mit Dateien und Repositories auf dem Hub mit Funktionen zu interagieren, die Git-Befehlen ähneln. Es ist ein Wrapper über Git und Git-LFS-Methoden, um die Git-Befehle zu verwenden, die Sie bereits kennen und lieben. Stellen Sie vor dem Start sicher, dass Sie Git-LFS installiert haben (siehe [hier](https://git-lfs.github.com/) für Installationsanweisungen). ### Verwenden eines lokalen Repositories Instanziieren Sie ein [`Repository`] Objekt mit einem Pfad zu einem lokalen Repository: ```py >>> from huggingface_hub import Repository >>> repo = Repository(local_dir="//") ``` ### Klonen Der `clone_from` Parameter klont ein Repository von einer Hugging Face Repository-ID in ein lokales Verzeichnis, das durch das Argument `local_dir` angegeben wird: ```py >>> from huggingface_hub import Repository >>> repo = Repository(local_dir="w2v2", clone_from="facebook/wav2vec2-large-960h-lv60") ``` `clone_from` kann auch ein Repository mit einer URL klonen: ```py >>> repo = Repository(local_dir="huggingface-hub", clone_from="https://huggingface.co/facebook/wav2vec2-large-960h-lv60") ``` Sie können den `clone_from` Parameter mit [`create_repo`] kombinieren, um ein Repository zu erstellen und zu klonen: ```py >>> repo_url = create_repo(repo_id="repo_name") >>> repo = Repository(local_dir="repo_local_path", clone_from=repo_url) ``` Sie können auch einen Git-Benutzernamen und eine E-Mail zu einem geklonten Repository konfigurieren, indem Sie die Parameter `git_user` und `git_email` beim Klonen eines Repositories angeben. Wenn Benutzer Änderungen in diesem Repository committen, wird Git über den Autor des Commits informiert sein. ```py >>> repo = Repository( ... "my-dataset", ... clone_from="/", ... token=True, ... repo_type="dataset", ... git_user="MyName", ... git_email="me@cool.mail" ... ) ``` ### Branch Branches sind wichtig für die Zusammenarbeit und das Experimentieren, ohne Ihre aktuellen Dateien und Codes zu beeinflussen. Wechseln Sie zwischen den Branches mit [`~Repository.git_checkout`]. Wenn Sie beispielsweise von `branch1` zu `branch2` wechseln möchten: ```py >>> from huggingface_hub import Repository >>> repo = Repository(local_dir="huggingface-hub", clone_from="/", revision='branch1') >>> repo.git_checkout("branch2") ``` ### Pull Mit [`~Repository.git_pull`] können Sie eine aktuelle lokale Branch mit Änderungen aus einem Remote-Repository aktualisieren: ```py >>> from huggingface_hub import Repository >>> repo.git_pull() ``` Setzen Sie `rebase=True`, wenn Sie möchten, dass Ihre lokalen Commits nach dem Aktualisieren Ihres Zweigs mit den neuen Commits aus dem Remote erfolgen: ```py >>> repo.git_pull(rebase=True) ``` huggingface_hub-1.1.5/docs/source/de/guides/search.md000066400000000000000000000050521510763414300225200ustar00rootroot00000000000000 # Den Hub durchsuchen In diesem Tutorial lernen Sie, wie Sie Modelle, Datensätze und Spaces auf dem Hub mit `huggingface_hub` durchsuchen können. ## Wie listet man Repositories auf? Die `huggingface_hub`-Bibliothek enthält einen HTTP-Client [`HfApi`], um mit dem Hub zu interagieren. Unter anderem kann er Modelle, Datensätze und Spaces auflisten, die auf dem Hub gespeichert sind: ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> models = api.list_models() ``` Die Ausgabe von [`list_models`] ist ein Iterator über die auf dem Hub gespeicherten Modelle. Ähnlich können Sie [`list_datasets`] verwenden, um Datensätze aufzulisten und [`list_spaces`], um Spaces aufzulisten. ## Wie filtert man Repositories? Das Auflisten von Repositories ist großartig, aber jetzt möchten Sie vielleicht Ihre Suche filtern. Die List-Helfer haben mehrere Attribute wie: - `filter` - `author` - `search` - ... Zwei dieser Parameter sind intuitiv (`author` und `search`), aber was ist mit diesem `filter`? `filter` nimmt als Eingabe ein [`ModelFilter`]-Objekt (oder [`DatasetFilter`]) entgegen. Sie können es instanziieren, indem Sie angeben, welche Modelle Sie filtern möchten. Hier ist ein Beispiel, um alle Modelle auf dem Hub zu erhalten, die Bildklassifizierung durchführen, auf dem Imagenet-Datensatz trainiert wurden und mit PyTorch laufen. Das kann mit einem einzigen [`ModelFilter`] erreicht werden. Attribute werden als "logisches UND" kombiniert. ```py models = hf_api.list_models( filter=ModelFilter( task="image-classification", library="pytorch", trained_dataset="imagenet" ) ) ``` Während des Filterns können Sie auch die Modelle sortieren und nur die Top-Ergebnisse abrufen. Zum Beispiel holt das folgende Beispiel die 5 am häufigsten heruntergeladenen Datensätze auf dem Hub: ```py >>> list(list_datasets(sort="downloads", direction=-1, limit=5)) [DatasetInfo( id='argilla/databricks-dolly-15k-curated-en', author='argilla', sha='4dcd1dedbe148307a833c931b21ca456a1fc4281', last_modified=datetime.datetime(2023, 10, 2, 12, 32, 53, tzinfo=datetime.timezone.utc), private=False, downloads=8889377, (...) ``` Eine andere Möglichkeit, dies zu tun, besteht darin, die [Modelle](https://huggingface.co/models) und [Datensätze](https://huggingface.co/datasets) Seiten in Ihrem Browser zu besuchen, nach einigen Parametern zu suchen und die Werte in der URL anzusehen. huggingface_hub-1.1.5/docs/source/de/guides/upload.md000066400000000000000000001010211510763414300225300ustar00rootroot00000000000000 # Dateien auf den Hub hochladen Das Teilen Ihrer Dateien und Arbeiten ist ein wichtiger Aspekt des Hubs. Das `huggingface_hub` bietet mehrere Optionen, um Ihre Dateien auf den Hub hochzuladen. Sie können diese Funktionen unabhängig verwenden oder sie in Ihre Bibliothek integrieren, um es Ihren Benutzern zu erleichtern, mit dem Hub zu interagieren. In dieser Anleitung erfahren Sie, wie Sie Dateien hochladen: - ohne Git zu verwenden. - mit [Git LFS](https://git-lfs.github.com/) wenn die Dateien sehr groß sind. - mit dem `commit`-Context-Manager. - mit der Funktion [`~Repository.push_to_hub`]. Wenn Sie Dateien auf den Hub hochladen möchten, müssen Sie sich bei Ihrem Hugging Face-Konto anmelden: - Melden Sie sich bei Ihrem Hugging Face-Konto mit dem folgenden Befehl an: ```bash hf auth login # oder mit einer Umgebungsvariable hf auth login --token $HUGGINGFACE_TOKEN ``` - Alternativ können Sie sich in einem Notebook oder einem Skript programmatisch mit [`login`] anmelden: ```python >>> from huggingface_hub import login >>> login() ``` Wenn es in einem Jupyter- oder Colaboratory-Notebook ausgeführt wird, startet [`login`] ein Widget, über das Sie Ihren Hugging Face-Zugriffstoken eingeben können. Andernfalls wird eine Meldung im Terminal angezeigt. Es ist auch möglich, sich programmatisch ohne das Widget anzumelden, indem Sie den Token direkt an [`login`] übergeben. Seien Sie jedoch vorsichtig, wenn Sie Ihr Notebook teilen. Es ist am Besten, den Token aus einem sicheren Passwortspeicher zu laden, anstatt ihn in Ihrem Colaboratory-Notebook zu speichern. ## Datei hochladen Sobald Sie ein Repository mit [`create_repo`] erstellt haben, können Sie mit [`upload_file`] eine Datei in Ihr Repository hochladen. Geben Sie den Pfad der hochzuladenden Datei, den Ort, an den Sie die Datei im Repository hochladen möchten, und den Namen des Repositories an, zu dem Sie die Datei hinzufügen möchten. Abhängig von Ihrem Repository-Typ können Sie optional den Repository-Typ als `dataset`, `model`, oder `space` festlegen. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.upload_file( ... path_or_fileobj="/path/to/local/folder/README.md", ... path_in_repo="README.md", ... repo_id="username/test-dataset", ... repo_type="dataset", ... ) ``` ## Ordner hochladen Verwenden Sie die Funktion [`upload_folder`], um einen lokalen Ordner in ein vorhandenes Repository hochzuladen. Geben Sie den Pfad des lokalen Ordners an, den Sie hochladen möchten, an welchem Ort Sie den Ordner im Repository hochladen möchten, und den Namen des Repositories, zu dem Sie den Ordner hinzufügen möchten. Abhängig von Ihrem Repository-Typ können Sie optional den Repository-Typ als `dataset`, `model`, oder `space` festlegen. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() # Den gesamten Inhalt aus dem lokalen Ordner in den entfernten Space hoch laden. # Standardmäßig werden Dateien im Hauptverzeichnis des Repos hochgeladen >>> api.upload_folder( ... folder_path="/path/to/local/space", ... repo_id="username/my-cool-space", ... repo_type="space", ... ) ``` Verwenden Sie die Argumente `allow_patterns` und `ignore_patterns`, um anzugeben, welche Dateien hochgeladen werden sollen. Diese Parameter akzeptieren entweder ein einzelnes Muster oder eine Liste von Mustern. Muster sind Standard-Wildcards (globbing patterns) wie [hier](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm) dokumentiert. Wenn sowohl `allow_patterns` als auch `ignore_patterns` angegeben werden, gelten beide Einschränkungen. Standardmäßig werden alle Dateien aus dem Ordner hochgeladen. Jeder `.git/`-Ordner in einem Unterverzeichnis wird ignoriert. Bitte beachten Sie jedoch, dass die `.gitignore`-Datei nicht berücksichtigt wird. Dies bedeutet, dass Sie `allow_patterns` und `ignore_patterns` verwenden müssen, um anzugeben, welche Dateien stattdessen hochgeladen werden sollen. ```py >>> api.upload_folder( ... folder_path="/path/to/local/folder", ... path_in_repo="my-dataset/train", # Hochladen in einen bestimmten Ordner ... repo_id="username/test-dataset", ... repo_type="dataset", ... ignore_patterns="**/logs/*.txt", # Alle Textprotokolle ignorieren ... ) ``` Sie können auch das Argument `delete_patterns` verwenden, um Dateien anzugeben, die Sie im selben Commit aus dem Repo löschen möchten. Dies kann nützlich sein, wenn Sie einen entfernten Ordner reinigen möchten, bevor Sie Dateien darin ablegen und nicht wissen, welche Dateien bereits vorhanden sind. Im folgenden Beispiel wird der lokale Ordner `./logs` in den entfernten Ordner `/experiment/logs/` hochgeladen. Es werden nur txt-Dateien hochgeladen, aber davor werden alle vorherigen Protokolle im Repo gelöscht. All dies in einem einzigen Commit. ```py >>> api.upload_folder( ... folder_path="/path/to/local/folder/logs", ... repo_id="username/trained-model", ... path_in_repo="experiment/logs/", ... allow_patterns="*.txt", # Alle lokalen Textdateien hochladen ... delete_patterns="*.txt", # Vorher alle enfernten Textdateien löschen ... ) ``` ## Erweiterte Funktionen In den meisten Fällen benötigen Sie nicht mehr als [`upload_file`] und [`upload_folder`], um Ihre Dateien auf den Hub hochzuladen. Das `huggingface_hub` bietet jedoch fortschrittlichere Funktionen, um die Dinge einfacher zu machen. Schauen wir sie uns an! ### Nicht blockierende Uploads In einigen Fällen möchten Sie Daten hochladen, ohne Ihren Hauptthread zu blockieren. Dies ist besonders nützlich, um Protokolle und Artefakte hochzuladen, während Sie weiter trainieren. Um dies zu tun, können Sie das Argument `run_as_future` in beiden [`upload_file`] und [`upload_folder`] verwenden. Dies gibt ein [`concurrent.futures.Future`](https://docs.python.org/3/library/concurrent.futures.html#future-objects)-Objekt zurück, mit dem Sie den Status des Uploads überprüfen können. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> future = api.upload_folder( # Hochladen im Hintergrund (nicht blockierende Aktion) ... repo_id="username/my-model", ... folder_path="checkpoints-001", ... run_as_future=True, ... ) >>> future Future(...) >>> future.done() False >>> future.result() # Warten bis der Upload abgeschlossen ist (blockierende Aktion) ... ``` > [!TIP] > Hintergrund-Aufgaben werden in die Warteschlange gestellt, wenn `run_as_future=True` verwendet wird. Das bedeutet, dass garantiert wird, dass die Aufgaben in der richtigen Reihenfolge ausgeführt werden. Auch wenn Hintergrundaufgaben hauptsächlich dazu dienen, Daten hochzuladen/Commits zu erstellen, können Sie jede gewünschte Methode in die Warteschlange stellen, indem Sie [`run_as_future`] verwenden. Sie können es beispielsweise verwenden, um ein Repo zu erstellen und dann Daten im Hintergrund dorthin hochzuladen. Das integrierte Argument `run_as_future` in Upload-Methoden ist lediglich ein Alias dafür. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.run_as_future(api.create_repo, "username/my-model", exists_ok=True) Future(...) >>> api.upload_file( ... repo_id="username/my-model", ... path_in_repo="file.txt", ... path_or_fileobj=b"file content", ... run_as_future=True, ... ) Future(...) ``` ### Ordner in Teilen hochladen Mit [`upload_folder`] können Sie ganz einfach einen gesamten Ordner ins Hub hochladen. Bei großen Ordnern (Tausende von Dateien oder Hunderte von GB) kann dies jedoch immer noch herausfordernd sein. Wenn Sie einen Ordner mit vielen Dateien haben, möchten Sie ihn möglicherweise in mehreren Commits hochladen. Wenn während des Uploads ein Fehler oder ein Verbindungsproblem auftritt, müssen Sie den Vorgang nicht von Anfang an wiederholen. Um einen Ordner in mehreren Commits hochzuladen, übergeben Sie einfach `multi_commits=True` als Argument. Intern wird `huggingface_hub` die hochzuladenden/zu löschenden Dateien auflisten und sie in mehrere Commits aufteilen. Die "Strategie" (d.h. wie die Commits aufgeteilt werden) basiert auf der Anzahl und Größe der hochzuladenden Dateien. Ein PR wird im Hub geöffnet, um alle Commits zu pushen. Sobald der PR bereit ist, werden die Commits zu einem einzigen Commit zusammengefasst. Wenn der Prozess unterbrochen wird, bevor er abgeschlossen ist, können Sie Ihr Skript erneut ausführen, um den Upload fortzusetzen. Der erstellte PR wird automatisch erkannt und der Upload setzt dort fort, wo er gestoppt wurde. Es wird empfohlen, `multi_commits_verbose=True` zu übergeben, um ein besseres Verständnis für den Upload und dessen Fortschritt zu erhalten. Das untenstehende Beispiel lädt den Ordner "checkpoints" in ein Dataset in mehreren Commits hoch. Ein PR wird im Hub erstellt und automatisch zusammengeführt, sobald der Upload abgeschlossen ist. Wenn Sie möchten, dass der PR offen bleibt und Sie ihn manuell überprüfen können, übergeben Sie `create_pr=True`. ```py >>> upload_folder( ... folder_path="local/checkpoints", ... repo_id="username/my-dataset", ... repo_type="dataset", ... multi_commits=True, ... multi_commits_verbose=True, ... ) ``` Wenn Sie die Upload-Strategie besser steuern möchten (d.h. die erstellten Commits), können Sie sich die Low-Level-Methoden [`plan_multi_commits`] und [`create_commits_on_pr`] ansehen. > [!WARNING] > `multi_commits` ist noch ein experimentelles Feature. Seine API und sein Verhalten können in Zukunft ohne vorherige Ankündigung geändert werden. ### Geplante Uploads Das Hugging Face Hub erleichtert das Speichern und Versionieren von Daten. Es gibt jedoch einige Einschränkungen, wenn Sie dieselbe Datei Tausende von Malen aktualisieren möchten. Sie möchten beispielsweise Protokolle eines Trainingsprozesses oder Benutzerfeedback in einem bereitgestellten Space speichern. In diesen Fällen macht es Sinn, die Daten als Dataset im Hub hochzuladen, aber es kann schwierig sein, dies richtig zu machen. Der Hauptgrund ist, dass Sie nicht jede Aktualisierung Ihrer Daten versionieren möchten, da dies das git-Repository unbrauchbar machen würde. Die Klasse [`CommitScheduler`] bietet eine Lösung für dieses Problem. Die Idee besteht darin, einen Hintergrundjob auszuführen, der regelmäßig einen lokalen Ordner ins Hub schiebt. Nehmen Sie an, Sie haben einen Gradio Space, der als Eingabe einen Text nimmt und zwei Übersetzungen davon generiert. Der Benutzer kann dann seine bevorzugte Übersetzung auswählen. Für jeden Durchlauf möchten Sie die Eingabe, Ausgabe und Benutzerpräferenz speichern, um die Ergebnisse zu analysieren. Dies ist ein perfekter Anwendungsfall für [`CommitScheduler`]; Sie möchten Daten ins Hub speichern (potenziell Millionen von Benutzerfeedbacks), aber Sie müssen nicht in Echtzeit jede Benutzereingabe speichern. Stattdessen können Sie die Daten lokal in einer JSON-Datei speichern und sie alle 10 Minuten hochladen. Zum Beispiel: ```py >>> import json >>> import uuid >>> from pathlib import Path >>> import gradio as gr >>> from huggingface_hub import CommitScheduler # Definieren Sie die Datei, in der die Daten gespeichert werden sollen. Verwenden Sie UUID, um sicherzustellen, dass vorhandene Daten aus einem früheren Lauf nicht überschrieben werden. >>> feedback_file = Path("user_feedback/") / f"data_{uuid.uuid4()}.json" >>> feedback_folder = feedback_file.parent # Geplante regelmäßige Uploads. Das Remote-Repo und der lokale Ordner werden erstellt, wenn sie noch nicht existieren. >>> scheduler = CommitScheduler( ... repo_id="report-translation-feedback", ... repo_type="dataset", ... folder_path=feedback_folder, ... path_in_repo="data", ... every=10, ... ) # Eine einfache Gradio-Anwendung, die einen Text als Eingabe nimmt und zwei Übersetzungen generiert. Der Benutzer wählt seine bevorzugte Übersetzung aus. >>> def save_feedback(input_text:str, output_1: str, output_2:str, user_choice: int) -> None: ... """ ... Füge Eingabe/Ausgabe und Benutzerfeedback zu einer JSON-Lines-Datei hinzu und verwende ein Thread-Lock, um gleichzeitiges Schreiben von verschiedenen Benutzern zu vermeiden. ... """ ... with scheduler.lock: ... with feedback_file.open("a") as f: ... f.write(json.dumps({"input": input_text, "output_1": output_1, "output_2": output_2, "user_choice": user_choice})) ... f.write("\n") # Starte Gradio >>> with gr.Blocks() as demo: >>> ... # Definiere Gradio Demo + verwende `save_feedback` >>> demo.launch() ``` Und das war's! Benutzereingabe/-ausgaben und Feedback sind als Dataset auf dem Hub verfügbar. Durch die Verwendung eines eindeutigen JSON-Dateinamens können Sie sicher sein, dass Sie keine Daten von einem vorherigen Lauf oder Daten von anderen Spaces/Replikas überschreiben, die gleichzeitig in dasselbe Repository pushen. Für weitere Details über den [`CommitScheduler`], hier das Wichtigste: - **append-only / Nur hinzufügen:** Es wird davon ausgegangen, dass Sie nur Inhalte zum Ordner hinzufügen. Sie dürfen nur Daten zu bestehenden Dateien hinzufügen oder neue Dateien erstellen. Das Löschen oder Überschreiben einer Datei könnte Ihr Repository beschädigen. - **git history / git Historie**: Der Scheduler wird den Ordner alle every Minuten committen. Um das Git-Repository nicht zu überladen, wird empfohlen, einen minimalen Wert von 5 Minuten festzulegen. Außerdem ist der Scheduler darauf ausgelegt, leere Commits zu vermeiden. Wenn im Ordner kein neuer Inhalt erkannt wird, wird der geplante Commit verworfen. - **errors / Fehler**: Der Scheduler läuft als Hintergrund-Thread. Er wird gestartet, wenn Sie die Klasse instanziieren, und stoppt nie. Insbesondere, wenn während des Uploads ein Fehler auftritt (z. B. Verbindungsproblem), wird der Scheduler ihn stillschweigend ignorieren und beim nächsten geplanten Commit erneut versuchen. - **thread-safety / Thread-Sicherheit**: In den meisten Fällen können Sie davon ausgehen, dass Sie eine Datei schreiben können, ohne sich um eine Lock-Datei kümmern zu müssen. Der Scheduler wird nicht abstürzen oder beschädigt werden, wenn Sie Inhalte in den Ordner schreiben, während er hochlädt. In der Praxis ist es möglich, dass bei stark ausgelasteten Apps Probleme mit der Parallelität auftreten. In diesem Fall empfehlen wir, das `scheduler.lock` Lock zu verwenden, um die Thread-Sicherheit zu gewährleisten. Das Lock wird nur gesperrt, wenn der Scheduler den Ordner auf Änderungen überprüft, nicht beim Hochladen von Daten. Sie können sicher davon ausgehen, dass dies das Benutzererlebnis in Ihrem Space nicht beeinflusst. #### Space Persistenz-Demo Das Speichern von Daten aus einem Space in einem Dataset auf dem Hub ist der Hauptanwendungsfall für den [`CommitScheduler`]. Je nach Anwendungsfall möchten Sie Ihre Daten möglicherweise anders strukturieren. Die Struktur muss robust gegenüber gleichzeitigen Benutzern und Neustarts sein, was oft das Generieren von UUIDs impliziert. Neben der Robustheit sollten Sie Daten in einem Format hochladen, das von der 🤗 Datasets-Bibliothek für die spätere Wiederverwendung gelesen werden kann. Wir haben einen [Space](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) erstellt, der zeigt, wie man verschiedene Datenformate speichert (dies muss möglicherweise für Ihre speziellen Bedürfnisse angepasst werden). #### Benutzerdefinierte Uploads [`CommitScheduler`] geht davon aus, dass Ihre Daten nur hinzugefügt werden und "wie sie sind" hochgeladen werden sollten. Sie möchten jedoch möglicherweise anpassen, wie Daten hochgeladen werden. Dies können Sie tun, indem Sie eine Klasse erstellen, die vom [`CommitScheduler`] erbt und die Methode `push_to_hub` überschreibt (fühlen Sie sich frei, sie nach Belieben zu überschreiben). Es ist garantiert, dass sie alle `every` Minuten in einem Hintergrund-Thread aufgerufen wird. Sie müssen sich keine Gedanken über Parallelität und Fehler machen, aber Sie müssen vorsichtig sein bei anderen Aspekten, wie z. B. dem Pushen von leeren Commits oder doppelten Daten. Im folgenden (vereinfachten) Beispiel überschreiben wir `push_to_hub`, um alle PNG-Dateien in einem einzigen Archiv zu zippen, um das Repo auf dem Hub nicht zu überladen: ```py class ZipScheduler(CommitScheduler): def push_to_hub(self): # 1. Liste PNG-Dateien auf png_files = list(self.folder_path.glob("*.png")) if len(png_files) == 0: return None # kehre früh zurück, wenn nichts zu committen ist # 2. Zippe PNG-Dateien in ein einzelnes Archiv with tempfile.TemporaryDirectory() as tmpdir: archive_path = Path(tmpdir) / "train.zip" with zipfile.ZipFile(archive_path, "w", zipfile.ZIP_DEFLATED) as zip: for png_file in png_files: zip.write(filename=png_file, arcname=png_file.name) # 3. Lade das Archiv hoch self.api.upload_file(..., path_or_fileobj=archive_path) # 4. Lösche lokale PNG-Dateien, um späteres erneutes Hochladen zu vermeiden for png_file in png_files: png_file.unlink() ``` Wenn Sie `push_to_hub` überschreiben, haben Sie Zugriff auf die Attribute vom [`CommitScheduler`] und insbesondere: - [`HfApi`] Client: `api` - Ordnerparameter: `folder_path` und `path_in_repo` - Repo-Parameter: `repo_id`, `repo_type`, `revision` - Das Thread-Lock: `lock` > [!TIP] > Für weitere Beispiele von benutzerdefinierten Schedulern, schauen Sie sich unseren [Demo Space](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) an, der verschiedene Implementierungen je nach Ihren Anforderungen enthält. ### create_commit Die Funktionen [`upload_file`] und [`upload_folder`] sind High-Level-APIs, die im Allgemeinen bequem zu verwenden sind. Wir empfehlen, diese Funktionen zuerst auszuprobieren, wenn Sie nicht auf einer niedrigeren Ebene arbeiten müssen. Wenn Sie jedoch auf Commit-Ebene arbeiten möchten, können Sie die Funktion [`create_commit`] direkt verwenden. Es gibt drei von [`create_commit`] unterstützte Operationstypen: - [`CommitOperationAdd`] lädt eine Datei in den Hub hoch. Wenn die Datei bereits existiert, werden die Dateiinhalte überschrieben. Diese Operation akzeptiert zwei Argumente: - `path_in_repo`: der Repository-Pfad, um eine Datei hochzuladen. - `path_or_fileobj`: entweder ein Pfad zu einer Datei auf Ihrem Dateisystem oder ein Datei-ähnliches Objekt. Dies ist der Inhalt der Datei, die auf den Hub hochgeladen werden soll. - [`CommitOperationDelete`] entfernt eine Datei oder einen Ordner aus einem Repository. Diese Operation akzeptiert path_in_repo als Argument. - [`CommitOperationCopy`] kopiert eine Datei innerhalb eines Repositorys. Diese Operation akzeptiert drei Argumente: - `src_path_in_repo`: der Repository-Pfad der zu kopierenden Datei. - `path_in_repo`: der Repository-Pfad, wohin die Datei kopiert werden soll. - `src_revision`: optional - die Revision der zu kopierenden Datei, wenn Sie eine Datei von einem anderen Branch/Revision kopieren möchten. Zum Beispiel, wenn Sie zwei Dateien hochladen und eine Datei in einem Hub-Repository löschen möchten: 1. Verwenden Sie die entsprechende `CommitOperation`, um eine Datei hinzuzufügen oder zu löschen und einen Ordner zu löschen: ```py >>> from huggingface_hub import HfApi, CommitOperationAdd, CommitOperationDelete >>> api = HfApi() >>> operations = [ ... CommitOperationAdd(path_in_repo="LICENSE.md", path_or_fileobj="~/repo/LICENSE.md"), ... CommitOperationAdd(path_in_repo="weights.h5", path_or_fileobj="~/repo/weights-final.h5"), ... CommitOperationDelete(path_in_repo="old-weights.h5"), ... CommitOperationDelete(path_in_repo="logs/"), ... CommitOperationCopy(src_path_in_repo="image.png", path_in_repo="duplicate_image.png"), ... ] ``` 2. Übergeben Sie Ihre Operationen an [`create_commit`]: ```py >>> api.create_commit( ... repo_id="lysandre/test-model", ... operations=operations, ... commit_message="Hochladen meiner Modell-Gewichte und -Lizenz", ... ) ``` Zusätzlich zu [`upload_file`] und [`upload_folder`] verwenden auch die folgenden Funktionen [`create_commit`] im Hintergrund: - [`delete_file`] löscht eine einzelne Datei aus einem Repository auf dem Hub. - [`delete_folder`] löscht einen gesamten Ordner aus einem Repository auf dem Hub. - [`metadata_update`] aktualisiert die Metadaten eines Repositorys. Für detailliertere Informationen werfen Sie einen Blick auf die [`HfApi`] Referenz. ## Tipps und Tricks für große Uploads Bei der Verwaltung einer großen Datenmenge in Ihrem Repo gibt es einige Einschränkungen zu beachten. Angesichts der Zeit, die es dauert, die Daten zu streamen, kann es sehr ärgerlich sein, am Ende des Prozesses einen Upload/Push zu verlieren oder eine degradierte Erfahrung zu machen, sei es auf hf.co oder bei lokalem Arbeiten. Wir haben eine Liste von Tipps und Empfehlungen zusammengestellt, um Ihr Repo zu strukturieren. | Eigenschaft | Empfohlen | Tipps | | ---------------- | ------------------ | ------------------------------------------------------ | | Repo-Größe | - | Kontaktieren Sie uns für große Repos (TBs Daten) | | Dateien pro Repo | <100k | Daten in weniger Dateien zusammenführen | | Einträge pro Ordner | <10k | Unterverzeichnisse im Repo verwenden | | Dateigröße | <5GB | Daten in geteilte Dateien aufteilen | | Commit-Größe | <100 files* | Dateien in mehreren Commits hochladen | | Commits pro Repo | - | Mehrere Dateien pro Commit hochladen und/oder Historie zusammenführen | _* Nicht relevant bei direkter Verwendung des `git` CLI_ Bitte lesen Sie den nächsten Abschnitt, um diese Beschränkungen besser zu verstehen und zu erfahren, wie Sie damit umgehen können. ### Hub-Repository Größenbeschränkungen Was meinen wir, wenn wir von "großen Uploads" sprechen, und welche Einschränkungen sind damit verbunden? Große Uploads können sehr unterschiedlich sein, von Repositories mit einigen riesigen Dateien (z. B. Modellgewichten) bis hin zu Repositories mit Tausenden von kleinen Dateien (z. B. einem Bilddatensatz). Hinter den Kulissen verwendet der Hub Git zur Versionierung der Daten, was strukturelle Auswirkungen darauf hat, was Sie in Ihrem Repo tun können. Wenn Ihr Repo einige der im vorherigen Abschnitt erwähnten Zahlen überschreitet, **empfehlen wir Ihnen dringend, [`git-sizer`](https://github.com/github/git-sizer) zu verwenden**, das eine sehr detaillierte Dokumentation über die verschiedenen Faktoren bietet, die Ihr Erlebnis beeinflussen werden. Hier ist ein TL;DR der zu berücksichtigenden Faktoren: - **Repository-Größe**: Die Gesamtgröße der Daten, die Sie hochladen möchten. Es gibt keine feste Obergrenze für die Größe eines Hub-Repositories. Wenn Sie jedoch vorhaben, Hunderte von GBs oder sogar TBs an Daten hochzuladen, würden wir es begrüßen, wenn Sie uns dies im Voraus mitteilen könnten, damit wir Ihnen besser helfen können, falls Sie während des Prozesses Fragen haben. Sie können uns unter datasets@huggingface.co oder auf [unserem Discord](http://hf.co/join/discord) kontaktieren. - **Anzahl der Dateien**: - Für ein optimales Erlebnis empfehlen wir, die Gesamtzahl der Dateien unter 100k zu halten. Versuchen Sie, die Daten zu weniger Dateien zusammenzuführen, wenn Sie mehr haben. Zum Beispiel können json-Dateien zu einer einzigen jsonl-Datei zusammengeführt oder große Datensätze als Parquet-Dateien exportiert werden. - Die maximale Anzahl von Dateien pro Ordner darf 10k Dateien pro Ordner nicht überschreiten. Eine einfache Lösung besteht darin, eine Repository-Struktur zu erstellen, die Unterverzeichnisse verwendet. Ein Repo mit 1k Ordnern von `000/` bis `999/`, in dem jeweils maximal 1000 Dateien enthalten sind, reicht bereits aus. - **Dateigröße**: Bei hochzuladenden großen Dateien (z. B. Modellgewichte) empfehlen wir dringend, sie **in Blöcke von etwa 5GB aufzuteilen**. Es gibt mehrere Gründe dafür: - Das Hoch- und Herunterladen kleinerer Dateien ist sowohl für Sie als auch für andere Benutzer viel einfacher. Bei der Datenübertragung können immer Verbindungsprobleme auftreten, und kleinere Dateien vermeiden das erneute Starten von Anfang an im Falle von Fehlern. - Dateien werden den Benutzern über CloudFront bereitgestellt. Aus unserer Erfahrung werden riesige Dateien von diesem Dienst nicht zwischengespeichert, was zu einer langsameren Downloadgeschwindigkeit führt. In jedem Fall wird keine einzelne LFS-Datei >50GB sein können. D. h. 50GB ist das absolute Limit für die Einzeldateigröße. - **Anzahl der Commits**: Es gibt kein festes Limit für die Gesamtzahl der Commits in Ihrer Repo-Historie. Aus unserer Erfahrung heraus beginnt das Benutzererlebnis im Hub jedoch nach einigen Tausend Commits abzunehmen. Wir arbeiten ständig daran, den Service zu verbessern, aber man sollte immer daran denken, dass ein Git-Repository nicht als Datenbank mit vielen Schreibzugriffen gedacht ist. Wenn die Historie Ihres Repos sehr groß wird, können Sie immer alle Commits mit [`super_squash_history`] zusammenfassen, um einen Neuanfang zu erhalten. Dies ist eine nicht rückgängig zu machende Operation. - **Anzahl der Operationen pro Commit**: Auch hier gibt es keine feste Obergrenze. Wenn ein Commit im Hub hochgeladen wird, wird jede Git-Operation (Hinzufügen oder Löschen) vom Server überprüft. Wenn hundert LFS-Dateien auf einmal committed werden, wird jede Datei einzeln überprüft, um sicherzustellen, dass sie korrekt hochgeladen wurde. Beim Pushen von Daten über HTTP mit `huggingface_hub` wird ein Timeout von 60s für die Anforderung festgelegt, was bedeutet, dass, wenn der Prozess mehr Zeit in Anspruch nimmt, clientseitig ein Fehler ausgelöst wird. Es kann jedoch (in seltenen Fällen) vorkommen, dass selbst wenn das Timeout clientseitig ausgelöst wird, der Prozess serverseitig dennoch abgeschlossen wird. Dies kann manuell überprüft werden, indem man das Repo im Hub durchsucht. Um dieses Timeout zu vermeiden, empfehlen wir, pro Commit etwa 50-100 Dateien hinzuzufügen. ### Praktische Tipps Nachdem wir die technischen Aspekte gesehen haben, die Sie bei der Strukturierung Ihres Repositories berücksichtigen müssen, schauen wir uns einige praktische Tipps an, um Ihren Upload-Prozess so reibungslos wie möglich zu gestalten. - **Fangen Sie klein an**: Wir empfehlen, mit einer kleinen Datenmenge zu beginnen, um Ihr Upload-Skript zu testen. Es ist einfacher, an einem Skript zu arbeiten, wenn ein Fehler nur wenig Zeit kostet. - **Rechnen Sie mit Ausfällen**: Das Streamen großer Datenmengen ist eine Herausforderung. Sie wissen nicht, was passieren kann, aber es ist immer am besten anzunehmen, dass etwas mindestens einmal schiefgehen wird - unabhängig davon, ob es an Ihrem Gerät, Ihrer Verbindung oder unseren Servern liegt. Wenn Sie zum Beispiel vorhaben, eine große Anzahl von Dateien hochzuladen, ist es am besten, lokal zu verfolgen, welche Dateien Sie bereits hochgeladen haben, bevor Sie die nächste Batch hochladen. Sie können sicher sein, dass eine LFS-Datei, die bereits committed wurde, niemals zweimal hochgeladen wird, aber es kann clientseitig trotzdem Zeit sparen, dies zu überprüfen. - **Verwenden Sie `hf_transfer`**: Dabei handelt es sich um eine auf Rust basierende [Bibliothek](https://github.com/huggingface/hf_transfer), die dazu dient, Uploads auf Maschinen mit sehr hoher Bandbreite zu beschleunigen. Um sie zu verwenden, müssen Sie sie installieren (`pip install hf_transfer`) und sie durch Einstellen von `HF_HUB_ENABLE_HF_TRANSFER=1` als Umgebungsvariable aktivieren. Anschließend können Sie `huggingface_hub` wie gewohnt verwenden. Hinweis: Dies ist ein Tool für Power-User. Es ist getestet und einsatzbereit, verfügt jedoch nicht über benutzerfreundliche Funktionen wie Fortschrittsanzeigen oder erweiterte Fehlerbehandlung. ## (veraltet) Dateien mit Git LFS hochladen Alle oben beschriebenen Methoden verwenden die Hub-API, um Dateien hochzuladen. Dies ist der empfohlene Weg, Dateien in den Hub hochzuladen. Wir bieten jedoch auch [`Repository`] an, einen Wrapper um das git-Tool, um ein lokales Repository zu verwalten. > [!WARNING] > Obwohl [`Repository`] formell nicht als veraltet gekennzeichnet ist, empfehlen wir stattdessen die Nutzung der HTTP-basierten Methoden, die oben beschrieben sind. > Für weitere Details zu dieser Empfehlung werfen Sie bitte einen Blick auf diesen [Leitfaden](../concepts/git_vs_http), der die Kernunterschiede zwischen HTTP- und Git-basierten Ansätzen erklärt. Git LFS verarbeitet automatisch Dateien, die größer als 10MB sind. Für sehr große Dateien (>5GB) müssen Sie jedoch einen benutzerdefinierten Transferagenten für Git LFS installieren: ```bash hf lfs-enable-largefiles . ``` Sie sollten dies für jedes Repository installieren, das eine sehr große Datei enthält. Einmal installiert, können Sie Dateien hochladen, die größer als 5GB sind. ### commit Kontextmanager Der `commit` Kontextmanager handhabt vier der gängigsten Git-Befehle: pull, add, commit und push. `git-lfs` beobactet automatisch jede Datei, die größer als 10MB ist. Im folgenden Beispiel handhabt der `commit` Kontextmanager die folgenden Aufgaben: 1. Holt Daten aus dem `text-files` Repository. 2. Fügt eine Änderung an `file.txt` hinzu. 3. Committet die Änderung. 4. Schickt die Änderung an das `text-files` Repository. ```python >>> from huggingface_hub import Repository >>> with Repository(local_dir="text-files", clone_from="/text-files").commit(commit_message="Mein erste Datei :)"): ... with open("file.txt", "w+") as f: ... f.write(json.dumps({"hey": 8})) ``` Hier ist ein weiteres Beispiel, wie man den `commit` Kontextmanager verwendet, um eine Datei in einem Repository zu speichern und hochzuladen: ```python >>> import torch >>> model = torch.nn.Transformer() >>> with Repository("torch-model", clone_from="/torch-model", token=True).commit(commit_message="Mein cooles Model :)"): ... torch.save(model.state_dict(), "model.pt") ``` Setzen Sie `blocking=False`, wenn Sie Ihre Commits asynchron pushen möchten. Das nicht-blockierende Verhalten ist nützlich, wenn Sie Ihr Skript weiterhin ausführen möchten, während Ihre Commits gesendet werden. ```python >>> with repo.commit(commit_message="Mein cooles Model :)", blocking=False) ``` Sie können den Status Ihres Pushs mit der Methode `command_queue` überprüfen: ```python >>> last_command = repo.command_queue[-1] >>> last_command.status ``` Beachten Sie die Tabelle mit möglichen Statuscodes: | Status | Beschreibung | | -------- | ------------------------------------ | | -1 | Der Push wird ausgeführt. | | 0 | Der Push wurde erfolgreich beendet. | | Non-zero | Ein Fehler ist aufgetreten. | Wenn `blocking=False` gesetzt ist, werden Befehle beobachtet und Ihr Skript wird erst beendet, wenn alle Pushs abgeschlossen sind, auch wenn andere Fehler in Ihrem Skript auftreten. Einige zusätzliche nützliche Befehle, um den Status eines Pushs zu überprüfen, sind: ```python # Einen Fehler inspizieren. >>> last_command.stderr # Überprüfen, ob ein Push abgeschlossen ist oder noch läuft. >>> last_command.is_done # Überprüfen, ob bei einem Push-Befehl ein Fehler aufgetreten ist. >>> last_command.failed ``` ### push_to_hub Die Klasse [`Repository`] hat eine Funktion [`~Repository.push_to_hub`], um Dateien hinzuzufügen, einen Commit zu machen und diese zu einem Repository zu pushen. Im Gegensatz zum `commit` Kontextmanager müssen Sie zuerst von einem Repository pullen, bevor Sie [`~Repository.push_to_hub`] aufrufen. Zum Beispiel, wenn Sie bereits ein Repository vom Hub geklont haben, können Sie das `repo` vom lokalen Verzeichnis initialisieren: ```python >>> from huggingface_hub import Repository >>> repo = Repository(local_dir="pfad/zur/lokalen/repo") ``` Aktualisieren Sie Ihren lokalen Klon mit [`~Repository.git_pull`] und dann pushen Sie Ihre Datei zum Hub: ```py >>> repo.git_pull() >>> repo.push_to_hub(commit_message="Committe meine geniale Datei zum Hub") ``` Wenn Sie jedoch noch nicht bereit sind, eine Datei zu pushen, können Sie [`~Repository.git_add`] und [`~Repository.git_commit`] verwenden, um nur Ihre Datei hinzuzufügen und zu committen: ```py >>> repo.git_add("path/to/file") >>> repo.git_commit(commit_message="füge meine erste Modell-Konfigurationsdatei hinzu :)") ``` Wenn Sie bereit sind, pushen Sie die Datei zu Ihrem Repository mit [`~Repository.git_push`]: ```py >>> repo.git_push() ``` huggingface_hub-1.1.5/docs/source/de/guides/webhooks_server.md000066400000000000000000000257361510763414300244750ustar00rootroot00000000000000 # Webhooks Server Webhooks sind ein Grundpfeiler für MLOps-bezogene Funktionen. Sie ermöglichen es Ihnen, auf neue Änderungen in bestimmten Repos oder auf alle Repos, die bestimmten Benutzern/Organisationen gehören, die Sie interessieren, zu hören. Dieser Leitfaden erklärt, wie Sie den `huggingface_hub` nutzen können, um einen Server zu erstellen, der auf Webhooks hört und ihn in einen Space zu implementieren. Es wird davon ausgegangen, dass Sie mit dem Konzept der Webhooks auf dem Huggingface Hub vertraut sind. Um mehr über Webhooks selbst zu erfahren, können Sie zuerst diesen [Leitfaden](https://huggingface.co/docs/hub/webhooks) lesen. Die Basis-Klasse, die wir in diesem Leitfaden verwenden werden, ist der [`WebhooksServer`]. Es handelt sich um eine Klasse, mit der sich ein Server leicht konfigurieren lässt, der Webhooks vom Huggingface Hub empfangen kann. Der Server basiert auf einer Gradio-App. Er verfügt über eine Benutzeroberfläche zur Anzeige von Anweisungen für Sie oder Ihre Benutzer und eine API zum Hören auf Webhooks. > [!TIP] > Um ein Beispiel eines laufenden Webhook-Servers zu sehen, werfen Sie einen Blick auf den [Spaces CI Bot](https://huggingface.co/spaces/spaces-ci-bot/webhook). Es handelt sich um einen Space, der kurzlebige Umgebungen startet, wenn ein PR in einem Space geöffnet wird. > [!WARNING] > Dies ist ein [experimentelles Feature](../package_reference/environment_variables#hfhubdisableexperimentalwarning). Das bedeutet, dass wir noch daran arbeiten, die API zu verbessern. Es könnten in der Zukunft ohne vorherige Ankündigung Änderungen vorgenommen werden. Stellen Sie sicher, dass Sie die Version des `huggingface_hub` in Ihren Anforderungen festlegen. ## Einen Endpunkt erstellen Das Implementieren eines Webhook-Endpunkts ist so einfach wie das Dekorieren einer Funktion. Lassen Sie uns ein erstes Beispiel betrachten, um die Hauptkonzepte zu erklären: ```python # app.py from huggingface_hub import webhook_endpoint, WebhookPayload @webhook_endpoint async def trigger_training(payload: WebhookPayload) -> None: if payload.repo.type == "dataset" and payload.event.action == "update": # Einen Trainingsjob auslösen, wenn ein Datensatz aktualisiert wird ... ``` Speichern Sie diesen Ausschnitt in einer Datei namens `'app.py'` und führen Sie ihn mit `'python app.py'` aus. Sie sollten eine Nachricht wie diese sehen: ```text Webhook secret is not defined. This means your webhook endpoints will be open to everyone. To add a secret, set `WEBHOOK_SECRET` as environment variable or pass it at initialization: `app = WebhooksServer(webhook_secret='my_secret', ...)` For more details about webhook secrets, please refer to https://huggingface.co/docs/hub/webhooks#webhook-secret. Running on local URL: http://127.0.0.1:7860 Running on public URL: https://1fadb0f52d8bf825fc.gradio.live This share link expires in 72 hours. For free permanent hosting and GPU upgrades (NEW!), check out Spaces: https://huggingface.co/spaces Webhooks are correctly setup and ready to use: - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training Go to https://huggingface.co/settings/webhooks to setup your webhooks. ``` Gute Arbeit! Sie haben gerade einen Webhook-Server gestartet! Lassen Sie uns genau aufschlüsseln, was passiert ist: 1. Durch das Dekorieren einer Funktion mit [`webhook_endpoint`] wurde im Hintergrund ein [`WebhooksServer`]-Objekt erstellt. Wie Sie sehen können, handelt es sich bei diesem Server um eine Gradio-App, die unter http://127.0.0.1:7860 läuft. Wenn Sie diese URL in Ihrem Browser öffnen, sehen Sie eine Landing Page mit Anweisungen zu den registrierten Webhooks. 2. Eine Gradio-App ist im Kern ein FastAPI-Server. Eine neue POST-Route `/webhooks/trigger_training` wurde hinzugefügt. Dies ist die Route, die auf Webhooks hört und die Funktion `trigger_training` ausführt, wenn sie ausgelöst wird. FastAPI wird das Payload automatisch parsen und es der Funktion als [`WebhookPayload`]-Objekt übergeben. Dies ist ein `pydantisches` Objekt, das alle Informationen über das Ereignis enthält, das den Webhook ausgelöst hat. 3. Die Gradio-App hat auch einen Tunnel geöffnet, um Anfragen aus dem Internet zu empfangen. Das Interessante daran ist: Sie können einen Webhook auf https://huggingface.co/settings/webhooks konfigurieren, der auf Ihren lokalen Rechner zeigt. Dies ist nützlich zum Debuggen Ihres Webhook-Servers und zum schnellen Iterieren, bevor Sie ihn in einem Space bereitstellen. 4. Schließlich teilen Ihnen die Logs auch mit, dass Ihr Server derzeit nicht durch ein Geheimnis gesichert ist. Dies ist für das lokale Debuggen nicht problematisch, sollte aber für später berücksichtigt werden. > [!WARNING] > Standardmäßig wird der Server am Ende Ihres Skripts gestartet. Wenn Sie es in einem Notizbuch ausführen, können Sie den Server manuell starten, indem Sie `decorated_function.run()` aufrufen. Da ein einzigartiger Server verwendet wird, müssen Sie den Server nur einmal starten, auch wenn Sie mehrere Endpunkte haben. ## Konfigurieren eines Webhook Jetzt, da Sie einen Webhook-Server am Laufen haben, möchten Sie einen Webhook konfigurieren, um Nachrichten zu empfangen. Gehen Sie zu https://huggingface.co/settings/webhooks, klicken Sie auf "Add a new webhook" und konfigurieren Sie Ihren Webhook. Legen Sie die Ziel-Repositories fest, die Sie beobachten möchten, und die Webhook-URL, hier `https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training`.
Und das war's! Sie können den Webhook jetzt auslösen, indem Sie das Ziel-Repository aktualisieren (z.B. einen Commit pushen). Überprüfen Sie den Aktivitäts-Tab Ihres Webhooks, um die ausgelösten Ereignisse zu sehen. Jetzt, wo Sie eine funktionierende Einrichtung haben, können Sie sie testen und schnell iterieren. Wenn Sie Ihren Code ändern und den Server neu starten, könnte sich Ihre öffentliche URL ändern. Stellen Sie sicher, dass Sie die Webhook-Konfiguration im Hub bei Bedarf aktualisieren. ## Bereitstellung in einem Space Jetzt, da Sie einen funktionierenden Webhook-Server haben, ist das Ziel, ihn in einem Space bereitzustellen. Gehen Sie zu https://huggingface.co/new-space, um einen Space zu erstellen. Geben Sie ihm einen Namen, wählen Sie das Gradio SDK und klicken Sie auf "Create Space". Laden Sie Ihren Code in den Space in einer Datei namens `app.py` hoch. Ihr Space wird automatisch gestartet! Für weitere Informationen zu Spaces lesen Sie bitte diesen [Leitfaden](https://huggingface.co/docs/hub/spaces-overview). Ihr Webhook-Server läuft nun auf einem öffentlichen Space. In den meisten Fällen möchten Sie ihn mit einem Geheimnis absichern. Gehen Sie zu Ihren Space-Einstellungen > Abschnitt "Repository secrets" > "Add a secret". Setzen Sie die Umgebungsvariable `WEBHOOK_SECRET` auf den von Ihnen gewählten Wert. Gehen Sie zurück zu den [Webhook-Einstellungen](https://huggingface.co/settings/webhooks) und setzen Sie das Geheimnis in der Webhook-Konfiguration. Jetzt werden von Ihrem Server nur Anfragen mit dem korrekten Geheimnis akzeptiert. Und das war's! Ihr Space ist nun bereit, Webhooks vom Hub zu empfangen. Bitte beachten Sie, dass wenn Sie den Space auf einer kostenlosen 'cpu-basic' Hardware ausführen, er nach 48 Stunden Inaktivität heruntergefahren wird. Wenn Sie einen permanenten Space benötigen, sollten Sie in Erwägung ziehen, auf eine [upgraded hardware](https://huggingface.co/docs/hub/spaces-gpus#hardware-specs) umzustellen. ## Erweiterte Nutzung Der obenstehende Leitfaden erklärte den schnellsten Weg, einen [`WebhooksServer`] einzurichten. In diesem Abschnitt werden wir sehen, wie man ihn weiter anpassen kann. ### Mehrere Endpunkte Sie können mehrere Endpunkte auf demselben Server registrieren. Beispielsweise möchten Sie vielleicht einen Endpunkt haben, um einen Trainingsjob auszulösen und einen anderen, um eine Modellevaluierung auszulösen. Dies können Sie tun, indem Sie mehrere `@webhook_endpoint`-Dekorateure hinzufügen: ```python # app.py from huggingface_hub import webhook_endpoint, WebhookPayload @webhook_endpoint async def trigger_training(payload: WebhookPayload) -> None: if payload.repo.type == "dataset" and payload.event.action == "update": # Einen Trainingsjob auslösen, wenn ein Datensatz aktualisiert wird ... @webhook_endpoint async def trigger_evaluation(payload: WebhookPayload) -> None: if payload.repo.type == "model" and payload.event.action == "update": # Einen Evaluierungsauftrag auslösen, wenn ein Modell aktualisiert wird ... ``` Dies wird zwei Endpunkte erstellen: ```text (...) Webhooks are correctly setup and ready to use: - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation ``` ### Benutzerdefinierter Server Um mehr Flexibilität zu erhalten, können Sie auch direkt ein [`WebhooksServer`] Objekt erstellen. Dies ist nützlich, wenn Sie die Startseite Ihres Servers anpassen möchten. Sie können dies tun, indem Sie eine [Gradio UI](https://gradio.app/docs/#blocks) übergeben, die die Standard-UI überschreibt. Zum Beispiel können Sie Anweisungen für Ihre Benutzer hinzufügen oder ein Formular zur manuellen Auslösung der Webhooks hinzufügen. Bei der Erstellung eines [`WebhooksServer`] können Sie mit dem Dekorateur [`~WebhooksServer.add_webhook`] neue Webhooks registrieren. Hier ist ein vollständiges Beispiel: ```python import gradio as gr from fastapi import Request from huggingface_hub import WebhooksServer, WebhookPayload # 1. Benutzerdefinierte UI definieren with gr.Blocks() as ui: ... # 2. Erstellen eines WebhooksServer mit benutzerdefinierter UI und Geheimnis app = WebhooksServer(ui=ui, webhook_secret="my_secret_key") # 3. Webhook mit explizitem Namen registrieren @app.add_webhook("/say_hello") async def hello(payload: WebhookPayload): return {"message": "hello"} # 4. Webhook mit implizitem Namen registrierene @app.add_webhook async def goodbye(payload: WebhookPayload): return {"message": "goodbye"} # 5. Server starten (optional) app.run() ``` 1. Wir definieren eine benutzerdefinierte UI mit Gradio-Blöcken. Diese UI wird auf der Startseite des Servers angezeigt. 2. Wir erstellen ein [`WebhooksServer`]-Objekt mit einer benutzerdefinierten UI und einem Geheimnis. Das Geheimnis ist optional und kann mit der `WEBHOOK_SECRET` Umgebungsvariable gesetzt werden. 3. Wir registrieren einen Webhook mit einem expliziten Namen. Dies wird einen Endpunkt unter `/webhooks/say_hello` erstellen. 4. Wir registrieren einen Webhook mit einem impliziten Namen. Dies wird einen Endpunkt unter `/webhooks/goodbye` erstellen. 5. Wir starten den Server. Dies ist optional, da Ihr Server automatisch am Ende des Skripts gestartet wird. huggingface_hub-1.1.5/docs/source/de/index.md000066400000000000000000000077061510763414300211120ustar00rootroot00000000000000 # 🤗 Hub client bibliothek Die `huggingface_hub` Bibliothek ermöglicht die Interaktion mit dem [Hugging Face Hub](https://hf.co), einer Plattform für maschinelles Lernen, die für Entwickler und Mitwirkende konzipiert ist. Hier können Sie vorab trainierte Modelle und Datensätze entdecken, mit zahlreichen Apps für maschinelles Lernen experimentieren und eigene Modelle sowie Datensätze mit der Community teilen. Die `huggingface_hub` Bibliothek macht es einfach, all das in Python umzusetzen. In der [Kurzanleitung](quick-start) der `huggingface_hub` Bibliothek erfahren Sie wie Sie Dateien vom Hub herunterladen, Repositories erstellen und Inhalte auf den Hub hochladen können. Weiterführend können Sie sich über Verwaltung von Repositories, die Interaktion in Diskussionen und den Zugriff auf die Inferenz-API auf dem 🤗 Hub informieren.
Schritt-für-Schritt-Anleitungen

Praktische Leitfäden, um ein bestimmtes Ziel zu erreichen. Durchstöbern Sie diese Anleitungen, um zu erfahren, wie Sie mit huggingface_hub echte Herausforderungen meistern können.
Konzeptionelle Leitfäden

Methodische Erklärungen zum Aufbau eines besseren Verständnisses der Huggingface_hub-Philosophie.
## Beitragen Alle Beiträge zum `huggingface_hub` sind willkommen und werden gleichermaßen geschätzt! 🤗 Neben dem Hinzufügen neuer Features oder dem Beheben von Problemen können Sie auch zur Verbesserung der Dokumentation beitragen, indem Sie ihre Richtigkeit und Aktualität gewährleisten. Sie können auch bei der Lösung von Fragen mithelfen oder neue Features vorschlagen, um die Bibliothek weiterzuentwickeln. Schauen Sie in die [Beitragsrichtlinien](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md), um mehr zu erfahren über das Melden von Problemen, das Vorschlagen von Features, das Einreichen eines Pull Requests, und das Testen Ihrer Code-Einsendungen, um sicherzustellen dass alles so wie erwartet funktioniert. Mitwirkende halten sich bitte an unseren [Verhaltenskodex](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md), um eine inklusive und einladende Umgebung zur Zusammenarbeit für Alle zu gewährleisten. huggingface_hub-1.1.5/docs/source/de/installation.md000066400000000000000000000166551510763414300225070ustar00rootroot00000000000000 # Installation Bevor Sie beginnen, müssen Sie Ihre Umgebung vorbereiten, indem Sie die entsprechenden Pakete installieren. `huggingface_hub` wurde für **Python 3.9+** getestet. ## Installation mit pip Es wird dringend empfohlen, `huggingface_hub` in einer [virtuellen Umgebung](https://docs.python.org/3/library/venv.html) zu installieren. Wenn Sie mit virtuellen Umgebungen in Python nicht vertraut sind, werfen Sie einen Blick auf diesen [Leitfaden](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). Eine virtuelle Umgebung erleichtert die Verwaltung verschiedener Projekte und verhindert Kompatibilitätsprobleme zwischen Abhängigkeiten. Beginnen Sie damit, eine virtuelle Umgebung in Ihrem Projektverzeichnis zu erstellen: ```bash python -m venv .env ``` Aktivieren Sie die virtuelle Umgebung. Unter Linux und macOS: ```bash source .env/bin/activate ``` Aktivieren der virtuellen Umgebung unter Windows: ```bash .env/Scripts/activate ``` Jetzt können Sie `huggingface_hub` aus dem [PyPi-Register](https://pypi.org/project/huggingface-hub/) installieren: ```bash pip install --upgrade huggingface_hub ``` Überprüfen Sie nach Abschluss, ob die [Installation korrekt funktioniert](#installation-berprfen). ### Installieren optionaler Abhängigkeiten Einige Abhängigkeiten von `huggingface_hub` sind [optional](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies), da sie nicht notwendig sind, um die Kernfunktionen von `huggingface_hub` auszuführen. Allerdings könnten einige Funktionen von `huggingface_hub` nicht verfügbar sein, wenn die optionalen Abhängigkeiten nicht installiert sind. Sie können optionale Abhängigkeiten über `pip` installieren: ```bash # Abhängigkeiten sowohl für torch-spezifische als auch für CLI-spezifische Funktionen installieren. pip install 'huggingface_hub[cli,torch]' ``` Hier ist die Liste der optionalen Abhängigkeiten in huggingface_hub: - `cli`: bietet eine komfortablere CLI-Schnittstelle für huggingface_hub. - `fastai`, `torch`: Abhängigkeiten, um framework-spezifische Funktionen auszuführen. - `dev`: Abhängigkeiten, um zur Bibliothek beizutragen. Enthält `testing` (um Tests auszuführen), `typing` (um den Type Checker auszuführen) und `quality` (um Linters auszuführen). ### Installieren von der Quelle In einigen Fällen kann es sinnvoll sein, `huggingface_hub` direkt von der Quelle zu installieren. Dies ermöglicht es Ihnen, die aktuellste `main`-Version anstelle der neuesten stabilen Version zu verwenden. Die `main`-Version ist nützlich, um immer auf dem neuesten Stand der Entwicklungen zu bleiben, zum Beispiel wenn ein Fehler seit der letzten offiziellen Veröffentlichung behoben wurde, aber noch keine neue Version herausgegeben wurde. Das bedeutet jedoch, dass die `main`-Version nicht immer stabil sein könnte. Wir bemühen uns, die Hauptversion funktionsfähig zu halten, und die meisten Probleme werden in der Regel innerhalb von einigen Stunden oder einem Tag gelöst. Wenn Sie auf ein Problem stoßen, eröffnen Sie bitte ein "Issue", damit wir es noch schneller beheben können! ```bash pip install git+https://github.com/huggingface/huggingface_hub ``` Bei der Installation von der Quelle können Sie auch einen bestimmten Zweig angeben. Dies ist nützlich, wenn Sie ein neues Feature oder einen neuen Fehlerbehebung testen möchten, der noch nicht zusammengeführt wurde: ```bash pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch ``` Überprüfen Sie nach Abschluss, ob die [Installation korrekt funktioniert](#installation-berprfen). ### Editierbare Installation Die Installation von der Quelle ermöglicht Ihnen eine [editierbare Installation](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs). Dies ist eine fortgeschrittenere Installation, wenn Sie zur Entwicklung von `huggingface_hub` beitragen und Änderungen im Code testen möchten. Sie müssen eine lokale Kopie von `huggingface_hub` auf Ihrem Computer klonen. ```bash # Zuerst die Repository lokal klonen git clone https://github.com/huggingface/huggingface_hub.git # Dann mit dem -e Flag installieren cd huggingface_hub pip install -e . ``` Diese Befehle verknüpfen den Ordner, in den Sie das Repository geklont haben, mit Ihren Python-Bibliothekspfaden. Python wird nun zusätzlich zu den normalen Bibliothekspfaden im geklonten Ordner suchen. Wenn Ihre Python-Pakete normalerweise in `./.venv/lib/python3.13/site-packages/` installiert sind, wird Python auch den geklonten Ordner `./huggingface_hub/` durchsuchen. ## Installieren mit conda Wenn Sie damit vertrauter sind, können Sie `huggingface_hub` über den [conda-forge-Kanal](https://anaconda.org/conda-forge/huggingface_hub) installieren: ```bash conda install -c conda-forge huggingface_hub ``` Überprüfen Sie nach Abschluss, ob die [Installation korrekt funktioniert](#installation-berprfen). ## Installation überprüfen Nach der Installation überprüfen Sie, ob `huggingface_hub` richtig funktioniert, indem Sie den folgenden Befehl ausführen: ```bash python -c "from huggingface_hub import model_info; print(model_info('gpt2'))" ``` Dieser Befehl ruft Informationen vom Hub über das [gpt2](https://huggingface.co/gpt2)-Modell ab. Die Ausgabe sollte so aussehen: ```text Model Name: gpt2 Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space'] Task: text-generation ``` ## Windows-Einschränkungen Mit unserem Ziel, gutes ML überall zu demokratisieren, haben wir `huggingface_hub` als plattformübergreifende Bibliothek entwickelt, insbesondere um sowohl auf Unix-basierten als auch auf Windows-Systemen korrekt zu funktionieren. Es gibt jedoch einige Fälle, in denen `huggingface_hub` unter Windows gewisse Einschränkungen hat. Hier ist eine ausführliche Liste der bekannten Probleme. Bitte informieren Sie uns, wenn Sie auf ein nicht dokumentiertes Problem stoßen, indem Sie ein [Issue auf Github eröffnen](https://github.com/huggingface/huggingface_hub/issues/new/choose). - Das Cache-System von `huggingface_hub` verwendet Symlinks, um Dateien, die vom Hub heruntergeladen wurden, effizient zu cachen. Unter Windows müssen Sie den Entwicklermodus aktivieren oder Ihr Skript als Admin ausführen, um Symlinks zu aktivieren. Wenn sie nicht aktiviert sind, funktioniert das Cache-System immer noch, aber nicht optimiert. Bitte lesen Sie den Abschnitt über [Cache-Einschränkungen](./guides/manage-cache#limitations) für weitere Details. - Dateipfade auf dem Hub können Sonderzeichen enthalten (z.B. `"pfad/zu?/meiner/datei"`). Windows ist bei [Sonderzeichen](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names) restriktiver, wodurch es unmöglich ist, diese Dateien unter Windows herunterzuladen. Hoffentlich ist dies ein seltener Fall. Bitte wenden Sie sich an den Repo-Eigentümer, wenn Sie denken, dass dies ein Fehler ist, oder an uns, um eine Lösung zu finden. ## Nächste Schritte Sobald `huggingface_hub`` richtig auf Ihrem Computer installiert ist, möchten Sie vielleicht [Umgebungsvariablen konfigurieren](package_reference/environment_variables) oder [einen unserer Leitfäden durchgehen](guides/overview), um loszulegen. huggingface_hub-1.1.5/docs/source/de/quick-start.md000066400000000000000000000150321510763414300222410ustar00rootroot00000000000000 # Kurzanleitung Der [Hugging Face Hub](https://huggingface.co/) ist die erste Anlaufstelle für das Teilen von Maschinenlernmodellen, Demos, Datensätzen und Metriken. Die `huggingface_hub`-Bibliothek hilft Ihnen, mit dem Hub zu interagieren, ohne Ihre Entwicklungs-Umgebung zu verlassen. Sie können Repositories einfach erstellen und verwalten, Dateien herunterladen und hochladen und nützliche Model- und Datensatz-Metadaten vom Hub abrufen. ## Installation Um loszulegen, installieren Sie die `huggingface_hub`-Bibliothek: ```bash pip install --upgrade huggingface_hub ``` Für weitere Details schauen Sie sich bitte den [Installationsleitfaden](installation) an. ## Dateien herunterladen Repositories auf dem Hub sind mit git versioniert, und Benutzer können eine einzelne Datei oder das gesamte Repository herunterladen. Sie können die Funktion [`hf_hub_download`] verwenden, um Dateien herunterzuladen. Diese Funktion lädt eine Datei herunter und speichert sie im Cache auf Ihrer lokalen Festplatte. Das nächste Mal, wenn Sie diese Datei benötigen, wird sie aus Ihrem Cache geladen, sodass Sie sie nicht erneut herunterladen müssen. Sie benötigen die Repository-ID und den Dateinamen der Datei, die Sie herunterladen möchten. Zum Beispiel, um die Konfigurationsdatei des [Pegasus](https://huggingface.co/google/pegasus-xsum) Modells herunterzuladen: ```py >>> from huggingface_hub import hf_hub_download >>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json") ``` Um eine bestimmte Version der Datei herunterzuladen, verwenden Sie den `revision`-Parameter, um den Namen der Branch, des Tags oder des Commit-Hashes anzugeben. Wenn Sie sich für den Commit-Hash entscheiden, muss es der vollständige Hash anstelle des kürzeren 7-Zeichen-Commit-Hashes sein: ```py >>> from huggingface_hub import hf_hub_download >>> hf_hub_download( ... repo_id="google/pegasus-xsum", ... filename="config.json", ... revision="4d33b01d79672f27f001f6abade33f22d993b151" ... ) ``` Für weitere Details und Optionen siehe die API-Referenz für [`hf_hub_download`]. ## Anmeldung In vielen Fällen müssen Sie mit einem Hugging Face-Konto angemeldet sein, um mit dem Hub zu interagieren: private Repos herunterladen, Dateien hochladen, PRs erstellen,... [Erstellen Sie ein Konto](https://huggingface.co/join), wenn Sie noch keines haben, und melden Sie sich dann an, um Ihr ["User Access Token"](https://huggingface.co/docs/hub/security-tokens) von Ihrer [Einstellungsseite](https://huggingface.co/settings/tokens) zu erhalten. Das "User Access Token" wird verwendet, um Ihre Identität gegenüber dem Hub zu authentifizieren. Sobald Sie Ihr "User Access Token" haben, führen Sie den folgenden Befehl in Ihrem Terminal aus: ```bash hf auth login # or using an environment variable hf auth login --token $HUGGINGFACE_TOKEN ``` Alternativ können Sie sich auch programmatisch in einem Notebook oder einem Skript mit [`login`] anmelden: ```py >>> from huggingface_hub import login >>> login() ``` Es ist auch möglich, sich programmatisch anzumelden, ohne aufgefordert zu werden, Ihr Token einzugeben, indem Sie das Token direkt an [`login`] weitergeben, wie z.B. `login(token="hf_xxx")`. Seien Sie vorsichtig, wenn Sie Ihren Quellcode teilen. Es ist eine bewährte Methode, das Token aus einem sicheren Tresor/Vault zu laden, anstatt es explizit in Ihrer Codebasis/Notebook zu speichern. Sie können nur auf 1 Konto gleichzeitig angemeldet sein. Wenn Sie Ihren Computer mit einem neuen Konto anmelden, werden Sie vom vorherigen abgemeldet. Mit dem Befehl `hf auth whoami` stellen Sie sicher, dass Sie immer wissen, welches Konto Sie gerade verwenden. Wenn Sie mehrere Konten im selben Skript verwalten möchten, können Sie Ihr Token bereitstellen, wenn Sie jede Methode aufrufen. Dies ist auch nützlich, wenn Sie kein Token auf Ihrem Computer speichern möchten. > [!WARNING] > Sobald Sie angemeldet sind, werden alle Anfragen an den Hub - auch Methoden, die nicht unbedingt eine Authentifizierung erfordern - standardmäßig Ihr Zugriffstoken verwenden. Wenn Sie die implizite Verwendung Ihres Tokens deaktivieren möchten, sollten Sie die Umgebungsvariable `HF_HUB_DISABLE_IMPLICIT_TOKEN` setzen. ## Eine Repository erstellen Nachdem Sie sich registriert und angemeldet haben, können Sie mit der Funktion [`create_repo`] ein Repository erstellen: ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.create_repo(repo_id="super-cool-model") ``` If you want your repository to be private, then: ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.create_repo(repo_id="super-cool-model", private=True) ``` Private Repositories sind für niemanden außer Ihnen selbst sichtbar. > [!TIP] > Um eine Repository zu erstellen oder Inhalte auf den Hub zu pushen, müssen Sie ein "User Access Token" bereitstellen, das die Schreibberechtigung (`write`) hat. Sie können die Berechtigung auswählen, wenn Sie das Token auf Ihrer [Einstellungsseite](https://huggingface.co/settings/tokens) erstellen. ## Dateien hochladen Verwenden Sie die [`upload_file`]-Funktion, um eine Datei zu Ihrem neu erstellten Repository hinzuzufügen. Sie müssen dabei das Folgende angeben: 1. Den Pfad der hochzuladenden Datei. 2. Den Pfad der Datei im Repository. 3. Die Repository-ID, zu der Sie die Datei hinzufügen möchten. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.upload_file( ... path_or_fileobj="/home/lysandre/dummy-test/README.md", ... path_in_repo="README.md", ... repo_id="lysandre/test-model", ... ) ``` Um mehr als eine Datei gleichzeitig hochzuladen, werfen Sie bitte einen Blick auf den [Upload](./guides/upload)-Leitfaden, der Ihnen verschiedene Methoden zum Hochladen von Dateien vorstellt (mit oder ohne git). ## Nächste Schritte Die `huggingface_hub`-Bibliothek bietet den Benutzern eine einfache Möglichkeit, mittels Python mit dem Hub zu interagieren. Um mehr darüber zu erfahren, wie Sie Ihre Dateien und Repositories auf dem Hub verwalten können, empfehlen wir, unsere [How-to-Leitfäden](./guides/overview) zu lesen: - [Verwalten Sie Ihre Repository](./guides/repository). - Dateien vom Hub [herunterladen](./guides/download). - Dateien auf den Hub [hochladen](./guides/upload). - [Durchsuchen Sie den Hub](./guides/search) nach dem gewünschten Modell oder Datensatz. - [Greifen Sie auf die Inferenz-API zu](./guides/inference), um schnelle Inferenzen durchzuführen. huggingface_hub-1.1.5/docs/source/en/000077500000000000000000000000001510763414300174615ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/en/_redirects.yml000066400000000000000000000013631510763414300223320ustar00rootroot00000000000000# Move "how-to" pages to the guides/ folder how-to-cache: guides/manage-cache how-to-discussions-and-pull-requests: guides/community how-to-downstream: guides/download how-to-inference: guides/inference how-to-manage: guides/repository how-to-model-cards: guides/model-cards how-to-upstream: guides/upload search-the-hub: guides/search guides/manage_spaces: guides/manage-spaces package_reference/inference_api: package_reference/inference_client package_reference/login: package_reference/authentication # Alias for hf-transfer description hf_transfer: package_reference/environment_variables#hfhubenablehftransfer # Alias for auth authentication: quick-start#authentication # Rename webhooks_server to webhooks guides/webhooks_server: guides/webhooks huggingface_hub-1.1.5/docs/source/en/_toctree.yml000066400000000000000000000060361510763414300220150ustar00rootroot00000000000000- title: 'Get started' sections: - local: index title: Home - local: quick-start title: Quickstart - local: installation title: Installation - title: 'How-to guides' sections: - local: guides/overview title: Overview - local: guides/download title: Download files - local: guides/upload title: Upload files - local: guides/cli title: Use the CLI - local: guides/hf_file_system title: HfFileSystem - local: guides/repository title: Repository - local: guides/search title: Search - local: guides/inference title: Inference - local: guides/inference_endpoints title: Inference Endpoints - local: guides/jobs title: Jobs - local: guides/community title: Community Tab - local: guides/collections title: Collections - local: guides/manage-cache title: Cache - local: guides/model-cards title: Model Cards - local: guides/manage-spaces title: Manage your Space - local: guides/integrations title: Integrate a library - local: guides/webhooks title: Webhooks - title: 'Conceptual guides' sections: - local: concepts/git_vs_http title: Git vs HTTP paradigm - local: concepts/migration title: Migrating to huggingface_hub v1.0 - title: 'Reference' sections: - local: package_reference/overview title: Overview - local: package_reference/authentication title: Authentication - local: package_reference/environment_variables title: Environment variables - local: package_reference/hf_api title: Hugging Face Hub API - local: package_reference/cli title: CLI - local: package_reference/file_download title: Downloading files - local: package_reference/mixins title: Mixins & serialization methods - local: package_reference/inference_types title: Inference Types - local: package_reference/inference_client title: Inference Client - local: package_reference/inference_endpoints title: Inference Endpoints - local: package_reference/mcp title: MCP Client - local: package_reference/hf_file_system title: HfFileSystem - local: package_reference/utilities title: Utilities - local: package_reference/community title: Discussions and Pull Requests - local: package_reference/cache title: Cache-system reference - local: package_reference/cards title: Repo Cards and Repo Card Data - local: package_reference/space_runtime title: Space runtime - local: package_reference/collections title: Collections - local: package_reference/tensorboard title: TensorBoard logger - local: package_reference/webhooks_server title: Webhooks server - local: package_reference/serialization title: Serialization - local: package_reference/dataclasses title: Strict dataclasses - local: package_reference/oauth title: OAuth - local: package_reference/jobs title: Jobs huggingface_hub-1.1.5/docs/source/en/concepts/000077500000000000000000000000001510763414300212775ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/en/concepts/git_vs_http.md000066400000000000000000000065161510763414300241630ustar00rootroot00000000000000 # Git vs HTTP paradigm The `huggingface_hub` library is a library for interacting with the Hugging Face Hub, which is a collection of git-based repositories (models, datasets or Spaces). There are two main ways to access the Hub using `huggingface_hub`. The first approach, the so-called "git-based" approach, relies on using standard `git` commands directly in a terminal. This method allows you to clone repositories, create commits, and push changes manually. The second option, called the "HTTP-based" approach, involves making HTTP requests using the [`HfApi`] client. Let's examine the pros and cons of each approach. ## Git: the historical CLI-based approach At first, most users interacted with the Hugging Face Hub using plain `git` commands such as `git clone`, `git add`, `git commit`, `git push`, `git tag`, or `git checkout`. This approach lets you work with a full local copy of the repository on your machine, just like in traditional software development. This can be an advantage when you need offline access or want to work with the full history of a repository. However, it also comes with downsides: you are responsible for keeping the repository up-to-date locally, handling credentials, and managing large files (via `git-lfs`), which can become cumbersome when working with large machine learning models or datasets. In many machine learning workflows, you may only need to download a few files for inference or convert weights without needing to clone the entire repository. In such cases, using `git` can be overkill and introduce unnecessary complexity. ## HfApi: a flexible and convenient HTTP client The [`HfApi`] class was developed to provide an alternative to using local git repositories, which can be cumbersome to maintain, especially when dealing with large models or datasets. The [`HfApi`] class offers the same functionality as git-based workflows -such as downloading and pushing files and creating branches and tags- but without the need for a local folder that needs to be kept in sync. In addition to the functionalities already provided by `git`, the [`HfApi`] class offers additional features, such as the ability to manage repos, download files using caching for efficient reuse, search the Hub for repos and metadata, access community features such as discussions, PRs, and comments, and configure Spaces hardware and secrets. ## What should I use ? And when ? Overall, the **HTTP-based approach is the recommended way to use** `huggingface_hub` in all cases. [`HfApi`] allows you to pull and push changes, work with PRs, tags and branches, interact with discussions and much more. However, not all git commands are available through [`HfApi`]. Some may never be implemented, but we are always trying to improve and close the gap. If you don't see your use case covered, please open [an issue on GitHub](https://github.com/huggingface/huggingface_hub)! We welcome feedback to help build the HF ecosystem with and for our users. This preference for the HTTP-based [`HfApi`] over direct `git` commands does not mean that git versioning will disappear from the Hugging Face Hub anytime soon. It will always be possible to use `git` locally in workflows where it makes sense.huggingface_hub-1.1.5/docs/source/en/concepts/migration.md000066400000000000000000000242511510763414300236160ustar00rootroot00000000000000# Migrating to huggingface_hub v1.0 The v1.0 release is a major milestone for the `huggingface_hub` library. It marks our commitment to API stability and the maturity of the library. We have made several improvements and breaking changes to make the library more robust and easier to use. This guide is intended to help you migrate your existing code to the new version. If you have any questions or feedback, please let us know by [opening an issue on GitHub](https://github.com/huggingface/huggingface_hub/issues). ## Python 3.9+ `huggingface_hub` now requires Python 3.9 or higher. Python 3.8 is no longer supported. ## HTTPX migration The `huggingface_hub` library now uses [`httpx`](https://www.python-httpx.org/) instead of `requests` for HTTP requests. This change was made to improve performance and to support both synchronous and asynchronous requests the same way. We therefore dropped both `requests` and `aiohttp` dependencies. ### Breaking changes This is a major change that affects the entire library. While we have tried to make this change as transparent as possible, you may need to update your code in some cases. Here is a list of breaking changes introduced in the process: - **Proxy configuration**: "per method" proxies are no longer supported. Proxies must be configured globally using the `HTTP_PROXY` and `HTTPS_PROXY` environment variables. - **Custom HTTP backend**: The `configure_http_backend` function has been removed. You should now use [`set_client_factory`] and [`set_async_client_factory`] to configure the HTTP clients. - **Error handling**: HTTP errors are not inherited from `requests.HTTPError` anymore, but from `httpx.HTTPError`. We recommend catching `huggingface_hub.HfHubHttpError` which is a subclass of `requests.HTTPError` in v0.x and of `httpx.HTTPError` in v1.x. Catching from the `huggingface_hub` error ensures your code is compatible with both the old and new versions of the library. - **SSLError**: `httpx` does not have the concept of `SSLError`. It is now a generic `httpx.ConnectError`. - **`LocalEntryNotFoundError`**: This error no longer inherits from `HTTPError`. We now define a `EntryNotFoundError` (new) that is inherited by both [`LocalEntryNotFoundError`] (if file not found in local cache) and [`RemoteEntryNotFoundError`] (if file not found in repo on the Hub). Only the remote error inherits from `HTTPError`. - **`InferenceClient`**: The `InferenceClient` can now be used as a context manager. This is especially useful when streaming tokens from a language model to ensure that the connection is closed properly. - **`AsyncInferenceClient`**: The `trust_env` parameter has been removed from the `AsyncInferenceClient`'s constructor. Environment variables are trusted by default by `httpx`. If you explicitly don't want to trust the environment, you must configure it with [`set_client_factory`]. For more details, you can check [PR #3328](https://github.com/huggingface/huggingface_hub/pull/3328) that introduced `httpx`. ### Why `httpx`? The migration from `requests` to `httpx` brings several key improvements that enhance the library's performance, reliability, and maintainability: **Thread Safety and Connection Reuse**: `httpx` is thread-safe by design, allowing us to safely reuse the same client across multiple threads. This connection reuse reduces the overhead of establishing new connections for each HTTP request, improving performance especially when making frequent requests to the Hub. **HTTP/2 Support**: `httpx` provides native HTTP/2 support, which offers better efficiency when making multiple requests to the same server (exactly our use case). This translates to lower latency and reduced resource consumption compared to HTTP/1.1. **Unified Sync/Async API**: Unlike our previous setup with separate `requests` (sync) and `aiohttp` (async) dependencies, `httpx` provides both synchronous and asynchronous clients with identical behavior. This ensures that `InferenceClient` and `AsyncInferenceClient` have consistent functionality and eliminates subtle behavioral differences that previously existed between the two implementations. **Improved SSL Error Handling**: `httpx` handles SSL errors more gracefully, making debugging connection issues easier and more reliable. **Future-Proof Architecture**: `httpx` is actively maintained and designed for modern Python applications. In contrast, `requests` is in maintenance mode and won't receive major updates like thread-safety improvements or HTTP/2 support. **Better Environment Variable Handling**: `httpx` provides more consistent handling of environment variables across both sync and async contexts, eliminating previous inconsistencies where `requests` would read local environment variables by default while `aiohttp` would not. The transition to `httpx` positions `huggingface_hub` with a modern, efficient, and maintainable HTTP backend. While most users should experience seamless operation, the underlying improvements provide better performance and reliability for all Hub interactions. ## `hf_transfer` Now that all repositories on the Hub are Xet-enabled and that `hf_xet` is the default way to download/upload files, we've removed support for the `hf_transfer` optional package. The `HF_HUB_ENABLE_HF_TRANSFER` environment variable is therefore ignored. Use [`HF_XET_HIGH_PERFORMANCE`](../package_reference/environment_variables.md) instead. ## `Repository` class The `Repository` class has been removed in v1.0. It was a thin wrapper around the `git` CLI for managing repositories. You can still use `git` directly in the terminal, but the recommended approach is to use the HTTP-based API in the `huggingface_hub` library for a smoother experience, especially when dealing with large files. Here is a mapping from the legacy `Repository` class to the new `HfApi` one: | `Repository` method | `HfApi` method | | ------------------------------------------ | ----------------------------------------------------- | | `repo.clone_from` | `snapshot_download` | | `repo.git_add` + `git_commit` + `git_push` | [`upload_file`], [`upload_folder`], [`create_commit`] | | `repo.git_tag` | `create_tag` | | `repo.git_branch` | `create_branch` | ## `HfFolder` class `HfFolder` was used to manage the user access token. Use [`login`] to save a new token, [`logout`] to delete it and [`whoami`] to check the user associated to the current token. Finally, use [`get_token`] to retrieve user's token in a script. ## `InferenceApi` class `InferenceApi` was a class to interact with the Inference API. It is now recommended to use the [`InferenceClient`] class instead. ## Other deprecated features Some methods and parameters have been removed in v1.0. The ones listed below have already been deprecated with a warning message in v0.x. - `constants.hf_cache_home` has been removed. Please use `HF_HOME` instead. - `use_auth_token` parameters have been removed from all methods. Please use `token` instead. - `get_token_permission` method has been removed. - `update_repo_visibility` method has been removed. Please use `update_repo_settings` instead. - `is_write_action` parameter has been removed from `build_hf_headers` as well as `write_permission` from `login`. The concept of "write permission" has been removed and is no longer relevant now that fine-grained tokens are the recommended approach. - `new_session` parameter in `login` has been renamed to `skip_if_logged_in` for better clarity. - `resume_download`, `force_filename`, and `local_dir_use_symlinks` parameters have been removed from `hf_hub_download` and `snapshot_download`. - `library`, `language`, `tags`, and `task` parameters have been removed from `list_models`. ## CLI cache commands Cache management from the CLI has been redesigned to follow a Docker-inspired workflow. The deprecated `huggingface-cli` has been removed, `hf` (introduced in v0.34) replaces it with a clearer ressource-action CLI. The legacy `hf cache scan` and `hf cache delete` commands are also removed in v1.0 and are replaced with the new trio below: - `hf cache ls` lists cache entries with concise table, JSON, or CSV output. Use `--revisions` to inspect individual revisions, add `--filter` expressions such as `size>1GB` or `accessed>30d`, and combine them with `--quiet` when you only need the identifiers. - `hf cache rm` deletes selected cache entries. Pass one or more repo IDs (for example `model/bert-base-uncased`) or revision hashes, and optionally add `--dry-run` to preview or `--yes` to skip the confirmation prompt. This replaces both the interactive TUI and `--disable-tui` workflows from the previous command. - `hf cache prune` performs the common cleanup task of deleting unreferenced revisions in one shot. Add `--dry-run` or `--yes` in the same way as with `hf cache rm`. Finally, the `[cli]` extra has been removed - The CLI now ships with the core `huggingface_hub` package. ## TensorFlow and Keras 2.x support All TensorFlow-related code and dependencies have been removed in v1.0. This includes the following breaking changes: - `huggingface_hub[tensorflow]` is no longer a supported extra dependency - The `split_tf_state_dict_into_shards` and `get_tf_storage_size` utility functions have been removed. - The `tensorflow`, `fastai`, and `fastcore` versions are no longer included in the built-in headers. The Keras 2.x integration has also been removed. This includes the `KerasModelHubMixin` class and the `save_pretrained_keras`, `from_pretrained_keras`, and `push_to_hub_keras` utilities. Keras 2.x is a legacy and unmaintained library. The recommended approach is to use Keras 3.x which is tightly integrated with the Hub (i.e. it contains built-in method to load/push to Hub). If you still want to work with Keras 2.x, you should downgrade `huggingface_hub` to v0.x version. ## `upload_file` and `upload_folder` return values The [`upload_file`] and [`upload_folder`] functions now return the URL of the commit created on the Hub. Previously, they returned the URL of the file or folder. This is to align with the return value of [`create_commit`], [`delete_file`] and [`delete_folder`]. huggingface_hub-1.1.5/docs/source/en/guides/000077500000000000000000000000001510763414300207415ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/en/guides/cli.md000066400000000000000000001175421510763414300220440ustar00rootroot00000000000000 # Command Line Interface (CLI) The `huggingface_hub` Python package comes with a built-in CLI called `hf`. This tool allows you to interact with the Hugging Face Hub directly from a terminal. For example, you can log in to your account, create a repository, upload and download files, etc. It also comes with handy features to configure your machine or manage your cache. In this guide, we will have a look at the main features of the CLI and how to use them. > [!TIP] > This guide covers the most important features of the `hf` CLI. > For a complete reference of all commands and options, see the [CLI reference](../package_reference/cli.md). ## Getting started First of all, let's install the CLI: ``` >>> pip install -U "huggingface_hub" ``` > [!TIP] > The CLI ships with the core `huggingface_hub` package. Alternatively, you can install the `hf` CLI with a single command: On macOS and Linux: ```bash >>> curl -LsSf https://hf.co/cli/install.sh | bash ``` On Windows: ```powershell >>> powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex" ``` Alternatively, you can install the `hf` CLI with a single command: On macOS and Linux: ```bash >>> curl -LsSf https://hf.co/cli/install.sh | sh ``` On Windows: ```powershell >>> powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex" ``` Once installed, you can check that the CLI is correctly setup: ``` >>> hf --help Usage: hf [OPTIONS] COMMAND [ARGS]... Hugging Face Hub CLI Options: --install-completion Install completion for the current shell. --show-completion Show completion for the current shell, to copy it or customize the installation. --help Show this message and exit. Commands: auth Manage authentication (login, logout, etc.). cache Manage local cache directory. download Download files from the Hub. env Print information about the environment. jobs Run and manage Jobs on the Hub. repo Manage repos on the Hub. repo-files Manage files in a repo on the Hub. upload Upload a file or a folder to the Hub. upload-large-folder Upload a large folder to the Hub. version Print information about the hf version. ``` If the CLI is correctly installed, you should see a list of all the options available in the CLI. If you get an error message such as `command not found: hf`, please refer to the [Installation](../installation) guide. > [!TIP] > The `--help` option is very convenient for getting more details about a command. You can use it anytime to list all available options and their details. For example, `hf upload --help` provides more information on how to upload files using the CLI. ### Other installation methods #### Using uv You can install and run the `hf` CLI with [uv](https://docs.astral.sh/uv/). Make sure uv is installed (adds `uv` and `uvx` to your PATH): ```bash >>> curl -LsSf https://astral.sh/uv/install.sh | sh ``` Then install the CLI globally and use it anywhere: ```bash >>> uv tool install "huggingface_hub" >>> hf auth whoami ``` Alternatively, run the CLI ephemerally with `uvx` (no global install): ```bash >>> uvx --from huggingface_hub hf auth whoami ``` #### Using Homebrew You can also install the CLI using [Homebrew](https://brew.sh/): ```bash >>> brew install huggingface-cli ``` Check out the Homebrew huggingface page [here](https://formulae.brew.sh/formula/huggingface-cli) for more details. ## hf auth login In many cases, you must be logged in to a Hugging Face account to interact with the Hub (download private repos, upload files, create PRs, etc.). To do so, you need a [User Access Token](https://huggingface.co/docs/hub/security-tokens) from your [Settings page](https://huggingface.co/settings/tokens). The User Access Token is used to authenticate your identity to the Hub. Make sure to set a token with write access if you want to upload or modify content. Once you have your token, run the following command in your terminal: ```bash >>> hf auth login ``` This command will prompt you for a token. Copy-paste yours and press *Enter*. Then, you'll be asked if the token should also be saved as a git credential. Press *Enter* again (default to yes) if you plan to use `git` locally. Finally, it will call the Hub to check that your token is valid and save it locally. ``` _| _| _| _| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _|_|_|_| _|_| _|_|_| _|_|_|_| _| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _| _|_|_|_| _| _| _| _|_| _| _|_| _| _| _| _| _| _|_| _|_|_| _|_|_|_| _| _|_|_| _| _| _| _| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _| _| _| _|_| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _| _| _| _|_|_| _|_|_|_| To log in, `huggingface_hub` requires a token generated from https://huggingface.co/settings/tokens . Enter your token (input will not be visible): Add token as git credential? (Y/n) Token is valid (permission: write). 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 ``` Alternatively, if you want to log-in without being prompted, you can pass the token directly from the command line. To be more secure, we recommend passing your token as an environment variable to avoid pasting it in your command history. ```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` ``` For more details about authentication, check out [this section](../quick-start#authentication). ## hf auth whoami If you want to know if you are logged in, you can use `hf auth whoami`. This command doesn't have any options and simply prints your username and the organizations you are a part of on the Hub: ```bash hf auth whoami Wauplin orgs: huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolCluster ``` If you are not logged in, an error message will be printed. ## hf auth logout This command logs you out. In practice, it will delete all tokens stored on your machine. If you want to remove a specific token, you can specify the token name as an argument. This command will not log you out if you are logged in using the `HF_TOKEN` environment variable (see [reference](../package_reference/environment_variables#hftoken)). If that is the case, you must unset the environment variable in your machine configuration. ## hf download Use the `hf download` command to download files from the Hub directly. Internally, it uses the same [`hf_hub_download`] and [`snapshot_download`] helpers described in the [Download](./download) guide and prints the returned path to the terminal. In the examples below, we will walk through the most common use cases. For a full list of available options, you can run: ```bash hf download --help ``` ### Download a single file To download a single file from a repo, simply provide the repo_id and filename as follows: ```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 ``` The command will always print on the last line the path to the file on your local machine. To download a file located in a subdirectory of the repo, you should provide the path of the file in the repo in posix format like this: ```bash >>> hf download HiDream-ai/HiDream-I1-Full text_encoder/model.safetensors ``` ### Download an entire repository In some cases, you just want to download all the files from a repository. This can be done by just specifying the repo 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 ... ``` ### Download a specific revision The examples above show how to download from the latest commit on the main branch. To download from a specific revision (commit hash, branch name or tag), use the `--revision` option: ```bash >>> hf download bigcode/the-stack --repo-type dataset --revision v1.1 ... ``` ### Download to a local folder The recommended (and default) way to download files from the Hub is to use the cache-system. However, in some cases you want to download files and move them to a specific folder. This is useful to get a workflow closer to what git commands offer. You can do that using the `--local-dir` option. A `.cache/huggingface/` folder is created at the root of your local directory containing metadata about the downloaded files. This prevents re-downloading files if they're already up-to-date. If the metadata has changed, then the new file version is downloaded. This makes the `local-dir` optimized for pulling only the latest changes. > [!TIP] > For more details on how downloading to a local file works, check out the [download](./download#download-files-to-a-local-folder) guide. ```bash >>> hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu ... fuyu/model-00001-of-00002.safetensors ``` ### Dry-run mode In some cases, you would like to check which files would be downloaded before actually downloading them. You can check this using the `--dry-run` parameter. It lists all files to download on the repo and checks whether they are already downloaded or not. This gives an idea of how many files have to be downloaded and their sizes. ```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 - ``` For more details, check out the [download guide](./download.md#dry-run-mode). ### Specify cache directory If not using `--local-dir`, all files will be downloaded by default to the cache directory defined by the `HF_HOME` [environment variable](../package_reference/environment_variables#hfhome). You can specify a custom cache using `--cache-dir`: ```bash >>> hf download adept/fuyu-8b --cache-dir ./path/to/cache ... ./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745 ``` ### Specify a token To access private or gated repositories, you must use a token. By default, the token saved locally (using `hf auth login`) will be used. If you want to authenticate explicitly, use the `--token` option: ```bash >>> hf download gpt2 config.json --token=hf_**** /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json ``` ### Quiet mode By default, the `hf download` command will be verbose. It will print details such as warning messages, information about the downloaded files, and progress bars. If you want to silence all of this, use the `--quiet` option. Only the last line (i.e. the path to the downloaded files) is printed. This can prove useful if you want to pass the output to another command in a script. ```bash >>> hf download gpt2 --quiet /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 ``` ### Download timeout On machines with slow connections, you might encounter timeout issues like this one: ```bash `httpx.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)')` ``` To mitigate this issue, you can set the `HF_HUB_DOWNLOAD_TIMEOUT` environment variable to a higher value (default is 10): ```bash export HF_HUB_DOWNLOAD_TIMEOUT=30 ``` For more details, check out the [environment variables reference](../package_reference/environment_variables#hfhubdownloadtimeout). And rerun your download command. ## hf upload Use the `hf upload` command to upload files to the Hub directly. Internally, it uses the same [`upload_file`] and [`upload_folder`] helpers described in the [Upload](./upload) guide. In the examples below, we will walk through the most common use cases. For a full list of available options, you can run: ```bash >>> hf upload --help ``` ### Upload an entire folder The default usage for this command is: ```bash # Usage: hf upload [repo_id] [local_path] [path_in_repo] ``` To upload the current directory at the root of the repo, use: ```bash >>> hf upload my-cool-model . . https://huggingface.co/Wauplin/my-cool-model/tree/main/ ``` > [!TIP] > If the repo doesn't exist yet, it will be created automatically. You can also upload a specific folder: ```bash >>> hf upload my-cool-model ./models . https://huggingface.co/Wauplin/my-cool-model/tree/main/ ``` Finally, you can upload a folder to a specific destination on the repo: ```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 You can also upload a single file by setting `local_path` to point to a file on your machine. If that's the case, `path_in_repo` is optional and will default to the name of your local file: ```bash >>> hf upload Wauplin/my-cool-model ./models/model.safetensors https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors ``` If you want to upload a single file to a specific directory, set `path_in_repo` accordingly: ```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 ``` ### Upload multiple files To upload multiple files from a folder at once without uploading the entire folder, use the `--include` and `--exclude` patterns. It can also be combined with the `--delete` option to delete files on the repo while uploading new ones. In the example below, we sync the local Space by deleting remote files and uploading all files except the ones in `/logs`: ```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" ... ``` ### Upload to a dataset or Space To upload to a dataset or a Space, use the `--repo-type` option: ```bash >>> hf upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset ... ``` ### Upload to an organization To upload content to a repo owned by an organization instead of a personal repo, you must explicitly specify it in the `repo_id`: ```bash >>> hf upload MyCoolOrganization/my-cool-model . . https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/ ``` ### Upload to a specific revision By default, files are uploaded to the `main` branch. If you want to upload files to another branch or reference, use the `--revision` option: ```bash # Upload files to a PR >>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104 ... ``` **Note:** if `revision` does not exist and `--create-pr` is not set, a branch will be created automatically from the `main` branch. ### Upload and create a PR If you don't have the permission to push to a repo, you must open a PR and let the authors know about the changes you want to make. This can be done by setting the `--create-pr` option: ```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/ ``` ### Upload at regular intervals In some cases, you might want to push regular updates to a repo. For example, this is useful if you're training a model and you want to upload the logs folder every 10 minutes. You can do this using the `--every` option: ```bash # Upload new logs every 10 minutes hf upload training-model logs/ --every=10 ``` ### Specify a commit message Use the `--commit-message` and `--commit-description` to set a custom message and description for your commit instead of the default one ```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 ``` ### Specify a token To upload files, you must use a token. By default, the token saved locally (using `hf auth login`) will be used. If you want to authenticate explicitly, use the `--token` option: ```bash >>> hf upload Wauplin/my-cool-model ./models . --token=hf_**** ... https://huggingface.co/Wauplin/my-cool-model/tree/main ``` ### Quiet mode By default, the `hf upload` command will be verbose. It will print details such as warning messages, information about the uploaded files, and progress bars. If you want to silence all of this, use the `--quiet` option. Only the last line (i.e. the URL to the uploaded files) is printed. This can prove useful if you want to pass the output to another command in a script. ```bash >>> hf upload Wauplin/my-cool-model ./models . --quiet https://huggingface.co/Wauplin/my-cool-model/tree/main ``` ## hf repo `hf repo` lets you create, delete, move repositories and update their settings on the Hugging Face Hub. It also includes subcommands to manage branches and tags. ### Create a repo ```bash >>> hf repo 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 ``` Create a private dataset or a Space: ```bash >>> hf repo create my-cool-dataset --repo-type dataset --private >>> hf repo create my-gradio-space --repo-type space --space-sdk gradio ``` Use `--exist-ok` if the repo may already exist, and `--resource-group-id` to target an Enterprise resource group. ### Delete a repo ```bash >>> hf repo delete Wauplin/my-cool-model ``` Datasets and Spaces: ```bash >>> hf repo delete my-cool-dataset --repo-type dataset >>> hf repo delete my-gradio-space --repo-type space ``` ### Move a repo ```bash >>> hf repo move old-namespace/my-model new-namespace/my-model ``` ### Update repo settings ```bash >>> hf repo settings Wauplin/my-cool-model --gated auto >>> hf repo settings Wauplin/my-cool-model --private true >>> hf repo settings Wauplin/my-cool-model --private false ``` - `--gated`: one of `auto`, `manual`, `false` - `--private true|false`: set repository privacy ### Manage branches ```bash >>> hf repo branch create Wauplin/my-cool-model dev >>> hf repo branch create Wauplin/my-cool-model release-1 --revision refs/pr/104 >>> hf repo branch delete Wauplin/my-cool-model dev ``` > [!TIP] > All commands accept `--repo-type` (one of `model`, `dataset`, `space`) and `--token` if you need to authenticate explicitly. Use `--help` on any command to see all options. ## hf repo-files If you want to delete files from a Hugging Face repository, use the `hf repo-files` command. ### Delete files The `hf repo-files delete ` sub-command allows you to delete files from a repository. Here are some usage examples. Delete a folder : ```bash >>> hf repo-files delete Wauplin/my-cool-model folder/ Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo... ``` Delete multiple files: ```bash >>> hf repo-files delete Wauplin/my-cool-model file.txt folder/pytorch_model.bin Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo... ``` Use Unix-style wildcards to delete sets of files: ```bash >>> hf repo-files delete Wauplin/my-cool-model "*.txt" "folder/*.bin" Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo... ``` ### Specify a token To delete files from a repo you must be authenticated and authorized. By default, the token saved locally (using `hf auth login`) will be used. If you want to authenticate explicitly, use the `--token` option: ```bash >>> hf repo-files delete --token=hf_**** Wauplin/my-cool-model file.txt ``` ## hf cache ls Use `hf cache ls` to inspect what is stored locally in your Hugging Face cache. By default it aggregates information by repository: ```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. ``` Add `--revisions` to drill down to specific snapshots, and chain filters to focus on what matters: ```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. ``` The command supports several output formats for scripting: `--format json` prints structured objects, `--format csv` writes comma-separated rows, and `--quiet` prints only IDs. Use `--sort` to order entries by `accessed`, `modified`, `name`, or `size` (append `:asc` or `:desc` to control order), and `--limit` to restrict results to the top N entries. Combine these with `--cache-dir` to target alternative cache locations. See the [Manage your cache](./manage-cache) guide for advanced workflows. Delete cache entries selected with `hf cache ls --q` by piping the IDs into `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) Delete repo: ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct Delete repo: ~/.cache/huggingface/hub/models--hexgrad--Kokoro-82M Cache deletion done. Saved 5.31G. Deleted 2 repo(s) and 2 revision(s); freed 5.31G. ``` ## hf cache rm `hf cache rm` removes cached repositories or individual revisions. Pass one or more repo IDs (`model/bert-base-uncased`) or revision hashes: ```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 Delete repo: ~/.cache/huggingface/hub/models--LiquidAI--LFM2-VL-1.6B Cache deletion done. Saved 3.2G. Deleted 1 repo(s) and 2 revision(s); freed 3.2G. ``` Mix repositories and specific revisions in the same call. Use `--dry-run` to preview the impact, or `--yes` to skip the confirmation prompt—handy in automated scripts: ```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. ``` When working outside the default cache location, pair the command with `--cache-dir PATH`. ## hf cache prune `hf cache prune` is a convenience shortcut that deletes every detached (unreferenced) revision in your cache. This keeps only revisions that are still reachable through a branch or tag: ```bash >>> hf cache prune About to delete 3 unreferenced revision(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); freed 2.4G. ``` As with the other cache commands, `--dry-run`, `--yes`, and `--cache-dir` are available. Refer to the [Manage your cache](./manage-cache) guide for more examples. ## hf cache verify Use `hf cache verify` to validate local files against their checksums on the Hub. You can verify either a cache snapshot or a regular local directory. Examples: ```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 ``` By default, the command warns about missing or extra files. Use flags to turn these warnings into errors: ```bash >>> hf cache verify deepseek-ai/DeepSeek-OCR --fail-on-missing-files --fail-on-extra-files ``` On success, you will see a summary: ```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. ``` If mismatches are detected, the command prints a detailed list and exits with a non-zero status. ## hf repo tag create The `hf repo tag create` command allows you to tag, untag, and list tags for repositories. ### Tag a model To tag a repo, you need to provide the `repo_id` and the `tag` name: ```bash >>> hf repo 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 ``` ### Tag a model at a specific revision If you want to tag a specific revision, you can use the `--revision` option. By default, the tag will be created on the `main` branch: ```bash >>> hf repo 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 ``` ### Tag a dataset or a Space If you want to tag a dataset or Space, you must specify the `--repo-type` option: ```bash >>> hf repo 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 tags To list all tags for a repository, use the `-l` or `--list` option: ```bash >>> hf repo tag create Wauplin/gradio-space-ci -l --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 a tag To delete a tag, use the `-d` or `--delete` option: ```bash >>> hf repo tag create -d 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 ``` You can also pass `-y` to skip the confirmation step. ## hf env The `hf env` command prints details about your machine setup. This is useful when you open an issue on [GitHub](https://github.com/huggingface/huggingface_hub) to help the maintainers investigate your problem. ```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 - httpx: 0.28.1 - 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_ETAG_TIMEOUT: 10 - HF_HUB_DOWNLOAD_TIMEOUT: 10 ``` ## hf jobs Run compute jobs on Hugging Face infrastructure with a familiar Docker-like interface. `hf jobs` is a command-line tool that lets you run anything on Hugging Face's infrastructure (including GPUs and TPUs!) with simple commands. Think `docker run`, but for running code on A100s. ```bash # Directly run Python code >>> hf jobs run 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 my_script.py ``` ### ✨ Key Features - 🐳 **Docker-like CLI**: Familiar commands (`run`, `ps`, `logs`, `inspect`) to run and manage jobs - 🔥 **Any Hardware**: From CPUs to A100 GPUs and TPU pods - switch with a simple flag - 📦 **Run Anything**: Use Docker images, HF Spaces, or your custom containers - 🔐 **Simple Auth**: Just use your HF token - 📊 **Live Monitoring**: Stream logs in real-time, just like running locally - 💰 **Pay-as-you-go**: Only pay for the seconds you use > [!TIP] > **Hugging Face Jobs** are available only to [Pro users](https://huggingface.co/pro) and [Team or Enterprise organizations](https://huggingface.co/enterprise). Upgrade your plan to get started! ### Quick Start #### 1. Run your first job ```bash # Run a simple Python script >>> hf jobs run python:3.12 python -c "print('Hello from HF compute!')" ``` This command runs the job and shows the logs. You can pass `--detach` to run the Job in the background and only print the Job ID. #### 2. Check job status ```bash # List your running jobs >>> hf jobs ps # Inspect the status of a job >>> hf jobs inspect # View logs from a job >>> hf jobs logs # Cancel a job >>> hf jobs cancel ``` #### 3. Run on GPU You can also run jobs on GPUs or TPUs with the `--flavor` option. For example, to run a PyTorch job on an A10G GPU: ```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()}")" ``` Running this will show the following output! ```bash This code ran with the following GPU: NVIDIA A10G ``` That's it! You're now running code on Hugging Face's infrastructure. ### Common Use Cases - **Model Training**: Fine-tune or train models on GPUs (T4, A10G, A100) without managing infrastructure - **Synthetic Data Generation**: Generate large-scale datasets using LLMs on powerful hardware - **Data Processing**: Process massive datasets with high-CPU configurations for parallel workloads - **Batch Inference**: Run offline inference on thousands of samples using optimized GPU setups - **Experiments & Benchmarks**: Run ML experiments on consistent hardware for reproducible results - **Development & Debugging**: Test GPU code without local CUDA setup ### Pass Environment variables and Secrets You can pass environment variables to your job using ```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 - they will be encrypted server side >>> hf jobs run -s MY_SECRET=psswrd 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'])" ``` > [!TIP] > Use `--secrets HF_TOKEN` to pass your local Hugging Face token implicitly. > With this syntax, the secret is retrieved from the environment variable. > For `HF_TOKEN`, it may read the token file located in the Hugging Face home folder if the environment variable is unset. ### Hardware Available `--flavor` options: - 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` (updated in 07/2025 from Hugging Face [suggested_hardware docs](https://huggingface.co/docs/hub/en/spaces-config-reference)) ### UV Scripts (Experimental) Run UV scripts (Python scripts with inline dependencies) on HF infrastructure: ```bash # Run a UV script (creates temporary repo) >>> hf jobs uv run my_script.py # Run with persistent repo >>> hf jobs uv run my_script.py --repo my-uv-scripts # Run with GPU >>> hf jobs uv run ml_training.py --flavor gpu-t4-small # 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 scripts are Python scripts that include their dependencies directly in the file using a special comment syntax. This makes them perfect for self-contained tasks that don't require complex project setups. Learn more about UV scripts in the [UV documentation](https://docs.astral.sh/uv/guides/scripts/). ### Scheduled Jobs Schedule and manage jobs that will run on HF infrastructure. The schedule should be one of `@annually`, `@yearly`, `@monthly`, `@weekly`, `@daily`, `@hourly`, or a CRON schedule expression (e.g., `"0 9 * * 1"` for 9 AM every Monday). ```bash # Schedule a job that runs every hour >>> hf jobs scheduled run @hourly 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 my_script.py ``` Use the same parameters as `hf jobs run` to pass environment variables, secrets, timeout, etc. Manage scheduled jobs using ```bash # List your active scheduled jobs >>> hf jobs scheduled ps # 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 # Delete a scheduled job >>> hf jobs scheduled delete ``` ## hf endpoints Use `hf endpoints` to list, deploy, describe, and manage Inference Endpoints directly from the terminal. The legacy `hf inference-endpoints` alias remains available for compatibility. ```bash # Lists endpoints in your namespace >>> hf endpoints ls # 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] > Add `--namespace` to target an organization, `--token` to override authentication. huggingface_hub-1.1.5/docs/source/en/guides/collections.md000066400000000000000000000227671510763414300236170ustar00rootroot00000000000000 # Collections A collection is a group of related items on the Hub (models, datasets, Spaces, papers) that are organized together on the same page. Collections are useful for creating your own portfolio, bookmarking content in categories, or presenting a curated list of items you want to share. Check out this [guide](https://huggingface.co/docs/hub/collections) to understand in more detail what collections are and how they look on the Hub. You can directly manage collections in the browser, but in this guide, we will focus on how to manage them programmatically. ## Fetch a collection Use [`get_collection`] to fetch your collections or any public ones. You must have the collection's *slug* to retrieve a collection. A slug is an identifier for a collection based on the title and a unique ID. You can find the slug in the URL of the collection page.
Let's fetch the collection with, `"TheBloke/recent-models-64f9a55bb3115b4f513ec026"`: ```py >>> from huggingface_hub import get_collection >>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026") >>> collection Collection( slug='TheBloke/recent-models-64f9a55bb3115b4f513ec026', title='Recent models', owner='TheBloke', items=[...], last_updated=datetime.datetime(2023, 10, 2, 22, 56, 48, 632000, tzinfo=datetime.timezone.utc), position=1, private=False, theme='green', upvotes=90, description="Models I've recently quantized. Please note that currently this list has to be updated manually, and therefore is not guaranteed to be up-to-date." ) >>> collection.items[0] CollectionItem( item_object_id='651446103cd773a050bf64c2', item_id='TheBloke/U-Amethyst-20B-AWQ', item_type='model', position=88, note=None ) ``` The [`Collection`] object returned by [`get_collection`] contains: - high-level metadata: `slug`, `owner`, `title`, `description`, etc. - a list of [`CollectionItem`] objects; each item represents a model, a dataset, a Space, or a paper. All collection items are guaranteed to have: - a unique `item_object_id`: this is the id of the collection item in the database - an `item_id`: this is the id on the Hub of the underlying item (model, dataset, Space, paper); it is not necessarily unique, and only the `item_id`/`item_type` pair is unique - an `item_type`: model, dataset, Space, paper - the `position` of the item in the collection, which can be updated to reorganize your collection (see [`update_collection_item`] below) A `note` can also be attached to the item. This is useful to add additional information about the item (a comment, a link to a blog post, etc.). The attribute still has a `None` value if an item doesn't have a note. In addition to these base attributes, returned items can have additional attributes depending on their type: `author`, `private`, `lastModified`, `gated`, `title`, `likes`, `upvotes`, etc. None of these attributes are guaranteed to be returned. ## List collections We can also retrieve collections using [`list_collections`]. Collections can be filtered using some parameters. Let's list all the collections from the user [`teknium`](https://huggingface.co/teknium). ```py >>> from huggingface_hub import list_collections >>> collections = list_collections(owner="teknium") ``` This returns an iterable of `Collection` objects. We can iterate over them to print, for example, the number of upvotes for each collection. ```py >>> for collection in collections: ... print("Number of upvotes:", collection.upvotes) Number of upvotes: 1 Number of upvotes: 5 ``` > [!WARNING] > When listing collections, the item list per collection is truncated to 4 items maximum. To retrieve all items from a collection, you must use [`get_collection`]. It is possible to do more advanced filtering. Let's get all collections containing the model [TheBloke/OpenHermes-2.5-Mistral-7B-GGUF](https://huggingface.co/TheBloke/OpenHermes-2.5-Mistral-7B-GGUF), sorted by trending, and limit the count to 5. ```py >>> collections = list_collections(item="models/TheBloke/OpenHermes-2.5-Mistral-7B-GGUF", sort="trending", limit=5): >>> for collection in collections: ... print(collection.slug) teknium/quantized-models-6544690bb978e0b0f7328748 AmeerH/function-calling-65560a2565d7a6ef568527af PostArchitekt/7bz-65479bb8c194936469697d8c gnomealone/need-to-test-652007226c6ce4cdacf9c233 Crataco/favorite-7b-models-651944072b4fffcb41f8b568 ``` Parameter `sort` must be one of `"last_modified"`, `"trending"` or `"upvotes"`. Parameter `item` accepts any particular item. For example: * `"models/teknium/OpenHermes-2.5-Mistral-7B"` * `"spaces/julien-c/open-gpt-rhyming-robot"` * `"datasets/squad"` * `"papers/2311.12983"` For more details, please check out [`list_collections`] reference. ## Create a new collection Now that we know how to get a [`Collection`], let's create our own! Use [`create_collection`] with a title and description. To create a collection on an organization page, pass `namespace="my-cool-org"` when creating the collection. Finally, you can also create private collections by passing `private=True`. ```py >>> from huggingface_hub import create_collection >>> collection = create_collection( ... title="ICCV 2023", ... description="Portfolio of models, papers and demos I presented at ICCV 2023", ... ) ``` It will return a [`Collection`] object with the high-level metadata (title, description, owner, etc.) and an empty list of items. You will now be able to refer to this collection using its `slug`. ```py >>> collection.slug 'owner/iccv-2023-15e23b46cb98efca45' >>> collection.title "ICCV 2023" >>> collection.owner "username" >>> collection.url 'https://huggingface.co/collections/owner/iccv-2023-15e23b46cb98efca45' ``` ## Manage items in a collection Now that we have a [`Collection`], we want to add items to it and organize them. ### Add items Items have to be added one by one using [`add_collection_item`]. You only need to know the `collection_slug`, `item_id` and `item_type`. Optionally, you can also add a `note` to the item (500 characters maximum). ```py >>> from huggingface_hub import create_collection, add_collection_item >>> collection = create_collection(title="OS Week Highlights - Sept 18 - 24", namespace="osanseviero") >>> collection.slug "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> add_collection_item(collection.slug, item_id="coqui/xtts", item_type="space") >>> add_collection_item( ... collection.slug, ... item_id="warp-ai/wuerstchen", ... item_type="model", ... note="Würstchen is a new fast and efficient high resolution text-to-image architecture and model" ... ) >>> add_collection_item(collection.slug, item_id="lmsys/lmsys-chat-1m", item_type="dataset") >>> add_collection_item(collection.slug, item_id="warp-ai/wuerstchen", item_type="space") # same item_id, different item_type ``` If an item already exists in a collection (same `item_id`/`item_type` pair), an HTTP 409 error will be raised. You can choose to ignore this error by setting `exists_ok=True`. ### Add a note to an existing item You can modify an existing item to add or modify the note attached to it using [`update_collection_item`]. Let's reuse the example above: ```py >>> from huggingface_hub import get_collection, update_collection_item # Fetch collection with newly added items >>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> collection = get_collection(collection_slug) # Add note the `lmsys-chat-1m` dataset >>> update_collection_item( ... collection_slug=collection_slug, ... item_object_id=collection.items[2].item_object_id, ... note="This dataset contains one million real-world conversations with 25 state-of-the-art LLMs.", ... ) ``` ### Reorder items Items in a collection are ordered. The order is determined by the `position` attribute of each item. By default, items are ordered by appending new items at the end of the collection. You can update the order using [`update_collection_item`] the same way you would add a note. Let's reuse our example above: ```py >>> from huggingface_hub import get_collection, update_collection_item # Fetch collection >>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> collection = get_collection(collection_slug) # Reorder to place the two `Wuerstchen` items together >>> update_collection_item( ... collection_slug=collection_slug, ... item_object_id=collection.items[3].item_object_id, ... position=2, ... ) ``` ### Remove items Finally, you can also remove an item using [`delete_collection_item`]. ```py >>> from huggingface_hub import get_collection, update_collection_item # Fetch collection >>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> collection = get_collection(collection_slug) # Remove `coqui/xtts` Space from the list >>> delete_collection_item(collection_slug=collection_slug, item_object_id=collection.items[0].item_object_id) ``` ## Delete collection A collection can be deleted using [`delete_collection`]. > [!WARNING] > This is a non-revertible action. A deleted collection cannot be restored. ```py >>> from huggingface_hub import delete_collection >>> collection = delete_collection("username/useless-collection-64f9a55bb3115b4f513ec026", missing_ok=True) ``` huggingface_hub-1.1.5/docs/source/en/guides/community.md000066400000000000000000000135111510763414300233100ustar00rootroot00000000000000 # Interact with Discussions and Pull Requests The `huggingface_hub` library provides a Python interface to interact with Pull Requests and Discussions on the Hub. Visit [the dedicated documentation page](https://huggingface.co/docs/hub/repositories-pull-requests-discussions) for a deeper view of what Discussions and Pull Requests on the Hub are, and how they work under the hood. ## Retrieve Discussions and Pull Requests from the Hub The `HfApi` class allows you to retrieve Discussions and Pull Requests on a given repo: ```python >>> from huggingface_hub import get_repo_discussions >>> for discussion in get_repo_discussions(repo_id="bigscience/bloom"): ... print(f"{discussion.num} - {discussion.title}, pr: {discussion.is_pull_request}") # 11 - Add Flax weights, pr: True # 10 - Update README.md, pr: True # 9 - Training languages in the model card, pr: True # 8 - Update tokenizer_config.json, pr: True # 7 - Slurm training script, pr: False [...] ``` `HfApi.get_repo_discussions` supports filtering by author, type (Pull Request or Discussion) and status (`open` or `closed`): ```python >>> from huggingface_hub import get_repo_discussions >>> for discussion in get_repo_discussions( ... repo_id="bigscience/bloom", ... author="ArthurZ", ... discussion_type="pull_request", ... discussion_status="open", ... ): ... print(f"{discussion.num} - {discussion.title} by {discussion.author}, pr: {discussion.is_pull_request}") # 19 - Add Flax weights by ArthurZ, pr: True ``` `HfApi.get_repo_discussions` returns a [generator](https://docs.python.org/3.7/howto/functional.html#generators) that yields [`Discussion`] objects. To get all the Discussions in a single list, run: ```python >>> from huggingface_hub import get_repo_discussions >>> discussions_list = list(get_repo_discussions(repo_id="bert-base-uncased")) ``` The [`Discussion`] object returned by [`HfApi.get_repo_discussions`] contains high-level overview of the Discussion or Pull Request. You can also get more detailed information using [`HfApi.get_discussion_details`]: ```python >>> from huggingface_hub import get_discussion_details >>> get_discussion_details( ... repo_id="bigscience/bloom-1b3", ... discussion_num=2 ... ) DiscussionWithDetails( num=2, author='cakiki', title='Update VRAM memory for the V100s', status='open', is_pull_request=True, events=[ DiscussionComment(type='comment', author='cakiki', ...), DiscussionCommit(type='commit', author='cakiki', summary='Update VRAM memory for the V100s', oid='1256f9d9a33fa8887e1c1bf0e09b4713da96773a', ...), ], conflicting_files=[], target_branch='refs/heads/main', merge_commit_oid=None, diff='diff --git a/README.md b/README.md\nindex a6ae3b9294edf8d0eda0d67c7780a10241242a7e..3a1814f212bc3f0d3cc8f74bdbd316de4ae7b9e3 100644\n--- a/README.md\n+++ b/README.md\n@@ -132,7 +132,7 [...]', ) ``` [`HfApi.get_discussion_details`] returns a [`DiscussionWithDetails`] object, which is a subclass of [`Discussion`] with more detailed information about the Discussion or Pull Request. Information includes all the comments, status changes, and renames of the Discussion via [`DiscussionWithDetails.events`]. In case of a Pull Request, you can retrieve the raw git diff with [`DiscussionWithDetails.diff`]. All the commits of the Pull Requests are listed in [`DiscussionWithDetails.events`]. ## Create and edit a Discussion or Pull Request programmatically The [`HfApi`] class also offers ways to create and edit Discussions and Pull Requests. You will need an [access token](https://huggingface.co/docs/hub/security-tokens) to create and edit Discussions or Pull Requests. The simplest way to propose changes on a repo on the Hub is via the [`create_commit`] API: just set the `create_pr` parameter to `True`. This parameter is also available on other methods that wrap [`create_commit`]: * [`upload_file`] * [`upload_folder`] * [`delete_file`] * [`delete_folder`] * [`metadata_update`] ```python >>> from huggingface_hub import metadata_update >>> metadata_update( ... repo_id="username/repo_name", ... metadata={"tags": ["computer-vision", "awesome-model"]}, ... create_pr=True, ... ) ``` You can also use [`HfApi.create_discussion`] (respectively [`HfApi.create_pull_request`]) to create a Discussion (respectively a Pull Request) on a repo. Opening a Pull Request this way can be useful if you need to work on changes locally. Pull Requests opened this way will be in `"draft"` mode. ```python >>> from huggingface_hub import create_discussion, create_pull_request >>> create_discussion( ... repo_id="username/repo-name", ... title="Hi from the huggingface_hub library!", ... token="", ... ) DiscussionWithDetails(...) >>> create_pull_request( ... repo_id="username/repo-name", ... title="Hi from the huggingface_hub library!", ... token="", ... ) DiscussionWithDetails(..., is_pull_request=True) ``` Managing Pull Requests and Discussions can be done entirely with the [`HfApi`] class. For example: * [`comment_discussion`] to add comments * [`edit_discussion_comment`] to edit comments * [`rename_discussion`] to rename a Discussion or Pull Request * [`change_discussion_status`] to open or close a Discussion / Pull Request * [`merge_pull_request`] to merge a Pull Request Visit the [`HfApi`] documentation page for an exhaustive reference of all available methods. ## Push changes to a Pull Request *Coming soon !* ## See also For a more detailed reference, visit the [Discussions and Pull Requests](../package_reference/community) and the [hf_api](../package_reference/hf_api) documentation page. huggingface_hub-1.1.5/docs/source/en/guides/download.md000066400000000000000000000316741510763414300231050ustar00rootroot00000000000000 # Download files from the Hub The `huggingface_hub` library provides functions to download files from the repositories stored on the Hub. You can use these functions independently or integrate them into your own library, making it more convenient for your users to interact with the Hub. This guide will show you how to: * Download and cache a single file. * Download and cache an entire repository. * Download files to a local folder. ## Download a single file The [`hf_hub_download`] function is the main function for downloading files from the Hub. It downloads the remote file, caches it on disk (in a version-aware way), and returns its local file path. > [!TIP] > The returned filepath is a pointer to the HF local cache. Therefore, it is important to not modify the file to avoid > having a corrupted cache. If you are interested in getting to know more about how files are cached, please refer to our > [caching guide](./manage-cache). ### From latest version Select the file to download using the `repo_id`, `repo_type` and `filename` parameters. By default, the file will be considered as being part of a `model` repo. ```python >>> from huggingface_hub import hf_hub_download >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json") '/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json' # Download from a dataset >>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset") '/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py' ``` ### From specific version By default, the latest version from the `main` branch is downloaded. However, in some cases you want to download a file at a particular version (e.g. from a specific branch, a PR, a tag or a commit hash). To do so, use the `revision` parameter: ```python # Download from the `v1.0` tag >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0") # Download from the `test-branch` branch >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch") # Download from Pull Request #3 >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3") # Download from a specific commit hash >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a") ``` **Note:** When using the commit hash, it must be the full-length hash instead of a 7-character commit hash. ### Construct a download URL In case you want to construct the URL used to download a file from a repo, you can use [`hf_hub_url`] which returns a URL. Note that it is used internally by [`hf_hub_download`]. ## Download an entire repository [`snapshot_download`] downloads an entire repository at a given revision. It uses internally [`hf_hub_download`] which means all downloaded files are also cached on your local disk. Downloads are made concurrently to speed up the process. To download a whole repository, just pass the `repo_id` and `repo_type`: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp") '/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade' # Or from a dataset >>> snapshot_download(repo_id="google/fleurs", repo_type="dataset") '/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34' ``` [`snapshot_download`] downloads the latest revision by default. If you want a specific repository revision, use the `revision` parameter: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1") ``` ### Filter files to download [`snapshot_download`] provides an easy way to download a repository. However, you don't always want to download the entire content of a repository. For example, you might want to prevent downloading all `.bin` files if you know you'll only use the `.safetensors` weights. You can do that using `allow_patterns` and `ignore_patterns` parameters. These parameters accept either a single pattern or a list of patterns. Patterns are Standard Wildcards (globbing patterns) as documented [here](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). The pattern matching is based on [`fnmatch`](https://docs.python.org/3/library/fnmatch.html). For example, you can use `allow_patterns` to only download JSON configuration files: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json") ``` On the other hand, `ignore_patterns` can exclude certain files from being downloaded. The following example ignores the `.msgpack` and `.h5` file extensions: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"]) ``` Finally, you can combine both to precisely filter your download. Here is an example to download all json and markdown files except `vocab.json`. ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json") ``` ## Download file(s) to a local folder By default, we recommend using the [cache system](./manage-cache) to download files from the Hub. You can specify a custom cache location using the `cache_dir` parameter in [`hf_hub_download`] and [`snapshot_download`], or by setting the [`HF_HOME`](../package_reference/environment_variables#hf_home) environment variable. However, if you need to download files to a specific folder, you can pass a `local_dir` parameter to the download function. This is useful to get a workflow closer to what the `git` command offers. The downloaded files will maintain their original file structure within the specified folder. For example, if `filename="data/train.csv"` and `local_dir="path/to/folder"`, the resulting filepath will be `"path/to/folder/data/train.csv"`. A `.cache/huggingface/` folder is created at the root of your local directory containing metadata about the downloaded files. This prevents re-downloading files if they're already up-to-date. If the metadata has changed, then the new file version is downloaded. This makes the `local_dir` optimized for pulling only the latest changes. After completing the download, you can safely remove the `.cache/huggingface/` folder if you no longer need it. However, be aware that re-running your script without this folder may result in longer recovery times, as metadata will be lost. Rest assured that your local data will remain intact and unaffected. > [!TIP] > Don't worry about the `.cache/huggingface/` folder when committing changes to the Hub! This folder is automatically ignored by both `git` and [`upload_folder`]. ## Download from the CLI You can use the `hf download` command from the terminal to directly download files from the Hub. Internally, it uses the same [`hf_hub_download`] and [`snapshot_download`] helpers described above and prints the returned path to the terminal. ```bash >>> hf download gpt2 config.json /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json ``` You can download multiple files at once which displays a progress bar and returns the snapshot path in which the files are located: ```bash >>> hf download gpt2 config.json model.safetensors Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s] /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 ``` For more details about the CLI download command, please refer to the [CLI guide](./cli#hf-download). ## Dry-run mode In some cases, you would like to check which files would be downloaded before actually downloading them. You can check this using the `--dry-run` parameter. It lists all files to download on the repo and checks whether they are already downloaded or not. This gives an idea of how many files have to be downloaded and their sizes. Here is an example, checking on a single file: ```sh >>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run [dry-run] Will download 1 files (out of 1) totalling 655.2M File Bytes to download ------------------------------ ----------------- onnx/decoder_model_merged.onnx 655.2M ``` And if the file is already cached: ```sh >>> hf download openai-community/gpt2 onnx/decoder_model_merged.onnx --dry-run [dry-run] Will download 0 files (out of 1) totalling 0.0. File Bytes to download ------------------------------ ----------------- onnx/decoder_model_merged.onnx - ``` You can also execute a dry-run on an entire repository: ```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 - ``` And with files filtering: ```sh >>> hf download openai-community/gpt2 --include "*.json" --dry-run [dry-run] Fetching 11 files: 100%|█████████████| 11/11 [00:00<00:00, 80518.92it/s] [dry-run] Will download 0 files (out of 11) totalling 0.0. File Bytes to download ---------------------------- ----------------- config.json - generation_config.json - onnx/config.json - onnx/generation_config.json - onnx/special_tokens_map.json - onnx/tokenizer.json - onnx/tokenizer_config.json - onnx/vocab.json - tokenizer.json - tokenizer_config.json - vocab.json - ``` Finally, you can also make a dry-run programmatically by passing `dry_run=True` to [`hf_hub_download`] and [`snapshot_download`]. It will return a [`DryRunFileInfo`] (respectively a list of [`DryRunFileInfo`]) with for each file, their commit hash, file name and file size, whether the file is cached and whether the file would be downloaded. In practice, the file will be downloaded if not cached or if `force_download=True` is passed. ## Faster downloads Take advantage of faster downloads through `hf_xet`, the Python binding to the [`xet-core`](https://github.com/huggingface/xet-core) library that enables chunk-based deduplication for faster downloads and uploads. `hf_xet` integrates seamlessly with `huggingface_hub`, but uses the Rust `xet-core` library and Xet storage instead of LFS. `hf_xet` uses the Xet storage system, which breaks files down into immutable chunks, storing collections of these chunks (called blocks or xorbs) remotely and retrieving them to reassemble the file when requested. When downloading, after confirming the user is authorized to access the files, `hf_xet` will query the Xet content-addressable service (CAS) with the LFS SHA256 hash for this file to receive the reconstruction metadata (ranges within xorbs) to assemble these files, along with presigned URLs to download the xorbs directly. Then `hf_xet` will efficiently download the xorb ranges necessary and will write out the files on disk. To enable it, simply install the latest version of `huggingface_hub`: ```bash pip install -U "huggingface_hub" ``` As of `huggingface_hub` 0.32.0, this will also install `hf_xet`. All other `huggingface_hub` APIs will continue to work without any modification. To learn more about the benefits of Xet storage and `hf_xet`, refer to this [section](https://huggingface.co/docs/hub/xet/index). Note: `hf_transfer` was formerly used with the LFS storage backend and is now deprecated; use `hf_xet` instead. huggingface_hub-1.1.5/docs/source/en/guides/hf_file_system.md000066400000000000000000000123601510763414300242650ustar00rootroot00000000000000 # Interact with the Hub through the Filesystem API In addition to the [`HfApi`], the `huggingface_hub` library provides [`HfFileSystem`], a pythonic [fsspec-compatible](https://filesystem-spec.readthedocs.io/en/latest/) file interface to the Hugging Face Hub. The [`HfFileSystem`] builds on top of the [`HfApi`] and offers typical filesystem style operations like `cp`, `mv`, `ls`, `du`, `glob`, `get_file`, and `put_file`. > [!WARNING] > [`HfFileSystem`] provides fsspec compatibility, which is useful for libraries that require it (e.g., reading > Hugging Face datasets directly with `pandas`). However, it introduces additional overhead due to this compatibility > layer. For better performance and reliability, it's recommended to use [`HfApi`] methods when possible. ## Usage ```python >>> from huggingface_hub import HfFileSystem >>> fs = HfFileSystem() >>> # List all files in a directory >>> fs.ls("datasets/my-username/my-dataset-repo/data", detail=False) ['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv'] >>> # List all ".csv" files in a repo >>> fs.glob("datasets/my-username/my-dataset-repo/**/*.csv") ['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv'] >>> # Read a remote file >>> with fs.open("datasets/my-username/my-dataset-repo/data/train.csv", "r") as f: ... train_data = f.readlines() >>> # Read the content of a remote file as a string >>> train_data = fs.read_text("datasets/my-username/my-dataset-repo/data/train.csv", revision="dev") >>> # Write a remote file >>> with fs.open("datasets/my-username/my-dataset-repo/data/validation.csv", "w") as f: ... f.write("text,label") ... f.write("Fantastic movie!,good") ``` The optional `revision` argument can be passed to run an operation from a specific commit such as a branch, tag name, or a commit hash. Unlike Python's built-in `open`, `fsspec`'s `open` defaults to binary mode, `"rb"`. This means you must explicitly set mode as `"r"` for reading and `"w"` for writing in text mode. Appending to a file (modes `"a"` and `"ab"`) is not supported yet. ## Integrations The [`HfFileSystem`] can be used with any library that integrates `fsspec`, provided the URL follows the scheme: ``` hf://[][@]/ ```
The `repo_type_prefix` is `datasets/` for datasets, `spaces/` for spaces, and models don't need a prefix in the URL. Some interesting integrations where [`HfFileSystem`] simplifies interacting with the Hub are listed below: * Reading/writing a [Pandas](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#reading-writing-remote-files) DataFrame from/to a Hub repository: ```python >>> import pandas as pd >>> # Read a remote CSV file into a dataframe >>> df = pd.read_csv("hf://datasets/my-username/my-dataset-repo/train.csv") >>> # Write a dataframe to a remote CSV file >>> df.to_csv("hf://datasets/my-username/my-dataset-repo/test.csv") ``` The same workflow can also be used for [Dask](https://docs.dask.org/en/stable/how-to/connect-to-remote-data.html) and [Polars](https://pola-rs.github.io/polars/py-polars/html/reference/io.html) DataFrames. * Querying (remote) Hub files with [DuckDB](https://duckdb.org/docs/guides/python/filesystems): ```python >>> from huggingface_hub import HfFileSystem >>> import duckdb >>> fs = HfFileSystem() >>> duckdb.register_filesystem(fs) >>> # Query a remote file and get the result back as a dataframe >>> fs_query_file = "hf://datasets/my-username/my-dataset-repo/data_dir/data.parquet" >>> df = duckdb.query(f"SELECT * FROM '{fs_query_file}' LIMIT 10").df() ``` * Using the Hub as an array store with [Zarr](https://zarr.readthedocs.io/en/stable/tutorial.html#io-with-fsspec): ```python >>> import numpy as np >>> import zarr >>> embeddings = np.random.randn(50000, 1000).astype("float32") >>> # Write an array to a repo >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="w") as root: ... foo = root.create_group("embeddings") ... foobar = foo.zeros('experiment_0', shape=(50000, 1000), chunks=(10000, 1000), dtype='f4') ... foobar[:] = embeddings >>> # Read an array from a repo >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="r") as root: ... first_row = root["embeddings/experiment_0"][0] ``` ## Authentication In many cases, you must be logged in with a Hugging Face account to interact with the Hub. Refer to the [Authentication](../quick-start#authentication) section of the documentation to learn more about authentication methods on the Hub. It is also possible to log in programmatically by passing your `token` as an argument to [`HfFileSystem`]: ```python >>> from huggingface_hub import HfFileSystem >>> fs = HfFileSystem(token=token) ``` If you log in this way, be careful not to accidentally leak the token when sharing your source code! huggingface_hub-1.1.5/docs/source/en/guides/inference.md000066400000000000000000001040061510763414300232220ustar00rootroot00000000000000 # Run Inference on servers Inference is the process of using a trained model to make predictions on new data. Because this process can be compute-intensive, running on a dedicated or external service can be an interesting option. The `huggingface_hub` library provides a unified interface to run inference across multiple services for models hosted on the Hugging Face Hub: 1. [Inference Providers](https://huggingface.co/docs/inference-providers/index): a streamlined, unified access to hundreds of machine learning models, powered by our serverless inference partners. This new approach builds on our previous Serverless Inference API, offering more models, improved performance, and greater reliability thanks to world-class providers. Refer to the [documentation](https://huggingface.co/docs/inference-providers/index#partners) for a list of supported providers. 2. [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index): a product to easily deploy models to production. Inference is run by Hugging Face in a dedicated, fully managed infrastructure on a cloud provider of your choice. 3. Local endpoints: you can also run inference with local inference servers like [llama.cpp](https://github.com/ggerganov/llama.cpp), [Ollama](https://ollama.com/), [vLLM](https://github.com/vllm-project/vllm), [LiteLLM](https://docs.litellm.ai/docs/simple_proxy), or [Text Generation Inference (TGI)](https://github.com/huggingface/text-generation-inference) by connecting the client to these local endpoints. > [!TIP] > [`InferenceClient`] is a Python client making HTTP calls to our APIs. If you want to make the HTTP calls directly using > your preferred tool (curl, postman,...), please refer to the [Inference Providers](https://huggingface.co/docs/inference-providers/index) documentation > or to the [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index) documentation pages. > > For web development, a [JS client](https://huggingface.co/docs/huggingface.js/inference/README) has been released. > If you are interested in game development, you might have a look at our [C# project](https://github.com/huggingface/unity-api). ## Getting started Let's get started with a text-to-image task: ```python >>> from huggingface_hub import InferenceClient # Example with an external provider (e.g. replicate) >>> replicate_client = InferenceClient( provider="replicate", api_key="my_replicate_api_key", ) >>> replicate_image = replicate_client.text_to_image( "A flying car crossing a futuristic cityscape.", model="black-forest-labs/FLUX.1-schnell", ) >>> replicate_image.save("flying_car.png") ``` In the example above, we initialized an [`InferenceClient`] with a third-party provider, [Replicate](https://replicate.com/). When using a provider, you must specify the model you want to use. The model id must be the id of the model on the Hugging Face Hub, not the id of the model from the third-party provider. In our example, we generated an image from a text prompt. The returned value is a `PIL.Image` object that can be saved to a file. For more details, check out the [`~InferenceClient.text_to_image`] documentation. Let's now see an example using the [`~InferenceClient.chat_completion`] API. This task uses an LLM to generate a response from a list of messages: ```python >>> from huggingface_hub import InferenceClient >>> messages = [ { "role": "user", "content": "What is the capital of France?", } ] >>> client = InferenceClient( provider="together", model="meta-llama/Meta-Llama-3-8B-Instruct", api_key="my_together_api_key", ) >>> client.chat_completion(messages, max_tokens=100) ChatCompletionOutput( choices=[ ChatCompletionOutputComplete( finish_reason="eos_token", index=0, message=ChatCompletionOutputMessage( role="assistant", content="The capital of France is Paris.", name=None, tool_calls=None ), logprobs=None, ) ], created=1719907176, id="", model="meta-llama/Meta-Llama-3-8B-Instruct", object="text_completion", system_fingerprint="2.0.4-sha-f426a33", usage=ChatCompletionOutputUsage(completion_tokens=8, prompt_tokens=17, total_tokens=25), ) ``` In the example above, we used a third-party provider ([Together AI](https://www.together.ai/)) and specified which model we want to use (`"meta-llama/Meta-Llama-3-8B-Instruct"`). We then gave a list of messages to complete (here, a single question) and passed an additional parameter to the API (`max_token=100`). The output is a `ChatCompletionOutput` object that follows the OpenAI specification. The generated content can be accessed with `output.choices[0].message.content`. For more details, check out the [`~InferenceClient.chat_completion`] documentation. > [!WARNING] > The API is designed to be simple. Not all parameters and options are available or described for the end user. Check out > [this page](https://huggingface.co/docs/api-inference/detailed_parameters) if you are interested in learning more about > all the parameters available for each task. ### Using a specific provider If you want to use a specific provider, you can specify it when initializing the client. The default value is "auto" which will select the first of the providers available for the model, sorted by the user's order in https://hf.co/settings/inference-providers. Refer to the [Supported providers and tasks](#supported-providers-and-tasks) section for a list of supported providers. ```python >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(provider="replicate", api_key="my_replicate_api_key") ``` ### Using a specific model What if you want to use a specific model? You can specify it either as a parameter or directly at an instance level: ```python >>> from huggingface_hub import InferenceClient # Initialize client for a specific model >>> client = InferenceClient(provider="together", model="meta-llama/Llama-3.1-8B-Instruct") >>> client.text_to_image(...) # Or use a generic client but pass your model as an argument >>> client = InferenceClient(provider="together") >>> client.text_to_image(..., model="meta-llama/Llama-3.1-8B-Instruct") ``` > [!TIP] > When using the "hf-inference" provider, each task comes with a recommended model from the 1M+ models available on the Hub. > However, this recommendation can change over time, so it's best to explicitly set a model once you've decided which one to use. > For third-party providers, you must always specify a model that is compatible with that provider. > > Visit the [Models](https://huggingface.co/models?inference=warm) page on the Hub to explore models available through Inference Providers. ### Using Inference Endpoints The examples we saw above use inference providers. While these prove to be very useful for prototyping and testing things quickly. Once you're ready to deploy your model to production, you'll need to use a dedicated infrastructure. That's where [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index) comes into play. It allows you to deploy any model and expose it as a private API. Once deployed, you'll get a URL that you can connect to using exactly the same code as before, changing only the `model` parameter: ```python >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if") # or >>> client = InferenceClient() >>> client.text_to_image(..., model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if") ``` Note that you cannot specify both a URL and a provider - they are mutually exclusive. URLs are used to connect directly to deployed endpoints. ### Using local endpoints You can use [`InferenceClient`] to run chat completion with local inference servers (llama.cpp, vllm, litellm server, TGI, mlx, etc.) running on your own machine. The API should be OpenAI API-compatible. ```python >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(model="http://localhost:8080") >>> response = client.chat.completions.create( ... messages=[ ... {"role": "user", "content": "What is the capital of France?"} ... ], ... max_tokens=100 ... ) >>> print(response.choices[0].message.content) ``` > [!TIP] > Similarly to the OpenAI Python client, [`InferenceClient`] can be used to run Chat Completion inference with any OpenAI REST API-compatible endpoint. ### Authentication Authentication can be done in two ways: **Routed through Hugging Face** : Use Hugging Face as a proxy to access third-party providers. The calls will be routed through Hugging Face's infrastructure using our provider keys, and the usage will be billed directly to your Hugging Face account. You can authenticate using a [User Access Token](https://huggingface.co/docs/hub/security-tokens). You can provide your Hugging Face token directly using the `api_key` parameter: ```python >>> client = InferenceClient( provider="replicate", api_key="hf_****" # Your HF token ) ``` If you *don't* pass an `api_key`, the client will attempt to find and use a token stored locally on your machine. This typically happens if you've previously logged in. See the [Authentication Guide](https://huggingface.co/docs/huggingface_hub/quick-start#authentication) for details on login. ```python >>> client = InferenceClient( provider="replicate", token="hf_****" # Your HF token ) ``` **Direct access to provider**: Use your own API key to interact directly with the provider's service: ```python >>> client = InferenceClient( provider="replicate", api_key="r8_****" # Your Replicate API key ) ``` For more details, refer to the [Inference Providers pricing documentation](https://huggingface.co/docs/inference-providers/pricing#routed-requests-vs-direct-calls). ## Supported providers and tasks [`InferenceClient`]'s goal is to provide the easiest interface to run inference on Hugging Face models, on any provider. It has a simple API that supports the most common tasks. Here is a table showing which providers support which tasks: | Task | Black Forest Labs | Cerebras | Clarifai | Cohere | fal-ai | Featherless AI | Fireworks AI | Groq | HF Inference | Hyperbolic | Nebius AI Studio | Novita AI | Nscale | OVHcloud AI Endpoints | Public AI | Replicate | Sambanova | Scaleway | Together | Wavespeed | Zai | | --------------------------------------------------- | ----------------- | -------- | -------- | ------ | ------ | -------------- | ------------ | ---- | ------------ | ---------- | ---------------- | --------- | ------ | -------- | ---------- | --------- | --------- | --------- | -------- | --------- | ---- | | [`~InferenceClient.audio_classification`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.audio_to_audio`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.automatic_speech_recognition`] | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.chat_completion`] | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | | [`~InferenceClient.document_question_answering`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.feature_extraction`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ | | [`~InferenceClient.fill_mask`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.image_classification`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.image_segmentation`] | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.image_to_image`] | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | | [`~InferenceClient.image_to_video`] | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | | [`~InferenceClient.image_to_text`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.object_detection`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.question_answering`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.sentence_similarity`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.summarization`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.table_question_answering`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.text_classification`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.text_generation`] | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | | [`~InferenceClient.text_to_image`] | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ | ✅ | ❌ | | [`~InferenceClient.text_to_speech`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.text_to_video`] | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | | [`~InferenceClient.tabular_classification`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.tabular_regression`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.token_classification`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.translation`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.visual_question_answering`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.zero_shot_image_classification`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | | [`~InferenceClient.zero_shot_classification`] | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | > [!TIP] > Check out the [Tasks](https://huggingface.co/tasks) page to learn more about each task. ## OpenAI compatibility The `chat_completion` task follows [OpenAI's Python client](https://github.com/openai/openai-python) syntax. What does it mean for you? It means that if you are used to play with `OpenAI`'s APIs you will be able to switch to `huggingface_hub.InferenceClient` to work with open-source models by updating just 2 line of code! ```diff - from openai import OpenAI + from huggingface_hub import InferenceClient - client = OpenAI( + client = InferenceClient( base_url=..., api_key=..., ) output = client.chat.completions.create( model="meta-llama/Meta-Llama-3-8B-Instruct", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Count to 10"}, ], stream=True, max_tokens=1024, ) for chunk in output: print(chunk.choices[0].delta.content) ``` And that's it! The only required changes are to replace `from openai import OpenAI` by `from huggingface_hub import InferenceClient` and `client = OpenAI(...)` by `client = InferenceClient(...)`. You can choose any LLM model from the Hugging Face Hub by passing its model id as `model` parameter. [Here is a list](https://huggingface.co/models?pipeline_tag=text-generation&other=conversational,text-generation-inference&sort=trending) of supported models. For authentication, you should pass a valid [User Access Token](https://huggingface.co/settings/tokens) as `api_key` or authenticate using `huggingface_hub` (see the [authentication guide](https://huggingface.co/docs/huggingface_hub/quick-start#authentication)). All input parameters and output format are strictly the same. In particular, you can pass `stream=True` to receive tokens as they are generated. You can also use the [`AsyncInferenceClient`] to run inference using `asyncio`: ```diff import asyncio - from openai import AsyncOpenAI + from huggingface_hub import AsyncInferenceClient - client = AsyncOpenAI() + client = AsyncInferenceClient() async def main(): stream = await client.chat.completions.create( model="meta-llama/Meta-Llama-3-8B-Instruct", messages=[{"role": "user", "content": "Say this is a test"}], stream=True, ) async for chunk in stream: print(chunk.choices[0].delta.content or "", end="") asyncio.run(main()) ``` You might wonder why using [`InferenceClient`] instead of OpenAI's client? There are a few reasons for that: 1. [`InferenceClient`] is configured for Hugging Face services. You don't need to provide a `base_url` to run models with Inference Providers. You also don't need to provide a `token` or `api_key` if your machine is already correctly logged in. 2. [`InferenceClient`] is tailored for both Text-Generation-Inference (TGI) and `transformers` frameworks, meaning you are assured it will always be on-par with the latest updates. 3. [`InferenceClient`] is integrated with our Inference Endpoints service, making it easier to launch an Inference Endpoint, check its status and run inference on it. Check out the [Inference Endpoints](./inference_endpoints.md) guide for more details. > [!TIP] > `InferenceClient.chat.completions.create` is simply an alias for `InferenceClient.chat_completion`. Check out the package reference of [`~InferenceClient.chat_completion`] for more details. `base_url` and `api_key` parameters when instantiating the client are also aliases for `model` and `token`. These aliases have been defined to reduce friction when switching from `OpenAI` to `InferenceClient`. ## Function Calling Function calling allows LLMs to interact with external tools, such as defined functions or APIs. This enables users to easily build applications tailored to specific use cases and real-world tasks. `InferenceClient` implements the same tool calling interface as the OpenAI Chat Completions API. Here is a simple example of tool calling using [Nebius](https://nebius.com/) as the inference provider: ```python from huggingface_hub import InferenceClient tools = [ { "type": "function", "function": { "name": "get_weather", "description": "Get current temperature for a given location.", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "City and country e.g. Paris, France" } }, "required": ["location"], }, } } ] client = InferenceClient(provider="nebius") response = client.chat.completions.create( model="Qwen/Qwen2.5-72B-Instruct", messages=[ { "role": "user", "content": "What's the weather like the next 3 days in London, UK?" } ], tools=tools, tool_choice="auto", ) print(response.choices[0].message.tool_calls[0].function.arguments) ``` > [!TIP] > Please refer to the providers' documentation to verify which models are supported by them for Function/Tool Calling. ## Structured Outputs & JSON Mode InferenceClient supports JSON mode for syntactically valid JSON responses and Structured Outputs for schema-enforced responses. JSON mode provides machine-readable data without strict structure, while Structured Outputs guarantee both valid JSON and adherence to a predefined schema for reliable downstream processing. We follow the OpenAI API specs for both JSON mode and Structured Outputs. You can enable them via the `response_format` argument. Here is an example of Structured Outputs using [Cerebras](https://www.cerebras.ai/) as the inference provider: ```python from huggingface_hub import InferenceClient json_schema = { "name": "book", "schema": { "properties": { "name": { "title": "Name", "type": "string", }, "authors": { "items": {"type": "string"}, "title": "Authors", "type": "array", }, }, "required": ["name", "authors"], "title": "Book", "type": "object", }, "strict": True, } client = InferenceClient(provider="cerebras") completion = client.chat.completions.create( model="Qwen/Qwen3-32B", messages=[ {"role": "system", "content": "Extract the books information."}, {"role": "user", "content": "I recently read 'The Great Gatsby' by F. Scott Fitzgerald."}, ], response_format={ "type": "json_schema", "json_schema": json_schema, }, ) print(completion.choices[0].message) ``` > [!TIP] > Please refer to the providers' documentation to verify which models are supported by them for Structured Outputs and JSON Mode. ## Async client An async version of the client is also provided, based on `asyncio` and `httpx`. All async API endpoints are available via [`AsyncInferenceClient`]. Its initialization and APIs are strictly the same as the sync-only version. ```py # Code must be run in an asyncio concurrent context. # $ python -m asyncio >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> image = await client.text_to_image("An astronaut riding a horse on the moon.") >>> image.save("astronaut.png") >>> async for token in await client.text_generation("The Huggingface Hub is", stream=True): ... print(token, end="") a platform for sharing and discussing ML-related content. ``` For more information about the `asyncio` module, please refer to the [official documentation](https://docs.python.org/3/library/asyncio.html). ## MCP Client The `huggingface_hub` library now includes an experimental [`MCPClient`], designed to empower Large Language Models (LLMs) with the ability to interact with external Tools via the [Model Context Protocol](https://modelcontextprotocol.io) (MCP). This client extends an [`AsyncInferenceClient`] to seamlessly integrate Tool usage. The [`MCPClient`] connects to MCP servers (either local `stdio` scripts or remote `http`/`sse` services) that expose tools. It feeds these tools to an LLM (via [`AsyncInferenceClient`]). If the LLM decides to use a tool, [`MCPClient`] manages the execution request to the MCP server and relays the Tool's output back to the LLM, often streaming results in real-time. In the following example, we use [Qwen/Qwen2.5-72B-Instruct](https://huggingface.co/Qwen/Qwen2.5-72B-Instruct) model via [Nebius](https://nebius.com/) inference provider. We then add a remote MCP server, in this case, an SSE server which made the Flux image generation tool available to the LLM. ```python import os from huggingface_hub import ChatCompletionInputMessage, ChatCompletionStreamOutput, MCPClient async def main(): async with MCPClient( provider="nebius", model="Qwen/Qwen2.5-72B-Instruct", api_key=os.environ["HF_TOKEN"], ) as client: await client.add_mcp_server(type="sse", url="https://evalstate-flux1-schnell.hf.space/gradio_api/mcp/sse") messages = [ { "role": "user", "content": "Generate a picture of a cat on the moon", } ] async for chunk in client.process_single_turn_with_tools(messages): # Log messages if isinstance(chunk, ChatCompletionStreamOutput): delta = chunk.choices[0].delta if delta.content: print(delta.content, end="") # Or tool calls elif isinstance(chunk, ChatCompletionInputMessage): print( f"\nCalled tool '{chunk.name}'. Result: '{chunk.content if len(chunk.content) < 1000 else chunk.content[:1000] + '...'}'" ) if __name__ == "__main__": import asyncio asyncio.run(main()) ``` For even simpler development, we offer a higher-level [`Agent`] class. This 'Tiny Agent' simplifies creating conversational Agents by managing the chat loop and state, essentially acting as a wrapper around [`MCPClient`]. It's designed to be a simple while loop built right on top of an [`MCPClient`]. You can run these Agents directly from the command line: ```bash # install latest version of huggingface_hub with the mcp extra pip install -U huggingface_hub[mcp] # Run an agent that uses the Flux image generation tool tiny-agents run julien-c/flux-schnell-generator ``` When launched, the Agent will load, list the Tools it has discovered from its connected MCP servers, and then it's ready for your prompts! ## Advanced tips In the above section, we saw the main aspects of [`InferenceClient`]. Let's dive into some more advanced tips. ### Billing As an HF user, you get monthly credits to run inference through various providers on the Hub. The amount of credits you get depends on your type of account (Free or PRO or Enterprise Hub). You get charged for every inference request, depending on the provider's pricing table. By default, the requests are billed to your personal account. However, it is possible to set the billing so that requests are charged to an organization you are part of by simply passing `bill_to=""` to `InferenceClient`. For this to work, your organization must be subscribed to Enterprise Hub. For more details about billing, check out [this guide](https://huggingface.co/docs/api-inference/pricing#features-using-inference-providers). ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(provider="fal-ai", bill_to="openai") >>> image = client.text_to_image( ... "A majestic lion in a fantasy forest", ... model="black-forest-labs/FLUX.1-schnell", ... ) >>> image.save("lion.png") ``` Note that it is NOT possible to charge another user or an organization you are not part of. If you want to grant someone else some credits, you must create a joint organization with them. ### Timeout Inference calls can take a significant amount of time. By default, [`InferenceClient`] will wait "indefinitely" until the inference complete. If you want more control in your workflow, you can set the `timeout` parameter to a specific value in seconds. If the timeout delay expires, an [`InferenceTimeoutError`] is raised, which you can catch in your code: ```python >>> from huggingface_hub import InferenceClient, InferenceTimeoutError >>> client = InferenceClient(timeout=30) >>> try: ... client.text_to_image(...) ... except InferenceTimeoutError: ... print("Inference timed out after 30s.") ``` ### Binary inputs Some tasks require binary inputs, for example, when dealing with images or audio files. In this case, [`InferenceClient`] tries to be as permissive as possible and accept different types: - raw `bytes` - a file-like object, opened as binary (`with open("audio.flac", "rb") as f: ...`) - a path (`str` or `Path`) pointing to a local file - a URL (`str`) pointing to a remote file (e.g. `https://...`). In this case, the file will be downloaded locally before being sent to the API. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.image_classification("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg") [{'score': 0.9779096841812134, 'label': 'Blenheim spaniel'}, ...] ``` huggingface_hub-1.1.5/docs/source/en/guides/inference_endpoints.md000066400000000000000000000353371510763414300253170ustar00rootroot00000000000000# Inference Endpoints Inference Endpoints provides a secure production solution to easily deploy any `transformers`, `sentence-transformers`, and `diffusers` models on a dedicated and autoscaling infrastructure managed by Hugging Face. An Inference Endpoint is built from a model from the [Hub](https://huggingface.co/models). In this guide, we will learn how to programmatically manage Inference Endpoints with `huggingface_hub`. For more information about the Inference Endpoints product itself, check out its [official documentation](https://huggingface.co/docs/inference-endpoints/index). This guide assumes `huggingface_hub` is correctly installed and that your machine is logged in. Check out the [Quick Start guide](https://huggingface.co/docs/huggingface_hub/quick-start#quickstart) if that's not the case yet. The minimal version supporting Inference Endpoints API is `v0.19.0`. > [!TIP] > **New:** it is now possible to deploy an Inference Endpoint from the [HF model catalog](https://endpoints.huggingface.co/catalog) with a simple API call. The catalog is a carefully curated list of models that can be deployed with optimized settings. You don't need to configure anything, we take all the heavy stuff on us! All models and settings are guaranteed to have been tested to provide best cost/performance balance. [`create_inference_endpoint_from_catalog`] works the same as [`create_inference_endpoint`], with much less parameters to pass. You can use [`list_inference_catalog`] to programmatically retrieve the catalog. > > Note that this is still an experimental feature. Let us know what you think if you use it! ## Create an Inference Endpoint The first step is to create an Inference Endpoint using [`create_inference_endpoint`]: ```py >>> from huggingface_hub import create_inference_endpoint >>> endpoint = create_inference_endpoint( ... "my-endpoint-name", ... repository="gpt2", ... framework="pytorch", ... task="text-generation", ... accelerator="cpu", ... vendor="aws", ... region="us-east-1", ... type="protected", ... instance_size="x2", ... instance_type="intel-icl" ... ) ``` Or via CLI: ```bash hf endpoints deploy my-endpoint-name --repo gpt2 --framework pytorch --accelerator cpu --vendor aws --region us-east-1 --instance-size x2 --instance-type intel-icl --task text-generation # Deploy from the catalog with a single command hf endpoints catalog deploy my-endpoint-name --repo openai/gpt-oss-120b ``` In this example, we created a `protected` Inference Endpoint named `"my-endpoint-name"`, to serve [gpt2](https://huggingface.co/gpt2) for `text-generation`. A `protected` Inference Endpoint means your token is required to access the API. We also need to provide additional information to configure the hardware requirements, such as vendor, region, accelerator, instance type, and size. You can check out the list of available resources [here](https://api.endpoints.huggingface.cloud/#/v2%3A%3Aprovider/list_vendors). Alternatively, you can create an Inference Endpoint manually using the [Web interface](https://ui.endpoints.huggingface.co/new) for convenience. Refer to this [guide](https://huggingface.co/docs/inference-endpoints/guides/advanced) for details on advanced settings and their usage. The value returned by [`create_inference_endpoint`] is an [`InferenceEndpoint`] object: ```py >>> endpoint InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) ``` Or via CLI: ```bash hf endpoints describe my-endpoint-name ``` It's a dataclass that holds information about the endpoint. You can access important attributes such as `name`, `repository`, `status`, `task`, `created_at`, `updated_at`, etc. If you need it, you can also access the raw response from the server with `endpoint.raw`. Once your Inference Endpoint is created, you can find it on your [personal dashboard](https://ui.endpoints.huggingface.co/). ![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/huggingface_hub/inference_endpoints_created.png) #### Using a custom image By default the Inference Endpoint is built from a docker image provided by Hugging Face. However, it is possible to specify any docker image using the `custom_image` parameter. A common use case is to run LLMs using the [text-generation-inference](https://github.com/huggingface/text-generation-inference) framework. This can be done like this: ```python # Start an Inference Endpoint running Zephyr-7b-beta on TGI >>> from huggingface_hub import create_inference_endpoint >>> endpoint = create_inference_endpoint( ... "aws-zephyr-7b-beta-0486", ... repository="HuggingFaceH4/zephyr-7b-beta", ... framework="pytorch", ... task="text-generation", ... accelerator="gpu", ... vendor="aws", ... region="us-east-1", ... type="protected", ... instance_size="x1", ... instance_type="nvidia-a10g", ... custom_image={ ... "health_route": "/health", ... "env": { ... "MAX_BATCH_PREFILL_TOKENS": "2048", ... "MAX_INPUT_LENGTH": "1024", ... "MAX_TOTAL_TOKENS": "1512", ... "MODEL_ID": "/repository" ... }, ... "url": "ghcr.io/huggingface/text-generation-inference:1.1.0", ... }, ... ) ``` The value to pass as `custom_image` is a dictionary containing a url to the docker container and configuration to run it. For more details about it, checkout the [Swagger documentation](https://api.endpoints.huggingface.cloud/#/v2%3A%3Aendpoint/create_endpoint). ### Get or list existing Inference Endpoints In some cases, you might need to manage Inference Endpoints you created previously. If you know the name, you can fetch it using [`get_inference_endpoint`], which returns an [`InferenceEndpoint`] object. Alternatively, you can use [`list_inference_endpoints`] to retrieve a list of all Inference Endpoints. Both methods accept an optional `namespace` parameter. You can set the `namespace` to any organization you are a part of. Otherwise, it defaults to your username. ```py >>> from huggingface_hub import get_inference_endpoint, list_inference_endpoints # Get one >>> get_inference_endpoint("my-endpoint-name") InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) # List all endpoints from an organization >>> list_inference_endpoints(namespace="huggingface") [InferenceEndpoint(name='aws-starchat-beta', namespace='huggingface', repository='HuggingFaceH4/starchat-beta', status='paused', url=None), ...] # List all endpoints from all organizations the user belongs to >>> list_inference_endpoints(namespace="*") [InferenceEndpoint(name='aws-starchat-beta', namespace='huggingface', repository='HuggingFaceH4/starchat-beta', status='paused', url=None), ...] ``` Or via CLI: ```bash hf endpoints describe my-endpoint-name hf endpoints ls --namespace huggingface hf endpoints ls --namespace '*' ``` ## Check deployment status In the rest of this guide, we will assume that we have a [`InferenceEndpoint`] object called `endpoint`. You might have noticed that the endpoint has a `status` attribute of type [`InferenceEndpointStatus`]. When the Inference Endpoint is deployed and accessible, the status should be `"running"` and the `url` attribute is set: ```py >>> endpoint InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='running', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud') ``` Before reaching a `"running"` state, the Inference Endpoint typically goes through an `"initializing"` or `"pending"` phase. You can fetch the new state of the endpoint by running [`~InferenceEndpoint.fetch`]. Like every other method from [`InferenceEndpoint`] that makes a request to the server, the internal attributes of `endpoint` are mutated in place: ```py >>> endpoint.fetch() InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) ``` Or via CLI: ```bash hf endpoints describe my-endpoint-name ``` Instead of fetching the Inference Endpoint status while waiting for it to run, you can directly call [`~InferenceEndpoint.wait`]. This helper takes as input a `timeout` and a `fetch_every` parameter (in seconds) and will block the thread until the Inference Endpoint is deployed. Default values are respectively `None` (no timeout) and `5` seconds. ```py # Pending endpoint >>> endpoint InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) # Wait 10s => raises a InferenceEndpointTimeoutError >>> endpoint.wait(timeout=10) raise InferenceEndpointTimeoutError("Timeout while waiting for Inference Endpoint to be deployed.") huggingface_hub._inference_endpoints.InferenceEndpointTimeoutError: Timeout while waiting for Inference Endpoint to be deployed. # Wait more >>> endpoint.wait() InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='running', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud') ``` If `timeout` is set and the Inference Endpoint takes too much time to load, a [`InferenceEndpointTimeoutError`] timeout error is raised. ## Run inference Once your Inference Endpoint is up and running, you can finally run inference on it! [`InferenceEndpoint`] has two properties `client` and `async_client` returning respectively an [`InferenceClient`] and an [`AsyncInferenceClient`] objects. ```py # Run text_generation task: >>> endpoint.client.text_generation("I am") ' not a fan of the idea of a "big-budget" movie. I think it\'s a' # Or in an asyncio context: >>> await endpoint.async_client.text_generation("I am") ``` If the Inference Endpoint is not running, an [`InferenceEndpointError`] exception is raised: ```py >>> endpoint.client huggingface_hub._inference_endpoints.InferenceEndpointError: Cannot create a client for this Inference Endpoint as it is not yet deployed. Please wait for the Inference Endpoint to be deployed using `endpoint.wait()` and try again. ``` For more details about how to use the [`InferenceClient`], check out the [Inference guide](../guides/inference). ## Manage lifecycle Now that we saw how to create an Inference Endpoint and run inference on it, let's see how to manage its lifecycle. > [!TIP] > In this section, we will see methods like [`~InferenceEndpoint.pause`], [`~InferenceEndpoint.resume`], [`~InferenceEndpoint.scale_to_zero`], [`~InferenceEndpoint.update`] and [`~InferenceEndpoint.delete`]. All of those methods are aliases added to [`InferenceEndpoint`] for convenience. If you prefer, you can also use the generic methods defined in `HfApi`: [`pause_inference_endpoint`], [`resume_inference_endpoint`], [`scale_to_zero_inference_endpoint`], [`update_inference_endpoint`], and [`delete_inference_endpoint`]. ### Pause or scale to zero To reduce costs when your Inference Endpoint is not in use, you can choose to either pause it using [`~InferenceEndpoint.pause`] or scale it to zero using [`~InferenceEndpoint.scale_to_zero`]. > [!TIP] > An Inference Endpoint that is *paused* or *scaled to zero* doesn't cost anything. The difference between those two is that a *paused* endpoint needs to be explicitly *resumed* using [`~InferenceEndpoint.resume`]. On the contrary, a *scaled to zero* endpoint will automatically start if an inference call is made to it, with an additional cold start delay. An Inference Endpoint can also be configured to scale to zero automatically after a certain period of inactivity. ```py # Pause and resume endpoint >>> endpoint.pause() InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='paused', url=None) >>> endpoint.resume() InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) >>> endpoint.wait().client.text_generation(...) ... # Scale to zero >>> endpoint.scale_to_zero() InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='scaledToZero', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud') # Endpoint is not 'running' but still has a URL and will restart on first call. ``` Or via CLI: ```bash hf endpoints pause my-endpoint-name hf endpoints resume my-endpoint-name hf endpoints scale-to-zero my-endpoint-name ``` ### Update model or hardware requirements In some cases, you might also want to update your Inference Endpoint without creating a new one. You can either update the hosted model or the hardware requirements to run the model. You can do this using [`~InferenceEndpoint.update`]: ```py # Change target model >>> endpoint.update(repository="gpt2-large") InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None) # Update number of replicas >>> endpoint.update(min_replica=2, max_replica=6) InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None) # Update to larger instance >>> endpoint.update(accelerator="cpu", instance_size="x4", instance_type="intel-icl") InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None) ``` Or via CLI: ```bash hf endpoints update my-endpoint-name --repo gpt2-large hf endpoints update my-endpoint-name --min-replica 2 --max-replica 6 hf endpoints update my-endpoint-name --accelerator cpu --instance-size x4 --instance-type intel-icl ``` ### Delete the endpoint Finally if you won't use the Inference Endpoint anymore, you can simply call [`~InferenceEndpoint.delete()`]. > [!WARNING] > This is a non-revertible action that will completely remove the endpoint, including its configuration, logs and usage metrics. You cannot restore a deleted Inference Endpoint. ## An end-to-end example A typical use case of Inference Endpoints is to process a batch of jobs at once to limit the infrastructure costs. You can automate this process using what we saw in this guide: ```py >>> import asyncio >>> from huggingface_hub import create_inference_endpoint # Start endpoint + wait until initialized >>> endpoint = create_inference_endpoint(name="batch-endpoint",...).wait() # Run inference >>> client = endpoint.client >>> results = [client.text_generation(...) for job in jobs] # Or with asyncio >>> async_client = endpoint.async_client >>> results = asyncio.gather(*[async_client.text_generation(...) for job in jobs]) # Pause endpoint >>> endpoint.pause() ``` Or if your Inference Endpoint already exists and is paused: ```py >>> import asyncio >>> from huggingface_hub import get_inference_endpoint # Get endpoint + wait until initialized >>> endpoint = get_inference_endpoint("batch-endpoint").resume().wait() # Run inference >>> async_client = endpoint.async_client >>> results = asyncio.gather(*[async_client.text_generation(...) for job in jobs]) # Pause endpoint >>> endpoint.pause() ``` huggingface_hub-1.1.5/docs/source/en/guides/integrations.md000066400000000000000000000530231510763414300237740ustar00rootroot00000000000000 # Integrate any ML framework with the Hub The Hugging Face Hub makes hosting and sharing models with the community easy. It supports [dozens of libraries](https://huggingface.co/docs/hub/models-libraries) in the Open Source ecosystem. We are always working on expanding this support to push collaborative Machine Learning forward. The `huggingface_hub` library plays a key role in this process, allowing any Python script to easily push and load files. There are four main ways to integrate a library with the Hub: 1. **Push to Hub:** implement a method to upload a model to the Hub. This includes the model weights, as well as [the model card](https://huggingface.co/docs/huggingface_hub/how-to-model-cards) and any other relevant information or data necessary to run the model (for example, training logs). This method is often called `push_to_hub()`. 2. **Download from Hub:** implement a method to load a model from the Hub. The method should download the model configuration/weights and load the model. This method is often called `from_pretrained` or `load_from_hub()`. 3. **Widgets:** display a widget on the landing page of your models on the Hub. It allows users to quickly try a model from the browser. In this guide, we will focus on the first two topics. We will present the two main approaches you can use to integrate a library, with their advantages and drawbacks. Everything is summarized at the end of the guide to help you choose between the two. Please keep in mind that these are only guidelines that you are free to adapt to you requirements. If you are interested in Inference and Widgets, you can follow [this guide](https://huggingface.co/docs/hub/models-adding-libraries#set-up-the-inference-api). In both cases, you can reach out to us if you are integrating a library with the Hub and want to be listed [in our docs](https://huggingface.co/docs/hub/models-libraries). ## A flexible approach: helpers The first approach to integrate a library to the Hub is to actually implement the `push_to_hub` and `from_pretrained` methods by yourself. This gives you full flexibility on which files you need to upload/download and how to handle inputs specific to your framework. You can refer to the two [upload files](./upload) and [download files](./download) guides to learn more about how to do that. This is, for example how the FastAI integration is implemented (see [`push_to_hub_fastai`] and [`from_pretrained_fastai`]). Implementation can differ between libraries, but the workflow is often similar. ### from_pretrained This is how a `from_pretrained` method usually looks like: ```python def from_pretrained(model_id: str) -> MyModelClass: # Download model from Hub cached_model = hf_hub_download( repo_id=repo_id, filename="model.pkl", library_name="fastai", library_version=get_fastai_version(), ) # Load model return load_model(cached_model) ``` ### push_to_hub The `push_to_hub` method often requires a bit more complexity to handle repo creation, generate the model card and save weights. A common approach is to save all of these files in a temporary folder, upload it and then delete it. ```python def push_to_hub(model: MyModelClass, repo_name: str) -> None: api = HfApi() # Create repo if not existing yet and get the associated repo_id repo_id = api.create_repo(repo_name, exist_ok=True) # Save all files in a temporary directory and push them in a single commit with TemporaryDirectory() as tmpdir: tmpdir = Path(tmpdir) # Save weights save_model(model, tmpdir / "model.safetensors") # Generate model card card = generate_model_card(model) (tmpdir / "README.md").write_text(card) # Save logs # Save figures # Save evaluation metrics # ... # Push to hub return api.upload_folder(repo_id=repo_id, folder_path=tmpdir) ``` This is of course only an example. If you are interested in more complex manipulations (delete remote files, upload weights on the fly, persist weights locally, etc.) please refer to the [upload files](./upload) guide. ### Limitations While being flexible, this approach has some drawbacks, especially in terms of maintenance. Hugging Face users are often used to additional features when working with `huggingface_hub`. For example, when loading files from the Hub, it is common to offer parameters like: - `token`: to download from a private repo - `revision`: to download from a specific branch - `cache_dir`: to cache files in a specific directory - `force_download`/`local_files_only`: to reuse the cache or not - `proxies`: configure HTTP session When pushing models, similar parameters are supported: - `commit_message`: custom commit message - `private`: create a private repo if missing - `create_pr`: create a PR instead of pushing to `main` - `branch`: push to a branch instead of the `main` branch - `allow_patterns`/`ignore_patterns`: filter which files to upload - `token` - ... All of these parameters can be added to the implementations we saw above and passed to the `huggingface_hub` methods. However, if a parameter changes or a new feature is added, you will need to update your package. Supporting those parameters also means more documentation to maintain on your side. To see how to mitigate these limitations, let's jump to our next section **class inheritance**. ## A more complex approach: class inheritance As we saw above, there are two main methods to include in your library to integrate it with the Hub: upload files (`push_to_hub`) and download files (`from_pretrained`). You can implement those methods by yourself but it comes with caveats. To tackle this, `huggingface_hub` provides a tool that uses class inheritance. Let's see how it works! In a lot of cases, a library already implements its model using a Python class. The class contains the properties of the model and methods to load, run, train, and evaluate it. Our approach is to extend this class to include upload and download features using mixins. A [Mixin](https://stackoverflow.com/a/547714) is a class that is meant to extend an existing class with a set of specific features using multiple inheritance. `huggingface_hub` provides its own mixin, the [`ModelHubMixin`]. The key here is to understand its behavior and how to customize it. The [`ModelHubMixin`] class implements 3 *public* methods (`push_to_hub`, `save_pretrained` and `from_pretrained`). Those are the methods that your users will call to load/save models with your library. [`ModelHubMixin`] also defines 2 *private* methods (`_save_pretrained` and `_from_pretrained`). Those are the ones you must implement. So to integrate your library, you should: 1. Make your Model class inherit from [`ModelHubMixin`]. 2. Implement the private methods: - [`~ModelHubMixin._save_pretrained`]: method taking as input a path to a directory and saving the model to it. You must write all the logic to dump your model in this method: model card, model weights, configuration files, training logs, and figures. Any relevant information for this model must be handled by this method. [Model Cards](https://huggingface.co/docs/hub/model-cards) are particularly important to describe your model. Check out [our implementation guide](./model-cards) for more details. - [`~ModelHubMixin._from_pretrained`]: **class method** taking as input a `model_id` and returning an instantiated model. The method must download the relevant files and load them. 3. You are done! The advantage of using [`ModelHubMixin`] is that once you take care of the serialization/loading of the files, you are ready to go. You don't need to worry about stuff like repo creation, commits, PRs, or revisions. The [`ModelHubMixin`] also ensures public methods are documented and type annotated, and you'll be able to view your model's download count on the Hub. All of this is handled by the [`ModelHubMixin`] and available to your users. ### A concrete example: PyTorch A good example of what we saw above is [`PyTorchModelHubMixin`], our integration for the PyTorch framework. This is a ready-to-use integration. #### How to use it? Here is how any user can load/save a PyTorch model from/to the Hub: ```python >>> import torch >>> import torch.nn as nn >>> from huggingface_hub import PyTorchModelHubMixin # Define your Pytorch model exactly the same way you are used to >>> class MyModel( ... nn.Module, ... PyTorchModelHubMixin, # multiple inheritance ... library_name="keras-nlp", ... tags=["keras"], ... repo_url="https://github.com/keras-team/keras-nlp", ... docs_url="https://keras.io/keras_nlp/", ... # ^ optional metadata to generate model card ... ): ... def __init__(self, hidden_size: int = 512, vocab_size: int = 30000, output_size: int = 4): ... super().__init__() ... self.param = nn.Parameter(torch.rand(hidden_size, vocab_size)) ... self.linear = nn.Linear(output_size, vocab_size) ... def forward(self, x): ... return self.linear(x + self.param) # 1. Create model >>> model = MyModel(hidden_size=128) # Config is automatically created based on input + default values >>> model.param.shape[0] 128 # 2. (optional) Save model to local directory >>> model.save_pretrained("path/to/my-awesome-model") # 3. Push model weights to the Hub >>> model.push_to_hub("my-awesome-model") # 4. Initialize model from the Hub => config has been preserved >>> model = MyModel.from_pretrained("username/my-awesome-model") >>> model.param.shape[0] 128 # Model card has been correctly populated >>> from huggingface_hub import ModelCard >>> card = ModelCard.load("username/my-awesome-model") >>> card.data.tags ["keras", "pytorch_model_hub_mixin", "model_hub_mixin"] >>> card.data.library_name "keras-nlp" ``` #### Implementation The implementation is actually very straightforward, and the full implementation can be found [here](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hub_mixin.py). 1. First, inherit your class from `ModelHubMixin`: ```python from huggingface_hub import ModelHubMixin class PyTorchModelHubMixin(ModelHubMixin): (...) ``` 2. Implement the `_save_pretrained` method: ```py from huggingface_hub import ModelHubMixin class PyTorchModelHubMixin(ModelHubMixin): (...) def _save_pretrained(self, save_directory: Path) -> None: """Save weights from a Pytorch model to a local directory.""" save_model_as_safetensor(self.module, str(save_directory / SAFETENSORS_SINGLE_FILE)) ``` 3. Implement the `_from_pretrained` method: ```python class PyTorchModelHubMixin(ModelHubMixin): (...) @classmethod # Must be a classmethod! def _from_pretrained( cls, *, model_id: str, revision: str, cache_dir: str, force_download: bool, local_files_only: bool, token: Union[str, bool, None], map_location: str = "cpu", # additional argument strict: bool = False, # additional argument **model_kwargs, ): """Load Pytorch pretrained weights and return the loaded model.""" model = cls(**model_kwargs) if os.path.isdir(model_id): print("Loading weights from local directory") model_file = os.path.join(model_id, SAFETENSORS_SINGLE_FILE) return cls._load_as_safetensor(model, model_file, map_location, strict) model_file = hf_hub_download( repo_id=model_id, filename=SAFETENSORS_SINGLE_FILE, revision=revision, cache_dir=cache_dir, force_download=force_download, token=token, local_files_only=local_files_only, ) return cls._load_as_safetensor(model, model_file, map_location, strict) ``` And that's it! Your library now enables users to upload and download files to and from the Hub. ### Advanced usage In the section above, we quickly discussed how the [`ModelHubMixin`] works. In this section, we will see some of its more advanced features to improve your library integration with the Hugging Face Hub. #### Model card [`ModelHubMixin`] generates the model card for you. Model cards are files that accompany the models and provide important information about them. Under the hood, model cards are simple Markdown files with additional metadata. Model cards are essential for discoverability, reproducibility, and sharing! Check out the [Model Cards guide](https://huggingface.co/docs/hub/model-cards) for more details. Generating model cards semi-automatically is a good way to ensure that all models pushed with your library will share common metadata: `library_name`, `tags`, `license`, `pipeline_tag`, etc. This makes all models backed by your library easily searchable on the Hub and provides some resource links for users landing on the Hub. You can define the metadata directly when inheriting from [`ModelHubMixin`]: ```py class UniDepthV1( nn.Module, PyTorchModelHubMixin, library_name="unidepth", repo_url="https://github.com/lpiccinelli-eth/UniDepth", docs_url=..., pipeline_tag="depth-estimation", license="cc-by-nc-4.0", tags=["monocular-metric-depth-estimation", "arxiv:1234.56789"] ): ... ``` By default, a generic model card will be generated with the info you've provided (example: [pyp1/VoiceCraft_giga830M](https://huggingface.co/pyp1/VoiceCraft_giga830M)). But you can define your own model card template as well! In this example, all models pushed with the `VoiceCraft` class will automatically include a citation section and license details. For more details on how to define a model card template, please check the [Model Cards guide](./model-cards). ```py MODEL_CARD_TEMPLATE = """ --- # For reference on model card metadata, see the spec: https://github.com/huggingface/hub-docs/blob/main/modelcard.md?plain=1 # Doc / guide: https://huggingface.co/docs/hub/model-cards {{ card_data }} --- This is a VoiceCraft model. For more details, please check out the official Github repo: https://github.com/jasonppy/VoiceCraft. This model is shared under a Attribution-NonCommercial-ShareAlike 4.0 International license. ## Citation @article{peng2024voicecraft, author = {Peng, Puyuan and Huang, Po-Yao and Li, Daniel and Mohamed, Abdelrahman and Harwath, David}, title = {VoiceCraft: Zero-Shot Speech Editing and Text-to-Speech in the Wild}, journal = {arXiv}, year = {2024}, } """ class VoiceCraft( nn.Module, PyTorchModelHubMixin, library_name="voicecraft", model_card_template=MODEL_CARD_TEMPLATE, ... ): ... ``` Finally, if you want to extend the model card generation process with dynamic values, you can override the [`~ModelHubMixin.generate_model_card`] method: ```py from huggingface_hub import ModelCard, PyTorchModelHubMixin class UniDepthV1(nn.Module, PyTorchModelHubMixin, ...): (...) def generate_model_card(self, *args, **kwargs) -> ModelCard: card = super().generate_model_card(*args, **kwargs) card.data.metrics = ... # add metrics to the metadata card.text += ... # append section to the modelcard return card ``` #### Config [`ModelHubMixin`] handles the model configuration for you. It automatically checks the input values when you instantiate the model and serializes them in a `config.json` file. This provides 2 benefits: 1. Users will be able to reload the model with the exact same parameters as you. 2. Having a `config.json` file automatically enables analytics on the Hub (i.e. the "downloads" count). But how does it work in practice? Several rules make the process as smooth as possible from a user perspective: - if your `__init__` method expects a `config` input, it will be automatically saved in the repo as `config.json`. - if the `config` input parameter is annotated with a dataclass type (e.g. `config: Optional[MyConfigClass] = None`), then the `config` value will be correctly deserialized for you. - all values passed at initialization will also be stored in the config file. This means you don't necessarily have to expect a `config` input to benefit from it. Example: ```py class MyModel(ModelHubMixin): def __init__(value: str, size: int = 3): self.value = value self.size = size (...) # implement _save_pretrained / _from_pretrained model = MyModel(value="my_value") model.save_pretrained(...) # config.json contains passed and default values {"value": "my_value", "size": 3} ``` But what if a value cannot be serialized as JSON? By default, the value will be ignored when saving the config file. However, in some cases your library already expects a custom object as input that cannot be serialized, and you don't want to update your internal logic to update its type. No worries! You can pass custom encoders/decoders for any type when inheriting from [`ModelHubMixin`]. This is a bit more work but ensures your internal logic is untouched when integrating your library with the Hub. Here is a concrete example where a class expects a `argparse.Namespace` config as input: ```py class VoiceCraft(nn.Module): def __init__(self, args): self.pattern = self.args.pattern self.hidden_size = self.args.hidden_size ... ``` One solution can be to update the `__init__` signature to `def __init__(self, pattern: str, hidden_size: int)` and update all snippets that instantiate your class. This is a perfectly valid way to fix it but it might break downstream applications using your library. Another solution is to provide a simple encoder/decoder to convert `argparse.Namespace` to a dictionary. ```py from argparse import Namespace class VoiceCraft( nn.Module, PyTorchModelHubMixin, # inherit from mixin coders={ Namespace : ( lambda x: vars(x), # Encoder: how to convert a `Namespace` to a valid jsonable value? lambda data: Namespace(**data), # Decoder: how to reconstruct a `Namespace` from a dictionary? ) } ): def __init__(self, args: Namespace): # annotate `args` self.pattern = self.args.pattern self.hidden_size = self.args.hidden_size ... ``` In the snippet above, both the internal logic and the `__init__` signature of the class did not change. This means all existing code snippets for your library will continue to work. To achieve this, we had to: 1. Inherit from the mixin (`PytorchModelHubMixin` in this case). 2. Pass a `coders` parameter in the inheritance. This is a dictionary where keys are custom types you want to process. Values are a tuple `(encoder, decoder)`. - The encoder expects an object of the specified type as input and returns a jsonable value. This will be used when saving a model with `save_pretrained`. - The decoder expects raw data (typically a dictionary) as input and reconstructs the initial object. This will be used when loading the model with `from_pretrained`. 3. Add a type annotation to the `__init__` signature. This is important to let the mixin know which type is expected by the class and, therefore, which decoder to use. For the sake of simplicity, the encoder/decoder functions in the example above are not robust. For a concrete implementation, you would most likely have to handle corner cases properly. ## Quick comparison Let's quickly sum up the two approaches we saw with their advantages and drawbacks. The table below is only indicative. Your framework might have some specificities that you need to address. This guide is only here to give guidelines and ideas on how to handle integration. In any case, feel free to contact us if you have any questions! | Integration | Using helpers | Using [`ModelHubMixin`] | | :-----------------------------: | :----------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------: | | User experience | `model = load_from_hub(...)`
`push_to_hub(model, ...)` | `model = MyModel.from_pretrained(...)`
`model.push_to_hub(...)` | | Flexibility | Very flexible.
You fully control the implementation. | Less flexible.
Your framework must have a model class. | | Maintenance | More maintenance to add support for configuration, and new features. Might also require fixing issues reported by users. | Less maintenance as most of the interactions with the Hub are implemented in `huggingface_hub`. | | Documentation / Type annotation | To be written manually. | Partially handled by `huggingface_hub`. | | Download counter | To be handled manually. | Enabled by default if class has a `config` attribute. | | Model card | To be handled manually | Generated by default with library_name, tags, etc. | huggingface_hub-1.1.5/docs/source/en/guides/jobs.md000066400000000000000000000414041510763414300222230ustar00rootroot00000000000000 # Run and manage Jobs The Hugging Face Hub provides compute for AI and data workflows via Jobs. A job runs on Hugging Face infrastructure and are defined with a command to run (e.g. a python command), a Docker Image from Hugging Face Spaces or Docker Hub, and a hardware flavor (CPU, GPU, TPU). This guide will show you how to interact with Jobs on the Hub, especially: - Run a job. - Check job status. - Select the hardware. - Configure environment variables and secrets. - Run UV scripts. If you want to run and manage a job on the Hub, your machine must be logged in. If you are not, please refer to [this section](../quick-start#authentication). In the rest of this guide, we will assume that your machine is logged in. > [!TIP] > **Hugging Face Jobs** are available only to [Pro users](https://huggingface.co/pro) and [Team or Enterprise organizations](https://huggingface.co/enterprise). Upgrade your plan to get started! ## Jobs Command Line Interface Use the [`hf jobs` CLI](./cli#hf-jobs) to run Jobs from the command line, and pass `--flavor` to specify your hardware. `hf jobs run` runs Jobs with a Docker image and a command with a familiar Docker-like interface. Think `docker run`, but for running code on any hardware: ```bash >>> hf jobs run python:3.12 python -c "print('Hello world!')" >>> 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())" ``` Use `hf jobs uv run` to run local or remote UV scripts: ```bash >>> hf jobs uv run my_script.py >>> hf jobs uv run --flavor a10g-small "https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py" ``` UV scripts are Python scripts that include their dependencies directly in the file using a special comment syntax defined in the [UV documentation](https://docs.astral.sh/uv/guides/scripts/). Now the rest of this guide will show you the python API. If you would like to view all the available `hf jobs` commands and options instead, check out the [guide on the `hf jobs` command line interface](./cli#hf-jobs). ## Run a Job Run compute Jobs defined with a command and a Docker Image on Hugging Face infrastructure (including GPUs and TPUs). You can only manage Jobs that you own (under your username namespace) or from organizations in which you have write permissions. This feature is pay-as-you-go: you only pay for the seconds you use. [`run_job`] lets you run any command on Hugging Face's infrastructure: ```python # Directly run Python code >>> from huggingface_hub import run_job >>> run_job( ... image="python:3.12", ... command=["python", "-c", "print('Hello from the cloud!')"], ... ) # Use GPUs without any setup >>> run_job( ... image="pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel", ... command=["python", "-c", "import torch; print(torch.cuda.get_device_name())"], ... flavor="a10g-small", ... ) # Run in an organization account >>> run_job( ... image="python:3.12", ... command=["python", "-c", "print('Running in an org account')"], ... namespace="my-org-name", ... ) # Run from Hugging Face Spaces >>> run_job( ... image="hf.co/spaces/lhoestq/duckdb", ... command=["duckdb", "-c", "select 'hello world'"], ... ) # Run a Python script with `uv` (experimental) >>> from huggingface_hub import run_uv_job >>> run_uv_job("my_script.py") ``` > [!WARNING] > **Important**: Jobs have a default timeout (30 minutes), after which they will automatically stop. For long-running tasks like model training, make sure to set a custom timeout using the `timeout` parameter. See [Configure Job Timeout](#configure-job-timeout) for details. [`run_job`] returns the [`JobInfo`] which has the URL of the Job on Hugging Face, where you can see the Job status and the logs. Save the Job ID from [`JobInfo`] to manage the job: ```python >>> from huggingface_hub import run_job >>> job = run_job( ... image="python:3.12", ... command=["python", "-c", "print('Hello from the cloud!')"] ... ) >>> job.url https://huggingface.co/jobs/lhoestq/687f911eaea852de79c4a50a >>> job.id 687f911eaea852de79c4a50a ``` Jobs run in the background. The next section guides you through [`inspect_job`] to know a jobs' status and [`fetch_job_logs`] to view the logs. ## Check Job status ```python # List your jobs >>> from huggingface_hub import list_jobs >>> jobs = list_jobs() >>> jobs[0] JobInfo(id='687f911eaea852de79c4a50a', created_at=datetime.datetime(2025, 7, 22, 13, 24, 46, 909000, tzinfo=datetime.timezone.utc), docker_image='python:3.12', space_id=None, command=['python', '-c', "print('Hello from the cloud!')"], arguments=[], environment={}, secrets={}, flavor='cpu-basic', status=JobStatus(stage='COMPLETED', message=None), owner=JobOwner(id='5e9ecfc04957053f60648a3e', name='lhoestq'), endpoint='https://huggingface.co', url='https://huggingface.co/jobs/lhoestq/687f911eaea852de79c4a50a') # List your running jobs >>> running_jobs = [job for job in list_jobs() if job.status.stage == "RUNNING"] # Inspect the status of a job >>> from huggingface_hub import inspect_job >>> inspect_job(job_id=job_id) JobInfo(id='687f911eaea852de79c4a50a', created_at=datetime.datetime(2025, 7, 22, 13, 24, 46, 909000, tzinfo=datetime.timezone.utc), docker_image='python:3.12', space_id=None, command=['python', '-c', "print('Hello from the cloud!')"], arguments=[], environment={}, secrets={}, flavor='cpu-basic', status=JobStatus(stage='COMPLETED', message=None), owner=JobOwner(id='5e9ecfc04957053f60648a3e', name='lhoestq'), endpoint='https://huggingface.co', url='https://huggingface.co/jobs/lhoestq/687f911eaea852de79c4a50a') # View logs from a job >>> from huggingface_hub import fetch_job_logs >>> for log in fetch_job_logs(job_id=job_id): ... print(log) Hello from the cloud! # Cancel a job >>> from huggingface_hub import cancel_job >>> cancel_job(job_id=job_id) ``` Check the status of multiple jobs to know when they're all finished using a loop and [`inspect_job`]: ```python # Run multiple jobs in parallel and wait for their completions >>> import time >>> from huggingface_hub import inspect_job, run_job >>> jobs = [run_job(image=image, command=command) for command in commands] >>> for job in jobs: ... while inspect_job(job_id=job.id).status.stage not in ("COMPLETED", "ERROR"): ... time.sleep(10) ``` ## Select the hardware There are numerous cases where running Jobs on GPUs are useful: - **Model Training**: Fine-tune or train models on GPUs (T4, A10G, A100) without managing infrastructure - **Synthetic Data Generation**: Generate large-scale datasets using LLMs on powerful hardware - **Data Processing**: Process massive datasets with high-CPU configurations for parallel workloads - **Batch Inference**: Run offline inference on thousands of samples using optimized GPU setups - **Experiments & Benchmarks**: Run ML experiments on consistent hardware for reproducible results - **Development & Debugging**: Test GPU code without local CUDA setup Run jobs on GPUs or TPUs with the `flavor` argument. For example, to run a PyTorch job on an A10G GPU: ```python # Use an A10G GPU to check PyTorch CUDA >>> from huggingface_hub import run_job >>> run_job( ... image="pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel", ... command=["python", "-c", "import torch; print(f'This code ran with the following GPU: {torch.cuda.get_device_name()}')"], ... flavor="a10g-small", ... ) ``` Running this will show the following output! ```bash This code ran with the following GPU: NVIDIA A10G ``` Use this to run a fine-tuning script like [trl/scripts/sft.py](https://github.com/huggingface/trl/blob/main/trl/scripts/sft.py) with UV: ```python >>> from huggingface_hub import run_uv_job >>> run_uv_job( ... "sft.py", ... script_args=["--model_name_or_path", "Qwen/Qwen2-0.5B", ...], ... dependencies=["trl"], ... env={"HF_TOKEN": ...}, ... flavor="a10g-small", ... ) ``` > [!TIP] > For comprehensive guidance on running model training jobs with TRL on Hugging Face infrastructure, check out the [TRL Jobs Training documentation](https://huggingface.co/docs/trl/main/en/jobs_training). It covers fine-tuning recipes, hardware selection, and best practices for training models efficiently. Available `flavor` options: - 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` (updated in 07/2025 from Hugging Face [suggested_hardware docs](https://huggingface.co/docs/hub/en/spaces-config-reference)) That's it! You're now running code on Hugging Face's infrastructure. ## Configure Job Timeout Jobs have a default timeout (30 minutes), after which they will automatically stop. This is important to know when running long-running tasks like model training. ### Setting a custom timeout You can specify a custom timeout value using the `timeout` parameter when running a job. The timeout can be specified in two ways: 1. **As a number** (interpreted as seconds): ```python >>> from huggingface_hub import run_job >>> job = run_job( ... image="pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel", ... command=["python", "train_model.py"], ... flavor="a10g-large", ... timeout=7200, # 2 hours in seconds ... ) ``` 2. **As a string with time units**: ```python >>> # Using different time units >>> job = run_job( ... image="pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel", ... command=["python", "train_model.py"], ... flavor="a10g-large", ... timeout="2h", # 2 hours ... ) >>> # Other examples: >>> # timeout="30m" # 30 minutes >>> # timeout="1.5h" # 1.5 hours >>> # timeout="1d" # 1 day >>> # timeout="3600s" # 3600 seconds ``` Supported time units: - `s` - seconds - `m` - minutes - `h` - hours - `d` - days ### Using timeout with UV jobs For UV jobs, you can also specify the timeout: ```python >>> from huggingface_hub import run_uv_job >>> job = run_uv_job( ... "training_script.py", ... flavor="a10g-large", ... timeout="90m", # 90 minutes ... ) ``` > [!WARNING] > If you don't specify a timeout, a default timeout will be applied to your job. For long-running tasks like model training that may take hours, make sure to set an appropriate timeout to avoid unexpected job terminations. ### Monitoring job duration When running long tasks, it's good practice to: - Estimate your job's expected duration and set a timeout with some buffer - Monitor your job's progress through the logs - Check the job status to ensure it hasn't timed out ```python >>> from huggingface_hub import inspect_job, fetch_job_logs >>> # Check job status >>> job_info = inspect_job(job_id=job.id) >>> if job_info.status.stage == "ERROR": ... print(f"Job failed: {job_info.status.message}") ... # Check logs for more details ... for log in fetch_job_logs(job_id=job.id): ... print(log) ``` For more details about the timeout parameter, see the [`run_job` API reference](https://huggingface.co/docs/huggingface_hub/package_reference/hf_api#huggingface_hub.HfApi.run_job.timeout). ## Pass Environment variables and Secrets You can pass environment variables to your job using `env` and `secrets`: ```python # Pass environment variables >>> from huggingface_hub import run_job >>> run_job( ... image="python:3.12", ... command=["python", "-c", "import os; print(os.environ['FOO'], os.environ['BAR'])"], ... env={"FOO": "foo", "BAR": "bar"}, ... ) ``` ```python # Pass secrets - they will be encrypted server side >>> from huggingface_hub import run_job >>> run_job( ... image="python:3.12", ... command=["python", "-c", "import os; print(os.environ['MY_SECRET'])"], ... secrets={"MY_SECRET": "psswrd"}, ... ) ``` ### UV Scripts (Experimental) > [!TIP] > Looking for ready-to-use UV scripts? Check out the [uv-scripts organization](https://huggingface.co/uv-scripts) on the Hugging Face Hub, which offers a community collection of UV scripts for tasks like model training, synthetic data generation, data processing, and more. Run UV scripts (Python scripts with inline dependencies) on HF infrastructure: ```python # Run a UV script (creates temporary repo) >>> from huggingface_hub import run_uv_job >>> run_uv_job("my_script.py") # Run with GPU >>> run_uv_job("ml_training.py", flavor="gpu-t4-small") # Run with dependencies >>> run_uv_job("inference.py", dependencies=["transformers", "torch"]) # Run a script directly from a URL >>> run_uv_job("https://huggingface.co/datasets/username/scripts/resolve/main/example.py") # Run a command >>> run_uv_job("python", script_args=["-c", "import lighteval"], dependencies=["lighteval"]) ``` UV scripts are Python scripts that include their dependencies directly in the file using a special comment syntax. This makes them perfect for self-contained tasks that don't require complex project setups. Learn more about UV scripts in the [UV documentation](https://docs.astral.sh/uv/guides/scripts/). #### Docker Images for UV Scripts While UV scripts can specify their dependencies inline, ML workloads often have complex dependencies. Using pre-built Docker images with these libraries already installed can significantly speed up job startup and avoid dependency issues. By default, when you run `hf jobs uv run` the `astral-sh/uv:python3.12-bookworm` image is used. This image is based on the Python 3.12 Bookworm distribution with uv pre-installed. You can specify a different image using the `--image` flag: ```bash hf jobs uv run \ --flavor a10g-large \ --image vllm/vllm-openai:latest \ ... ``` The above command will run using the `vllm/vllm-openai:latest` image. This approach could be useful if you are using vLLM for synthetic data generation. > [!TIP] > Many inference frameworks provide optimized docker images. As uv is increasingly adopted in the Python ecosystem more of these will also have uv pre-installed meaning they will work when using hf jobs uv run. ### Scheduled Jobs Schedule and manage jobs that will run on HF infrastructure. Use [`create_scheduled_job`] or [`create_scheduled_uv_job`] with a schedule of `@annually`, `@yearly`, `@monthly`, `@weekly`, `@daily`, `@hourly`, or a CRON schedule expression (e.g., `"0 9 * * 1"` for 9 AM every Monday): ```python # Schedule a job that runs every hour >>> from huggingface_hub import create_scheduled_job >>> create_scheduled_job( ... image="python:3.12", ... command=["python", "-c", "print('This runs every hour!')"], ... schedule="@hourly" ... ) # Use the CRON syntax >>> create_scheduled_job( ... image="python:3.12", ... command=["python", "-c", "print('This runs every 5 minutes!')"], ... schedule="*/5 * * * *" ... ) # Schedule with GPU >>> create_scheduled_job( ... image="pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel", ... command=["python", "-c", 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'], ... schedule="@hourly", ... flavor="a10g-small", ... ) # Schedule a UV script >>> from huggingface_hub import create_scheduled_uv_job >>> create_scheduled_uv_job("my_script.py", schedule="@hourly") ``` Use the same parameters as [`run_job`] and [`run_uv_job`] to pass environment variables, secrets, timeout, etc. Manage scheduled jobs using [`list_scheduled_jobs`], [`inspect_scheduled_job`], [`suspend_scheduled_job`], [`resume_scheduled_job`], and [`delete_scheduled_job`]: ```python # List your active scheduled jobs >>> from huggingface_hub import list_scheduled_jobs >>> list_scheduled_jobs() # Inspect the status of a job >>> from huggingface_hub import inspect_scheduled_job >>> inspect_scheduled_job(scheduled_job_id) # Suspend (pause) a scheduled job >>> from huggingface_hub import suspend_scheduled_job >>> suspend_scheduled_job(scheduled_job_id) # Resume a scheduled job >>> from huggingface_hub import resume_scheduled_job >>> resume_scheduled_job(scheduled_job_id) # Delete a scheduled job >>> from huggingface_hub import delete_scheduled_job >>> delete_scheduled_job(scheduled_job_id) ``` ### Trigger Jobs with webhooks Webhooks allow you to listen for new changes on specific repos or to all repos belonging to particular set of users/organizations (not just your repos, but any repo). Use [`create_webhook`] to create a webhook that triggers a Job when a change happens in a Hugging Face repository: ```python from huggingface_hub import create_webhook # Example: Creating a webhook that triggers a Job webhook = create_webhook( job_id=job_id, watched=[{"type": "user", "name": "your-username"}, {"type": "org", "name": "your-org-name"}], domains=["repo", "discussion"], secret="your-secret" ) ``` The webhook triggers the Job with the webhook payload in the environment variable `WEBHOOK_PAYLOAD`. You can find more information on webhooks in the [Webhooks documentation](./webhooks). huggingface_hub-1.1.5/docs/source/en/guides/manage-cache.md000066400000000000000000000713541510763414300235660ustar00rootroot00000000000000 # Understand caching `huggingface_hub` utilizes the local disk as two caches, which avoid re-downloading items again. The first cache is a file-based cache, which caches individual files downloaded from the Hub and ensures that the same file is not downloaded again when a repo gets updated. The second cache is a chunk cache, where each chunk represents a byte range from a file and ensures that chunks that are shared across files are only downloaded once. ## File-based caching The Hugging Face Hub cache-system is designed to be the central cache shared across libraries that depend on the Hub. It has been updated in v0.8.0 to prevent re-downloading same files between revisions. The caching system is designed as follows: ``` ├─ ├─ ├─ ``` The default `` is `~/.cache/huggingface/hub`. However, it is customizable with the `cache_dir` argument on all methods, or by specifying either `HF_HOME` or `HF_HUB_CACHE` environment variable. Models, datasets and spaces share a common root. Each of these repositories contains the repository type, the namespace (organization or username) if it exists and the repository name: ``` ├─ models--julien-c--EsperBERTo-small ├─ models--lysandrejik--arxiv-nlp ├─ models--bert-base-cased ├─ datasets--glue ├─ datasets--huggingface--DataMeasurementsFiles ├─ spaces--dalle-mini--dalle-mini ``` It is within these folders that all files will now be downloaded from the Hub. Caching ensures that a file isn't downloaded twice if it already exists and wasn't updated; but if it was updated, and you're asking for the latest file, then it will download the latest file (while keeping the previous file intact in case you need it again). In order to achieve this, all folders contain the same skeleton: ``` ├─ datasets--glue │ ├─ refs │ ├─ blobs │ ├─ snapshots ... ``` Each folder is designed to contain the following: ### Refs The `refs` folder contains files which indicates the latest revision of the given reference. For example, if we have previously fetched a file from the `main` branch of a repository, the `refs` folder will contain a file named `main`, which will itself contain the commit identifier of the current head. If the latest commit of `main` has `aaaaaa` as identifier, then it will contain `aaaaaa`. If that same branch gets updated with a new commit, that has `bbbbbb` as an identifier, then re-downloading a file from that reference will update the `refs/main` file to contain `bbbbbb`. ### Blobs The `blobs` folder contains the actual files that we have downloaded. The name of each file is their hash. ### Snapshots The `snapshots` folder contains symlinks to the blobs mentioned above. It is itself made up of several folders: one per known revision! In the explanation above, we had initially fetched a file from the `aaaaaa` revision, before fetching a file from the `bbbbbb` revision. In this situation, we would now have two folders in the `snapshots` folder: `aaaaaa` and `bbbbbb`. In each of these folders, live symlinks that have the names of the files that we have downloaded. For example, if we had downloaded the `README.md` file at revision `aaaaaa`, we would have the following path: ``` //snapshots/aaaaaa/README.md ``` That `README.md` file is actually a symlink linking to the blob that has the hash of the file. By creating the skeleton this way we open the mechanism to file sharing: if the same file was fetched in revision `bbbbbb`, it would have the same hash and the file would not need to be re-downloaded. ### .no_exist (advanced) In addition to the `blobs`, `refs` and `snapshots` folders, you might also find a `.no_exist` folder in your cache. This folder keeps track of files that you've tried to download once but don't exist on the Hub. Its structure is the same as the `snapshots` folder with 1 subfolder per known revision: ``` //.no_exist/aaaaaa/config_that_does_not_exist.json ``` Unlike the `snapshots` folder, files are simple empty files (no symlinks). In this example, the file `"config_that_does_not_exist.json"` does not exist on the Hub for the revision `"aaaaaa"`. As it only stores empty files, this folder is neglectable in term of disk usage. So now you might wonder, why is this information even relevant? In some cases, a framework tries to load optional files for a model. Saving the non-existence of optional files makes it faster to load a model as it saves 1 HTTP call per possible optional file. This is for example the case in `transformers` where each tokenizer can support additional files. The first time you load the tokenizer on your machine, it will cache which optional files exist (and which doesn't) to make the loading time faster for the next initializations. To test if a file is cached locally (without making any HTTP request), you can use the [`try_to_load_from_cache`] helper. It will either return the filepath (if exists and cached), the object `_CACHED_NO_EXIST` (if non-existence is cached) or `None` (if we don't know). ```python from huggingface_hub import try_to_load_from_cache, _CACHED_NO_EXIST filepath = try_to_load_from_cache() if isinstance(filepath, str): # file exists and is cached ... elif filepath is _CACHED_NO_EXIST: # non-existence of file is cached ... else: # file is not cached ... ``` ### In practice In practice, your cache should look like the following tree: ```text [ 96] . └── [ 160] models--julien-c--EsperBERTo-small ├── [ 160] blobs │ ├── [321M] 403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd │ ├── [ 398] 7cb18dc9bafbfcf74629a4b760af1b160957a83e │ └── [1.4K] d7edf6bd2a681fb0175f7735299831ee1b22b812 ├── [ 96] refs │ └── [ 40] main └── [ 128] snapshots ├── [ 128] 2439f60ef33a0d46d85da5001d52aeda5b00ce9f │ ├── [ 52] README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812 │ └── [ 76] pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd └── [ 128] bbc77c8132af1cc5cf678da3f1ddf2de43606d48 ├── [ 52] README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e └── [ 76] pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd ``` ### Limitations In order to have an efficient cache-system, `huggingface-hub` uses symlinks. However, symlinks are not supported on all machines. This is a known limitation especially on Windows. When this is the case, `huggingface_hub` do not use the `blobs/` directory but directly stores the files in the `snapshots/` directory instead. This workaround allows users to download and cache files from the Hub exactly the same way. Tools to inspect and delete the cache (see below) are also supported. However, the cache-system is less efficient as a single file might be downloaded several times if multiple revisions of the same repo is downloaded. If you want to benefit from the symlink-based cache-system on a Windows machine, you either need to [activate Developer Mode](https://docs.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development) or to run Python as an administrator. When symlinks are not supported, a warning message is displayed to the user to alert them they are using a degraded version of the cache-system. This warning can be disabled by setting the `HF_HUB_DISABLE_SYMLINKS_WARNING` environment variable to true. ## Chunk-based caching (Xet) To provide more efficient file transfers, `hf_xet` adds a `xet` directory to the existing `huggingface_hub` cache, creating additional caching layer to enable chunk-based deduplication. This cache holds chunks (immutable byte ranges of files ~64KB in size) and shards (a data structure that maps files to chunks). For more information on the Xet Storage system, see this [section](https://huggingface.co/docs/hub/xet/index). The `xet` directory, located at `~/.cache/huggingface/xet` by default, contains two caches, utilized for uploads and downloads. It has the following structure: ```bash ├─ xet │ ├─ environment_identifier │ │ ├─ chunk_cache │ │ ├─ shard_cache │ │ ├─ staging ``` The `environment_identifier` directory is an encoded string (it may appear on your machine as `https___cas_serv-tGqkUaZf_CBPHQ6h`). This is used during development allowing for local and production versions of the cache to exist alongside each other simultaneously. It is also used when downloading from repositories that reside in different [storage regions](https://huggingface.co/docs/hub/storage-regions). You may see multiple such entries in the `xet` directory, each corresponding to a different environment, but their internal structure is the same. The internal directories serve the following purposes: * `chunk-cache` contains cached data chunks that are used to speed up downloads. * `shard-cache` contains cached shards that are utilized on the upload path. * `staging` is a workspace designed to support resumable uploads. These are documented below. Note that the `xet` caching system, like the rest of `hf_xet` is fully integrated with `huggingface_hub`. If you use the existing APIs for interacting with cached assets, there is no need to update your workflow. The `xet` caches are built as an optimization layer on top of the existing `hf_xet` chunk-based deduplication and `huggingface_hub` cache system. ### `chunk_cache` This cache is used on the download path. The cache directory structure is based on a base-64 encoded hash from the content-addressed store (CAS) that backs each Xet-enabled repository. A CAS hash serves as the key to lookup the offsets of where the data is stored. Note: as of `hf_xet` 1.2.0 the chunk_cache is disabled by default. To enable it, set the `HF_XET_CHUNK_CACHE_SIZE_BYTES` environment variable to the appropriate size prior to launching the Python process. At the topmost level, the first two letters of the base 64 encoded CAS hash are used to create a subdirectory in the `chunk_cache` (keys that share these first two letters are grouped here). The inner levels are comprised of subdirectories with the full key as the directory name. At the base are the cache items which are ranges of blocks that contain the cached chunks. ```bash ├─ xet │ ├─ chunk_cache │ │ ├─ A1 │ │ │ ├─ A1GerURLUcISVivdseeoY1PnYifYkOaCCJ7V5Q9fjgxkZWZhdWx0 │ │ │ │ ├─ AAAAAAEAAAA5DQAAAAAAAIhRLjDI3SS5jYs4ysNKZiJy9XFI8CN7Ww0UyEA9KPD9 │ │ │ │ ├─ AQAAAAIAAABzngAAAAAAAPNqPjd5Zby5aBvabF7Z1itCx0ryMwoCnuQcDwq79jlB ``` When requesting a file, the first thing `hf_xet` does is communicate with Xet storage’s content addressed store (CAS) for reconstruction information. The reconstruction information contains information about the CAS keys required to download the file in its entirety. Before executing the requests for the CAS keys, the `chunk_cache` is consulted. If a key in the cache matches a CAS key, then there is no reason to issue a request for that content. `hf_xet` uses the chunks stored in the directory instead. As the `chunk_cache` is purely an optimization, not a guarantee, `hf_xet` utilizes a computationally efficient eviction policy. When the `chunk_cache` is full (see `Limits and Limitations` below), `hf_xet` implements a random eviction policy when selecting an eviction candidate. This significantly reduces the overhead of managing a robust caching system (e.g., LRU) while still providing most of the benefits of caching chunks. ### `shard_cache` This cache is used when uploading content to the Hub. The directory is flat, comprising only of shard files, each using an ID for the shard name. ```sh ├─ xet │ ├─ shard_cache │ │ ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb │ │ ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb │ │ ├─ ceeeb7ea4cf6c0a8d395a2cf9c08871211fbbd17b9b5dc1005811845307e6b8f.mdb │ │ ├─ e8535155b1b11ebd894c908e91a1e14e3461dddd1392695ddc90ae54a548d8b2.mdb ``` The `shard_cache` contains shards that are: - Locally generated and successfully uploaded to the CAS - Downloaded from CAS as part of the global deduplication algorithm Shards provide a mapping between files and chunks. During uploads, each file is chunked and the hash of the chunk is saved. Every shard in the cache is then consulted. If a shard contains a chunk hash that is present in the local file being uploaded, then that chunk can be discarded as it is already stored in CAS. All shards have an expiration date of 3-4 weeks from when they are downloaded. Shards that are expired are not loaded during upload and are deleted one week after expiration. ### `staging` When an upload terminates before the new content has been committed to the repository, you will need to resume the file transfer. However, it is possible that some chunks were successfully uploaded prior to the interruption. So that you do not have to restart from the beginning, the `staging` directory acts as a workspace during uploads, storing metadata for successfully uploaded chunks. The `staging` directory has the following shape: ``` ├─ xet │ ├─ staging │ │ ├─ shard-session │ │ │ ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb │ │ │ ├─ xorb-metadata │ │ │ │ ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb ``` As files are processed and chunks successfully uploaded, their metadata is stored in `xorb-metadata` as a shard. Upon resuming an upload session, each file is processed again and the shards in this directory are consulted. Any content that was successfully uploaded is skipped, and any new content is uploaded (and its metadata saved). Meanwhile, `shard-session` stores file and chunk information for processed files. On successful completion of an upload, the content from these shards is moved to the more persistent `shard-cache`. ### Limits and Limitations The `chunk_cache` is limited to 10GB in size while the `shard_cache` has a soft limit of 4GB. By design, both caches are without high-level APIs, although their size is configurable through the `HF_XET_CHUNK_CACHE_SIZE_BYTES` and `HF_XET_SHARD_CACHE_SIZE_LIMIT` environment variables. These caches are used primarily to facilitate the reconstruction (download) or upload of a file. To interact with the assets themselves, it’s recommended that you use the [`huggingface_hub` cache system APIs](https://huggingface.co/docs/huggingface_hub/guides/manage-cache). If you need to reclaim the space utilized by either cache or need to debug any potential cache-related issues, simply remove the `xet` cache entirely by running `rm -rf ~//xet` where `` is the location of your Hugging Face cache, typically `~/.cache/huggingface` Example full `xet`cache directory tree: ```sh ├─ xet │ ├─ chunk_cache │ │ ├─ L1 │ │ │ ├─ L1GerURLUcISVivdseeoY1PnYifYkOaCCJ7V5Q9fjgxkZWZhdWx0 │ │ │ │ ├─ AAAAAAEAAAA5DQAAAAAAAIhRLjDI3SS5jYs4ysNKZiJy9XFI8CN7Ww0UyEA9KPD9 │ │ │ │ ├─ AQAAAAIAAABzngAAAAAAAPNqPjd5Zby5aBvabF7Z1itCx0ryMwoCnuQcDwq79jlB │ ├─ shard_cache │ │ ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb │ │ ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb │ │ ├─ ceeeb7ea4cf6c0a8d395a2cf9c08871211fbbd17b9b5dc1005811845307e6b8f.mdb │ │ ├─ e8535155b1b11ebd894c908e91a1e14e3461dddd1392695ddc90ae54a548d8b2.mdb │ ├─ staging │ │ ├─ shard-session │ │ │ ├─ 906ee184dc1cd0615164a89ed64e8147b3fdccd1163d80d794c66814b3b09992.mdb │ │ │ ├─ xorb-metadata │ │ │ │ ├─ 1fe4ffd5cf0c3375f1ef9aec5016cf773ccc5ca294293d3f92d92771dacfc15d.mdb ``` To learn more about Xet Storage, see this [section](https://huggingface.co/docs/hub/xet/index). ## Caching assets In addition to caching files from the Hub, downstream libraries often requires to cache other files related to HF but not handled directly by `huggingface_hub` (example: file downloaded from GitHub, preprocessed data, logs,...). In order to cache those files, called `assets`, one can use [`cached_assets_path`]. This small helper generates paths in the HF cache in a unified way based on the name of the library requesting it and optionally on a namespace and a subfolder name. The goal is to let every downstream libraries manage its assets its own way (e.g. no rule on the structure) as long as it stays in the right assets folder. Those libraries can then leverage tools from `huggingface_hub` to manage the cache, in particular scanning and deleting parts of the assets from a CLI command. ```py from huggingface_hub import cached_assets_path assets_path = cached_assets_path(library_name="datasets", namespace="SQuAD", subfolder="download") something_path = assets_path / "something.json" # Do anything you like in your assets folder ! ``` > [!TIP] > [`cached_assets_path`] is the recommended way to store assets but is not mandatory. If > your library already uses its own cache, feel free to use it! ### Assets in practice In practice, your assets cache should look like the following tree: ```text assets/ └── datasets/ │ ├── SQuAD/ │ │ ├── downloaded/ │ │ ├── extracted/ │ │ └── processed/ │ ├── Helsinki-NLP--tatoeba_mt/ │ ├── downloaded/ │ ├── extracted/ │ └── processed/ └── transformers/ ├── default/ │ ├── something/ ├── bert-base-cased/ │ ├── default/ │ └── training/ hub/ └── models--julien-c--EsperBERTo-small/ ├── blobs/ │ ├── (...) │ ├── (...) ├── refs/ │ └── (...) └── [ 128] snapshots/ ├── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/ │ ├── (...) └── bbc77c8132af1cc5cf678da3f1ddf2de43606d48/ └── (...) ``` ## Manage your file-based cache ### Inspect your cache At the moment, cached files are never deleted from your local directory: when you download a new revision of a branch, previous files are kept in case you need them again. Therefore it can be useful to inspect your cache directory in order to know which repos and revisions are taking the most disk space. `huggingface_hub` provides helpers you can use from the `hf` CLI or from Python. **Inspect cache from the terminal** Run `hf cache ls` to explore what is stored locally. By default the command aggregates information by repository: ```text ➜ hf cache ls ID SIZE LAST_ACCESSED LAST_MODIFIED REFS ------------------------------------ ------- ------------- ------------- ------------------- dataset/glue 116.3K 4 days ago 4 days ago 2.4.0 main 1.17.0 dataset/google/fleurs 64.9M 1 week ago 1 week ago main refs/pr/1 model/Jean-Baptiste/camembert-ner 441.0M 2 weeks ago 16 hours ago main model/bert-base-cased 1.9G 1 week ago 2 years ago model/t5-base 10.1K 3 months ago 3 months ago main model/t5-small 970.7M 3 days ago 3 days ago main refs/pr/1 Found 6 repo(s) for a total of 12 revision(s) and 3.4G on disk. ``` Add `--revisions` to list every cached snapshot and chain filters to focus on what matters. Filters understand human-friendly sizes and durations, so expressions such as `size>1GB` or `accessed>30d` work out of the box: ```text ➜ hf cache ls --revisions --filter "size>1GB" --filter "accessed>30d" ID REVISION SIZE LAST_MODIFIED REFS ------------------------------------ ------------------ ------- ------------- ------------------- model/bert-base-cased 6d1d7a1a2a6cf4c2 1.9G 2 years ago model/t5-small 1c610f6b3f5e7d8a 1.1G 3 months ago main Found 2 repo(s) for a total of 2 revision(s) and 3.0G on disk. ``` Need machine-friendly output? Use `--format json` to get structured objects or `--format csv` for spreadsheets. Alternatively `--quiet` prints only identifiers (one per line) so you can pipe them into other tooling. Use `--sort` to order entries by `accessed`, `modified`, `name`, or `size` (append `:asc` or `:desc` to control order), and `--limit` to restrict results to the top N entries. Combine these options with `--cache-dir` when you need to inspect a cache stored outside of `HF_HOME`. **Filter with common shell tools** Tabular output means you can keep using the tooling you already know. For instance, the snippet below finds every cached revision related to `t5-small`: ```text ➜ eval "hf cache ls --revisions" | grep "t5-small" model/t5-small 1c610f6b3f5e7d8a 1.1G 3 months ago main model/t5-small 8f3ad1c90fed7a62 820.1M 2 weeks ago refs/pr/1 ``` **Inspect cache from Python** For a more advanced usage, use [`scan_cache_dir`] which is the python utility called by the CLI tool. You can use it to get a detailed report structured around 4 dataclasses: - [`HFCacheInfo`]: complete report returned by [`scan_cache_dir`] - [`CachedRepoInfo`]: information about a cached repo - [`CachedRevisionInfo`]: information about a cached revision (e.g. "snapshot") inside a repo - [`CachedFileInfo`]: information about a cached file in a snapshot Here is a simple usage example. See reference for details. ```py >>> from huggingface_hub import scan_cache_dir >>> hf_cache_info = scan_cache_dir() HFCacheInfo( size_on_disk=3398085269, repos=frozenset({ CachedRepoInfo( repo_id='t5-small', repo_type='model', repo_path=PosixPath(...), size_on_disk=970726914, nb_files=11, last_accessed=1662971707.3567169, last_modified=1662971107.3567169, revisions=frozenset({ CachedRevisionInfo( commit_hash='d78aea13fa7ecd06c29e3e46195d6341255065d5', size_on_disk=970726339, snapshot_path=PosixPath(...), # No `last_accessed` as blobs are shared among revisions last_modified=1662971107.3567169, files=frozenset({ CachedFileInfo( file_name='config.json', size_on_disk=1197 file_path=PosixPath(...), blob_path=PosixPath(...), blob_last_accessed=1662971707.3567169, blob_last_modified=1662971107.3567169, ), CachedFileInfo(...), ... }), ), CachedRevisionInfo(...), ... }), ), CachedRepoInfo(...), ... }), warnings=[ CorruptedCacheException("Snapshots dir doesn't exist in cached repo: ..."), CorruptedCacheException(...), ... ], ) ``` ### Verify your cache `huggingface_hub` can verify that your cached files match the checksums on the Hub. Use `hf cache verify` CLI to validate file consistency for a specific revision of a specific repository: ```bash >>> hf cache verify meta-llama/Llama-3.2-1B-Instruct ✅ Verified 13 file(s) for 'meta-llama/Llama-3.2-1B-Instruct' (model) in ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct/snapshots/9213176726f574b556790deb65791e0c5aa438b6 All checksums match. ``` Verify a specific cached revision: ```bash >>> hf cache verify meta-llama/Llama-3.1-8B-Instruct --revision 0e9e39f249a16976918f6564b8830bc894c89659 ``` > [!TIP] > Check the [`hf cache verify` CLI reference](../package_reference/cli#hf-cache-verify) for more details about the usage and a complete list of options. ### Clean your cache Scanning your cache is interesting but what you really want to do next is usually to delete some portions to free up some space on your drive. This is possible using the `hf cache rm` and `hf cache prune` CLI commands. One can also programmatically use the [`~HFCacheInfo.delete_revisions`] helper from the [`HFCacheInfo`] object returned when scanning the cache. **Delete strategy** To delete some cache, you need to pass a list of revisions to delete. The tool will define a strategy to free up the space based on this list. It returns a [`DeleteCacheStrategy`] object that describes which files and folders will be deleted. The [`DeleteCacheStrategy`] allows give you how much space is expected to be freed. Once you agree with the deletion, you must execute it to make the deletion effective. In order to avoid discrepancies, you cannot edit a strategy object manually. The strategy to delete revisions is the following: - the `snapshot` folder containing the revision symlinks is deleted. - blobs files that are targeted only by revisions to be deleted are deleted as well. - if a revision is linked to 1 or more `refs`, references are deleted. - if all revisions from a repo are deleted, the entire cached repository is deleted. > [!TIP] > Revision hashes are unique across all repositories. `hf cache rm` therefore accepts either > a repo identifier (for example `model/bert-base-uncased`) or a bare revision hash; when > passing a hash you don't need to specify the repo separately. > [!WARNING] > If a revision is not found in the cache, it will be silently ignored. Besides, if a file > or folder cannot be found while trying to delete it, a warning will be logged but no > error is thrown. The deletion continues for other paths contained in the > [`DeleteCacheStrategy`] object. **Clean cache from the terminal** Use `hf cache rm` to permanently delete repositories or revisions from your cache. Pass one or more repo identifiers (for example `model/bert-base-uncased`) or revision hashes: ```text ➜ hf cache rm model/bert-base-cased About to delete 1 repo(s) totalling 1.9G. - model/bert-base-cased (entire repo) Proceed with deletion? [y/N]: y Deleted 1 repo(s) and 1 revision(s); freed 1.9G. ``` You can also use `hf cache rm` in combination with `hf cache ls --quiet` to bulk-delete entries identified by a filter: ```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) Delete repo: ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct Delete repo: ~/.cache/huggingface/hub/models--hexgrad--Kokoro-82M Cache deletion done. Saved 5.31G. Deleted 2 repo(s) and 2 revision(s); freed 5.31G. ``` Mix repositories and revisions in the same call. Add `--dry-run` to preview the impact, or `--yes` to skip the confirmation prompt when scripting: ```text ➜ 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. ``` When working outside the default cache location, pair the command with `--cache-dir PATH`. To clean up detached snapshots in bulk, run `hf cache prune`. It automatically selects revisions that are no longer referenced by a branch or tag: ```text ➜ hf cache prune About to delete 3 unreferenced revision(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); freed 2.4G. ``` Both commands support `--dry-run`, `--yes`, and `--cache-dir` so you can preview, automate, and target alternate cache directories as needed. **Clean cache from Python** For more flexibility, you can also use the [`~HFCacheInfo.delete_revisions`] method programmatically. Here is a simple example. See reference for details. ```py >>> from huggingface_hub import scan_cache_dir >>> delete_strategy = scan_cache_dir().delete_revisions( ... "81fd1d6e7847c99f5862c9fb81387956d99ec7aa" ... "e2983b237dccf3ab4937c97fa717319a9ca1a96d", ... "6c0e6080953db56375760c0471a8c5f2929baf11", ... ) >>> print("Will free " + delete_strategy.expected_freed_size_str) Will free 8.6G >>> delete_strategy.execute() Cache deletion done. Saved 8.6G. ``` huggingface_hub-1.1.5/docs/source/en/guides/manage-spaces.md000066400000000000000000000303551510763414300237750ustar00rootroot00000000000000 # Manage your Space In this guide, we will see how to manage your Space runtime ([secrets](https://huggingface.co/docs/hub/spaces-overview#managing-secrets), [hardware](https://huggingface.co/docs/hub/spaces-gpus), and [storage](https://huggingface.co/docs/hub/spaces-storage#persistent-storage)) using `huggingface_hub`. ## A simple example: configure secrets and hardware. Here is an end-to-end example to create and set up a Space on the Hub. **1. Create a Space on the Hub.** ```py >>> from huggingface_hub import HfApi >>> repo_id = "Wauplin/my-cool-training-space" >>> api = HfApi() # For example with a Gradio SDK >>> api.create_repo(repo_id=repo_id, repo_type="space", space_sdk="gradio") ``` **1. (bis) Duplicate a Space.** This can prove useful if you want to build up from an existing Space instead of starting from scratch. It is also useful is you want control over the configuration/settings of a public Space. See [`duplicate_space`] for more details. ```py >>> api.duplicate_space("multimodalart/dreambooth-training") ``` **2. Upload your code using your preferred solution.** Here is an example to upload the local folder `src/` from your machine to your Space: ```py >>> api.upload_folder(repo_id=repo_id, repo_type="space", folder_path="src/") ``` At this step, your app should already be running on the Hub for free ! However, you might want to configure it further with secrets and upgraded hardware. **3. Configure secrets and variables** Your Space might require some secret keys, token or variables to work. See [docs](https://huggingface.co/docs/hub/spaces-overview#managing-secrets) for more details. For example, an HF token to upload an image dataset to the Hub once generated from your Space. ```py >>> api.add_space_secret(repo_id=repo_id, key="HF_TOKEN", value="hf_api_***") >>> api.add_space_variable(repo_id=repo_id, key="MODEL_REPO_ID", value="user/repo") ``` Secrets and variables can be deleted as well: ```py >>> api.delete_space_secret(repo_id=repo_id, key="HF_TOKEN") >>> api.delete_space_variable(repo_id=repo_id, key="MODEL_REPO_ID") ``` > [!TIP] > From within your Space, secrets are available as environment variables (or > Streamlit Secrets Management if using Streamlit). No need to fetch them via the API! > [!WARNING] > Any change in your Space configuration (secrets or hardware) will trigger a restart of your app. **Bonus: set secrets and variables when creating or duplicating the Space!** Secrets and variables can be set when creating or duplicating a space: ```py >>> api.create_repo( ... repo_id=repo_id, ... repo_type="space", ... space_sdk="gradio", ... space_secrets=[{"key"="HF_TOKEN", "value"="hf_api_***"}, ...], ... space_variables=[{"key"="MODEL_REPO_ID", "value"="user/repo"}, ...], ... ) ``` ```py >>> api.duplicate_space( ... from_id=repo_id, ... secrets=[{"key"="HF_TOKEN", "value"="hf_api_***"}, ...], ... variables=[{"key"="MODEL_REPO_ID", "value"="user/repo"}, ...], ... ) ``` **4. Configure the hardware** By default, your Space will run on a CPU environment for free. You can upgrade the hardware to run it on GPUs. A payment card or a community grant is required to access upgrade your Space. See [docs](https://huggingface.co/docs/hub/spaces-gpus) for more details. ```py # Use `SpaceHardware` enum >>> from huggingface_hub import SpaceHardware >>> api.request_space_hardware(repo_id=repo_id, hardware=SpaceHardware.T4_MEDIUM) # Or simply pass a string value >>> api.request_space_hardware(repo_id=repo_id, hardware="t4-medium") ``` Hardware updates are not done immediately as your Space has to be reloaded on our servers. At any time, you can check on which hardware your Space is running to see if your request has been met. ```py >>> runtime = api.get_space_runtime(repo_id=repo_id) >>> runtime.stage "RUNNING_BUILDING" >>> runtime.hardware "cpu-basic" >>> runtime.requested_hardware "t4-medium" ``` You now have a Space fully configured. Make sure to downgrade your Space back to "cpu-classic" when you are done using it. **Bonus: request hardware when creating or duplicating the Space!** Upgraded hardware will be automatically assigned to your Space once it's built. ```py >>> api.create_repo( ... repo_id=repo_id, ... repo_type="space", ... space_sdk="gradio" ... space_hardware="cpu-upgrade", ... space_storage="small", ... space_sleep_time="7200", # 2 hours in secs ... ) ``` ```py >>> api.duplicate_space( ... from_id=repo_id, ... hardware="cpu-upgrade", ... storage="small", ... sleep_time="7200", # 2 hours in secs ... ) ``` **5. Pause and restart your Space** By default if your Space is running on an upgraded hardware, it will never be stopped. However to avoid getting billed, you might want to pause it when you are not using it. This is possible using [`pause_space`]. A paused Space will be inactive until the owner of the Space restarts it, either with the UI or via API using [`restart_space`]. For more details about paused mode, please refer to [this section](https://huggingface.co/docs/hub/spaces-gpus#pause) ```py # Pause your Space to avoid getting billed >>> api.pause_space(repo_id=repo_id) # (...) # Restart it when you need it >>> api.restart_space(repo_id=repo_id) ``` Another possibility is to set a timeout for your Space. If your Space is inactive for more than the timeout duration, it will go to sleep. Any visitor landing on your Space will start it back up. You can set a timeout using [`set_space_sleep_time`]. For more details about sleeping mode, please refer to [this section](https://huggingface.co/docs/hub/spaces-gpus#sleep-time). ```py # Put your Space to sleep after 1h of inactivity >>> api.set_space_sleep_time(repo_id=repo_id, sleep_time=3600) ``` Note: if you are using a 'cpu-basic' hardware, you cannot configure a custom sleep time. Your Space will automatically be paused after 48h of inactivity. **Bonus: set a sleep time while requesting hardware** Upgraded hardware will be automatically assigned to your Space once it's built. ```py >>> api.request_space_hardware(repo_id=repo_id, hardware=SpaceHardware.T4_MEDIUM, sleep_time=3600) ``` **Bonus: set a sleep time when creating or duplicating the Space!** ```py >>> api.create_repo( ... repo_id=repo_id, ... repo_type="space", ... space_sdk="gradio" ... space_hardware="t4-medium", ... space_sleep_time="3600", ... ) ``` ```py >>> api.duplicate_space( ... from_id=repo_id, ... hardware="t4-medium", ... sleep_time="3600", ... ) ``` **6. Add persistent storage to your Space** You can choose the storage tier of your choice to access disk space that persists across restarts of your Space. This means you can read and write from disk like you would with a traditional hard drive. See [docs](https://huggingface.co/docs/hub/spaces-storage#persistent-storage) for more details. ```py >>> from huggingface_hub import SpaceStorage >>> api.request_space_storage(repo_id=repo_id, storage=SpaceStorage.LARGE) ``` You can also delete your storage, losing all the data permanently. ```py >>> api.delete_space_storage(repo_id=repo_id) ``` Note: You cannot decrease the storage tier of your space once it's been granted. To do so, you must delete the storage first then request the new desired tier. **Bonus: request storage when creating or duplicating the Space!** ```py >>> api.create_repo( ... repo_id=repo_id, ... repo_type="space", ... space_sdk="gradio" ... space_storage="large", ... ) ``` ```py >>> api.duplicate_space( ... from_id=repo_id, ... storage="large", ... ) ``` ## More advanced: temporarily upgrade your Space ! Spaces allow for a lot of different use cases. Sometimes, you might want to temporarily run a Space on a specific hardware, do something and then shut it down. In this section, we will explore how to benefit from Spaces to finetune a model on demand. This is only one way of solving this particular problem. It has to be taken as a suggestion and adapted to your use case. Let's assume we have a Space to finetune a model. It is a Gradio app that takes as input a model id and a dataset id. The workflow is as follows: 0. (Prompt the user for a model and a dataset) 1. Load the model from the Hub. 2. Load the dataset from the Hub. 3. Finetune the model on the dataset. 4. Upload the new model to the Hub. Step 3. requires a custom hardware but you don't want your Space to be running all the time on a paid GPU. A solution is to dynamically request hardware for the training and shut it down afterwards. Since requesting hardware restarts your Space, your app must somehow "remember" the current task it is performing. There are multiple ways of doing this. In this guide we will see one solution using a Dataset as "task scheduler". ### App skeleton Here is what your app would look like. On startup, check if a task is scheduled and if yes, run it on the correct hardware. Once done, set back hardware to the free-plan CPU and prompt the user for a new task. > [!WARNING] > Such a workflow does not support concurrent access as normal demos. > In particular, the interface will be disabled when training occurs. > It is preferable to set your repo as private to ensure you are the only user. ```py # Space will need your token to request hardware: set it as a Secret ! HF_TOKEN = os.environ.get("HF_TOKEN") # Space own repo_id TRAINING_SPACE_ID = "Wauplin/dreambooth-training" from huggingface_hub import HfApi, SpaceHardware api = HfApi(token=HF_TOKEN) # On Space startup, check if a task is scheduled. If yes, finetune the model. If not, # display an interface to request a new task. task = get_task() if task is None: # Start Gradio app def gradio_fn(task): # On user request, add task and request hardware add_task(task) api.request_space_hardware(repo_id=TRAINING_SPACE_ID, hardware=SpaceHardware.T4_MEDIUM) gr.Interface(fn=gradio_fn, ...).launch() else: runtime = api.get_space_runtime(repo_id=TRAINING_SPACE_ID) # Check if Space is loaded with a GPU. if runtime.hardware == SpaceHardware.T4_MEDIUM: # If yes, finetune base model on dataset ! train_and_upload(task) # Then, mark the task as "DONE" mark_as_done(task) # DO NOT FORGET: set back CPU hardware api.request_space_hardware(repo_id=TRAINING_SPACE_ID, hardware=SpaceHardware.CPU_BASIC) else: api.request_space_hardware(repo_id=TRAINING_SPACE_ID, hardware=SpaceHardware.T4_MEDIUM) ``` ### Task scheduler Scheduling tasks can be done in many ways. Here is an example how it could be done using a simple CSV stored as a Dataset. ```py # Dataset ID in which a `tasks.csv` file contains the tasks to perform. # Here is a basic example for `tasks.csv` containing inputs (base model and dataset) # and status (PENDING or DONE). # multimodalart/sd-fine-tunable,Wauplin/concept-1,DONE # multimodalart/sd-fine-tunable,Wauplin/concept-2,PENDING TASK_DATASET_ID = "Wauplin/dreambooth-task-scheduler" def _get_csv_file(): return hf_hub_download(repo_id=TASK_DATASET_ID, filename="tasks.csv", repo_type="dataset", token=HF_TOKEN) def get_task(): with open(_get_csv_file()) as csv_file: csv_reader = csv.reader(csv_file, delimiter=',') for row in csv_reader: if row[2] == "PENDING": return row[0], row[1] # model_id, dataset_id def add_task(task): model_id, dataset_id = task with open(_get_csv_file()) as csv_file: with open(csv_file, "r") as f: tasks = f.read() api.upload_file( repo_id=repo_id, repo_type=repo_type, path_in_repo="tasks.csv", # Quick and dirty way to add a task path_or_fileobj=(tasks + f"\n{model_id},{dataset_id},PENDING").encode() ) def mark_as_done(task): model_id, dataset_id = task with open(_get_csv_file()) as csv_file: with open(csv_file, "r") as f: tasks = f.read() api.upload_file( repo_id=repo_id, repo_type=repo_type, path_in_repo="tasks.csv", # Quick and dirty way to set the task as DONE path_or_fileobj=tasks.replace( f"{model_id},{dataset_id},PENDING", f"{model_id},{dataset_id},DONE" ).encode() ) ``` huggingface_hub-1.1.5/docs/source/en/guides/model-cards.md000066400000000000000000000241531510763414300234620ustar00rootroot00000000000000 # Create and share Model Cards The `huggingface_hub` library provides a Python interface to create, share, and update Model Cards. Visit [the dedicated documentation page](https://huggingface.co/docs/hub/models-cards) for a deeper view of what Model Cards on the Hub are, and how they work under the hood. ## Load a Model Card from the Hub To load an existing card from the Hub, you can use the [`ModelCard.load`] function. Here, we'll load the card from [`nateraw/vit-base-beans`](https://huggingface.co/nateraw/vit-base-beans). ```python from huggingface_hub import ModelCard card = ModelCard.load('nateraw/vit-base-beans') ``` This card has some helpful attributes that you may want to access/leverage: - `card.data`: Returns a [`ModelCardData`] instance with the model card's metadata. Call `.to_dict()` on this instance to get the representation as a dictionary. - `card.text`: Returns the text of the card, *excluding the metadata header*. - `card.content`: Returns the text content of the card, *including the metadata header*. ## Create Model Cards ### From Text To initialize a Model Card from text, just pass the text content of the card to the `ModelCard` on init. ```python content = """ --- language: en license: mit --- # My Model Card """ card = ModelCard(content) card.data.to_dict() == {'language': 'en', 'license': 'mit'} # True ``` Another way you might want to do this is with f-strings. In the following example, we: - Use [`ModelCardData.to_yaml`] to convert metadata we defined to YAML so we can use it to insert the YAML block in the model card. - Show how you might use a template variable via Python f-strings. ```python card_data = ModelCardData(language='en', license='mit', library='timm') example_template_var = 'nateraw' content = f""" --- { card_data.to_yaml() } --- # My Model Card This model created by [@{example_template_var}](https://github.com/{example_template_var}) """ card = ModelCard(content) print(card) ``` The above example would leave us with a card that looks like this: ``` --- language: en license: mit library: timm --- # My Model Card This model created by [@nateraw](https://github.com/nateraw) ``` ### From a Jinja Template If you have `Jinja2` installed, you can create Model Cards from a jinja template file. Let's see a basic example: ```python from pathlib import Path from huggingface_hub import ModelCard, ModelCardData # Define your jinja template template_text = """ --- {{ card_data }} --- # Model Card for MyCoolModel This model does this and that. This model was created by [@{{ author }}](https://hf.co/{{author}}). """.strip() # Write the template to a file Path('custom_template.md').write_text(template_text) # Define card metadata card_data = ModelCardData(language='en', license='mit', library_name='keras') # Create card from template, passing it any jinja template variables you want. # In our case, we'll pass author card = ModelCard.from_template(card_data, template_path='custom_template.md', author='nateraw') card.save('my_model_card_1.md') print(card) ``` The resulting card's markdown looks like this: ``` --- language: en license: mit library_name: keras --- # Model Card for MyCoolModel This model does this and that. This model was created by [@nateraw](https://hf.co/nateraw). ``` If you update any card.data, it'll reflect in the card itself. ``` card.data.library_name = 'timm' card.data.language = 'fr' card.data.license = 'apache-2.0' print(card) ``` Now, as you can see, the metadata header has been updated: ``` --- language: fr license: apache-2.0 library_name: timm --- # Model Card for MyCoolModel This model does this and that. This model was created by [@nateraw](https://hf.co/nateraw). ``` As you update the card data, you can validate the card is still valid against the Hub by calling [`ModelCard.validate`]. This ensures that the card passes any validation rules set up on the Hugging Face Hub. ### From the Default Template Instead of using your own template, you can also use the [default template](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md), which is a fully featured model card with tons of sections you may want to fill out. Under the hood, it uses [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/) to fill out a template file. > [!TIP] > Note that you will have to have Jinja2 installed to use `from_template`. You can do so with `pip install Jinja2`. ```python card_data = ModelCardData(language='en', license='mit', library_name='keras') card = ModelCard.from_template( card_data, model_id='my-cool-model', model_description="this model does this and that", developers="Nate Raw", repo="https://github.com/huggingface/huggingface_hub", ) card.save('my_model_card_2.md') print(card) ``` ## Share Model Cards If you're authenticated with the Hugging Face Hub (either by using `hf auth login` or [`login`]), you can push cards to the Hub by simply calling [`ModelCard.push_to_hub`]. Let's take a look at how to do that... First, we'll create a new repo called 'hf-hub-modelcards-pr-test' under the authenticated user's namespace: ```python from huggingface_hub import whoami, create_repo user = whoami()['name'] repo_id = f'{user}/hf-hub-modelcards-pr-test' url = create_repo(repo_id, exist_ok=True) ``` Then, we'll create a card from the default template (same as the one defined in the section above): ```python card_data = ModelCardData(language='en', license='mit', library_name='keras') card = ModelCard.from_template( card_data, model_id='my-cool-model', model_description="this model does this and that", developers="Nate Raw", repo="https://github.com/huggingface/huggingface_hub", ) ``` Finally, we'll push that up to the hub ```python card.push_to_hub(repo_id) ``` You can check out the resulting card [here](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/blob/main/README.md). If you instead wanted to push a card as a pull request, you can just say `create_pr=True` when calling `push_to_hub`: ```python card.push_to_hub(repo_id, create_pr=True) ``` A resulting PR created from this command can be seen [here](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/discussions/3). ## Update metadata In this section we will see what metadata are in repo cards and how to update them. `metadata` refers to a hash map (or key value) context that provides some high-level information about a model, dataset or Space. That information can include details such as the model's `pipeline type`, `model_id` or `model_description`. For more detail you can take a look to these guides: [Model Card](https://huggingface.co/docs/hub/model-cards#model-card-metadata), [Dataset Card](https://huggingface.co/docs/hub/datasets-cards#dataset-card-metadata) and [Spaces Settings](https://huggingface.co/docs/hub/spaces-settings#spaces-settings). Now lets see some examples on how to update those metadata. Let's start with a first example: ```python >>> from huggingface_hub import metadata_update >>> metadata_update("username/my-cool-model", {"pipeline_tag": "image-classification"}) ``` With these two lines of code you will update the metadata to set a new `pipeline_tag`. By default, you cannot update a key that is already existing on the card. If you want to do so, you must pass `overwrite=True` explicitly: ```python >>> from huggingface_hub import metadata_update >>> metadata_update("username/my-cool-model", {"pipeline_tag": "text-generation"}, overwrite=True) ``` It often happens that you want to suggest some changes to a repository on which you don't have write permission. You can do that by creating a PR on that repo which will allow the owners to review and merge your suggestions. ```python >>> from huggingface_hub import metadata_update >>> metadata_update("someone/model", {"pipeline_tag": "text-classification"}, create_pr=True) ``` ## Include Evaluation Results To include evaluation results in the metadata `model-index`, you can pass an [`EvalResult`] or a list of `EvalResult` with your associated evaluation results. Under the hood it'll create the `model-index` when you call `card.data.to_dict()`. For more information on how this works, you can check out [this section of the Hub docs](https://huggingface.co/docs/hub/models-cards#evaluation-results). > [!TIP] > Note that using this function requires you to include the `model_name` attribute in [`ModelCardData`]. ```python card_data = ModelCardData( language='en', license='mit', model_name='my-cool-model', eval_results = EvalResult( task_type='image-classification', dataset_type='beans', dataset_name='Beans', metric_type='accuracy', metric_value=0.7 ) ) card = ModelCard.from_template(card_data) print(card.data) ``` The resulting `card.data` should look like this: ``` language: en license: mit model-index: - name: my-cool-model results: - task: type: image-classification dataset: name: Beans type: beans metrics: - type: accuracy value: 0.7 ``` If you have more than one evaluation result you'd like to share, just pass a list of `EvalResult`: ```python card_data = ModelCardData( language='en', license='mit', model_name='my-cool-model', eval_results = [ EvalResult( task_type='image-classification', dataset_type='beans', dataset_name='Beans', metric_type='accuracy', metric_value=0.7 ), EvalResult( task_type='image-classification', dataset_type='beans', dataset_name='Beans', metric_type='f1', metric_value=0.65 ) ] ) card = ModelCard.from_template(card_data) card.data ``` Which should leave you with the following `card.data`: ``` language: en license: mit model-index: - name: my-cool-model results: - task: type: image-classification dataset: name: Beans type: beans metrics: - type: accuracy value: 0.7 - type: f1 value: 0.65 ``` huggingface_hub-1.1.5/docs/source/en/guides/overview.md000066400000000000000000000150141510763414300231320ustar00rootroot00000000000000 # How-to guides In this section, you will find practical guides to help you achieve a specific goal. Take a look at these guides to learn how to use huggingface_hub to solve real-world problems:
Repository

How to create a repository on the Hub? How to configure it? How to interact with it?

Download files

How do I download a file from the Hub? How do I download a repository?

Upload files

How to upload a file or a folder? How to make changes to an existing repository on the Hub?

Search

How to efficiently search through the 200k+ public models, datasets and spaces?

HfFileSystem

How to interact with the Hub through a convenient interface that mimics Python's file interface?

Inference

How to make predictions using Hugging Face Inference Providers?

Community Tab

How to interact with the Community tab (Discussions and Pull Requests)?

Collections

How to programmatically build collections?

Cache

How does the cache-system work? How to benefit from it?

Model Cards

How to create and share Model Cards?

Manage your Space

How to manage your Space hardware and configuration?

Integrate a library

What does it mean to integrate a library with the Hub? And how to do it?

Webhooks server

How to create a server to receive Webhooks and deploy it as a Space?

Jobs

How to run and manage compute Jobs on Hugging Face infrastructure and select the hardware?

huggingface_hub-1.1.5/docs/source/en/guides/repository.md000066400000000000000000000223671510763414300235140ustar00rootroot00000000000000 # Create and manage a repository The Hugging Face Hub is a collection of git repositories. [Git](https://git-scm.com/) is a widely used tool in software development to easily version projects when working collaboratively. This guide will show you how to interact with the repositories on the Hub, especially: - Create and delete a repository. - Manage branches and tags. - Rename your repository. - Update your repository visibility. - Manage a local copy of your repository. > [!WARNING] > If you are used to working with platforms such as GitLab/GitHub/Bitbucket, your first instinct > might be to use `git` CLI to clone your repo (`git clone`), commit changes (`git add, git commit`) and push them > (`git push`). This is valid when using the Hugging Face Hub. However, software engineering and machine learning do > not share the same requirements and workflows. Model repositories might maintain large model weight files for different > frameworks and tools, so cloning the repository can lead to you maintaining large local folders with massive sizes. As > a result, it may be more efficient to use our custom HTTP methods. You can read our [Git vs HTTP paradigm](../concepts/git_vs_http) > explanation page for more details. If you want to create and manage a repository on the Hub, your machine must be logged in. If you are not, please refer to [this section](../quick-start#authentication). In the rest of this guide, we will assume that your machine is logged in. ## Repo creation and deletion The first step is to know how to create and delete repositories. You can only manage repositories that you own (under your username namespace) or from organizations in which you have write permissions. ### Create a repository Create an empty repository with [`create_repo`] and give it a name with the `repo_id` parameter. The `repo_id` is your namespace followed by the repository name: `username_or_org/repo_name`. ```py >>> from huggingface_hub import create_repo >>> create_repo("lysandre/test-model") 'https://huggingface.co/lysandre/test-model' ``` Or via CLI: ```bash >>> hf repo create lysandre/test-model Successfully created lysandre/test-model on the Hub. Your repo is now available at https://huggingface.co/lysandre/test-model ``` By default, [`create_repo`] creates a model repository. But you can use the `repo_type` parameter to specify another repository type. For example, if you want to create a dataset repository: ```py >>> from huggingface_hub import create_repo >>> create_repo("lysandre/test-dataset", repo_type="dataset") 'https://huggingface.co/datasets/lysandre/test-dataset' ``` Or via CLI: ```bash >>> hf repo create lysandre/test-dataset --repo-type dataset ``` When you create a repository, you can set your repository visibility with the `private` parameter. ```py >>> from huggingface_hub import create_repo >>> create_repo("lysandre/test-private", private=True) ``` Or via CLI: ```bash >>> hf repo create lysandre/test-private --private ``` If you want to change the repository visibility at a later time, you can use the [`update_repo_settings`] function. > [!TIP] > If you are part of an organization with an Enterprise plan, you can create a repo in a specific resource group by passing `resource_group_id` as parameter to [`create_repo`]. Resource groups are a security feature to control which members from your org can access a given resource. You can get the resource group ID by copying it from your org settings page url on the Hub (e.g. `"https://huggingface.co/organizations/huggingface/settings/resource-groups/66670e5163145ca562cb1988"` => `"66670e5163145ca562cb1988"`). For more details about resource group, check out this [guide](https://huggingface.co/docs/hub/en/security-resource-groups). ### Delete a repository Delete a repository with [`delete_repo`]. Make sure you want to delete a repository because this is an irreversible process! Specify the `repo_id` of the repository you want to delete: ```py >>> delete_repo(repo_id="lysandre/my-corrupted-dataset", repo_type="dataset") ``` Or via CLI: ```bash >>> hf repo delete lysandre/my-corrupted-dataset --repo-type dataset ``` ### Duplicate a repository (only for Spaces) In some cases, you want to copy someone else's repo to adapt it to your use case. This is possible for Spaces using the [`duplicate_space`] method. It will duplicate the whole repository. You will still need to configure your own settings (hardware, sleep-time, storage, variables and secrets). Check out our [Manage your Space](./manage-spaces) guide for more details. ```py >>> from huggingface_hub import duplicate_space >>> duplicate_space("multimodalart/dreambooth-training", private=False) RepoUrl('https://huggingface.co/spaces/nateraw/dreambooth-training',...) ``` ## Upload and download files Now that you have created your repository, you are interested in pushing changes to it and downloading files from it. These 2 topics deserve their own guides. Please refer to the [upload](./upload) and the [download](./download) guides to learn how to use your repository. ## Branches and tags Git repositories often make use of branches to store different versions of a same repository. Tags can also be used to flag a specific state of your repository, for example, when releasing a version. More generally, branches and tags are referred as [git references](https://git-scm.com/book/en/v2/Git-Internals-Git-References). ### Create branches and tags You can create new branch and tags using [`create_branch`] and [`create_tag`]: ```py >>> from huggingface_hub import create_branch, create_tag # Create a branch on a Space repo from `main` branch >>> create_branch("Matthijs/speecht5-tts-demo", repo_type="space", branch="handle-dog-speaker") # Create a tag on a Dataset repo from `v0.1-release` branch >>> create_tag("bigcode/the-stack", repo_type="dataset", revision="v0.1-release", tag="v0.1.1", tag_message="Bump release version.") ``` Or via CLI: ```bash >>> hf repo branch create Matthijs/speecht5-tts-demo handle-dog-speaker --repo-type space >>> hf repo tag create bigcode/the-stack v0.1.1 --repo-type dataset --revision v0.1-release -m "Bump release version." ``` You can use the [`delete_branch`] and [`delete_tag`] functions in the same way to delete a branch or a tag, or `hf repo branch delete` and `hf repo tag delete` respectively in CLI. ### List all branches and tags You can also list the existing git refs from a repository using [`list_repo_refs`]: ```py >>> from huggingface_hub import list_repo_refs >>> list_repo_refs("bigcode/the-stack", repo_type="dataset") GitRefs( branches=[ GitRefInfo(name='main', ref='refs/heads/main', target_commit='18edc1591d9ce72aa82f56c4431b3c969b210ae3'), GitRefInfo(name='v1.1.a1', ref='refs/heads/v1.1.a1', target_commit='f9826b862d1567f3822d3d25649b0d6d22ace714') ], converts=[], tags=[ GitRefInfo(name='v1.0', ref='refs/tags/v1.0', target_commit='c37a8cd1e382064d8aced5e05543c5f7753834da') ] ) ``` ## Change repository settings Repositories come with some settings that you can configure. Most of the time, you will want to do that manually in the repo settings page in your browser. You must have write access to a repo to configure it (either own it or being part of an organization). In this section, we will see the settings that you can also configure programmatically using `huggingface_hub`. Some settings are specific to Spaces (hardware, environment variables,...). To configure those, please refer to our [Manage your Spaces](../guides/manage-spaces) guide. ### Update visibility A repository can be public or private. A private repository is only visible to you or members of the organization in which the repository is located. Change a repository to private as shown in the following: ```py >>> from huggingface_hub import update_repo_settings >>> update_repo_settings(repo_id=repo_id, private=True) ``` Or via CLI: ```bash >>> hf repo settings lysandre/test-private --private true ``` ### Setup gated access To give more control over how repos are used, the Hub allows repo authors to enable **access requests** for their repos. User must agree to share their contact information (username and email address) with the repo authors to access the files when enabled. A repo with access requests enabled is called a **gated repo**. You can set a repo as gated using [`update_repo_settings`]: ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.update_repo_settings(repo_id=repo_id, gated="auto") # Set automatic gating for a model ``` Or via CLI: ```bash >>> hf repo settings lysandre/test-private --gated auto ``` ### Rename your repository You can rename your repository on the Hub using [`move_repo`]. Using this method, you can also move the repo from a user to an organization. When doing so, there are a [few limitations](https://hf.co/docs/hub/repositories-settings#renaming-or-transferring-a-repo) that you should be aware of. For example, you can't transfer your repo to another user. ```py >>> from huggingface_hub import move_repo >>> move_repo(from_id="Wauplin/cool-model", to_id="huggingface/cool-model") ``` Or via CLI: ```bash >>> hf repo move Wauplin/cool-model huggingface/cool-model ``` huggingface_hub-1.1.5/docs/source/en/guides/search.md000066400000000000000000000036341510763414300225360ustar00rootroot00000000000000 # Search the Hub In this tutorial, you will learn how to search models, datasets and spaces on the Hub using `huggingface_hub`. ## How to list repositories ? `huggingface_hub` library includes an HTTP client [`HfApi`] to interact with the Hub. Among other things, it can list models, datasets and spaces stored on the Hub: ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> models = api.list_models() ``` The output of [`list_models`] is an iterator over the models stored on the Hub. Similarly, you can use [`list_datasets`] to list datasets and [`list_spaces`] to list Spaces. ## How to filter repositories ? Listing repositories is great but now you might want to filter your search. The list helpers have several attributes like: - `filter` - `author` - `search` - ... Let's see an example to get all models on the Hub that does image classification, have been trained on the imagenet dataset and that runs with PyTorch. ```py models = hf_api.list_models(filter=["image-classification", "pytorch", "imagenet"]) ``` While filtering, you can also sort the models and take only the top results. For example, the following example fetches the top 5 most downloaded datasets on the Hub: ```py >>> list(list_datasets(sort="downloads", direction=-1, limit=5)) [DatasetInfo( id='argilla/databricks-dolly-15k-curated-en', author='argilla', sha='4dcd1dedbe148307a833c931b21ca456a1fc4281', last_modified=datetime.datetime(2023, 10, 2, 12, 32, 53, tzinfo=datetime.timezone.utc), private=False, downloads=8889377, (...) ``` To explore available filters on the Hub, visit [models](https://huggingface.co/models) and [datasets](https://huggingface.co/datasets) pages in your browser, search for some parameters and look at the values in the URL. huggingface_hub-1.1.5/docs/source/en/guides/upload.md000066400000000000000000000663121510763414300225570ustar00rootroot00000000000000 # Upload files to the Hub Sharing your files and work is an important aspect of the Hub. The `huggingface_hub` offers several options for uploading your files to the Hub. You can use these functions independently or integrate them into your library, making it more convenient for your users to interact with the Hub. Whenever you want to upload files to the Hub, you need to log in to your Hugging Face account. For more details about authentication, check out [this section](../quick-start#authentication). ## Upload a file Once you've created a repository with [`create_repo`], you can upload a file to your repository using [`upload_file`]. Specify the path of the file to upload, where you want to upload the file to in the repository, and the name of the repository you want to add the file to. Depending on your repository type, you can optionally set the repository type as a `dataset`, `model`, or `space`. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.upload_file( ... path_or_fileobj="/path/to/local/folder/README.md", ... path_in_repo="README.md", ... repo_id="username/test-dataset", ... repo_type="dataset", ... ) ``` ## Upload a folder Use the [`upload_folder`] function to upload a local folder to an existing repository. Specify the path of the local folder to upload, where you want to upload the folder to in the repository, and the name of the repository you want to add the folder to. Depending on your repository type, you can optionally set the repository type as a `dataset`, `model`, or `space`. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() # Upload all the content from the local folder to your remote Space. # By default, files are uploaded at the root of the repo >>> api.upload_folder( ... folder_path="/path/to/local/space", ... repo_id="username/my-cool-space", ... repo_type="space", ... ) ``` By default, the `.gitignore` file will be taken into account to know which files should be committed or not. By default we check if a `.gitignore` file is present in a commit, and if not, we check if it exists on the Hub. Please be aware that only a `.gitignore` file present at the root of the directory will be used. We do not check for `.gitignore` files in subdirectories. If you don't want to use an hardcoded `.gitignore` file, you can use the `allow_patterns` and `ignore_patterns` arguments to filter which files to upload. These parameters accept either a single pattern or a list of patterns. Patterns are Standard Wildcards (globbing patterns) as documented [here](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). If both `allow_patterns` and `ignore_patterns` are provided, both constraints apply. Beside the `.gitignore` file and allow/ignore patterns, any `.git/` folder present in any subdirectory will be ignored. ```py >>> api.upload_folder( ... folder_path="/path/to/local/folder", ... path_in_repo="my-dataset/train", # Upload to a specific folder ... repo_id="username/test-dataset", ... repo_type="dataset", ... ignore_patterns="**/logs/*.txt", # Ignore all text logs ... ) ``` You can also use the `delete_patterns` argument to specify files you want to delete from the repo in the same commit. This can prove useful if you want to clean a remote folder before pushing files in it and you don't know which files already exists. The example below uploads the local `./logs` folder to the remote `/experiment/logs/` folder. Only txt files are uploaded but before that, all previous logs on the repo on deleted. All of this in a single commit. ```py >>> api.upload_folder( ... folder_path="/path/to/local/folder/logs", ... repo_id="username/trained-model", ... path_in_repo="experiment/logs/", ... allow_patterns="*.txt", # Upload all local text files ... delete_patterns="*.txt", # Delete all remote text files before ... ) ``` ## Upload from the CLI You can use the `hf upload` command from the terminal to directly upload files to the Hub. Internally it uses the same [`upload_file`] and [`upload_folder`] helpers described above. You can either upload a single file or an entire folder: ```bash # Usage: hf upload [repo_id] [local_path] [path_in_repo] >>> hf upload Wauplin/my-cool-model ./models/model.safetensors model.safetensors https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors >>> hf upload Wauplin/my-cool-model ./models . https://huggingface.co/Wauplin/my-cool-model/tree/main ``` `local_path` and `path_in_repo` are optional and can be implicitly inferred. If `local_path` is not set, the tool will check if a local folder or file has the same name as the `repo_id`. If that's the case, its content will be uploaded. Otherwise, an exception is raised asking the user to explicitly set `local_path`. In any case, if `path_in_repo` is not set, files are uploaded at the root of the repo. For more details about the CLI upload command, please refer to the [CLI guide](./cli#hf-upload). ## Upload a large folder In most cases, the [`upload_folder`] method and `hf upload` command should be the go-to solutions to upload files to the Hub. They ensure a single commit will be made, handle a lot of use cases, and fail explicitly when something wrong happens. However, when dealing with a large amount of data, you will usually prefer a resilient process even if it leads to more commits or requires more CPU usage. The [`upload_large_folder`] method has been implemented in that spirit: - it is resumable: the upload process is split into many small tasks (hashing files, pre-uploading them, and committing them). Each time a task is completed, the result is cached locally in a `./cache/huggingface` folder inside the folder you are trying to upload. By doing so, restarting the process after an interruption will resume all completed tasks. - it is multi-threaded: hashing large files and pre-uploading them benefits a lot from multithreading if your machine allows it. - it is resilient to errors: a high-level retry-mechanism has been added to retry each independent task indefinitely until it passes (no matter if it's a OSError, ConnectionError, PermissionError, etc.). This mechanism is double-edged. If transient errors happen, the process will continue and retry. If permanent errors happen (e.g. permission denied), it will retry indefinitely without solving the root cause. If you want more technical details about how `upload_large_folder` is implemented under the hood, please have a look to the [`upload_large_folder`] package reference. Here is how to use [`upload_large_folder`] in a script. The method signature is very similar to [`upload_folder`]: ```py >>> api.upload_large_folder( ... repo_id="HuggingFaceM4/Docmatix", ... repo_type="dataset", ... folder_path="/path/to/local/docmatix", ... ) ``` You will see the following output in your terminal: ``` Repo created: https://huggingface.co/datasets/HuggingFaceM4/Docmatix Found 5 candidate files to upload Recovering from metadata files: 100%|█████████████████████████████████████| 5/5 [00:00<00:00, 542.66it/s] ---------- 2024-07-22 17:23:17 (0:00:00) ---------- Files: hashed 5/5 (5.0G/5.0G) | pre-uploaded: 0/5 (0.0/5.0G) | committed: 0/5 (0.0/5.0G) | ignored: 0 Workers: hashing: 0 | get upload mode: 0 | pre-uploading: 5 | committing: 0 | waiting: 11 --------------------------------------------------- ``` First, the repo is created if it didn't exist before. Then, the local folder is scanned for files to upload. For each file, we try to recover metadata information (from a previously interrupted upload). From there, it is able to launch workers and print an update status every 1 minute. Here, we can see that 5 files have already been hashed but not pre-uploaded. 5 workers are pre-uploading files while the 11 others are waiting for a task. A command line is also provided. You can define the number of workers and the level of verbosity in the terminal: ```sh hf upload-large-folder HuggingFaceM4/Docmatix --repo-type=dataset /path/to/local/docmatix --num-workers=16 ``` > [!TIP] > For large uploads, you have to set `repo_type="model"` or `--repo-type=model` explicitly. Usually, this information is implicit in all other `HfApi` methods. This is to avoid having data uploaded to a repository with a wrong type. If that's the case, you'll have to re-upload everything. > [!WARNING] > While being much more robust to upload large folders, `upload_large_folder` is more limited than [`upload_folder`] feature-wise. In practice: > - you cannot set a custom `path_in_repo`. If you want to upload to a subfolder, you need to set the proper structure locally. > - you cannot set a custom `commit_message` and `commit_description` since multiple commits are created. > - you cannot delete from the repo while uploading. Please make a separate commit first. > - you cannot create a PR directly. Please create a PR first (from the UI or using [`create_pull_request`]) and then commit to it by passing `revision`. ### Tips and tricks for large uploads There are some limitations to be aware of when dealing with a large amount of data in your repo. Given the time it takes to stream the data, getting an upload/push to fail at the end of the process or encountering a degraded experience, be it on hf.co or when working locally, can be very annoying. Check out our [Repository limitations and recommendations](https://huggingface.co/docs/hub/repositories-recommendations) guide for best practices on how to structure your repositories on the Hub. Let's move on with some practical tips to make your upload process as smooth as possible. - **Start small**: We recommend starting with a small amount of data to test your upload script. It's easier to iterate on a script when failing takes only a little time. - **Expect failures**: Streaming large amounts of data is challenging. You don't know what can happen, but it's always best to consider that something will fail at least once -no matter if it's due to your machine, your connection, or our servers. For example, if you plan to upload a large number of files, it's best to keep track locally of which files you already uploaded before uploading the next batch. You are ensured that an LFS file that is already committed will never be re-uploaded twice but checking it client-side can still save some time. This is what [`upload_large_folder`] does for you. - **Use `hf_xet`**: this leverages the new storage backend for the Hub, is written in Rust, and is now available for everyone to use. In fact, `hf_xet` is already enabled by default when using `huggingface_hub`! For maximum performance, set [`HF_XET_HIGH_PERFORMANCE=1`](../package_reference/environment_variables.md#hf_xet_high_performance) as an environment variable. Be aware that when high performance mode is enabled, the tool will try to use all available bandwidth and CPU cores. ## Advanced features In most cases, you won't need more than [`upload_file`] and [`upload_folder`] to upload your files to the Hub. However, `huggingface_hub` has more advanced features to make things easier. Let's have a look at them! ### Faster Uploads Take advantage of faster uploads through `hf_xet`, the Python binding to the [`xet-core`](https://github.com/huggingface/xet-core) library that enables chunk-based deduplication for faster uploads and downloads. `hf_xet` integrates seamlessly with `huggingface_hub`, but uses the Rust `xet-core` library and Xet storage instead of LFS. `hf_xet` uses the Xet storage system, which breaks files down into immutable chunks, storing collections of these chunks (called blocks or xorbs) remotely and retrieving them to reassemble the file when requested. When uploading, after confirming the user is authorized to write to this repo, `hf_xet` will scan the files, breaking them down into their chunks and collecting those chunks into xorbs (and deduplicating across known chunks), and then will be upload these xorbs to the Xet content-addressable service (CAS), which will verify the integrity of the xorbs, register the xorb metadata along with the LFS SHA256 hash (to support lookup/download), and write the xorbs to remote storage. To enable it, simply install the latest version of `huggingface_hub`: ```bash pip install -U "huggingface_hub" ``` As of `huggingface_hub` 0.32.0, this will also install `hf_xet`. All other `huggingface_hub` APIs will continue to work without any modification. To learn more about the benefits of Xet storage and `hf_xet`, refer to this [section](https://huggingface.co/docs/hub/xet/index). **Cluster / Distributed Filesystem Upload Considerations** When uploading from a cluster, the files being uploaded often reside on a distributed or networked filesystem (NFS, EBS, Lustre, Fsx, etc). Xet storage will chunk those files and write them into blocks (also called xorbs) locally, and once the block is completed will upload them. For better performance when uploading from a distributed filesystem, make sure to set [`HF_XET_CACHE`](../package_reference/environment_variables#hfxetcache) to a directory that is on a local disk (ex. a local NVMe or SSD disk). The default location for the Xet cache is under `HF_HOME` at (`~/.cache/huggingface/xet`) and this being in the user's home directory is often also located on the distributed filesystem. ### Non-blocking uploads In some cases, you want to push data without blocking your main thread. This is particularly useful to upload logs and artifacts while continuing a training. To do so, you can use the `run_as_future` argument in both [`upload_file`] and [`upload_folder`]. This will return a [`concurrent.futures.Future`](https://docs.python.org/3/library/concurrent.futures.html#future-objects) object that you can use to check the status of the upload. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> future = api.upload_folder( # Upload in the background (non-blocking action) ... repo_id="username/my-model", ... folder_path="checkpoints-001", ... run_as_future=True, ... ) >>> future Future(...) >>> future.done() False >>> future.result() # Wait for the upload to complete (blocking action) ... ``` > [!TIP] > Background jobs are queued when using `run_as_future=True`. This means that you are guaranteed that the jobs will be > executed in the correct order. Even though background jobs are mostly useful to upload data/create commits, you can queue any method you like using [`run_as_future`]. For instance, you can use it to create a repo and then upload data to it in the background. The built-in `run_as_future` argument in upload methods is just an alias around it. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.run_as_future(api.create_repo, "username/my-model", exists_ok=True) Future(...) >>> api.upload_file( ... repo_id="username/my-model", ... path_in_repo="file.txt", ... path_or_fileobj=b"file content", ... run_as_future=True, ... ) Future(...) ``` ### Upload a folder by chunks [`upload_folder`] makes it easy to upload an entire folder to the Hub. However, for large folders (thousands of files or hundreds of GB), we recommend using [`upload_large_folder`], which splits the upload into multiple commits. See the [Upload a large folder](#upload-a-large-folder) section for more details. ### Scheduled uploads The Hugging Face Hub makes it easy to save and version data. However, there are some limitations when updating the same file thousands of times. For instance, you might want to save logs of a training process or user feedback on a deployed Space. In these cases, uploading the data as a dataset on the Hub makes sense, but it can be hard to do properly. The main reason is that you don't want to version every update of your data because it'll make the git repository unusable. The [`CommitScheduler`] class offers a solution to this problem. The idea is to run a background job that regularly pushes a local folder to the Hub. Let's assume you have a Gradio Space that takes as input some text and generates two translations of it. Then, the user can select their preferred translation. For each run, you want to save the input, output, and user preference to analyze the results. This is a perfect use case for [`CommitScheduler`]; you want to save data to the Hub (potentially millions of user feedback), but you don't _need_ to save in real-time each user's input. Instead, you can save the data locally in a JSON file and upload it every 10 minutes. For example: ```py >>> import json >>> import uuid >>> from pathlib import Path >>> import gradio as gr >>> from huggingface_hub import CommitScheduler # Define the file where to save the data. Use UUID to make sure not to overwrite existing data from a previous run. >>> feedback_file = Path("user_feedback/") / f"data_{uuid.uuid4()}.json" >>> feedback_folder = feedback_file.parent # Schedule regular uploads. Remote repo and local folder are created if they don't already exist. >>> scheduler = CommitScheduler( ... repo_id="report-translation-feedback", ... repo_type="dataset", ... folder_path=feedback_folder, ... path_in_repo="data", ... every=10, ... ) # Define the function that will be called when the user submits its feedback (to be called in Gradio) >>> def save_feedback(input_text:str, output_1: str, output_2:str, user_choice: int) -> None: ... """ ... Append input/outputs and user feedback to a JSON Lines file using a thread lock to avoid concurrent writes from different users. ... """ ... with scheduler.lock: ... with feedback_file.open("a") as f: ... f.write(json.dumps({"input": input_text, "output_1": output_1, "output_2": output_2, "user_choice": user_choice})) ... f.write("\n") # Start Gradio >>> with gr.Blocks() as demo: >>> ... # define Gradio demo + use `save_feedback` >>> demo.launch() ``` And that's it! User input/outputs and feedback will be available as a dataset on the Hub. By using a unique JSON file name, you are guaranteed you won't overwrite data from a previous run or data from another Spaces/replicas pushing concurrently to the same repository. For more details about the [`CommitScheduler`], here is what you need to know: - **append-only:** It is assumed that you will only add content to the folder. You must only append data to existing files or create new files. Deleting or overwriting a file might corrupt your repository. - **git history**: The scheduler will commit the folder every `every` minutes. To avoid polluting the git repository too much, it is recommended to set a minimal value of 5 minutes. Besides, the scheduler is designed to avoid empty commits. If no new content is detected in the folder, the scheduled commit is dropped. - **errors:** The scheduler run as background thread. It is started when you instantiate the class and never stops. In particular, if an error occurs during the upload (example: connection issue), the scheduler will silently ignore it and retry at the next scheduled commit. - **thread-safety:** In most cases it is safe to assume that you can write to a file without having to worry about a lock file. The scheduler will not crash or be corrupted if you write content to the folder while it's uploading. In practice, _it is possible_ that concurrency issues happen for heavy-loaded apps. In this case, we advice to use the `scheduler.lock` lock to ensure thread-safety. The lock is blocked only when the scheduler scans the folder for changes, not when it uploads data. You can safely assume that it will not affect the user experience on your Space. #### Space persistence demo Persisting data from a Space to a Dataset on the Hub is the main use case for [`CommitScheduler`]. Depending on the use case, you might want to structure your data differently. The structure has to be robust to concurrent users and restarts which often implies generating UUIDs. Besides robustness, you should upload data in a format readable by the 🤗 Datasets library for later reuse. We created a [Space](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) that demonstrates how to save several different data formats (you may need to adapt it for your own specific needs). #### Custom uploads [`CommitScheduler`] assumes your data is append-only and should be uploading "as is". However, you might want to customize the way data is uploaded. You can do that by creating a class inheriting from [`CommitScheduler`] and overwrite the `push_to_hub` method (feel free to overwrite it any way you want). You are guaranteed it will be called every `every` minutes in a background thread. You don't have to worry about concurrency and errors but you must be careful about other aspects, such as pushing empty commits or duplicated data. In the (simplified) example below, we overwrite `push_to_hub` to zip all PNG files in a single archive to avoid overloading the repo on the Hub: ```py class ZipScheduler(CommitScheduler): def push_to_hub(self): # 1. List PNG files png_files = list(self.folder_path.glob("*.png")) if len(png_files) == 0: return None # return early if nothing to commit # 2. Zip png files in a single archive with tempfile.TemporaryDirectory() as tmpdir: archive_path = Path(tmpdir) / "train.zip" with zipfile.ZipFile(archive_path, "w", zipfile.ZIP_DEFLATED) as zip: for png_file in png_files: zip.write(filename=png_file, arcname=png_file.name) # 3. Upload archive self.api.upload_file(..., path_or_fileobj=archive_path) # 4. Delete local png files to avoid re-uploading them later for png_file in png_files: png_file.unlink() ``` When you overwrite `push_to_hub`, you have access to the attributes of [`CommitScheduler`] and especially: - [`HfApi`] client: `api` - Folder parameters: `folder_path` and `path_in_repo` - Repo parameters: `repo_id`, `repo_type`, `revision` - The thread lock: `lock` > [!TIP] > For more examples of custom schedulers, check out our [demo Space](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) > containing different implementations depending on your use cases. ### create_commit The [`upload_file`] and [`upload_folder`] functions are high-level APIs that are generally convenient to use. We recommend trying these functions first if you don't need to work at a lower level. However, if you want to work at a commit-level, you can use the [`create_commit`] function directly. There are three types of operations supported by [`create_commit`]: - [`CommitOperationAdd`] uploads a file to the Hub. If the file already exists, the file contents are overwritten. This operation accepts two arguments: - `path_in_repo`: the repository path to upload a file to. - `path_or_fileobj`: either a path to a file on your filesystem or a file-like object. This is the content of the file to upload to the Hub. - [`CommitOperationDelete`] removes a file or a folder from a repository. This operation accepts `path_in_repo` as an argument. - [`CommitOperationCopy`] copies a file within a repository. This operation accepts three arguments: - `src_path_in_repo`: the repository path of the file to copy. - `path_in_repo`: the repository path where the file should be copied. - `src_revision`: optional - the revision of the file to copy if your want to copy a file from a different branch/revision. For example, if you want to upload two files and delete a file in a Hub repository: 1. Use the appropriate `CommitOperation` to add or delete a file and to delete a folder: ```py >>> from huggingface_hub import HfApi, CommitOperationAdd, CommitOperationDelete >>> api = HfApi() >>> operations = [ ... CommitOperationAdd(path_in_repo="LICENSE.md", path_or_fileobj="~/repo/LICENSE.md"), ... CommitOperationAdd(path_in_repo="weights.h5", path_or_fileobj="~/repo/weights-final.h5"), ... CommitOperationDelete(path_in_repo="old-weights.h5"), ... CommitOperationDelete(path_in_repo="logs/"), ... CommitOperationCopy(src_path_in_repo="image.png", path_in_repo="duplicate_image.png"), ... ] ``` 2. Pass your operations to [`create_commit`]: ```py >>> api.create_commit( ... repo_id="lysandre/test-model", ... operations=operations, ... commit_message="Upload my model weights and license", ... ) ``` In addition to [`upload_file`] and [`upload_folder`], the following functions also use [`create_commit`] under the hood: - [`delete_file`] deletes a single file from a repository on the Hub. - [`delete_folder`] deletes an entire folder from a repository on the Hub. - [`metadata_update`] updates a repository's metadata. For more detailed information, take a look at the [`HfApi`] reference. ### Preupload LFS files before commit In some cases, you might want to upload huge files to S3 **before** making the commit call. For example, if you are committing a dataset in several shards that are generated in-memory, you would need to upload the shards one by one to avoid an out-of-memory issue. A solution is to upload each shard as a separate commit on the repo. While being perfectly valid, this solution has the drawback of potentially messing the git history by generating tens of commits. To overcome this issue, you can upload your files one by one to S3 and then create a single commit at the end. This is possible using [`preupload_lfs_files`] in combination with [`create_commit`]. > [!WARNING] > This is a power-user method. Directly using [`upload_file`], [`upload_folder`] or [`create_commit`] instead of handling > the low-level logic of pre-uploading files is the way to go in the vast majority of cases. The main caveat of > [`preupload_lfs_files`] is that until the commit is actually made, the upload files are not accessible on the repo on > the Hub. If you have a question, feel free to ping us on our Discord or in a GitHub issue. Here is a simple example illustrating how to pre-upload files: ```py >>> from huggingface_hub import CommitOperationAdd, preupload_lfs_files, create_commit, create_repo >>> repo_id = create_repo("test_preupload").repo_id >>> operations = [] # List of all `CommitOperationAdd` objects that will be generated >>> for i in range(5): ... content = ... # generate binary content ... addition = CommitOperationAdd(path_in_repo=f"shard_{i}_of_5.bin", path_or_fileobj=content) ... preupload_lfs_files(repo_id, additions=[addition]) ... operations.append(addition) >>> # Create commit >>> create_commit(repo_id, operations=operations, commit_message="Commit all shards") ``` First, we create the [`CommitOperationAdd`] objects one by one. In a real-world example, those would contain the generated shards. Each file is uploaded before generating the next one. During the [`preupload_lfs_files`] step, **the `CommitOperationAdd` object is mutated**. You should only use it to pass it directly to [`create_commit`]. The main update of the object is that **the binary content is removed** from it, meaning that it will be garbage-collected if you don't store another reference to it. This is expected as we don't want to keep in memory the content that is already uploaded. Finally we create the commit by passing all the operations to [`create_commit`]. You can pass additional operations (add, delete or copy) that have not been processed yet and they will be handled correctly. huggingface_hub-1.1.5/docs/source/en/guides/webhooks.md000066400000000000000000000311701510763414300231060ustar00rootroot00000000000000 # Webhooks Webhooks are a foundation for MLOps-related features. They allow you to listen for new changes on specific repos or to all repos belonging to particular users/organizations you're interested in following. This guide will first explain how to manage webhooks programmatically. Then we'll see how to leverage `huggingface_hub` to create a server listening to webhooks and deploy it to a Space. This guide assumes you are familiar with the concept of webhooks on the Huggingface Hub. To learn more about webhooks themselves, you should read this [guide](https://huggingface.co/docs/hub/webhooks) first. ## Managing Webhooks `huggingface_hub` allows you to manage your webhooks programmatically. You can list your existing webhooks, create new ones, and update, enable, disable or delete them. This section guides you through the procedures using the Hugging Face Hub's API functions. ### Creating a Webhook To create a new webhook, use [`create_webhook`] and specify the URL where payloads should be sent, what events should be watched, and optionally set a domain and a secret for security. ```python from huggingface_hub import create_webhook # Example: Creating a webhook webhook = create_webhook( url="https://webhook.site/your-custom-url", watched=[{"type": "user", "name": "your-username"}, {"type": "org", "name": "your-org-name"}], domains=["repo", "discussion"], secret="your-secret" ) ``` A webhook can also trigger a Job to run on Hugging face infrastructure instead of sending the payload to an URL. In this case you need to pass the ID of a source Job. ```python from huggingface_hub import create_webhook # Example: Creating a webhook that triggers a Job webhook = create_webhook( job_id=job_id, watched=[{"type": "user", "name": "your-username"}, {"type": "org", "name": "your-org-name"}], domains=["repo", "discussion"], secret="your-secret" ) ``` The webhook triggers the Job with the webhook payload in the environment variable `WEBHOOK_PAYLOAD`. For more information on Hugging Face Jobs, available hardware (CPU, GPU) and UV scripts, see the [Jobs documentation](./jobs). ### Listing Webhooks To see all the webhooks you have configured, you can list them with [`list_webhooks`]. This is useful to review their IDs, URLs, and statuses. ```python from huggingface_hub import list_webhooks # Example: Listing all webhooks webhooks = list_webhooks() for webhook in webhooks: print(webhook) ``` ### Updating a Webhook If you need to change the configuration of an existing webhook, such as the URL or the events it watches, you can update it using [`update_webhook`]. ```python from huggingface_hub import update_webhook # Example: Updating a webhook updated_webhook = update_webhook( webhook_id="your-webhook-id", url="https://new.webhook.site/url", watched=[{"type": "user", "name": "new-username"}], domains=["repo"] ) ``` ### Enabling and Disabling Webhooks You might want to temporarily disable a webhook without deleting it. This can be done using [`disable_webhook`], and the webhook can be re-enabled later with [`enable_webhook`]. ```python from huggingface_hub import enable_webhook, disable_webhook # Example: Enabling a webhook enabled_webhook = enable_webhook("your-webhook-id") print("Enabled:", enabled_webhook) # Example: Disabling a webhook disabled_webhook = disable_webhook("your-webhook-id") print("Disabled:", disabled_webhook) ``` ### Deleting a Webhook When a webhook is no longer needed, it can be permanently deleted using [`delete_webhook`]. ```python from huggingface_hub import delete_webhook # Example: Deleting a webhook delete_webhook("your-webhook-id") ``` ## Webhooks Server The base class that we will use in this guides section is [`WebhooksServer`]. It is a class for easily configuring a server that can receive webhooks from the Huggingface Hub. The server is based on a [Gradio](https://gradio.app/) app. It has a UI to display instructions for you or your users and an API to listen to webhooks. > [!TIP] > To see a running example of a webhook server, check out the [Spaces CI Bot](https://huggingface.co/spaces/spaces-ci-bot/webhook) > one. It is a Space that launches ephemeral environments when a PR is opened on a Space. > [!WARNING] > This is an [experimental feature](../package_reference/environment_variables#hfhubdisableexperimentalwarning). This > means that we are still working on improving the API. Breaking changes might be introduced in the future without prior > notice. Make sure to pin the version of `huggingface_hub` in your requirements. ### Create an endpoint Implementing a webhook endpoint is as simple as decorating a function. Let's see a first example to explain the main concepts: ```python # app.py from huggingface_hub import webhook_endpoint, WebhookPayload @webhook_endpoint async def trigger_training(payload: WebhookPayload) -> None: if payload.repo.type == "dataset" and payload.event.action == "update": # Trigger a training job if a dataset is updated ... ``` Save this snippet in a file called `'app.py'` and run it with `'python app.py'`. You should see a message like this: ```text Webhook secret is not defined. This means your webhook endpoints will be open to everyone. To add a secret, set `WEBHOOK_SECRET` as environment variable or pass it at initialization: `app = WebhooksServer(webhook_secret='my_secret', ...)` For more details about webhook secrets, please refer to https://huggingface.co/docs/hub/webhooks#webhook-secret. Running on local URL: http://127.0.0.1:7860 Running on public URL: https://1fadb0f52d8bf825fc.gradio.live This share link expires in 72 hours. For free permanent hosting and GPU upgrades (NEW!), check out Spaces: https://huggingface.co/spaces Webhooks are correctly setup and ready to use: - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training Go to https://huggingface.co/settings/webhooks to setup your webhooks. ``` Good job! You just launched a webhook server! Let's break down what happened exactly: 1. By decorating a function with [`webhook_endpoint`], a [`WebhooksServer`] object has been created in the background. As you can see, this server is a Gradio app running on http://127.0.0.1:7860. If you open this URL in your browser, you will see a landing page with instructions about the registered webhooks. 2. A Gradio app is a FastAPI server under the hood. A new POST route `/webhooks/trigger_training` has been added to it. This is the route that will listen to webhooks and run the `trigger_training` function when triggered. FastAPI will automatically parse the payload and pass it to the function as a [`WebhookPayload`] object. This is a `pydantic` object that contains all the information about the event that triggered the webhook. 3. The Gradio app also opened a tunnel to receive requests from the internet. This is the interesting part: you can configure a Webhook on https://huggingface.co/settings/webhooks pointing to your local machine. This is useful for debugging your webhook server and quickly iterating before deploying it to a Space. 4. Finally, the logs also tell you that your server is currently not secured by a secret. This is not problematic for local debugging but is to keep in mind for later. > [!WARNING] > By default, the server is started at the end of your script. If you are running it in a notebook, you can start the > server manually by calling `decorated_function.run()`. Since a unique server is used, you only have to start the server > once even if you have multiple endpoints. ### Configure a Webhook Now that you have a webhook server running, you want to configure a Webhook to start receiving messages. Go to https://huggingface.co/settings/webhooks, click on "Add a new webhook" and configure your Webhook. Set the target repositories you want to watch and the Webhook URL, here `https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training`.
And that's it! You can now trigger that webhook by updating the target repository (e.g. push a commit). Check the Activity tab of your Webhook to see the events that have been triggered. Now that you have a working setup, you can test it and quickly iterate. If you modify your code and restart the server, your public URL might change. Make sure to update the webhook configuration on the Hub if needed. ### Deploy to a Space Now that you have a working webhook server, the goal is to deploy it to a Space. Go to https://huggingface.co/new-space to create a Space. Give it a name, select the Gradio SDK and click on "Create Space". Upload your code to the Space in a file called `app.py`. Your Space will start automatically! For more details about Spaces, please refer to this [guide](https://huggingface.co/docs/hub/spaces-overview). Your webhook server is now running on a public Space. If most cases, you will want to secure it with a secret. Go to your Space settings > Section "Repository secrets" > "Add a secret". Set the `WEBHOOK_SECRET` environment variable to the value of your choice. Go back to the [Webhooks settings](https://huggingface.co/settings/webhooks) and set the secret in the webhook configuration. Now, only requests with the correct secret will be accepted by your server. And this is it! Your Space is now ready to receive webhooks from the Hub. Please keep in mind that if you run the Space on a free 'cpu-basic' hardware, it will be shut down after 48 hours of inactivity. If you need a permanent Space, you should consider setting to an [upgraded hardware](https://huggingface.co/docs/hub/spaces-gpus#hardware-specs). ### Advanced usage The guide above explained the quickest way to setup a [`WebhooksServer`]. In this section, we will see how to customize it further. #### Multiple endpoints You can register multiple endpoints on the same server. For example, you might want to have one endpoint to trigger a training job and another one to trigger a model evaluation. You can do this by adding multiple `@webhook_endpoint` decorators: ```python # app.py from huggingface_hub import webhook_endpoint, WebhookPayload @webhook_endpoint async def trigger_training(payload: WebhookPayload) -> None: if payload.repo.type == "dataset" and payload.event.action == "update": # Trigger a training job if a dataset is updated ... @webhook_endpoint async def trigger_evaluation(payload: WebhookPayload) -> None: if payload.repo.type == "model" and payload.event.action == "update": # Trigger an evaluation job if a model is updated ... ``` Which will create two endpoints: ```text (...) Webhooks are correctly setup and ready to use: - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation ``` #### Custom server To get more flexibility, you can also create a [`WebhooksServer`] object directly. This is useful if you want to customize the landing page of your server. You can do this by passing a [Gradio UI](https://gradio.app/docs/#blocks) that will overwrite the default one. For example, you can add instructions for your users or add a form to manually trigger the webhooks. When creating a [`WebhooksServer`], you can register new webhooks using the [`~WebhooksServer.add_webhook`] decorator. Here is a complete example: ```python import gradio as gr from fastapi import Request from huggingface_hub import WebhooksServer, WebhookPayload # 1. Define UI with gr.Blocks() as ui: ... # 2. Create WebhooksServer with custom UI and secret app = WebhooksServer(ui=ui, webhook_secret="my_secret_key") # 3. Register webhook with explicit name @app.add_webhook("/say_hello") async def hello(payload: WebhookPayload): return {"message": "hello"} # 4. Register webhook with implicit name @app.add_webhook async def goodbye(payload: WebhookPayload): return {"message": "goodbye"} # 5. Start server (optional) app.run() ``` 1. We define a custom UI using Gradio blocks. This UI will be displayed on the landing page of the server. 2. We create a [`WebhooksServer`] object with a custom UI and a secret. The secret is optional and can be set with the `WEBHOOK_SECRET` environment variable. 3. We register a webhook with an explicit name. This will create an endpoint at `/webhooks/say_hello`. 4. We register a webhook with an implicit name. This will create an endpoint at `/webhooks/goodbye`. 5. We start the server. This is optional as your server will automatically be started at the end of the script. huggingface_hub-1.1.5/docs/source/en/index.md000066400000000000000000000073101510763414300211130ustar00rootroot00000000000000 # 🤗 Hub client library The `huggingface_hub` library allows you to interact with the [Hugging Face Hub](https://hf.co), a machine learning platform for creators and collaborators. Discover pre-trained models and datasets for your projects or play with the hundreds of machine learning apps hosted on the Hub. You can also create and share your own models and datasets with the community. The `huggingface_hub` library provides a simple way to do all these things with Python. Read the [quick start guide](quick-start) to get up and running with the `huggingface_hub` library. You will learn how to download files from the Hub, create a repository, and upload files to the Hub. Keep reading to learn more about how to manage your repositories on the 🤗 Hub, how to interact in discussions or even how to run inference.
How-to guides

Practical guides to help you achieve a specific goal. Take a look at these guides to learn how to use huggingface_hub to solve real-world problems.
Reference

Exhaustive and technical description of huggingface_hub classes and methods.
Conceptual guides

High-level explanations for building a better understanding of huggingface_hub philosophy.
## Contribute All contributions to the `huggingface_hub` are welcomed and equally valued! 🤗 Besides adding or fixing existing issues in the code, you can also help improve the documentation by making sure it is accurate and up-to-date, help answer questions on issues, and request new features you think will improve the library. Take a look at the [contribution guide](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) to learn more about how to submit a new issue or feature request, how to submit a pull request, and how to test your contributions to make sure everything works as expected. Contributors should also be respectful of our [code of conduct](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md) to create an inclusive and welcoming collaborative space for everyone. huggingface_hub-1.1.5/docs/source/en/installation.md000066400000000000000000000154161510763414300225130ustar00rootroot00000000000000 # Installation Before you start, you will need to set up your environment by installing the appropriate packages. `huggingface_hub` is tested on **Python 3.9+**. ## Install with pip It is highly recommended to install `huggingface_hub` in a [virtual environment](https://docs.python.org/3/library/venv.html). If you are unfamiliar with Python virtual environments, take a look at this [guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). A virtual environment makes it easier to manage different projects, and avoid compatibility issues between dependencies. Start by creating a virtual environment in your project directory: ```bash python -m venv .env ``` Activate the virtual environment. On Linux and macOS: ```bash source .env/bin/activate ``` Activate virtual environment on Windows: ```bash .env/Scripts/activate ``` Now you're ready to install `huggingface_hub` [from the PyPi registry](https://pypi.org/project/huggingface-hub/): ```bash pip install --upgrade huggingface_hub ``` Once done, [check installation](#check-installation) is working correctly. ### Install optional dependencies Some dependencies of `huggingface_hub` are [optional](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies) because they are not required to run the core features of `huggingface_hub`. However, some features of the `huggingface_hub` may not be available if the optional dependencies aren't installed. You can install optional dependencies via `pip`: ```bash # Install dependencies for both torch-specific and CLI-specific features. pip install 'huggingface_hub[cli,torch]' ``` Here is the list of optional dependencies in `huggingface_hub`: - `cli`: provide a more convenient CLI interface for `huggingface_hub`. - `fastai`, `torch`: dependencies to run framework-specific features. - `dev`: dependencies to contribute to the lib. Includes `testing` (to run tests), `typing` (to run type checker) and `quality` (to run linters). ### Install from source In some cases, it is interesting to install `huggingface_hub` directly from source. This allows you to use the bleeding edge `main` version rather than the latest stable version. The `main` version is useful for staying up-to-date with the latest developments, for instance if a bug has been fixed since the last official release but a new release hasn't been rolled out yet. However, this means the `main` version may not always be stable. We strive to keep the `main` version operational, and most issues are usually resolved within a few hours or a day. If you run into a problem, please open an Issue so we can fix it even sooner! ```bash pip install git+https://github.com/huggingface/huggingface_hub ``` When installing from source, you can also specify a specific branch. This is useful if you want to test a new feature or a new bug-fix that has not been merged yet: ```bash pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch ``` Once done, [check installation](#check-installation) is working correctly. ### Editable install Installing from source allows you to set up an [editable install](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs). This is a more advanced installation if you plan to contribute to `huggingface_hub` and need to test changes in the code. You need to clone a local copy of `huggingface_hub` on your machine. ```bash # First, clone repo locally git clone https://github.com/huggingface/huggingface_hub.git # Then, install with -e flag cd huggingface_hub pip install -e . ``` These commands will link the folder you cloned the repository to and your Python library paths. Python will now look inside the folder you cloned to in addition to the normal library paths. For example, if your Python packages are typically installed in `./.venv/lib/python3.13/site-packages/`, Python will also search the folder you cloned `./huggingface_hub/`. ## Install the Hugging Face CLI Use our one-liner installers to set up the `hf` CLI without touching your Python environment: On macOS and Linux: ```bash curl -LsSf https://hf.co/cli/install.sh | bash ``` On Windows: ```powershell powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex" ``` ## Install with conda If you are more familiar with it, you can install `huggingface_hub` using the [conda-forge channel](https://anaconda.org/conda-forge/huggingface_hub): ```bash conda install -c conda-forge huggingface_hub ``` Once done, [check installation](#check-installation) is working correctly. ## Check installation Once installed, check that `huggingface_hub` works properly by running the following command: ```bash python -c "from huggingface_hub import model_info; print(model_info('gpt2'))" ``` This command will fetch information from the Hub about the [gpt2](https://huggingface.co/gpt2) model. Output should look like this: ```text Model Name: gpt2 Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space'] Task: text-generation ``` ## Windows limitations With our goal of democratizing good ML everywhere, we built `huggingface_hub` to be a cross-platform library and in particular to work correctly on both Unix-based and Windows systems. However, there are a few cases where `huggingface_hub` has some limitations when run on Windows. Here is an exhaustive list of known issues. Please let us know if you encounter any undocumented problem by opening [an issue on Github](https://github.com/huggingface/huggingface_hub/issues/new/choose). - `huggingface_hub`'s cache system relies on symlinks to efficiently cache files downloaded from the Hub. On Windows, you must activate developer mode or run your script as admin to enable symlinks. If they are not activated, the cache-system still works but in a non-optimized manner. Please read [the cache limitations](./guides/manage-cache#limitations) section for more details. - Filepaths on the Hub can have special characters (e.g. `"path/to?/my/file"`). Windows is more restrictive on [special characters](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names) which makes it impossible to download those files on Windows. Hopefully this is a rare case. Please reach out to the repo owner if you think this is a mistake or to us to figure out a solution. ## Next steps Once `huggingface_hub` is properly installed on your machine, you might want to [configure environment variables](package_reference/environment_variables) or [check one of our guides](guides/overview) to get started. huggingface_hub-1.1.5/docs/source/en/package_reference/000077500000000000000000000000001510763414300230725ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/en/package_reference/authentication.md000066400000000000000000000013211510763414300264300ustar00rootroot00000000000000 # Authentication The `huggingface_hub` library allows users to programmatically manage authentication to the Hub. This includes logging in, logging out, switching between tokens, and listing available tokens. For more details about authentication, check out [this section](../quick-start#authentication). ## login [[autodoc]] login ## interpreter_login [[autodoc]] interpreter_login ## notebook_login [[autodoc]] notebook_login ## logout [[autodoc]] logout ## auth_switch [[autodoc]] auth_switch ## auth_list [[autodoc]] auth_list huggingface_hub-1.1.5/docs/source/en/package_reference/cache.md000066400000000000000000000024341510763414300244620ustar00rootroot00000000000000 # Cache-system reference The caching system was updated in v0.8.0 to become the central cache-system shared across libraries that depend on the Hub. Read the [cache-system guide](../guides/manage-cache) for a detailed presentation of caching at HF. ## Helpers ### try_to_load_from_cache [[autodoc]] huggingface_hub.try_to_load_from_cache ### cached_assets_path [[autodoc]] huggingface_hub.cached_assets_path ### scan_cache_dir [[autodoc]] huggingface_hub.scan_cache_dir ## Data structures All structures are built and returned by [`scan_cache_dir`] and are immutable. ### HFCacheInfo [[autodoc]] huggingface_hub.HFCacheInfo ### CachedRepoInfo [[autodoc]] huggingface_hub.CachedRepoInfo - size_on_disk_str - refs ### CachedRevisionInfo [[autodoc]] huggingface_hub.CachedRevisionInfo - size_on_disk_str - nb_files ### CachedFileInfo [[autodoc]] huggingface_hub.CachedFileInfo - size_on_disk_str ### DeleteCacheStrategy [[autodoc]] huggingface_hub.DeleteCacheStrategy - expected_freed_size_str ## Exceptions ### CorruptedCacheException [[autodoc]] huggingface_hub.CorruptedCacheException huggingface_hub-1.1.5/docs/source/en/package_reference/cards.md000066400000000000000000000033331510763414300245120ustar00rootroot00000000000000 # Repository Cards The huggingface_hub library provides a Python interface to create, share, and update Model/Dataset Cards. Visit the [dedicated documentation page](https://huggingface.co/docs/hub/models-cards) for a deeper view of what Model Cards on the Hub are, and how they work under the hood. You can also check out our [Model Cards guide](../how-to-model-cards) to get a feel for how you would use these utilities in your own projects. ## Repo Card The `RepoCard` object is the parent class of [`ModelCard`], [`DatasetCard`] and `SpaceCard`. [[autodoc]] huggingface_hub.repocard.RepoCard - __init__ - all ## Card Data The [`CardData`] object is the parent class of [`ModelCardData`] and [`DatasetCardData`]. [[autodoc]] huggingface_hub.repocard_data.CardData ## Model Cards ### ModelCard [[autodoc]] ModelCard ### ModelCardData [[autodoc]] ModelCardData ## Dataset Cards Dataset cards are also known as Data Cards in the ML Community. ### DatasetCard [[autodoc]] DatasetCard ### DatasetCardData [[autodoc]] DatasetCardData ## Space Cards ### SpaceCard [[autodoc]] SpaceCard ### SpaceCardData [[autodoc]] SpaceCardData ## Utilities ### EvalResult [[autodoc]] EvalResult ### model_index_to_eval_results [[autodoc]] huggingface_hub.repocard_data.model_index_to_eval_results ### eval_results_to_model_index [[autodoc]] huggingface_hub.repocard_data.eval_results_to_model_index ### metadata_eval_result [[autodoc]] huggingface_hub.repocard.metadata_eval_result ### metadata_update [[autodoc]] huggingface_hub.repocard.metadata_update huggingface_hub-1.1.5/docs/source/en/package_reference/cli.md000066400000000000000000001171301510763414300241660ustar00rootroot00000000000000 # `hf` Hugging Face Hub CLI **Usage**: ```console $ hf [OPTIONS] COMMAND [ARGS]... ``` **Options**: * `--install-completion`: Install completion for the current shell. * `--show-completion`: Show completion for the current shell, to copy it or customize the installation. * `--help`: Show this message and exit. **Commands**: * `auth`: Manage authentication (login, logout, etc.). * `cache`: Manage local cache directory. * `download`: Download files from the Hub. * `endpoints`: Manage Hugging Face Inference Endpoints. * `env`: Print information about the environment. * `jobs`: Run and manage Jobs on the Hub. * `lfs-enable-largefiles`: Configure your repository to enable upload... * `lfs-multipart-upload`: Upload large files to the Hub. * `repo`: Manage repos on the Hub. * `repo-files`: Manage files in a repo on the Hub. * `upload`: Upload a file or a folder to the Hub. * `upload-large-folder`: Upload a large folder to the Hub. * `version`: Print information about the hf version. ## `hf auth` Manage authentication (login, logout, etc.). **Usage**: ```console $ hf auth [OPTIONS] COMMAND [ARGS]... ``` **Options**: * `--help`: Show this message and exit. **Commands**: * `list`: List all stored access tokens * `login`: Login using a token from... * `logout`: Logout from a specific token * `switch`: Switch between access tokens * `whoami`: Find out which huggingface.co account you... ### `hf auth list` List all stored access tokens **Usage**: ```console $ hf auth list [OPTIONS] ``` **Options**: * `--help`: Show this message and exit. ### `hf auth login` Login using a token from huggingface.co/settings/tokens **Usage**: ```console $ hf auth login [OPTIONS] ``` **Options**: * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--add-to-git-credential / --no-add-to-git-credential`: Save to git credential helper. Useful only if you plan to run git commands directly. [default: no-add-to-git-credential] * `--help`: Show this message and exit. ### `hf auth logout` Logout from a specific token **Usage**: ```console $ hf auth logout [OPTIONS] ``` **Options**: * `--token-name TEXT`: Name of token to logout * `--help`: Show this message and exit. ### `hf auth switch` Switch between access tokens **Usage**: ```console $ hf auth switch [OPTIONS] ``` **Options**: * `--token-name TEXT`: Name of the token to switch to * `--add-to-git-credential / --no-add-to-git-credential`: Save to git credential helper. Useful only if you plan to run git commands directly. [default: no-add-to-git-credential] * `--help`: Show this message and exit. ### `hf auth whoami` Find out which huggingface.co account you are logged in as. **Usage**: ```console $ hf auth whoami [OPTIONS] ``` **Options**: * `--help`: Show this message and exit. ## `hf cache` Manage local cache directory. **Usage**: ```console $ hf cache [OPTIONS] COMMAND [ARGS]... ``` **Options**: * `--help`: Show this message and exit. **Commands**: * `ls`: List cached repositories or revisions. * `prune`: Remove detached revisions from the cache. * `rm`: Remove cached repositories or revisions. * `verify`: Verify checksums for a single repo... ### `hf cache ls` List cached repositories or revisions. **Usage**: ```console $ hf cache ls [OPTIONS] ``` **Options**: * `--cache-dir TEXT`: Cache directory to scan (defaults to Hugging Face cache). * `--revisions / --no-revisions`: Include revisions in the output instead of aggregated repositories. [default: no-revisions] * `-f, --filter TEXT`: Filter entries (e.g. 'size>1GB', 'type=model', 'accessed>7d'). Can be used multiple times. * `--format [table|json|csv]`: Output format. [default: table] * `-q, --quiet`: Print only IDs (repo IDs or revision hashes). * `--sort [accessed|accessed:asc|accessed:desc|modified|modified:asc|modified:desc|name|name:asc|name:desc|size|size:asc|size:desc]`: Sort entries by key. Supported keys: 'accessed', 'modified', 'name', 'size'. Append ':asc' or ':desc' to explicitly set the order (e.g., 'modified:asc'). Defaults: 'accessed', 'modified', 'size' default to 'desc' (newest/biggest first); 'name' defaults to 'asc' (alphabetical). * `--limit INTEGER`: Limit the number of results returned. Returns only the top N entries after sorting. * `--help`: Show this message and exit. ### `hf cache prune` Remove detached revisions from the cache. **Usage**: ```console $ hf cache prune [OPTIONS] ``` **Options**: * `--cache-dir TEXT`: Cache directory to scan (defaults to Hugging Face cache). * `-y, --yes`: Skip confirmation prompt. * `--dry-run / --no-dry-run`: Preview deletions without removing anything. [default: no-dry-run] * `--help`: Show this message and exit. ### `hf cache rm` Remove cached repositories or revisions. **Usage**: ```console $ hf cache rm [OPTIONS] TARGETS... ``` **Arguments**: * `TARGETS...`: One or more repo IDs (e.g. model/bert-base-uncased) or revision hashes to delete. [required] **Options**: * `--cache-dir TEXT`: Cache directory to scan (defaults to Hugging Face cache). * `-y, --yes`: Skip confirmation prompt. * `--dry-run / --no-dry-run`: Preview deletions without removing anything. [default: no-dry-run] * `--help`: Show this message and exit. ### `hf cache verify` Verify checksums for a single repo revision from cache or a local directory. Examples: - Verify main revision in cache: `hf cache verify gpt2` - Verify specific revision: `hf cache verify gpt2 --revision refs/pr/1` - Verify dataset: `hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type dataset` - Verify local dir: `hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repo` **Usage**: ```console $ hf cache verify [OPTIONS] REPO_ID ``` **Arguments**: * `REPO_ID`: The ID of the repo (e.g. `username/repo-name`). [required] **Options**: * `--repo-type [model|dataset|space]`: The type of repository (model, dataset, or space). [default: model] * `--revision TEXT`: Git revision id which can be a branch name, a tag, or a commit hash. * `--cache-dir TEXT`: Cache directory to use when verifying files from cache (defaults to Hugging Face cache). * `--local-dir TEXT`: If set, verify files under this directory instead of the cache. * `--fail-on-missing-files`: Fail if some files exist on the remote but are missing locally. * `--fail-on-extra-files`: Fail if some files exist locally but are not present on the remote revision. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ## `hf download` Download files from the Hub. **Usage**: ```console $ hf download [OPTIONS] REPO_ID [FILENAMES]... ``` **Arguments**: * `REPO_ID`: The ID of the repo (e.g. `username/repo-name`). [required] * `[FILENAMES]...`: Files to download (e.g. `config.json`, `data/metadata.jsonl`). **Options**: * `--repo-type [model|dataset|space]`: The type of repository (model, dataset, or space). [default: model] * `--revision TEXT`: Git revision id which can be a branch name, a tag, or a commit hash. * `--include TEXT`: Glob patterns to include from files to download. eg: *.json * `--exclude TEXT`: Glob patterns to exclude from files to download. * `--cache-dir TEXT`: Directory where to save files. * `--local-dir TEXT`: If set, the downloaded file will be placed under this directory. Check out https://huggingface.co/docs/huggingface_hub/guides/download#download-files-to-local-folder for more details. * `--force-download / --no-force-download`: If True, the files will be downloaded even if they are already cached. [default: no-force-download] * `--dry-run / --no-dry-run`: If True, perform a dry run without actually downloading the file. [default: no-dry-run] * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--quiet / --no-quiet`: If True, progress bars are disabled and only the path to the download files is printed. [default: no-quiet] * `--max-workers INTEGER`: Maximum number of workers to use for downloading files. Default is 8. [default: 8] * `--help`: Show this message and exit. ## `hf endpoints` Manage Hugging Face Inference Endpoints. **Usage**: ```console $ hf endpoints [OPTIONS] COMMAND [ARGS]... ``` **Options**: * `--help`: Show this message and exit. **Commands**: * `catalog`: Interact with the Inference Endpoints... * `delete`: Delete an Inference Endpoint permanently. * `deploy`: Deploy an Inference Endpoint from a Hub... * `describe`: Get information about an existing endpoint. * `list-catalog`: List available Catalog models. * `ls`: Lists all Inference Endpoints for the... * `pause`: Pause an Inference Endpoint. * `resume`: Resume an Inference Endpoint. * `scale-to-zero`: Scale an Inference Endpoint to zero. * `update`: Update an existing endpoint. ### `hf endpoints catalog` Interact with the Inference Endpoints catalog. **Usage**: ```console $ hf endpoints catalog [OPTIONS] COMMAND [ARGS]... ``` **Options**: * `--help`: Show this message and exit. **Commands**: * `deploy`: Deploy an Inference Endpoint from the... * `ls`: List available Catalog models. #### `hf endpoints catalog deploy` Deploy an Inference Endpoint from the Model Catalog. **Usage**: ```console $ hf endpoints catalog deploy [OPTIONS] ``` **Options**: * `--repo TEXT`: The name of the model repository associated with the Inference Endpoint (e.g. 'openai/gpt-oss-120b'). [required] * `--name TEXT`: Endpoint name. * `--namespace TEXT`: The namespace associated with the Inference Endpoint. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. #### `hf endpoints catalog ls` List available Catalog models. **Usage**: ```console $ hf endpoints catalog ls [OPTIONS] ``` **Options**: * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ### `hf endpoints delete` Delete an Inference Endpoint permanently. **Usage**: ```console $ hf endpoints delete [OPTIONS] NAME ``` **Arguments**: * `NAME`: Endpoint name. [required] **Options**: * `--namespace TEXT`: The namespace associated with the Inference Endpoint. Defaults to the current user's namespace. * `--yes`: Skip confirmation prompts. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ### `hf endpoints deploy` Deploy an Inference Endpoint from a Hub repository. **Usage**: ```console $ hf endpoints deploy [OPTIONS] NAME ``` **Arguments**: * `NAME`: Endpoint name. [required] **Options**: * `--repo TEXT`: The name of the model repository associated with the Inference Endpoint (e.g. 'openai/gpt-oss-120b'). [required] * `--framework TEXT`: The machine learning framework used for the model (e.g. 'vllm'). [required] * `--accelerator TEXT`: The hardware accelerator to be used for inference (e.g. 'cpu'). [required] * `--instance-size TEXT`: The size or type of the instance to be used for hosting the model (e.g. 'x4'). [required] * `--instance-type TEXT`: The cloud instance type where the Inference Endpoint will be deployed (e.g. 'intel-icl'). [required] * `--region TEXT`: The cloud region in which the Inference Endpoint will be created (e.g. 'us-east-1'). [required] * `--vendor TEXT`: The cloud provider or vendor where the Inference Endpoint will be hosted (e.g. 'aws'). [required] * `--namespace TEXT`: The namespace associated with the Inference Endpoint. Defaults to the current user's namespace. * `--task TEXT`: The task on which to deploy the model (e.g. 'text-classification'). * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ### `hf endpoints describe` Get information about an existing endpoint. **Usage**: ```console $ hf endpoints describe [OPTIONS] NAME ``` **Arguments**: * `NAME`: Endpoint name. [required] **Options**: * `--namespace TEXT`: The namespace associated with the Inference Endpoint. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ### `hf endpoints list-catalog` List available Catalog models. **Usage**: ```console $ hf endpoints list-catalog [OPTIONS] ``` **Options**: * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ### `hf endpoints ls` Lists all Inference Endpoints for the given namespace. **Usage**: ```console $ hf endpoints ls [OPTIONS] ``` **Options**: * `--namespace TEXT`: The namespace associated with the Inference Endpoint. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ### `hf endpoints pause` Pause an Inference Endpoint. **Usage**: ```console $ hf endpoints pause [OPTIONS] NAME ``` **Arguments**: * `NAME`: Endpoint name. [required] **Options**: * `--namespace TEXT`: The namespace associated with the Inference Endpoint. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ### `hf endpoints resume` Resume an Inference Endpoint. **Usage**: ```console $ hf endpoints resume [OPTIONS] NAME ``` **Arguments**: * `NAME`: Endpoint name. [required] **Options**: * `--namespace TEXT`: The namespace associated with the Inference Endpoint. Defaults to the current user's namespace. * `--fail-if-already-running`: If `True`, the method will raise an error if the Inference Endpoint is already running. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ### `hf endpoints scale-to-zero` Scale an Inference Endpoint to zero. **Usage**: ```console $ hf endpoints scale-to-zero [OPTIONS] NAME ``` **Arguments**: * `NAME`: Endpoint name. [required] **Options**: * `--namespace TEXT`: The namespace associated with the Inference Endpoint. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ### `hf endpoints update` Update an existing endpoint. **Usage**: ```console $ hf endpoints update [OPTIONS] NAME ``` **Arguments**: * `NAME`: Endpoint name. [required] **Options**: * `--namespace TEXT`: The namespace associated with the Inference Endpoint. Defaults to the current user's namespace. * `--repo TEXT`: The name of the model repository associated with the Inference Endpoint (e.g. 'openai/gpt-oss-120b'). * `--accelerator TEXT`: The hardware accelerator to be used for inference (e.g. 'cpu'). * `--instance-size TEXT`: The size or type of the instance to be used for hosting the model (e.g. 'x4'). * `--instance-type TEXT`: The cloud instance type where the Inference Endpoint will be deployed (e.g. 'intel-icl'). * `--framework TEXT`: The machine learning framework used for the model (e.g. 'custom'). * `--revision TEXT`: The specific model revision to deploy on the Inference Endpoint (e.g. '6c0e6080953db56375760c0471a8c5f2929baf11'). * `--task TEXT`: The task on which to deploy the model (e.g. 'text-classification'). * `--min-replica INTEGER`: The minimum number of replicas (instances) to keep running for the Inference Endpoint. * `--max-replica INTEGER`: The maximum number of replicas (instances) to scale to for the Inference Endpoint. * `--scale-to-zero-timeout INTEGER`: The duration in minutes before an inactive endpoint is scaled to zero. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ## `hf env` Print information about the environment. **Usage**: ```console $ hf env [OPTIONS] ``` **Options**: * `--help`: Show this message and exit. ## `hf jobs` Run and manage Jobs on the Hub. **Usage**: ```console $ hf jobs [OPTIONS] COMMAND [ARGS]... ``` **Options**: * `--help`: Show this message and exit. **Commands**: * `cancel`: Cancel a Job * `inspect`: Display detailed information on one or... * `logs`: Fetch the logs of a Job * `ps`: List Jobs * `run`: Run a Job * `scheduled`: Create and manage scheduled Jobs on the Hub. * `uv`: Run UV scripts (Python with inline... ### `hf jobs cancel` Cancel a Job **Usage**: ```console $ hf jobs cancel [OPTIONS] JOB_ID ``` **Arguments**: * `JOB_ID`: Job ID [required] **Options**: * `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ### `hf jobs inspect` Display detailed information on one or more Jobs **Usage**: ```console $ hf jobs inspect [OPTIONS] JOB_IDS... ``` **Arguments**: * `JOB_IDS...`: The jobs to inspect [required] **Options**: * `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ### `hf jobs logs` Fetch the logs of a Job **Usage**: ```console $ hf jobs logs [OPTIONS] JOB_ID ``` **Arguments**: * `JOB_ID`: Job ID [required] **Options**: * `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ### `hf jobs ps` List Jobs **Usage**: ```console $ hf jobs ps [OPTIONS] ``` **Options**: * `-a, --all`: Show all Jobs (default shows just running) * `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `-f, --filter TEXT`: Filter output based on conditions provided (format: key=value) * `--format TEXT`: Format output using a custom template * `--help`: Show this message and exit. ### `hf jobs run` Run a Job **Usage**: ```console $ hf jobs run [OPTIONS] IMAGE COMMAND... ``` **Arguments**: * `IMAGE`: The Docker image to use. [required] * `COMMAND...`: The command to run. [required] **Options**: * `-e, --env TEXT`: Set environment variables. E.g. --env ENV=value * `-s, --secrets TEXT`: Set secret environment variables. E.g. --secrets SECRET=value or `--secrets HF_TOKEN` to pass your Hugging Face token. * `--env-file TEXT`: Read in a file of environment variables. * `--secrets-file TEXT`: Read in a file of secret environment variables. * `--flavor [cpu-basic|cpu-upgrade|cpu-xl|zero-a10g|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|h100|h100x8]`: Flavor for the hardware, as in HF Spaces. Defaults to `cpu-basic`. Possible values: cpu-basic, cpu-upgrade, cpu-xl, t4-small, t4-medium, l4x1, l4x4, l40sx1, l40sx4, l40sx8, a10g-small, a10g-large, a10g-largex2, a10g-largex4, a100-large, h100, h100x8. * `--timeout TEXT`: Max duration: int/float with s (seconds, default), m (minutes), h (hours) or d (days). * `-d, --detach`: Run the Job in the background and print the Job ID. * `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ### `hf jobs scheduled` Create and manage scheduled Jobs on the Hub. **Usage**: ```console $ hf jobs scheduled [OPTIONS] COMMAND [ARGS]... ``` **Options**: * `--help`: Show this message and exit. **Commands**: * `delete`: Delete a scheduled Job * `inspect`: Display detailed information on one or... * `ps`: List scheduled Jobs * `resume`: Resume (unpause) a scheduled Job * `run`: Schedule a Job * `suspend`: Suspend (pause) a scheduled Job * `uv`: Schedule UV scripts on HF infrastructure #### `hf jobs scheduled delete` Delete a scheduled Job **Usage**: ```console $ hf jobs scheduled delete [OPTIONS] SCHEDULED_JOB_ID ``` **Arguments**: * `SCHEDULED_JOB_ID`: Scheduled Job ID [required] **Options**: * `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. #### `hf jobs scheduled inspect` Display detailed information on one or more scheduled Jobs **Usage**: ```console $ hf jobs scheduled inspect [OPTIONS] SCHEDULED_JOB_IDS... ``` **Arguments**: * `SCHEDULED_JOB_IDS...`: The scheduled jobs to inspect [required] **Options**: * `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. #### `hf jobs scheduled ps` List scheduled Jobs **Usage**: ```console $ hf jobs scheduled ps [OPTIONS] ``` **Options**: * `-a, --all`: Show all scheduled Jobs (default hides suspended) * `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `-f, --filter TEXT`: Filter output based on conditions provided (format: key=value) * `--format TEXT`: Format output using a custom template * `--help`: Show this message and exit. #### `hf jobs scheduled resume` Resume (unpause) a scheduled Job **Usage**: ```console $ hf jobs scheduled resume [OPTIONS] SCHEDULED_JOB_ID ``` **Arguments**: * `SCHEDULED_JOB_ID`: Scheduled Job ID [required] **Options**: * `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. #### `hf jobs scheduled run` Schedule a Job **Usage**: ```console $ hf jobs scheduled run [OPTIONS] SCHEDULE IMAGE COMMAND... ``` **Arguments**: * `SCHEDULE`: One of annually, yearly, monthly, weekly, daily, hourly, or a CRON schedule expression. [required] * `IMAGE`: The Docker image to use. [required] * `COMMAND...`: The command to run. [required] **Options**: * `--suspend / --no-suspend`: Suspend (pause) the scheduled Job * `--concurrency / --no-concurrency`: Allow multiple instances of this Job to run concurrently * `-e, --env TEXT`: Set environment variables. E.g. --env ENV=value * `-s, --secrets TEXT`: Set secret environment variables. E.g. --secrets SECRET=value or `--secrets HF_TOKEN` to pass your Hugging Face token. * `--env-file TEXT`: Read in a file of environment variables. * `--secrets-file TEXT`: Read in a file of secret environment variables. * `--flavor [cpu-basic|cpu-upgrade|cpu-xl|zero-a10g|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|h100|h100x8]`: Flavor for the hardware, as in HF Spaces. Defaults to `cpu-basic`. Possible values: cpu-basic, cpu-upgrade, cpu-xl, t4-small, t4-medium, l4x1, l4x4, l40sx1, l40sx4, l40sx8, a10g-small, a10g-large, a10g-largex2, a10g-largex4, a100-large, h100, h100x8. * `--timeout TEXT`: Max duration: int/float with s (seconds, default), m (minutes), h (hours) or d (days). * `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. #### `hf jobs scheduled suspend` Suspend (pause) a scheduled Job **Usage**: ```console $ hf jobs scheduled suspend [OPTIONS] SCHEDULED_JOB_ID ``` **Arguments**: * `SCHEDULED_JOB_ID`: Scheduled Job ID [required] **Options**: * `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. #### `hf jobs scheduled uv` Schedule UV scripts on HF infrastructure **Usage**: ```console $ hf jobs scheduled uv [OPTIONS] COMMAND [ARGS]... ``` **Options**: * `--help`: Show this message and exit. **Commands**: * `run`: Run a UV script (local file or URL) on HF... ##### `hf jobs scheduled uv run` Run a UV script (local file or URL) on HF infrastructure **Usage**: ```console $ hf jobs scheduled uv run [OPTIONS] SCHEDULE SCRIPT [SCRIPT_ARGS]... ``` **Arguments**: * `SCHEDULE`: One of annually, yearly, monthly, weekly, daily, hourly, or a CRON schedule expression. [required] * `SCRIPT`: UV script to run (local file or URL) [required] * `[SCRIPT_ARGS]...`: Arguments for the script **Options**: * `--suspend / --no-suspend`: Suspend (pause) the scheduled Job * `--concurrency / --no-concurrency`: Allow multiple instances of this Job to run concurrently * `--image TEXT`: Use a custom Docker image with `uv` installed. * `--repo TEXT`: Repository name for the script (creates ephemeral if not specified) * `--flavor [cpu-basic|cpu-upgrade|cpu-xl|zero-a10g|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|h100|h100x8]`: Flavor for the hardware, as in HF Spaces. Defaults to `cpu-basic`. Possible values: cpu-basic, cpu-upgrade, cpu-xl, t4-small, t4-medium, l4x1, l4x4, l40sx1, l40sx4, l40sx8, a10g-small, a10g-large, a10g-largex2, a10g-largex4, a100-large, h100, h100x8. * `-e, --env TEXT`: Set environment variables. E.g. --env ENV=value * `-s, --secrets TEXT`: Set secret environment variables. E.g. --secrets SECRET=value or `--secrets HF_TOKEN` to pass your Hugging Face token. * `--env-file TEXT`: Read in a file of environment variables. * `--secrets-file TEXT`: Read in a file of secret environment variables. * `--timeout TEXT`: Max duration: int/float with s (seconds, default), m (minutes), h (hours) or d (days). * `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--with TEXT`: Run with the given packages installed * `-p, --python TEXT`: The Python interpreter to use for the run environment * `--help`: Show this message and exit. ### `hf jobs uv` Run UV scripts (Python with inline dependencies) on HF infrastructure **Usage**: ```console $ hf jobs uv [OPTIONS] COMMAND [ARGS]... ``` **Options**: * `--help`: Show this message and exit. **Commands**: * `run`: Run a UV script (local file or URL) on HF... #### `hf jobs uv run` Run a UV script (local file or URL) on HF infrastructure **Usage**: ```console $ hf jobs uv run [OPTIONS] SCRIPT [SCRIPT_ARGS]... ``` **Arguments**: * `SCRIPT`: UV script to run (local file or URL) [required] * `[SCRIPT_ARGS]...`: Arguments for the script **Options**: * `--image TEXT`: Use a custom Docker image with `uv` installed. * `--repo TEXT`: Repository name for the script (creates ephemeral if not specified) * `--flavor [cpu-basic|cpu-upgrade|cpu-xl|zero-a10g|t4-small|t4-medium|l4x1|l4x4|l40sx1|l40sx4|l40sx8|a10g-small|a10g-large|a10g-largex2|a10g-largex4|a100-large|h100|h100x8]`: Flavor for the hardware, as in HF Spaces. Defaults to `cpu-basic`. Possible values: cpu-basic, cpu-upgrade, cpu-xl, t4-small, t4-medium, l4x1, l4x4, l40sx1, l40sx4, l40sx8, a10g-small, a10g-large, a10g-largex2, a10g-largex4, a100-large, h100, h100x8. * `-e, --env TEXT`: Set environment variables. E.g. --env ENV=value * `-s, --secrets TEXT`: Set secret environment variables. E.g. --secrets SECRET=value or `--secrets HF_TOKEN` to pass your Hugging Face token. * `--env-file TEXT`: Read in a file of environment variables. * `--secrets-file TEXT`: Read in a file of secret environment variables. * `--timeout TEXT`: Max duration: int/float with s (seconds, default), m (minutes), h (hours) or d (days). * `-d, --detach`: Run the Job in the background and print the Job ID. * `--namespace TEXT`: The namespace where the job will be running. Defaults to the current user's namespace. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--with TEXT`: Run with the given packages installed * `-p, --python TEXT`: The Python interpreter to use for the run environment * `--help`: Show this message and exit. ## `hf lfs-enable-largefiles` Configure your repository to enable upload of files > 5GB. **Usage**: ```console $ hf lfs-enable-largefiles [OPTIONS] PATH ``` **Arguments**: * `PATH`: Local path to repository you want to configure. [required] **Options**: * `--help`: Show this message and exit. ## `hf lfs-multipart-upload` Upload large files to the Hub. **Usage**: ```console $ hf lfs-multipart-upload [OPTIONS] ``` **Options**: * `--help`: Show this message and exit. ## `hf repo` Manage repos on the Hub. **Usage**: ```console $ hf repo [OPTIONS] COMMAND [ARGS]... ``` **Options**: * `--help`: Show this message and exit. **Commands**: * `branch`: Manage branches for a repo on the Hub. * `create`: Create a new repo on the Hub. * `delete`: Delete a repo from the Hub. * `move`: Move a repository from a namespace to... * `settings`: Update the settings of a repository. * `tag`: Manage tags for a repo on the Hub. ### `hf repo branch` Manage branches for a repo on the Hub. **Usage**: ```console $ hf repo branch [OPTIONS] COMMAND [ARGS]... ``` **Options**: * `--help`: Show this message and exit. **Commands**: * `create`: Create a new branch for a repo on the Hub. * `delete`: Delete a branch from a repo on the Hub. #### `hf repo branch create` Create a new branch for a repo on the Hub. **Usage**: ```console $ hf repo branch create [OPTIONS] REPO_ID BRANCH ``` **Arguments**: * `REPO_ID`: The ID of the repo (e.g. `username/repo-name`). [required] * `BRANCH`: The name of the branch to create. [required] **Options**: * `--revision TEXT`: Git revision id which can be a branch name, a tag, or a commit hash. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--repo-type [model|dataset|space]`: The type of repository (model, dataset, or space). [default: model] * `--exist-ok / --no-exist-ok`: If set to True, do not raise an error if branch already exists. [default: no-exist-ok] * `--help`: Show this message and exit. #### `hf repo branch delete` Delete a branch from a repo on the Hub. **Usage**: ```console $ hf repo branch delete [OPTIONS] REPO_ID BRANCH ``` **Arguments**: * `REPO_ID`: The ID of the repo (e.g. `username/repo-name`). [required] * `BRANCH`: The name of the branch to delete. [required] **Options**: * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--repo-type [model|dataset|space]`: The type of repository (model, dataset, or space). [default: model] * `--help`: Show this message and exit. ### `hf repo create` Create a new repo on the Hub. **Usage**: ```console $ hf repo create [OPTIONS] REPO_ID ``` **Arguments**: * `REPO_ID`: The ID of the repo (e.g. `username/repo-name`). [required] **Options**: * `--repo-type [model|dataset|space]`: The type of repository (model, dataset, or space). [default: model] * `--space-sdk TEXT`: Hugging Face Spaces SDK type. Required when --type is set to 'space'. * `--private / --no-private`: Whether to create a private repo if repo doesn't exist on the Hub. Ignored if the repo already exists. [default: no-private] * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--exist-ok / --no-exist-ok`: Do not raise an error if repo already exists. [default: no-exist-ok] * `--resource-group-id TEXT`: Resource group in which to create the repo. Resource groups is only available for Enterprise Hub organizations. * `--help`: Show this message and exit. ### `hf repo delete` Delete a repo from the Hub. this is an irreversible operation. **Usage**: ```console $ hf repo delete [OPTIONS] REPO_ID ``` **Arguments**: * `REPO_ID`: The ID of the repo (e.g. `username/repo-name`). [required] **Options**: * `--repo-type [model|dataset|space]`: The type of repository (model, dataset, or space). [default: model] * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--missing-ok / --no-missing-ok`: If set to True, do not raise an error if repo does not exist. [default: no-missing-ok] * `--help`: Show this message and exit. ### `hf repo move` Move a repository from a namespace to another namespace. **Usage**: ```console $ hf repo move [OPTIONS] FROM_ID TO_ID ``` **Arguments**: * `FROM_ID`: The ID of the repo (e.g. `username/repo-name`). [required] * `TO_ID`: The ID of the repo (e.g. `username/repo-name`). [required] **Options**: * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--repo-type [model|dataset|space]`: The type of repository (model, dataset, or space). [default: model] * `--help`: Show this message and exit. ### `hf repo settings` Update the settings of a repository. **Usage**: ```console $ hf repo settings [OPTIONS] REPO_ID ``` **Arguments**: * `REPO_ID`: The ID of the repo (e.g. `username/repo-name`). [required] **Options**: * `--gated [auto|manual|false]`: The gated status for the repository. * `--private / --no-private`: Whether the repository should be private. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--repo-type [model|dataset|space]`: The type of repository (model, dataset, or space). [default: model] * `--help`: Show this message and exit. ### `hf repo tag` Manage tags for a repo on the Hub. **Usage**: ```console $ hf repo tag [OPTIONS] COMMAND [ARGS]... ``` **Options**: * `--help`: Show this message and exit. **Commands**: * `create`: Create a tag for a repo. * `delete`: Delete a tag for a repo. * `list`: List tags for a repo. #### `hf repo tag create` Create a tag for a repo. **Usage**: ```console $ hf repo tag create [OPTIONS] REPO_ID TAG ``` **Arguments**: * `REPO_ID`: The ID of the repo (e.g. `username/repo-name`). [required] * `TAG`: The name of the tag to create. [required] **Options**: * `-m, --message TEXT`: The description of the tag to create. * `--revision TEXT`: Git revision id which can be a branch name, a tag, or a commit hash. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--repo-type [model|dataset|space]`: The type of repository (model, dataset, or space). [default: model] * `--help`: Show this message and exit. #### `hf repo tag delete` Delete a tag for a repo. **Usage**: ```console $ hf repo tag delete [OPTIONS] REPO_ID TAG ``` **Arguments**: * `REPO_ID`: The ID of the repo (e.g. `username/repo-name`). [required] * `TAG`: The name of the tag to delete. [required] **Options**: * `-y, --yes`: Answer Yes to prompt automatically * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--repo-type [model|dataset|space]`: The type of repository (model, dataset, or space). [default: model] * `--help`: Show this message and exit. #### `hf repo tag list` List tags for a repo. **Usage**: ```console $ hf repo tag list [OPTIONS] REPO_ID ``` **Arguments**: * `REPO_ID`: The ID of the repo (e.g. `username/repo-name`). [required] **Options**: * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--repo-type [model|dataset|space]`: The type of repository (model, dataset, or space). [default: model] * `--help`: Show this message and exit. ## `hf repo-files` Manage files in a repo on the Hub. **Usage**: ```console $ hf repo-files [OPTIONS] COMMAND [ARGS]... ``` **Options**: * `--help`: Show this message and exit. **Commands**: * `delete` ### `hf repo-files delete` **Usage**: ```console $ hf repo-files delete [OPTIONS] REPO_ID PATTERNS... ``` **Arguments**: * `REPO_ID`: The ID of the repo (e.g. `username/repo-name`). [required] * `PATTERNS...`: Glob patterns to match files to delete. [required] **Options**: * `--repo-type [model|dataset|space]`: The type of repository (model, dataset, or space). [default: model] * `--revision TEXT`: Git revision id which can be a branch name, a tag, or a commit hash. * `--commit-message TEXT`: The summary / title / first line of the generated commit. * `--commit-description TEXT`: The description of the generated commit. * `--create-pr / --no-create-pr`: Whether to create a new Pull Request for these changes. [default: no-create-pr] * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--help`: Show this message and exit. ## `hf upload` Upload a file or a folder to the Hub. **Usage**: ```console $ hf upload [OPTIONS] REPO_ID [LOCAL_PATH] [PATH_IN_REPO] ``` **Arguments**: * `REPO_ID`: The ID of the repo (e.g. `username/repo-name`). [required] * `[LOCAL_PATH]`: Local path to the file or folder to upload. Wildcard patterns are supported. Defaults to current directory. * `[PATH_IN_REPO]`: Path of the file or folder in the repo. Defaults to the relative path of the file or folder. **Options**: * `--repo-type [model|dataset|space]`: The type of repository (model, dataset, or space). [default: model] * `--revision TEXT`: Git revision id which can be a branch name, a tag, or a commit hash. * `--private / --no-private`: Whether to create a private repo if repo doesn't exist on the Hub. Ignored if the repo already exists. [default: no-private] * `--include TEXT`: Glob patterns to match files to upload. * `--exclude TEXT`: Glob patterns to exclude from files to upload. * `--delete TEXT`: Glob patterns for file to be deleted from the repo while committing. * `--commit-message TEXT`: The summary / title / first line of the generated commit. * `--commit-description TEXT`: The description of the generated commit. * `--create-pr / --no-create-pr`: Whether to upload content as a new Pull Request. [default: no-create-pr] * `--every FLOAT`: f set, a background job is scheduled to create commits every `every` minutes. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--quiet / --no-quiet`: Disable progress bars and warnings; print only the returned path. [default: no-quiet] * `--help`: Show this message and exit. ## `hf upload-large-folder` Upload a large folder to the Hub. Recommended for resumable uploads. **Usage**: ```console $ hf upload-large-folder [OPTIONS] REPO_ID LOCAL_PATH ``` **Arguments**: * `REPO_ID`: The ID of the repo (e.g. `username/repo-name`). [required] * `LOCAL_PATH`: Local path to the folder to upload. [required] **Options**: * `--repo-type [model|dataset|space]`: The type of repository (model, dataset, or space). [default: model] * `--revision TEXT`: Git revision id which can be a branch name, a tag, or a commit hash. * `--private / --no-private`: Whether to create a private repo if repo doesn't exist on the Hub. Ignored if the repo already exists. [default: no-private] * `--include TEXT`: Glob patterns to match files to upload. * `--exclude TEXT`: Glob patterns to exclude from files to upload. * `--token TEXT`: A User Access Token generated from https://huggingface.co/settings/tokens. * `--num-workers INTEGER`: Number of workers to use to hash, upload and commit files. * `--no-report / --no-no-report`: Whether to disable regular status report. [default: no-no-report] * `--no-bars / --no-no-bars`: Whether to disable progress bars. [default: no-no-bars] * `--help`: Show this message and exit. ## `hf version` Print information about the hf version. **Usage**: ```console $ hf version [OPTIONS] ``` **Options**: * `--help`: Show this message and exit. huggingface_hub-1.1.5/docs/source/en/package_reference/collections.md000066400000000000000000000013751510763414300257400ustar00rootroot00000000000000 # Managing collections Check out the [`HfApi`] documentation page for the reference of methods to manage your Space on the Hub. - Get collection content: [`get_collection`] - Create new collection: [`create_collection`] - Update a collection: [`update_collection_metadata`] - Delete a collection: [`delete_collection`] - Add an item to a collection: [`add_collection_item`] - Update an item in a collection: [`update_collection_item`] - Remove an item from a collection: [`delete_collection_item`] ### Collection [[autodoc]] Collection ### CollectionItem [[autodoc]] CollectionItem huggingface_hub-1.1.5/docs/source/en/package_reference/community.md000066400000000000000000000015141510763414300254410ustar00rootroot00000000000000 # Interacting with Discussions and Pull Requests Check the [`HfApi`] documentation page for the reference of methods enabling interaction with Pull Requests and Discussions on the Hub. - [`get_repo_discussions`] - [`get_discussion_details`] - [`create_discussion`] - [`create_pull_request`] - [`rename_discussion`] - [`comment_discussion`] - [`edit_discussion_comment`] - [`change_discussion_status`] - [`merge_pull_request`] ## Data structures [[autodoc]] Discussion [[autodoc]] DiscussionWithDetails [[autodoc]] DiscussionEvent [[autodoc]] DiscussionComment [[autodoc]] DiscussionStatusChange [[autodoc]] DiscussionCommit [[autodoc]] DiscussionTitleChange huggingface_hub-1.1.5/docs/source/en/package_reference/dataclasses.md000066400000000000000000000176411510763414300257140ustar00rootroot00000000000000# Strict Dataclasses The `huggingface_hub` package provides a utility to create **strict dataclasses**. These are enhanced versions of Python's standard `dataclass` with additional validation features. Strict dataclasses ensure that fields are validated both during initialization and assignment, making them ideal for scenarios where data integrity is critical. ## Overview Strict dataclasses are created using the `@strict` decorator. They extend the functionality of regular dataclasses by: - Validating field types based on type hints - Supporting custom validators for additional checks - Optionally allowing arbitrary keyword arguments in the constructor - Validating fields both at initialization and during assignment ## Benefits - **Data Integrity**: Ensures fields always contain valid data - **Ease of Use**: Integrates seamlessly with Python's `dataclass` module - **Flexibility**: Supports custom validators for complex validation logic - **Lightweight**: Requires no additional dependencies such as Pydantic, attrs, or similar libraries ## Usage ### Basic Example ```python from dataclasses import dataclass from huggingface_hub.dataclasses import strict, as_validated_field # Custom validator to ensure a value is positive @as_validated_field def positive_int(value: int): if not value > 0: raise ValueError(f"Value must be positive, got {value}") @strict @dataclass class Config: model_type: str hidden_size: int = positive_int(default=16) vocab_size: int = 32 # Default value # Methods named `validate_xxx` are treated as class-wise validators def validate_big_enough_vocab(self): if self.vocab_size < self.hidden_size: raise ValueError(f"vocab_size ({self.vocab_size}) must be greater than hidden_size ({self.hidden_size})") ``` Fields are validated during initialization: ```python config = Config(model_type="bert", hidden_size=24) # Valid config = Config(model_type="bert", hidden_size=-1) # Raises StrictDataclassFieldValidationError ``` Consistency between fields is also validated during initialization (class-wise validation): ```python # `vocab_size` too small compared to `hidden_size` config = Config(model_type="bert", hidden_size=32, vocab_size=16) # Raises StrictDataclassClassValidationError ``` Fields are also validated during assignment: ```python config.hidden_size = 512 # Valid config.hidden_size = -1 # Raises StrictDataclassFieldValidationError ``` To re-run class-wide validation after assignment, you must call `.validate` explicitly: ```python config.validate() # Runs all class validators ``` ### Custom Validators You can attach multiple custom validators to fields using [`validated_field`]. A validator is a callable that takes a single argument and raises an exception if the value is invalid. ```python from dataclasses import dataclass from huggingface_hub.dataclasses import strict, validated_field def multiple_of_64(value: int): if value % 64 != 0: raise ValueError(f"Value must be a multiple of 64, got {value}") @strict @dataclass class Config: hidden_size: int = validated_field(validator=[positive_int, multiple_of_64]) ``` In this example, both validators are applied to the `hidden_size` field. ### Additional Keyword Arguments By default, strict dataclasses only accept fields defined in the class. You can allow additional keyword arguments by setting `accept_kwargs=True` in the `@strict` decorator. ```python from dataclasses import dataclass from huggingface_hub.dataclasses import strict @strict(accept_kwargs=True) @dataclass class ConfigWithKwargs: model_type: str vocab_size: int = 16 config = ConfigWithKwargs(model_type="bert", vocab_size=30000, extra_field="extra_value") print(config) # ConfigWithKwargs(model_type='bert', vocab_size=30000, *extra_field='extra_value') ``` Additional keyword arguments appear in the string representation of the dataclass but are prefixed with `*` to highlight that they are not validated. ### Integration with Type Hints Strict dataclasses respect type hints and validate them automatically. For example: ```python from typing import List from dataclasses import dataclass from huggingface_hub.dataclasses import strict @strict @dataclass class Config: layers: List[int] config = Config(layers=[64, 128]) # Valid config = Config(layers="not_a_list") # Raises StrictDataclassFieldValidationError ``` Supported types include: - Any - Union - Optional - Literal - List - Dict - Tuple - Set And any combination of these types. If your need more complex type validation, you can do it through a custom validator. ### Class validators Methods named `validate_xxx` are treated as class validators. These methods must only take `self` as an argument. Class validators are run once during initialization, right after `__post_init__`. You can define as many of them as needed—they'll be executed sequentially in the order they appear. Note that class validators are not automatically re-run when a field is updated after initialization. To manually re-validate the object, you need to call `obj.validate()`. ```py from dataclasses import dataclass from huggingface_hub.dataclasses import strict @strict @dataclass class Config: foo: str foo_length: int upper_case: bool = False def validate_foo_length(self): if len(self.foo) != self.foo_length: raise ValueError(f"foo must be {self.foo_length} characters long, got {len(self.foo)}") def validate_foo_casing(self): if self.upper_case and self.foo.upper() != self.foo: raise ValueError(f"foo must be uppercase, got {self.foo}") config = Config(foo="bar", foo_length=3) # ok config.upper_case = True config.validate() # Raises StrictDataclassClassValidationError Config(foo="abcd", foo_length=3) # Raises StrictDataclassFieldValidationError Config(foo="Bar", foo_length=3, upper_case=True) # Raises StrictDataclassFieldValidationError ``` > [!WARNING] > Method `.validate()` is a reserved name on strict dataclasses. > To prevent unexpected behaviors, a [`StrictDataclassDefinitionError`] error will be raised if your class already defines one. ## API Reference ### `@strict` The `@strict` decorator enhances a dataclass with strict validation. [[autodoc]] dataclasses.strict ### `validate_typed_dict` Method to validate that a dictionary conforms to the types defined in a `TypedDict` class. This is the equivalent to dataclass validation but for `TypedDict`s. Since typed dicts are never instantiated (only used by static type checkers), validation step must be manually called. [[autodoc]] dataclasses.validate_typed_dict ### `as_validated_field` Decorator to create a [`validated_field`]. Recommended for fields with a single validator to avoid boilerplate code. [[autodoc]] dataclasses.as_validated_field ### `validated_field` Creates a dataclass field with custom validation. [[autodoc]] dataclasses.validated_field ### Errors [[autodoc]] errors.StrictDataclassError [[autodoc]] errors.StrictDataclassDefinitionError [[autodoc]] errors.StrictDataclassFieldValidationError ## Why Not Use `pydantic`? (or `attrs`? or `marshmallow_dataclass`?) - See discussion in https://github.com/huggingface/transformers/issues/36329 regarding adding Pydantic as a dependency. It would be a heavy addition and require careful logic to support both v1 and v2. - We don't need most of Pydantic's features, especially those related to automatic casting, jsonschema, serialization, aliases, etc. - We don't need the ability to instantiate a class from a dictionary. - We don't want to mutate data. In `@strict`, "validation" means "checking if a value is valid." In Pydantic, "validation" means "casting a value, possibly mutating it, and then checking if it's valid." - We don't need blazing-fast validation. `@strict` isn't designed for heavy loads where performance is critical. Common use cases involve validating a model configuration (performed once and negligible compared to running a model). This allows us to keep the code minimal.huggingface_hub-1.1.5/docs/source/en/package_reference/environment_variables.md000066400000000000000000000304561510763414300300200ustar00rootroot00000000000000 # Environment variables `huggingface_hub` can be configured using environment variables. If you are unfamiliar with environment variable, here are generic articles about them [on macOS and Linux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/) and on [Windows](https://phoenixnap.com/kb/windows-set-environment-variable). This page will guide you through all environment variables specific to `huggingface_hub` and their meaning. ## Generic ### HF_INFERENCE_ENDPOINT To configure the inference api base url. You might want to set this variable if your organization is pointing at an API Gateway rather than directly at the inference api. Defaults to `"https://api-inference.huggingface.co"`. ### HF_HOME To configure where `huggingface_hub` will locally store data. In particular, your token and the cache will be stored in this folder. Defaults to `"~/.cache/huggingface"` unless [XDG_CACHE_HOME](#xdgcachehome) is set. ### HF_HUB_CACHE To configure where repositories from the Hub will be cached locally (models, datasets and spaces). Defaults to `"$HF_HOME/hub"` (e.g. `"~/.cache/huggingface/hub"` by default). ### HF_XET_CACHE To configure where Xet chunks (byte ranges from files managed by Xet backend) are cached locally. Defaults to `"$HF_HOME/xet"` (e.g. `"~/.cache/huggingface/xet"` by default). ### HF_ASSETS_CACHE To configure where [assets](../guides/manage-cache#caching-assets) created by downstream libraries will be cached locally. Those assets can be preprocessed data, files downloaded from GitHub, logs,... Defaults to `"$HF_HOME/assets"` (e.g. `"~/.cache/huggingface/assets"` by default). ### HF_TOKEN To configure the User Access Token to authenticate to the Hub. If set, this value will overwrite the token stored on the machine (in either `$HF_TOKEN_PATH` or `"$HF_HOME/token"` if the former is not set). For more details about authentication, check out [this section](../quick-start#authentication). ### HF_TOKEN_PATH To configure where `huggingface_hub` should store the User Access Token. Defaults to `"$HF_HOME/token"` (e.g. `~/.cache/huggingface/token` by default). ### HF_HUB_VERBOSITY Set the verbosity level of the `huggingface_hub`'s logger. Must be one of `{"debug", "info", "warning", "error", "critical"}`. Defaults to `"warning"`. For more details, see [logging reference](../package_reference/utilities#huggingface_hub.utils.logging.get_verbosity). ### HF_HUB_ETAG_TIMEOUT Integer value to define the number of seconds to wait for server response when fetching the latest metadata from a repo before downloading a file. If the request times out, `huggingface_hub` will default to the locally cached files. Setting a lower value speeds up the workflow for machines with a slow connection that have already cached files. A higher value guarantees the metadata call to succeed in more cases. Default to 10s. ### HF_HUB_DOWNLOAD_TIMEOUT Integer value to define the number of seconds to wait for server response when downloading a file. If the request times out, a TimeoutError is raised. Setting a higher value is beneficial on machine with a slow connection. A smaller value makes the process fail quicker in case of complete network outage. Default to 10s. ## Xet ### Other Xet environment variables * [`HF_HUB_DISABLE_XET`](../package_reference/environment_variables#hfhubdisablexet) * [`HF_XET_CACHE`](../package_reference/environment_variables#hfxetcache) * [`HF_XET_HIGH_PERFORMANCE`](../package_reference/environment_variables#hfxethighperformance) * [`HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY`](../package_reference/environment_variables#hfxetreconstructwritesequentially) ### HF_XET_CHUNK_CACHE_SIZE_BYTES To set the size of the Xet chunk cache locally. By default, the chunk cache is disabled. The chunk cache can be beneficial if you are generating new revisions to existing models or datasets as this is used to cache terms/chunks that are fetched from S3. A larger cache can better take advantage of deduplication across repos & files. To enable the chunk cache set the environment variable to a large number (10GB) or greater. However, in most cases when downloading or uploading new data, disabling the chunk cache will have better performance, which is why it is disabled by default. Defaults to `0` (0 bytes, means chunk cache is disabled). ### HF_XET_SHARD_CACHE_SIZE_LIMIT To set the size of the Xet shard cache locally. Increasing this will improve upload efficiency as chunks referenced in cached shard files are not re-uploaded. Note that the default soft limit is likely sufficient for most workloads. Defaults to `4000000000` (4GB). ### HF_XET_NUM_CONCURRENT_RANGE_GETS To set the number of concurrent terms (range of bytes from within a xorb, often called a chunk) downloaded from S3 per file. Increasing this will help with the speed of downloading a file if there is network bandwidth available. Defaults to `16`. ## Boolean values The following environment variables expect a boolean value. The variable will be considered as `True` if its value is one of `{"1", "ON", "YES", "TRUE"}` (case-insensitive). Any other value (or undefined) will be considered as `False`. ### HF_DEBUG If set, the log level for the `huggingface_hub` logger is set to DEBUG. Additionally, all requests made by HF libraries will be logged as equivalent cURL commands for easier debugging and reproducibility. ### HF_HUB_OFFLINE If set, no HTTP calls will be made to the Hugging Face Hub. If you try to download files, only the cached files will be accessed. If no cache file is detected, an error is raised This is useful in case your network is slow and you don't care about having the latest version of a file. If `HF_HUB_OFFLINE=1` is set as environment variable and you call any method of [`HfApi`], an [`~huggingface_hub.utils.OfflineModeIsEnabled`] exception will be raised. **Note:** even if the latest version of a file is cached, calling `hf_hub_download` still triggers a HTTP request to check that a new version is not available. Setting `HF_HUB_OFFLINE=1` will skip this call which speeds up your loading time. ### HF_HUB_DISABLE_IMPLICIT_TOKEN Authentication is not mandatory for every request to the Hub. For instance, requesting details about `"gpt2"` model does not require to be authenticated. However, if a user is [logged in](../package_reference/login), the default behavior will be to always send the token in order to ease user experience (never get a HTTP 401 Unauthorized) when accessing private or gated repositories. For privacy, you can disable this behavior by setting `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`. In this case, the token will be sent only for "write-access" calls (example: create a commit). **Note:** disabling implicit sending of token can have weird side effects. For example, if you want to list all models on the Hub, your private models will not be listed. You would need to explicitly pass `token=True` argument in your script. ### HF_HUB_DISABLE_PROGRESS_BARS For time-consuming tasks, `huggingface_hub` displays a progress bar by default (using tqdm). You can disable all the progress bars at once by setting `HF_HUB_DISABLE_PROGRESS_BARS=1`. ### HF_HUB_DISABLE_SYMLINKS_WARNING If you are on a Windows machine, it is recommended to enable the developer mode or to run `huggingface_hub` in admin mode. If not, `huggingface_hub` will not be able to create symlinks in your cache system. You will be able to execute any script but your user experience will be degraded as some huge files might end-up duplicated on your hard-drive. A warning message is triggered to warn you about this behavior. Set `HF_HUB_DISABLE_SYMLINKS_WARNING=1`, to disable this warning. For more details, see [cache limitations](../guides/manage-cache#limitations). ### HF_HUB_DISABLE_EXPERIMENTAL_WARNING Some features of `huggingface_hub` are experimental. This means you can use them but we do not guarantee they will be maintained in the future. In particular, we might update the API or behavior of such features without any deprecation cycle. A warning message is triggered when using an experimental feature to warn you about it. If you're comfortable debugging any potential issues using an experimental feature, you can set `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` to disable the warning. If you are using an experimental feature, please let us know! Your feedback can help us design and improve it. ### HF_HUB_DISABLE_TELEMETRY By default, some data is collected by HF libraries (`transformers`, `datasets`, `gradio`,..) to monitor usage, debug issues and help prioritize features. Each library defines its own policy (i.e. which usage to monitor) but the core implementation happens in `huggingface_hub` (see [`send_telemetry`]). You can set `HF_HUB_DISABLE_TELEMETRY=1` as environment variable to globally disable telemetry. ### HF_HUB_DISABLE_XET Set to disable using `hf-xet`, even if it is available in your Python environment. This is since `hf-xet` will be used automatically if it is found, this allows explicitly disabling its usage. If you are disabling Xet, please consider [filing an issue and including the diagnostics](https://github.com/huggingface/xet-core?tab=readme-ov-file#issues-diagnostics--debugging) information to help us understand why Xet is not working for you. ### HF_HUB_ENABLE_HF_TRANSFER > [!WARNING] > This is a deprecated environment variable. > Now that the Hugging Face Hub is fully powered by the Xet storage backend, all file transfers go through the `hf-xet` binary package. It provides efficient transfers using a chunk-based deduplication strategy and integrates seamlessly with `huggingface_hub`. > This means `hf_transfer` can't be used anymore. If you are interested in higher performance, check out the [`HF_XET_HIGH_PERFORMANCE` section](#hf_xet_high_performance) ### HF_XET_HIGH_PERFORMANCE Set `hf-xet` to operate with increased settings to maximize network and disk resources on the machine. Enabling high performance mode will try to saturate the network bandwidth of this machine and utilize all CPU cores for parallel upload/download activity. Consider this analogous to the legacy `HF_HUB_ENABLE_HF_TRANSFER=1` environment variable but applied to `hf-xet`. To learn more about the benefits of Xet storage and `hf_xet`, refer to this [section](https://huggingface.co/docs/hub/xet/index). ### HF_XET_RECONSTRUCT_WRITE_SEQUENTIALLY To have `hf-xet` write sequentially to local disk, instead of in parallel. `hf-xet` is designed for SSD/NVMe disks (using parallel writes with direct addressing). If you are using an HDD (spinning hard disk), setting this will change disk writes to be sequential instead of parallel. For slower hard disks, this can improve overall write performance, as the disk is not spinning to seek for parallel writes. ## Deprecated environment variables In order to standardize all environment variables within the Hugging Face ecosystem, some variables have been marked as deprecated. Although they remain functional, they no longer take precedence over their replacements. The following table outlines the deprecated variables and their corresponding alternatives: | Deprecated Variable | Replacement | | --------------------------- | ------------------ | | `HUGGINGFACE_HUB_CACHE` | `HF_HUB_CACHE` | | `HUGGINGFACE_ASSETS_CACHE` | `HF_ASSETS_CACHE` | | `HUGGING_FACE_HUB_TOKEN` | `HF_TOKEN` | | `HUGGINGFACE_HUB_VERBOSITY` | `HF_HUB_VERBOSITY` | ## From external tools Some environment variables are not specific to `huggingface_hub` but are still taken into account when they are set. ### DO_NOT_TRACK Boolean value. Equivalent to `HF_HUB_DISABLE_TELEMETRY`. When set to true, telemetry is globally disabled in the Hugging Face Python ecosystem (`transformers`, `diffusers`, `gradio`, etc.). See https://consoledonottrack.com/ for more details. ### NO_COLOR Boolean value. When set, `hf` CLI will not print any ANSI color. See [no-color.org](https://no-color.org/). ### XDG_CACHE_HOME Used only when `HF_HOME` is not set! This is the default way to configure where [user-specific non-essential (cached) data should be written](https://wiki.archlinux.org/title/XDG_Base_Directory) on linux machines. If `HF_HOME` is not set, the default home will be `"$XDG_CACHE_HOME/huggingface"` instead of `"~/.cache/huggingface"`. huggingface_hub-1.1.5/docs/source/en/package_reference/file_download.md000066400000000000000000000016571510763414300262330ustar00rootroot00000000000000 # Downloading files ## Download a single file ### hf_hub_download [[autodoc]] huggingface_hub.hf_hub_download ### hf_hub_url [[autodoc]] huggingface_hub.hf_hub_url ## Download a snapshot of the repo [[autodoc]] huggingface_hub.snapshot_download ## Get metadata about a file ### get_hf_file_metadata [[autodoc]] huggingface_hub.get_hf_file_metadata ### HfFileMetadata [[autodoc]] huggingface_hub.HfFileMetadata ## Caching The methods displayed above are designed to work with a caching system that prevents re-downloading files. The caching system was updated in v0.8.0 to become the central cache-system shared across libraries that depend on the Hub. Read the [cache-system guide](../guides/manage-cache) for a detailed presentation of caching at HF. huggingface_hub-1.1.5/docs/source/en/package_reference/hf_api.md000066400000000000000000000053421510763414300246460ustar00rootroot00000000000000 # HfApi Client Below is the documentation for the `HfApi` class, which serves as a Python wrapper for the Hugging Face Hub's API. All methods from the `HfApi` are also accessible from the package's root directly. Both approaches are detailed below. Using the root method is more straightforward but the [`HfApi`] class gives you more flexibility. In particular, you can pass a token that will be reused in all HTTP calls. This is different from `hf auth login` or [`login`] as the token is not persisted on the machine. It is also possible to provide a different endpoint or configure a custom user-agent. ```python from huggingface_hub import HfApi, list_models # Use root method models = list_models() # Or configure a HfApi client hf_api = HfApi( endpoint="https://huggingface.co", # Can be a Private Hub endpoint. token="hf_xxx", # Token is not persisted on the machine. ) models = hf_api.list_models() ``` ## HfApi [[autodoc]] HfApi ## API Dataclasses ### AccessRequest [[autodoc]] huggingface_hub.hf_api.AccessRequest ### CommitInfo [[autodoc]] huggingface_hub.hf_api.CommitInfo ### DatasetInfo [[autodoc]] huggingface_hub.hf_api.DatasetInfo ### DryRunFileInfo [[autodoc]] huggingface_hub.hf_api.DryRunFileInfo ### GitRefInfo [[autodoc]] huggingface_hub.hf_api.GitRefInfo ### GitCommitInfo [[autodoc]] huggingface_hub.hf_api.GitCommitInfo ### GitRefs [[autodoc]] huggingface_hub.hf_api.GitRefs ### InferenceProviderMapping [[autodoc]] huggingface_hub.hf_api.InferenceProviderMapping ### LFSFileInfo [[autodoc]] huggingface_hub.hf_api.LFSFileInfo ### ModelInfo [[autodoc]] huggingface_hub.hf_api.ModelInfo ### RepoSibling [[autodoc]] huggingface_hub.hf_api.RepoSibling ### RepoFile [[autodoc]] huggingface_hub.hf_api.RepoFile ### RepoUrl [[autodoc]] huggingface_hub.hf_api.RepoUrl ### SafetensorsRepoMetadata [[autodoc]] huggingface_hub.utils.SafetensorsRepoMetadata ### SafetensorsFileMetadata [[autodoc]] huggingface_hub.utils.SafetensorsFileMetadata ### SpaceInfo [[autodoc]] huggingface_hub.hf_api.SpaceInfo ### TensorInfo [[autodoc]] huggingface_hub.utils.TensorInfo ### User [[autodoc]] huggingface_hub.hf_api.User ### UserLikes [[autodoc]] huggingface_hub.hf_api.UserLikes ### WebhookInfo [[autodoc]] huggingface_hub.hf_api.WebhookInfo ### WebhookWatchedItem [[autodoc]] huggingface_hub.hf_api.WebhookWatchedItem ## CommitOperation Below are the supported values for [`CommitOperation`]: [[autodoc]] CommitOperationAdd [[autodoc]] CommitOperationDelete [[autodoc]] CommitOperationCopy ## CommitScheduler [[autodoc]] CommitScheduler huggingface_hub-1.1.5/docs/source/en/package_reference/hf_file_system.md000066400000000000000000000013601510763414300264140ustar00rootroot00000000000000 # Filesystem API The `HfFileSystem` class provides a pythonic file interface to the Hugging Face Hub based on [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/). ## HfFileSystem `HfFileSystem` is based on [fsspec](https://filesystem-spec.readthedocs.io/en/latest/), so it is compatible with most of the APIs that it offers. For more details, check out [our guide](../guides/hf_file_system) and fsspec's [API Reference](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem). [[autodoc]] HfFileSystem - __init__ - all huggingface_hub-1.1.5/docs/source/en/package_reference/inference_client.md000066400000000000000000000040621510763414300267120ustar00rootroot00000000000000 # Inference Inference is the process of using a trained model to make predictions on new data. Because this process can be compute-intensive, running on a dedicated or external service can be an interesting option. The `huggingface_hub` library provides a unified interface to run inference across multiple services for models hosted on the Hugging Face Hub: 1. [Inference Providers](https://huggingface.co/docs/inference-providers/index): a streamlined, unified access to hundreds of machine learning models, powered by our serverless inference partners. This new approach builds on our previous Serverless Inference API, offering more models, improved performance, and greater reliability thanks to world-class providers. Refer to the [documentation](https://huggingface.co/docs/inference-providers/index#partners) for a list of supported providers. 2. [Inference Endpoints](https://huggingface.co/docs/inference-endpoints/index): a product to easily deploy models to production. Inference is run by Hugging Face in a dedicated, fully managed infrastructure on a cloud provider of your choice. 3. Local endpoints: you can also run inference with local inference servers like [llama.cpp](https://github.com/ggerganov/llama.cpp), [Ollama](https://ollama.com/), [vLLM](https://github.com/vllm-project/vllm), [LiteLLM](https://docs.litellm.ai/docs/simple_proxy), or [Text Generation Inference (TGI)](https://github.com/huggingface/text-generation-inference) by connecting the client to these local endpoints. These services can be called with the [`InferenceClient`] object. Please refer to [this guide](../guides/inference) for more information on how to use it. ## Inference Client [[autodoc]] InferenceClient ## Async Inference Client An async version of the client is also provided, based on `asyncio` and `httpx`. [[autodoc]] AsyncInferenceClient ## InferenceTimeoutError [[autodoc]] InferenceTimeoutError huggingface_hub-1.1.5/docs/source/en/package_reference/inference_endpoints.md000066400000000000000000000040561510763414300274420ustar00rootroot00000000000000# Inference Endpoints Inference Endpoints provides a secure production solution to easily deploy models on a dedicated and autoscaling infrastructure managed by Hugging Face. An Inference Endpoint is built from a model from the [Hub](https://huggingface.co/models). This page is a reference for `huggingface_hub`'s integration with Inference Endpoints. For more information about the Inference Endpoints product, check out its [official documentation](https://huggingface.co/docs/inference-endpoints/index). > [!TIP] > Check out the [related guide](../guides/inference_endpoints) to learn how to use `huggingface_hub` to manage your Inference Endpoints programmatically. Inference Endpoints can be fully managed via API. The endpoints are documented with [Swagger](https://api.endpoints.huggingface.cloud/). The [`InferenceEndpoint`] class is a simple wrapper built on top on this API. ## Methods A subset of the Inference Endpoint features are implemented in [`HfApi`]: - [`get_inference_endpoint`] and [`list_inference_endpoints`] to get information about your Inference Endpoints - [`create_inference_endpoint`], [`update_inference_endpoint`] and [`delete_inference_endpoint`] to deploy and manage Inference Endpoints - [`pause_inference_endpoint`] and [`resume_inference_endpoint`] to pause and resume an Inference Endpoint - [`scale_to_zero_inference_endpoint`] to manually scale an Endpoint to 0 replicas ## InferenceEndpoint The main dataclass is [`InferenceEndpoint`]. It contains information about a deployed `InferenceEndpoint`, including its configuration and current state. Once deployed, you can run inference on the Endpoint using the [`InferenceEndpoint.client`] and [`InferenceEndpoint.async_client`] properties that respectively return an [`InferenceClient`] and an [`AsyncInferenceClient`] object. [[autodoc]] InferenceEndpoint - from_raw - client - async_client - all ## InferenceEndpointStatus [[autodoc]] InferenceEndpointStatus ## InferenceEndpointType [[autodoc]] InferenceEndpointType ## InferenceEndpointError [[autodoc]] InferenceEndpointError huggingface_hub-1.1.5/docs/source/en/package_reference/inference_types.md000066400000000000000000000227151510763414300266050ustar00rootroot00000000000000 # Inference types This page lists the types (e.g. dataclasses) available for each task supported on the Hugging Face Hub. Each task is specified using a JSON schema, and the types are generated from these schemas - with some customization due to Python requirements. Visit [@huggingface.js/tasks](https://github.com/huggingface/huggingface.js/tree/main/packages/tasks/src/tasks) to find the JSON schemas for each task. This part of the lib is still under development and will be improved in future releases. ## audio_classification [[autodoc]] huggingface_hub.AudioClassificationInput [[autodoc]] huggingface_hub.AudioClassificationOutputElement [[autodoc]] huggingface_hub.AudioClassificationParameters ## audio_to_audio [[autodoc]] huggingface_hub.AudioToAudioInput [[autodoc]] huggingface_hub.AudioToAudioOutputElement ## automatic_speech_recognition [[autodoc]] huggingface_hub.AutomaticSpeechRecognitionGenerationParameters [[autodoc]] huggingface_hub.AutomaticSpeechRecognitionInput [[autodoc]] huggingface_hub.AutomaticSpeechRecognitionOutput [[autodoc]] huggingface_hub.AutomaticSpeechRecognitionOutputChunk [[autodoc]] huggingface_hub.AutomaticSpeechRecognitionParameters ## chat_completion [[autodoc]] huggingface_hub.ChatCompletionInput [[autodoc]] huggingface_hub.ChatCompletionInputFunctionDefinition [[autodoc]] huggingface_hub.ChatCompletionInputFunctionName [[autodoc]] huggingface_hub.ChatCompletionInputJSONSchema [[autodoc]] huggingface_hub.ChatCompletionInputMessage [[autodoc]] huggingface_hub.ChatCompletionInputMessageChunk [[autodoc]] huggingface_hub.ChatCompletionInputResponseFormatJSONObject [[autodoc]] huggingface_hub.ChatCompletionInputResponseFormatJSONSchema [[autodoc]] huggingface_hub.ChatCompletionInputResponseFormatText [[autodoc]] huggingface_hub.ChatCompletionInputStreamOptions [[autodoc]] huggingface_hub.ChatCompletionInputTool [[autodoc]] huggingface_hub.ChatCompletionInputToolCall [[autodoc]] huggingface_hub.ChatCompletionInputToolChoiceClass [[autodoc]] huggingface_hub.ChatCompletionInputURL [[autodoc]] huggingface_hub.ChatCompletionOutput [[autodoc]] huggingface_hub.ChatCompletionOutputComplete [[autodoc]] huggingface_hub.ChatCompletionOutputFunctionDefinition [[autodoc]] huggingface_hub.ChatCompletionOutputLogprob [[autodoc]] huggingface_hub.ChatCompletionOutputLogprobs [[autodoc]] huggingface_hub.ChatCompletionOutputMessage [[autodoc]] huggingface_hub.ChatCompletionOutputToolCall [[autodoc]] huggingface_hub.ChatCompletionOutputTopLogprob [[autodoc]] huggingface_hub.ChatCompletionOutputUsage [[autodoc]] huggingface_hub.ChatCompletionStreamOutput [[autodoc]] huggingface_hub.ChatCompletionStreamOutputChoice [[autodoc]] huggingface_hub.ChatCompletionStreamOutputDelta [[autodoc]] huggingface_hub.ChatCompletionStreamOutputDeltaToolCall [[autodoc]] huggingface_hub.ChatCompletionStreamOutputFunction [[autodoc]] huggingface_hub.ChatCompletionStreamOutputLogprob [[autodoc]] huggingface_hub.ChatCompletionStreamOutputLogprobs [[autodoc]] huggingface_hub.ChatCompletionStreamOutputTopLogprob [[autodoc]] huggingface_hub.ChatCompletionStreamOutputUsage ## depth_estimation [[autodoc]] huggingface_hub.DepthEstimationInput [[autodoc]] huggingface_hub.DepthEstimationOutput ## document_question_answering [[autodoc]] huggingface_hub.DocumentQuestionAnsweringInput [[autodoc]] huggingface_hub.DocumentQuestionAnsweringInputData [[autodoc]] huggingface_hub.DocumentQuestionAnsweringOutputElement [[autodoc]] huggingface_hub.DocumentQuestionAnsweringParameters ## feature_extraction [[autodoc]] huggingface_hub.FeatureExtractionInput ## fill_mask [[autodoc]] huggingface_hub.FillMaskInput [[autodoc]] huggingface_hub.FillMaskOutputElement [[autodoc]] huggingface_hub.FillMaskParameters ## image_classification [[autodoc]] huggingface_hub.ImageClassificationInput [[autodoc]] huggingface_hub.ImageClassificationOutputElement [[autodoc]] huggingface_hub.ImageClassificationParameters ## image_segmentation [[autodoc]] huggingface_hub.ImageSegmentationInput [[autodoc]] huggingface_hub.ImageSegmentationOutputElement [[autodoc]] huggingface_hub.ImageSegmentationParameters ## image_to_image [[autodoc]] huggingface_hub.ImageToImageInput [[autodoc]] huggingface_hub.ImageToImageOutput [[autodoc]] huggingface_hub.ImageToImageParameters [[autodoc]] huggingface_hub.ImageToImageTargetSize ## image_to_text [[autodoc]] huggingface_hub.ImageToTextGenerationParameters [[autodoc]] huggingface_hub.ImageToTextInput [[autodoc]] huggingface_hub.ImageToTextOutput [[autodoc]] huggingface_hub.ImageToTextParameters ## image_to_video [[autodoc]] huggingface_hub.ImageToVideoInput [[autodoc]] huggingface_hub.ImageToVideoOutput [[autodoc]] huggingface_hub.ImageToVideoParameters [[autodoc]] huggingface_hub.ImageToVideoTargetSize ## object_detection [[autodoc]] huggingface_hub.ObjectDetectionBoundingBox [[autodoc]] huggingface_hub.ObjectDetectionInput [[autodoc]] huggingface_hub.ObjectDetectionOutputElement [[autodoc]] huggingface_hub.ObjectDetectionParameters ## question_answering [[autodoc]] huggingface_hub.QuestionAnsweringInput [[autodoc]] huggingface_hub.QuestionAnsweringInputData [[autodoc]] huggingface_hub.QuestionAnsweringOutputElement [[autodoc]] huggingface_hub.QuestionAnsweringParameters ## sentence_similarity [[autodoc]] huggingface_hub.SentenceSimilarityInput [[autodoc]] huggingface_hub.SentenceSimilarityInputData ## summarization [[autodoc]] huggingface_hub.SummarizationInput [[autodoc]] huggingface_hub.SummarizationOutput [[autodoc]] huggingface_hub.SummarizationParameters ## table_question_answering [[autodoc]] huggingface_hub.TableQuestionAnsweringInput [[autodoc]] huggingface_hub.TableQuestionAnsweringInputData [[autodoc]] huggingface_hub.TableQuestionAnsweringOutputElement [[autodoc]] huggingface_hub.TableQuestionAnsweringParameters ## text2text_generation [[autodoc]] huggingface_hub.Text2TextGenerationInput [[autodoc]] huggingface_hub.Text2TextGenerationOutput [[autodoc]] huggingface_hub.Text2TextGenerationParameters ## text_classification [[autodoc]] huggingface_hub.TextClassificationInput [[autodoc]] huggingface_hub.TextClassificationOutputElement [[autodoc]] huggingface_hub.TextClassificationParameters ## text_generation [[autodoc]] huggingface_hub.TextGenerationInput [[autodoc]] huggingface_hub.TextGenerationInputGenerateParameters [[autodoc]] huggingface_hub.TextGenerationInputGrammarType [[autodoc]] huggingface_hub.TextGenerationOutput [[autodoc]] huggingface_hub.TextGenerationOutputBestOfSequence [[autodoc]] huggingface_hub.TextGenerationOutputDetails [[autodoc]] huggingface_hub.TextGenerationOutputPrefillToken [[autodoc]] huggingface_hub.TextGenerationOutputToken [[autodoc]] huggingface_hub.TextGenerationStreamOutput [[autodoc]] huggingface_hub.TextGenerationStreamOutputStreamDetails [[autodoc]] huggingface_hub.TextGenerationStreamOutputToken ## text_to_audio [[autodoc]] huggingface_hub.TextToAudioGenerationParameters [[autodoc]] huggingface_hub.TextToAudioInput [[autodoc]] huggingface_hub.TextToAudioOutput [[autodoc]] huggingface_hub.TextToAudioParameters ## text_to_image [[autodoc]] huggingface_hub.TextToImageInput [[autodoc]] huggingface_hub.TextToImageOutput [[autodoc]] huggingface_hub.TextToImageParameters ## text_to_speech [[autodoc]] huggingface_hub.TextToSpeechGenerationParameters [[autodoc]] huggingface_hub.TextToSpeechInput [[autodoc]] huggingface_hub.TextToSpeechOutput [[autodoc]] huggingface_hub.TextToSpeechParameters ## text_to_video [[autodoc]] huggingface_hub.TextToVideoInput [[autodoc]] huggingface_hub.TextToVideoOutput [[autodoc]] huggingface_hub.TextToVideoParameters ## token_classification [[autodoc]] huggingface_hub.TokenClassificationInput [[autodoc]] huggingface_hub.TokenClassificationOutputElement [[autodoc]] huggingface_hub.TokenClassificationParameters ## translation [[autodoc]] huggingface_hub.TranslationInput [[autodoc]] huggingface_hub.TranslationOutput [[autodoc]] huggingface_hub.TranslationParameters ## video_classification [[autodoc]] huggingface_hub.VideoClassificationInput [[autodoc]] huggingface_hub.VideoClassificationOutputElement [[autodoc]] huggingface_hub.VideoClassificationParameters ## visual_question_answering [[autodoc]] huggingface_hub.VisualQuestionAnsweringInput [[autodoc]] huggingface_hub.VisualQuestionAnsweringInputData [[autodoc]] huggingface_hub.VisualQuestionAnsweringOutputElement [[autodoc]] huggingface_hub.VisualQuestionAnsweringParameters ## zero_shot_classification [[autodoc]] huggingface_hub.ZeroShotClassificationInput [[autodoc]] huggingface_hub.ZeroShotClassificationOutputElement [[autodoc]] huggingface_hub.ZeroShotClassificationParameters ## zero_shot_image_classification [[autodoc]] huggingface_hub.ZeroShotImageClassificationInput [[autodoc]] huggingface_hub.ZeroShotImageClassificationOutputElement [[autodoc]] huggingface_hub.ZeroShotImageClassificationParameters ## zero_shot_object_detection [[autodoc]] huggingface_hub.ZeroShotObjectDetectionBoundingBox [[autodoc]] huggingface_hub.ZeroShotObjectDetectionInput [[autodoc]] huggingface_hub.ZeroShotObjectDetectionOutputElement [[autodoc]] huggingface_hub.ZeroShotObjectDetectionParameters huggingface_hub-1.1.5/docs/source/en/package_reference/jobs.md000066400000000000000000000011621510763414300243510ustar00rootroot00000000000000 # Jobs Check the [`HfApi`] documentation page for the reference of methods to manage your Jobs on the Hub. - Run a Job: [`run_job`] - Fetch logs: [`fetch_job_logs`] - Inspect Job: [`inspect_job`] - List Jobs: [`list_jobs`] - Cancel Job: [`cancel_job`] - Run a UV Job: [`run_uv_job`] ## Data structures ### JobInfo [[autodoc]] JobInfo ### JobOwner [[autodoc]] JobOwner ### JobStage [[autodoc]] JobStage ### JobStatus [[autodoc]] JobStatus huggingface_hub-1.1.5/docs/source/en/package_reference/mcp.md000066400000000000000000000016631510763414300242010ustar00rootroot00000000000000# MCP Client The `huggingface_hub` library now includes an [`MCPClient`], designed to empower Large Language Models (LLMs) with the ability to interact with external Tools via the [Model Context Protocol](https://modelcontextprotocol.io) (MCP). This client extends an [`AsyncInferenceClient`] to seamlessly integrate Tool usage. The [`MCPClient`] connects to MCP servers (local `stdio` scripts or remote `http`/`sse` services) that expose tools. It feeds these tools to an LLM (via [`AsyncInferenceClient`]). If the LLM decides to use a tool, [`MCPClient`] manages the execution request to the MCP server and relays the Tool's output back to the LLM, often streaming results in real-time. We also provide a higher-level [`Agent`] class. This 'Tiny Agent' simplifies creating conversational Agents by managing the chat loop and state, acting as a wrapper around [`MCPClient`]. ## MCP Client [[autodoc]] MCPClient ## Agent [[autodoc]] Agenthuggingface_hub-1.1.5/docs/source/en/package_reference/mixins.md000066400000000000000000000013331510763414300247230ustar00rootroot00000000000000 # Mixins & serialization methods ## Mixins The `huggingface_hub` library offers a range of mixins that can be used as a parent class for your objects, in order to provide simple uploading and downloading functions. Check out our [integration guide](../guides/integrations) to learn how to integrate any ML framework with the Hub. ### Generic [[autodoc]] ModelHubMixin - all - _save_pretrained - _from_pretrained ### PyTorch [[autodoc]] PyTorchModelHubMixin ### Fastai [[autodoc]] from_pretrained_fastai [[autodoc]] push_to_hub_fastai huggingface_hub-1.1.5/docs/source/en/package_reference/oauth.md000066400000000000000000000053051510763414300245370ustar00rootroot00000000000000 # OAuth and FastAPI OAuth is an open standard for access delegation, commonly used to grant applications limited access to a user's information without exposing their credentials. When combined with FastAPI it allows you to build secure APIs that allow users to log in using external identity providers like Google or GitHub. In a usual scenario: - FastAPI will define the API endpoints and handles the HTTP requests. - OAuth is integrated using libraries like fastapi.security or external tools like Authlib. - When a user wants to log in, FastAPI redirects them to the OAuth provider’s login page. - After successful login, the provider redirects back with a token. - FastAPI verifies this token and uses it to authorize the user or fetch user profile data. This approach helps avoid handling passwords directly and offloads identity management to trusted providers. # Hugging Face OAuth Integration in FastAPI This module provides tools to integrate Hugging Face OAuth into a FastAPI application. It enables user authentication using the Hugging Face platform including mocked behavior for local development and real OAuth flow for Spaces. ## OAuth Overview The `attach_huggingface_oauth` function adds login, logout, and callback endpoints to your FastAPI app. When used in a Space, it connects to the Hugging Face OAuth system. When used locally it will inject a mocked user. Click here to learn more about [adding a Sign-In with HF option to your Space](https://huggingface.co/docs/hub/en/spaces-oauth) ### How to use it? ```python from huggingface_hub import attach_huggingface_oauth, parse_huggingface_oauth from fastapi import FastAPI, Request app = FastAPI() attach_huggingface_oauth(app) @app.get("/") def greet_json(request: Request): oauth_info = parse_huggingface_oauth(request) if oauth_info is None: return {"msg": "Not logged in!"} return {"msg": f"Hello, {oauth_info.user_info.preferred_username}!"} ``` > [!TIP] > You might also be interested in [a practical example that demonstrates OAuth in action](https://huggingface.co/spaces/Wauplin/fastapi-oauth/blob/main/app.py). > For a more comprehensive implementation, check out [medoidai/GiveBackGPT](https://huggingface.co/spaces/medoidai/GiveBackGPT) Space which implements HF OAuth in a full-scale application. ### attach_huggingface_oauth [[autodoc]] attach_huggingface_oauth ### parse_huggingface_oauth [[autodoc]] parse_huggingface_oauth ### OAuthOrgInfo [[autodoc]] OAuthOrgInfo ### OAuthUserInfo [[autodoc]] OAuthUserInfo ### OAuthInfo [[autodoc]] OAuthInfo huggingface_hub-1.1.5/docs/source/en/package_reference/overview.md000066400000000000000000000004441510763414300252640ustar00rootroot00000000000000 # Overview This section contains an exhaustive and technical description of `huggingface_hub` classes and methods. huggingface_hub-1.1.5/docs/source/en/package_reference/serialization.md000066400000000000000000000175421510763414300263020ustar00rootroot00000000000000 # Serialization `huggingface_hub` provides helpers to save and load ML model weights in a standardized way. This part of the library is still under development and will be improved in future releases. The goal is to harmonize how weights are saved and loaded across the Hub, both to remove code duplication across libraries and to establish consistent conventions. ## DDUF file format DDUF is a file format designed for diffusion models. It allows saving all the information to run a model in a single file. This work is inspired by the [GGUF](https://github.com/ggerganov/ggml/blob/master/docs/gguf.md) format. `huggingface_hub` provides helpers to save and load DDUF files, ensuring the file format is respected. > [!WARNING] > This is a very early version of the parser. The API and implementation can evolve in the near future. > > The parser currently does very little validation. For more details about the file format, check out https://github.com/huggingface/huggingface.js/tree/main/packages/dduf. ### How to write a DDUF file? Here is how to export a folder containing different parts of a diffusion model using [`export_folder_as_dduf`]: ```python # Export a folder as a DDUF file >>> from huggingface_hub import export_folder_as_dduf >>> export_folder_as_dduf("FLUX.1-dev.dduf", folder_path="path/to/FLUX.1-dev") ``` For more flexibility, you can use [`export_entries_as_dduf`] and pass a list of files to include in the final DDUF file: ```python # Export specific files from the local disk. >>> from huggingface_hub import export_entries_as_dduf >>> export_entries_as_dduf( ... dduf_path="stable-diffusion-v1-4-FP16.dduf", ... entries=[ # List entries to add to the DDUF file (here, only FP16 weights) ... ("model_index.json", "path/to/model_index.json"), ... ("vae/config.json", "path/to/vae/config.json"), ... ("vae/diffusion_pytorch_model.fp16.safetensors", "path/to/vae/diffusion_pytorch_model.fp16.safetensors"), ... ("text_encoder/config.json", "path/to/text_encoder/config.json"), ... ("text_encoder/model.fp16.safetensors", "path/to/text_encoder/model.fp16.safetensors"), ... # ... add more entries here ... ] ... ) ``` The `entries` parameter also supports passing an iterable of paths or bytes. This can prove useful if you have a loaded model and want to serialize it directly into a DDUF file instead of having to serialize each component to disk first and then as a DDUF file. Here is an example of how a `StableDiffusionPipeline` can be serialized as DDUF: ```python # Export state_dicts one by one from a loaded pipeline >>> from diffusers import DiffusionPipeline >>> from typing import Generator, Tuple >>> import safetensors.torch >>> from huggingface_hub import export_entries_as_dduf >>> pipe = DiffusionPipeline.from_pretrained("CompVis/stable-diffusion-v1-4") ... # ... do some work with the pipeline >>> def as_entries(pipe: DiffusionPipeline) -> Generator[Tuple[str, bytes], None, None]: ... # Build a generator that yields the entries to add to the DDUF file. ... # The first element of the tuple is the filename in the DDUF archive (must use UNIX separator!). The second element is the content of the file. ... # Entries will be evaluated lazily when the DDUF file is created (only 1 entry is loaded in memory at a time) ... yield "vae/config.json", pipe.vae.to_json_string().encode() ... yield "vae/diffusion_pytorch_model.safetensors", safetensors.torch.save(pipe.vae.state_dict()) ... yield "text_encoder/config.json", pipe.text_encoder.config.to_json_string().encode() ... yield "text_encoder/model.safetensors", safetensors.torch.save(pipe.text_encoder.state_dict()) ... # ... add more entries here >>> export_entries_as_dduf(dduf_path="stable-diffusion-v1-4.dduf", entries=as_entries(pipe)) ``` **Note:** in practice, `diffusers` provides a method to directly serialize a pipeline in a DDUF file. The snippet above is only meant as an example. ### How to read a DDUF file? ```python >>> import json >>> import safetensors.torch >>> from huggingface_hub import read_dduf_file # Read DDUF metadata >>> dduf_entries = read_dduf_file("FLUX.1-dev.dduf") # Returns a mapping filename <> DDUFEntry >>> dduf_entries["model_index.json"] DDUFEntry(filename='model_index.json', offset=66, length=587) # Load model index as JSON >>> json.loads(dduf_entries["model_index.json"].read_text()) {'_class_name': 'FluxPipeline', '_diffusers_version': '0.32.0.dev0', '_name_or_path': 'black-forest-labs/FLUX.1-dev', 'scheduler': ['diffusers', 'FlowMatchEulerDiscreteScheduler'], 'text_encoder': ['transformers', 'CLIPTextModel'], 'text_encoder_2': ['transformers', 'T5EncoderModel'], 'tokenizer': ['transformers', 'CLIPTokenizer'], 'tokenizer_2': ['transformers', 'T5TokenizerFast'], 'transformer': ['diffusers', 'FluxTransformer2DModel'], 'vae': ['diffusers', 'AutoencoderKL']} # Load VAE weights using safetensors >>> with dduf_entries["vae/diffusion_pytorch_model.safetensors"].as_mmap() as mm: ... state_dict = safetensors.torch.load(mm) ``` ### Helpers [[autodoc]] huggingface_hub.export_entries_as_dduf [[autodoc]] huggingface_hub.export_folder_as_dduf [[autodoc]] huggingface_hub.read_dduf_file [[autodoc]] huggingface_hub.DDUFEntry ### Errors [[autodoc]] huggingface_hub.errors.DDUFError [[autodoc]] huggingface_hub.errors.DDUFCorruptedFileError [[autodoc]] huggingface_hub.errors.DDUFExportError [[autodoc]] huggingface_hub.errors.DDUFInvalidEntryNameError ## Saving tensors The main helper of the `serialization` module takes a torch `nn.Module` as input and saves it to disk. It handles the logic to save shared tensors (see [safetensors explanation](https://huggingface.co/docs/safetensors/torch_shared_tensors)) as well as logic to split the state dictionary into shards, using [`split_torch_state_dict_into_shards`] under the hood. At the moment, only `torch` framework is supported. If you want to save a state dictionary (e.g. a mapping between layer names and related tensors) instead of a `nn.Module`, you can use [`save_torch_state_dict`] which provides the same features. This is useful for example if you want to apply custom logic to the state dict before saving it. ### save_torch_model [[autodoc]] huggingface_hub.save_torch_model ### save_torch_state_dict [[autodoc]] huggingface_hub.save_torch_state_dict The `serialization` module also contains low-level helpers to split a state dictionary into several shards, while creating a proper index in the process. These helpers are available for `torch` tensors and are designed to be easily extended to any other ML frameworks. ### split_torch_state_dict_into_shards [[autodoc]] huggingface_hub.split_torch_state_dict_into_shards ### split_state_dict_into_shards_factory This is the underlying factory from which each framework-specific helper is derived. In practice, you are not expected to use this factory directly except if you need to adapt it to a framework that is not yet supported. If that is the case, please let us know by [opening a new issue](https://github.com/huggingface/huggingface_hub/issues/new) on the `huggingface_hub` repo. [[autodoc]] huggingface_hub.split_state_dict_into_shards_factory ## Loading tensors The loading helpers support both single-file and sharded checkpoints in either safetensors or pickle format. [`load_torch_model`] takes a `nn.Module` and a checkpoint path (either a single file or a directory) as input and load the weights into the model. ### load_torch_model [[autodoc]] huggingface_hub.load_torch_model ### load_state_dict_from_file [[autodoc]] huggingface_hub.load_state_dict_from_file ## Tensors helpers ### get_torch_storage_id [[autodoc]] huggingface_hub.get_torch_storage_id ### get_torch_storage_size [[autodoc]] huggingface_hub.get_torch_storage_sizehuggingface_hub-1.1.5/docs/source/en/package_reference/space_runtime.md000066400000000000000000000014731510763414300262570ustar00rootroot00000000000000 # Managing your Space runtime Check the [`HfApi`] documentation page for the reference of methods to manage your Space on the Hub. - Duplicate a Space: [`duplicate_space`] - Fetch current runtime: [`get_space_runtime`] - Manage secrets: [`add_space_secret`] and [`delete_space_secret`] - Manage hardware: [`request_space_hardware`] - Manage state: [`pause_space`], [`restart_space`], [`set_space_sleep_time`] ## Data structures ### SpaceRuntime [[autodoc]] SpaceRuntime ### SpaceHardware [[autodoc]] SpaceHardware ### SpaceStage [[autodoc]] SpaceStage ### SpaceStorage [[autodoc]] SpaceStorage ### SpaceVariable [[autodoc]] SpaceVariable huggingface_hub-1.1.5/docs/source/en/package_reference/tensorboard.md000066400000000000000000000022051510763414300257350ustar00rootroot00000000000000 # TensorBoard logger TensorBoard is a visualization toolkit for machine learning experimentation. TensorBoard allows tracking and visualizing metrics such as loss and accuracy, visualizing the model graph, viewing histograms, displaying images and much more. TensorBoard is well integrated with the Hugging Face Hub. The Hub automatically detects TensorBoard traces (such as `tfevents`) when pushed to the Hub which starts an instance to visualize them. To get more information about TensorBoard integration on the Hub, check out [this guide](https://huggingface.co/docs/hub/tensorboard). To benefit from this integration, `huggingface_hub` provides a custom logger to push logs to the Hub. It works as a drop-in replacement for [SummaryWriter](https://tensorboardx.readthedocs.io/en/latest/tensorboard.html) with no extra code needed. Traces are still saved locally and a background job push them to the Hub at regular interval. ## HFSummaryWriter [[autodoc]] HFSummaryWriter huggingface_hub-1.1.5/docs/source/en/package_reference/utilities.md000066400000000000000000000245771510763414300254460ustar00rootroot00000000000000 # Utilities ## Configure logging The `huggingface_hub` package exposes a `logging` utility to control the logging level of the package itself. You can import it as such: ```py from huggingface_hub import logging ``` Then, you may define the verbosity in order to update the amount of logs you'll see: ```python from huggingface_hub import logging logging.set_verbosity_error() logging.set_verbosity_warning() logging.set_verbosity_info() logging.set_verbosity_debug() logging.set_verbosity(...) ``` The levels should be understood as follows: - `error`: only show critical logs about usage which may result in an error or unexpected behavior. - `warning`: show logs that aren't critical but usage may result in unintended behavior. Additionally, important informative logs may be shown. - `info`: show most logs, including some verbose logging regarding what is happening under the hood. If something is behaving in an unexpected manner, we recommend switching the verbosity level to this in order to get more information. - `debug`: show all logs, including some internal logs which may be used to track exactly what's happening under the hood. [[autodoc]] logging.get_verbosity [[autodoc]] logging.set_verbosity [[autodoc]] logging.set_verbosity_info [[autodoc]] logging.set_verbosity_debug [[autodoc]] logging.set_verbosity_warning [[autodoc]] logging.set_verbosity_error [[autodoc]] logging.disable_propagation [[autodoc]] logging.enable_propagation ### Repo-specific helper methods The methods exposed below are relevant when modifying modules from the `huggingface_hub` library itself. Using these shouldn't be necessary if you use `huggingface_hub` and you don't modify them. [[autodoc]] logging.get_logger ## Configure progress bars Progress bars are a useful tool to display information to the user while a long-running task is being executed (e.g. when downloading or uploading files). `huggingface_hub` exposes a [`~utils.tqdm`] wrapper to display progress bars in a consistent way across the library. By default, progress bars are enabled. You can disable them globally by setting `HF_HUB_DISABLE_PROGRESS_BARS` environment variable. You can also enable/disable them using [`~utils.enable_progress_bars`] and [`~utils.disable_progress_bars`]. If set, the environment variable has priority on the helpers. ```py >>> from huggingface_hub import snapshot_download >>> from huggingface_hub.utils import are_progress_bars_disabled, disable_progress_bars, enable_progress_bars >>> # Disable progress bars globally >>> disable_progress_bars() >>> # Progress bar will not be shown ! >>> snapshot_download("gpt2") >>> are_progress_bars_disabled() True >>> # Re-enable progress bars globally >>> enable_progress_bars() ``` ### Group-specific control of progress bars You can also enable or disable progress bars for specific groups. This allows you to manage progress bar visibility more granularly within different parts of your application or library. When a progress bar is disabled for a group, all subgroups under it are also affected unless explicitly overridden. ```py # Disable progress bars for a specific group >>> disable_progress_bars("peft.foo") >>> assert not are_progress_bars_disabled("peft") >>> assert not are_progress_bars_disabled("peft.something") >>> assert are_progress_bars_disabled("peft.foo") >>> assert are_progress_bars_disabled("peft.foo.bar") # Re-enable progress bars for a subgroup >>> enable_progress_bars("peft.foo.bar") >>> assert are_progress_bars_disabled("peft.foo") >>> assert not are_progress_bars_disabled("peft.foo.bar") # Use groups with tqdm # No progress bar for `name="peft.foo"` >>> for _ in tqdm(range(5), name="peft.foo"): ... pass # Progress bar will be shown for `name="peft.foo.bar"` >>> for _ in tqdm(range(5), name="peft.foo.bar"): ... pass 100%|███████████████████████████████████████| 5/5 [00:00<00:00, 117817.53it/s] ``` ### are_progress_bars_disabled [[autodoc]] huggingface_hub.utils.are_progress_bars_disabled ### disable_progress_bars [[autodoc]] huggingface_hub.utils.disable_progress_bars ### enable_progress_bars [[autodoc]] huggingface_hub.utils.enable_progress_bars ## Configuring the HTTP Backend In `huggingface_hub` v0.x, HTTP requests were handled with `requests`, and configuration was done via `configure_http_backend`. Since we now use `httpx`, configuration works differently: you must provide a factory function that takes no arguments and returns an `httpx.Client`. You can review the [default implementation here](https://github.com/huggingface/huggingface_hub/blob/v1.0-release/src/huggingface_hub/utils/_http.py) to see which parameters are used by default. In some setups, you may need to control how HTTP requests are made, for example when working behind a proxy. The `huggingface_hub` library allows you to configure this globally with [`set_client_factory`]. After configuration, all requests to the Hub will use your custom settings. Since `huggingface_hub` relies on `httpx.Client` under the hood, you can check the [`httpx` documentation](https://www.python-httpx.org/advanced/clients/) for details on available parameters. If you are building a third-party library and need to make direct requests to the Hub, use [`get_session`] to obtain a correctly configured `httpx` client. Replace any direct `httpx.get(...)` calls with `get_session().get(...)` to ensure proper behavior. [[autodoc]] set_client_factory [[autodoc]] get_session In rare cases, you may want to manually close the current session (for example, after a transient `SSLError`). You can do this with [`close_session`]. A new session will automatically be created on the next call to [`get_session`]. Sessions are always closed automatically when the process exits. [[autodoc]] close_session For async code, use [`set_async_client_factory`] to configure an `httpx.AsyncClient` and [`get_async_session`] to retrieve one. [[autodoc]] set_async_client_factory [[autodoc]] get_async_session Unlike the synchronous client, the lifecycle of the async client is not managed automatically. Use an async context manager to handle it properly. ## Handle HTTP errors `huggingface_hub` defines its own HTTP errors to refine the `HTTPError` raised by `requests` with additional information sent back by the server. ### Raise for status [`~utils.hf_raise_for_status`] is meant to be the central method to "raise for status" from any request made to the Hub. It wraps the base `requests.raise_for_status` to provide additional information. Any `HTTPError` thrown is converted into a `HfHubHTTPError`. ```py import requests from huggingface_hub.utils import hf_raise_for_status, HfHubHTTPError response = requests.post(...) try: hf_raise_for_status(response) except HfHubHTTPError as e: print(str(e)) # formatted message e.request_id, e.server_message # details returned by server # Complete the error message with additional information once it's raised e.append_to_message("\n`create_commit` expects the repository to exist.") raise ``` [[autodoc]] huggingface_hub.utils.hf_raise_for_status ### HTTP errors Here is a list of HTTP errors thrown in `huggingface_hub`. #### HfHubHTTPError `HfHubHTTPError` is the parent class for any HF Hub HTTP error. It takes care of parsing the server response and format the error message to provide as much information to the user as possible. [[autodoc]] huggingface_hub.errors.HfHubHTTPError #### RepositoryNotFoundError [[autodoc]] huggingface_hub.errors.RepositoryNotFoundError #### GatedRepoError [[autodoc]] huggingface_hub.errors.GatedRepoError #### RevisionNotFoundError [[autodoc]] huggingface_hub.errors.RevisionNotFoundError #### BadRequestError [[autodoc]] huggingface_hub.errors.BadRequestError #### EntryNotFoundError [[autodoc]] huggingface_hub.errors.EntryNotFoundError #### RemoteEntryNotFoundError [[autodoc]] huggingface_hub.errors.RemoteEntryNotFoundError #### LocalEntryNotFoundError [[autodoc]] huggingface_hub.errors.LocalEntryNotFoundError #### OfflineModeIsEnabled [[autodoc]] huggingface_hub.errors.OfflineModeIsEnabled ## Telemetry `huggingface_hub` includes a helper to send telemetry data. This information helps us debug issues and prioritize new features. Users can disable telemetry collection at any time by setting the `HF_HUB_DISABLE_TELEMETRY=1` environment variable. Telemetry is also disabled in offline mode (i.e. when setting HF_HUB_OFFLINE=1). If you are maintainer of a third-party library, sending telemetry data is as simple as making a call to [`send_telemetry`]. Data is sent in a separate thread to reduce as much as possible the impact for users. [[autodoc]] utils.send_telemetry ## Validators `huggingface_hub` includes custom validators to validate method arguments automatically. Validation is inspired by the work done in [Pydantic](https://pydantic-docs.helpmanual.io/) to validate type hints but with more limited features. ### Generic decorator [`~utils.validate_hf_hub_args`] is a generic decorator to encapsulate methods that have arguments following `huggingface_hub`'s naming. By default, all arguments that has a validator implemented will be validated. If an input is not valid, a [`~utils.HFValidationError`] is thrown. Only the first non-valid value throws an error and stops the validation process. Usage: ```py >>> from huggingface_hub.utils import validate_hf_hub_args >>> @validate_hf_hub_args ... def my_cool_method(repo_id: str): ... print(repo_id) >>> my_cool_method(repo_id="valid_repo_id") valid_repo_id >>> my_cool_method("other..repo..id") huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'. >>> my_cool_method(repo_id="other..repo..id") huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'. ``` #### validate_hf_hub_args [[autodoc]] utils.validate_hf_hub_args #### HFValidationError [[autodoc]] utils.HFValidationError ### Argument validators Validators can also be used individually. Here is a list of all arguments that can be validated. #### repo_id [[autodoc]] utils.validate_repo_id #### smoothly_deprecate_legacy_arguments Not exactly a validator, but ran as well. [[autodoc]] utils._validators.smoothly_deprecate_legacy_arguments huggingface_hub-1.1.5/docs/source/en/package_reference/webhooks_server.md000066400000000000000000000053171510763414300266310ustar00rootroot00000000000000 # Webhooks Server Webhooks are a foundation for MLOps-related features. They allow you to listen for new changes on specific repos or to all repos belonging to particular users/organizations you're interested in following. To learn more about webhooks on the Huggingface Hub, you can read the Webhooks [guide](https://huggingface.co/docs/hub/webhooks). > [!TIP] > Check out this [guide](../guides/webhooks_server) for a step-by-step tutorial on how to set up your webhooks server and > deploy it as a Space. > [!WARNING] > This is an experimental feature. This means that we are still working on improving the API. Breaking changes might be > introduced in the future without prior notice. Make sure to pin the version of `huggingface_hub` in your requirements. > A warning is triggered when you use an experimental feature. You can disable it by setting `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` as an environment variable. ## Server The server is a [Gradio](https://gradio.app/) app. It has a UI to display instructions for you or your users and an API to listen to webhooks. Implementing a webhook endpoint is as simple as decorating a function. You can then debug it by redirecting the Webhooks to your machine (using a Gradio tunnel) before deploying it to a Space. ### WebhooksServer [[autodoc]] huggingface_hub.WebhooksServer ### @webhook_endpoint [[autodoc]] huggingface_hub.webhook_endpoint ## Payload [`WebhookPayload`] is the main data structure that contains the payload from Webhooks. This is a `pydantic` class which makes it very easy to use with FastAPI. If you pass it as a parameter to a webhook endpoint, it will be automatically validated and parsed as a Python object. For more information about webhooks payload, you can refer to the Webhooks Payload [guide](https://huggingface.co/docs/hub/webhooks#webhook-payloads). [[autodoc]] huggingface_hub.WebhookPayload ### WebhookPayload [[autodoc]] huggingface_hub.WebhookPayload ### WebhookPayloadComment [[autodoc]] huggingface_hub.WebhookPayloadComment ### WebhookPayloadDiscussion [[autodoc]] huggingface_hub.WebhookPayloadDiscussion ### WebhookPayloadDiscussionChanges [[autodoc]] huggingface_hub.WebhookPayloadDiscussionChanges ### WebhookPayloadEvent [[autodoc]] huggingface_hub.WebhookPayloadEvent ### WebhookPayloadMovedTo [[autodoc]] huggingface_hub.WebhookPayloadMovedTo ### WebhookPayloadRepo [[autodoc]] huggingface_hub.WebhookPayloadRepo ### WebhookPayloadUrl [[autodoc]] huggingface_hub.WebhookPayloadUrl ### WebhookPayloadWebhook [[autodoc]] huggingface_hub.WebhookPayloadWebhook huggingface_hub-1.1.5/docs/source/en/quick-start.md000066400000000000000000000171041510763414300222550ustar00rootroot00000000000000 # Quickstart The [Hugging Face Hub](https://huggingface.co/) is the go-to place for sharing machine learning models, demos, datasets, and metrics. `huggingface_hub` library helps you interact with the Hub without leaving your development environment. You can create and manage repositories easily, download and upload files, and get useful model and dataset metadata from the Hub. ## Installation To get started, install the `huggingface_hub` library: ```bash pip install --upgrade huggingface_hub ``` For more details, check out the [installation](installation) guide. ## Download files Repositories on the Hub are git version controlled, and users can download a single file or the whole repository. You can use the [`hf_hub_download`] function to download files. This function will download and cache a file on your local disk. The next time you need that file, it will load from your cache, so you don't need to re-download it. You will need the repository id and the filename of the file you want to download. For example, to download the [Pegasus](https://huggingface.co/google/pegasus-xsum) model configuration file: ```py >>> from huggingface_hub import hf_hub_download >>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json") ``` To download a specific version of the file, use the `revision` parameter to specify the branch name, tag, or commit hash. If you choose to use the commit hash, it must be the full-length hash instead of the shorter 7-character commit hash: ```py >>> from huggingface_hub import hf_hub_download >>> hf_hub_download( ... repo_id="google/pegasus-xsum", ... filename="config.json", ... revision="4d33b01d79672f27f001f6abade33f22d993b151" ... ) ``` For more details and options, see the API reference for [`hf_hub_download`]. ## Authentication In a lot of cases, you must be authenticated with a Hugging Face account to interact with the Hub: download private repos, upload files, create PRs,... [Create an account](https://huggingface.co/join) if you don't already have one, and then sign in to get your [User Access Token](https://huggingface.co/docs/hub/security-tokens) from your [Settings page](https://huggingface.co/settings/tokens). The User Access Token is used to authenticate your identity to the Hub. > [!TIP] > Tokens can have `read` or `write` permissions. Make sure to have a `write` access token if you want to create or edit a repository. Otherwise, it's best to generate a `read` token to reduce risk in case your token is inadvertently leaked. ### Login command The easiest way to authenticate is to save the token on your machine. You can do that from the terminal using the [`login`] command: ```bash hf auth login ``` The command will tell you if you are already logged in and prompt you for your token. The token is then validated and saved in your `HF_HOME` directory (defaults to `~/.cache/huggingface/token`). Any script or library interacting with the Hub will use this token when sending requests. Alternatively, you can programmatically log in using [`login`] in a notebook or a script: ```py >>> from huggingface_hub import login >>> login() ``` You can only be logged in to one account at a time. Logging in to a new account will automatically log you out of the previous one. To determine your currently active account, simply run the `hf auth whoami` command. > [!WARNING] > Once logged in, all requests to the Hub - even methods that don't necessarily require authentication - will use your access token by default. If you want to disable the implicit use of your token, you should set `HF_HUB_DISABLE_IMPLICIT_TOKEN=1` as an environment variable (see [reference](../package_reference/environment_variables#hfhubdisableimplicittoken)). ### Manage multiple tokens locally You can save multiple tokens on your machine by simply logging in with the [`login`] command with each token. If you need to switch between these tokens locally, you can use the [`auth switch`] command: ```bash hf auth switch ``` This command will prompt you to select a token by its name from a list of saved tokens. Once selected, the chosen token becomes the _active_ token, and it will be used for all interactions with the Hub. You can list all available access tokens on your machine with `hf auth list`. ### Environment variable The environment variable `HF_TOKEN` can also be used to authenticate yourself. This is especially useful in a Space where you can set `HF_TOKEN` as a [Space secret](https://huggingface.co/docs/hub/spaces-overview#managing-secrets). > [!TIP] > **NEW:** Google Colaboratory lets you define [private keys](https://twitter.com/GoogleColab/status/1719798406195867814) for your notebooks. Define a `HF_TOKEN` secret to be automatically authenticated! Authentication via an environment variable or a secret has priority over the token stored on your machine. ### Method parameters Finally, it is also possible to authenticate by passing your token to any method that accepts `token` as a parameter. ``` from huggingface_hub import whoami user = whoami(token=...) ``` This is usually discouraged except in an environment where you don't want to store your token permanently or if you need to handle several tokens at once. > [!WARNING] > Please be careful when passing tokens as a parameter. It is always best practice to load the token from a secure vault instead of hardcoding it in your codebase or notebook. Hardcoded tokens present a major leak risk if you share your code inadvertently. ## Create a repository Once you've registered and logged in, create a repository with the [`create_repo`] function: ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.create_repo(repo_id="super-cool-model") ``` If you want your repository to be private, then: ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.create_repo(repo_id="super-cool-model", private=True) ``` Private repositories will not be visible to anyone except yourself. > [!TIP] > To create a repository or to push content to the Hub, you must provide a User Access > Token that has the `write` permission. You can choose the permission when creating the > token in your [Settings page](https://huggingface.co/settings/tokens). ## Upload files Use the [`upload_file`] function to add a file to your newly created repository. You need to specify: 1. The path of the file to upload. 2. The path of the file in the repository. 3. The repository id of where you want to add the file. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.upload_file( ... path_or_fileobj="/home/lysandre/dummy-test/README.md", ... path_in_repo="README.md", ... repo_id="lysandre/test-model", ... ) ``` To upload more than one file at a time, take a look at the [Upload](./guides/upload) guide which will introduce you to several methods for uploading files (with or without git). ## Next steps The `huggingface_hub` library provides an easy way for users to interact with the Hub with Python. To learn more about how you can manage your files and repositories on the Hub, we recommend reading our [how-to guides](./guides/overview) to: - [Manage your repository](./guides/repository). - [Download](./guides/download) files from the Hub. - [Upload](./guides/upload) files to the Hub. - [Search the Hub](./guides/search) for your desired model or dataset. - [Run Inference](./guides/inference) across multiple services for models hosted on the Hugging Face Hub. huggingface_hub-1.1.5/docs/source/fr/000077500000000000000000000000001510763414300174665ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/fr/_toctree.yml000066400000000000000000000004341510763414300220160ustar00rootroot00000000000000- title: "Introduction" sections: - local: index title: Home - local: quick-start title: Démarrage rapide - local: installation title: Installation - title: "Guides" sections: - local: guides/integrations title: Intégrer dans une librariehuggingface_hub-1.1.5/docs/source/fr/guides/000077500000000000000000000000001510763414300207465ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/fr/guides/integrations.md000066400000000000000000000366761510763414300240200ustar00rootroot00000000000000 # Intégrez votre framework de ML avec le Hub Le Hugging Face Hub facilite l'hébergement et le partage de modèles et de jeux de données. Des [dizaines de librairies](https://huggingface.co/docs/hub/models-libraries) sont intégrées à cet écosystème. La communauté travaille constamment à en intégrer de nouvelles et contribue ainsi à faciliter la collaboration dans le milieu du machine learning. La librairie `huggingface_hub` joue un rôle clé dans ce processus puisqu'elle permet d'interagir avec le Hub depuis n'importe quel script Python. Il existe quatre façons principales d'intégrer une bibliothèque au Hub : 1. **Push to Hub** implémente une méthode pour upload un modèle sur le Hub. Cela inclut les paramètres du modèle, sa fiche descriptive (appelée [Model Card](https://huggingface.co/docs/huggingface_hub/how-to-model-cards)) et toute autre information pertinente liée au modèle (par exemple, les logs d'entraînement). Cette méthode est souvent appelée `push_to_hub()`. 2. **Download from Hub** implémente une méthode pour charger un modèle depuis le Hub. La méthode doit télécharger la configuration et les poids du modèle puis instancier celui-ci. Cette méthode est souvent appelée `from_pretrained` ou `load_from_hub()`. 3. **Widgets** affiche un widget sur la page d'accueil de votre modèle dans le Hub. Les widgets permettent aux utilisateurs de rapidement tester un modèle depuis le navigateur. Dans ce guide, nous nous concentrerons sur les deux premiers sujets. Nous présenterons les deux approches principales que vous pouvez utiliser pour intégrer une librairie, avec leurs avantages et leurs inconvénients. Tout est résumé à la fin du guide pour vous aider à choisir entre les deux. Veuillez garder à l'esprit que ce ne sont que des conseils, et vous êtes libres de les adapter à votre cas d'usage. Si les Widgets vous intéressent, vous pouvez suivre [ce guide](https://huggingface.co/docs/hub/models-adding-libraries#set-up-the-inference-api). Dans les deux cas, vous pouvez nous contacter si vous intégrez une librairie au Hub et que vous voulez être listé [dans la documentation officielle](https://huggingface.co/docs/hub/models-libraries). ## Une approche flexible: les helpers La première approche pour intégrer une librairie au Hub est d'implémenter les méthodes `push_to_hub` et `from_pretrained` vous-même. Ceci vous donne une flexibilité totale sur le choix du fichier que vous voulez upload/download et sur comment gérer les inputs spécifiques à votre framework. Vous pouvez vous référer aux guides : [upload des fichiers](./upload) et [télécharger des fichiers](./download) pour en savoir plus sur la manière de faire. Par example, c'est de cette manière que l'intégration de FastAI est implémentée (voir [`push_to_hub_fastai`] et [`from_pretrained_fastai`]). L'implémentation peut varier entre différentes librairies, mais le workflow est souvent similaire. ### from_pretrained Voici un exemple classique pour implémenter la méthode `from_pretrained`: ```python def from_pretrained(model_id: str) -> MyModelClass: # Téléchargement des paramètres depuis le Hub cached_model = hf_hub_download( repo_id=repo_id, filename="model.pkl", library_name="fastai", library_version=get_fastai_version(), ) # Instanciation du modèle return load_model(cached_model) ``` ### push_to_hub La méthode `push_to_hub` demande souvent un peu plus de complexité pour gérer la création du dépôt git, générer la model card et enregistrer les paramètres. Une approche commune est de sauvegarder tous ces fichiers dans un dossier temporaire, les transférer sur le Hub avant de les supprimer localement. ```python def push_to_hub(model: MyModelClass, repo_name: str) -> None: api = HfApi() # Créez d'un dépôt s'il n'existe pas encore, et obtenez le repo_id associé repo_id = api.create_repo(repo_name, exist_ok=True).repo_id # Sauvegardez tous les fichiers dans un chemin temporaire, et pushez les en un seul commit with TemporaryDirectory() as tmpdir: tmpdir = Path(tmpdir) # Sauvegardez les poids save_model(model, tmpdir / "model.safetensors") # Générez la model card card = generate_model_card(model) (tmpdir / "README.md").write_text(card) # Sauvegardez les logs # Sauvegardez le métriques d'évaluation # ... # Pushez vers le Hub return api.upload_folder(repo_id=repo_id, folder_path=tmpdir) ``` Ceci n'est qu'un exemple. Si vous êtes intéressés par des manipulations plus complexes (supprimer des fichiers distants, upload des poids à la volée, maintenir les poids localement, etc.) consultez le guide [upload des fichiers](./upload). ### Limitations Bien que très flexible, cette approche a quelques défauts, particulièrement en termes de maintenance. Les utilisateurs d'Hugging Face sont habitués à utiliser certaines fonctionnalités lorsqu'ils travaillent avec `huggingface_hub`. Par exemple, lors du chargement de fichiers depuis le Hub, il est commun de passer des paramètres tels que: - `token`: pour télécharger depuis un dépôt privé - `revision`: pour télécharger depuis une branche spécifique - `cache_dir`: pour paramétrer la mise en cache des fichiers - `force_download`: pour désactiver le cache - `api_endpoint`/`proxies`: pour configurer la session HTTP Lorsque vous pushez des modèles, des paramètres similaires sont utilisables: - `commit_message`: message de commit personnalisé - `private`: crée un dépôt privé s'il en manque un - `create_pr`: crée une pull request au lieu de push vers `main` - `branch`: push vers une branche au lieu de push sur `main` - `allow_patterns`/`ignore_patterns`: filtre les fichiers à upload - `token` - `api_endpoint` - ... Tous ces paramètres peuvent être ajoutés aux implémentations vues ci-dessus et passés aux méthodes de `huggingface_hub`. Toutefois, si un paramètre change ou qu'une nouvelle fonctionnalité est ajoutée, vous devrez mettre à jour votre package. Supporter ces paramètres implique aussi plus de documentation à maintenir de votre côté. Dans la prochaine section, nous allons voir comment dépasser ces limitations. ## Une approche plus complexe: l'héritage de classe Comme vu ci-dessus, deux méthodes principales sont à inclure dans votre librairie pour l'intégrer avec le Hub: la méthode permettant d'upload des fichiers (`push_to_hub`) et celle pour télécharger des fichiers (`from_pretrained`). Vous pouvez implémenter ces méthodes vous-même mais cela a des inconvénients. Pour gérer ça, `huggingface_hub` fournit un outil qui utilise l'héritage de classe. Regardons comment ça marche ! Dans beaucoup de cas, une librairie définit déjà les modèles comme des classes Python. La classe contient les propriétés du modèle et des méthodes pour charger, lancer, entraîner et évaluer le modèle. Notre approche est d'étendre cette classe pour inclure les fonctionnalités upload et download en utilisant les mixins. Une [mixin](https://stackoverflow.com/a/547714) est une classe qui est faite pour étendre une classe existante avec une liste de fonctionnalités spécifiques en utilisant l'héritage de classe. `huggingface_hub` offre son propre mixin, le [`ModelHubMixin`]. La clef ici est de comprendre son comportement et comment le customiser. La classe [`ModelHubMixin`] implémente 3 méthodes *public* (`push_to_hub`, `save_pretrained` et `from_pretrained`). Ce sont les méthodes que vos utilisateurs appelleront pour charger/enregistrer des modèles avec votre librairie. [`ModelHubMixin`] définit aussi 2 méthodes *private* (`_save_pretrained` et `from_pretrained`). Ce sont celles que vous devez implémenter. Ainsi, pour intégrer votre librairie, vous devez : 1. Faire en sorte que votre classe Model hérite de [`ModelHubMixin`]. 2. Implémenter les méthodes privées: - [`~ModelHubMixin._save_pretrained`]: méthode qui prend en entrée un chemin vers un directory et qui sauvegarde le modèle. Vous devez écrire toute la logique pour dump votre modèle de cette manière: model card, poids du modèle, fichiers de configuration, et logs d'entraînement. Toute information pertinente pour ce modèle doit être gérée par cette méthode. Les [model cards](https://huggingface.co/docs/hub/model-cards) sont particulièrement importantes pour décrire votre modèle. Vérifiez [notre guide d'implémentation](./model-cards) pour plus de détails. - [`~ModelHubMixin._from_pretrained`]: **méthode de classe** prenant en entrée un `model_id` et qui retourne un modèle instancié. Cette méthode doit télécharger un ou plusieurs fichier(s) et le(s) charger. 3. Fini! L'avantage d'utiliser [`ModelHubMixin`] est qu'une fois que vous vous êtes occupés de la sérialisation et du chargement du fichier, vous êtes prêts. Vous n'avez pas besoin de vous soucier de la création du dépôt, des commits, des pull requests ou des révisions. Tout ceci est géré par le mixin et est disponible pour vos utilisateurs. Le Mixin s'assure aussi que les méthodes publiques sont bien documentées et que les annotations de typage sont spécifiées. ### Un exemple concret: PyTorch Un bon exemple de ce que nous avons vu ci-dessus est [`PyTorchModelHubMixin`], notre intégration pour le framework PyTorch. C'est une intégration prête à l'emploi. #### Comment l'utiliser ? Voici comment n'importe quel utilisateur peut charger/enregistrer un modèle Pytorch depuis/vers le Hub: ```python >>> import torch >>> import torch.nn as nn >>> from huggingface_hub import PyTorchModelHubMixin # 1. Définissez votre modèle Pytorch exactement comme vous êtes habitués à le faire >>> class MyModel(nn.Module, PyTorchModelHubMixin): # héritage multiple ... def __init__(self): ... super().__init__() ... self.param = nn.Parameter(torch.rand(3, 4)) ... self.linear = nn.Linear(4, 5) ... def forward(self, x): ... return self.linear(x + self.param) >>> model = MyModel() # 2. (optionnel) Sauvegarder le modèle dans un chemin local >>> model.save_pretrained("path/to/my-awesome-model") # 3. Pushez les poids du modèle vers le Hub >>> model.push_to_hub("my-awesome-model") # 4. initialisez le modèle depuis le Hub >>> model = MyModel.from_pretrained("username/my-awesome-model") ``` #### Implémentation L'implémentation est très succincte (voir [ici](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hub_mixin.py)). 1. Premièrement, faites hériter votre classe de `ModelHubMixin`: ```python from huggingface_hub import ModelHubMixin class PyTorchModelHubMixin(ModelHubMixin): (...) ``` 2. Implémentez la méthode `_save_pretrained`: ```py from huggingface_hub import ModelCard, ModelCardData class PyTorchModelHubMixin(ModelHubMixin): (...) def _save_pretrained(self, save_directory: Path): """Générez une model card et enregistrez les poids d'un modèle Pytroch vers un chemin local.""" model_card = ModelCard.from_template( card_data=ModelCardData( license='mit', library_name="pytorch", ... ), model_summary=..., model_type=..., ... ) (save_directory / "README.md").write_text(str(model)) torch.save(obj=self.module.state_dict(), f=save_directory / "pytorch_model.bin") ``` 3. Implémentez la méthode `_from_pretrained`: ```python class PyTorchModelHubMixin(ModelHubMixin): (...) @classmethod # Doit absolument être une méthode de clase ! def _from_pretrained( cls, *, model_id: str, revision: str, cache_dir: str, force_download: bool, local_files_only: bool, token: Union[str, bool, None], map_location: str = "cpu", # argument supplémentaire strict: bool = False, # argument supplémentaire **model_kwargs, ): """Chargez les poids pré-entrainés et renvoyez les au modèle chargé.""" if os.path.isdir(model_id): # Peut être un chemin local print("Loading weights from local directory") model_file = os.path.join(model_id, "pytorch_model.bin") else: # Ou un modèle du Hub model_file = hf_hub_download( # Téléchargez depuis le Hub, en passant le mêmes arguments d'entrée repo_id=model_id, filename="pytorch_model.bin", revision=revision, cache_dir=cache_dir, force_download=force_download, token=token, local_files_only=local_files_only, ) # Chargez le modèle et reoutnez une logique personnalisée dépendant de votre framework model = cls(**model_kwargs) state_dict = torch.load(model_file, map_location=torch.device(map_location)) model.load_state_dict(state_dict, strict=strict) model.eval() return model ``` Et c'est fini ! Votre librairie permet maintenant aux utilisateurs d'upload et de télécharger des fichiers vers et depuis le Hub. ## Comparaison Résumons rapidement les deux approches que nous avons vu avec leurs avantages et leurs défauts. Le tableau ci-dessous est purement indicatif. Votre framework aura peut-êre des spécificités à prendre en compte. Ce guide est ici pour vous donner des indications et des idées sur comment gérer l'intégration. Dans tous les cas, n'hésitez pas à nous contacter si vous avez une question ! | Intégration | Utilisant des helpers | Utilisant [`ModelHubMixin`] | | :-------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------: | | Expérience utilisateur | `model = load_from_hub(...)`
`push_to_hub(model, ...)` | `model = MyModel.from_pretrained(...)`
`model.push_to_hub(...)` | | Flexible | Très flexible.
Vous controllez complètement l'implémentation. | Moins flexible.
Votre framework doit avoir une classe de modèle. | | Maintenance | Plus de maintenance pour ajouter du support pour la configuration, et de nouvelles fonctionnalités. Peut aussi nécessiter de fixx des problèmes signalés par les utilisateurs. | Moins de maintenance vu que la plupart des intégrations avec le Hub sont implémentés dans `huggingface_hub` | | Documentation / Anotation de type | A écrire à la main | Géré partiellement par `huggingface_hub`. | huggingface_hub-1.1.5/docs/source/fr/index.md000066400000000000000000000100461510763414300211200ustar00rootroot00000000000000 # Un client Python pour le Hugging Face Hub La librairie `huggingface_hub` vous permet d'interagir avec le [Hugging Face Hub](https://hf.co), une plateforme de machine learning pour créer et collaborer. Découvrez des modèles pré- entrainés et des datasets pour vos projets ou jouez avec des centraines d'applications hébergées sur le Hub. Vous pouvez aussi créer et partager vos propres modèles et datasets avec la communauté. La librairie `huggingface_hub` offre une manière simple de faire toutes ces choses avec Python. Lisez le [guide d'introduction rapide](quick-start) pour vous lancer avec la librairie `huggingface_hub`. Vous apprendrez à télécharger des fichiers depuis le Hub, à créer un dépôt et upload des fichiers vers le Hub. Continuez à lire pour apprendre le management de dépôt sur le Hub, comment interagir avec les discussions ou même comment accéder à l'API d'inférence.
Vue d'ensemble

Guides pratiques pour vous aider à atteindre un but en particulier. Lisez ces guides pour apprendre comment utiliser huggingface_hub pour résoudre des problèmes concrets.
Références

Description exhaustive des classes et méthodes présentes dans huggingface_hub.
Guides conceptuels

Explications permettant d'avoir une meilleure compréhension de la philosophie derrière huggingface_hub.
## Contributions Toutes les contributions au projet `huggingface_hub` sont les bienvenues et valorisées à la même hauteur. 🤗 En plus de l'ajout ou de la correction de bug dans le code, vous pouvez également aider à améliorer la documentation en vérifiant qu'elle est exacte et à jour, répondre à des questions sur des issues, et demander de nouvelles fonctionnalités qui amélioreront la librairie. Regardez le [guide de contribution](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) pour en savoir plus sur comment commencer à travailler sur une issue, comment faire une pull request et comment tester vos contributions pour vérifier que vos modifications fonctionnent comme prévu. Les contributeurs doivent aussi respecter notre [code de conduite](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md) (en anglais) pour créer un espace collaboratif inclusif et bienveillant envers tout le monde.huggingface_hub-1.1.5/docs/source/fr/installation.md000066400000000000000000000171101510763414300225110ustar00rootroot00000000000000 # Installation Avant de commencer, vous allez avoir besoin de préparer votre environnement en installant les packages appropriés. `huggingface_hub` est testée sur **Python 3.9+**. ## Installation avec pip Il est fortement recommandé d'installer `huggingface_hub` dans un [environnement virtuel](https://docs.python.org/3/library/venv.html). Si vous n'êtes pas familier avec les environnements virtuels Python, suivez ce [guide](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/). Un environnement virtuel sera utile lorsque vous devrez gérer des plusieurs projets en parallèle afin d'éviter les problèmes de compatibilité entre les différentes dépendances. Commencez par créer un environnement virtuel à l'emplacement de votre projet: ```bash python -m venv .env ``` Activez l'environnement virtuel sur Linux et macOS: ```bash source .env/bin/activate ``` Activez l'environnement virtuel sur Windows: ```bash .env/Scripts/activate ``` Maintenant, vous êtes prêts à installer `hugginface_hub` [depuis PyPi](https://pypi.org/project/huggingface-hub/): ```bash pip install --upgrade huggingface_hub ``` Une fois l'installation terminée, rendez-vous à la section [vérification](#verification-de-l-installation) pour s'assurer que tout fonctionne correctement. ### Installation des dépendances optionnelles Certaines dépendances de `huggingface_hub` sont [optionnelles](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies) car elles ne sont pas nécessaire pour faire marcher les fonctionnalités principales de `huggingface_hub`. Toutefois, certaines fonctionnalités de `huggingface_hub` ne seront pas disponibles si les dépendances optionnelles ne sont pas installées Vous pouvez installer des dépendances optionnelles via `pip`: ```bash #Installation des dépendances spécifiques à Pytorch et au CLI. pip install 'huggingface_hub[cli,torch]' ``` Voici une liste des dépendances optionnelles dans `huggingface_hub`: - `cli` fournit une interface d'invite de commande plus pratique pour `huggingface_hub`. - `fastai`, `torch` sont des dépendances pour utiliser des fonctionnalités spécifiques à un framework. - `dev` permet de contribuer à la librairie. Cette dépendance inclut `testing` (pour lancer des tests), `typing` (pour lancer le vérifieur de type) et `quality` (pour lancer des linters). ### Installation depuis le code source Dans certains cas, il est intéressant d'installer `huggingface_hub` directement depuis le code source. Ceci vous permet d'utiliser la version `main`, contenant les dernières mises à jour, plutôt que d'utiliser la dernière version stable. La version `main` est utile pour rester à jour sur les derniers développements, par exemple si un bug est corrigé depuis la dernière version officielle mais que la nouvelle version n'a pas encore été faite. Toutefois, cela signifie que la version `main` peut ne pas être stable. Nous travaillons afin de rendre la version `main` aussi stable que possible, et la plupart des problèmes sont résolus en quelques heures ou jours. Si vous avez un problème, ouvrez une issue afin que nous puissions la régler au plus vite ! ```bash pip install git+https://github.com/huggingface/huggingface_hub ``` Lorsque vous installez depuis le code source, vous pouvez préciser la branche depuis laquelle installer. Cela permet de tester une nouvelle fonctionnalité ou un bug-fix qui n'a pas encore été merge: ```bash pip install git+https://github.com/huggingface/huggingface_hub@ma-branche ``` Une fois l'installation terminée, rendez-vous à la section [vérification](#verification-de-l-installation) pour s'assurer que tout fonctionne correctement. ### Installation éditable L'installation depuis le code source vous permet de mettre en place une [installation éditable](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs). Cette installation sert surtout si vous comptez contribuer à `huggingface_hub` et que vous avez besoin de tester rapidement des changements dans le code. Pour cela, vous devez cloner le projet `huggingface_hub` sur votre machine. ```bash # Commencez par cloner le dépôt en local git clone https://github.com/huggingface/huggingface_hub.git # Ensuite, installez-le avec le flag -e cd huggingface_hub pip install -e . ``` Python regardera maintenant à l'intérieur du dossier dans lequel vous avez cloné le dépôt en plus des chemins de librairie classiques. Par exemple, si vos packages Python sont installés dans `./.venv/lib/python3.13/site-packages/`, Python regardera aussi dans le dossier que vous avez cloné `./huggingface_hub/`. ## Installation avec conda Si vous avez plutôt l'habitude d'utiliser conda, vous pouvez installer `huggingface_hub` en utilisant le [channel conda-forge](https://anaconda.org/conda-forge/huggingface_hub): ```bash conda install -c conda-forge huggingface_hub ``` Une fois l'installation terminée, rendez-vous à la section [vérification](#verification-de-l-installation) pour s'assurer que tout fonctionne correctement. ## Vérification de l'installation Une fois installée, vérifiez que `huggingface_hub` marche correctement en lançant la commande suivante: ```bash python -c "from huggingface_hub import model_info; print(model_info('gpt2'))" ``` Cette commande va récupérer des informations sur le modèle [gpt2](https://huggingface.co/gpt2) depuis le Hub. La sortie devrait ressembler à ça: ```text Model Name: gpt2 Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space'] Task: text-generation ``` ## Les limitations Windows Afin de démocratiser le machine learning au plus grand nombre, nous avons développé `huggingface_hub` de manière cross-platform et en particulier, pour qu'elle fonctionne sur une maximum de systèmes d'exploitation différents. Toutefois `huggingface_hub` connaît dans certains cas des limitations sur Windows. Nous avons listé ci-dessous les problèmes connus. N'hésitez pas à nous signaler si vous rencontrez un problème non documenté en ouvrant une [issue sur Github](https://github.com/huggingface/huggingface_hub/issues/new/choose). - Le cache de `huggingface_hub` a besoin des symlinks pour mettre en cache les fichiers installés depuis le Hub. Sur windows, vous devez activer le mode développeur pour lancer ou lancer votre script en tant qu'administrateur afin de faire fonctionner les symlinks. S'ils ne sont pas activés, le système de cache fonctionnera toujours mais de manière sous-optimale. Consultez les [limitations du cache](./guides/manage-cache#limitations) pour plus de détails. - Les noms de fichiers sur le Hub peuvent avoir des caractères spéciaux (par exemple `"path/to?/my/file"`). Windows est plus restrictif sur les [caractères spéciaux](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names) ce qui rend ces fichiers ininstallables sur Windows. Heureusement c'est un cas assez rare. Contactez le propriétaire du dépôt si vous pensez que c'est une erreur ou contactez nous pour que nous cherchions une solution. ## Prochaines étapes Une fois que `huggingface_hub` est installé correctement sur votre machine, vous aurez peut-être besoin de [configurer les variables d'environnement](package_reference/environment_variables) ou de [lire un de nos guides](guides/overview) pour vous lancer. huggingface_hub-1.1.5/docs/source/fr/quick-start.md000066400000000000000000000145271510763414300222700ustar00rootroot00000000000000 # Démarrage rapide Le [Hugging Face Hub](https://huggingface.co/) est le meilleur endroit pour partager des modèles de machine learning, des démos, des datasets et des métriques. La librairie `huggingface_hub` vous aide à intéragir avec le Hub sans sortir de votre environnement de développement. Vous pouvez: créer et gérer des dépôts facilement, télécharger et upload des fichiers, et obtenir des modèles et des métadonnées depuis le Hub. ## Installation Pour commencer, installez la librairie `huggingface_hub`: ```bash pip install --upgrade huggingface_hub ``` Pour plus de détails, vérifiez le guide d'[installation](installation) ## Télécharger des fichiers Les dépôts sur le Hub utilisent le versioning Git, les utilisateurs peuvent télécharger un fichier, ou un dépôt entier. Vous pouvez utiliser la fonction [`hf_hub_download`] pour télécharger des fichiers. Cette fonction téléchargera et mettra dans le cache un fichier sur votre disque local. La prochaine fois que vous aurez besoin de ce fichier, il sera chargé depuis votre cache de façon à ce que vous n'ayez pas besoin de le retélécharger. Vous aurez besoin de l'id du dépôt et du nom du fichier que vous voulez télécharger. Par exemple, pour télécharger le fichier de configuration du modèle [Pegasus](https://huggingface.co/google/pegasus-xsum): ```py >>> from huggingface_hub import hf_hub_download >>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json") ``` Pour télécharger une version spécifique du fichier, utilisez le paramètre `revision` afin de spécifier le nom de la branche, le tag ou le hash de commit. Si vous décidez d'utiliser le hash de commit, vous devez renseigner le hash entier et pas le hash court de 7 caractères: ```py >>> from huggingface_hub import hf_hub_download >>> hf_hub_download( ... repo_id="google/pegasus-xsum", ... filename="config.json", ... revision="4d33b01d79672f27f001f6abade33f22d993b151" ... ) ``` Pour plus de détails et d'options, consultez la réference de l'API pour [`hf_hub_download`]. ## Connexion Dans la plupart des cas, vous devez être connectés avec un compte Hugging Face pour interagir avec le Hub: pour télécharger des dépôts privés, upload des fichiers, créer des pull requests... [Créez un compte](https://huggingface.co/join) si vous n'en avez pas déjà un et connectez vous pour obtenir votre [token d'authentification](https://huggingface.co/docs/hub/security-tokens) depuis vos [paramètres](https://huggingface.co/settings/tokens). Le token est utilisé pour authentifier votre identité au Hub. Une fois que vous avez votre token d'authentification, lancez la commande suivante dans votre terminal: ```bash hf auth login # ou en utilisant une varible d'environnement: hf auth login --token $HUGGINGFACE_TOKEN ``` Sinon, vous pouvez vous connecter en utilisant [`login`] dans un notebook ou un script: ```py >>> from huggingface_hub import login >>> login() ``` Il est aussi possible de se connecter automatiquement sans qu'on vous demande votre token en passant le token dans [`login`] de cette manière: `login(token="hf_xxx")`. Si vous choisissez cette méthode, faites attention lorsque vous partagez votre code source. Une bonne pratique est de charger le token depuis un trousseau sécurisé au lieu de l'enregistrer en clair dans votre codebase/notebook. Vous ne pouvez être connecté qu'à un seul compte à la fois. Si vous connectez votre machine à un autre compte, vous serez déconnecté du premier compte. Vérifiez toujours le compte que vous utilisez avec la commande `hf auth whoami`. Si vous voulez gérer plusieurs compte dans le même script, vous pouvez passer votre token à chaque appel de méthode. C'est aussi utile si vous ne voulez pas sauvegarder de token sur votre machine. > [!WARNING] > Une fois que vous êtes connectés, toutes les requêtes vers le Hub (même les méthodes qui ne nécessite pas explicitement > d'authentification) utiliseront votre token d'authentification par défaut. Si vous voulez supprimer l'utilisation implicite > de votre token, vous devez définir la variable d'environnement `HF_HUB_DISABLE_IMPLICIT_TOKEN`. ## Créer un dépôt Une fois que vous avez créé votre compte et que vous vous êtes connectés, vous pouvez créer un dépôt avec la fonction [`create_repo`]: ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.create_repo(repo_id="super-cool-model") ``` Si vous voulez que votre dépôt soit privé, alors: ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.create_repo(repo_id="super-cool-model", private=True) ``` Les dépôts privés ne seront visible que par vous. > [!TIP] > Pour créer un dépôt ou push du contenu sur le Hub, vous devez fournir un token > d'authentification qui a les permissions `write`. Vous pouvez choisir la permission > lorsque vous générez le token dans vos [paramètres](https://huggingface.co/settings/tokens). ## Upload des fichiers Utilisez la fonction [`upload_file`] pour ajouter un fichier à votre dépôt. Vous devez spécifier: 1. Le chemin du fichier à upload. 2. Le chemin du fichier dans le dépôt. 3. L'id du dépôt dans lequel vous voulez ajouter le fichier. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.upload_file( ... path_or_fileobj="/home/lysandre/dummy-test/README.md", ... path_in_repo="README.md", ... repo_id="lysandre/test-model", ... ) ``` Pour upload plus d'un fichier à la fois, consultez le guide [upload](./guides/upload) qui détaille plusieurs méthodes pour upload des fichiers (avec ou sans Git). ## Prochaines étapes La librairie `huggingface_hub` permet à ses utilisateurs d'intéragir facilementavec le Hub via Python. Pour en apprendre plus sur comment gérer vos fichiers et vos dépôts sur le Hub, nous vous recommandons de lire notre [guide conceptuel](./guides/overview) pour : - [Gérer votre dépôt](./guides/repository). - [Télécharger](./guides/download) des fichiers depuis le Hub. - [Upload](./guides/upload) des fichiers vers le Hub. - [Faire des recherches dans le Hub](./guides/search) pour votre modèle ou dataset. - [Accédder à l'API d'inférence](./guides/inference) pour faire des inférences rapides.huggingface_hub-1.1.5/docs/source/hi/000077500000000000000000000000001510763414300174575ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/hi/_toctree.yml000066400000000000000000000003501510763414300220040ustar00rootroot00000000000000- title: "शुरू हो जाओ" sections: - local: index title: होम - local: quick-start title: जल्दी शुरू - local: installation title: इंस्टालेशन huggingface_hub-1.1.5/docs/source/hi/index.md000066400000000000000000000141131510763414300211100ustar00rootroot00000000000000 # 🤗 हब क्लाइंट लाइब्रेरी `huggingface_hub` लाइब्रेरी आपको [हगिंग फेस' के साथ काम करने की अनुमति देती है हब](https://hf.co), रचनाकारों और सहयोगियों के लिए एक मशीन लर्निंग प्लेटफॉर्म। अपनी परियोजनाओं के लिए पूर्व-प्रशिक्षित मॉडल और डेटासेट खोजें या सैकड़ों के साथ खेलें हब पर होस्ट किए गए मशीन लर्निंग ऐप्स। आप अपने स्वयं के मॉडल और डेटासेट्स भी बना सकते हैं और उन्हें समुदाय के साथ साझा कर सकते हैं। `huggingface_hub` लाइब्रेरी इसका एक आसान तरीका प्रदान करती है ये सभी चीजें Python के साथ करें। इसके साथ काम के लिए [quick-start] (क्विक-स्टार्ट) पढ़ें `huggingface_hub` लाइब्रेरी। आप सीखेंगे कि हब से फाइलें कैसे डाउनलोड करें, एक रिपॉजिटरी कैसे बनाएं, और हब पर फाइलें कैसे अपलोड करें। 🤗 हब पर अपनी रिपॉजिटरी कैसे प्रबंधित करें, चर्चाओं में कैसे भाग लें, या इन्फरेंस एपीआई तक कैसे पहुँचें, इसके बारे में अधिक जानने के लिए पढ़ते रहें।
How-to guides

Practical guides to help you achieve a specific goal. Take a look at these guides to learn how to use huggingface_hub to solve real-world problems.
Reference

Exhaustive and technical description of huggingface_hub classes and methods.
Conceptual guides

High-level explanations for building a better understanding of huggingface_hub philosophy.
## योगदान देना `huggingface_hub` में सभी योगदानों का स्वागत किया जाता है और समान रूप से महत्व दिया जाता है! 🤗 इसके अलावा कोड में मौजूदा समस्याओं को जोड़ने या ठीक करने से आप इसे बेहतर बनाने में भी मदद कर सकते हैं यह सुनिश्चित करके कि दस्तावेज़ीकरण सटीक और अद्यतित है, प्रश्नों के उत्तर देने में सहायता करें मुद्दे, और नई सुविधाओं का अनुरोध करें जो आपको लगता है कि लाइब्रेरी में सुधार करेगी। एक नया मुद्दा या सुविधा अनुरोध कैसे सबमिट करें, पुल अनुरोध कैसे सबमिट करें, और यह सुनिश्चित करने के लिए अपने योगदानों का परीक्षण कैसे करें कि सब कुछ अपेक्षा के अनुरूप काम करता है, इसके बारे में अधिक जानने के लिए [योगदान गाइड](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) पर एक नज़र डालें। योगदानकर्ताओं को सभी के लिए एक समावेशी और स्वागत योग्य सहयोगी स्थान बनाने के लिए हमारे [आचार संहिता](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md), का भी सम्मान करना चाहिए।huggingface_hub-1.1.5/docs/source/hi/installation.md000066400000000000000000000330421510763414300225040ustar00rootroot00000000000000 # स्थापना आरंभ करने से पहले, आपको उपयुक्त पैकेज स्थापित करके अपना परिवेश सेटअप करना होगा। `huggingface_hub` का परीक्षण **Python 3.9+** पर किया गया है। ## पिप के साथ स्थापित करें [वर्चुअल वातावरण](https://docs.python.org/3/library/venv.html) में `huggingface_hub` इंस्टॉल करने की अत्यधिक अनुशंसा की जाती है। यदि आप Python वर्चुअल वातावरण से अपरिचित हैं, तो इस [गाइड](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/) पर एक नज़र डालें। एक वर्चुअल वातावरण विभिन्न परियोजनाओं को प्रबंधित करना आसान बनाता है, और निर्भरताओं के बीच संगतता समस्याओं से बचाता है। अपनी प्रोजेक्ट निर्देशिका में एक वर्चुअल वातावरण बनाकर प्रारंभ करें: ```bash python -m venv .env ``` वर्चुअल वातावरण सक्रिय करें. Linux और macOS पर: ```bash source .env/bin/activate ``` वर्चुअल वातावरण सक्रिय करें Windows पर: ```bash .env/Scripts/activate ``` अब आप `huggingface_hub` [PyPi रजिस्ट्री से](https://pypi.org/project/huggingface-hub/), इंस्टॉल करने के लिए तैयार हैं: ```bash pip install --upgrade huggingface_hub ``` एक बार हो जाने के बाद [चेक इंस्टालेशन](#चेक-इंस्टॉलेशन), यह सुनिश्चित करने के लिए कि वह ठीक से काम कर रहा है। ### वैकल्पिक निर्भरताएँ स्थापित करें `huggingface_hub` की कुछ निर्भरताएं [वैकल्पिक](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies) हैं क्योंकि उन्हें `huggingface_hub` की मुख्य विशेषताओं को चलाने की आवश्यकता नहीं है। हालाँकि, यदि वैकल्पिक निर्भरताएँ स्थापित नहीं हैं तो `huggingface_hub` की कुछ सुविधाएँ उपलब्ध नहीं हो सकती हैं। आप `pip` के माध्यम से वैकल्पिक निर्भरताएँ स्थापित कर सकते हैं: ```bash # Install dependencies for both torch-specific and CLI-specific features. pip install 'huggingface_hub[cli,torch]' ``` यहां `huggingface_hub` में वैकल्पिक निर्भरताओं की सूची दी गई है: - `cli`: `huggingface_hub` के लिए अधिक सुविधाजनक CLI इंटरफ़ेस प्रदान करें। - `fastai`, `torch`: फ्रेमवर्क-विशिष्ट सुविधाओं को चलाने के लिए निर्भरताएँ। - `dev`: lib में योगदान करने के लिए निर्भरताएँ। इसमें 'परीक्षण' (परीक्षण चलाने के लिए), 'टाइपिंग' (टाइप चेकर चलाने के लिए) और 'गुणवत्ता' (लिंटर चलाने के लिए) शामिल हैं। ### स्रोत से इंस्टॉल करें कुछ मामलों में, `huggingface_hub` को सीधे स्रोत से स्थापित करना दिलचस्प होता है। यह आपको नवीनतम स्थिर संस्करण के बजाय अत्याधुनिक `main` संस्करण का उपयोग करने की अनुमति देता है। `main` संस्करण नवीनतम विकास के साथ अद्यतित रहने के लिए उपयोगी है, उदाहरण के लिए यदि अंतिम आधिकारिक रिलीज के बाद से एक बग को ठीक किया गया है लेकिन अभी तक एक नई रिलीज शुरू नहीं की गई है। हालांकि, इसका मतलब है कि `main` संस्करण हमेशा स्थिर नहीं हो सकता है। हम `main` संस्करण को चालू रखने का प्रयास करते हैं, और अधिकांश समस्याएं आमतौर पर कुछ घंटों या एक दिन के भीतर हल हो जाती हैं। यदि आप किसी समस्या का सामना करते हैं, तो कृपया एक समस्या खोलें ताकि हम इसे और भी जल्दी ठीक कर सकें! ```bash pip install git+https://github.com/huggingface/huggingface_hub ``` स्रोत से इंस्टॉल करते समय, आप एक विशिष्ट शाखा भी निर्दिष्ट कर सकते हैं। यह तब उपयोगी होता है जब आप किसी नई सुविधा या नए बग-फिक्स का परीक्षण करना चाहते हैं जिसे अभी तक मर्ज नहीं किया गया है: ```bash pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch ``` एक बार हो जाने के बाद [चेक इंस्टालेशन](#चेक-इंस्टॉलेशन), यह सुनिश्चित करने के लिए कि वह ठीक से काम कर रहा है। ### संपादन योग्य इंस्टॉल स्रोत से इंस्टॉल करने से आपको एक [संपादन योग्य इंस्टॉल](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs) कर सकते हैं। यदि आप `huggingface_hub` में योगदान करने की योजना बना रहे हैं और कोड में परिवर्तनों का परीक्षण करने की आवश्यकता है, तो यह एक अधिक उन्नत इंस्टॉलेशन है। आपको अपनी मशीन पर `huggingface_hub` की एक स्थानीय प्रति क्लोन करने की आवश्यकता है। ```bash # First, clone repo locally git clone https://github.com/huggingface/huggingface_hub.git # Then, install with -e flag cd huggingface_hub pip install -e . ``` ये कमांड उस फ़ोल्डर को लिंक करेंगे जिसमें आपने रिपॉजिटरी को क्लोन किया था और आपके Python लाइब्रेरी पथ। Python अब सामान्य लाइब्रेरी पथ के अलावा आपके द्वारा क्लोन किए गए फ़ोल्डर के अंदर भी देखेगा। उदाहरण के लिए, यदि आपके Python पैकेज आमतौर पर `./.venv/lib/python3.11/site-packages/` में स्थापित होते हैं, तो Python उस फ़ोल्डर को भी खोजेगा जिसे आपने `./huggingface_hub/` क्लोन किया था। ## कोंडा के साथ स्थापित करें यदि आप इससे अधिक परिचित हैं, तो आप [conda-forge चैनल](https://anaconda.org/conda-forge/huggingface_hub) का उपयोग करके `huggingface_hub` इंस्टॉल कर सकते हैं: ```bash conda install -c conda-forge huggingface_hub ``` एक बार हो जाने के बाद [चेक इंस्टालेशन](#चेक-इंस्टॉलेशन), यह सुनिश्चित करने के लिए कि वह ठीक से काम कर रहा है। ## स्थापना की जाँच करें एक बार इंस्टॉल हो जाने पर, निम्नलिखित कमांड चलाकर जांचें कि `huggingface_hub` ठीक से काम करता है: ```bash python -c "from huggingface_hub import model_info; print(model_info('gpt2'))" ``` यह कमांड हब से [gpt2](https://huggingface.co/gpt2) मॉडल के बारे में जानकारी प्राप्त करेगा। आउटपुट इस तरह दिखना चाहिए: ```text Model Name: gpt2 Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space'] Task: text-generation ``` ## विंडोज़ सीमाएँ हर जगह अच्छे एमएल को लोकतांत्रिक बनाने के हमारे लक्ष्य के साथ, हमने `huggingface_hub` को एक क्रॉस-प्लेटफ़ॉर्म लाइब्रेरी बनाने के लिए बनाया है और विशेष रूप से यूनिक्स-आधारित और विंडोज सिस्टम दोनों पर सही ढंग से काम करने के लिए। हालाँकि, ऐसे कुछ मामले हैं जहाँ विंडोज़ पर चलने पर `huggingface_hub` की कुछ सीमाएँ हैं। यहां ज्ञात मुद्दों की एक विस्तृत सूची दी गई है। यदि आप [Github](https://github.com/huggingface/huggingface_hub/issues/new/choose) पर एक समस्या खोलकर किसी अनिर्दिष्ट समस्या का सामना करते हैं तो कृपया हमें बताएं। - `huggingface_hub` का `cache` सिस्टम हब से डाउनलोड की गई फ़ाइलों को कुशलतापूर्वक `cache` करने के लिए सिमलिंक पर निर्भर करता है। विंडोज़ पर, आपको सिमलिंक को सक्षम करने के लिए डेवलपर मोड को सक्रिय करना होगा या अपने स्क्रिप्ट को व्यवस्थापक के रूप में चलाना होगा। यदि वे सक्रिय नहीं हैं, तो cache-सिस्टम अभी भी काम करता है लेकिन गैर-अनुकूलित तरीके से। अधिक जानकारी के लिए कृपया [cache सीमाएँ](./guides/manage-cache#limities) अनुभाग पढ़ें। - हब पर फ़ाइलपथ में विशेष वर्ण हो सकते हैं (उदा. `"path/to?/my/file"`)। विंडोज़ विशेष वर्णों पर अधिक प्रतिबंधात्मक है जिससे उन फ़ाइलों को विंडोज़ पर डाउनलोड करना असंभव हो जाता है। उम्मीद है कि यह एक दुर्लभ मामला है। अगर आपको लगता है कि यह एक गलती है तो कृपया रेपो मालिक से संपर्क करें या समाधान निकालने के लिए हमसे संपर्क करें। ## अगले कदम एक बार जब `huggingface_hub` आपकी मशीन पर ठीक से स्थापित हो जाता है, तो आप आरंभ करने के लिए [पर्यावरण चर कॉन्फ़िगर करें](package_reference/environment_variables) या [हमारे गाइडों में से एक की जांच करें](guides/overview)। huggingface_hub-1.1.5/docs/source/hi/quick-start.md000066400000000000000000000405641510763414300222610ustar00rootroot00000000000000 # जल्दी शुरू [Hugging Face Hub](https://huggingface.co/) मशीन लर्निंग मॉडल, डेमो, डेटासेट और मेट्रिक्स साझा करने के लिए सबसे उपयुक्त स्थान है। `huggingface_hub` लाइब्रेरी आपको अपने विकास परिवेश को छोड़े बिना हब के साथ इंटरैक्ट करने में मदद करती है। आप आसानी से रिपॉजिटरी बना और प्रबंधित कर सकते हैं, फ़ाइलें डाउनलोड और अपलोड कर सकते हैं, और हब से उपयोगी मॉडल और डेटासेट मेटाडेटा प्राप्त कर सकते हैं। ## इंस्टालेशन आरंभ करने के लिए, `huggingface_hub` लाइब्रेरी स्थापित करें: ```bash pip install --upgrade huggingface_hub ``` अधिक विवरण के लिए, [installation](इंस्टॉलेशन) गाइड देखें। ## फ़ाइलें डाउनलोड करें हब पर रिपॉजिटरी `git` वर्जन नियंत्रित हैं, और उपयोगकर्ता एक फ़ाइल या पूरी रिपॉजिटरी डाउनलोड कर सकते हैं। फ़ाइलों को डाउनलोड करने के लिए आप [`hf_hub_download`] फ़ंक्शन का उपयोग कर सकते हैं। यह फ़ंक्शन आपकी स्थानीय डिस्क पर एक फ़ाइल डाउनलोड और `cache` करेगा। अगली बार जब आपको उस फ़ाइल की आवश्यकता होगी, तो यह आपके `cache` से लोड हो जाएगी, इसलिए आपको इसे फिर से डाउनलोड करने की आवश्यकता नहीं है। आपको उस फ़ाइल की रिपॉजिटरी आईडी और फ़ाइल नाम की आवश्यकता होगी जिसे आप डाउनलोड करना चाहते हैं। उदाहरण के लिए, [Pegasus](https://huggingface.co/google/pegasus-xsum) मॉडल कॉन्फ़िगरेशन फ़ाइल डाउनलोड करने के लिए: ```py >>> from huggingface_hub import hf_hub_download >>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json") ``` फ़ाइल के किसी विशिष्ट संस्करण को डाउनलोड करने के लिए, शाखा नाम, टैग या कमिट हैश निर्दिष्ट करने के लिए `revision` पैरामीटर का उपयोग करें। यदि आप कमिट हैश का उपयोग करना चुनते हैं, तो यह छोटे 7-वर्ण कमिट हैश के बजाय पूर्ण-लंबाई वाला हैश होना चाहिए: ```py >>> from huggingface_hub import hf_hub_download >>> hf_hub_download( ... repo_id="google/pegasus-xsum", ... filename="config.json", ... revision="4d33b01d79672f27f001f6abade33f22d993b151" ... ) ``` अधिक विवरण और विकल्पों के लिए, [`hf_hub_download`] के लिए एपीआई संदर्भ देखें। ## प्रमाणीकरण कई मामलों में, हब के साथ इंटरैक्ट करने के लिए आपको `Hugging Face` खाते से प्रमाणित होना होगा: निजी रेपो डाउनलोड करें, फ़ाइलें अपलोड करें, पीआर बनाएं,... [एक खाता बनाएं](https://huggingface.co/join), यदि आपके पास पहले से कोई खाता नहीं है| और फिर अपना [User Access Token](https://huggingface.co/docs/hub/security-tokens) प्राप्त करने के लिए साइन इन करें, आपके [सेटिंग्स पेज](https://huggingface.co/settings/tokens) से। उपयोगकर्ता एक्सेस टोकन का उपयोग हब पर आपकी पहचान को प्रमाणित करने के लिए किया जाता है। > [!TIP] > टोकन में `read` या `write` की अनुमतियाँ हो सकती हैं। यदि आप कोई रिपॉजिटरी बनाना या संपादित करना चाहते हैं तो सुनिश्चित करें कि आपके पास `write` का एक्सेस टोकन है। अन्यथा, अनजाने में आपके टोकन के लीक होने की स्थिति में जोखिम को कम करने के लिए `read` का टोकन जनरेट करना सबसे अच्छा है। ### लॉगिन कमांड प्रमाणित करने का सबसे आसान तरीका टोकन को अपनी मशीन पर सहेजना है। आप [`login`] कमांड का उपयोग करके टर्मिनल से ऐसा कर सकते हैं: ```bash hf auth login ``` कमांड आपको बताएगा कि क्या आप पहले से लॉग इन हैं और आपसे आपके टोकन के लिए पूछेगा। फिर टोकन को मान्य किया जाता है और आपकी `HF_HOME` निर्देशिका (डिफ़ॉल्ट रूप से `~/.cache/huggingface/token`) में सहेजा जाता है। हब के साथ इंटरैक्ट करने वाला कोई भी स्क्रिप्ट या लाइब्रेरी अनुरोध भेजते समय इस टोकन का उपयोग करेगा। वैकल्पिक रूप से, आप किसी नोटबुक या स्क्रिप्ट में [`login`] का उपयोग करके प्रोग्रामेटिक रूप से लॉगिन कर सकते हैं: ```py >>> from huggingface_hub import login >>> login() ``` आप एक समय में केवल एक ही खाते में लॉग इन कर सकते हैं। नए खाते में लॉग इन करने से आप स्वचालित रूप से पिछले खाते से लॉग आउट हो जाएंगे। अपने वर्तमान में सक्रिय खाते को निर्धारित करने के लिए, बस `hf auth whoami` कमांड चलाएँ। > [!WARNING] > एक बार लॉग इन करने के बाद, हब के सभी अनुरोध - यहां तक ​​कि वे तरीके जिनके लिए आवश्यक रूप से प्रमाणीकरण की आवश्यकता नहीं होती है - डिफ़ॉल्ट रूप से आपके एक्सेस टोकन का उपयोग करेंगे। यदि आप अपने टोकन के निहित उपयोग को अक्षम करना चाहते हैं, तो आपको एक पर्यावरण चर के रूप में `HF_HUB_DISABLE_IMPLICIT_TOKEN=1` सेट करना चाहिए [देखें संदर्भ](../package_reference/environment_variables#hfhubdisableimplicittoken)। ### स्थानीय रूप से कई टोकन प्रबंधित करें आप प्रत्येक टोकन के साथ [`login`] कमांड से लॉग इन करके अपनी मशीन पर कई टोकन सहेज सकते हैं। यदि आपको इन टोकन के बीच स्थानीय रूप से स्विच करने की आवश्यकता है, तो आप [auth switch] कमांड का उपयोग कर सकते हैं: ```bash hf auth switch ``` यह कमांड आपको सहेजे गए टोकन की सूची से उसके नाम से एक टोकन चुनने के लिए कहेगा। एक बार चुने जाने के बाद, चुना गया टोकन `_active_` टोकन बन जाता है, और इसका उपयोग हब के साथ सभी इंटरैक्शन के लिए किया जाएगा। आप `hf auth list` के साथ अपनी मशीन पर उपलब्ध सभी एक्सेस टोकन सूचीबद्ध कर सकते हैं। ### पर्यावरण चर पर्यावरण चर `HF_TOKEN` का उपयोग स्वयं को प्रमाणित करने के लिए भी किया जा सकता है। यह एक ऐसे स्थान में विशेष रूप से उपयोगी है जहाँ आप `HF_TOKEN` को [Space Secret](https://huggingface.co/docs/hub/spaces-overview#managing-secrets) के रूप में सेट कर सकते हैं। > [!TIP] > **नया:** Google Colaboratory आपको अपनी नोटबुक के लिए [private keys](https://twitter.com/GoogleColab/status/1719798406195867814) परिभाषित करने देता है। स्वचालित रूप से प्रमाणित होने के लिए एक `HF_TOKEN` रहस्य परिभाषित करें! पर्यावरण चर या रहस्य के माध्यम से प्रमाणीकरण को आपकी मशीन पर संग्रहीत टोकन पर प्राथमिकता दी जाती है। ### मेथड पैरामीटर अंत में, `token` को पैरामीटर के रूप में स्वीकार करने वाली किसी भी विधि में अपना टोकन पास करके प्रमाणित करना भी संभव है। ``` from huggingface_hub import whoami user = whoami(token=...) ``` सामान्यतः इसकी अनुशंसा नहीं की जाती है, सिवाय उन परिस्थितियों में जहाँ आप अपना टोकन स्थायी रूप से संग्रहीत नहीं करना चाहते हैं या यदि आपको एक साथ कई टोकन संभालने की आवश्यकता है। > [!WARNING] > टोकन को पैरामीटर के रूप में पास करते समय कृपया सावधान रहें। अपने कोडबेस या नोटबुक में इसे हार्डकोड करने के बजाय टोकन को एक सुरक्षित वॉल्ट से लोड करना हमेशा सबसे अच्छा अभ्यास होता है। यदि आप अनजाने में अपना कोड साझा करते हैं तो हार्डकोडेड टोकन एक बड़ा रिसाव जोखिम पेश करते हैं। ## रिपॉजिटरी बनाएँ एक बार जब आप पंजीकृत हो जाते हैं और लॉग इन कर लेते हैं, तो [`create_repo`] फ़ंक्शन के साथ एक रिपॉजिटरी बनाएँ: ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.create_repo(repo_id="super-cool-model") ``` यदि आप चाहते हैं कि आपकी रिपॉजिटरी निजी हो, तो: ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.create_repo(repo_id="super-cool-model", private=True) ``` निजी रिपॉजिटरी आपके अलावा किसी और को दिखाई नहीं देंगी। > [!TIP] > रिपॉजिटरी बनाने या हब पर सामग्री पुश करने के लिए, आपको एक उपयोगकर्ता एक्सेस > टोकन प्रदान करना होगा जिसके पास `write` की अनुमति हो। > टोकन बनाते समय आप अपने [सेटिंग्स पेज](https://huggingface.co/settings/tokens) में अनुमति चुन सकते हैं। ## फाइलें अपलोड करें अपनी नव निर्मित रिपॉजिटरी में फ़ाइल जोड़ने के लिए [`upload_file`] फ़ंक्शन का उपयोग करें। आप निर्दिष्ट करने की आवश्यकता है: 1. अपलोड करने के लिए फ़ाइल का पथ. 2. रिपोजिटरी में फ़ाइल का पथ. 3. रिपॉजिटरी आईडी जहाँ आप फ़ाइल जोड़ना चाहते हैं। ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.upload_file( ... path_or_fileobj="/home/lysandre/dummy-test/README.md", ... path_in_repo="README.md", ... repo_id="lysandre/test-model", ... ) ``` एक समय में एक से अधिक फ़ाइल अपलोड करने के लिए, [अपलोड](./guides/upload) मार्गदर्शिका पर एक नज़र डालें जो आपको फ़ाइलें अपलोड करने के कई तरीकों से परिचित कराएगा (git के साथ या उसके बिना)। ## अगले कदम `huggingface_hub` लाइब्रेरी उपयोगकर्ताओं को हब के साथ बातचीत करने का एक आसान तरीका प्रदान करती है Python के साथ. हब पर आप अपनी फ़ाइलों और रिपॉजिटरी को कैसे प्रबंधित कर सकते हैं,, इसके बारे में अधिक जानने के लिए, हम अनुशंसा करते हैं कि आप हमारे [कैसे करें मार्गदर्शिकाएं](./guides/अवलोकन) पढ़ें: - [अपना भंडार प्रबंधित करें](./guides/repository)। - हब से [डाउनलोड](./guides/download) फ़ाइलें। - हब पर [अपलोड](./guides/upload) फ़ाइलें। - अपने इच्छित मॉडल या डेटासेट के लिए [हब खोजें](./guides/search)। - तेज अनुमान के लिए [अनुमान एपीआई तक पहुंचें](./guides/अनुमान)। huggingface_hub-1.1.5/docs/source/ko/000077500000000000000000000000001510763414300174705ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/ko/_toctree.yml000066400000000000000000000051411510763414300220200ustar00rootroot00000000000000- title: "시작하기" sections: - local: index title: 홈 - local: quick-start title: 둘러보기 - local: installation title: 설치 방법 - title: "How-to 가이드" sections: - local: guides/overview title: 개요 - local: guides/download title: 파일 다운로드하기 - local: guides/upload title: 파일 업로드하기 - local: guides/cli title: 명령줄 인터페이스(CLI) 사용하기 - local: guides/hf_file_system title: Hf파일시스템 - local: guides/search title: Hub에서 검색하기 - local: guides/inference title: 추론 - local: guides/inference_endpoints title: 추론 엔드포인트 - local: guides/community title: 커뮤니티 - local: guides/collections title: Collections - local: guides/manage-cache title: 캐시 관리 - local: guides/model-cards title: 모델 카드 - local: guides/manage-spaces title: Space 관리 - local: guides/integrations title: 라이브러리 통합 - local: guides/webhooks_server title: 웹훅 서버 - title: "라이브러리 레퍼런스" sections: - local: package_reference/overview title: 개요 - local: package_reference/login title: 로그인 및 로그아웃 - local: package_reference/environment_variables title: 환경 변수 - local: package_reference/hf_api title: 허깅페이스 Hub API - local: package_reference/file_download title: 파일 다운로드하기 - local: package_reference/mixins title: 믹스인 & 직렬화 메소드 - local: package_reference/inference_types title: 추론 타입 - local: package_reference/inference_client title: 추론 클라이언트 - local: package_reference/inference_endpoints title: 추론 엔드포인트 - local: package_reference/hf_file_system title: Hf파일시스템 - local: package_reference/utilities title: 유틸리티 - local: package_reference/community title: Discussions 및 Pull Requests - local: package_reference/cache title: 캐시 시스템 참조 - local: package_reference/cards title: Repo Cards 와 Repo Card Data - local: package_reference/collections title: 컬렉션 관리 - local: package_reference/space_runtime title: Space 런타임 - local: package_reference/tensorboard title: TensorBoard 로거 - local: package_reference/webhooks_server title: 웹훅 서버 - local: package_reference/serialization title: 직렬화huggingface_hub-1.1.5/docs/source/ko/guides/000077500000000000000000000000001510763414300207505ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/ko/guides/cli.md000066400000000000000000000614141510763414300220470ustar00rootroot00000000000000 # 명령줄 인터페이스 (CLI) [[command-line-interface]] `huggingface_hub` Python 패키지는 `hf`라는 내장 CLI를 함께 제공합니다. 이 도구를 사용하면 터미널에서 Hugging Face Hub와 직접 상호 작용할 수 있습니다. 계정에 로그인하고, 리포지토리를 생성하고, 파일을 업로드 및 다운로드하는 등의 다양한 작업을 수행할 수 있습니다. 또한 머신을 구성하거나 캐시를 관리하는 데 유용한 기능도 제공합니다. 이 가이드는 CLI의 주요 기능과 사용 방법에 관해 설명합니다. ## 시작하기 [[getting-started]] 먼저, CLI를 설치해 보세요: ``` >>> pip install -U "huggingface_hub" ``` > [!TIP] > CLI는 기본 `huggingface_hub` 패키지에 포함되어 있습니다. 설치가 완료되면, CLI가 올바르게 설정되었는지 확인할 수 있습니다: ``` >>> hf --help usage: hf [] positional arguments: {auth,cache,download,repo,repo-files,upload,upload-large-folder,env,version,lfs-enable-largefiles,lfs-multipart-upload} hf command helpers auth Manage authentication (login, logout, etc.). cache Manage local cache directory. download Download files from the Hub repo Manage repos on the Hub. repo-files Manage files in a repo on the Hub. upload Upload a file or a folder to the Hub. Recommended for single-commit uploads. upload-large-folder Upload a large folder to the Hub. Recommended for resumable uploads. env Print information about the environment. version Print information about the hf version. options: -h, --help show this help message and exit ``` CLI가 제대로 설치되었다면 CLI에서 사용 가능한 모든 옵션 목록이 출력됩니다. `command not found: hf`와 같은 오류 메시지가 표시된다면 [설치](../installation) 가이드를 확인하세요. > [!TIP] > `--help` 옵션을 사용하면 명령어에 대한 자세한 정보를 얻을 수 있습니다. 언제든지 사용 가능한 모든 옵션과 그 세부 사항을 확인할 수 있습니다. 예를 들어 `hf upload --help`는 CLI를 사용하여 파일을 업로드하는 구체적인 방법을 알려줍니다. ### 다른 방법으로 설치하기 [[alternative-install]] #### uv 사용하기 [[using-uv]] [uv](https://docs.astral.sh/uv/)를 사용하면 `hf` CLI를 설치하거나, 설치 없이 바로 실행할 수 있습니다. 먼저 uv를 설치하세요 (PATH에 `uv`와 `uvx`가 추가됩니다): ```bash >>> curl -LsSf https://astral.sh/uv/install.sh | sh ``` 영구적으로 도구를 설치해 어디에서나 사용하려면: ```bash >>> uv tool install "huggingface_hub" >>> hf --help ``` 전역 설치 없이 일회성으로 실행하려면 `uvx`를 사용하세요: ```bash >>> uvx --from huggingface_hub hf --help ``` #### Homebrew 사용하기 [[using-homebrew]] [Homebrew](https://brew.sh/)를 사용하여 CLI를 설치할 수도 있습니다: ```bash >>> brew install huggingface-cli ``` Homebrew huggingface에 대한 자세한 내용은 [여기](https://formulae.brew.sh/formula/huggingface-cli)에서 확인할 수 있습니다. ## hf auth login [[hf-login]] Hugging Face Hub에 접근하는 대부분의 작업(비공개 리포지토리 액세스, 파일 업로드, PR 제출 등)을 위해서는 Hugging Face 계정에 로그인해야 합니다. 로그인을 하기 위해서 [설정 페이지](https://huggingface.co/settings/tokens)에서 생성한 [사용자 액세스 토큰](https://huggingface.co/docs/hub/security-tokens)이 필요하며, 이 토큰은 Hub에서의 사용자 인증에 사용됩니다. 파일 업로드나 콘텐츠 수정을 위해선 쓰기 권한이 있는 토큰이 필요합니다. 토큰을 받은 후에 터미널에서 다음 명령을 실행하세요: ```bash >>> hf auth login ``` 이 명령은 토큰을 입력하라는 메시지를 표시합니다. 토큰을 복사하여 붙여넣고 Enter 키를 입력합니다. 그런 다음 토큰을 git 자격 증명으로 저장할지 묻는 메시지가 표시됩니다. 로컬에서 `git`을 사용할 계획이라면 Enter 키를 입력합니다(기본값은 yes). 마지막으로 Hub에서 토큰의 유효성을 검증한 후 로컬에 저장합니다. ``` _| _| _| _| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _|_|_|_| _|_| _|_|_| _|_|_|_| _| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _| _|_|_|_| _| _| _| _|_| _| _|_| _| _| _| _| _| _|_| _|_|_| _|_|_|_| _| _|_|_| _| _| _| _| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _| _| _| _|_| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _| _| _| _|_|_| _|_|_|_| To log in, `huggingface_hub` requires a token generated from https://huggingface.co/settings/tokens . Token: Add token as git credential? (Y/n) Token is valid (permission: write). 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 ``` 프롬프트를 거치지 않고 바로 로그인하고 싶다면, 명령줄에서 토큰을 직접 입력할 수도 있습니다. 하지만 보안을 더욱 강화하기 위해서는 명령 기록에 토큰을 남기지 않고, 환경 변수를 통해 토큰을 전달하는 방법이 바람직합니다. ```bash # Or using an environment variable >>> hf auth login --token $HUGGINGFACE_TOKEN --add-to-git-credential Token is valid (permission: write). 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 ``` [이 단락](../quick-start#authentication)에서 인증에 대한 더 자세한 내용을 확인할 수 있습니다. ## hf auth whoami [[hf-whoami]] 로그인 여부를 확인하기 위해 `hf auth whoami` 명령어를 사용할 수 있습니다. 이 명령어는 옵션이 없으며, 간단하게 사용자 이름과 소속된 조직들을 출력합니다: ```bash hf auth whoami Wauplin orgs: huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolCluster ``` 로그인하지 않은 경우 오류 메시지가 출력됩니다. ## hf auth logout [[hf-auth-logout]] 이 명령어를 사용하여 로그아웃할 수 있습니다. 실제로는 컴퓨터에 저장된 토큰을 삭제합니다. 하지만 `HF_TOKEN` 환경 변수를 사용하여 로그인했다면, 이 명령어로는 로그아웃할 수 없습니다([참조]((../package_reference/environment_variables#hftoken))). 대신 컴퓨터의 환경 설정에서 `HF_TOKEN` 변수를 제거하면 됩니다. ## hf download [[hf-download]] `hf download` 명령어를 사용하여 Hub에서 직접 파일을 다운로드할 수 있습니다. [다운로드](./download) 가이드에서 설명된 [`hf_hub_download`], [`snapshot_download`] 헬퍼 함수를 사용하여 반환된 경로를 터미널에 출력합니다. 우리는 아래 예시에서 가장 일반적인 사용 사례를 살펴볼 것입니다. 사용 가능한 모든 옵션을 보려면 아래 명령어를 실행해보세요: ```bash hf download --help ``` ### 파일 한 개 다운로드하기 [[download-a-single-file]] 리포지토리에서 파일 하나를 다운로드하고 싶다면, 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 ``` 이 명령어를 실행하면 항상 마지막 줄에 파일 경로를 출력합니다. ### 전체 리포지토리 다운로드하기 [[download-an-entire-repository]] 리포지토리의 모든 파일을 다운로드하고 싶을 때에는 repo 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 ... ``` ### 특정 리비전 다운로드하기 [[download-a-specific-revision]] 따로 리비전을 지정하지 않는다면 기본적으로 main 브랜치의 최신 커밋에서 파일을 다운로드합니다. 특정 리비전(커밋 해시, 브랜치 이름 또는 태그)에서 다운로드하려면 `--revision` 옵션을 사용하세요: ```bash >>> hf download bigcode/the-stack --repo-type dataset --revision v1.1 ... ``` ### 로컬 폴더에 다운로드하기 [[download-to-a-local-folder]] Hub에서 파일을 다운로드하는 권장되고 기본적인 방법은 캐시 시스템을 사용하는 것입니다. 그러나 특정한 경우에는 파일을 지정된 폴더로 다운로드하고 옮기고 싶을 수 있습니다. 이는 git 명령어와 유사한 워크플로우를 만드는데 도움이 됩니다. `--local_dir` 옵션을 사용하여 이 작업을 수행할 수 있습니다. > [!WARNING] > 로컬 폴더에 다운로드하는 것에는 몇 가지 단점이 있습니다. `--local-dir` 명령어를 사용하기 전에 [다운로드](./download#download-files-to-local-folder) 가이드에서 해당 내용을 확인해보세요. ```bash >>> hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir . ... ./model-00001-of-00002.safetensors ``` ### 캐시 디렉터리 지정하기 [[specify-cache-directory]] 기본적으로 모든 파일은 `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 ``` ### 토큰 설정하기 [[specify-a-token]] 비공개 또는 접근이 제한된 리포지토리들에 접근하기 위해서는 토큰이 필요합니다. 기본적으로 로컬에 저장된 토큰(`hf auth login`)이 사용됩니다. 직접 인증하고 싶다면 `--token` 옵션을 사용해보세요: ```bash >>> hf download gpt2 config.json --token=hf_**** /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json ``` ### 조용한 모드 [[quiet-mode]] `hf download` 명령은 상세한 정보를 출력합니다. 경고 메시지, 다운로드된 파일 정보, 진행률 등이 포함됩니다. 이 모든 출력을 숨기려면 `--quiet` 옵션을 사용하세요. 이 옵션을 사용하면 다운로드된 파일의 경로가 표시되는 마지막 줄만 출력됩니다. 이 기능은 스크립트에서 다른 명령어로 출력을 전달하고자 할 때 유용할 수 있습니다. ```bash >>> hf download gpt2 --quiet /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 ``` ## hf upload [[hf-upload]] `hf upload` 명령어로 Hub에 직접 파일을 업로드할 수 있습니다. [업로드](./upload) 가이드에서 설명된 [`upload_file`], [`upload_folder`] 헬퍼 함수를 사용합니다. 우리는 아래 예시에서 가장 일반적인 사용 사례를 살펴볼 것입니다. 사용 가능한 모든 옵션을 보려면 아래 명령어를 실행해보세요: ```bash >>> hf upload --help ``` ### 전체 폴더 업로드하기 [[upload-an-entire-folder]] 이 명령어의 기본 사용법은 다음과 같습니다: ```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 ``` ### 여러 파일 업로드하기 [[upload-multiple-files]] 전체 폴더를 업로드하지 않고 한 번에 여러 파일을 업로드하려면 `--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에 업로드하기 [[upload-to-a-dataset-or-space]] 데이터 세트나 Space에 업로드하려면 `--repo-type` 옵션을 사용하세요: ```bash >>> hf upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset ... ``` ### 조직에 업로드하기 [[upload-to-an-organization]] 개인 리포지토리 대신 조직이 소유한 리포지토리에 파일을 업로드하려면 `repo_id`를 입력해야 합니다: ```bash >>> hf upload MyCoolOrganization/my-cool-model . . https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/ ``` ### 특정 개정에 업로드하기 [[upload-to-a-specific-revision]] 기본적으로 파일은 `main` 브랜치에 업로드됩니다. 다른 브랜치나 참조에 파일을 업로드하려면 `--revision` 옵션을 사용하세요: ```bash # Upload files to a PR >>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104 ... ``` **참고:** `revision`이 존재하지 않고 `--create-pr` 옵션이 설정되지 않은 경우, `main` 브랜치에서 자동으로 새 브랜치가 생성됩니다. ### 업로드 및 PR 생성하기 [[upload-and-create-a-pr]] 리포지토리에 푸시할 권한이 없다면, 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/ ``` ### 정기적으로 업로드하기 [[upload-at-regular-intervals]] 리포지토리에 정기적으로 업데이트하고 싶을 때, `--every` 옵션을 사용할 수 있습니다. 예를 들어, 모델을 훈련하는 중에 로그 폴더를 10분마다 업로드하고 싶다면 다음과 같이 사용할 수 있습니다: ```bash # Upload new logs every 10 minutes hf upload training-model logs/ --every=10 ``` ### 커밋 메시지 지정하기 [[specify-a-commit-message]] `--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 ``` ### 토큰 지정하기 [[specify-a-token]] 파일을 업로드하려면 토큰이 필요합니다. 기본적으로 로컬에 저장된 토큰(`hf auth login`)이 사용됩니다. 직접 인증하고 싶다면 `--token` 옵션을 사용해보세요: ```bash >>> hf upload Wauplin/my-cool-model ./models . --token=hf_**** ... https://huggingface.co/Wauplin/my-cool-model/tree/main ``` ### 조용한 모드 [[quiet-mode]] 기본적으로 `hf upload` 명령은 상세한 정보를 출력합니다. 경고 메시지, 업로드된 파일 정보, 진행률 등이 포함됩니다. 이 모든 출력을 숨기려면 `--quiet` 옵션을 사용하세요. 이 옵션을 사용하면 업로드된 파일의 URL이 표시되는 마지막 줄만 출력됩니다. 이 기능은 스크립트에서 다른 명령어로 출력을 전달하고자 할 때 유용할 수 있습니다. ```bash >>> hf upload Wauplin/my-cool-model ./models . --quiet https://huggingface.co/Wauplin/my-cool-model/tree/main ``` ## hf cache ls [[hf-cache-ls]] 로컬 캐시에 어떤 리포지토리나 수정 버전이 저장되어 있는지 확인하려면 `hf cache ls`를 사용하세요. 기본 출력은 리포지토리 단위 요약입니다. ```bash >>> hf cache ls ID SIZE LAST_ACCESSED LAST_MODIFIED REFS ------------------------------------ ------- ------------- ------------- ------------------- dataset/glue 116.3K 4 days ago 4 days ago 2.4.0 main 1.17.0 dataset/google/fleurs 64.9M 1 week ago 1 week ago main refs/pr/1 model/Jean-Baptiste/camembert-ner 441.0M 2 weeks ago 16 hours ago main model/bert-base-cased 1.9G 1 week ago 2 years ago model/t5-base 10.1K 3 months ago 3 months ago main model/t5-small 970.7M 3 days ago 3 days ago main refs/pr/1 Found 6 repo(s) for a total of 12 revision(s) and 3.4G on disk. ``` `--revisions` 옵션과 `--filter` 표현식을 조합하면 특정 스냅샷만 추려 볼 수 있습니다. ```bash >>> hf cache ls --revisions --filter "size>1GB" --filter "accessed>30d" ID REVISION SIZE LAST_MODIFIED REFS ------------------------------------ ------------------ ------- ------------- ------------------- model/bert-base-cased 6d1d7a1a2a6cf4c2 1.9G 2 years ago model/t5-small 1c610f6b3f5e7d8a 1.1G 3 months ago main Found 2 repo(s) for a total of 2 revision(s) and 3.0G on disk. ``` `--format json`, `--format csv`, `--quiet`, `--cache-dir` 등 다양한 옵션으로 출력 형식을 조정할 수 있습니다. 자세한 내용은 [캐시 관리](./manage-cache#scan-your-cache) 가이드를 참고하세요. `hf cache ls --quiet`로 추린 식별자를 `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) Delete repo: ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct Delete repo: ~/.cache/huggingface/hub/models--hexgrad--Kokoro-82M Cache deletion done. Saved 5.31G. Deleted 2 repo(s) and 2 revision(s); freed 5.31G. ``` ## hf cache rm [[hf-cache-rm]] 캐시에서 특정 리포지토리나 수정 버전을 삭제하려면 `hf cache rm`을 사용합니다. 리포지토리 식별자나 수정 버전 해시를 하나 이상 전달하면 됩니다. `--dry-run`으로 미리보기, `--yes`로 확인창 건너뛰기, `--cache-dir`로 다른 경로 지정이 가능합니다. ## hf cache prune [[hf-cache-prune]] 참조되지 않는(detached) 수정 버전만 한꺼번에 제거하려면 `hf cache prune`을 실행하세요. `--dry-run`, `--yes`, `--cache-dir` 옵션 역시 동일하게 사용할 수 있습니다. ## hf env [[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: 0.19.0.dev0 - Platform: Linux-6.2.0-36-generic-x86_64-with-glibc2.35 - Python version: 3.10.12 - Running in iPython ?: No - Running in notebook ?: No - Running in Google Colab ?: No - Token path ?: /home/wauplin/.cache/huggingface/token - Has saved token ?: True - Who am I ?: Wauplin - Configured git credential helpers: store - FastAI: N/A - Torch: 1.12.1 - Jinja2: 3.1.2 - Graphviz: 0.20.1 - Pydot: 1.4.2 - Pillow: 9.2.0 - hf_transfer: 0.1.3 - gradio: 4.0.2 - tensorboard: 2.6 - numpy: 1.23.2 - pydantic: 2.4.2 - aiohttp: 3.8.4 - 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_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_ENABLE_HF_TRANSFER: False - HF_HUB_ETAG_TIMEOUT: 10 - HF_HUB_DOWNLOAD_TIMEOUT: 10 ``` huggingface_hub-1.1.5/docs/source/ko/guides/collections.md000066400000000000000000000252311510763414300236130ustar00rootroot00000000000000 # Collections[[collections]] Collection은 Hub(모델, 데이터셋, Spaces, 논문)에 있는 관련 항목들의 그룹으로, 같은 페이지에 함께 구성되어 있습니다. Collections는 자신만의 포트폴리오를 만들거나, 카테고리별로 콘텐츠를 북마크 하거나, 공유하고 싶은 item들의 큐레이팅 된 목록을 제시하는 데 유용합니다. 여기 [가이드](https://huggingface.co/docs/hub/collections)를 확인하여 Collections가 무엇이고 Hub에서 어떻게 보이는지 자세히 알아보세요. 브라우저에서 직접 Collections를 관리할 수 있지만, 이 가이드에서는 프로그래밍 방식으로 Collection을 관리하는 방법에 초점을 맞추겠습니다. ## Collection 가져오기[[fetch-a-collection]] [`get_collection`]을 사용하여 자신의 Collections나 공개된 Collection을 가져올 수 있습니다. Collection을 가져오려면 Collection의 *slug*가 필요합니다. Slug는 제목과 고유한 ID를 기반으로 한 Collection의 식별자입니다. Collection 페이지의 URL에서 slug를 찾을 수 있습니다.
`"TheBloke/recent-models-64f9a55bb3115b4f513ec026"` Collection을 가져와 봅시다: ```py >>> from huggingface_hub import get_collection >>> collection = get_collection("TheBloke/recent-models-64f9a55bb3115b4f513ec026") >>> collection Collection( slug='TheBloke/recent-models-64f9a55bb3115b4f513ec026', title='Recent models', owner='TheBloke', items=[...], last_updated=datetime.datetime(2023, 10, 2, 22, 56, 48, 632000, tzinfo=datetime.timezone.utc), position=1, private=False, theme='green', upvotes=90, description="Models I've recently quantized. Please note that currently this list has to be updated manually, and therefore is not guaranteed to be up-to-date." ) >>> collection.items[0] CollectionItem( item_object_id='651446103cd773a050bf64c2', item_id='TheBloke/U-Amethyst-20B-AWQ', item_type='model', position=88, note=None ) ``` [`get_collection`]에 의해 반환된 [`Collection`] 객체에는 다음이 포함되어 있습니다: - 높은 수준의 메타데이터: `slug`, `owner`, `title`, `description` 등 - [`CollectionItem`] 객체의 목록; 각 항목은 모델, 데이터셋, Space 또는 논문을 나타냅니다. 모든 Collection 항목에는 다음이 보장됩니다: - 고유한 `item_object_id`: 데이터베이스에서 Collection 항목의 id - 기본 항목(모델, 데이터셋, Space, 논문)의 Hub에서의 `item_id`; 고유하지 않으며, `item_id`/`item_type` 쌍만 고유합니다. - `item_type`: 모델, 데이터셋, Space, 논문 - Collection에서 항목의 `position`으로, 이를 업데이트하여 Collection을 재구성할 수 있습니다(아래의 [`update_collection_item`] 참조) 각 항목에는 추가 정보(코멘트, 블로그 포스트 링크 등)를 위한 `note`도 첨부될 수 있습니다. 항목에 note가 없으면 해당 속성값은 `None`이 됩니다. 이러한 기본 속성 외에도, 반환된 항목은 유형에 따라 추가 속성(`author`, `private`, `lastModified`, `gated`, `title`, `likes`, `upvotes` 등)을 가질 수 있습니다. 그러나 이러한 속성이 반환된다는 보장은 없습니다. ## Collections 나열하기[[fetch-a-collection]] [`list_collections`]를 사용하여 Collections를 나열할 수도 있습니다. Collections는 몇 가지 매개변수를 사용하여 필터링할 수 있습니다. 사용자 [`teknium`](https://huggingface.co/teknium)의 모든 Collections를 나열해 봅시다. ```py >>> from huggingface_hub import list_collections >>> collections = list_collections(owner="teknium") ``` 이렇게 하면 `Collection` 객체의 반복 가능한 객체가 반환됩니다. 예를 들어 각 Collection의 upvotes 수를 출력하기 위해 반복할 수 있습니다. ```py >>> for collection in collections: ... print("Number of upvotes:", collection.upvotes) Number of upvotes: 1 Number of upvotes: 5 ``` > [!WARNING] > Collections를 나열할 때, 각 Collection의 항목 목록은 최대 4개 항목으로 잘립니다. Collection의 모든 항목을 가져오려면 [`get_collection`]을 사용해야 합니다. 고급 필터링을 수행할 수 있습니다. 예를 들어 모델 [TheBloke/OpenHermes-2.5-Mistral-7B-GGUF](https://huggingface.co/TheBloke/OpenHermes-2.5-Mistral-7B-GGUF)를 포함하는 트렌딩 순으로 정렬된 Collections를 5개까지만 가져올 수 있습니다. ```py >>> collections = list_collections(item="models/TheBloke/OpenHermes-2.5-Mistral-7B-GGUF", sort="trending", limit=5): >>> for collection in collections: ... print(collection.slug) teknium/quantized-models-6544690bb978e0b0f7328748 AmeerH/function-calling-65560a2565d7a6ef568527af PostArchitekt/7bz-65479bb8c194936469697d8c gnomealone/need-to-test-652007226c6ce4cdacf9c233 Crataco/favorite-7b-models-651944072b4fffcb41f8b568 ``` `sort` 매개변수는 `"last_modified"`, `"trending"` 또는 `"upvotes"` 중 하나여야 합니다. `item` 매개변수는 특정 항목을 받습니다. 예를 들면 다음과 같습니다: * `"models/teknium/OpenHermes-2.5-Mistral-7B"` * `"spaces/julien-c/open-gpt-rhyming-robot"` * `"datasets/squad"` * `"papers/2311.12983"` 자세한 내용은 [`list_collections`] 참조를 확인하시기 바랍니다. ## 새 Collection 만들기[[fetch-a-collection]] 이제 [`Collection`]을 가져오는 방법을 알았으니 우리만의 Collection을 만들어봅시다! 제목과 설명을 사용하여 [`create_collection`]을 호출합니다. 조직 페이지에 Collection을 만들려면 Collection 생성 시 `namespace="my-cool-org"`를 전달합니다. 마지막으로 `private=True`를 전달하여 비공개 Collection을 만들 수도 있습니다. ```py >>> from huggingface_hub import create_collection >>> collection = create_collection( ... title="ICCV 2023", ... description="Portfolio of models, papers and demos I presented at ICCV 2023", ... ) ``` 이렇게 하면 (제목, 설명, 소유자 등의) 높은 수준의 메타데이터와 빈 항목 목록을 가진 [`Collection`] 객체가 반환됩니다. 이제 `slug`를 사용하여 이 Collection을 참조할 수 있습니다. ```py >>> collection.slug 'owner/iccv-2023-15e23b46cb98efca45' >>> collection.title "ICCV 2023" >>> collection.owner "username" >>> collection.url 'https://huggingface.co/collections/owner/iccv-2023-15e23b46cb98efca45' ``` ## Collection의 item 관리[[manage-items-in-a-collection]] 이제 [`Collection`]을 가지고 있으므로, 여기에 item을 추가하고 구성해봅시다. ### item 추가[[add-items]] item은 [`add_collection_item`]을 사용하여 하나씩 추가해야 합니다. `collection_slug`, `item_id`, `item_type`만 알면 됩니다. 또한 선택적으로 항목에 `note`를 추가할 수도 있습니다(최대 500자). ```py >>> from huggingface_hub import create_collection, add_collection_item >>> collection = create_collection(title="OS Week Highlights - Sept 18 - 24", namespace="osanseviero") >>> collection.slug "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> add_collection_item(collection.slug, item_id="coqui/xtts", item_type="space") >>> add_collection_item( ... collection.slug, ... item_id="warp-ai/wuerstchen", ... item_type="model", ... note="Würstchen is a new fast and efficient high resolution text-to-image architecture and model" ... ) >>> add_collection_item(collection.slug, item_id="lmsys/lmsys-chat-1m", item_type="dataset") >>> add_collection_item(collection.slug, item_id="warp-ai/wuerstchen", item_type="space") # 동일한 item_id, 다른 item_type ``` Collection에 item이 이미 존재하는 경우(동일한 `item_id`/`item_type` 쌍), HTTP 409 오류가 발생합니다. `exists_ok=True`를 설정하면 이 오류를 무시할 수 있습니다. ### 기존 item에 메모 추가[[add-a-note-to-an-existing-item]] [`update_collection_item`]을 사용하여 기존 item을 수정하여 메모를 추가하거나 변경할 수 있습니다. 위의 예시를 다시 사용해 봅시다: ```py >>> from huggingface_hub import get_collection, update_collection_item # 새로 추가된 item과 함께 Collection 가져오기 >>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> collection = get_collection(collection_slug) # `lmsys-chat-1m` 데이터셋에 메모 추가 >>> update_collection_item( ... collection_slug=collection_slug, ... item_object_id=collection.items[2].item_object_id, ... note="This dataset contains one million real-world conversations with 25 state-of-the-art LLMs.", ... ) ``` ### item 재정렬[[reorder-items]] Collection의 item은 순서가 있습니다. 이 순서는 각 item의 `position` 속성에 의해 결정됩니다. 기본적으로 item은 Collection의 끝에 추가되는 방식으로 순서가 지정됩니다. [`update_collection_item`]을 사용하여 메모를 추가하는 것과 같은 방식으로 순서를 업데이트할 수 있습니다. 위의 예시를 다시 사용해 봅시다: ```py >>> from huggingface_hub import get_collection, update_collection_item # Collection 가져오기 >>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> collection = get_collection(collection_slug) # 두 개의 `Wuerstchen` item을 함께 배치하도록 재정렬 >>> update_collection_item( ... collection_slug=collection_slug, ... item_object_id=collection.items[3].item_object_id, ... position=2, ... ) ``` ### item 제거[[remove-items]] 마지막으로 [`delete_collection_item`]을 사용하여 item을 제거할 수도 있습니다. ```py >>> from huggingface_hub import get_collection, update_collection_item # Collection 가져오기 >>> collection_slug = "osanseviero/os-week-highlights-sept-18-24-650bfed7f795a59f491afb80" >>> collection = get_collection(collection_slug) # 목록에서 `coqui/xtts` Space 제거 >>> delete_collection_item(collection_slug=collection_slug, item_object_id=collection.items[0].item_object_id) ``` ## Collection 삭제[[delete-collection]] [`delete_collection`]을 사용하여 Collection을 삭제할 수 있습니다. > [!WARNING] > 이 작업은 되돌릴 수 없습니다. 삭제된 Collection은 복구할 수 없습니다. ```py >>> from huggingface_hub import delete_collection >>> collection = delete_collection("username/useless-collection-64f9a55bb3115b4f513ec026", missing_ok=True) ```huggingface_hub-1.1.5/docs/source/ko/guides/community.md000066400000000000000000000152201510763414300233160ustar00rootroot00000000000000 # Discussions 및 Pull Requests를 이용하여 상호작용하기[[interact-with-discussions-and-pull-requests]] `huggingface_hub` 라이브러리는 Hub의 Pull Requests 및 Discussions와 상호작용할 수 있는 Python 인터페이스를 제공합니다. [전용 문서 페이지](https://huggingface.co/docs/hub/repositories-pull-requests-discussions)를 방문하여 Hub의 Discussions와 Pull Requests가 무엇이고 어떻게 작동하는지 자세히 살펴보세요. ## Hub에서 Discussions 및 Pull Requests 가져오기[[retrieve-discussions-and-pull-requests-from-the-hub]] `HfApi` 클래스를 사용하면 지정된 리포지토리에 대한 Discussions 및 Pull Requests를 검색할 수 있습니다: ```python >>> from huggingface_hub import get_repo_discussions >>> for discussion in get_repo_discussions(repo_id="bigscience/bloom"): ... print(f"{discussion.num} - {discussion.title}, pr: {discussion.is_pull_request}") # 11 - Add Flax weights, pr: True # 10 - Update README.md, pr: True # 9 - Training languages in the model card, pr: True # 8 - Update tokenizer_config.json, pr: True # 7 - Slurm training script, pr: False [...] ``` `HfApi.get_repo_discussion`은 작성자, 유형(Pull Requests 또는 Discussion) 및 상태(`open` 또는 `closed`)별로 필터링을 지원합니다: ```python >>> from huggingface_hub import get_repo_discussions >>> for discussion in get_repo_discussions( ... repo_id="bigscience/bloom", ... author="ArthurZ", ... discussion_type="pull_request", ... discussion_status="open", ... ): ... print(f"{discussion.num} - {discussion.title} by {discussion.author}, pr: {discussion.is_pull_request}") # 19 - Add Flax weights by ArthurZ, pr: True ``` `HfApi.get_repo_discussions`는 [`Discussion`] 객체를 생성하는 [생성자](https://docs.python.org/3.7/howto/functional.html#generators)를 반환합니다. 모든 Discussions를 하나의 리스트로 가져오려면 다음을 실행합니다: ```python >>> from huggingface_hub import get_repo_discussions >>> discussions_list = list(get_repo_discussions(repo_id="bert-base-uncased")) ``` [`HfApi.get_repo_discussions`]가 반환하는 [`Discussion`] 객체에는 Discussions 또는 Pull Request에 대한 개략적인 개요가 포함되어 있습니다. [`HfApi.get_discussion_details`]를 사용하여 더 자세한 정보를 얻을 수도 있습니다: ```python >>> from huggingface_hub import get_discussion_details >>> get_discussion_details( ... repo_id="bigscience/bloom-1b3", ... discussion_num=2 ... ) DiscussionWithDetails( num=2, author='cakiki', title='Update VRAM memory for the V100s', status='open', is_pull_request=True, events=[ DiscussionComment(type='comment', author='cakiki', ...), DiscussionCommit(type='commit', author='cakiki', summary='Update VRAM memory for the V100s', oid='1256f9d9a33fa8887e1c1bf0e09b4713da96773a', ...), ], conflicting_files=[], target_branch='refs/heads/main', merge_commit_oid=None, diff='diff --git a/README.md b/README.md\nindex a6ae3b9294edf8d0eda0d67c7780a10241242a7e..3a1814f212bc3f0d3cc8f74bdbd316de4ae7b9e3 100644\n--- a/README.md\n+++ b/README.md\n@@ -132,7 +132,7 [...]', ) ``` [`HfApi.get_discussion_details`]는 Discussion 또는 Pull Request에 대한 자세한 정보가 포함된 [`Discussion`]의 하위 클래스인 [`DiscussionWithDetails`] 객체를 반환합니다. 해당 정보는 [`DiscussionWithDetails.events`]를 통해 Discussion의 모든 댓글, 상태 변경 및 이름 변경을 포함하고 있습니다. Pull Request의 경우, [`DiscussionWithDetails.diff`]를 통해 원시 git diff를 검색할 수 있습니다. Pull Request의 모든 커밋은 [`DiscussionWithDetails.events`]에 나열됩니다. ## 프로그래밍 방식으로 Discussion 또는 Pull Request를 생성하고 수정하기[[create-and-edit-a-discussion-or-pull-request-programmatically]] [`HfApi`] 클래스는 Discussions 및 Pull Requests를 생성하고 수정하는 방법도 제공합니다. Discussions와 Pull Requests를 만들고 편집하려면 [접근 토큰](https://huggingface.co/docs/hub/security-tokens)이 필요합니다. Hub의 리포지토리에 변경 사항을 제안하는 가장 간단한 방법은 [`create_commit`] API를 사용하는 것입니다. `create_pr` 매개변수를 `True`로 설정하기만 하면 됩니다. 이 매개변수는 [`create_commit`]을 래핑하는 다른 함수에서도 사용할 수 있습니다: * [`upload_file`] * [`upload_folder`] * [`delete_file`] * [`delete_folder`] * [`metadata_update`] ```python >>> from huggingface_hub import metadata_update >>> metadata_update( ... repo_id="username/repo_name", ... metadata={"tags": ["computer-vision", "awesome-model"]}, ... create_pr=True, ... ) ``` 리포지토리에 대한 Discussion(또는 Pull Request)을 만들려면 [`HfApi.create_discussion`](또는 [`HfApi.create_pull_request`])을 사용할 수도 있습니다. 이 방법으로 Pull Request를 열면 로컬에서 변경 작업을 해야 하는 경우에 유용할 수 있습니다. 이 방법으로 열린 Pull Request는 `"draft"` 모드가 됩니다. ```python >>> from huggingface_hub import create_discussion, create_pull_request >>> create_discussion( ... repo_id="username/repo-name", ... title="Hi from the huggingface_hub library!", ... token="", ... ) DiscussionWithDetails(...) >>> create_pull_request( ... repo_id="username/repo-name", ... title="Hi from the huggingface_hub library!", ... token="", ... ) DiscussionWithDetails(..., is_pull_request=True) ``` Pull Requests 및 Discussions 관리는 전적으로 [`HfApi`] 클래스로 할 수 있습니다. 예를 들어: * 댓글을 추가하려면 [`comment_discussion`] * 댓글을 수정하려면 [`edit_discussion_comment`] * Discussion 또는 Pull Request의 이름을 바꾸려면 [`rename_discussion`] * Discussion / Pull Request를 열거나 닫으려면 [`change_discussion_status`] * Pull Request를 병합하려면 [`merge_pull_request`]를 사용합니다. 사용 가능한 모든 메소드에 대한 전체 참조는 [`HfApi`] 문서 페이지를 참조하세요. ## Pull Request에 변경 사항 푸시[[push-changes-to-a-pull-request]] *곧 공개됩니다!* ## 참고 항목[[see-also]] 더 자세한 내용은 [Discussions 및 Pull Requests](../package_reference/community)와 [hf_api](../package_reference/hf_api) 문서 페이지를 참조하세요. huggingface_hub-1.1.5/docs/source/ko/guides/download.md000066400000000000000000000344701510763414300231110ustar00rootroot00000000000000 # Hub에서 파일 다운로드하기[[download-files-from-the-hub]] `huggingface_hub` 라이브러리는 Hub의 저장소에서 파일을 다운로드하는 기능을 제공합니다. 이 기능은 함수로 직접 사용할 수 있고, 사용자가 만든 라이브러리에 통합하여 Hub와 쉽게 상호 작용할 수 있도록 할 수 있습니다. 이 가이드에서는 다음 내용을 다룹니다: * 파일 하나를 다운로드하고 캐시하는 방법 * 리포지토리 전체를 다운로드하고 캐시하는 방법 * 로컬 폴더에 파일을 다운로드하는 방법 ## 파일 하나만 다운로드하기[[download-a-single-file]] [`hf_hub_download`] 함수를 사용하면 Hub에서 파일을 다운로드할 수 있습니다. 이 함수는 원격 파일을 다운로드하여 (버전별로) 디스크에 캐시하고, 로컬 파일 경로를 반환합니다. > [!TIP] > 반환된 파일 경로는 HF 로컬 캐시의 위치를 가리킵니다. 그러므로 캐시가 손상되지 않도록 파일을 수정하지 않는 것이 좋습니다. 캐시가 어떻게 작동하는지 자세히 알고 싶으시면 [캐싱 가이드](./manage-cache)를 참조하세요. ### 최신 버전에서 파일 다운로드하기[[from-latest-version]] 다운로드할 파일을 선택하기 위해 `repo_id`, `repo_type`, `filename` 매개변수를 사용합니다. `repo_type` 매개변수를 생략하면 파일은 `model` 리포의 일부라고 간주됩니다. ```python >>> from huggingface_hub import hf_hub_download >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json") '/root/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade/config.json' # 데이터세트의 경우 >>> hf_hub_download(repo_id="google/fleurs", filename="fleurs.py", repo_type="dataset") '/root/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34/fleurs.py' ``` ### 특정 버전에서 파일 다운로드하기[[from-specific-version]] 기본적으로 `main` 브랜치의 최신 버전의 파일이 다운로드됩니다. 그러나 특정 버전의 파일을 다운로드하고 싶을 수도 있습니다. 예를 들어, 특정 브랜치, 태그, 커밋 해시 등에서 파일을 다운로드하고 싶을 수 있습니다. 이 경우 `revision` 매개변수를 사용하여 원하는 버전을 지정할 수 있습니다: ```python # `v1.0` 태그에서 다운로드하기 >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="v1.0") # `test-branch` 브랜치에서 다운로드하기 >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="test-branch") # PR #3에서 다운로드하기 >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="refs/pr/3") # 특정 커밋 해시에서 다운로드하기 >>> hf_hub_download(repo_id="lysandre/arxiv-nlp", filename="config.json", revision="877b84a8f93f2d619faa2a6e514a32beef88ab0a") ``` **참고**: 커밋 해시를 사용할 때는 7자리의 짧은 커밋 해시가 아니라 전체 길이의 커밋 해시를 사용해야 합니다. ### 다운로드 URL 만들기[[construct-a-download-url]] 리포지토리에서 파일을 다운로드하는 데 사용할 URL을 만들고 싶은 경우 [`hf_hub_url`] 함수를 사용하여 URL을 반환받을 수 있습니다. 이 함수는 [`hf_hub_download`] 함수가 내부적으로 사용하는 URL을 생성한다는 점을 알아두세요. ## 전체 리포지토리 다운로드하기[[download-an-entire-repository]] [`snapshot_download`] 함수는 특정 버전의 전체 리포지토리를 다운로드합니다. 이 함수는 내부적으로 [`hf_hub_download`] 함수를 사용하므로, 다운로드한 모든 파일은 로컬 디스크에 캐시되어 저장됩니다. 다운로드는 여러 파일을 동시에 받아오기 때문에 빠르게 진행됩니다. 전체 리포지토리를 다운로드하려면 `repo_id`와 `repo_type`을 인자로 넘겨주면 됩니다: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp") '/home/lysandre/.cache/huggingface/hub/models--lysandre--arxiv-nlp/snapshots/894a9adde21d9a3e3843e6d5aeaaf01875c7fade' # 또는 데이터세트의 경우 >>> snapshot_download(repo_id="google/fleurs", repo_type="dataset") '/home/lysandre/.cache/huggingface/hub/datasets--google--fleurs/snapshots/199e4ae37915137c555b1765c01477c216287d34' ``` [`snapshot_download`] 함수는 기본적으로 최신 버전의 리포지토리를 다운로드합니다. 특정 버전의 리포지토리를 다운로드하고 싶은 경우, `revision` 매개변수에 원하는 버전을 지정하면 됩니다: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", revision="refs/pr/1") ``` ### 다운로드할 파일 선택하기[[filter-files-to-download]] [`snapshot_download`] 함수는 리포지토리를 쉽게 다운로드할 수 있도록 해줍니다. 그러나 리포지토리의 모든 내용을 다운로드하고 싶지 않을 수도 있습니다. 예를 들어, `.safetensors` 가중치만 사용하고 싶다면, 모든 `.bin` 파일을 다운로드하지 않도록 할 수 있습니다. `allow_pattern`과 `ignore_pattern` 매개변수를 사용하여 원하는 파일만 다운로드할 수 있습니다. 이 매개변수들은 하나의 패턴이나 패턴의 리스트를 받을 수 있습니다. 패턴은 [여기](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm)에서 설명된 것처럼 표준 와일드카드(글로빙 패턴)입니다. 패턴 매칭은 [`fnmatch`](https://docs.python.org/3/library/fnmatch.html)에 기반합니다. 예를 들어, `allow_patterns`를 사용하여 JSON 구성 파일만 다운로드하는 방법은 다음과 같습니다: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", allow_patterns="*.json") ``` 반대로 `ignore_patterns`는 특정 파일을 다운로드에서 제외시킬 수 있습니다. 다음 예제는 `.msgpack`과 `.h5` 파일 확장자를 무시하는 방법입니다: ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="lysandre/arxiv-nlp", ignore_patterns=["*.msgpack", "*.h5"]) ``` 마지막으로, 두 가지 매개변수를 함께 사용하여 다운로드를 정확하게 선택할 수 있습니다. 다음은 `vocab.json`을 제외한 모든 json 및 마크다운 파일을 다운로드하는 예제입니다. ```python >>> from huggingface_hub import snapshot_download >>> snapshot_download(repo_id="gpt2", allow_patterns=["*.md", "*.json"], ignore_patterns="vocab.json") ``` ## 로컬 폴더에 파일 다운로드하기[[download-files-to-local-folder]] Hub에서 파일을 다운로드하는 가장 좋은 (그리고 기본적인) 방법은 [캐시 시스템](./manage-cache)을 사용하는 것입니다. 캐시 위치는 `cache_dir` 매개변수로 설정하여 지정할 수 있습니다([`hf_hub_download`]과 [`snapshot_download`]에서 모두 사용 가능). 그러나 파일을 다운로드하여 특정 폴더에 넣고 싶은 경우도 있습니다. 이 기능은 `git` 명령어가 제공하는 기능과 비슷한 워크플로우를 만들 수 있습니다. 이 경우 `local_dir`과 `local_dir_use_symlinks` 매개변수를 사용하여 원하는 대로 파일을 넣을 수 있습니다: - `local_dir`은 시스템 내의 폴더 경로입니다. 다운로드한 파일은 리포지토리에 있는 것과 같은 파일 구조를 유지합니다. 예를 들어 `filename="data/train.csv"`와 `local_dir="path/to/folder"`라면, 반환된 파일 경로는 `"path/to/folder/data/train.csv"`가 됩니다. - `local_dir_use_symlinks`는 파일을 로컬 폴더에 어떻게 넣을지 정의합니다. - 기본 동작('자동')은 작은 파일(5MB 이하)은 복사하고 큰 파일은 심볼릭 링크를 사용하는 것입니다. 심볼릭 링크를 사용하면 대역폭과 디스크 공간을 모두 절약할 수 있습니다. 그러나 심볼릭 링크된 파일을 직접 수정하면 캐시가 손상될 수 있으므로 작은 파일에 대해서는 복사를 사용합니다. 5MB 임계값은 `HF_HUB_LOCAL_DIR_AUTO_SYMLINK_THRESHOLD` 환경 변수로 설정할 수 있습니다. - `local_dir_use_symlinks=true`로 설정하면 디스크 공간을 최대한 절약하기 위해 모든 파일이 심볼릭 링크됩니다. 이는 예를 들어 수천 개의 작은 파일로 이루어진 대용량 데이터 세트를 다운로드할 때 유용합니다. - 마지막으로 심볼릭 링크를 전혀 사용하지 않으려면 심볼릭 링크를 비활성화하면 됩니다(`local_dir_use_symlinks=False`). 캐시 디렉토리는 파일이 이미 캐시되었는지 여부를 확인하는 데 계속 사용됩니다. 이미 캐시된 경우 파일이 캐시에서 **복사**됩니다(즉, 대역폭은 절약되지만 디스크 공간이 증가합니다). 파일이 아직 캐시되지 않은 경우 파일을 다운로드하여 로컬 디렉터리에 바로 넣습니다. 즉, 나중에 다른 곳에서 다시 사용하려면 **다시 다운로드**해야 합니다. 다음은 다양한 옵션을 요약한 표입니다. 이 표를 참고하여 자신의 사용 사례에 가장 적합한 매개변수를 선택하세요. | 파라미터 | 캐시되었는지 여부 | 반환된 파일경로 | 열람 권한 | 수정 권한 | 대역폭의 효율적인 사용 | 디스크의 효율적인 접근 | |---|:---:|:---:|:---:|:---:|:---:|:---:| | `local_dir=None` | | 캐시 속 심볼릭 링크 | ✅ | ❌
_(저장하면 캐시가 손상됩니다)_ | ✅ | ✅ | | `local_dir="path/to/folder"`
`local_dir_use_symlinks="auto"` | | 폴더 속 파일 또는 심볼릭 링크 | ✅ | ✅ _(소규모 파일의 경우)_
⚠️ _(대규모 파일의 경우 저장하기 전에 경로를 생성하지 마세요)_ | ✅ | ✅ | | `local_dir="path/to/folder"`
`local_dir_use_symlinks=True` | | 폴더 속 심볼릭 링크 | ✅ | ⚠️
_(저장하기 전에 경로를 생성하지 마세요)_ | ✅ | ✅ | | `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | 아니오 | 폴더 속 파일 | ✅ | ✅ | ❌
_(다시 실행하면 파일도 다시 다운로드됩니다)_ | ⚠️
(여러 폴더에서 실행하면 그만큼 복사본이 생깁니다) | | `local_dir="path/to/folder"`
`local_dir_use_symlinks=False` | 예 | 폴더 속 파일 | ✅ | ✅ | ⚠️
_(파일이 캐시되어 있어야 합니다)_ | ❌
_(파일이 중복됩니다)_ | **참고**: Windows 컴퓨터를 사용하는 경우 심볼릭 링크를 사용하려면 개발자 모드를 켜거나 관리자 권한으로 `huggingface_hub`를 실행해야 합니다. 자세한 내용은 [캐시 제한](../guides/manage-cache#limitations) 섹션을 참조하세요. ## CLI에서 파일 다운로드하기[[download-from-the-cli]] 터미널에서 `hf download` 명령어를 사용하면 Hub에서 파일을 바로 다운로드할 수 있습니다. 이 명령어는 내부적으로 앞서 설명한 [`hf_hub_download`]과 [`snapshot_download`] 함수를 사용하고, 다운로드한 파일의 로컬 경로를 터미널에 출력합니다: ```bash >>> hf download gpt2 config.json /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json ``` 기본적으로 (`hf auth login` 명령으로) 로컬에 저장된 토큰을 사용합니다. 직접 인증하고 싶다면, `--token` 옵션을 사용하세요: ```bash >>> hf download gpt2 config.json --token=hf_**** /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json ``` 여러 파일을 한 번에 다운로드하면 진행률 표시줄이 보이고, 파일이 있는 스냅샷 경로가 반환됩니다: ```bash >>> hf download gpt2 config.json model.safetensors Fetching 2 files: 100%|████████████████████████████████████████████| 2/2 [00:00<00:00, 23831.27it/s] /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 ``` 진행률 표시줄이나 잠재적 경고가 필요 없다면 `--quiet` 옵션을 사용하세요. 이 옵션은 스크립트에서 다른 명령어로 출력을 넘겨주려는 경우에 유용할 수 있습니다. ```bash >>> hf download gpt2 config.json model.safetensors /home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10 ``` 기본적으로 파일은 `HF_HOME` 환경 변수에 정의된 캐시 디렉터리(또는 지정하지 않은 경우 `~/.cache/huggingface/hub`)에 다운로드됩니다. 캐시 디렉터리는 `--cache-dir` 옵션으로 변경할 수 있습니다: ```bash >>> hf download gpt2 config.json --cache-dir=./cache ./cache/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.json ``` 캐시 디렉터리 구조를 따르지 않고 로컬 폴더에 파일을 다운로드하려면 `--local-dir` 옵션을 사용하세요. 로컬 폴더로 다운로드하면 이 [표](https://huggingface.co/docs/huggingface_hub/guides/download#download-files-to-local-folder)에 나열된 제한 사항이 있습니다. ```bash >>> hf download gpt2 config.json --local-dir=./models/gpt2 ./models/gpt2/config.json ``` 다른 리포지토리 유형이나 버전에서 파일을 다운로드하거나 glob 패턴을 사용하여 다운로드할 파일을 선택하거나 제외하도록 지정할 수 있는 인수들이 더 있습니다: ```bash >>> hf download bigcode/the-stack --repo-type=dataset --revision=v1.2 --include="data/python/*" --exclu de="*.json" --exclude="*.zip" Fetching 206 files: 100%|████████████████████████████████████████████| 206/206 [02:31<2:31, ?it/s] /home/wauplin/.cache/huggingface/hub/datasets--bigcode--the-stack/snapshots/9ca8fa6acdbc8ce920a0cb58adcdafc495818ae7 ``` 인수들의 전체 목록을 보려면 다음 명령어를 실행하세요: ```bash hf download --help ``` huggingface_hub-1.1.5/docs/source/ko/guides/hf_file_system.md000066400000000000000000000124221510763414300242730ustar00rootroot00000000000000 # Hugging Face Hub에서 파일 시스템 API를 통해 상호작용하기[[interact-with-the-hub-through-the-filesystem-api]] `huggingface_hub` 라이브러리는 [`HfApi`] 외에도 Hugging Face Hub에 대한 파이써닉한 [fsspec-compatible](https://filesystem-spec.readthedocs.io/en/latest/) 파일 인터페이스인 [`HfFileSystem`]을 제공합니다. [`HfFileSystem`]은 [`HfApi`]을 기반으로 구축되며, `cp`, `mv`, `ls`, `du`, `glob`, `get_file` 및 `put_file`과 같은 일반적인 파일 시스템 스타일 작업을 제공합니다. ## 사용법[[usage]] ```python >>> from huggingface_hub import HfFileSystem >>> fs = HfFileSystem() >>> # 디렉터리의 모든 파일 나열하기 >>> fs.ls("datasets/my-username/my-dataset-repo/data", detail=False) ['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv'] >>> # 저장소(repo)에서 ".csv" 파일 모두 나열하기 >>> fs.glob("datasets/my-username/my-dataset-repo/**.csv") ['datasets/my-username/my-dataset-repo/data/train.csv', 'datasets/my-username/my-dataset-repo/data/test.csv'] >>> # 원격 파일 읽기 >>> with fs.open("datasets/my-username/my-dataset-repo/data/train.csv", "r") as f: ... train_data = f.readlines() >>> # 문자열로 원격 파일의 내용 읽기 >>> train_data = fs.read_text("datasets/my-username/my-dataset-repo/data/train.csv", revision="dev") >>> # 원격 파일 쓰기 >>> with fs.open("datasets/my-username/my-dataset-repo/data/validation.csv", "w") as f: ... f.write("text,label") ... f.write("Fantastic movie!,good") ``` 선택적 `revision` 인수를 전달하여 브랜치, 태그 이름 또는 커밋 해시와 같은 특정 커밋에서 작업을 실행할 수 있습니다. 파이썬에 내장된 `open`과 달리 `fsspec`의 `open`은 바이너리 모드 `"rb"`로 기본 설정됩니다. 이것은 텍스트 모드에서 읽기 위해 `"r"`, 쓰기 위해 `"w"`로 모드를 명시적으로 설정해야 함을 의미합니다. 파일에 추가하기(모드 `"a"` 및 `"ab"`)는 아직 지원되지 않습니다. ## 통합[[integrations]] [`HfFileSystem`]은 URL이 다음 구문을 따르는 경우 `fsspec`을 통합하는 모든 라이브러리에서 사용할 수 있습니다. ``` hf://[][@]/ ``` 여기서 `repo_type_prefix`는 Datasets의 경우 `datasets/`, Spaces의 경우 `spaces/`이며, 모델에는 URL에 접두사가 필요하지 않습니다. [`HfFileSystem`]이 Hub와의 상호작용을 단순화하는 몇 가지 흥미로운 통합 사례는 다음과 같습니다: * Hub 저장소에서 [Pandas](https://pandas.pydata.org/pandas-docs/stable/user_guide/io.html#reading-writing-remote-files) DataFrame 읽기/쓰기: ```python >>> import pandas as pd >>> # 원격 CSV 파일을 데이터프레임으로 읽기 >>> df = pd.read_csv("hf://datasets/my-username/my-dataset-repo/train.csv") >>> # 데이터프레임을 원격 CSV 파일로 쓰기 >>> df.to_csv("hf://datasets/my-username/my-dataset-repo/test.csv") ``` 동일한 워크플로우를 [Dask](https://docs.dask.org/en/stable/how-to/connect-to-remote-data.html) 및 [Polars](https://pola-rs.github.io/polars/py-polars/html/reference/io.html) DataFrame에도 사용할 수 있습니다. * [DuckDB](https://duckdb.org/docs/guides/python/filesystems)를 사용하여 (원격) Hub 파일 쿼리: ```python >>> from huggingface_hub import HfFileSystem >>> import duckdb >>> fs = HfFileSystem() >>> duckdb.register_filesystem(fs) >>> # 원격 파일을 쿼리하고 결과를 데이터프레임으로 가져오기 >>> fs_query_file = "hf://datasets/my-username/my-dataset-repo/data_dir/data.parquet" >>> df = duckdb.query(f"SELECT * FROM '{fs_query_file}' LIMIT 10").df() ``` * [Zarr](https://zarr.readthedocs.io/en/stable/tutorial.html#io-with-fsspec)를 사용하여 Hub를 배열 저장소로 사용: ```python >>> import numpy as np >>> import zarr >>> embeddings = np.random.randn(50000, 1000).astype("float32") >>> # 저장소(repo)에 배열 쓰기 >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="w") as root: ... foo = root.create_group("embeddings") ... foobar = foo.zeros('experiment_0', shape=(50000, 1000), chunks=(10000, 1000), dtype='f4') ... foobar[:] = embeddings >>> # 저장소(repo)에서 배열 읽기 >>> with zarr.open_group("hf://my-username/my-model-repo/array-store", mode="r") as root: ... first_row = root["embeddings/experiment_0"][0] ``` ## 인증[[authentication]] 대부분의 경우 Hub와 상호작용하려면 Hugging Face 계정에 로그인해야 합니다. Hub에서 인증 방법에 대해 자세히 알아보려면 문서의 [인증](../quick-start#authentication) 섹션을 참조하세요. 또한 [`HfFileSystem`]에 `token`을 인수로 전달하여 프로그래밍 방식으로 로그인할 수 있습니다: ```python >>> from huggingface_hub import HfFileSystem >>> fs = HfFileSystem(token=token) ``` 이렇게 로그인하는 경우 소스 코드를 공유할 때 토큰이 실수로 누출되지 않도록 주의해야 합니다! huggingface_hub-1.1.5/docs/source/ko/guides/inference.md000066400000000000000000000352731510763414300232420ustar00rootroot00000000000000 # 서버에서 추론 진행하기[[run-inference-on-servers]] 추론은 훈련된 모델을 사용하여 새 데이터에 대한 예측을 수행하는 과정입니다. 이 과정은 계산이 많이 필요할 수 있으므로, 전용 서버에서 실행하는 것이 좋은 방안이 될 수 있습니다. `huggingface_hub` 라이브러리는 호스팅된 모델에 대한 추론을 실행하는 서비스를 호출하는 간편한 방법을 제공합니다. 다음과 같은 여러 서비스에 연결할 수 있습니다: - [추론 API](https://huggingface.co/docs/api-inference/index): Hugging Face의 인프라에서 가속화된 추론을 실행할 수 있는 서비스로 무료로 제공됩니다. 이 서비스는 추론을 시작하고 다양한 모델을 테스트하며 AI 제품의 프로토타입을 만드는 빠른 방법입니다. - [추론 엔드포인트](https://huggingface.co/docs/inference-endpoints/index): 모델을 제품 환경에 쉽게 배포할 수 있는 제품입니다. 사용자가 선택한 클라우드 환경에서 완전 관리되는 전용 인프라에서 Hugging Face를 통해 추론이 실행됩니다. > [!TIP] > [`InferenceClient`]는 API에 HTTP 호출을 수행하는 Python 클라이언트입니다. HTTP 호출을 원하는 툴을 이용하여 직접 사용하려면 (curl, postman 등) [추론 API](https://huggingface.co/docs/api-inference/index) 또는 [추론 엔드포인트](https://huggingface.co/docs/inference-endpoints/index) 문서 페이지를 참조하세요. > > 웹 개발을 위해 [JS 클라이언트](https://huggingface.co/docs/huggingface.js/inference/README)가 출시되었습니다. 게임 개발에 관심이 있다면 [C# 프로젝트](https://github.com/huggingface/unity-api)를 살펴보세요. ## 시작하기[[getting-started]] text-to-image 작업을 시작해보겠습니다. ```python >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> image = client.text_to_image("An astronaut riding a horse on the moon.") >>> image.save("astronaut.png") ``` 우리는 기본 매개변수로 [`InferenceClient`]를 초기화했습니다. 수행하고자 하는 [작업](#supported-tasks)만 알면 됩니다. 기본적으로 클라이언트는 추론 API에 연결하고 작업을 완료할 모델을 선택합니다. 예제에서는 텍스트 프롬프트에서 이미지를 생성했습니다. 반환된 값은 파일로 저장할 수 있는 `PIL.Image` 객체입니다. > [!WARNING] > API는 간단하게 설계되었습니다. 모든 매개변수와 옵션이 사용 가능하거나 설명되어 있는 것은 아닙니다. 각 작업에서 사용 가능한 모든 매개변수에 대해 자세히 알아보려면 [이 페이지](https://huggingface.co/docs/api-inference/detailed_parameters)를 확인하세요. ### 특정 모델 사용하기[[using-a-specific-model]] 특정 모델을 사용하고 싶다면 어떻게 해야 할까요? 매개변수로 직접 지정하거나 인스턴스 수준에서 직접 지정할 수 있습니다: ```python >>> from huggingface_hub import InferenceClient # 특정 모델을 위한 클라이언트를 초기화합니다. >>> client = InferenceClient(model="prompthero/openjourney-v4") >>> client.text_to_image(...) # 또는 일반적인 클라이언트를 사용하되 모델을 인수로 전달하세요. >>> client = InferenceClient() >>> client.text_to_image(..., model="prompthero/openjourney-v4") ``` > [!TIP] > Hugging Face Hub에는 20만 개가 넘는 모델이 있습니다! [`InferenceClient`]의 각 작업에는 추천되는 모델이 포함되어 있습니다. HF의 추천은 사전 고지 없이 시간이 지남에 따라 변경될 수 있음을 유의하십시오. 따라서 모델을 결정한 후에는 명시적으로 모델을 설정하는 것이 좋습니다. 또한 대부분의 경우 자신의 필요에 맞는 모델을 직접 찾고자 할 것입니다. 허브의 [모델](https://huggingface.co/models) 페이지를 방문하여 찾아보세요. ### 특정 URL 사용하기[[using-a-specific-url]] 위에서 본 예제들은 서버리스 추론 API를 사용합니다. 이는 빠르게 프로토타입을 정하고 테스트할 때 매우 유용합니다. 모델을 프로덕션 환경에 배포할 준비가 되면 전용 인프라를 사용해야 합니다. 그것이 [추론 엔드포인트](https://huggingface.co/docs/inference-endpoints/index)가 필요한 이유입니다. 이를 사용하면 모든 모델을 배포하고 개인 API로 노출시킬 수 있습니다. 한 번 배포되면 이전과 완전히 동일한 코드를 사용하여 연결할 수 있는 URL을 얻게 됩니다. `model` 매개변수만 변경하면 됩니다: ```python >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if") # 또는 >>> client = InferenceClient() >>> client.text_to_image(..., model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if") ``` ### 인증[[authentication]] [`InferenceClient`]로 수행된 호출은 [사용자 액세스 토큰](https://huggingface.co/docs/hub/security-tokens)을 사용하여 인증할 수 있습니다. 기본적으로 로그인한 경우 기기에 저장된 토큰을 사용합니다 ([인증 방법](https://huggingface.co/docs/huggingface_hub/quick-start#authentication)을 확인하세요). 로그인하지 않은 경우 인스턴스 매개변수로 토큰을 전달할 수 있습니다. ```python >>> from huggingface_hub import InferenceClient >>> client = InferenceClient(token="hf_***") ``` > [!TIP] > 추론 API를 사용할 때 인증은 필수가 아닙니다. 그러나 인증된 사용자는 서비스를 이용할 수 있는 더 높은 무료 티어를 받습니다. 토큰은 개인 모델이나 개인 엔드포인트에서 추론을 실행하려면 필수입니다. ## 지원되는 작업[[supported-tasks]] [`InferenceClient`]의 목표는 Hugging Face 모델에서 추론을 실행하기 위한 가장 쉬운 인터페이스를 제공하는 것입니다. 이는 가장 일반적인 작업들을 지원하는 간단한 API를 가지고 있습니다. 현재 지원되는 작업 목록은 다음과 같습니다: | 도메인 | 작업 | 지원 여부 | 문서 | | ----------- | --------------------------------------------------------------------------------- | --------- | --------------------------------------------------- | | 오디오 | [오디오 분류](https://huggingface.co/tasks/audio-classification) | ✅ | [`~InferenceClient.audio_classification`] | | 오디오 | [오디오 투 오디오](https://huggingface.co/tasks/audio-to-audio) | ✅ | [`~InferenceClient.audio_to_audio`] | | | [자동 음성 인식](https://huggingface.co/tasks/automatic-speech-recognition) | ✅ | [`~InferenceClient.automatic_speech_recognition`] | | | [텍스트 투 스피치](https://huggingface.co/tasks/text-to-speech) | ✅ | [`~InferenceClient.text_to_speech`] | | 컴퓨터 비전 | [이미지 분류](https://huggingface.co/tasks/image-classification) | ✅ | [`~InferenceClient.image_classification`] | | | [이미지 분할](https://huggingface.co/tasks/image-segmentation) | ✅ | [`~InferenceClient.image_segmentation`] | | | [이미지 투 이미지](https://huggingface.co/tasks/image-to-image) | ✅ | [`~InferenceClient.image_to_image`] | | | [이미지 투 텍스트](https://huggingface.co/tasks/image-to-text) | ✅ | [`~InferenceClient.image_to_text`] | | | [객체 탐지](https://huggingface.co/tasks/object-detection) | ✅ | [`~InferenceClient.object_detection`] | | | [텍스트 투 이미지](https://huggingface.co/tasks/text-to-image) | ✅ | [`~InferenceClient.text_to_image`] | | | [제로샷 이미지 분류](https://huggingface.co/tasks/zero-shot-image-classification) | ✅ | [`~InferenceClient.zero_shot_image_classification`] | | 멀티모달 | [문서 질의 응답](https://huggingface.co/tasks/document-question-answering) | ✅ | [`~InferenceClient.document_question_answering`] | | | [시각적 질의 응답](https://huggingface.co/tasks/visual-question-answering) | ✅ | [`~InferenceClient.visual_question_answering`] | | 자연어 처리 | [대화형](https://huggingface.co/tasks/conversational) | ✅ | [`~InferenceClient.conversational`] | | | [특성 추출](https://huggingface.co/tasks/feature-extraction) | ✅ | [`~InferenceClient.feature_extraction`] | | | [마스크 채우기](https://huggingface.co/tasks/fill-mask) | ✅ | [`~InferenceClient.fill_mask`] | | | [질의 응답](https://huggingface.co/tasks/question-answering) | ✅ | [`~InferenceClient.question_answering`] | | | [문장 유사도](https://huggingface.co/tasks/sentence-similarity) | ✅ | [`~InferenceClient.sentence_similarity`] | | | [요약](https://huggingface.co/tasks/summarization) | ✅ | [`~InferenceClient.summarization`] | | | [테이블 질의 응답](https://huggingface.co/tasks/table-question-answering) | ✅ | [`~InferenceClient.table_question_answering`] | | | [텍스트 분류](https://huggingface.co/tasks/text-classification) | ✅ | [`~InferenceClient.text_classification`] | | | [텍스트 생성](https://huggingface.co/tasks/text-generation) | ✅ | [`~InferenceClient.text_generation`] | | | [토큰 분류](https://huggingface.co/tasks/token-classification) | ✅ | [`~InferenceClient.token_classification`] | | | [번역](https://huggingface.co/tasks/translation) | ✅ | [`~InferenceClient.translation`] | | | [제로샷 분류](https://huggingface.co/tasks/zero-shot-classification) | ✅ | [`~InferenceClient.zero_shot_classification`] | | 타블로 | [타블로 작업 분류](https://huggingface.co/tasks/tabular-classification) | ✅ | [`~InferenceClient.tabular_classification`] | | | [타블로 회귀](https://huggingface.co/tasks/tabular-regression) | ✅ | [`~InferenceClient.tabular_regression`] | > [!TIP] > 각 작업에 대해 더 자세히 알고 싶거나 사용 방법 및 각 작업에 대한 가장 인기 있는 모델을 알아보려면 [Tasks](https://huggingface.co/tasks) 페이지를 확인하세요. ## 비동기 클라이언트[[async-client]] `asyncio`와 `aiohttp`를 기반으로 한 클라이언트의 비동기 버전도 제공됩니다. `aiohttp`를 직접 설치하거나 `[inference]` 추가 옵션을 사용할 수 있습니다: ```sh pip install --upgrade huggingface_hub[inference] # 또는 # pip install aiohttp ``` 설치 후 모든 비동기 API 엔드포인트는 [`AsyncInferenceClient`]를 통해 사용할 수 있습니다. 초기화 및 API는 동기 전용 버전과 완전히 동일합니다. ```py # 코드는 비동기 asyncio 라이브러리 동시성 컨텍스트에서 실행되어야 합니다. # $ python -m asyncio >>> from huggingface_hub import AsyncInferenceClient >>> client = AsyncInferenceClient() >>> image = await client.text_to_image("An astronaut riding a horse on the moon.") >>> image.save("astronaut.png") >>> async for token in await client.text_generation("The Huggingface Hub is", stream=True): ... print(token, end="") a platform for sharing and discussing ML-related content. ``` `asyncio` 모듈에 대한 자세한 정보는 [공식 문서](https://docs.python.org/3/library/asyncio.html)를 참조하세요. ## 고급 팁[[advanced-tips]] 위 섹션에서는 [`InferenceClient`]의 주요 측면을 살펴보았습니다. 이제 몇 가지 고급 팁에 대해 자세히 알아보겠습니다. ### 타임아웃[[timeout]] 추론을 수행할 때 타임아웃이 발생하는 주요 원인은 두 가지입니다: - 추론 프로세스가 완료되는 데 오랜 시간이 걸리는 경우 - 모델이 사용 불가능한 경우, 예를 들어 Inference API를 처음으로 가져오는 경우 [`InferenceClient`]에는 이 두 가지를 처리하기 위한 전역 `timeout` 매개변수가 있습니다. 기본값은 `None`으로 설정되어 있으며, 클라이언트가 추론이 완료될 때까지 무기한으로 기다리게 합니다. 워크플로우에서 더 많은 제어를 원하는 경우 초 단위의 특정한 값으로 설정할 수 있습니다. 타임아웃 딜레이가 만료되면 [`InferenceTimeoutError`]가 발생합니다. 이를 코드에서 처리할 수 있습니다: ```python >>> from huggingface_hub import InferenceClient, InferenceTimeoutError >>> client = InferenceClient(timeout=30) >>> try: ... client.text_to_image(...) ... except InferenceTimeoutError: ... print("Inference timed out after 30s.") ``` ### 이진 입력[[binary-inputs]] 일부 작업에는 이미지 또는 오디오 파일을 처리할 때와 같이 이진 입력이 필요한 경우가 있습니다. 이 경우 [`InferenceClient`]는 최대한 다양한 유형을 융통성 있게 허용합니다: - 원시 `bytes` - 이진으로 열린 파일과 유사한 객체 (`with open("audio.flac", "rb") as f: ...`) - 로컬 파일을 가리키는 경로 (`str` 또는 `Path`) - 원격 파일을 가리키는 URL (`str`) (예: `https://...`). 이 경우 파일은 Inference API로 전송되기 전에 로컬로 다운로드됩니다. ```py >>> from huggingface_hub import InferenceClient >>> client = InferenceClient() >>> client.image_classification("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg") [{'score': 0.9779096841812134, 'label': 'Blenheim spaniel'}, ...] ``` huggingface_hub-1.1.5/docs/source/ko/guides/inference_endpoints.md000066400000000000000000000355261510763414300253260ustar00rootroot00000000000000# 추론 엔드포인트[[inference-endpoints]] 추론 엔드포인트는 Hugging Face가 관리하는 전용 및 자동 확장 인프라에 `transformers`, `sentence-transformers` 및 `diffusers` 모델을 쉽게 배포할 수 있는 안전한 프로덕션 솔루션을 제공합니다. 추론 엔드포인트는 [Hub](https://huggingface.co/models)의 모델로 구축됩니다. 이 가이드에서는 `huggingface_hub`를 사용하여 프로그래밍 방식으로 추론 엔드포인트를 관리하는 방법을 배웁니다. 추론 엔드포인트 제품 자체에 대한 자세한 내용은 [공식 문서](https://huggingface.co/docs/inference-endpoints/index)를 참조하세요. 이 가이드에서는 `huggingface_hub`가 올바르게 설치 및 로그인되어 있다고 가정합니다. 아직 그렇지 않은 경우 [빠른 시작 가이드](https://huggingface.co/docs/huggingface_hub/quick-start#quickstart)를 참조하세요. 추론 엔드포인트 API를 지원하는 최소 버전은 `v0.19.0`입니다. ## 추론 엔드포인트 생성[[create-an-inference-endpoint]] 첫 번째 단계는 [`create_inference_endpoint`]를 사용하여 추론 엔드포인트를 생성하는 것입니다: ```py >>> from huggingface_hub import create_inference_endpoint >>> endpoint = create_inference_endpoint( ... "my-endpoint-name", ... repository="gpt2", ... framework="pytorch", ... task="text-generation", ... accelerator="cpu", ... vendor="aws", ... region="us-east-1", ... type="protected", ... instance_size="x2", ... instance_type="intel-icl" ... ) ``` 예시에서는 `"my-endpoint-name"`라는 `protected` 추론 엔드포인트를 생성하여 `text-generation`을 위한 [gpt2](https://huggingface.co/gpt2)를 제공합니다. `protected` 추론 엔드포인트 API에 액세스하려면 토큰이 필요합니다. 또한 벤더, 지역, 액셀러레이터, 인스턴스 유형, 크기와 같은 하드웨어 요구 사항을 구성하기 위한 추가 정보를 제공해야 합니다. 사용 가능한 리소스 목록은 [여기](https://api.endpoints.huggingface.cloud/#/v2%3A%3Aprovider/list_vendors)에서 확인할 수 있습니다. 또한 [웹 인터페이스](https://ui.endpoints.huggingface.co/new)를 사용하여 편리하게 수동으로 추론 엔드포인트를 생성할 수 있습니다. 고급 설정 및 사용법에 대한 자세한 내용은 [이 가이드](https://huggingface.co/docs/inference-endpoints/guides/advanced)를 참조하세요. [`create_inference_endpoint`]에서 반환된 값은 [`InferenceEndpoint`] 개체입니다: ```py >>> endpoint InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) ``` 이것은 엔드포인트에 대한 정보를 저장하는 데이터클래스입니다. `name`, `repository`, `status`, `task`, `created_at`, `updated_at` 등과 같은 중요한 속성에 접근할 수 있습니다. 필요한 경우 `endpoint.raw`를 통해 서버로부터의 원시 응답에도 접근할 수 있습니다. 추론 엔드포인트가 생성되면 [개인 대시보드](https://ui.endpoints.huggingface.co/)에서 확인할 수 있습니다. ![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/huggingface_hub/inference_endpoints_created.png) #### 사용자 정의 이미지 사용[[using-a-custom-image]] 기본적으로 추론 엔드포인트는 Hugging Face에서 제공하는 도커 이미지로 구축됩니다. 그러나 `custom_image` 매개변수를 사용하여 모든 도커 이미지를 지정할 수 있습니다. 일반적인 사용 사례는 [text-generation-inference](https://github.com/huggingface/text-generation-inference) 프레임워크를 사용하여 LLM을 실행하는 것입니다. 다음과 같이 수행할 수 있습니다: ```python # TGI에서 Zephyr-7b-beta를 실행하는 추론 엔드포인트 시작하기 >>> from huggingface_hub import create_inference_endpoint >>> endpoint = create_inference_endpoint( ... "aws-zephyr-7b-beta-0486", ... repository="HuggingFaceH4/zephyr-7b-beta", ... framework="pytorch", ... task="text-generation", ... accelerator="gpu", ... vendor="aws", ... region="us-east-1", ... type="protected", ... instance_size="x1", ... instance_type="nvidia-a10g", ... custom_image={ ... "health_route": "/health", ... "env": { ... "MAX_BATCH_PREFILL_TOKENS": "2048", ... "MAX_INPUT_LENGTH": "1024", ... "MAX_TOTAL_TOKENS": "1512", ... "MODEL_ID": "/repository" ... }, ... "url": "ghcr.io/huggingface/text-generation-inference:1.1.0", ... }, ... ) ``` `custom_image`에 전달할 값은 도커 컨테이너의 URL과 이를 실행하기 위한 구성이 포함된 딕셔너리입니다. 자세한 내용은 [Swagger 문서](https://api.endpoints.huggingface.cloud/#/v2%3A%3Aendpoint/create_endpoint)를 참조하세요. ### 기존 추론 엔드포인트 가져오기 또는 리스트 조회[[get-or-list-existing-inference-endpoints]] 경우에 따라 이전에 생성한 추론 엔드포인트를 관리해야 할 수 있습니다. 이름을 알고 있는 경우 [`get_inference_endpoint`]를 사용하여 [`InferenceEndpoint`] 개체를 가져올 수 있습니다. 또는 [`list_inference_endpoints`]를 사용하여 모든 추론 엔드포인트 리스트를 검색할 수 있습니다. 두 메소드 모두 선택적 `namespace` 매개변수를 허용합니다. 속해 있는 조직의 `namespace`를 설정할 수 있습니다. 그렇지 않으면 기본적으로 사용자 이름이 사용됩니다. ```py >>> from huggingface_hub import get_inference_endpoint, list_inference_endpoints # 엔드포인트 개체 가져오기 >>> get_inference_endpoint("my-endpoint-name") InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) # 조직의 모든 추론 엔드포인트 나열 >>> list_inference_endpoints(namespace="huggingface") [InferenceEndpoint(name='aws-starchat-beta', namespace='huggingface', repository='HuggingFaceH4/starchat-beta', status='paused', url=None), ...] # 사용자가 속해있는 모든 조직의 엔드포인트 나열 >>> list_inference_endpoints(namespace="*") [InferenceEndpoint(name='aws-starchat-beta', namespace='huggingface', repository='HuggingFaceH4/starchat-beta', status='paused', url=None), ...] ``` ## 배포 상태 확인[[check-deployment-status]] 이 가이드의 나머지 부분에서는 `endpoint`라는 이름의 [`InferenceEndpoint`] 객체를 가지고 있다고 가정합니다. 엔드포인트에 `status` 속성이 [`InferenceEndpointStatus`] 유형이라는 것을 알 수 있었습니다. 추론 엔드포인트가 배포되고 접근 가능하면 상태가 `"running"`이 되고 `url` 속성이 설정됩니다: ```py >>> endpoint InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='running', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud') ``` `추론 엔드포인트가 "running"` 상태에 도달하기 전에 일반적으로 `"initializing"` 또는 `"pending"` 단계를 거칩니다. [`~InferenceEndpoint.fetch`]를 실행하여 엔드포인트의 새로운 상태를 가져올 수 있습니다. [`InferenceEndpoint`]의 다른 메소드와 마찬가지로 이 메소드는 서버에 요청을 하며, `endpoint`의 내부 속성이 변경됩니다: ```py >>> endpoint.fetch() InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) ``` 추론 엔드포인트가 실행될 때까지 기다리면서 상태를 가져오는 대신 [`~InferenceEndpoint.wait`]를 직접 호출할 수 있습니다. 이 헬퍼는 `timeout`과 `fetch_every` 매개변수를 입력으로 받아 (초 단위) 추론 엔드포인트가 배포될 때까지 스레드를 차단합니다. 기본값은 각각 `None`(제한 시간 없음)과 `5`초입니다. ```py # 엔드포인트 보류 >>> endpoint InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) # 10초 대기 => InferenceEndpointTimeoutError 발생 >>> endpoint.wait(timeout=10) raise InferenceEndpointTimeoutError("Timeout while waiting for Inference Endpoint to be deployed.") huggingface_hub._inference_endpoints.InferenceEndpointTimeoutError: Timeout while waiting for Inference Endpoint to be deployed. # 추가 대기 >>> endpoint.wait() InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='running', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud') ``` `timeout`이 설정되어 있고 추론 엔드포인트를 불러오는 데 너무 오래 걸리면, [`InferenceEndpointTimeoutError`] 제한 시간 초과 오류가 발생합니다. ## 추론 실행[[run-inference]] 추론 엔드포인트가 실행되면, 마침내 추론을 실행할 수 있습니다! [`InferenceEndpoint`]에는 각각 [`InferenceClient`]와 [`AsyncInferenceClient`]를 반환하는 `client`와 `async_client` 속성이 있습니다. ```py # 텍스트 생성 작업 실행: >>> endpoint.client.text_generation("I am") ' not a fan of the idea of a "big-budget" movie. I think it\'s a' # 비동기 컨텍스트에서도 마찬가지로 실행: >>> await endpoint.async_client.text_generation("I am") ``` 추론 엔드포인트가 실행 중이 아니면 [`InferenceEndpointError`] 오류가 발생합니다: ```py >>> endpoint.client huggingface_hub._inference_endpoints.InferenceEndpointError: Cannot create a client for this Inference Endpoint as it is not yet deployed. Please wait for the Inference Endpoint to be deployed using `endpoint.wait()` and try again. ``` [`InferenceClient`]를 사용하는 방법에 대한 자세한 내용은 [추론 가이드](../guides/inference)를 참조하세요. ## 라이프사이클 관리[[manage-lifecycle]] 이제 추론 엔드포인트를 생성하고 추론을 실행하는 방법을 살펴보았으니, 라이프사이클을 관리하는 방법을 살펴봅시다. > [!TIP] > 이 섹션에서는 [`~InferenceEndpoint.pause`], [`~InferenceEndpoint.resume`], [`~InferenceEndpoint.scale_to_zero`], [`~InferenceEndpoint.update`] 및 [`~InferenceEndpoint.delete`] 등의 메소드를 살펴볼 것입니다. 모든 메소드는 편의를 위해 [`InferenceEndpoint`]에 추가된 별칭입니다. 원한다면 `HfApi`에 정의된 일반 메소드 [`pause_inference_endpoint`], [`resume_inference_endpoint`], [`scale_to_zero_inference_endpoint`], [`update_inference_endpoint`] 및 [`delete_inference_endpoint`]를 사용할 수도 있습니다. ### 일시 중지 또는 0으로 확장[[pause-or-scale-to-zero]] 추론 엔드포인트를 사용하지 않을 때 비용을 절감하기 위해 [`~InferenceEndpoint.pause`]를 사용하여 일시 중지하거나 [`~InferenceEndpoint.scale_to_zero`]를 사용하여 0으로 스케일링할 수 있습니다. > [!TIP] > *일시 중지* 또는 *0으로 스케일링*된 추론 엔드포인트는 비용이 들지 않습니다. 이 두 가지의 차이점은 *일시 중지* 엔드포인트는 [`~InferenceEndpoint.resume`]를 사용하여 명시적으로 *재개*해야 한다는 것입니다. 반대로 *0으로 스케일링*된 엔드포인트는 추론 호출이 있으면 추가 콜드 스타트 지연과 함께 자동으로 시작됩니다. 추론 엔드포인트는 일정 기간 비활성화된 후 자동으로 0으로 스케일링되도록 구성할 수도 있습니다. ```py # 엔드포인트 일시중지 및 재시작 >>> endpoint.pause() InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='paused', url=None) >>> endpoint.resume() InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='pending', url=None) >>> endpoint.wait().client.text_generation(...) ... # 0으로 스케일링 >>> endpoint.scale_to_zero() InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2', status='scaledToZero', url='https://jpj7k2q4j805b727.us-east-1.aws.endpoints.huggingface.cloud') # 엔드포인트는 'running'은 아니지만 URL�을 가지고 있으며 첫 번째 호출 시 다시 시작됩니다. ``` ### 모델 또는 하드웨어 요구 사항 업데이트[[update-model-or-hardware-requirements]] 경우에 따라 새로운 엔드포인트를 생성하지 않고 추론 엔드포인트를 업데이트하고 싶을 수 있습니다. 호스팅된 모델이나 모델 실행에 필요한 하드웨어 요구 사항을 업데이트할 수 있습니다. 이렇게 하려면 [`~InferenceEndpoint.update`]를 사용합니다: ```py # 타겟 모델 변경 >>> endpoint.update(repository="gpt2-large") InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None) # 복제본 갯수 업데이트 >>> endpoint.update(min_replica=2, max_replica=6) InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None) # 더 큰 인스턴스로 업데이트 >>> endpoint.update(accelerator="cpu", instance_size="x4", instance_type="intel-icl") InferenceEndpoint(name='my-endpoint-name', namespace='Wauplin', repository='gpt2-large', status='pending', url=None) ``` ### 엔드포인트 삭제[[delete-the-endpoint]] 마지막으로 더 이상 추론 엔드포인트를 사용하지 않을 경우, [`~InferenceEndpoint.delete()`]를 호출하기만 하면 됩니다. > [!WARNING] > 이것은 돌이킬 수 없는 작업이며, 구성, 로그 및 사용 메트릭을 포함한 엔드포인트를 완전히 제거합니다. 삭제된 추론 엔드포인트는 복원할 수 없습니다. ## 엔드 투 엔드 예제[an-end-to-end-example] 추론 엔드포인트의 일반적인 사용 사례는 한 번에 여러 개의 작업을 처리하여 인프라 비용을 제한하는 것입니다. 이 가이드에서 본 것을 사용하여 이 프로세스를 자동화할 수 있습니다: ```py >>> import asyncio >>> from huggingface_hub import create_inference_endpoint # 엔드포인트 시작 + 초기화될 때까지 대기 >>> endpoint = create_inference_endpoint(name="batch-endpoint",...).wait() # 추론 실행 >>> client = endpoint.client >>> results = [client.text_generation(...) for job in jobs] # 비동기 추론 실행 >>> async_client = endpoint.async_client >>> results = asyncio.gather(*[async_client.text_generation(...) for job in jobs]) # 엔드포인트 중지 >>> endpoint.pause() ``` 또는 추론 엔드포인트가 이미 존재하고 일시 중지된 경우: ```py >>> import asyncio >>> from huggingface_hub import get_inference_endpoint # 엔드포인트 가져오기 + 초기화될 때까지 대기 >>> endpoint = get_inference_endpoint("batch-endpoint").resume().wait() # 추론 실행 >>> async_client = endpoint.async_client >>> results = asyncio.gather(*[async_client.text_generation(...) for job in jobs]) # 엔드포인트 중지 >>> endpoint.pause() ``` huggingface_hub-1.1.5/docs/source/ko/guides/integrations.md000066400000000000000000000622501510763414300240050ustar00rootroot00000000000000 # Hub와 어떤 머신 러닝 프레임워크든 통합[[integrate-any-ml-framework-with-the-hub]] Hugging Face Hub는 커뮤니티와 모델을 공유하는 것을 쉽게 만들어줍니다. 이는 오픈소스 생태계의 [수십 가지 라이브러리](https://huggingface.co/docs/hub/models-libraries)를 지원합니다. 저희는 항상 협업적인 머신 러닝을 발전시키기 위해 이 라이브러리를 확대하고자 노력하고 있습니다. `huggingface_hub` 라이브러리는 어떤 Python 스크립트든지 쉽게 파일을 업로드하고 가져올 수 있는 중요한 역할을 합니다. 라이브러리를 Hub와 통합하는 네 가지 주요 방법이 있습니다: 1. **Hub에 업로드하기**: 모델을 Hub에 업로드하는 메소드를 구현합니다. 이에는 모델 가중치뿐만 아니라 [모델 카드](https://huggingface.co/docs/huggingface_hub/how-to-model-cards) 및 모델 실행에 필요한 다른 관련 정보나 데이터(예: 훈련 로그)가 포함됩니다. 이 메소드는 일반적으로 `push_to_hub()`라고 합니다. 2. **Hub에서 다운로드하기**: Hub에서 모델을 가져오는 메소드를 구현합니다. 이 메소드는 모델 구성/가중치를 다운로드하고 모델을 가져와야 합니다. 이 메소드는 일반적으로 `from_pretrained` 또는 `load_from_hub()`라고 합니다. 3. **추론 API**: 라이브러리에서 지원하는 모델에 대해 무료로 추론을 실행할 수 있도록 당사 서버를 사용합니다. 4. **위젯**: Hub의 모델 랜딩 페이지에 위젯을 표시합니다. 이를 통해 사용자들은 브라우저에서 빠르게 모델을 시도할 수 있습니다. 이 가이드에서는 앞의 두 가지 주제에 중점을 둘 것입니다. 우리는 라이브러리를 통합하는 데 사용할 수 있는 두 가지 주요 방법을 소개하고 각각의 장단점을 설명할 것입니다. 두 가지 중 어떤 것을 선택할지에 대한 도움이 되도록 끝 부분에 내용이 요약되어 있습니다. 이는 단지 가이드라는 것을 명심하고 상황에 맞게 적응시킬 수 있는 가이드라는 점을 유념하십시오. 추론 및 위젯에 관심이 있는 경우 [이 가이드](https://huggingface.co/docs/hub/models-adding-libraries#set-up-the-inference-api)를 참조할 수 있습니다. 양쪽 모두에서 라이브러리를 Hub와 통합하고 [문서](https://huggingface.co/docs/hub/models-libraries)에 목록에 게시하고자 하는 경우에는 언제든지 연락하실 수 있습니다. ## 유연한 접근 방식: 도우미(helper)[[a-flexible-approach-helpers]] 라이브러리를 Hub에 통합하는 첫 번째 접근 방법은 실제로 `push_to_hub` 및 `from_pretrained` 메소드를 직접 구현하는 것입니다. 이를 통해 업로드/다운로드할 파일 및 입력을 처리하는 방법에 대한 완전한 유연성을 제공받을 수 있습니다. 이를 위해 [파일 업로드](./upload) 및 [파일 다운로드](./download) 가이드를 참조하여 자세히 알아볼 수 있습니다. 예를 들어 FastAI 통합이 구현된 방법을 보면 됩니다 ([`push_to_hub_fastai`] 및 [`from_pretrained_fastai`]를 참조). 라이브러리마다 구현 방식은 다를 수 있지만, 워크플로우는 일반적으로 비슷합니다. ### from_pretrained[[frompretrained]] 일반적으로 `from_pretrained` 메소드는 다음과 같은 형태를 가집니다: ```python def from_pretrained(model_id: str) -> MyModelClass: # Hub로부터 모델을 다운로드 cached_model = hf_hub_download( repo_id=repo_id, filename="model.pkl", library_name="fastai", library_version=get_fastai_version(), ) # 모델 가져오기 return load_model(cached_model) ``` ### push_to_hub[[pushtohub]] `push_to_hub` 메소드는 종종 리포지토리 생성, 모델 카드 생성 및 가중치 저장을 처리하기 위해 조금 더 복잡한 접근 방식이 필요합니다. 일반적으로 모든 이러한 파일을 임시 폴더에 저장한 다음 업로드하고 나중에 삭제하는 방식이 흔히 사용됩니다. ```python def push_to_hub(model: MyModelClass, repo_name: str) -> None: api = HfApi() # 해당 리포지토리가 아직 없다면 리포지토리를 생성하고 관련된 리포지토리 ID를 가져옵니다. repo_id = api.create_repo(repo_name, exist_ok=True) # 모든 파일을 임시 디렉토리에 저장하고 이를 단일 커밋으로 푸시합니다. with TemporaryDirectory() as tmpdir: tmpdir = Path(tmpdir) # 가중치 저장 save_model(model, tmpdir / "model.safetensors") # model card 생성 card = generate_model_card(model) (tmpdir / "README.md").write_text(card) # 로그 저장 # 설정 저장 # 평가 지표를 저장 # ... # Hub에 푸시 return api.upload_folder(repo_id=repo_id, folder_path=tmpdir) ``` 물론 이는 단순한 예시에 불과합니다. 더 복잡한 조작(원격 파일 삭제, 가중치를 실시간으로 업로드, 로컬로 가중치를 유지 등)에 관심이 있다면 [파일 업로드](./upload) 가이드를 참조해 주세요. ### 제한 사항[[limitations]] 이러한 방식은 유연성을 가지고 있지만, 유지보수 측면에서 일부 단점을 가지고 있습니다. Hugging Face 사용자들은 `huggingface_hub`와 함께 작업할 때 추가 기능에 익숙합니다. 예를 들어, Hub에서 파일을 로드할 때 다음과 같은 매개변수를 제공하는 것이 일반적입니다: - `token`: 개인 리포지토리에서 다운로드하기 위한 토큰 - `revision`: 특정 브랜치에서 다운로드하기 위한 리비전 - `cache_dir`: 특정 디렉터리에 파일을 캐시하기 위한 디렉터리 - `force_download`/`local_files_only`: 캐시를 재사용할 것인지 여부를 결정하는 매개변수 - `proxies`: HTTP 세션 구성 모델을 푸시할 때는 유사한 매개변수가 지원됩니다: - `commit_message`: 사용자 정의 커밋 메시지 - `private`: 개인 리포지토리를 만들어야 할 경우 - `create_pr`: `main`에 푸시하는 대신 PR을 만드는 경우 - `branch`: `main` 브랜치 대신 브랜치에 푸시하는 경우 - `allow_patterns/ignore_patterns`: 업로드할 파일을 필터링하는 매개변수 - `token` - ... 이러한 매개변수는 위에서 본 구현에 추가하여 `huggingface_hub` 메소드로 전달할 수 있습니다. 그러나 매개변수가 변경되거나 새로운 기능이 추가되는 경우에는 패키지를 업데이트해야 합니다. 이러한 매개변수를 지원하는 것은 유지 관리할 문서가 더 많아진다는 것을 의미합니다. 이러한 제한 사항을 완화할 수 있는 방법을 보려면 다음 섹션인 **클래스 상속**으로 이동해 보겠습니다. ## 더욱 복잡한 접근법: 클래스 상속[[a-more-complex-approach-class-inheritance]] 위에서 보았듯이 Hub와 통합하기 위해 라이브러리에 포함해야 할 주요 메소드는 파일을 업로드 (`push_to_hub`) 와 파일 다운로드 (`from_pretrained`)입니다. 이러한 메소드를 직접 구현할 수 있지만, 이에는 몇 가지 주의할 점이 있습니다. 이를 해결하기 위해 `huggingface_hub`은 클래스 상속을 사용하는 도구를 제공합니다. 이 도구가 어떻게 작동하는지 살펴보겠습니다! 많은 경우에 라이브러리는 이미 Python 클래스를 사용하여 모델을 구현합니다. 이 클래스에는 모델의 속성 및 로드, 실행, 훈련 및 평가하는 메소드가 포함되어 있습니다. 접근 방식은 믹스인을 사용하여 이 클래스를 확장하여 업로드 및 다운로드 기능을 포함하는 것입니다. [믹스인(Mixin)](https://stackoverflow.com/a/547714)은 기존 클래스에 여러 상속을 통해 특정 기능을 확장하기 위해 설계된 클래스입니다. `huggingface_hub`은 자체 믹스인인 [`ModelHubMixin`]을 제공합니다. 여기서 핵심은 동작과 이를 사용자 정의하는 방법을 이해하는 것입니다. [`ModelHubMixin`] 클래스는 세 개의 *공개* 메소드(`push_to_hub`, `save_pretrained`, `from_pretrained`)를 구현합니다. 이 메소드들은 사용자가 라이브러리를 사용하여 모델을 로드/저장할 때 호출하는 메소드입니다. 또한 [`ModelHubMixin`]은 두 개의 *비공개* 메소드(`_save_pretrained` 및 `_from_pretrained`)를 정의합니다. 라이브러리를 통합하려면 이 메소드들을 구현해야 합니다. : 1. 모델 클래스를 [`ModelHubMixin`]에서 상속합니다. 2. 비공개 메소드를 구현합니다: - [`~ModelHubMixin._save_pretrained`]: 디렉터리 경로를 입력으로 받아 모델을 해당 디렉터리에 저장하는 메소드입니다. 이 메소드에는 모델 카드, 모델 가중치, 구성 파일, 훈련 로그 및 그림 등 해당 모델에 대한 모든 관련 정보를 저장하기 위한 로직을 작성해야 합니다. [모델 카드](https://huggingface.co/docs/hub/model-cards)는 모델을 설명하는 데 특히 중요합니다. 더 자세한 내용은 [구현 가이드](./model-cards)를 확인하세요. - [`~ModelHubMixin._from_pretrained`]: `model_id`를 입력으로 받아 인스턴스화된 모델을 반환하는 **클래스 메소드**입니다. 이 메소드는 관련 파일을 다운로드하고 가져와야 합니다. 3. 완료했습니다! [`ModelHubMixin`]의 장점은 파일의 직렬화/로드에만 신경을 쓰면 되기 때문에 즉시 사용할 수 있다는 것입니다. 리포지토리 생성, 커밋, PR 또는 리비전과 같은 사항에 대해 걱정할 필요가 없습니다. [`ModelHubMixin`]은 또한 공개 메소드가 문서화되고 타입에 주석이 달려있는지를 확인하며, Hub 모델의 다운로드 수를 볼 수 있도록 합니다. 이 모든 것은 [`ModelHubMixin`]에 의해 처리되며 사용자에게 제공됩니다. ### 자세한 예시: PyTorch[[a-concrete-example-pytorch]] 위에서 언급한 내용의 좋은 예시는 Pytorch 프레임워크를 통합한 [`PyTorchModelHubMixin`]입니다. 바로 사용 가능할 수 있는 메소드입니다. #### 어떻게 사용하나요?[[how-to-use-it]] 다음은 Hub에서 PyTorch 모델을 로드/저장하는 방법입니다: ```python >>> import torch >>> import torch.nn as nn >>> from huggingface_hub import PyTorchModelHubMixin # PyTorch 모델을 여러분이 흔히 사용하는 방식과 완전히 동일하게 정의하세요. >>> class MyModel( ... nn.Module, ... PyTorchModelHubMixin, # 다중 상속 ... library_name="keras-nlp", ... tags=["keras"], ... repo_url="https://github.com/keras-team/keras-nlp", ... docs_url="https://keras.io/keras_nlp/", ... # ^ 모델 카드를 생성하는 데 선택적인 메타데이터입니다. ... ): ... def __init__(self, hidden_size: int = 512, vocab_size: int = 30000, output_size: int = 4): ... super().__init__() ... self.param = nn.Parameter(torch.rand(hidden_size, vocab_size)) ... self.linear = nn.Linear(output_size, vocab_size) ... def forward(self, x): ... return self.linear(x + self.param) # 1. 모델 생성 >>> model = MyModel(hidden_size=128) # 설정은 입력 및 기본값을 기반으로 자동으로 생성됩니다. >>> model.param.shape[0] 128 # 2. (선택사항) 모델을 로컬 디렉터리에 저장합니다. >>> model.save_pretrained("path/to/my-awesome-model") # 3. 모델 가중치를 Hub에 푸시합니다. >>> model.push_to_hub("my-awesome-model") # 4. Hub로부터 모델을 초기화합니다. => 이때 설정은 보존됩니다. >>> model = MyModel.from_pretrained("username/my-awesome-model") >>> model.param.shape[0] 128 # 모델 카드가 올바르게 작성되었습니다. >>> from huggingface_hub import ModelCard >>> card = ModelCard.load("username/my-awesome-model") >>> card.data.tags ["keras", "pytorch_model_hub_mixin", "model_hub_mixin"] >>> card.data.library_name "keras-nlp" ``` #### 구현[[implementation]] 실제 구현은 매우 간단합니다. 전체 구현은 [여기](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/hub_mixin.py)에서 찾을 수 있습니다. 1. 클래스를 `ModelHubMixin`으로부터 상속하세요: ```python from huggingface_hub import ModelHubMixin class PyTorchModelHubMixin(ModelHubMixin): (...) ``` 2. `_save_pretrained` 메소드를 구현하세요: ```py from huggingface_hub import ModelHubMixin class PyTorchModelHubMixin(ModelHubMixin): (...) def _save_pretrained(self, save_directory: Path) -> None: """PyTorch 모델의 가중치를 로컬 디렉터리에 저장합니다.""" save_model_as_safetensor(self.module, str(save_directory / SAFETENSORS_SINGLE_FILE)) ``` 3. `_from_pretrained` 메소드를 구현하세요: ```python class PyTorchModelHubMixin(ModelHubMixin): (...) @classmethod # 반드시 클래스 메소드여야 합니다! def _from_pretrained( cls, *, model_id: str, revision: str, cache_dir: str, force_download: bool, proxies: Optional[dict], local_files_only: bool, token: Union[str, bool, None], map_location: str = "cpu", # 추가 인자 strict: bool = False, # 추가 인자 **model_kwargs, ): """PyTorch의 사전 학습된 가중치와 모델을 반환합니다.""" model = cls(**model_kwargs) if os.path.isdir(model_id): print("Loading weights from local directory") model_file = os.path.join(model_id, SAFETENSORS_SINGLE_FILE) return cls._load_as_safetensor(model, model_file, map_location, strict) model_file = hf_hub_download( repo_id=model_id, filename=SAFETENSORS_SINGLE_FILE, revision=revision, cache_dir=cache_dir, force_download=force_download, token=token, local_files_only=local_files_only, ) return cls._load_as_safetensor(model, model_file, map_location, strict) ``` 이게 전부입니다! 이제 라이브러리를 통해 Hub로부터 파일을 업로드하고 다운로드할 수 있습니다. ### 고급 사용법[[advanced-usage]] 위의 섹션에서는 [`ModelHubMixin`]이 어떻게 작동하는지 간단히 살펴보았습니다. 이번 섹션에서는 Hugging Face Hub와 라이브러리 통합을 개선하기 위한 더 고급 기능 중 일부를 살펴보겠습니다. #### 모델 카드[[model-card]] [`ModelHubMixin`]은 모델 카드를 자동으로 생성합니다. 모델 카드는 모델과 함께 제공되는 중요한 정보를 제공하는 파일입니다. 모델 카드는 추가 메타데이터가 포함된 간단한 Markdown 파일입니다. 모델 카드는 발견 가능성, 재현성 및 공유를 위해 중요합니다! 더 자세한 내용은 [모델 카드 가이드](https://huggingface.co/docs/hub/model-cards)를 확인하세요. 모델 카드를 반자동으로 생성하는 것은 라이브러리로 푸시된 모든 모델이 `library_name`, `tags`, `license`, `pipeline_tag` 등과 같은 공통 메타데이터를 공유하도록 하는 좋은 방법입니다. 이를 통해 모든 모델이 Hub에서 쉽게 검색 가능하게 되고, Hub에 접속한 사용자에게 일부 리소스 링크를 제공합니다. [`ModelHubMixin`]을 상속할 때 메타데이터를 직접 정의할 수 있습니다: ```py class UniDepthV1( nn.Module, PyTorchModelHubMixin, library_name="unidepth", repo_url="https://github.com/lpiccinelli-eth/UniDepth", docs_url=..., pipeline_tag="depth-estimation", license="cc-by-nc-4.0", tags=["monocular-metric-depth-estimation", "arxiv:1234.56789"] ): ... ``` 기본적으로는 제공된 정보로 일반적인 모델 카드가 생성됩니다(예: [pyp1/VoiceCraft_giga830M](https://huggingface.co/pyp1/VoiceCraft_giga830M)). 그러나 사용자 정의 모델 카드 템플릿을 정의할 수도 있습니다! 이 예에서는 `VoiceCraft` 클래스로 푸시된 모든 모델에 자동으로 인용 부분과 라이선스 세부 정보가 포함됩니다. 모델 카드 템플릿을 정의하는 방법에 대한 자세한 내용은 [모델 카드 가이드](./model-cards)를 참조하세요. ```py MODEL_CARD_TEMPLATE = """ --- # For reference on model card metadata, see the spec: https://github.com/huggingface/hub-docs/blob/main/modelcard.md?plain=1 # Doc / guide: https://huggingface.co/docs/hub/model-cards {{ card_data }} --- This is a VoiceCraft model. For more details, please check out the official Github repo: https://github.com/jasonppy/VoiceCraft. This model is shared under a Attribution-NonCommercial-ShareAlike 4.0 International license. ## Citation @article{peng2024voicecraft, author = {Peng, Puyuan and Huang, Po-Yao and Li, Daniel and Mohamed, Abdelrahman and Harwath, David}, title = {VoiceCraft: Zero-Shot Speech Editing and Text-to-Speech in the Wild}, journal = {arXiv}, year = {2024}, } """ class VoiceCraft( nn.Module, PyTorchModelHubMixin, library_name="voicecraft", model_card_template=MODEL_CARD_TEMPLATE, ... ): ... ``` 마지막으로, 모델 카드 생성 프로세스를 동적 값으로 확장하려면 [`~ModelHubMixin.generate_model_card`] 메소드를 재정의할 수 있습니다: ```py from huggingface_hub import ModelCard, PyTorchModelHubMixin class UniDepthV1(nn.Module, PyTorchModelHubMixin, ...): (...) def generate_model_card(self, *args, **kwargs) -> ModelCard: card = super().generate_model_card(*args, **kwargs) card.data.metrics = ... # 메타데이터에 메트릭 추가 card.text += ... # 모델 카드에 섹션 추가 return card ``` #### 구성[[config]] [`ModelHubMixin`]은 모델 구성을 처리합니다. 모델을 인스턴스화할 때 입력 값들을 자동으로 확인하고 이를 `config.json` 파일에 직렬화합니다. 이렇게 함으로써 두 가지 이점이 제공됩니다: 1. 사용자는 정확히 동일한 매개변수로 모델을 다시 가져올 수 있습니다. 2. `config.json` 파일이 자동으로 생성되면 Hub에서 분석이 가능해집니다(즉, "다운로드" 횟수가 기록됩니다). 하지만 이것이 실제로 어떻게 작동하는 걸까요? 사용자 관점에서 프로세스가 가능한 매끄럽도록 하기 위해 여러 규칙이 존재합니다: - 만약 `__init__` 메소드가 `config` 입력을 기대한다면, 이는 자동으로 `config.json`으로 저장됩니다. - 만약 `config` 입력 매개변수에 데이터 클래스 유형(예: `config: Optional[MyConfigClass] = None`)의 어노테이션이 있다면, config 값은 올바르게 역직렬화됩니다. - 초기화할 때 전달된 모든 값들도 구성 파일에 저장됩니다. 이는 `config` 입력을 기대하지 않더라도 이점을 얻을 수 있다는 것을 의미합니다. 예시: ```py class MyModel(ModelHubMixin): def __init__(value: str, size: int = 3): self.value = value self.size = size (...) # _save_pretrained / _from_pretrained 구현 model = MyModel(value="my_value") model.save_pretrained(...) # config.json 파일에는 전달된 값과 기본 값이 모두 포함됩니다. {"value": "my_value", "size": 3} ``` 그러나 값이 JSON으로 직렬화될 수 없는 경우, 기본적으로 구성 파일을 저장할 때 해당 값은 무시됩니다. 그러나 경우에 따라 라이브러리가 이미 직렬화할 수 없는 사용자 정의 객체를 예상하고 있고 해당 유형을 업데이트하고 싶지 않은 경우가 있습니다. 그렇다면 [`ModelHubMixin`]을 상속할 때 어떤 유형에 대한 사용자 지정 인코더/디코더를 전달할 수 있습니다. 이는 조금 더 많은 작업이 필요하지만 내부 로직을 변경하지 않고도 라이브러리를 Hub에 통합할 수 있도록 보장합니다. 여기서 `argparse.Namespace` 구성을 입력으로 받는 클래스의 구체적인 예가 있습니다: ```py class VoiceCraft(nn.Module): def __init__(self, args): self.pattern = self.args.pattern self.hidden_size = self.args.hidden_size ... ``` 한 가지 해결책은 `__init__` 시그니처를 `def __init__(self, pattern: str, hidden_size: int)`로 업데이트하고 클래스를 인스턴스화하는 모든 스니펫을 업데이트하는 것입니다. 이 방법은 유효한 방법이지만, 라이브러리를 사용하는 하위 응용 프로그램을 망가뜨릴 수 있습니다. 다른 해결책은 `argparse.Namespace`를 사전으로 변환하는 간단한 인코더/디코더를 제공하는 것입니다. ```py from argparse import Namespace class VoiceCraft( nn.Module, PyTorchModelHubMixin, # 믹스인을 상속합니다. coders={ Namespace: ( lambda x: vars(x), # Encoder: `Namespace`를 유효한 JSON 형태로 변환하는 방법은 무엇인가요? lambda data: Namespace(**data), # Decoder: 딕셔너리에서 Namespace를 재구성하는 방법은 무엇인가요? ) } ): def __init__(self, args: Namespace): # `args`에 주석을 답니다. self.pattern = self.args.pattern self.hidden_size = self.args.hidden_size ... ``` 위의 코드 스니펫에서는 클래스의 내부 로직과 `__init__` 시그니처가 변경되지 않았습니다. 이는 기존의 모든 코드 스니펫이 여전히 작동한다는 것을 의미합니다. 이를 달성하기 위해 다음 과정을 수행하면 됩니다: 1. 믹스인(`PytorchModelHubMixin`)으로부터 상속합니다. 2. 상속 시 `coders` 매개변수를 전달합니다. 이는 키가 처리하려는 사용자 지정 유형이고, 값은 튜플 `(인코더, 디코더)`입니다. - 인코더는 지정된 유형의 객체를 입력으로 받아서 jsonable 값으로 반환합니다. 이는 `save_pretrained`로 모델을 저장할 때 사용됩니다. - 디코더는 원시 데이터(일반적으로 딕셔너리 타입)를 입력으로 받아서 초기 객체를 재구성합니다. 이는 `from_pretrained`로 모델을 로드할 때 사용됩니다. - `__init__` 시그니처에 유형 주석을 추가합니다. 이는 믹스인에게 클래스가 기대하는 유형과, 따라서 어떤 디코더를 사용해야 하는지를 알려주는 데 중요합니다. 위의 예제는 간단한 예시이기 때문에 인코더/디코더 함수는 견고하지 않습니다. 구체적인 구현을 위해서는 코너 케이스를 적절하게 처리해야 할 것입니다. ## 빠른 비교[[quick-comparison]] 두 가지 접근 방법에 대한 장단점을 간단히 정리해보겠습니다. 아래 표는 단순히 예시일 뿐입니다. 각자 다른 프레임워크에는 고려해야 할 특정 사항이 있을 수 있습니다. 이 가이드는 통합을 다루는 아이디어와 지침을 제공하기 위한 것입니다. 언제든지 궁금한 점이 있으면 문의해 주세요! | 통합 | helpers 사용 시 | [`ModelHubMixin`] 사용 시 | | :------------------: | :-------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------: | | 사용자 경험 | `model = load_from_hub(...)`
`push_to_hub(model, ...)` | `model = MyModel.from_pretrained(...)`
`model.push_to_hub(...)` | | 유연성 | 매우 유연합니다.
구현을 완전히 제어합니다. | 유연성이 떨어집니다.
프레임워크에는 모델 클래스가 있어야 합니다. | | 유지 관리 | 구성 및 새로운 기능에 대한 지원을 추가하기 위한 유지 관리가 더 필요합니다. 사용자가 보고한 문제를 해결해야할 수도 있습니다. | Hub와의 대부분의 상호 작용이 `huggingface_hub`에서 구현되므로 유지 관리가 줄어듭니다. | | 문서화 / 타입 주석 | 수동으로 작성해야 합니다. | `huggingface_hub`에서 부분적으로 처리됩니다. | | 다운로드 횟수 표시기 | 수동으로 처리해야 합니다. | 클래스에 `config` 속성이 있다면 기본적으로 활성화됩니다. | | 모델 카드 | 수동으로 처리해야 합니다. | library_name, tags 등을 활용하여 기본적으로 생성됩니다. | huggingface_hub-1.1.5/docs/source/ko/guides/manage-cache.md000066400000000000000000000534301510763414300235700ustar00rootroot00000000000000 # `huggingface_hub` 캐시 시스템 관리하기[[manage-huggingfacehub-cache-system]] ## 캐싱 이해하기[[understand-caching]] Hugging Face Hub 캐시 시스템은 Hub에 의존하는 라이브러리 간에 공유되는 중앙 캐시로 설계되었습니다. v0.8.0에서 수정한 파일 간에 다시 다운로드하는 것을 방지하도록 업데이트되었습니다. 캐시 시스템은 다음과 같이 설계되었습니다: ``` ├─ ├─ ├─ ``` ``는 보통 사용자의 홈 디렉토리입니다. 그러나 모든 메소드에서 `cache_dir` 인수를 사용하거나 `HF_HOME` 또는 `HF_HUB_CACHE` 환경 변수를 지정하여 사용자 정의할 수 있습니다. 모델, 데이터셋, 스페이스는 공통된 루트를 공유합니다. 각 리포지토리는 리포지토리 유형과 네임스페이스(조직 또는 사용자 이름이 있을 경우), 리포지토리 이름을 포함합니다: ``` ├─ models--julien-c--EsperBERTo-small ├─ models--lysandrejik--arxiv-nlp ├─ models--bert-base-cased ├─ datasets--glue ├─ datasets--huggingface--DataMeasurementsFiles ├─ spaces--dalle-mini--dalle-mini ``` Hub로부터 모든 파일이 이 폴더들 안에 다운로드됩니다. 캐싱은 파일이 이미 존재하고 업데이트되지 않은 경우, 파일을 두 번 다운로드하지 않도록 해줍니다. 하지만 파일이 업데이트되었고 최신 파일을 요청하면, 최신 파일을 다운로드합니다 (이전 파일은 그대로 유지되어 필요할 때 다시 사용할 수 있습니다). 이를 위해 모든 폴더는 동일한 구조를 가집니다: ``` ├─ datasets--glue │ ├─ refs │ ├─ blobs │ ├─ snapshots ... ``` 각 폴더는 다음과 같은 내용을 포함하도록 구성되었습니다: ### Refs[[refs]] `refs` 폴더에는 주어진 참조의 최신 수정 버전을 나타내는 파일이 포함되어 있습니다. 예를 들어, 이전에 리포지토리의 `main` 브랜치에서 파일을 가져온 경우, `refs` 폴더에는 `main`이라는 이름의 파일이 포함되며, 이 파일 자체에는 현재 헤드의 커밋 식별자가 들어 있습니다. 만약 `main`의 최신 커밋 식별자가 `aaaaaa`라면, 그 파일에는 `aaaaaa`가 들어 있습니다. 같은 브랜치가 새로운 커밋으로 업데이트되어 `bbbbbb`라는 식별자를 갖게 되면, 해당 참조에서 파일을 다시 다운로드할 때 `refs/main` 파일은 `bbbbbb`로 업데이트됩니다. ### Blobs[[blobs]] `blobs` 폴더에는 실제로 다운로드된 파일이 포함되어 있습니다. 각 파일의 이름은 해당 파일의 해시값입니다. ### Snapshots[[snapshots]] `snapshots` 폴더에는 위에서 언급한 blobs에 대한 심볼릭 링크가 포함되어 있습니다. 이 폴더는 여러 개의 하위 폴더로 구성되어 있으며, 각 폴더는 알려진 수정 버전을 나타냅니다. 위 설명에서, 처음에 `aaaaaa` 버전에서 파일을 가져왔고, 그 후에 `bbbbbb` 버전에서 파일을 가져왔습니다. 이 상황에서 `snapshots` 폴더에는 `aaaaaa`와 `bbbbbb`라는 두 개의 폴더가 있습니다. 이 폴더들 각각에는 다운로드한 파일의 이름을 가진 심볼릭 링크가 있습니다. 예를 들어, `aaaaaa` 버전에서 `README.md` 파일을 다운로드했다면, 다음과 같은 경로가 생깁니다: ``` //snapshots/aaaaaa/README.md ``` 그 `README.md` 파일은 실제로 해당 파일의 해시를 가진 blob에 대한 심볼릭 링크입니다. 이와 같은 구조를 생성함으로써 파일 공유 메커니즘이 열리게 됩니다. 동일한 파일을 `bbbbbb` 버전에서 가져온 경우, 동일한 해시를 가지게 되어 파일을 다시 다운로드할 필요가 없습니다. ### .no_exist (advanced)[[noexist-advanced]] `blobs`, `refs`, `snapshots` 폴더 외에도 캐시에서 `.no_exist` 폴더를 찾을 수 있습니다. 이 폴더는 한 번 다운로드하려고 시도했지만 Hub에 존재하지 않는 파일을 기록합니다. 이 폴더의 구조는 `snapshots` 폴더와 동일하며, 알려진 각 수정 버전에 대해 하나의 하위 폴더를 갖습니다: ``` //.no_exist/aaaaaa/config_that_does_not_exist.json ``` `snapshots` 폴더와 달리, 파일은 단순히 빈 파일입니다 (심볼릭 링크가 아님). 이 예에서 `"config_that_does_not_exist.json"` 파일은 `"aaaaaa"` 버전에 대해 Hub에 존재하지 않습니다. 빈 파일만 저장하므로, 이 폴더는 디스크 사용량을 크게 차지하지 않기에 무시할 수 있습니다. 그렇다면 이제 여러분은 왜 이 정보가 관련이 있는지 궁금해 할지도 모릅니다. 몇몇 경우에서는 프레임워크가 모델에 대한 옵션 파일들을 불러오려고 시도합니다. 존재하지 않는 옵션 파일들을 저장하면 가능한 옵션 파일당 1개의 HTTP 호출을 절약할 수 있어 모델을 더 빠르게 불러올 수 있습니다. 이는 예를 들어 각 토크나이저가 추가 파일을 지원하는 `transformers`에서 발생합니다. 처음으로 토크나이저를 로드할 때, 다음 초기화를 위해 로딩 시간을 더 빠르게 하기 위해 옵션 파일이 존재하는지 여부를 캐시합니다. HTTP 요청을 만들지 않고 로컬로 캐시된 파일이 있는지 테스트하려면, [`try_to_load_from_cache`] 헬퍼를 사용할 수 있습니다. 이것은 파일이 존재하고 캐시된 경우에는 파일 경로를, 존재하지 않음이 캐시된 경우에는 `_CACHED_NO_EXIST` 객체를, 알 수 없는 경우에는 `None`을 반환합니다. ```python from huggingface_hub import try_to_load_from_cache, _CACHED_NO_EXIST filepath = try_to_load_from_cache() if isinstance(filepath, str): # 파일이 존재하고 캐시됩니다 ... elif filepath is _CACHED_NO_EXIST: # 파일의 존재여부가 캐시됩니다 ... else: # 파일은 캐시되지 않습니다 ... ``` ### 캐시 구조 예시[[in-practice]] 실제로는 캐시는 다음과 같은 트리 구조를 가질 것입니다: ```text [ 96] . └── [ 160] models--julien-c--EsperBERTo-small ├── [ 160] blobs │ ├── [321M] 403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd │ ├── [ 398] 7cb18dc9bafbfcf74629a4b760af1b160957a83e │ └── [1.4K] d7edf6bd2a681fb0175f7735299831ee1b22b812 ├── [ 96] refs │ └── [ 40] main └── [ 128] snapshots ├── [ 128] 2439f60ef33a0d46d85da5001d52aeda5b00ce9f │ ├── [ 52] README.md -> ../../blobs/d7edf6bd2a681fb0175f7735299831ee1b22b812 │ └── [ 76] pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd └── [ 128] bbc77c8132af1cc5cf678da3f1ddf2de43606d48 ├── [ 52] README.md -> ../../blobs/7cb18dc9bafbfcf74629a4b760af1b160957a83e └── [ 76] pytorch_model.bin -> ../../blobs/403450e234d65943a7dcf7e05a771ce3c92faa84dd07db4ac20f592037a1e4bd ``` ### 제한사항[[limitations]] 효율적인 캐시 시스템을 갖기 위해 `huggingface-hub`은 심볼릭 링크를 사용합니다. 그러나 모든 기기에서 심볼릭 링크를 지원하지는 않습니다. 특히 Windows에서 이러한 한계가 있다는 것이 알려져 있습니다. 이런 경우에는 `huggingface_hub`이 `blobs/` 디렉터리를 사용하지 않고 대신 파일을 직접 `snapshots/` 디렉터리에 저장합니다. 이 해결책을 통해 사용자는 Hub에서 파일을 다운로드하고 캐시하는 방식을 정확히 동일하게 사용할 수 있습니다. 캐시를 검사하고 삭제하는 도구들도 지원됩니다. 그러나 캐시 시스템은 동일한 리포지토리의 여러 수정 버전을 다운로드하는 경우 같은 파일이 여러 번 다운로드될 수 있기 때문에 효율적이지 않을 수 있습니다. Windows 기기에서 심볼릭 링크 기반 캐시 시스템의 이점을 누리려면, [개발자 모드를 활성화](https://docs.microsoft.com/ko-kr/windows/apps/get-started/enable-your-device-for-development)하거나 Python을 관리자 권한으로 실행해야 합니다. 심볼릭 링크가 지원되지 않는 경우, 사용자에게 캐시 시스템의 낮은 버전을 사용 중임을 알리는 경고 메시지가 표시됩니다. 이 경고는 `HF_HUB_DISABLE_SYMLINKS_WARNING` 환경 변수를 true로 설정하여 비활성화할 수 있습니다. ## 캐싱 자산[[caching-assets]] Hub에서 파일을 캐시하는 것 외에도, 하위 라이브러리들은 종종 `huggingface_hub`에 직접 처리되지 않는 HF와 관련된 다른 파일을 캐시해야 할 때가 있습니다 (예: GitHub에서 다운로드한 파일, 전처리된 데이터, 로그 등). 이러한 파일, 즉 '자산(assets)'을 캐시하기 위해 [`cached_assets_path`]를 사용할 수 있습니다. 이 헬퍼는 요청한 라이브러리의 이름과 선택적으로 네임스페이스 및 하위 폴더 이름을 기반으로 HF 캐시의 경로를 통일된 방식으로 생성합니다. 목표는 모든 하위 라이브러리가 자산을 자체 방식대로(예: 구조에 대한 규칙 없음) 관리할 수 있도록 하는 것입니다. 그러나 올바른 자산 폴더 내에 있어야 합니다. 그러한 라이브러리는 `huggingface_hub`의 도구를 활용하여 캐시를 관리할 수 있으며, 특히 CLI 명령을 통해 자산의 일부를 스캔하고 삭제할 수 있습니다. ```py from huggingface_hub import cached_assets_path assets_path = cached_assets_path(library_name="datasets", namespace="SQuAD", subfolder="download") something_path = assets_path / "something.json" # 자산 폴더에서 원하는 대로 작업하세요! ``` > [!TIP] > [`cached_assets_path`]는 자산을 저장하는 권장 방법이지만 필수는 아닙니다. 이미 라이브러리가 자체 캐시를 사용하는 경우 해당 캐시를 자유롭게 사용하세요! ### 자산 캐시 구조 예시[[assets-in-practice]] 실제로는 자산 캐시는 다음과 같은 트리 구조를 가질 것입니다: ```text assets/ └── datasets/ │ ├── SQuAD/ │ │ ├── downloaded/ │ │ ├── extracted/ │ │ └── processed/ │ ├── Helsinki-NLP--tatoeba_mt/ │ ├── downloaded/ │ ├── extracted/ │ └── processed/ └── transformers/ ├── default/ │ ├── something/ ├── bert-base-cased/ │ ├── default/ │ └── training/ hub/ └── models--julien-c--EsperBERTo-small/ ├── blobs/ │ ├── (...) │ ├── (...) ├── refs/ │ └── (...) └── [ 128] snapshots/ ├── 2439f60ef33a0d46d85da5001d52aeda5b00ce9f/ │ ├── (...) └── bbc77c8132af1cc5cf678da3f1ddf2de43606d48/ └── (...) ``` ## 캐시 확인하기[[scan-your-cache]] 현재 캐시된 파일은 로컬 디렉토리에서 자동으로 삭제되지 않습니다. 브랜치의 새로운 수정 버전을 다운로드하면 이전 파일이 그대로 남아 향후 다시 사용할 수 있습니다. 따라서 디스크 공간을 많이 차지하는 리포지토리와 수정 버전을 파악하려면 캐시 디렉터리를 점검하는 것이 좋습니다. `huggingface_hub`은 이를 위해 CLI와 Python 유틸리티를 모두 제공합니다. ### 터미널에서 캐시 확인하기[[scan-cache-from-the-terminal]] HF 캐시 상태를 살펴보는 가장 간단한 방법은 `hf cache ls` 명령을 사용하는 것입니다. 기본적으로 캐시에 저장된 리포지토리를 한눈에 보여줍니다. ```text ➜ hf cache ls ID SIZE LAST_ACCESSED LAST_MODIFIED REFS ------------------------------------ ------- ------------- ------------- ------------------- dataset/glue 116.3K 4 days ago 4 days ago 2.4.0 main 1.17.0 dataset/google/fleurs 64.9M 1 week ago 1 week ago main refs/pr/1 model/Jean-Baptiste/camembert-ner 441.0M 2 weeks ago 16 hours ago main model/bert-base-cased 1.9G 1 week ago 2 years ago model/t5-base 10.1K 3 months ago 3 months ago main model/t5-small 970.7M 3 days ago 3 days ago main refs/pr/1 Found 6 repo(s) for a total of 12 revision(s) and 3.4G on disk. ``` `--revisions` 옵션을 추가하면 각 스냅샷별 상세 목록을 확인할 수 있습니다. `size>1GB`, `accessed>30d`와 같이 사람이 읽기 쉬운 값을 사용하는 필터도 함께 적용할 수 있습니다. ```text ➜ hf cache ls --revisions --filter "size>1GB" --filter "accessed>30d" ID REVISION SIZE LAST_MODIFIED REFS ------------------------------------ ------------------ ------- ------------- ------------------- model/bert-base-cased 6d1d7a1a2a6cf4c2 1.9G 2 years ago model/t5-small 1c610f6b3f5e7d8a 1.1G 3 months ago main Found 2 repo(s) for a total of 2 revision(s) and 3.0G on disk. ``` 머신 친화적인 출력이 필요하다면 `--format json` 또는 `--format csv`를 사용하고, 식별자만 받고 싶다면 `--quiet`를 사용할 수 있습니다. `--cache-dir` 옵션을 함께 지정하면 기본 위치가 아닌 다른 캐시 디렉터리를 살펴볼 수도 있습니다. ```text ➜ 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) Delete repo: ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct Delete repo: ~/.cache/huggingface/hub/models--hexgrad--Kokoro-82M Cache deletion done. Saved 5.31G. Deleted 2 repo(s) and 2 revision(s); freed 5.31G. ``` #### 쉘 도구로 필터링하기[[grep-example]] 출력이 표 형식이므로 기존의 `grep` 같은 도구와도 잘 어울립니다. 아래 예시는 `t5-small` 관련 스냅샷만 찾는 방법입니다. ```text ➜ eval "hf cache ls --revisions" | grep "t5-small" model/t5-small 1c610f6b3f5e7d8a 1.1G 3 months ago main model/t5-small 8f3ad1c90fed7a62 820.1M 2 weeks ago refs/pr/1 ``` ### 파이썬에서 캐시 스캔하기[[scan-cache-from-python]] 보다 고급 기능을 사용하려면, CLI 도구에서 호출되는 파이썬 유틸리티인 [`scan_cache_dir`]을 사용할 수 있습니다. 이를 사용하여 4가지 데이터 클래스를 중심으로 구조화된 자세한 보고서를 얻을 수 있습니다: - [`HFCacheInfo`]: [`scan_cache_dir`]에 의해 반환되는 완전한 보고서 - [`CachedRepoInfo`]: 캐시된 리포지토리에 관한 정보 - [`CachedRevisionInfo`]: 리포지토리 내의 캐시된 수정 버전(예: "snapshot")에 관한 정보 - [`CachedFileInfo`]: 스냅샷 내의 캐시된 파일에 관한 정보 다음은 간단한 사용 예시입니다. 자세한 내용은 참조 문서를 참고하세요. ```py >>> from huggingface_hub import scan_cache_dir >>> hf_cache_info = scan_cache_dir() HFCacheInfo( size_on_disk=3398085269, repos=frozenset({ CachedRepoInfo( repo_id='t5-small', repo_type='model', repo_path=PosixPath(...), size_on_disk=970726914, nb_files=11, last_accessed=1662971707.3567169, last_modified=1662971107.3567169, revisions=frozenset({ CachedRevisionInfo( commit_hash='d78aea13fa7ecd06c29e3e46195d6341255065d5', size_on_disk=970726339, snapshot_path=PosixPath(...), # 수정 버전 간에 blobs가 공유되기 때문에 `last_accessed`가 없습니다. last_modified=1662971107.3567169, files=frozenset({ CachedFileInfo( file_name='config.json', size_on_disk=1197 file_path=PosixPath(...), blob_path=PosixPath(...), blob_last_accessed=1662971707.3567169, blob_last_modified=1662971107.3567169, ), CachedFileInfo(...), ... }), ), CachedRevisionInfo(...), ... }), ), CachedRepoInfo(...), ... }), warnings=[ CorruptedCacheException("Snapshots dir doesn't exist in cached repo: ..."), CorruptedCacheException(...), ... ], ) ``` ## 캐시 정리하기[[clean-your-cache]] 캐시를 스캔하는 것은 흥미로울 수 있지만 실제로 해야 할 다음 작업은 일반적으로 드라이브의 일부 공간을 확보하기 위해 일부를 삭제하는 것입니다. 이는 `delete-cache` CLI 명령을 사용하여 가능합니다. 또한 캐시를 스캔할 때 반환되는 [`HFCacheInfo`] 객체에서 [`~HFCacheInfo.delete_revisions`] 헬퍼를 사용하여 프로그래밍 방식으로도 사용할 수 있습니다. ### 전략적으로 삭제하기[[delete-strategy]] 캐시를 삭제하려면 삭제할 수정 버전 목록을 전달해야 합니다. 이 도구는 이 목록을 기반으로 공간을 확보하기 위한 전략을 정의합니다. 이는 어떤 파일과 폴더가 삭제될지를 설명하는 [`DeleteCacheStrategy`] 객체를 반환합니다. [`DeleteCacheStrategy`]를 통해 사용 가능한 공간을 확보 할 수 있습니다. 삭제에 동의하면 삭제를 실행하여 삭제를 유효하게 만들어야 합니다. 불일치를 피하기 위해 전략 객체를 수동으로 편집할 수 없습니다. 수정 버전을 삭제하기 위한 전략은 다음과 같습니다: - 수정 버전 심볼릭 링크가 있는 `snapshot` 폴더가 삭제됩니다. - 삭제할 수정 버전에만 대상이 되는 blobs 파일도 삭제됩니다. - 수정 버전이 1개 이상의 `refs`에 연결되어 있는 경우, 참조가 삭제됩니다. - 리포지토리의 모든 수정 버전이 삭제되는 경우 전체 캐시된 리포지토리가 삭제됩니다. > [!TIP] > 수정 버전 해시는 모든 리포지토리를 통틀어 고유합니다. 따라서 `hf cache rm`은 리포지토리 식별자(`model/bert-base-uncased` 등)와 수정 버전 해시를 모두 인수로 받으며, 해시를 전달할 때는 리포지토리를 별도로 지정할 필요가 없습니다. > [!WARNING] > 캐시에서 수정 버전을 찾을 수 없는 경우 무시됩니다. 또한 삭제 중에 파일 또는 폴더를 찾을 수 없는 경우 경고가 기록되지만 오류가 발생하지 않습니다. [`DeleteCacheStrategy`] 객체에 포함된 다른 경로에 대해 삭제가 계속됩니다. ### 터미널에서 캐시 정리하기[[clean-cache-from-the-terminal]] 캐시에서 불필요한 데이터를 지우려면 `hf cache rm` 명령을 사용하세요. 리포지토리 식별자(예: `model/bert-base-uncased`)나 수정 버전 해시를 인수로 전달하면 됩니다. ```text ➜ hf cache rm model/bert-base-cased About to delete 1 repo(s) totalling 1.9G. - model/bert-base-cased (entire repo) Proceed with deletion? [y/N]: y Deleted 1 repo(s) and 1 revision(s); freed 1.9G. ``` 여러 리포지토리와 특정 수정 버전을 함께 지정할 수도 있습니다. `--dry-run` 옵션을 사용하면 실제 삭제 없이 결과를 미리 확인할 수 있고, 자동화된 스크립트에서는 `--yes`로 확인 단계를 건너뛸 수 있습니다. ```text ➜ 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` 옵션으로 경로를 지정하세요. 사용되지 않는(detached) 스냅샷만 한 번에 정리하려면 `hf cache prune`을 사용할 수 있습니다. 이 명령은 브랜치나 태그에서 참조하지 않는 수정 버전을 자동으로 선택합니다. ```text ➜ hf cache prune About to delete 3 unreferenced revision(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); freed 2.4G. ``` 두 명령 모두 `--dry-run`, `--yes`, `--cache-dir` 옵션을 지원하므로 시뮬레이션, 자동화, 대체 캐시 경로 지정을 자유롭게 조합할 수 있습니다. ### 파이썬에서 캐시 정리하기[[clean-cache-from-python]] 더 유연하게 사용하려면, 프로그래밍 방식으로 [`~HFCacheInfo.delete_revisions`] 메소드를 사용할 수도 있습니다. 간단한 예제를 살펴보겠습니다. 자세한 내용은 참조 문서를 확인하세요. ```py >>> from huggingface_hub import scan_cache_dir >>> delete_strategy = scan_cache_dir().delete_revisions( ... "81fd1d6e7847c99f5862c9fb81387956d99ec7aa" ... "e2983b237dccf3ab4937c97fa717319a9ca1a96d", ... "6c0e6080953db56375760c0471a8c5f2929baf11", ... ) >>> print("Will free " + delete_strategy.expected_freed_size_str) Will free 8.6G >>> delete_strategy.execute() Cache deletion done. Saved 8.6G. ``` huggingface_hub-1.1.5/docs/source/ko/guides/manage-spaces.md000066400000000000000000000345021510763414300240020ustar00rootroot00000000000000 # Space 관리하기[[manage-your-space]] 이 가이드에서는 `huggingface_hub`를 사용하여 Space 런타임([보안 정보](https://huggingface.co/docs/hub/spaces-overview#managing-secrets), [하드웨어](https://huggingface.co/docs/hub/spaces-gpus) 및 [저장소](https://huggingface.co/docs/hub/spaces-storage#persistent-storage))를 관리하는 방법을 살펴보겠습니다. ## 간단한 예제: 보안 정보 및 하드웨어 구성하기.[[a-simple-example-configure-secrets-and-hardware]] 다음은 Hub에서 Space를 생성하고 설정하는 통합 예시입니다. **1. Hub에 Space 생성하기.** ```py >>> from huggingface_hub import HfApi >>> repo_id = "Wauplin/my-cool-training-space" >>> api = HfApi() # Gradio SDK 예제 >>> api.create_repo(repo_id=repo_id, repo_type="space", space_sdk="gradio") ``` **1. (bis) Space 복제하기.** 기존의 Space에서부터 시작하는 대신 새로운 Space를 구축하고 싶을 때 유용할 수 있습니다. 또한 공개된 Space의 구성/설정을 제어하고 싶을 때도 유용합니다. 자세한 내용은 [`duplicate_space`]를 참조하세요. ```py >>> api.duplicate_space("multimodalart/dreambooth-training") ``` **2. 선호하는 솔루션을 사용하여 코드 업로드하기.** 다음은 로컬 폴더 `src/`를 사용자의 컴퓨터에서 Space로 업로드하는 예시입니다: ```py >>> api.upload_folder(repo_id=repo_id, repo_type="space", folder_path="src/") ``` 이 단계에서는 앱이 이미 무료로 Hub에서 실행 중이어야 합니다! 그러나 더 많은 보안 정보와 업그레이드된 하드웨어를 이용하여 추가적으로 구성할 수 있습니다. **3. 보안 정보와 변수 설정하기** Space에서 작동하려면 일부 보안 키, 토큰 또는 변수가 필요할 수 있습니다. 자세한 내용은 [문서](https://huggingface.co/docs/hub/spaces-overview#managing-secrets)를 참조하세요. Space에서 생성된 HF 토큰으로 이미지 데이터 세트를 Hub에 업로드하는 경우를 예로 들어봅시다. ```py >>> api.add_space_secret(repo_id=repo_id, key="HF_TOKEN", value="hf_api_***") >>> api.add_space_variable(repo_id=repo_id, key="MODEL_REPO_ID", value="user/repo") ``` 보안 정보와 변수는 삭제할 수도 있습니다: ```py >>> api.delete_space_secret(repo_id=repo_id, key="HF_TOKEN") >>> api.delete_space_variable(repo_id=repo_id, key="MODEL_REPO_ID") ``` > [!TIP] > Space 내에서 보안 정보는 환경 변수로 사용할 수 있습니다 (Streamlit를 사용하는 경우 Streamlit Secrets를 사용). API를 통해 가져올 필요가 없습니다! > [!WARNING] > Space 구성(보안 정보 또는 하드웨어)이 변경되면 앱이 다시 시작됩니다. **보너스: Space 생성 또는 복제 시 보안 정보와 변수 설정하기!** Space를 생성하거나 복제할 때 보안 정보와 변수를 설정할 수 있습니다: ```py >>> api.create_repo( ... repo_id=repo_id, ... repo_type="space", ... space_sdk="gradio", ... space_secrets=[{"key"="HF_TOKEN", "value"="hf_api_***"}, ...], ... space_variables=[{"key"="MODEL_REPO_ID", "value"="user/repo"}, ...], ... ) ``` ```py >>> api.duplicate_space( ... from_id=repo_id, ... secrets=[{"key"="HF_TOKEN", "value"="hf_api_***"}, ...], ... variables=[{"key"="MODEL_REPO_ID", "value"="user/repo"}, ...], ... ) ``` **4. 하드웨어 구성** 기본적으로 Space는 무료로 CPU 환경에서 실행됩니다. GPU에서 실행하기 위해 하드웨어를 업그레이드 할 수도 있습니다. 하드웨어를 업그레이드하려면 결제 카드 또는 커뮤니티 그랜트가 필요합니다. 자세한 내용은 [문서](https://huggingface.co/docs/hub/spaces-gpus)를 참조하세요. ```py # `SpaceHardware` enum 사용 >>> from huggingface_hub import SpaceHardware >>> api.request_space_hardware(repo_id=repo_id, hardware=SpaceHardware.T4_MEDIUM) # 또는 간단히 문자열 값 전달 >>> api.request_space_hardware(repo_id=repo_id, hardware="t4-medium") ``` Space가 서버에서 다시 로드되어야 하기 때문에 하드웨어 업데이트는 즉시 이루어지지 않습니다. Space가 어떤 하드웨어에서 실행되고 있는지 언제든지 확인하여 요청이 충족되었는지 확인할 수 있습니다. ```py >>> runtime = api.get_space_runtime(repo_id=repo_id) >>> runtime.stage "RUNNING_BUILDING" >>> runtime.hardware "cpu-basic" >>> runtime.requested_hardware "t4-medium" ``` 이제 완전히 구성된 Space를 가지게 되었습니다. 사용이 끝난 후에는 Space를 "cpu-classic"으로 다운그레이드하는 것을 잊지 마세요. **보너스: Space를 생성하거나 복제할 때 하드웨어 요청하기!** Space가 구축되면 업그레이드된 하드웨어가 자동으로 할당됩니다. ```py >>> api.create_repo( ... repo_id=repo_id, ... repo_type="space", ... space_sdk="gradio" ... space_hardware="cpu-upgrade", ... space_storage="small", ... space_sleep_time="7200", # 2시간을 초로 환산 ... ) ``` ```py >>> api.duplicate_space( ... from_id=repo_id, ... hardware="cpu-upgrade", ... storage="small", ... sleep_time="7200", # 2시간을 초로 환산 ... ) ``` **5. Space 일시 중지 및 다시 시작** 기본적으로 Space가 업그레이드된 하드웨어에서 실행 중이면 절대로 중단되지 않습니다. 그러나 요금이 부과되는 것을 피하려면 사용하지 않을 때 일시 중지하는 것이 좋습니다. 이는 [`pause_space`]를 사용하여 가능합니다. 일시 중지된 Space는 Space 소유자가 UI를 통해 또는 [`restart_space`]를 사용하여 API를 통해 다시 시작할 때까지 비활성화됩니다. 일시 중지된 모드에 대한 자세한 내용은 [이 섹션](https://huggingface.co/docs/hub/spaces-gpus#pause)을 참조하세요. ```py # 과금을 피하기 위해 Space를 일시 중지하세요 >>> api.pause_space(repo_id=repo_id) # (...) # 필요할 때 다시 시작하세요 >>> api.restart_space(repo_id=repo_id) ``` 다른 방법은 Space에 대한 제한 시간을 설정하는 것입니다. Space가 제한 시간을 초과하여 비활성화되면 Space가 sleep 상태로 전환됩니다. Space를 방문한 방문자가 다시 시작시킬 수 있습니다. [`set_space_sleep_time`]를 사용하여 제한 시간을 설정할 수 있습니다. Sleeping 모드에 대한 자세한 내용은 [이 섹션](https://huggingface.co/docs/hub/spaces-gpus#sleep-time)을 참조하세요. ```py # 동작이 멈춘 후 1시간 후에 Space를 sleep 상태로 설정하세요 >>> api.set_space_sleep_time(repo_id=repo_id, sleep_time=3600) ``` 참고: 'cpu-basic' 하드웨어를 사용하는 경우 사용자 정의 sleep 시간을 구성할 수 없습니다. Space가 48시간 동안 동작을 멈추면 자동으로 일시 중지됩니다. **보너스: 하드웨어를 요청하는 동안 sleep 시간 설정하기** 업그레이드된 하드웨어가 Space에 자동으로 할당됩니다. ```py >>> api.request_space_hardware(repo_id=repo_id, hardware=SpaceHardware.T4_MEDIUM, sleep_time=3600) ``` **보너스: Space를 생성하거나 복제할 때 sleep 시간 설정하기!** ```py >>> api.create_repo( ... repo_id=repo_id, ... repo_type="space", ... space_sdk="gradio" ... space_hardware="t4-medium", ... space_sleep_time="3600", ... ) ``` ```py >>> api.duplicate_space( ... from_id=repo_id, ... hardware="t4-medium", ... sleep_time="3600", ... ) ``` **6. Space에 지속적으로 저장소 추가하기** Space를 다시 시작할 때 지속적으로 디스크 공간에 접근할 수 있는 원하는 저장소 계층을 선택할 수 있습니다. 이는 기존의 하드 드라이브와 같이 디스크에서 읽고 쓸 수 있음을 의미합니다. 자세한 내용은 [문서](https://huggingface.co/docs/hub/spaces-storage#persistent-storage)를 참조하세요. ```py >>> from huggingface_hub import SpaceStorage >>> api.request_space_storage(repo_id=repo_id, storage=SpaceStorage.LARGE) ``` 또한 모든 데이터를 영구적으로 삭제하여 저장소를 삭제할 수 있습니다. ```py >>> api.delete_space_storage(repo_id=repo_id) ``` 참고: 한 번 승인된 저장소의 저장소 계층을 낮출 수 없습니다. 그렇게 하려면, 먼저 저장소를 삭제한 다음 새로운 원하는 계층을 요청해야 합니다. **보너스: Space를 생성하거나 복제할 때 저장소 요청하기!** ```py >>> api.create_repo( ... repo_id=repo_id, ... repo_type="space", ... space_sdk="gradio" ... space_storage="large", ... ) ``` ```py >>> api.duplicate_space( ... from_id=repo_id, ... storage="large", ... ) ``` ## 고급 기능: Space를 일시적으로 업그레이드하기![[more-advanced-temporarily-upgrade-your-space-]] Space는 다양한 사용 사례를 허용합니다. 때로는 특정 하드웨어에서 Space를 일시적으로 실행한 다음 무언가를 수행한 후 종료하고 싶을 수 있습니다. 이 섹션에서는 Space를 활용하여 필요할 때 모델을 세밀하게 조정하는 방법에 대해 탐색할 것입니다. 이는 특정 문제를 해결하는 한 가지 방법에 불과합니다. 이를 바탕으로 사용 사례에 맞게 조정해서 사용해야 합니다. 모델을 세밀하게 조정하기 위한 Space가 있다고 가정해 봅시다. 입력으로 모델 ID와 데이터 세트 ID를 받는 Gradio 앱입니다. 작업 흐름은 다음과 같습니다: 0. (사용자에게 모델과 데이터 세트를 요청) 1. Hub에서 모델을 로드합니다. 2. Hub에서 데이터 세트를 로드합니다. 3. 데이터 세트로 모델을 미세 조정합니다. 4. 새 모델을 Hub에 업로드합니다. 단계 3.에서는 사용자 정의 하드웨어가 필요하지만 유료 GPU에서 Space를 항상 실행하고 싶지는 않을 것입니다. 이 때는 학습을 위해 하드웨어를 동적으로 요청한 다음 종료해야 합니다. 하드웨어를 요청하면 Space가 다시 시작되므로 앱은 현재 수행 중인 작업을 어떻게든 "기억"해야 합니다. 이를 수행하는 여러 가지 방법이 있습니다. 이 가이드에서는 "작업 스케줄러"로서 Dataset을 사용하는 하나의 해결책을 살펴보겠습니다. ### 앱 구조[[app-skeleton]] 다음은 구현된 앱의 모습입니다. 시작할 때 예약된 작업이 있는지 확인하고 있다면 적절한 하드웨어에서 실행합니다. 작업이 완료되면 하드웨어를 무료 요금제 CPU로 다시 설정하고 사용자에게 새 작업을 요청합니다. > [!WARNING] > 이 예시는 일반적인 데모처럼 병렬 액세스를 지원하지 않습니다. 특히 학습이 진행되는 동안 인터페이스가 비활성화됩니다. 저장소를 개인으로 설정하여 단일 사용자임을 보장하는 것이 좋습니다. ```py # Space는 하드웨어를 요청하기 위해 토큰이 필요합니다: Secret으로 설정하세요! HF_TOKEN = os.environ.get("HF_TOKEN") # Space를 가진 repo_id TRAINING_SPACE_ID = "Wauplin/dreambooth-training" from huggingface_hub import HfApi, SpaceHardware api = HfApi(token=HF_TOKEN) # Space 시작 시 예약된 작업을 확인합니다. 예약된 작업이 있는 경우 모델을 미세 조정합니다. 그렇지 않은 경우, # 새 작업을 요청할 수 있는 인터페이스를 표시합니다. task = get_task() if task is None: # Gradio 앱 시작 def gradio_fn(task): # 사용자 요청 시 작업 추가 및 하드웨어 요청 add_task(task) api.request_space_hardware(repo_id=TRAINING_SPACE_ID, hardware=SpaceHardware.T4_MEDIUM) gr.Interface(fn=gradio_fn, ...).launch() else: runtime = api.get_space_runtime(repo_id=TRAINING_SPACE_ID) # GPU를 사용 중인지 확인합니다. if runtime.hardware == SpaceHardware.T4_MEDIUM: # 그렇다면, 기본 모델을 데이터 세트로 미세 조정합니다! train_and_upload(task) # 그런 다음, 작업을 "DONE"으로 표시합니다. mark_as_done(task) # 잊지 말아야 할 것: CPU 하드웨어로 다시 설정 api.request_space_hardware(repo_id=TRAINING_SPACE_ID, hardware=SpaceHardware.CPU_BASIC) else: api.request_space_hardware(repo_id=TRAINING_SPACE_ID, hardware=SpaceHardware.T4_MEDIUM) ``` ### 작업 스케줄러[[task-scheduler]] 작업 스케줄링은 여러 가지 방법으로 수행할 수 있습니다. 여기에는 간단한 CSV 파일을 데이터 세트로 사용하여 작업 스케줄링을 하는 예시입니다. ```py # 'tasks.csv' 파일을 포함하는 데이터 세트의 Dataset ID. # 여기서는 입력(기본 모델 및 데이터 세트)과 상태(PENDING 또는 DONE)가 포함된 'tasks.csv' 기본 예제가 주어집니다. # multimodalart/sd-fine-tunable,Wauplin/concept-1,DONE # multimodalart/sd-fine-tunable,Wauplin/concept-2,PENDING TASK_DATASET_ID = "Wauplin/dreambooth-task-scheduler" def _get_csv_file(): return hf_hub_download(repo_id=TASK_DATASET_ID, filename="tasks.csv", repo_type="dataset", token=HF_TOKEN) def get_task(): with open(_get_csv_file()) as csv_file: csv_reader = csv.reader(csv_file, delimiter=',') for row in csv_reader: if row[2] == "PENDING": return row[0], row[1] # model_id, dataset_id def add_task(task): model_id, dataset_id = task with open(_get_csv_file()) as csv_file: with open(csv_file, "r") as f: tasks = f.read() api.upload_file( repo_id=repo_id, repo_type=repo_type, path_in_repo="tasks.csv", # 작업을 추가하기 위한 빠르고 더러운 방법 path_or_fileobj=(tasks + f"\n{model_id},{dataset_id},PENDING").encode() ) def mark_as_done(task): model_id, dataset_id = task with open(_get_csv_file()) as csv_file: with open(csv_file, "r") as f: tasks = f.read() api.upload_file( repo_id=repo_id, repo_type=repo_type, path_in_repo="tasks.csv", # 작업을 DONE으로 설정하는 빠르고 더러운 방법 path_or_fileobj=tasks.replace( f"{model_id},{dataset_id},PENDING", f"{model_id},{dataset_id},DONE" ).encode() ) ``` huggingface_hub-1.1.5/docs/source/ko/guides/model-cards.md000066400000000000000000000270601510763414300234710ustar00rootroot00000000000000 # 모델 카드 생성 및 공유[[create-and-share-model-cards]] `huggingface_hub` 라이브러리는 모델 카드를 생성, 공유, 업데이트할 수 있는 파이썬 인터페이스를 제공합니다. Hub의 모델 카드가 무엇인지, 그리고 실제로 어떻게 작동하는지에 대한 자세한 내용을 확인하려면 [전용 설명 페이지](https://huggingface.co/docs/hub/models-cards)를 방문하세요. > [!TIP] > [신규 (베타)! 우리의 실험적인 모델 카드 크리에이터 앱을 사용해 보세요](https://huggingface.co/spaces/huggingface/Model_Cards_Writing_Tool) ## Hub에서 모델 카드 불러오기[[load-a-model-card-from-the-hub]] Hub에서 기존 카드를 불러오려면 [`ModelCard.load`] 기능을 사용하면 됩니다. 이 문서에서는 [`nateraw/vit-base-beans`](https://huggingface.co/nateraw/vit-base-beans)에서 카드를 불러오겠습니다. ```python from huggingface_hub import ModelCard card = ModelCard.load('nateraw/vit-base-beans') ``` 이 카드에는 접근하거나 활용할 수 있는 몇 가지 유용한 속성이 있습니다: - `card.data`: 모델 카드의 메타데이터와 함께 [`ModelCardData`] 인스턴스를 반환합니다. 이 인스턴스에 `.to_dict()`를 호출하여 표현을 사전으로 가져옵니다. - `card.text`: *메타데이터 헤더를 제외*한 카드의 텍스트를 반환합니다. - `card.content`: *메타데이터 헤더를 포함*한 카드의 텍스트 콘텐츠를 반환합니다. ## 모델 카드 만들기[[create-model-cards]] ### 텍스트에서 생성[[from-text]] 텍스트로 모델 카드의 초기 내용을 설정하려면, 카드의 텍스트 내용을 초기화 시 `ModelCard`에 전달하면 됩니다. ```python content = """ --- language: en license: mit --- # 내 모델 카드 """ card = ModelCard(content) card.data.to_dict() == {'language': 'en', 'license': 'mit'} # True ``` 이 작업을 수행하는 또 다른 방법은 f-strings를 사용하는 것입니다. 다음 예에서 우리는: - 모델 카드에 YAML 블록을 삽입할 수 있도록 [`ModelCardData.to_yaml`]을 사용해서 우리가 정의한 메타데이터를 YAML로 변환합니다. - Python f-strings를 통해 템플릿 변수를 사용할 방법을 보여줍니다. ```python card_data = ModelCardData(language='en', license='mit', library='timm') example_template_var = 'nateraw' content = f""" --- { card_data.to_yaml() } --- # 내 모델 카드 이 모델은 [@{example_template_var}](https://github.com/ {example_template_var})에 의해 생성되었습니다 """ card = ModelCard(content) print(card) ``` 위 예시는 다음과 같은 모습의 카드를 남깁니다: ``` --- language: en license: mit library: timm --- # 내 모델 카드 This model created by [@nateraw](https://github.com/nateraw) ``` ### Jinja 템플릿으로부터[[from-a-jinja-template]] `Jinja2`가 설치되어 있으면, jinja 템플릿 파일에서 모델 카드를 만들 수 있습니다. 기본적인 예를 살펴보겠습니다: ```python from pathlib import Path from huggingface_hub import ModelCard, ModelCardData # jinja 템플릿 정의 template_text = """ --- {{ card_data }} --- # MyCoolModel 모델용 모델 카드 이 모델은 이런 저런 것들을 합니다. 이 모델은 [[@{{ author }}](https://hf.co/{{author}})에 의해 생성되었습니다. """.strip() # 템플릿을 파일에 쓰기 Path('custom_template.md').write_text(template_text) # 카드 메타데이터 정의 card_data = ModelCardData(language='en', license='mit', library_name='keras') # 템플릿에서 카드를 만들고 원하는 Jinja 템플릿 변수를 전달합니다. # 우리의 경우에는 작성자를 전달하겠습니다. card = ModelCard.from_template(card_data, template_path='custom_template.md', author='nateraw') card.save('my_model_card_1.md') print(card) ``` 결과 카드의 마크다운은 다음과 같습니다: ``` --- language: en license: mit library_name: keras --- # MyCoolModel 모델용 모델 카드 이 모델은 이런 저런 것들을 합니다. 이 모델은 [@nateraw](https://hf.co/nateraw)에 의해 생성되었습니다. ``` 카드 데이터를 업데이트하면 카드 자체에 반영됩니다. ``` card.data.library_name = 'timm' card.data.language = 'fr' card.data.license = 'apache-2.0' print(card) ``` 이제 보시다시피 메타데이터 헤더가 업데이트되었습니다: ``` --- language: fr license: apache-2.0 library_name: timm --- # MyCoolModel 모델용 모델 카드 이 모델은 이런 저런 것들을 합니다. 이 모델은 [@nateraw](https://hf.co/nateraw)에 의해 생성되었습니다. ``` 카드 데이터를 업데이트할 때 [`ModelCard.validate`]를 불러와 Hub에 대해 카드가 여전히 유효한지 확인할 수 있습니다. 이렇게 하면 Hugging Face Hub에 설정된 모든 유효성 검사 규칙을 통과할 수 있습니다. ### 기본 템플릿으로부터[[from-the-default-template]] 자체 템플릿을 사용하는 대신에, 많은 섹션으로 구성된 기능이 풍부한 [기본 템플릿](https://github.com/huggingface/huggingface_hub/blob/main/src/huggingface_hub/templates/modelcard_template.md)을 사용할 수도 있습니다. 내부적으론 [Jinja2](https://jinja.palletsprojects.com/en/3.1.x/) 를 사용하여 템플릿 파일을 작성합니다. > [!TIP] > `from_template`를 사용하려면 jinja2를 설치해야 합니다. `pip install Jinja2`를 사용하면 됩니다. ```python card_data = ModelCardData(language='en', license='mit', library_name='keras') card = ModelCard.from_template( card_data, model_id='my-cool-model', model_description="this model does this and that", developers="Nate Raw", repo="https://github.com/huggingface/huggingface_hub", ) card.save('my_model_card_2.md') print(card) ``` ## 모델 카드 공유하기[[share-model-cards]] Hugging Face Hub로 인증받은 경우(`hf auth login` 또는 [`login`] 사용) 간단히 [`ModelCard.push_to_hub`]를 호출하여 카드를 Hub에 푸시할 수 있습니다. 이를 수행하는 방법을 살펴보겠습니다. 먼저 인증된 사용자의 네임스페이스 아래에 'hf-hub-modelcards-pr-test'라는 새로운 레포지토리를 만듭니다: ```python from huggingface_hub import whoami, create_repo user = whoami()['name'] repo_id = f'{user}/hf-hub-modelcards-pr-test' url = create_repo(repo_id, exist_ok=True) ``` 그런 다음 기본 템플릿에서 카드를 만듭니다(위 섹션에서 정의한 것과 동일): ```python card_data = ModelCardData(language='en', license='mit', library_name='keras') card = ModelCard.from_template( card_data, model_id='my-cool-model', model_description="this model does this and that", developers="Nate Raw", repo="https://github.com/huggingface/huggingface_hub", ) ``` 마지막으로 이를 Hub로 푸시하겠습니다. ```python card.push_to_hub(repo_id) ``` 결과 카드는 [여기](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/blob/main/README.md)에서 확인할 수 있습니다. PR로 카드를 푸시하고 싶다면 `push_to_hub`를 호출할 때 `create_pr=True`라고 지정하면 됩니다. ```python card.push_to_hub(repo_id, create_pr=True) ``` 이 명령으로 생성된 결과 PR은 [여기](https://huggingface.co/nateraw/hf-hub-modelcards-pr-test/discussions/3)에서 볼 수 있습니다. ## 메타데이터 업데이트[[update-metadata]] 이 섹션에서는 레포 카드에 있는 메타데이터와 업데이트 방법을 확인합니다. `메타데이터`는 모델, 데이터 세트, Spaces에 대한 높은 수준의 정보를 제공하는 해시맵(또는 키 값) 컨텍스트를 말합니다. 모델의 `pipeline type`, `model_id` 또는 `model_desc` 설명 등의 정보가 포함될 수 있습니다. 자세한 내용은 [모델 카드](https://huggingface.co/docs/hub/model-cards#model-card-metadata), [데이터 세트 카드](https://huggingface.co/docs/hub/datasets-cards#dataset-card-metadata) 및 [�Spaces 설정](https://huggingface.co/docs/hub/spaces-settings#spaces-settings) 을 참조하세요. 이제 메타데이터를 업데이트하는 방법에 대한 몇 가지 예를 살펴보겠습니다. 첫 번째 예부터 살펴보겠습니다: ```python >>> from huggingface_hub import metadata_update >>> metadata_update("username/my-cool-model", {"pipeline_tag": "image-classification"}) ``` 두 줄의 코드를 사용하면 메타데이터를 업데이트하여 새로운 `파이프라인_태그`를 설정할 수 있습니다. 기본적으로 카드에 이미 존재하는 키는 업데이트할 수 없습니다. 그렇게 하려면 `overwrite=True`를 명시적으로 전달해야 합니다. ```python >>> from huggingface_hub import metadata_update >>> metadata_update("username/my-cool-model", {"pipeline_tag": "text-generation"}, overwrite=True) ``` 쓰기 권한이 없는 저장소에 일부 변경 사항을 제안하려는 경우가 종종 있습니다. 소유자가 귀하의 제안을 검토하고 병합할 수 있도록 해당 저장소에 PR을 생성하면 됩니다. ```python >>> from huggingface_hub import metadata_update >>> metadata_update("someone/model", {"pipeline_tag": "text-classification"}, create_pr=True) ``` ## 평가 결과 포함하기[[include-evaluation-results]] 메타데이터 `모델-인덱스`에 평가 결과를 포함하려면 관련 평가 결과와 함께 [EvalResult] 또는 `EvalResult` 목록을 전달하면 됩니다. 내부적으론 `card.data.to _dict()`를 호출하면 `모델-인덱스`가 생성됩니다. 자세한 내용은 [Hub 문서의 이 섹션](https://huggingface.co/docs/hub/models-cards#evaluation-results)을 참조하십시오. > [!TIP] > 이 기능을 사용하려면 [ModelCardData]에 `model_name` 속성을 포함해야 합니다. ```python card_data = ModelCardData( language='en', license='mit', model_name='my-cool-model', eval_results = EvalResult( task_type='image-classification', dataset_type='beans', dataset_name='Beans', metric_type='accuracy', metric_value=0.7 ) ) card = ModelCard.from_template(card_data) print(card.data) ``` 결과 `card.data`는 다음과 같이 보여야 합니다: ``` language: en license: mit model-index: - name: my-cool-model results: - task: type: image-classification dataset: name: Beans type: beans metrics: - type: accuracy value: 0.7 ``` `EvalResult`: 공유하고 싶은 평가 결과가 둘 이상 있는 경우 `EvalResults` 목록을 전달하기만 하면 됩니다: ```python card_data = ModelCardData( language='en', license='mit', model_name='my-cool-model', eval_results = [ EvalResult( task_type='image-classification', dataset_type='beans', dataset_name='Beans', metric_type='accuracy', metric_value=0.7 ), EvalResult( task_type='image-classification', dataset_type='beans', dataset_name='Beans', metric_type='f1', metric_value=0.65 ) ] ) card = ModelCard.from_template(card_data) card.data ``` 그러면 다음 `card.data`가 남게 됩니다: ``` language: en license: mit model-index: - name: my-cool-model results: - task: type: image-classification dataset: name: Beans type: beans metrics: - type: accuracy value: 0.7 - type: f1 value: 0.65 ``` huggingface_hub-1.1.5/docs/source/ko/guides/overview.md000066400000000000000000000142511510763414300231430ustar00rootroot00000000000000 # How-to 가이드 [[howto-guides]] 특정 목표를 달성하는 데 도움이 되는 실용적인 가이드들입니다. huggingface_hub로 실제 문제를 해결하는 방법을 배우려면 다음 문서들을 살펴보세요.
리포지토리

Hub에서 리포지토리를 만드는 방법은 무엇인가요? 구성하는 방법은요? 리포지토리와 상호 작용하려면 어떻게 해야하나요?

파일 다운로드

Hub에서 파일을 다운로드하려면 어떻게 하나요? 리포지토리는요?

파일 업로드

파일이나 폴더를 어떻게 업로드하나요? Hub의 기존 리포지토리를 변경하려면 어떻게 해야 하나요?

검색

20만 개가 넘게 공개된 모델, 데이터 세트 및 Space를 효율적으로 검색하는 방법은 무엇인가요?

HfFileSystem

Python의 파일 인터페이스를 모방한 편리한 인터페이스를 통해 Hub와 상호 작용하는 방법은 무엇인가요?

Inference

가속화된 Inference API로 추론하려면 어떻게 하나요?

커뮤니티 탭

커뮤니티 탭에서 PR과 댓글을 통해 어떻게 소통할 수 있나요?

캐시

캐시 시스템은 어떻게 작동하나요? 이점은 무엇인가요?

모델 카드

모델 카드는 어떻게 만들고 공유하나요?

Space 관리

Space 하드웨어와 구성은 어떻게 관리하나요?

라이브러리 통합

라이브러리를 Hub와 통합한다는 것은 무엇을 의미하나요? 그리고 어떻게 할 수 있을까요?

웹훅 서버

웹훅을 수신할 서버를 만들고 Space로 배포하는 방법은 무엇인가요?

huggingface_hub-1.1.5/docs/source/ko/guides/search.md000066400000000000000000000057121510763414300225440ustar00rootroot00000000000000 # Hub에서 검색하기[[search-the-hub]] 이 튜토리얼에서는 `huggingface_hub`를 사용하여 Hub에서 모델, 데이터 세트 및 Spaces를 검색하는 방법을 배웁니다. ## 리포지토리를 어떻게 나열하나요?[[how-to-list-repositories-]] `huggingface_hub` 라이브러리에는 Hub와 상호작용하기 위한 HTTP 클라이언트[`HfApi`]가 포함되어 있습니다. 이를 통해, Hub에 저장된 모델, 데이터셋, 그리고 Spaces를 나열할 수 있습니다. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> models = api.list_models() ``` [`list_models`]의 출력은 Hub에 저장되어 있는 모델들을 나열한 결과입니다. 마찬가지로, [`list_datasets`]를 사용하여 데이터 세트를 나열하고 [`list_spaces`]를 사용하여 Spaces를 나열할 수 있습니다. ## 리포지토리를 어떻게 필터링하나요?[[how-to-filter-repositories-]] 리포지토리를 나열하는 것도 유용하지만, 검색을 필터링하고 싶을 수도 있습니다. 리스트에는 다음과 같은 여러 속성이 있습니다. - `filter` - `author` - `search` - ... 이 매개변수 중 두 개는 직관적입니다(`author` 및 `search`). 그렇다면 `filter`는 어떤 것을 나타낼까요? `filter`는 [`ModelFilter`] 객체(또는 [`DatasetFilter`])를 입력으로 받습니다. 이를 이용해 필터링 하고 싶은 모델을 지정하여 인스턴스를 생성할 수 있습니다. PyTorch로 작동되고 imagenet 데이터 세트로 훈련된, 이미지 분류를 위한 Hub의 모든 모델을 찾는 방법으로 예를 들어보겠습니다. 이 과정은 단일 [ModelFilter]를 사용하여 수행할 수 있습니다. 이때, 필터링 속성들은 '논리적 AND'로 결합되어, 지정한 모든 조건을 만족하는 모델만 선택됩니다. ```py models = hf_api.list_models( filter=ModelFilter( task="image-classification", library="pytorch", trained_dataset="imagenet" ) ) ``` 필터링하는 과정에서 모델을 정렬하고 상위 결과만 선택할 수도 있습니다. 다음 예제는 Hub에서 가장 많이 다운로드된 상위 5개 데이터 세트를 가져옵니다. ```py >>> list(list_datasets(sort="downloads", direction=-1, limit=5)) [DatasetInfo( id='argilla/databricks-dolly-15k-curated-en', author='argilla', sha='4dcd1dedbe148307a833c931b21ca456a1fc4281', last_modified=datetime.datetime(2023, 10, 2, 12, 32, 53, tzinfo=datetime.timezone.utc), private=False, downloads=8889377, (...) ``` Hub에서 사용 가능한 필터에 대해 살펴보려면 웹브라우저에서 [모델](https://huggingface.co/models) 및 [데이터 세트](https://huggingface.co/datasets) 페이지를 방문하여 일부 매개변수를 검색한 다음, URL에서 값들을 확인해보세요. huggingface_hub-1.1.5/docs/source/ko/guides/upload.md000066400000000000000000000654121510763414300225660ustar00rootroot00000000000000 # Hub에 파일 업로드하기[[upload-files-to-the-hub]] 파일과 작업물을 공유하는 것은 Hub의 주요 특성 중 하나입니다. `huggingface_hub`는 Hub에 파일을 업로드하기 위한 몇 가지 옵션을 제공합니다. 이러한 기능을 단독으로 사용하거나 라이브러리에 통합하여 해당 라이브러리의 사용자가 Hub와 더 편리하게 상호작용할 수 있도록 도울 수 있습니다. Hub에 파일을 업로드 하려면 허깅페이스 계정으로 로그인해야 합니다. 인증에 대한 자세한 내용은 [이 페이지](../quick-start#authentication)를 참조해 주세요. ## 파일 업로드하기[[upload-a-file]] [`create_repo`]로 리포지토리를 생성했다면, [`upload_file`]을 사용하여 해당 리포지토리에 파일을 업로드할 수 있습니다. 업로드할 파일의 본 경로, 리포지토리에서 파일을 업로드할 위치, 대상 리포지토리의 이름을 지정합니다. 리포지토리의 유형을 `dataset`, `model`, `space`로 선택적으로 설정할 수 있습니다. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.upload_file( ... path_or_fileobj="/path/to/local/folder/README.md", ... path_in_repo="README.md", ... repo_id="username/test-dataset", ... repo_type="dataset", ... ) ``` ## 폴더 업로드[[upload-a-folder]] 로컬 폴더를 리포지토리에 업로드하려면 [`upload_folder`] 함수를 사용합니다. 업로드할 로컬 폴더의 본 경로, 리포지토리에서 폴더를 업로드할 위치, 대상 리포지토리의 이름을 지정합니다. 리포지토리의 유형을 `dataset`, `model`, `space`로 선택적으로 설정할 수 있습니다. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() # 로컬 폴더에 있는 모든 콘텐츠를 원격 Space에 업로드 합니다. # 파일은 기본적으로 리포지토리의 루트 디렉토리에 업로드 됩니다. >>> api.upload_folder( ... folder_path="/path/to/local/space", ... repo_id="username/my-cool-space", ... repo_type="space", ... ) ``` 기본적으로 어떤 파일을 커밋할지 여부를 알기 위해 `.gitignore` 파일을 참조하게 됩니다. 기본적으로 커밋에 `.gitignore` 파일이 있는지 확인하고, 없는 경우 Hub에 파일이 있는지 확인합니다. 디렉터리의 루트 경로에 있는 `.gitignore` 파일만 사용된다는 점을 주의하세요. 하위 경로에는 `.gitignore` 파일이 있는지 확인하지 않습니다. 하드코딩된 `.gitignore` 파일을 사용하지 않으려면 `allow_patterns` 와 `ignore_patterns` 인수를 사용하여 업로드할 파일을 필터링할 수 있습니다. 이 매개변수들은 단일 패턴 또는 패턴 리스트를 허용합니다. 패턴의 형식은 [이 문서](https://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm)에 설명된 대로 표준 와일드카드(글로빙 패턴)입니다. `allow_patterns`과 `ignore_patterns`을 모두 사용하면 두 가지 설정이 모두 적용됩니다. `.gitignore` 파일과 allow/ignore 패턴 외에 하위 경로 있는 모든 `.git/` 폴더는 무시됩니다. ```py >>> api.upload_folder( ... folder_path="/path/to/local/folder", ... path_in_repo="my-dataset/train", # 특정 폴더에 업로드 ... repo_id="username/test-dataset", ... repo_type="dataset", ... ignore_patterns="**/logs/*.txt", # 모든 로그 텍스트 파일을 무시 ... ) ``` `delete_patterns` 인수를 사용하여 동일한 커밋에서 리포지토리에서 삭제할 파일을 지정할 수도 있습니다. 이 방법은 파일을 푸시하기 전에 원격 폴더를 정리하고 싶은데 어떤 파일이 이미 존재하는지 모르는 경우에 유용합니다. 다음은 로컬 `./logs` 폴더를 원격 `/experiment/logs/` 폴더에 업로드하는 예시입니다. 폴더 내의 txt 파일만을 업로드 하게 되며 그 전에 리포지토리에 있던 모든 이전 txt 파일이 삭제됩니다. 이 모든 과정이 단 한 번의 커밋으로 이루어집니다. ```py >>> api.upload_folder( ... folder_path="/path/to/local/folder/logs", ... repo_id="username/trained-model", ... path_in_repo="experiment/logs/", ... allow_patterns="*.txt", # 모든 로컬 텍스트 파일을 업로드 ... delete_patterns="*.txt", # 모든 이전 텍스트 파일을 삭제 ... ) ``` ## CLI에서 업로드[[upload-from-the-cli]] 터미널에서 `hf upload` 명령어를 사용하여 Hub에 파일을 직접 업로드할 수 있습니다. 내부적으로는 위에서 설명한 것과 동일한 [`upload_file`] 와 [`upload_folder`] 함수를 사용합니다. 다음과 같이 단일 파일 또는 전체 폴더를 업로드할 수 있습니다: ```bash # 사용례: hf upload [repo_id] [local_path] [path_in_repo] >>> hf upload Wauplin/my-cool-model ./models/model.safetensors model.safetensors https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors >>> hf upload Wauplin/my-cool-model ./models . https://huggingface.co/Wauplin/my-cool-model/tree/main ``` `local_path` 와 `path_in_repo`는 선택 사항이며 주어지지 않을 시 임의로 추정됩니다. `local_path`가 설정되지 않은 경우, 이 툴은 로컬 폴더나 파일에 `repo_id`와 같은 이름이 있는지 확인하며, 발견된 경우 해당 폴더나 파일이 업로드됩니다. 같은 이름의 폴더나 파일을 찾지 못한다면 사용자에게 `local_path`를 명시하도록 요청하는 예외 처리가 발생합니다. 어떤 경우든 `path_in_repo`가 설정되어 있지 않으면 파일이 리포지토리의 루트 디렉터리에 업로드됩니다. CLI 업로드 명령어에 대한 자세한 내용은 [CLI 가이드](./cli#hf-upload)를 참조하세요. ## 고급 기능[[advanced-features]] 대부분의 경우, Hub에 파일을 업로드하는 데 [`upload_file`]과 [`upload_folder`] 이상이 필요하지 않습니다. 하지만 `huggingface_hub`에는 작업을 더 쉽게 할 수 있는 고급 기능이 있습니다. 그 기능들을 살펴봅시다! ### 논블로킹 업로드[[non-blocking-uploads]] 메인 스레드를 멈추지 않고 데이터를 푸시하고 싶은 경우가 있습니다. 이는 모델 학습을 계속 진행하면서 로그와 아티팩트를 업로드할 때 특히 유용합니다. 이렇게 하려면 [`upload_file`]과 [[`upload_folder`] 에 `run_as_future` 인수를 사용하고 [`concurrent.futures.Future`](https://docs.python.org/3/library/concurrent.futures.html#future-objects)객체를 반환받아 업로드 상태를 확인하는 데 사용할 수 있습니다. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> future = api.upload_folder( # 백그라운드에서 업로드 작업 수행 (논블로킹) ... repo_id="username/my-model", ... folder_path="checkpoints-001", ... run_as_future=True, ... ) >>> future Future(...) >>> future.done() False >>> future.result() # 업로드가 완료될 때까지 대기 (블로킹) ... ``` > [!TIP] > `run_as_future=True`를 사용하면 백그라운드 작업이 큐에 대기됩니다. 이는 작업이 올바른 순서로 실행된다는 것을 의미합니다. 백그라운드 작업은 주로 데이터를 업로드하거나 커밋을 생성하는 데 유용하지만, 이 외에도 [`run_as_future`]를 사용하여 원하는 메소드를 대기열에 넣을 수 있습니다. 예를 들어, 해당 기능을 사용하여 백그라운드에서 리포지토리를 만든 다음 그대로 데이터를 업로드할 수 있습니다. 업로드 메소드에 내장된 `run_as_future` 인수는 본 기능의 별칭입니다. ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.run_as_future(api.create_repo, "username/my-model", exists_ok=True) Future(...) >>> api.upload_file( ... repo_id="username/my-model", ... path_in_repo="file.txt", ... path_or_fileobj=b"file content", ... run_as_future=True, ... ) Future(...) ``` ### 청크 단위로 폴더 업로드하기[[upload-a-folder-by-chunks]] [`upload_folder`]를 사용하면 전체 폴더를 Hub에 쉽게 업로드할 수 있지만, 대용량 폴더(수천 개의 파일 또는 수백 GB의 용량)의 경우 문제가 될 수 있습니다. 파일이 많은 폴더가 있는 경우 여러 커밋에 걸쳐 업로드하는 것이 좋습니다. 업로드 중에 오류나 연결 문제가 발생해도 처음부터 다시 시작할 필요는 없습니다. 여러 커밋으로 폴더를 업로드하려면 `multi_commits=True`를 인수로 전달하면 됩니다. 내부적으로 `huggingface_hub`는 업로드/삭제할 파일을 나열하고 여러 커밋으로 분할합니다. 커밋을 분할하는 전략은 업로드할 파일의 수와 크기에 따라 결정됩니다. 모든 커밋을 푸시하기 위해 Hub에 PR이 열리게 되며, PR이 준비되면 여러 커밋이 단일 커밋으로 뭉쳐집니다. 완료하기 전에 프로세스가 중단된 경우 스크립트를 다시 실행하여 업로드를 재개할 수 있습니다. 생성된 PR이 자동으로 감지되고 업로드가 중단된 지점부터 업로드가 재개됩니다. 업로드 진행 상황을 더 잘 이해하고 싶다면 `multi_commits_verbose=True`를 인수로 전달하면 됩니다. 다음은 여러 커밋으로 체크포인트 폴더를 데이터셋에 업로드하는 예제입니다. Hub에 PR이 생성되고 업로드가 완료되면 자동으로 병합됩니다. PR을 계속 열어두고 수동으로 검토하려면 `create_pr=True`를 인수로 전달하면 됩니다. ```py >>> upload_folder( ... folder_path="local/checkpoints", ... repo_id="username/my-dataset", ... repo_type="dataset", ... multi_commits=True, ... multi_commits_verbose=True, ... ) ``` 업로드 전략(즉, 생성되는 커밋)을 더 잘 제어하고 싶으면 로우 레벨의 [`plan_multi_commits`] 와 [`create_commits_on_pr`] 메서드를 살펴보세요. > [!WARNING] > `multi_commits`은 아직 실험적인 기능입니다. > 해당 API와 동작은 향후 사전 고지 없이 변경될 수 있습니다. ### 예약된 업로드[[scheduled-uploads]] 허깅 페이스 Hub를 사용하면 데이터를 쉽게 저장하고 버전업할 수 있지만, 동일한 파일을 수천 번 업데이트할 때는 몇 가지 제한이 있습니다. 예를 들어, 배포된 Space에 대한 교육 프로세스 또는 사용자 로그를 저장하고 싶을 때 Hub에 데이터 집합으로 데이터를 업로드하는 것이 좋아 보이지만, 이를 제대로 하기 어려울 수 있습니다. 데이터의 모든 업데이트를 버전으로 만들게 되면 git 리포지토리를 사용할 수 없는 상태로 만들어 버리기 때문입니다. [`CommitScheduler`] 클래스는 이 문제에 대한 해결책을 제공합니다. 이 클래스는 로컬 폴더를 Hub에 정기적으로 푸시하는 백그라운드 작업을 실행합니다. 일부 텍스트를 입력으로 받아 두 개의 번역을 생성한 다음, 사용자가 선호하는 번역을 선택할 수 있는 라디오 스페이스가 있다고 가정해 보겠습니다. 이 스페이스의 각 실행에 대해 입력, 출력 및 사용자 기본 설정을 저장하여 결과를 분석하려고 하는데, 이것은 [`CommitScheduler`]의 완벽한 사용 사례가 될 수 있습니다. Hub에 데이터(잠재적으로 수백만 개의 사용자 피드백)를 저장하고 싶지만, 굳이 각 사용자의 입력을 _실시간_ 으로 저장할 필요는 없으니 데이터를 로컬 JSON 파일에 저장한 다음 10분마다 업로드하면 됩니다. 예제 코드는 다음과 같습니다: ```py >>> import json >>> import uuid >>> from pathlib import Path >>> import gradio as gr >>> from huggingface_hub import CommitScheduler # 데이터를 저장할 파일을 선언합니다. UUID를 이용하여 중복을 방지합니다. >>> feedback_file = Path("user_feedback/") / f"data_{uuid.uuid4()}.json" >>> feedback_folder = feedback_file.parent # 정기 업로드를 예약합니다. 원격 리포지토리와 로컬 폴더가 없을시 생성합니다. >>> scheduler = CommitScheduler( ... repo_id="report-translation-feedback", ... repo_type="dataset", ... folder_path=feedback_folder, ... path_in_repo="data", ... every=10, ... ) # 사용자가 피드백을 제출할 때 호출받을 함수를 정의합니다. (Gradio 안에서 호출받게 됩니다) >>> def save_feedback(input_text:str, output_1: str, output_2:str, user_choice: int) -> None: ... """ ... JSON Lines 파일에 입/출력과 사용자 피드백을 추가합니다. 타 사용자에 의한 동시적인 쓰기를 지양하기 위해 스레드 락을 사용합니다. ... """ ... with scheduler.lock: ... with feedback_file.open("a") as f: ... f.write(json.dumps({"input": input_text, "output_1": output_1, "output_2": output_2, "user_choice": user_choice})) ... f.write("\n") # Gradio를 시작합니다. >>> with gr.Blocks() as demo: >>> ... # Gradio 데모를 정의하고 `save_feedback`을 사용합니다 >>> demo.launch() ``` 사용자 입력/출력 및 피드백은 Hub에서 데이터 세트의 형태로 사용할 수 있습니다. 고유한 JSON 파일 이름을 사용하면 이전 실행이나 다른 스페이스/복제본이 동일한 리포지토리에 동시에 푸시하는 경우의 데이터를 덮어쓰지 않도록 보장할 수 있습니다. [`CommitScheduler`]에 대한 상세 사항은 다음과 같습니다: - **추가 전용:** 스케줄러는 폴더에 콘텐츠를 추가만 한다고 가정합니다. 기존 파일에 데이터를 추가하거나 새 파일을 만들 때만 사용하여야 합니다. 파일을 삭제하거나 덮어쓰면 리포지토리가 손상될 수 있습니다. - **git 히스토리**: 기본적으로 스케줄러는 `매 분마다` 폴더를 커밋합니다. git 리포지토리를 너무 많이 오염시키지 않으려면 최소값을 5분으로 설정하는 것이 좋습니다. 또한 스케줄러는 빈 커밋을 피하도록 설계되었는데, 만약 폴더에서 새 콘텐츠가 감지되지 않으면 예약된 커밋을 삭제합니다. - **에러:** 스케줄러는 백그라운드 스레드로 실행되고, 이는 클래스를 인스턴스화할 때 시작되며 절대 멈추지 않습니다. 만약 업로드 중에 오류가 발생하면(예: 연결 문제), 스케줄러는 이를 아무 말 없이 무시하고 다음 예약된 커밋에서 재시도 합니다. - **스레드 안전:** 대부분의 경우 파일 락에 대해 걱정할 필요 없이 파일에 쓰기 작업을 수행 할 수 있습니다. 스케줄러는 업로드하는 동안 대상 폴더에 콘텐츠를 쓰더라도 충돌하거나 손상되지 않습니다. 그러나, 부하가 많은 앱의 경우 이런 작업에서 _동시성 문제_ 가 발생할 수 있습니다. 이 경우, `scheduler.lock`을 사용하여 스레드 안전을 보장하는 것이 좋습니다. 이 락은 스케줄러가 폴더에서 변경 사항을 검색할 때만 차단되며, 데이터를 업로드할 때는 차단되지 않습니다. 따라서 Space의 사용자 환경에는 영향을 미치지 않습니다. #### 스페이스 지속성 데모[[space-persistence-demo]] 스페이스에서 Hub의 데이터셋으로 데이터를 영속하는 것이 [`CommitScheduler`]의 주요 사용 사례입니다. 각 사용 사례에 따라 데이터 구조를 다르게 설정해야 할 수도 있습니다. 데이터 구조는 동시 사용자와 재시작에 대해 견고해야 하며, 이는 대개 UUID를 생성 해야 함을 의미합니다. 견고함 뿐만 아니라, 재사용성을 위해 🤗 데이터 세트 라이브러리에서 읽을 수 있는 형식으로 데이터를 업로드해야 합니다. 이 [스페이스](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver) 예제에서 여러 가지 데이터 형식을 저장하는 방법을 보여줍니다(각자의 필요에 맞게 조정해야 할 수도 있습니다). #### 사용자 지정 업로드[[custom-uploads]] [`CommitScheduler`]는 데이터가 추가 전용이며 "있는 그대로" 업로드해야 한다고 가정합니다. 그러나 데이터 업로드 방식을 사용자 스스로 정의하고 싶을 때도 있는데, [`CommitScheduler`]를 상속받는 클래스를 생성하고 `push_to_hub` 메서드를 덮어쓰면 됩니다(원하는 방식으로 자유롭게 덮어쓰세요). 이렇게 하면 해당 클래스가 백그라운드 스레드에서 `매 분마다` 호출됩니다. 동시성 및 오류에 대해 걱정할 필요는 없지만 빈 커밋이나 중복된 데이터를 푸시하는 것과 같은 케이스들에 주의해야 합니다. 아래의 (단순화된) 예제에서는 `push_to_hub`를 덮어써서 모든 PNG 파일을 단일 아카이브에 압축하여 Hub의 리포지토리에 과부하가 걸리는 것을 방지합니다:. ```py class ZipScheduler(CommitScheduler): def push_to_hub(self): # 1. PNG 파일들을 나열합니다. png_files = list(self.folder_path.glob("*.png")) if len(png_files) == 0: return None # 커밋할 것이 없다면 일찍 리턴합니다. # 2. png 파일들을 단일 Zip 파일로 압축합니다. with tempfile.TemporaryDirectory() as tmpdir: archive_path = Path(tmpdir) / "train.zip" with zipfile.ZipFile(archive_path, "w", zipfile.ZIP_DEFLATED) as zip: for png_file in png_files: zip.write(filename=png_file, arcname=png_file.name) # 3. 압축된 파일을 업로드 합니다. self.api.upload_file(..., path_or_fileobj=archive_path) # 4. 로컬 png 파일을 삭제하여 다음에 다시 업로드 되는 일을 방지합니다. for png_file in png_files: png_file.unlink() ``` `push_to_hub`를 덮어쓰면 다음과 같은 [`CommitScheduler`]의 속성에 접근할 수 있습니다: - [`HfApi`] 클라이언트: `api` - 폴더 매개변수: `folder_path` 및 `path_in_repo` - 리포지토리 매개변수: `repo_id`, `repo_type`, `revision` - 스레드 락: `lock` > [!TIP] > 사용자 정의 스케줄러의 더 많은 예제는 사용 사례에 따른 다양한 구현이 포함된 [데모 스페이스](https://huggingface.co/spaces/Wauplin/space_to_dataset_saver)를 참조하세요. ### create_commit[[createcommit]] [`upload_file`] 및 [`upload_folder`] 함수는 일반적으로 사용하기 편리한 하이 레벨 API입니다. 로우 레벨에서 작업할 필요가 없다면 이 함수들을 먼저 사용해 볼 것을 권장합니다. 만약 커밋 레벨에서 작업하고 싶다면 [`create_commit`] 함수를 직접 사용할 수 있습니다. [`create_commit`]이 지원하는 작업 유형은 세 가지입니다: - [`CommitOperationAdd`] 는 파일을 Hub에 업로드합니다. 파일이 이미 있는 경우 파일 내용을 덮어씁니다. 이 작업은 두 개의 인수를 받습니다: - `path_in_repo`: 파일을 업로드할 리포지토리 경로. - `path_or_fileobj`: Hub에 업로드할 파일의 파일 시스템상 파일 경로 또는 파일 스타일 객체. - [`CommitOperationDelete`]는 리포지토리에서 파일 또는 폴더를 제거합니다. 이 작업은 `path_in_repo`를 인수로 받습니다. - [`CommitOperationCopy`]는 리포지토리 내의 파일을 복사합니다. 이 작업은 세 가지 인수를 받습니다: - `src_path_in_repo`: 복사할 파일의 리포지토리 경로. - `path_in_repo`: 파일 붙여넣기를 수행할 리포지토리 경로. - `src_revision`: 선택 사항 - 다른 브랜치/리비전에서 파일을 복사하려는 경우 필요한 복사할 파일의 리비전. 예를 들어, Hub 리포지토리에서 두 개의 파일을 업로드하고 한 개의 파일을 삭제하려는 경우: 1. 파일을 추가하거나 삭제하고 폴더를 삭제하기 위해 적절한 `CommitOperation`을 사용합니다: ```py >>> from huggingface_hub import HfApi, CommitOperationAdd, CommitOperationDelete >>> api = HfApi() >>> operations = [ ... CommitOperationAdd(path_in_repo="LICENSE.md", path_or_fileobj="~/repo/LICENSE.md"), ... CommitOperationAdd(path_in_repo="weights.h5", path_or_fileobj="~/repo/weights-final.h5"), ... CommitOperationDelete(path_in_repo="old-weights.h5"), ... CommitOperationDelete(path_in_repo="logs/"), ... CommitOperationCopy(src_path_in_repo="image.png", path_in_repo="duplicate_image.png"), ... ] ``` 2. 작업을 [`create_commit`]에 전달합니다: ```py >>> api.create_commit( ... repo_id="lysandre/test-model", ... operations=operations, ... commit_message="Upload my model weights and license", ... ) ``` 다음 함수들은 [`upload_file`] 및 [`upload_folder`] 외에도 내부적으로 [`create_commit`]을 사용합니다: - [`delete_file`]은 Hub의 리포지토리에서 단일 파일을 삭제합니다. - [`delete_folder`]는 Hub의 리포지토리에서 전체 폴더를 삭제합니다. - [`metadata_update`]는 리포지토리의 메타데이터를 업데이트합니다. 자세한 내용은 [`HfApi`] 의 레퍼런스를 참조하세요. ### 커밋하기 전에 LFS 파일 미리 업로드하기[[preupload-lfs-files-before-commit]] 경우에 따라 커밋 호출을 **하기 전에** 대용량 파일을 S3에 업로드해야 할 수도 있습니다. 예를 들어 인메모리에 생성된 여러 개의 샤드에 있는 데이터 세트를 커밋하는 경우, 샤드를 하나씩 업로드해야 메모리 부족 문제를 피할 수 있을 것입니다. 이 문제에 대한 해결책은 각 샤드를 리포지토리에 별도의 커밋으로 업로드하는 것입니다. 이 방법은 완벽하게 유효하지만, 수십 개의 커밋을 생성하여 잠재적으로 git 히스토리를 엉망으로 만들 수 있다는 단점이 있습니다. 이 문제를 극복하기 위해 파일을 하나씩 S3에 업로드한 다음 마지막에 하나의 커밋을 생성할 수 있습니다. 이는 [`preupload_lfs_files`]와 [`create_commit`]을 함께 사용하면 됩니다. > [!WARNING] > 이 방법은 고급 사용자를 위한 방식입니다. > 사전에 파일을 미리 업로드하는 로우 레벨 로직을 처리하는 대신 [`upload_file`], [`upload_folder`] 또는 [`create_commit`]을 직접 사용하는 것이 대부분의 경우에 적합합니다. > [`preupload_lfs_files`]의 주요 주의 사항은 커밋이 실제로 이루어질 때까지는 Hub의 리포지토리에서 업로드 파일에 액세스할 수 없다는 것입니다. > 궁금한 점이 있으면 언제든지 Discord나 GitHub 이슈로 문의해 주세요. 다음은 파일을 미리 업로드하는 방법을 보여주는 간단한 예시입니다: ```py >>> from huggingface_hub import CommitOperationAdd, preupload_lfs_files, create_commit, create_repo >>> repo_id = create_repo("test_preupload").repo_id >>> operations = [] # 생성될 모든 `CommitOperationAdd` 객체를 나열합니다. >>> for i in range(5): ... content = ... # bin 자료를 생성합니다. ... addition = CommitOperationAdd(path_in_repo=f"shard_{i}_of_5.bin", path_or_fileobj=content) ... preupload_lfs_files(repo_id, additions=[addition]) ... operations.append(addition) >>> # 커밋을 생성합니다. >>> create_commit(repo_id, operations=operations, commit_message="Commit all shards") ``` 먼저, [`CommitOperationAdd`] 오브젝트를 하나씩 생성합니다. 실전을 상정한 예제에서는, 여기에 생성된 샤드를 포함합니다. 각 파일은 다음 파일을 생성하기 전에 업로드됩니다. [`preupload_lfs_files`] 단계에서는 **`CommitOperationAdd` 오브젝트가 변경됩니다.** 따라서[`create_commit`]에 직접 전달할 때만 사용해야 합니다. 오브젝트의 주요 업데이트는 **바이너리 콘텐츠가 제거**된다는 것인데, 이는 따로 레퍼런스를 저장하지 않으면 가비지 콜렉팅 됨을 의미합니다. 이미 업로드된 콘텐츠를 메모리상에 남기고 싶지 않기 때문입니다. 마지막으로 모든 작업을 [`create_commit`]에 전달하여 커밋을 생성합니다. 아직 처리되지 않은 추가 작업(추가, 삭제 또는 복사)도 전달하면 올바르게 처리됩니다. ## 대용량 업로드를 위한 팁과 요령[[tips-and-tricks-for-large-uploads]] 리포지토리에 있는 대량의 데이터를 처리할 때 주의해야 할 몇 가지 제한 사항이 있습니다. 데이터를 스트리밍하는 데 걸리는 시간을 고려하면, 프로세스 마지막에 업로드/푸시가 실패하거나 hf.co에서 또는 로컬에서 작업할 때 성능 저하가 발생하는 것은 매우 성가신 일이 될 수 있습니다. Hub에서 리포지토리를 구성하는 방법에 대한 모범 사례는 [리포지토리 제한 사항 및 권장 사항](https://huggingface.co/docs/hub/repositories-recommendations) 가이드를 참조하세요. 다음으로 업로드 프로세스를 최대한 원활하게 진행할 수 있는 몇 가지 실용적인 팁을 살펴보겠습니다. - **작게 시작하세요**: 업로드 스크립트를 테스트할 때는 소량의 데이터로 시작하는 것이 좋습니다. 소량의 데이터를 처리하는데 적은 시간이 들기 때문에 스크립트를 반복하는 것이 더 쉽습니다. - **실패를 예상하세요**: 대량의 데이터를 스트리밍하는 것은 어려운 일입니다. 어떤 일이 일어날지 알 수 없지만, 항상 컴퓨터, 연결, 서버 등 어떤 이유로든 한 번쯤은 실패할 수 있다는 점을 고려하는 것이 가장 좋습니다. 예를 들어, 많은 양의 파일을 업로드할 계획이라면 다음 파일을 업로드하기 전에 이미 업로드한 파일을 로컬에서 추적하는 것이 가장 좋습니다. 이미 커밋된 LFS 파일은 절대 두 번 다시 업로드되지 않지만 클라이언트 측에서 이를 확인하면 시간을 절약할 수 있습니다. - **`hf_transfer`를 사용하세요**: [`hf_transfer`](https://github.com/huggingface/hf_transfer)는 대역폭이 매우 높은 컴퓨터에서 업로드 속도를 높이기 위한 Rust 기반 라이브러리입니다. `hf_transfer`를 사용하려면: 1. `huggingface_hub`를 설치할 때 `hf_transfer`를 추가로 지정합니다. (예: `pip install huggingface_hub[hf_transfer]`). 2. 환경 변수로 `HF_HUB_ENABLE_HF_TRANSFER=1`을 설정합니다. > [!WARNING] > `hf_transfer`는 고급 사용자 도구입니다! > 테스트 및 프로덕션 준비가 완료되었지만, 고급 오류 처리나 프록시와 같은 사용자 친화적인 기능이 부족합니다. > 자세한 내용은 [이 섹션](https://huggingface.co/docs/huggingface_hub/hf_transfer)을 참조하세요. huggingface_hub-1.1.5/docs/source/ko/guides/webhooks_server.md000066400000000000000000000260071510763414300245060ustar00rootroot00000000000000 # 웹훅 서버[[webhooks-server]] 웹훅은 MLOps 관련 기능의 기반이 됩니다. 이를 통해 특정 저장소의 새로운 변경 사항을 수신하거나, 관심 있는 특정 사용자/조직에 속한 모든 저장소의 변경 사항을 받아볼 수 있습니다. 이 가이드에서는 `huggingface_hub`를 활용하여 웹훅을 수신하는 서버를 만들고 Space에 배포하는 방법을 설명합니다. 이를 위해서는 Huggingface Hub의 웹훅 개념에 대해 익숙해야 합니다. 웹훅 자체에 대해 더 자세히 알아보려면 이 [가이드](https://huggingface.co/docs/hub/webhooks)를 먼저 읽어보세요. 이 가이드에서 사용할 기본 클래스는 [`WebhooksServer`]입니다. 이 클래스는 Huggingface Hub에서 웹훅을 받을 수 있는 서버를 쉽게 구성할 수 있습니다. 서버는 [Gradio](https://gradio.app/) 앱을 기반으로 합니다. 이 서버에는 사용자를 위한 지침을 표시하는 UI와 웹훅을 수신하는 API가 있습니다. > [!TIP] > 웹훅 서버의 실행 예시를 보려면 [Spaces CI Bot](https://huggingface.co/spaces/spaces-ci-bot/webhook)을 확인하세요. > 이것은 Space의 PR이 열릴 때마다 임시 환경을 실행하는 Space입니다. > [!WARNING] > 이것은 [실험적 기능](../package_reference/environment_variables#hfhubdisableexperimentalwarning)입니다. > 본 API는 현재 개선 작업 중이며, 향후 사전 통지 없이 주요 변경 사항이 도입될 수 있습니다. > requirements에서 `huggingface_hub`의 버전을 고정하는 것을 권장합니다. ## 엔드포인트 생성[[create-an-endpoint]] 웹훅 엔드포인트를 구현하는 것은 함수에 데코레이터를 추가하는 것만큼 간단합니다. 주요 개념을 설명하기 위해 첫 번째 예시를 살펴보겠습니다: ```python # app.py from huggingface_hub import webhook_endpoint, WebhookPayload @webhook_endpoint async def trigger_training(payload: WebhookPayload) -> None: if payload.repo.type == "dataset" and payload.event.action == "update": # 데이터 세트가 업데이트되면 학습 작업을 트리거합니다. ... ``` 이 코드 스니펫을 `'app.py'`라는 파일에 저장하고 `'python app.py'`로 실행하면 다음과 같은 메시지가 표시될 것입니다: ```text Webhook secret is not defined. This means your webhook endpoints will be open to everyone. To add a secret, set `WEBHOOK_SECRET` as environment variable or pass it at initialization: `app = WebhooksServer(webhook_secret='my_secret', ...)` For more details about webhook secrets, please refer to https://huggingface.co/docs/hub/webhooks#webhook-secret. Running on local URL: http://127.0.0.1:7860 Running on public URL: https://1fadb0f52d8bf825fc.gradio.live This share link expires in 72 hours. For free permanent hosting and GPU upgrades (NEW!), check out Spaces: https://huggingface.co/spaces Webhooks are correctly setup and ready to use: - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training Go to https://huggingface.co/settings/webhooks to setup your webhooks. ``` 축하합니다! 웹훅 서버를 실행했습니다! 정확히 어떤 일이 일어났는지 살펴보겠습니다: 1. [`webhook_endpoint`]로 함수에 데코레이터를 추가하면 백그라운드에서 [`WebhooksServer`] 객체가 생성됩니다. 볼 수 있듯이 이 서버는 http://127.0.0.1:7860 에서 실행되는 Gradio 앱입니다. 이 URL을 브라우저에서 열면 등록된 웹훅에 대한 지침이 있는 랜딩 페이지를 볼 수 있습니다. 2. Gradio 앱은 내부적으로 FastAPI 서버입니다. 새로운 POST 경로 `/webhooks/trigger_training`이 추가되었습니다. 이 경로는 웹훅을 수신하고 트리거될 때 `trigger_training` 함수를 실행합니다. FastAPI는 자동으로 페이로드를 구문 분석하고 [`WebhookPayload`] 객체로 함수에 전달합니다. 이 `pydantic` 객체에는 웹훅을 트리거한 이벤트에 대한 모든 정보가 포함되어 있습니다. 3. Gradio 앱은 인터넷에서 요청을 받을 수 있는 터널도 열었습니다. 이것은 흥미로운 부분으로, https://huggingface.co/settings/webhooks 에서 로컬 머신을 가리키는 웹훅을 구성할 수 있습니다. 이를 통해 웹훅 서버를 디버깅하고 Space에 배포하기 전에 빠르게 반복할 수 있습니다. 4. 마지막으로 로그에는 서버가 현재 비밀로 보호되지 않는다고 알려줍니다. 이것은 로컬 디버깅에는 문제가 되지 않지만 나중에 고려해야 할 사항입니다. > [!WARNING] > 기본적으로 서버는 스크립트 끝에서 시작됩니다. > 주피터 노트북에서 실행 중이라면 `decorated_function.run()`을 호출하여 서버를 수동으로 시작할 수 있습니다. > 고유한 서버를 사용하기 때문에 여러 엔드포인트가 있더라도 서버를 한 번만 시작하면 됩니다. ## 웹훅 설정하기[[configure-a-webhook]] 웹훅 서버를 실행하고 있으므로, 이제 메시지를 수신하기 위해 웹훅을 구성해야 합니다. https://huggingface.co/settings/webhooks 로 이동하여 "Add a new webhook"을 클릭하고 웹훅을 구성하세요. 모니터링할 대상 저장소와 웹훅 URL `https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training`을 설정하세요.
이걸로 끝입니다! 이제 대상 저장소를 업데이트하면 웹훅을 트리거할 수 있습니다. 예를 들면, 커밋 푸시가 그 방법이 될 수 있습니다. 웹훅의 Activity 탭에서 트리거된 이벤트를 확인할 수 있습니다. 이제 작동하는 구성이 있으므로 테스트하고 빠르게 반복할 수 있습니다. 코드를 수정하고 서버를 다시 시작하면 공개 URL이 변경될 수 있습니다. 필요한 경우 Hub에서 웹훅 구성을 업데이트하세요. ## Space에 배포하기[[deploy-to-a-space]] 이제 작동하는 웹훅 서버가 마련되었으므로, 다음 목표는 이를 Space에 배포하는 것입니다. https://huggingface.co/new-space 에 가서 Space를 생성합니다. 이름을 지정하고, Gradio SDK를 선택한 다음 "Create Space"를 클릭합니다. 코드를 `app.py` 파일로 Space에 업로드합니다. Space가 자동으로 시작됩니다! Space에 대한 자세한 내용은 이 [가이드](https://huggingface.co/docs/hub/spaces-overview)를 참조하세요. 웹훅 서버가 이제 공개 Space에서 실행 중입니다. 대부분의 경우 비밀번호로 보안을 설정하고 싶을 것입니다. Space 설정 > "Repository secrets" 섹션 > "Add a secret" 로 이동합니다. `WEBHOOK_SECRET` 환경 변수에 원하는 값을 설정합니다. [Webhooks 설정](https://huggingface.co/settings/webhooks)으로 돌아가서 웹훅 구성에 비밀번호를 설정합니다. 이제 올바른 비밀번호가 있는 요청만 서버에서 허용됩니다. 이게 전부입니다! Space가 이제 Hub의 웹훅을 수신할 준비가 되었습니다. 무료 하드웨어인 'cpu-basic'에서 Space를 실행 시, 48시간 동안 비활성화되면 종료된다는 점을 유념하세요. 영구적인 Space가 필요한 경우 [업그레이드된 하드웨어](https://huggingface.co/docs/hub/spaces-gpus#hardware-specs)를 설정해야 합니다. ## 고급 사용법[[advanced-usage]] 위의 가이드에서는 [`WebhooksServer`]를 설정하는 가장 빠른 방법에 대해 설명했습니다. 이 섹션에서는 이를 더욱 사용자 정의하는 방법을 살펴보겠습니다. ### 다중 엔드포인트[[multiple-endpoints]] 동일한 서버에 여러 엔드포인트를 등록할 수 있습니다. 예를 들어, 하나의 엔드포인트는 학습 작업을 트리거하고 다른 엔드포인트는 모델 평가를 트리거하도록 할 수 있습니다. 이를 위해 여러 개의 `@webhook_endpoint` 데코레이터를 추가하면 됩니다: ```python # app.py from huggingface_hub import webhook_endpoint, WebhookPayload @webhook_endpoint async def trigger_training(payload: WebhookPayload) -> None: if payload.repo.type == "dataset" and payload.event.action == "update": # 데이터 세트가 업데이트되면 학습 작업을 트리거합니다. ... @webhook_endpoint async def trigger_evaluation(payload: WebhookPayload) -> None: if payload.repo.type == "model" and payload.event.action == "update": # 모델이 업데이트되면 평가 작업을 트리거합니다. ... ``` 이렇게 하면 두 개의 엔드포인트가 생성됩니다: ```text (...) Webhooks are correctly setup and ready to use: - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_training - POST https://1fadb0f52d8bf825fc.gradio.live/webhooks/trigger_evaluation ``` ### 사용자 정의 서버[[custom-server]] 더 많은 유연성을 얻기 위해 [`WebhooksServer`] 객체를 직접 생성할 수도 있습니다. 이것은 서버의 랜딩 페이지를 사용자 정의하고자 할 때 유용합니다. 기본 페이지를 덮어쓸 [Gradio UI](https://gradio.app/docs/#blocks)를 전달하여 이를 수행할 수 있습니다. 예를 들어, 사용자를 위한 지침을 추가하거나 웹훅을 수동으로 트리거하는 양식을 추가할 수 있습니다. [`WebhooksServer`]를 생성할 때, [`~WebhooksServer.add_webhook`] 데코레이터를 사용하여 새로운 웹훅을 등록할 수 있습니다. 전체 예제는 다음과 같습니다: ```python import gradio as gr from fastapi import Request from huggingface_hub import WebhooksServer, WebhookPayload # 1. UI 정의 with gr.Blocks() as ui: ... # 2. 사용자 정의 UI와 시크릿으로 WebhooksServer 생성 app = WebhooksServer(ui=ui, webhook_secret="my_secret_key") # 3. 명시적 이름으로 웹훅 등록 @app.add_webhook("/say_hello") async def hello(payload: WebhookPayload): return {"message": "hello"} # 4. 암시적 이름으로 웹훅 등록 @app.add_webhook async def goodbye(payload: WebhookPayload): return {"message": "goodbye"} # 5. 서버 시작 (선택 사항) app.run() ``` 1. Gradio 블록을 사용하여 사용자 정의 UI를 정의합니다. 이 UI는 서버의 랜딩 페이지에 표시됩니다. 2. 사용자 정의 UI와 시크릿으로 [`WebhooksServer`] 객체를 생성합니다. 시크릿은 선택 사항이며 `WEBHOOK_SECRET` 환경 변수로 설정할 수 있습니다. 3. 명시적 이름으로 웹훅을 등록합니다. 이렇게 하면 `/webhooks/say_hello` 엔드포인트가 생성됩니다. 4. 암시적 이름으로 웹훅을 등록합니다. 이렇게 하면 `/webhooks/goodbye` 엔드포인트가 생성됩니다. 5. 서버를 시작합니다. 이것은 선택 사항이며 스크립트 끝에서 자동으로 서버가 시작됩니다. huggingface_hub-1.1.5/docs/source/ko/index.md000066400000000000000000000103711510763414300211230ustar00rootroot00000000000000 # 🤗 Hub 클라이언트 라이브러리 [[hub-client-library]] `huggingface_hub` 라이브러리는 [Hugging Face Hub](https://hf.co)와 상호작용할 수 있게 해줍니다. Hugging Face Hub는 창작자와 협업자를 위한 머신러닝 플랫폼입니다. 여러분의 프로젝트에 적합한 사전 훈련된 모델과 데이터셋을 발견하거나, Hub에 호스팅된 수백 개의 머신러닝 앱들을 사용해보세요. 또한, 여러분이 만든 모델과 데이터셋을 커뮤니티와 공유할 수도 있습니다. `huggingface_hub` 라이브러리는 파이썬으로 이 모든 것을 간단하게 할 수 있는 방법을 제공합니다. `huggingface_hub` 라이브러리를 사용하기 위한 [빠른 시작 가이드](quick-start)를 읽어보세요. Hub에서 파일을 다운로드하거나, 레포지토리를 생성하거나, 파일을 업로드하는 방법을 배울 수 있습니다. 계속 읽어보면, 🤗 Hub에서 여러분의 레포지토리를 어떻게 관리하고, 토론에 어떻게 참여하고, 추론 API에 어떻게 접근하는지 알아볼 수 있습니다.
How-to 가이드

특정 목표를 달성하는 데 도움이 되는 실용적인 가이드입니다. huggingface_hub로 실제 문제를 해결하는 방법을 배우려면 이 가이드들을 살펴보세요.
라이브러리 레퍼런스

huggingface_hub의 클래스와 메소드에 대한 완전하고 기술적인 설명입니다.
개념 가이드

huggingface_hub의 철학을 더 잘 이해하기 위한 고수준의 설명입니다.
## 기여하기 [[contribute]] `huggingface_hub`에 대한 모든 기여를 환영하며, 소중히 생각합니다! 🤗 코드에서 기존의 이슈를 추가하거나 수정하는 것 외에도, 문서를 정확하고 최신으로 유지하도록 개선하거나, 이슈에 대한 질문에 답하거나, 라이브러리를 개선할 수 있다고 생각하는 새로운 기능을 요청하는 것도 커뮤니티에 도움이 됩니다. 새로운 이슈나 기능 요청을 제출하는 방법, PR을 제출하는 방법, 기여한 내용을 테스트하여 모든 것이 예상대로 작동하는지 확인하는 방법 등에 대해 더 알아보려면 [기여 가이드](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md)를 살펴보세요. 기여자들은 또한 모든 사람들을 위해 포괄적이고 환영받는 협업 공간을 만들기 위해 우리의 [행동 강령](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md)을 준수해야 합니다. huggingface_hub-1.1.5/docs/source/ko/installation.md000066400000000000000000000167521510763414300225260ustar00rootroot00000000000000 # 설치 방법 [[installation]] 시작하기 전에 적절한 패키지를 설치하여 환경을 설정해야 합니다. `huggingface_hub`는 **Python 3.9+**에서 테스트되었습니다. ## pip로 설치하기 [[install-with-pip]] [가상 환경](https://docs.python.org/3/library/venv.html)에서 `huggingface_hub`를 설치하는 것을 적극 권장합니다. 파이썬 가상 환경에 익숙하지 않다면 이 [가이드](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)를 참고하세요. 가상 환경을 사용하면 여러 프로젝트를 더 쉽게 관리하고 의존성 간의 호환성 문제를 피할 수 있습니다. 프로젝트 디렉토리에 가상 환경을 생성하는 것으로 시작하세요: ```bash python -m venv .env ``` 가상환경을 활성화하려면 Linux 및 macOS의 경우: ```bash source .env/bin/activate ``` Windows의 경우: ```bash .env/Scripts/activate ``` [PyPi 레지스트리](https://pypi.org/project/huggingface-hub/)에서 `huggingface_hub`를 설치할 준비가 되었습니다: ```bash pip install --upgrade huggingface_hub ``` 완료되면 [설치 확인](#check-installation)이 올바르게 작동하는지 확인합니다. ### 선택 의존성 설치 [[install-optional-dependencies]] `huggingface_hub`의 일부 의존성은 `huggingface_hub`의 핵심 기능을 실행하는 데 필요하지 않으므로 [선택적](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies)입니다. 설치가 되어있지 않다면 `huggingface_hub`의 추가적인 기능을 사용하지 못할 수 있습니다. 선택적 의존성은 `pip`을 통해 설치할 수 있습니다: ```bash # PyTorch와 CLI와 관련된 기능에 대한 의존성을 모두 설치합니다. pip install 'huggingface_hub[cli,torch]' ``` 다음은 `huggingface_hub`의 선택 의존성 목록입니다: - `cli`: 보다 편리한 `huggingface_hub`의 CLI 인터페이스입니다. - `fastai`, `torch`: 프레임워크별 기능을 실행하려면 필요합니다. - `dev`: 라이브러리에 기여하고 싶다면 필요합니다. 테스트 실행을 위한 `testing`, 타입 검사기 실행을 위한 `typing`, 린터 실행을 위한 `quality`가 포함됩니다. ### 소스에서 설치 [[install-from-source]] 경우에 따라 소스에서 직접 `huggingface_hub`를 설치하는 게 더 나을수도 있습니다. 이렇게 하면 최신 릴리스 버전이 아닌 최신 `main` 버전을 사용할 수 있습니다. `main` 버전은 마지막 공식 릴리스 이후 버그가 수정되었지만 아직 새 릴리스가 출시되지 않은 경우와 같이 최신 개발 사항을 들고오는 데 유용합니다. 동시에 `main` 버전은 항상 안정적일 수 없다는 뜻이기도 합니다. 저희는 `main` 버전을 계속 운영하기 위해 노력하고 있으며, 대부분의 문제는 보통 몇 시간 또는 하루 이내에 해결됩니다. 문제가 발생하면 이슈를 열어주시면 더 빨리 해결할 수 있어요! ```bash pip install git+https://github.com/huggingface/huggingface_hub ``` 소스에서 설치할 때 특정 브랜치를 지정할 수도 있습니다. 아직 병합되지 않은 새로운 기능이나 새로운 버그 수정을 테스트하려는 경우에 유용합니다: ```bash pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch ``` 완료되면 [설치 확인](#check-installation)을 통해 올바르게 작동하는지 확인하세요. ### 편집 가능한 설치 [[editable-install]] 소스에서 설치하면 [편집 가능한 설치](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs)를 설정할 수 있습니다. 이런 고급 설치는 `huggingface_hub`에 기여하고 코드의 변경 사항을 테스트해야 하는 경우에 쓰입니다. 컴퓨터에 `huggingface_hub`의 로컬 복사본을 클론해둬야 합니다. ```bash # 먼저 로컬에 리포지토리를 복제하세요. git clone https://github.com/huggingface/huggingface_hub.git # 그런 다음 -e 플래그를 사용하여 설치하세요. cd huggingface_hub pip install -e . ``` 이렇게 클론한 레포지토리 폴더와 Python 경로를 연결합니다. 이제 Python은 일반적인 라이브러리 경로 외에도 복제된 폴더 내부를 찾습니다. 예를 들어 파이썬 패키지가 일반적으로 `./.venv/lib/python3.13/site-packages/`에 설치되어 있다면, Python은 복제된 폴더 `./huggingface_hub/`도 검색하게 됩니다. ## conda로 설치하기 [[install-with-conda]] 이미 익숙하다면 [conda-forge 채널](https://anaconda.org/conda-forge/huggingface_hub)를 통해 `huggingface_hub`를 설치할 수도 있습니다: ```bash conda install -c conda-forge huggingface_hub ``` 완료되면 [설치 확인](#check-installation)을 통해 올바르게 작동하는지 확인하세요. ## 설치 확인 [[check-installation]] 설치가 완료되면 다음 명령을 실행하여 `huggingface_hub`가 제대로 작동하는지 확인하세요: ```bash python -c "from huggingface_hub import model_info; print(model_info('gpt2'))" ``` 이 명령은 Hub에서 [gpt2](https://huggingface.co/gpt2) 모델에 대한 정보를 가져옵니다. 출력은 다음과 같아야 합니다: ```text Model Name: gpt2 Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space'] Task: text-generation ``` ## Windows 제한 사항 [[windows-limitations]] 좋은 ML을 어디서나 사용할 수 있게 하자는 목표 아래, `huggingface_hub`를 크로스 플랫폼 라이브러리로 만들었으며, 특히 유닉스 기반과 Windows 시스템 모두에서 잘 작동하도록 했습니다. 그럼에도 `huggingface_hub`를 Windows에서 실행할 때 몇 가지 제한이 있습니다. 다음은 알려진 문제의 전체 목록입니다. 문서화되지 않은 문제가 발생하면 [GitHub에 이슈](https://github.com/huggingface/huggingface_hub/issues/new/choose)를 열어서 알려주시기 바랍니다. - `huggingface_hub`의 캐시 시스템은 Hub에서 다운로드한 파일을 효율적으로 캐시하기 위해 심볼릭 링크에 의존합니다. Windows에서는 개발자 모드를 활성화하거나 관리자 권한으로 스크립트를 실행해야 심볼릭 링크를 활성화할 수 있습니다. 활성화하지 않으면 캐시 시스템이 계속 작동하지만 최적화되지 않은 방식으로 작동합니다. 자세한 내용은 [캐시 제한](./guides/manage-cache#limitations) 섹션을 참조하세요. - Hub의 파일 경로에는 특수 문자를 사용할 수 있습니다(예: `"path/to?/my/file"`). 드문 경우이길 바라지만, Windows는 [특수 문자](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names)에 대한 제한이 더 엄격하기 때문에 해당 파일을 다운로드할 수 없습니다. 실수라고 생각되면 레포지토리 소유자에게 문의하시거나 해결책을 찾기 위해 저희에게 연락해 주세요. ## 다음 단계 [[next-steps]] 컴퓨터에 `huggingface_hub`가 제대로 설치되면 [환경 변수를 설정](package_reference/environment_variables)하거나 [가이드 중 하나를 골라](guides/overview) 시작할 수 있습니다. huggingface_hub-1.1.5/docs/source/ko/package_reference/000077500000000000000000000000001510763414300231015ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/ko/package_reference/cache.md000066400000000000000000000034301510763414300244660ustar00rootroot00000000000000 # 캐시 시스템 참조[[cache-system-reference]] 버전 0.8.0에서의 업데이트로, 캐시 시스템은 Hub에 의존하는 라이브러리 전체에서 공유되는 중앙 캐시 시스템으로 발전하였습니다. Hugging Face 캐싱에 대한 자세한 설명은 [캐시 시스템 가이드](../guides/manage-cache)를 참조하세요. ## 도우미 함수[[helpers]] ### try_to_load_from_cache[[huggingface_hub.try_to_load_from_cache]] [[autodoc]] huggingface_hub.try_to_load_from_cache ### cached_assets_path[[huggingface_hub.cached_assets_path]] [[autodoc]] huggingface_hub.cached_assets_path ### scan_cache_dir[[huggingface_hub.scan_cache_dir]] [[autodoc]] huggingface_hub.scan_cache_dir ## 데이터 구조[[data-structures]] 모든 구조체는 [`scan_cache_dir`]에 의해 생성되고 반환되며, 불변(immutable)입니다. ### HFCacheInfo[[huggingface_hub.HFCacheInfo]] [[autodoc]] huggingface_hub.HFCacheInfo ### CachedRepoInfo[[huggingface_hub.CachedRepoInfo]] [[autodoc]] huggingface_hub.CachedRepoInfo - size_on_disk_str - refs ### CachedRevisionInfo[[huggingface_hub.CachedRevisionInfo]] [[autodoc]] huggingface_hub.CachedRevisionInfo - size_on_disk_str - nb_files ### CachedFileInfo[[huggingface_hub.CachedFileInfo]] [[autodoc]] huggingface_hub.CachedFileInfo - size_on_disk_str ### DeleteCacheStrategy[[huggingface_hub.DeleteCacheStrategy]] [[autodoc]] huggingface_hub.DeleteCacheStrategy - expected_freed_size_str ## 예외[[exceptions]] ### CorruptedCacheException[[huggingface_hub.CorruptedCacheException]] [[autodoc]] huggingface_hub.CorruptedCacheException huggingface_hub-1.1.5/docs/source/ko/package_reference/cards.md000066400000000000000000000044601510763414300245230ustar00rootroot00000000000000# 리포지토리 카드[[repository-cards]] huggingface_hub 라이브러리는 모델/데이터 세트 카드를 생성, 공유 및 업데이트하기 위한 Python 인터페이스를 제공합니다. Hub의 모델 카드가 무엇이며 내부적으로 어떻게 작동하는지 더 깊이 있게 알아보려면 [전용 문서 페이지](https://huggingface.co/docs/hub/models-cards)를 방문하세요. 또한 이러한 유틸리티를 자신의 프로젝트에서 어떻게 사용할 수 있는지 감을 잡기 위해 [모델 카드 가이드](../how-to-model-cards)를 확인할 수 있습니다. ## 리포지토리 카드[[huggingface_hub.RepoCard]] `RepoCard` 객체는 [`ModelCard`], [`DatasetCard`] 및 `SpaceCard`의 상위 클래스입니다. [[autodoc]] huggingface_hub.repocard.RepoCard - __init__ - all ## 카드 데이터[[huggingface_hub.CardData]] [`CardData`] 객체는 [`ModelCardData`]와 [`DatasetCardData`]의 상위 클래스입니다. [[autodoc]] huggingface_hub.repocard_data.CardData ## 모델 카드[[model-cards]] ### ModelCard[[huggingface_hub.ModelCard]] [[autodoc]] ModelCard ### ModelCardData[[huggingface_hub.ModelCardData]] [[autodoc]] ModelCardData ## 데이터 세트 카드[[cards#dataset-cards]] ML 커뮤니티에서는 데이터 세트 카드를 데이터 카드라고도 합니다. ### DatasetCard[[huggingface_hub.DatasetCard]] [[autodoc]] DatasetCard ### DatasetCardData[[huggingface_hub.DatasetCardData]] [[autodoc]] DatasetCardData ## 공간 카드[[space-cards]] ### SpaceCard[[huggingface_hub.SpaceCardData]] [[autodoc]] SpaceCard ### SpaceCardData[[huggingface_hub.SpaceCardData]] [[autodoc]] SpaceCardData ## 유틸리티[[utilities]] ### EvalResult[[huggingface_hub.EvalResult]] [[autodoc]] EvalResult ### model_index_to_eval_results[[huggingface_hub.repocard_data.model_index_to_eval_results]] [[autodoc]] huggingface_hub.repocard_data.model_index_to_eval_results ### eval_results_to_model_index[[huggingface_hub.repocard_data.eval_results_to_model_index]] [[autodoc]] huggingface_hub.repocard_data.eval_results_to_model_index ### metadata_eval_result[[huggingface_hub.metadata_eval_result]] [[autodoc]] huggingface_hub.repocard.metadata_eval_result ### metadata_update[[huggingface_hub.metadata_update]] [[autodoc]] huggingface_hub.repocard.metadata_updatehuggingface_hub-1.1.5/docs/source/ko/package_reference/collections.md000066400000000000000000000015421510763414300257430ustar00rootroot00000000000000 # 컬렉션 관리[[managing-collections]] Hub에서 Space를 관리하는 메소드에 대한 자세한 설명은 [`HfApi`] 페이지를 확인하세요. - 컬렉션 내용 가져오기: [`get_collection`] - 새로운 컬렉션 생성: [`create_collection`] - 컬렉션 업데이트: [`update_collection_metadata`] - 컬렉션 삭제: [`delete_collection`] - 컬렉션에 항목 추가: [`add_collection_item`] - 컬렉션의 항목 업데이트: [`update_collection_item`] - 컬렉션에서 항목 제거: [`delete_collection_item`] ### Collection[[huggingface_hub.Collection]] [[autodoc]] Collection ### CollectionItem[[huggingface_hub.CollectionItem]] [[autodoc]] CollectionItem huggingface_hub-1.1.5/docs/source/ko/package_reference/community.md000066400000000000000000000017251510763414300254540ustar00rootroot00000000000000 # Discussions 및 Pull Requests를 이용하여 상호작용하기[[interacting-with-discussions-and-pull-requests]] Hub에서 Discussions 및 Pull Requests를 이용하여 상호 작용할 수 있는 방법에 대해 참조하고자 한다면 [`HfApi`] 문서 페이지를 확인하세요. - [`get_repo_discussions`] - [`get_discussion_details`] - [`create_discussion`] - [`create_pull_request`] - [`rename_discussion`] - [`comment_discussion`] - [`edit_discussion_comment`] - [`change_discussion_status`] - [`merge_pull_request`] ## 데이터 구조[[huggingface_hub.Discussion]] [[autodoc]] Discussion [[autodoc]] DiscussionWithDetails [[autodoc]] DiscussionEvent [[autodoc]] DiscussionComment [[autodoc]] DiscussionStatusChange [[autodoc]] DiscussionCommit [[autodoc]] DiscussionTitleChange huggingface_hub-1.1.5/docs/source/ko/package_reference/environment_variables.md000066400000000000000000000277741510763414300300400ustar00rootroot00000000000000 # 환경 변수[[environment-variables]] `huggingface_hub`는 환경 변수를 사용해 설정할 수 있습니다. 환경 변수에 대해 잘 알지 못하다면 그에 대한 문서인 [macOS and Linux](https://linuxize.com/post/how-to-set-and-list-environment-variables-in-linux/)와 [Windows](https://phoenixnap.com/kb/windows-set-environment-variable)를 참고하세요. 이 문서에서는 `huggingface_hub`와 관련된 모든 환경 변수와 그 의미에 대해 안내합니다. ## 일반적인 변수[[generic]] ### HF_INFERENCE_ENDPOINT[[hfinferenceendpoint]] 추론 API 기본 URL을 구성합니다. 조직에서 추론 API를 직접 가리키는 것이 아니라 API 게이트웨이를 가리키는 경우 이 변수를 설정할 수 있습니다. 기본값은 `"https://api-inference.huggingface.co"`입니다. ### HF_HOME[[hfhome]] `huggingface_hub`가 어디에 데이터를 로컬로 저장할 지 위치를 구성합니다. 특히 토큰과 캐시가 이 폴더에 저장됩니다. [XDG_CACHE_HOME](#xdgcachehome)이 설정되어 있지 않다면, 기본값은 `"~/.cache/huggingface"`입니다. ### HF_HUB_CACHE[[hfhubcache]] Hub의 리포지토리가 로컬로 캐시될 위치(모델, 데이터세트 및 스페이스)를 구성합니다. 기본값은 `"$HF_HOME/hub"` (예로 들면, 기본 설정은 `"~/.cache/huggingface/hub"`)입니다. ### HF_ASSETS_CACHE[[hfassetscache]] 다운스트림 라이브러리에서 생성된 [assets](../guides/manage-cache#caching-assets)가 로컬로 캐시되는 위치를 구성합니다. 이 assets은 전처리된 데이터, GitHub에서 다운로드한 파일, 로그, ... 등이 될 수 있습니다. 기본값은 `"$HF_HOME/assets"` (예로 들면, 기본 설정은 `"~/.cache/huggingface/assets"`)입니다. ### HF_TOKEN[[hftoken]] Hub에 인증하기 위한 사용자 액세스 토큰을 구성합니다. 이 값을 설정하면 머신에 저장된 토큰을 덮어씁니다(`$HF_TOKEN_PATH`, 또는 `$HF_TOKEN_PATH`가 설정되지 않은 경우 `"$HF_HOME/token"`에 저장됨). 인증에 대한 자세한 내용은 [이 섹션](../quick-start#인증)을 참조하세요. ### HF_TOKEN_PATH[[hftokenpath]] `huggingface_hub`가 사용자 액세스 토큰(User Access Token)을 저장할 위치를 구성합니다. 기본값은 `"$HF_HOME/token"`(예로 들면, 기본 설정은 `~/.cache/huggingface/token`)입니다. ### HF_HUB_VERBOSITY[[hfhubverbosity]] `huggingface_hub`의 로거(logger)의 상세도 수준(verbosity level)을 설정합니다. 다음 중 하나여야 합니다. `{"debug", "info", "warning", "error", "critical"}` 중 하나여야 합니다. 기본값은 `"warning"`입니다. 더 자세한 정보를 알아보고 싶다면, [logging reference](../package_reference/utilities#huggingface_hub.utils.logging.get_verbosity)를 살펴보세요. ### HF_HUB_ETAG_TIMEOUT[[hfhubetagtimeout]] 파일을 다운로드하기 전에 리포지토리에서 최신 메타데이터를 가져올 때 서버 응답을 기다리는 시간(초)을 정의하는 정수 값입니다. 요청 시간이 초과되면 `huggingface_hub`는 기본적으로 로컬에 캐시된 파일을 사용합니다. 값을 낮게 설정하면 이미 파일을 캐시한 연결 속도가 느린 컴퓨터의 워크플로 속도가 빨라집니다. 값이 클수록 더 많은 경우에서 메타데이터 호출이 성공할 수 있습니다. 기본값은 10초입니다. ### HF_HUB_DOWNLOAD_TIMEOUT[[hfhubdownloadtimeout]] 파일을 다운로드할 때 서버 응답을 기다리는 시간(초)을 정의하는 정수 값입니다. 요청 시간이 초과되면 TimeoutError가 발생합니다. 연결 속도가 느린 컴퓨터에서는 값을 높게 설정하는 것이 좋습니다. 값이 작을수록 네트워크가 완전히 중단된 경우에 프로세스가 더 빨리 실패합니다. 기본값은 10초입니다. ## 불리언 값[[boolean-values]] 다음 환경 변수는 불리언 값을 요구합니다. 변수는 값이 `{"1", "ON", "YES", "TRUE"}`(대소문자 구분 없음) 중 하나이면 `True`로 간주합니다. 다른 값(또는 정의되지 않음)은 `False`로 간주됩니다. ### HF_HUB_OFFLINE[[hfhuboffline]] 이 옵션을 설정하면 Hugging Face Hub에 HTTP 호출이 이루어지지 않습니다. 파일을 다운로드하려고 하면 캐시된 파일만 액세스됩니다. 캐시 파일이 감지되지 않으면 오류를 발생합니다. 네트워크 속도가 느리고 파일의 최신 버전이 중요하지 않은 경우에 유용합니다. 환경 변수로 `HF_HUB_OFFLINE=1`이 설정되어 있고 [`HfApi`]의 메소드를 호출하면 [`~huggingface_hub.utils.OfflineModeIsEnabled`] 예외가 발생합니다. **참고:** 최신 버전의 파일이 캐시되어 있더라도 `hf_hub_download`를 호출하면 새 버전을 사용할 수 없는지 확인하기 위해 HTTP 요청이 발생합니다. `HF_HUB_OFFLINE=1`을 설정하면 이 호출을 건너뛰어 로딩 시간이 빨라집니다. ### HF_HUB_DISABLE_IMPLICIT_TOKEN[[hfhubdisableimplicittoken]] Hub에 대한 모든 요청이 반드시 인증을 필요로 하는 것은 아닙니다. 예를 들어 `"gpt2"` 모델에 대한 세부 정보를 요청하는 경우에는 인증이 필요하지 않습니다. 그러나 사용자가 [로그인](../package_reference/login) 상태인 경우, 기본 동작은 사용자 경험을 편하게 하기 위해 비공개 또는 게이트 리포지토리에 액세스할 때 항상 토큰을 전송하는 것(HTTP 401 권한 없음이 표시되지 않음)입니다. 개인 정보 보호를 위해 `HF_HUB_DISABLE_IMPLICIT_TOKEN=1`로 설정하여 이 동작을 비활성화할 수 있습니다. 이 경우 토큰은 "쓰기 권한" 호출(예: 커밋 생성)에만 전송됩니다. **참고:** 토큰을 항상 전송하는 것을 비활성화하면 이상한 부작용이 발생할 수 있습니다. 예를 들어 Hub에 모든 모델을 나열하려는 경우 당신의 비공개 모델은 나열되지 않습니다. 사용자 스크립트에 명시적으로 `token=True` 인수를 전달해야 합니다. ### HF_HUB_DISABLE_PROGRESS_BARS[[hfhubdisableprogressbars]] 시간이 오래 걸리는 작업의 경우 `huggingface_hub`는 기본적으로 진행률 표시줄을 표시합니다(tqdm 사용). 모든 진행률 표시줄을 한 번에 비활성화하려면 `HF_HUB_DISABLE_PROGRESS_BARS=1`으로 설정하면 됩니다. ### HF_HUB_DISABLE_SYMLINKS_WARNING[[hfhubdisablesymlinkswarning]] Windows 머신을 사용하는 경우 개발자 모드를 활성화하거나 관리자 모드에서 `huggingface_hub`를 관리자 모드로 실행하는 것이 좋습니다. 그렇지 않은 경우 `huggingface_hub`가 캐시 시스템에 심볼릭 링크를 생성할 수 없습니다. 모든 스크립트를 실행할 수 있지만 일부 대용량 파일이 하드 드라이브에 중복될 수 있으므로 사용자 경힘이 저하될 수 있습니다. 이 동작을 경고하기 위해 경고 메시지가 나타납니다. `HF_HUB_DISABLE_SYMLINKS_WARNING=1`로 설정하면 이 경고를 비활성화할 수 있습니다. 자세한 내용은 [캐시 제한](../guides/manage-cache#limitations)을 참조하세요. ### HF_HUB_DISABLE_EXPERIMENTAL_WARNING[[hfhubdisableexperimentalwarning]] `huggingface_hub`의 일부 기능은 실험 단계입니다. 즉, 사용은 가능하지만 향후 유지될 것이라고 보장할 수는 없습니다. 특히 이러한 기능의 API나 동작은 지원 중단 없이 업데이트될 수 있습니다. 실험적 기능을 사용할 때는 이에 대한 경고를 위해 경고 메시지가 나타납니다. 실험적 기능을 사용하여 잠재적인 문제를 디버깅하는 것이 편하다면 `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1`으로 설정하여 경고를 비활성화할 수 있습니다. 실험적인 기능을 사용 중이라면 알려주세요! 여러분의 피드백은 기능을 설계하고 개선하는 데 도움이 됩니다. ### HF_HUB_DISABLE_TELEMETRY[[hfhubdisabletelemetry]] 기본적으로 일부 데이터는 사용량을 모니터링하고 문제를 디버그하며 기능의 우선순위를 정하는 데 도움을 주기 위해 HF 라이브러리(`transformers`, `datasets`, `gradio`,...)에서 수집합니다. 각 라이브러리는 자체 정책(즉, 모니터링할 사용량)을 정의하지만 핵심 구현은 `huggingface_hub`에서 이루어집니다([`send_telemetry`] 참조). 환경 변수로 `HF_HUB_DISABLE_TELEMETRY=1`을 설정하여 원격 측정을 전역적으로 비활성화할 수 있습니다. ### HF_HUB_ENABLE_HF_TRANSFER[[hfhubenablehftransfer]] Hub에서 `hf_transfer`를 사용하여 더 빠르게 업로드 및 다운로드하려면 `True`로 설정하세요. 기본적으로 `huggingface_hub`는 파이썬 기반 `requests.get` 및 `requests.post` 함수를 사용합니다. 이 함수들은 안정적이고 다용도로 사용할 수 있지만 대역폭이 높은 머신에서는 가장 효율적인 선택이 아닐 수 있습니다. [`hf_transfer`](https://github.com/huggingface/hf_transfer)는 대용량 파일을 작은 부분으로 분할하여 사용 대역폭을 최대화하고 여러 스레드를 사용하여 동시에 전송함으로써 대역폭을 최대화하기 위해 개발된 Rust 기반 패키지입니다. 이 접근 방식은 전송 속도를 거의 두 배로 높일 수 있습니다. `hf_transfer`를 사용하려면: 1. `huggingface_hub`를 설치할 때 `hf_transfer`를 추가로 지정합니다. (예시: `pip install huggingface_hub[hf_transfer]`). 2. 환경 변수로 `HF_HUB_ENABLE_HF_TRANSFER=1`을 설정합니다. `hf_transfer`를 사용하면 특정 제한 사항이 있다는 점에 유의하세요. 순수 파이썬 기반이 아니므로 오류 디버깅이 어려울 수 있습니다. 또한 `hf_transfer`에는 다운로드 재개 및 프록시와 같은 몇 가지 사용자 친화적인 기능이 없습니다. 이런 부족한 부분은 Rust 로직의 단순성과 속도를 유지하기 위해 의도한 것입니다. 이런 이유들로, `hf_transfer`는 `huggingface_hub`에서 기본적으로 활성화되지 않습니다. ## 사용되지 않는 환경 변수[[deprecated-environment-variables]] Hugging Face 생태계의 모든 환경 변수를 표준화하기 위해 일부 변수는 사용되지 않는 것으로 표시되었습니다. 해당 변수는 여전히 작동하지만 더 이상 대체한 변수보다 우선하지 않습니다. 다음 표에는 사용되지 않는 변수와 해당 대체 변수가 간략하게 설명되어 있습니다: | 사용되지 않는 변수 | 대체 변수 | | --------------------------- | ------------------ | | `HUGGINGFACE_HUB_CACHE` | `HF_HUB_CACHE` | | `HUGGINGFACE_ASSETS_CACHE` | `HF_ASSETS_CACHE` | | `HUGGING_FACE_HUB_TOKEN` | `HF_TOKEN` | | `HUGGINGFACE_HUB_VERBOSITY` | `HF_HUB_VERBOSITY` | ## 외부 도구[[from-external-tools]] 일부 환경 변수는 `huggingface_hub`에만 특정되지는 않지만 설정 시 함께 고려됩니다. ### DO_NOT_TRACK[[donottrack]] 불리언 값입니다. `hf_hub_disable_telemetry`에 해당합니다. True로 설정하면 Hugging Face Python 생태계(`transformers`, `diffusers`, `gradio` 등)에서 원격 측정이 전역적으로 비활성화됩니다. 자세한 내용은 https://consoledonottrack.com/ 을 참조하세요. ### NO_COLOR[[nocolor]] 불리언 값입니다. 이 값을 설정하면 `hf` 도구는 ANSI 색상을 출력하지 않습니다. [no-color.org](https://no-color.org/)를 참조하세요. ### XDG_CACHE_HOME[[xdgcachehome]] `HF_HOME`이 설정되지 않은 경우에만 사용합니다! 이것은 Linux 시스템에서 [사용자별 비필수(캐시된) 데이터](https://wiki.archlinux.org/title/XDG_Base_Directory)가 쓰여져야 하는 위치를 구성하는 기본 방법입니다. `HF_HOME`이 설정되지 않은 경우 기본 홈은 `"~/.cache/huggingface"`대신 `"$XDG_CACHE_HOME/huggingface"`가 됩니다. huggingface_hub-1.1.5/docs/source/ko/package_reference/file_download.md000066400000000000000000000025351510763414300262360ustar00rootroot00000000000000 # 파일 다운로드 하기[[downloading-files]] ## 단일 파일 다운로드하기[[download-a-single-file]] ### hf_hub_download[[huggingface_hub.hf_hub_download]] [[autodoc]]huggingface_hub.hf_hub_download ### hf_hub_url[[huggingface_hub.hf_hub_url]] [[autodoc]]huggingface_hub.hf_hub_url ## 리포지토리의 스냅샷 다운로드하기[[huggingface_hub.snapshot_download]] [[autodoc]]huggingface_hub.snapshot_download ## 파일에 대한 메타데이터 가져오기[[get-metadata-about-a-file]] ### get_hf_file_metadata[[huggingface_hub.get_hf_file_metadata]] [[autodoc]]huggingface_hub.get_hf_file_metadata ### HfFileMetadata[[huggingface_hub.HfFileMetadata]] [[autodoc]]huggingface_hub.HfFileMetadata ## 캐싱[[caching]] 위에 나열된 메소드들은 파일을 재다운로드하지 않도록 하는 캐싱 시스템과 함께 작동하도록 설계되었습니다. v0.8.0에서의 업데이트로, 캐싱 시스템은 Hub를 기반으로 하는 다양한 라이브러리 간의 공유 중앙 캐시 시스템으로 발전했습니다. Hugging Face에서의 캐싱에 대한 자세한 설명은[캐시 시스템 가이드](../guides/manage-cache)를 참조하세요. huggingface_hub-1.1.5/docs/source/ko/package_reference/hf_api.md000066400000000000000000000064021510763414300246530ustar00rootroot00000000000000 # HfApi Client[[hfapi-client]] 아래는 허깅 페이스 Hub의 API를 위한 파이썬 래퍼인 `HfApi` 클래스에 대한 문서입니다. `HfApi`의 모든 메서드는 패키지의 루트에서 직접 접근할 수 있습니다. 두 접근 방식은 아래에서 자세히 설명합니다. 루트 메서드를 사용하는 것이 더 간단하지만 [`HfApi`] 클래스를 사용하면 더 유연하게 사용할 수 있습니다. 특히 모든 HTTP 호출에서 재사용할 토큰을 전달할 수 있습니다. 이 방식은 토큰이 머신에 유지되지 않기 때문에 `hf auth login` 또는 [`login`]를 사용하는 방식과는 다르며, 다른 엔드포인트를 제공하거나 사용자정의 에이전트를 구성할 수도 있습니다. ```python from huggingface_hub import HfApi, list_models # 루트 메서드를 사용하세요. models = list_models() # 또는 HfApi client를 구성하세요. hf_api = HfApi( endpoint="https://huggingface.co", # 비공개 Hub 엔드포인트를 지정할 수 있습니다. token="hf_xxx", # 토큰은 머신에 유지되지 않습니다. ) models = hf_api.list_models() ``` ## HfApi[[huggingface_hub.HfApi]] [[autodoc]] HfApi ## API Dataclasses[[api-dataclasses]] ### AccessRequest[[huggingface_hub.hf_api.AccessRequest]] [[autodoc]] huggingface_hub.hf_api.AccessRequest ### CommitInfo[[huggingface_hub.CommitInfo]] [[autodoc]] huggingface_hub.hf_api.CommitInfo ### DatasetInfo[[huggingface_hub.hf_api.DatasetInfo]] [[autodoc]] huggingface_hub.hf_api.DatasetInfo ### GitRefInfo[[huggingface_hub.GitRefInfo]] [[autodoc]] huggingface_hub.hf_api.GitRefInfo ### GitCommitInfo[[huggingface_hub.GitCommitInfo]] [[autodoc]] huggingface_hub.hf_api.GitCommitInfo ### GitRefs[[huggingface_hub.GitRefs]] [[autodoc]] huggingface_hub.hf_api.GitRefs ### ModelInfo[[huggingface_hub.hf_api.ModelInfo]] [[autodoc]] huggingface_hub.hf_api.ModelInfo ### RepoSibling[[huggingface_hub.hf_api.RepoSibling]] [[autodoc]] huggingface_hub.hf_api.RepoSibling ### RepoFile[[huggingface_hub.hf_api.RepoFile]] [[autodoc]] huggingface_hub.hf_api.RepoFile ### RepoUrl[[huggingface_hub.RepoUrl]] [[autodoc]] huggingface_hub.hf_api.RepoUrl ### SafetensorsRepoMetadata[[huggingface_hub.utils.SafetensorsRepoMetadata]] [[autodoc]] huggingface_hub.utils.SafetensorsRepoMetadata ### SafetensorsFileMetadata[[huggingface_hub.utils.SafetensorsFileMetadata]] [[autodoc]] huggingface_hub.utils.SafetensorsFileMetadata ### SpaceInfo[[huggingface_hub.hf_api.SpaceInfo]] [[autodoc]] huggingface_hub.hf_api.SpaceInfo ### TensorInfo[[huggingface_hub.utils.TensorInfo]] [[autodoc]] huggingface_hub.utils.TensorInfo ### User[[huggingface_hub.User]] [[autodoc]] huggingface_hub.hf_api.User ### UserLikes[[huggingface_hub.UserLikes]] [[autodoc]] huggingface_hub.hf_api.UserLikes ## CommitOperation[[huggingface_hub.CommitOperationAdd]] [`CommitOperation`]에 지원되는 값은 다음과 같습니다: [[autodoc]] CommitOperationAdd [[autodoc]] CommitOperationDelete [[autodoc]] CommitOperationCopy ## CommitScheduler[[huggingface_hub.CommitScheduler]] [[autodoc]] CommitScheduler huggingface_hub-1.1.5/docs/source/ko/package_reference/hf_file_system.md000066400000000000000000000015371510763414300264310ustar00rootroot00000000000000 # 파일 시스템 API[[filesystem-api]] [`HfFileSystem`] 클래스는 [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/)을 기반으로 Hugging Face Hub에 Python 파일 인터페이스를 제공합니다. ## [HfFileSystem](Hf파일시스템) [`HfFileSystem`]은 [`fsspec`](https://filesystem-spec.readthedocs.io/en/latest/)을 기반으로 하므로 제공되는 대부분의 API와 호환됩니다. 자세한 내용은 [가이드](../guides/hf_file_system) 및 fsspec의 [API 레퍼런스](https://filesystem-spec.readthedocs.io/en/latest/api.html#fsspec.spec.AbstractFileSystem)를 확인하세요. [[autodoc]] HfFileSystem - __init__ - resolve_path - ls huggingface_hub-1.1.5/docs/source/ko/package_reference/inference_client.md000066400000000000000000000043671510763414300267310ustar00rootroot00000000000000 # 추론[[inference]] 추론은 학습된 모델을 사용하여 새로운 데이터를 예측하는 과정입니다. 이 과정은 계산량이 많을 수 있기 때문에, 전용 서버에서 실행하는 것이 흥미로운 옵션이 될 수 있습니다. `huggingface_hub` 라이브러리는 호스팅된 모델에 대한 추론을 실행하는 간단한 방법을 제공합니다. 연결할 수 있는 서비스는 여러가지가 있습니다: - [추론 API](https://huggingface.co/docs/api-inference/index): Hugging Face의 인프라에서 가속화된 추론을 무료로 실행할 수 있는 서비스입니다. 이 서비스는 시작하기 위한 빠른 방법이며, 다양한 모델을 테스트하고 AI 제품을 프로토타입화하는 데에도 유용합니다. - [추론 엔드포인트](https://huggingface.co/inference-endpoints): 모델을 쉽게 운영 환경으로 배포할 수 있는 제품입니다. 추론은 여러분이 선택한 클라우드 제공업체의 전용 및 완전히 관리되는 인프라에서 Hugging Face에 의해 실행됩니다. 이러한 서비스는 [`InferenceClient`] 객체를 사용하여 호출할 수 있습니다. 자세한 사용 방법에 대해서는 [이 가이드](../guides/inference)를 참조해주세요. ## 추론 클라이언트[[huggingface_hub.InferenceClient]] [[autodoc]] InferenceClient ## 비동기 추론 클라이언트[[huggingface_hub.AsyncInferenceClient]] 비동기 버전의 클라이언트도 제공되며, 이는 `asyncio`와 `aiohttp`를 기반으로 작동합니다. 이를 사용하려면 `aiohttp`를 직접 설치하거나 `[inference]` 추가 기능을 사용할 수 있습니다: ```sh pip install --upgrade huggingface_hub[inference] # 또는 # pip install aiohttp ``` [[autodoc]] AsyncInferenceClient ## 추론 시간 초과 오류[[huggingface_hub.InferenceTimeoutError]] [[autodoc]] InferenceTimeoutError ## 반환 유형[[return-types]] 대부분의 작업에 대해, 반환 값은 내장된 유형(string, list, image...)을 갖습니다. 보다 복잡한 유형을 위한 목록은 다음과 같습니다. huggingface_hub-1.1.5/docs/source/ko/package_reference/inference_endpoints.md000066400000000000000000000050421510763414300274450ustar00rootroot00000000000000# 추론 엔드포인트 [[inference-endpoints]] Hugging Face가 관리하는 추론 엔드포인트는 우리가 모델을 쉽고 안전하게 배포할 수 있게 해주는 도구입니다. 이러한 추론 엔드포인트는 [Hub](https://huggingface.co/models)에 있는 모델을 기반으로 설계되었습니다. 이 문서는 `huggingface_hub`와 추론 엔드포인트 통합에 관한 참조 페이지이며, 더욱 자세한 정보는 [공식 문서](https://huggingface.co/docs/inference-endpoints/index)를 통해 확인할 수 있습니다. > [!TIP] > 'huggingface_hub'를 사용하여 추론 엔드포인트를 프로그래밍 방식으로 관리하는 방법을 알고 싶다면, [관련 가이드](../guides/inference_endpoints)를 확인해 보세요. 추론 엔드포인트는 API로 쉽게 접근할 수 있습니다. 이 엔드포인트들은 [Swagger](https://api.endpoints.huggingface.cloud/)를 통해 문서화되어 있고, [`InferenceEndpoint`] 클래스는 이 API를 사용해 만든 간단한 래퍼입니다. ## 매소드 [[methods]] 다음과 같은 추론 엔드포인트의 기능이 [`HfApi`]안에 구현되어 있습니다: - [`get_inference_endpoint`]와 [`list_inference_endpoints`]를 사용해 엔드포인트 정보를 조회할 수 있습니다. - [`create_inference_endpoint`], [`update_inference_endpoint`], [`delete_inference_endpoint`]로 엔드포인트를 배포하고 관리할 수 있습니다. - [`pause_inference_endpoint`]와 [`resume_inference_endpoint`]로 엔드포인트를 잠시 멈추거나 다시 시작할 수 있습니다. - [`scale_to_zero_inference_endpoint`]로 엔드포인트의 복제본을 0개로 설정할 수 있습니다. ## InferenceEndpoint [[huggingface_hub.InferenceEndpoint]] 기본 데이터 클래스는 [`InferenceEndpoint`]입니다. 여기에는 구성 및 현재 상태를 가지고 있는 배포된 `InferenceEndpoint`에 대한 정보가 포함되어 있습니다. 배포 후에는 [`InferenceEndpoint.client`]와 [`InferenceEndpoint.async_client`]를 사용해 엔드포인트에서 추론 작업을 할 수 있고, 이때 [`InferenceClient`]와 [`AsyncInferenceClient`] 객체를 반환합니다. [[autodoc]] InferenceEndpoint - from_raw - client - async_client - all ## InferenceEndpointStatus [[huggingface_hub.InferenceEndpointStatus]] [[autodoc]] InferenceEndpointStatus ## InferenceEndpointType [[huggingface_hub.InferenceEndpointType]] [[autodoc]] InferenceEndpointType ## InferenceEndpointError [[huggingface_hub.InferenceEndpointError]] [[autodoc]] InferenceEndpointError huggingface_hub-1.1.5/docs/source/ko/package_reference/inference_types.md000066400000000000000000000257311510763414300266150ustar00rootroot00000000000000 # 추론 타입[[inference-types]] 이 페이지에는 Hugging Face Hub에서 지원하는 타입(예: 데이터 클래스)이 나열되어 있습니다. 각 작업은 JSON 스키마를 사용하여 지정되며, 이러한 스키마에 의해서 타입이 생성됩니다. 이때 Python 요구 사항으로 인해 일부 사용자 정의가 있을 수 있습니다. 각 작업의 JSON 스키마를 확인하려면 [@huggingface.js/tasks](https://github.com/huggingface/huggingface.js/tree/main/packages/tasks/src/tasks)를 확인하세요. 라이브러리에서 이 부분은 아직 개발 중이며, 향후 릴리즈에서 개선될 예정입니다. ## audio_classification[[huggingface_hub.AudioClassificationInput]] [[autodoc]] huggingface_hub.AudioClassificationInput [[autodoc]] huggingface_hub.AudioClassificationOutputElement [[autodoc]] huggingface_hub.AudioClassificationParameters ## audio_to_audio[[huggingface_hub.AudioToAudioInput]] [[autodoc]] huggingface_hub.AudioToAudioInput [[autodoc]] huggingface_hub.AudioToAudioOutputElement ## automatic_speech_recognition[[huggingface_hub.AutomaticSpeechRecognitionGenerationParameters]] [[autodoc]] huggingface_hub.AutomaticSpeechRecognitionGenerationParameters [[autodoc]] huggingface_hub.AutomaticSpeechRecognitionInput [[autodoc]] huggingface_hub.AutomaticSpeechRecognitionOutput [[autodoc]] huggingface_hub.AutomaticSpeechRecognitionOutputChunk [[autodoc]] huggingface_hub.AutomaticSpeechRecognitionParameters ## chat_completion[[huggingface_hub.ChatCompletionInput]] [[autodoc]] huggingface_hub.ChatCompletionInput [[autodoc]] huggingface_hub.ChatCompletionInputFunctionDefinition [[autodoc]] huggingface_hub.ChatCompletionInputFunctionName [[autodoc]] huggingface_hub.ChatCompletionInputJSONSchema [[autodoc]] huggingface_hub.ChatCompletionInputMessage [[autodoc]] huggingface_hub.ChatCompletionInputMessageChunk [[autodoc]] huggingface_hub.ChatCompletionInputResponseFormatJSONObject [[autodoc]] huggingface_hub.ChatCompletionInputResponseFormatJSONSchema [[autodoc]] huggingface_hub.ChatCompletionInputResponseFormatText [[autodoc]] huggingface_hub.ChatCompletionInputStreamOptions [[autodoc]] huggingface_hub.ChatCompletionInputTool [[autodoc]] huggingface_hub.ChatCompletionInputToolCall [[autodoc]] huggingface_hub.ChatCompletionInputToolChoiceClass [[autodoc]] huggingface_hub.ChatCompletionInputURL [[autodoc]] huggingface_hub.ChatCompletionOutput [[autodoc]] huggingface_hub.ChatCompletionOutputComplete [[autodoc]] huggingface_hub.ChatCompletionOutputFunctionDefinition [[autodoc]] huggingface_hub.ChatCompletionOutputLogprob [[autodoc]] huggingface_hub.ChatCompletionOutputLogprobs [[autodoc]] huggingface_hub.ChatCompletionOutputMessage [[autodoc]] huggingface_hub.ChatCompletionOutputToolCall [[autodoc]] huggingface_hub.ChatCompletionOutputTopLogprob [[autodoc]] huggingface_hub.ChatCompletionOutputUsage [[autodoc]] huggingface_hub.ChatCompletionStreamOutput [[autodoc]] huggingface_hub.ChatCompletionStreamOutputChoice [[autodoc]] huggingface_hub.ChatCompletionStreamOutputDelta [[autodoc]] huggingface_hub.ChatCompletionStreamOutputDeltaToolCall [[autodoc]] huggingface_hub.ChatCompletionStreamOutputFunction [[autodoc]] huggingface_hub.ChatCompletionStreamOutputLogprob [[autodoc]] huggingface_hub.ChatCompletionStreamOutputLogprobs [[autodoc]] huggingface_hub.ChatCompletionStreamOutputTopLogprob [[autodoc]] huggingface_hub.ChatCompletionStreamOutputUsage ## depth_estimation[[huggingface_hub.DepthEstimationInput]] [[autodoc]] huggingface_hub.DepthEstimationInput [[autodoc]] huggingface_hub.DepthEstimationOutput ## document_question_answering[[huggingface_hub.DocumentQuestionAnsweringInput]] [[autodoc]] huggingface_hub.DocumentQuestionAnsweringInput [[autodoc]] huggingface_hub.DocumentQuestionAnsweringInputData [[autodoc]] huggingface_hub.DocumentQuestionAnsweringOutputElement [[autodoc]] huggingface_hub.DocumentQuestionAnsweringParameters ## feature_extraction[[huggingface_hub.FeatureExtractionInput]] [[autodoc]] huggingface_hub.FeatureExtractionInput ## fill_mask[[huggingface_hub.FillMaskInput]] [[autodoc]] huggingface_hub.FillMaskInput [[autodoc]] huggingface_hub.FillMaskOutputElement [[autodoc]] huggingface_hub.FillMaskParameters ## image_classification[[huggingface_hub.ImageClassificationInput]] [[autodoc]] huggingface_hub.ImageClassificationInput [[autodoc]] huggingface_hub.ImageClassificationOutputElement [[autodoc]] huggingface_hub.ImageClassificationParameters ## image_segmentation[[huggingface_hub.ImageSegmentationInput]] [[autodoc]] huggingface_hub.ImageSegmentationInput [[autodoc]] huggingface_hub.ImageSegmentationOutputElement [[autodoc]] huggingface_hub.ImageSegmentationParameters ## image_to_image[[huggingface_hub.ImageToImageInput]] [[autodoc]] huggingface_hub.ImageToImageInput [[autodoc]] huggingface_hub.ImageToImageOutput [[autodoc]] huggingface_hub.ImageToImageParameters [[autodoc]] huggingface_hub.ImageToImageTargetSize ## image_to_text[[huggingface_hub.ImageToTextGenerationParameters]] [[autodoc]] huggingface_hub.ImageToTextGenerationParameters [[autodoc]] huggingface_hub.ImageToTextInput [[autodoc]] huggingface_hub.ImageToTextOutput [[autodoc]] huggingface_hub.ImageToTextParameters ## image_to_video[[huggingface_hub.ImageToVideoInput]] [[autodoc]] huggingface_hub.ImageToVideoInput [[autodoc]] huggingface_hub.ImageToVideoOutput [[autodoc]] huggingface_hub.ImageToVideoParameters [[autodoc]] huggingface_hub.ImageToVideoTargetSize ## object_detection[[huggingface_hub.ObjectDetectionBoundingBox]] [[autodoc]] huggingface_hub.ObjectDetectionBoundingBox [[autodoc]] huggingface_hub.ObjectDetectionInput [[autodoc]] huggingface_hub.ObjectDetectionOutputElement [[autodoc]] huggingface_hub.ObjectDetectionParameters ## question_answering[[huggingface_hub.QuestionAnsweringInput]] [[autodoc]] huggingface_hub.QuestionAnsweringInput [[autodoc]] huggingface_hub.QuestionAnsweringInputData [[autodoc]] huggingface_hub.QuestionAnsweringOutputElement [[autodoc]] huggingface_hub.QuestionAnsweringParameters ## sentence_similarity[[huggingface_hub.SentenceSimilarityInput]] [[autodoc]] huggingface_hub.SentenceSimilarityInput [[autodoc]] huggingface_hub.SentenceSimilarityInputData ## summarization[[huggingface_hub.SummarizationInput]] [[autodoc]] huggingface_hub.SummarizationInput [[autodoc]] huggingface_hub.SummarizationOutput [[autodoc]] huggingface_hub.SummarizationParameters ## table_question_answering[[huggingface_hub.TableQuestionAnsweringInput]] [[autodoc]] huggingface_hub.TableQuestionAnsweringInput [[autodoc]] huggingface_hub.TableQuestionAnsweringInputData [[autodoc]] huggingface_hub.TableQuestionAnsweringOutputElement [[autodoc]] huggingface_hub.TableQuestionAnsweringParameters ## text2text_generation[[huggingface_hub.Text2TextGenerationInput]] [[autodoc]] huggingface_hub.Text2TextGenerationInput [[autodoc]] huggingface_hub.Text2TextGenerationOutput [[autodoc]] huggingface_hub.Text2TextGenerationParameters ## text_classification[[huggingface_hub.TextClassificationInput]] [[autodoc]] huggingface_hub.TextClassificationInput [[autodoc]] huggingface_hub.TextClassificationOutputElement [[autodoc]] huggingface_hub.TextClassificationParameters ## text_generation[[huggingface_hub.TextGenerationInput]] [[autodoc]] huggingface_hub.TextGenerationInput [[autodoc]] huggingface_hub.TextGenerationInputGenerateParameters [[autodoc]] huggingface_hub.TextGenerationInputGrammarType [[autodoc]] huggingface_hub.TextGenerationOutput [[autodoc]] huggingface_hub.TextGenerationOutputBestOfSequence [[autodoc]] huggingface_hub.TextGenerationOutputDetails [[autodoc]] huggingface_hub.TextGenerationOutputPrefillToken [[autodoc]] huggingface_hub.TextGenerationOutputToken [[autodoc]] huggingface_hub.TextGenerationStreamOutput [[autodoc]] huggingface_hub.TextGenerationStreamOutputStreamDetails [[autodoc]] huggingface_hub.TextGenerationStreamOutputToken ## text_to_audio[[huggingface_hub.TextToAudioGenerationParameters]] [[autodoc]] huggingface_hub.TextToAudioGenerationParameters [[autodoc]] huggingface_hub.TextToAudioInput [[autodoc]] huggingface_hub.TextToAudioOutput [[autodoc]] huggingface_hub.TextToAudioParameters ## text_to_image[[huggingface_hub.TextToImageInput]] [[autodoc]] huggingface_hub.TextToImageInput [[autodoc]] huggingface_hub.TextToImageOutput [[autodoc]] huggingface_hub.TextToImageParameters ## text_to_speech[[huggingface_hub.TextToSpeechGenerationParameters]] [[autodoc]] huggingface_hub.TextToSpeechGenerationParameters [[autodoc]] huggingface_hub.TextToSpeechInput [[autodoc]] huggingface_hub.TextToSpeechOutput [[autodoc]] huggingface_hub.TextToSpeechParameters ## text_to_video[[huggingface_hub.TextToVideoInput]] [[autodoc]] huggingface_hub.TextToVideoInput [[autodoc]] huggingface_hub.TextToVideoOutput [[autodoc]] huggingface_hub.TextToVideoParameters ## token_classification[[huggingface_hub.TokenClassificationInput]] [[autodoc]] huggingface_hub.TokenClassificationInput [[autodoc]] huggingface_hub.TokenClassificationOutputElement [[autodoc]] huggingface_hub.TokenClassificationParameters ## translation[[huggingface_hub.TranslationInput]] [[autodoc]] huggingface_hub.TranslationInput [[autodoc]] huggingface_hub.TranslationOutput [[autodoc]] huggingface_hub.TranslationParameters ## video_classification[[huggingface_hub.VideoClassificationInput]] [[autodoc]] huggingface_hub.VideoClassificationInput [[autodoc]] huggingface_hub.VideoClassificationOutputElement [[autodoc]] huggingface_hub.VideoClassificationParameters ## visual_question_answering[[huggingface_hub.VisualQuestionAnsweringInput]] [[autodoc]] huggingface_hub.VisualQuestionAnsweringInput [[autodoc]] huggingface_hub.VisualQuestionAnsweringInputData [[autodoc]] huggingface_hub.VisualQuestionAnsweringOutputElement [[autodoc]] huggingface_hub.VisualQuestionAnsweringParameters ## zero_shot_classification[[huggingface_hub.ZeroShotClassificationInput]] [[autodoc]] huggingface_hub.ZeroShotClassificationInput [[autodoc]] huggingface_hub.ZeroShotClassificationOutputElement [[autodoc]] huggingface_hub.ZeroShotClassificationParameters ## zero_shot_image_classification[[huggingface_hub.ZeroShotImageClassificationInput]] [[autodoc]] huggingface_hub.ZeroShotImageClassificationInput [[autodoc]] huggingface_hub.ZeroShotImageClassificationOutputElement [[autodoc]] huggingface_hub.ZeroShotImageClassificationParameters ## zero_shot_object_detection[[huggingface_hub.ZeroShotObjectDetectionBoundingBox]] [[autodoc]] huggingface_hub.ZeroShotObjectDetectionBoundingBox [[autodoc]] huggingface_hub.ZeroShotObjectDetectionInput [[autodoc]] huggingface_hub.ZeroShotObjectDetectionOutputElement [[autodoc]] huggingface_hub.ZeroShotObjectDetectionParameters huggingface_hub-1.1.5/docs/source/ko/package_reference/login.md000066400000000000000000000013161510763414300245340ustar00rootroot00000000000000 # 로그인 및 로그아웃[[login-and-logout]] `huggingface_hub` 라이브러리를 사용하면 사용자의 기기를 Hub에 프로그래밍적으로 로그인/로그아웃할 수 있습니다. 인증에 대한 자세한 내용은 [이 섹션](../quick-start#authentication)을 확인하세요. ## 로그인[[login]] [[autodoc]] login ## 인터프리터_로그인[[interpreter_login]] [[autodoc]] interpreter_login ## 노트북_로그인[[notebook_login]] [[autodoc]] notebook_login ## 로그아웃[[logout]] [[autodoc]] logout huggingface_hub-1.1.5/docs/source/ko/package_reference/mixins.md000066400000000000000000000016661510763414300247430ustar00rootroot00000000000000 # 믹스인 & 직렬화 메소드[[mixins--serialization-methods]] ## 믹스인[[mixins]] `huggingface_hub` 라이브러리는 객체에 함수들의 업로드 및 다운로드 기능을 손쉽게 제공하기 위해서, 부모 클래스로 사용될 수 있는 다양한 믹스인을 제공합니다. ML 프레임워크를 Hub와 통합하는 방법은 [통합 가이드](../guides/integrations)를 통해 배울 수 있습니다. ### 제네릭[[huggingface_hub.ModelHubMixin]] [[autodoc]] ModelHubMixin - all - _save_pretrained - _from_pretrained ### PyTorch[[huggingface_hub.PyTorchModelHubMixin]] [[autodoc]] PyTorchModelHubMixin ### Fastai[[huggingface_hub.from_pretrained_fastai]] [[autodoc]] from_pretrained_fastai [[autodoc]] push_to_hub_fastai huggingface_hub-1.1.5/docs/source/ko/package_reference/overview.md000066400000000000000000000005101510763414300252650ustar00rootroot00000000000000 # Overview[[overview]] 이 섹션은 `huggingface_hub` 클래스와 메서드에 대한 상세하고 기술적인 설명을 포함하고 있습니다. huggingface_hub-1.1.5/docs/source/ko/package_reference/serialization.md000066400000000000000000000036621510763414300263070ustar00rootroot00000000000000 # 직렬화[[serialization]] `huggingface_hub`에는 ML 라이브러리가 모델 가중치를 표준화된 방식으로 직렬화 할 수 있도록 돕는 헬퍼를 포함하고 있습니다. 라이브러리의 이 부분은 아직 개발 중이며 향후 버전에서 개선될 예정입니다. 개선 목표는 Hub에서 가중치의 직렬화 방식을 통일하고, 라이브러리 간 코드 중복을 줄이며, Hub에서의 규약을 촉진하는 것입니다. ## 상태 사전을 샤드로 나누기[[split-state-dict-into-shards]] 현재 이 모듈은 상태 딕셔너리(예: 레이어 이름과 관련 텐서 간의 매핑)를 받아 여러 샤드로 나누고, 이 과정에서 적절한 인덱스를 생성하는 단일 헬퍼를 포함하고 있습니다. 이 헬퍼는 `torch` 텐서에 사용 가능하며, 다른 ML 프레임워크로 쉽게 확장될 수 있도록 설계되었습니다. ### split_torch_state_dict_into_shards[[huggingface_hub.split_torch_state_dict_into_shards]] [[autodoc]] huggingface_hub.split_torch_state_dict_into_shards ### split_state_dict_into_shards_factory[[huggingface_hub.split_state_dict_into_shards_factory]] 이것은 각 프레임워크별 헬퍼가 파생되는 기본 틀입니다. 실제로는 아직 지원되지 않는 프레임워크에 맞게 조정할 필요가 있는 경우가 아니면 이 틀을 직접 사용할 것으로 예상되지 않습니다. 그런 경우가 있다면, `huggingface_hub` 리포지토리에 [새로운 이슈를 개설](https://github.com/huggingface/huggingface_hub/issues/new) 하여 알려주세요. [[autodoc]] huggingface_hub.split_state_dict_into_shards_factory ## 도우미 ### get_torch_storage_id[[huggingface_hub.get_torch_storage_id]] [[autodoc]] huggingface_hub.get_torch_storage_idhuggingface_hub-1.1.5/docs/source/ko/package_reference/space_runtime.md000066400000000000000000000020261510763414300262610ustar00rootroot00000000000000 # Space 런타임 관리[[managing-your-space-runtime]] Hub의 Space를 관리하는 메소드에 대한 자세한 설명은 [`HfApi`]페이지를 확인하세요. - Space 복제: [`duplicate_space`] - 현재 런타임 가져오기: [`get_space_runtime`] - 보안 관리: [`add_space_secret`] 및 [`delete_space_secret`] - 하드웨어 관리: [`request_space_hardware`] - 상태 관리: [`pause_space`], [`restart_space`], [`set_space_sleep_time`] ## 데이터 구조[[data-structures]] ### SpaceRuntime[[huggingface_hub.SpaceRuntime]] [[autodoc]] SpaceRuntime ### SpaceHardware[[huggingface_hub.SpaceHardware]] [[autodoc]] SpaceHardware ### SpaceStage[[huggingface_hub.SpaceStage]] [[autodoc]] SpaceStage ### SpaceStorage[[huggingface_hub.SpaceStorage]] [[autodoc]] SpaceStorage ### SpaceVariable[[huggingface_hub.SpaceVariable]] [[autodoc]] SpaceVariablehuggingface_hub-1.1.5/docs/source/ko/package_reference/tensorboard.md000066400000000000000000000025201510763414300257440ustar00rootroot00000000000000 # TensorBoard 로거[[tensorboard-logger]] TensorBoard는 기계학습 실험을 위한 시각화 도구입니다. 주로 손실 및 정확도와 같은 지표를 추적 및 시각화하고, 모델 그래프와 히스토그램을 보여주고, 이미지를 표시하는 등 다양한 기능을 제공합니다. 또한 TensorBoard는 Hugging Face Hub와 잘 통합되어 있습니다. `tfevents` 같은 TensorBoard 추적을 Hub에 푸시하면 Hub는 이를 자동으로 감지하여 시각화 인스턴스를 시작합니다. TensorBoard와 Hub의 통합에 대한 자세한 정보는 [가이드](https://huggingface.co/docs/hub/tensorboard)를 확인하세요. 이 통합을 위해, `huggingface_hub`는 로그를 Hub로 푸시하기 위한 사용자 정의 로거를 제공합니다. 이 로거는 추가적인 코드 없이 [SummaryWriter](https://tensorboardx.readthedocs.io/en/latest/tensorboard.html)의 대체제로 사용될 수 있습니다. 추적은 계속해서 로컬에 저장되며 백그라운드 작업이 일정한 시간마다 Hub에 푸시하는 형태로 동작합니다. ## HFSummaryWriter[[huggingface_hub.HFSummaryWriter]] [[autodoc]] HFSummaryWriter huggingface_hub-1.1.5/docs/source/ko/package_reference/utilities.md000066400000000000000000000223401510763414300254370ustar00rootroot00000000000000 # 유틸리티[[utilities]] ## 로깅 구성[[huggingface_hub.utils.logging.get_verbosity]] `huggingface_hub` 패키지는 패키지 로그 레벨을 제어하기 위한 `logging` 유틸리티를 제공합니다. 다음과 같이 가져올 수 있습니다: ```py from huggingface_hub import logging ``` 그런 다음, 로그의 출력 수를 업데이트하기 위해 로그 레벨을 정의할 수 있습니다: ```python from huggingface_hub import logging logging.set_verbosity_error() logging.set_verbosity_warning() logging.set_verbosity_info() logging.set_verbosity_debug() logging.set_verbosity(...) ``` 로그 레벨은 다음과 같이 이해하면 됩니다: - `error`: 오류 또는 예기치 않은 동작으로 이어질 수 있는 결정적인 로그만 표시합니다. - `warning`: 결정적이진 않지만 의도치 않은 동작을 초래할 수 있는 로그를 표시합니다. 또한 중요한 정보를 포함한 로그도 표시될 수 있습니다. - `info`: 하부에서 무슨 일이 일어나고 있는지에 대한 자세한 로그를 포함하여 대부분의 로그를 표시합니다. 무언가 예상치 못한 방식으로 동작하는 경우, 더 많은 정보를 얻기 위해 verbosity 단계로 전환하는 것이 좋습니다. - `debug`: 하부에서 정확히 무슨 일이 일어나고 있는지를 추적하는 데 사용될 수 있는 일부 내부 로그를 포함하여 모든 로그를 표시합니다. [[autodoc]] logging.get_verbosity [[autodoc]] logging.set_verbosity [[autodoc]] logging.set_verbosity_info [[autodoc]] logging.set_verbosity_debug [[autodoc]] logging.set_verbosity_warning [[autodoc]] logging.set_verbosity_error [[autodoc]] logging.disable_propagation [[autodoc]] logging.enable_propagation ### 리포지토리별 도우미 메소드[[huggingface_hub.utils.logging.get_logger]] 아래 제공된 메소드들은 `huggingface_hub` 라이브러리 모듈을 수정할 때 관련이 있습니다. `huggingface_hub`를 사용하고 해당 모듈을 수정하지 않는 경우에는 사용할 필요가 없습니다. [[autodoc]] logging.get_logger ## 프로그레스 바 구성하기[[configure-progress-bars]] 프로그레스 바는 긴 시간이 걸리는 작업을 실행하는 동안 정보를 표시하는 유용한 도구입니다(예시로 파일을 다운로드하거나 업로드하는 등). `huggingface_hub`는 라이브러리 전체에서 일관된 방식으로 프로그레스 바를 표시하기 위한 [`~utils.tqdm`] 래퍼를 제공합니다. 기본적으로 프로그레스 바가 활성화되어 있습니다. `HF_HUB_DISABLE_PROGRESS_BARS` 환경 변수를 설정하여 전역적으로 비활성화할 수 있습니다. 또한 [`~utils.enable_progress_bars`]와 [`~utils.disable_progress_bars`]를 사용하여 프로그레스 바를 개별적으로 활성화 또는 비활성화할 수도 있습니다. 만약 환경 변수가 설정되어 있다면, 환경 변수가 도우미에서 우선 순위를 가집니다. ```py >>> from huggingface_hub import snapshot_download >>> from huggingface_hub.utils import are_progress_bars_disabled, disable_progress_bars, enable_progress_bars >>> # 전역적으로 프로그레스 바를 비활성화합니다. >>> disable_progress_bars() >>> # 프로그레스 바가 표시되지 않습니다! >>> snapshot_download("gpt2") >>> are_progress_bars_disabled() True >>> # 다시 프로그레스 바가 활성화됩니다 >>> enable_progress_bars() ``` ### are_progress_bars_disabled[[huggingface_hub.utils.are_progress_bars_disabled]] [[autodoc]] huggingface_hub.utils.are_progress_bars_disabled ### disable_progress_bars[[huggingface_hub.utils.disable_progress_bars]] [[autodoc]] huggingface_hub.utils.disable_progress_bars ### enable_progress_bars[huggingface_hub.utils.enable_progress_bars]] [[autodoc]] huggingface_hub.utils.enable_progress_bars ## HTTP 오류 다루기[[handle-http-errors]] `huggingface_hub`는 서버에서 반환된 추가 정보로 `requests`에서 발생한 `HTTPError`를 세분화하기 위해 자체 HTTP 오류를 정의합니다. ### 예외 발생[[huggingface_hub.utils.hf_raise_for_status]] [`~utils.hf_raise_for_status`]는 Hub에 대한 모든 요청에서 "상태를 확인하고 예외를 발생시키는" 중앙 메소드로 사용됩니다. 이 메서드는 기본 `requests.raise_for_status`를 감싸서 추가 정보를 제공합니다. 발생된 모든 `HTTPError`는 `HfHubHTTPError`로 변환됩니다. ```py import requests from huggingface_hub.utils import hf_raise_for_status, HfHubHTTPError response = requests.post(...) try: hf_raise_for_status(response) except HfHubHTTPError as e: print(str(e)) # 형식화된 메시지 e.request_id, e.server_message # 서버에서 반환된 세부 정보 # 오류 메시지를 발생시킬 때 추가 정보를 포함하여 완성합니다 e.append_to_message("\n`create_commit` expects the repository to exist.") raise ``` [[autodoc]] huggingface_hub.utils.hf_raise_for_status ### HTTP 오류[[http-errors]] 여기에는 `huggingface_hub`에서 발생하는 HTTP 오류 목록이 있습니다. #### HfHubHTTPError[[huggingface_hub.errors.HfHubHTTPError]] `HfHubHTTPError`는 HF Hub HTTP 오류에 대한 부모 클래스입니다. 이 클래스는 서버 응답을 구문 분석하고 오류 메시지를 형식화하여 사용자에게 가능한 많은 정보를 제공합니다. [[autodoc]] huggingface_hub.errors.HfHubHTTPError #### RepositoryNotFoundError[[huggingface_hub.errors.RepositoryNotFoundError]] [[autodoc]] huggingface_hub.errors.RepositoryNotFoundError #### GatedRepoError[[huggingface_hub.errors.GatedRepoError]] [[autodoc]] huggingface_hub.errors.GatedRepoError #### RevisionNotFoundError[[huggingface_hub.errors.RevisionNotFoundError]] [[autodoc]] huggingface_hub.errors.RevisionNotFoundError #### BadRequestError[[huggingface_hub.errors.BadRequestError]] [[autodoc]] huggingface_hub.errors.BadRequestError #### EntryNotFoundError[[huggingface_hub.errors.EntryNotFoundError]] [[autodoc]] huggingface_hub.errors.EntryNotFoundError #### RemoteEntryNotFoundError[[huggingface_hub.errors.RemoteEntryNotFoundError]] [[autodoc]] huggingface_hub.errors.RemoteEntryNotFoundError #### LocalEntryNotFoundError[[huggingface_hub.errors.LocalEntryNotFoundError]] [[autodoc]] huggingface_hub.errors.LocalEntryNotFoundError #### OfflineModeIsEnabledd[[huggingface_hub.errors.OfflineModeIsEnabled]] [[autodoc]] huggingface_hub.errors.OfflineModeIsEnabled ## 원격 측정[[huggingface_hub.utils.send_telemetry]] `huggingface_hub`는 원격 측정 데이터를 보내는 도우미가 포함되어 있습니다. 이 정보는 문제를 디버깅하고 새로운 기능을 우선적으로 처리하는 데 도움이 됩니다. 사용자는 `HF_HUB_DISABLE_TELEMETRY=1` 환경 변수를 설정하여 언제든지 원격 측정 수집을 비활성화할 수 있습니다. 또한 오프라인 모드에서도 (즉, HF_HUB_OFFLINE=1로 설정된 경우) 원격 측정이 비활성화됩니다. 서드 파티 라이브러리의 유지 관리자인 경우, 원격 측정 데이터를 보내는 것은 [`send_telemetry`]를 호출하는 것만큼 간단합니다. 사용자에게 가능한 영향을 최소화하기 위해 데이터는 별도의 스레드에서 전송됩니다. [[autodoc]] utils.send_telemetry ## 검증기[[validators]] `huggingface_hub`에는 메소드 인수를 자동으로 유효성 검사하는 사용자 정의 검증기가 포함되어 있습니다. 이 유효성 검사는 타입 힌트를 검증하는 데 [Pydantic](https://pydantic-docs.helpmanual.io/)의 작업을 참고하여 구현되었지만, 기능은 더 제한적입니다. ### 일반 데코레이터[[generic-decorator]] [`~utils.validate_hf_hub_args`]는 `huggingface_hub`의 네이밍을 따르는 인수를 갖는 메소드를 캡슐화하는 일반적인 데코레이터입니다. 기본적으로 구현된 검증기가 있는 모든 인수가 유효성 검사됩니다. 입력이 유효하지 않은 경우 [`~utils.HFValidationError`]이 발생합니다. 첫 번째 유효하지 않은 값만 오류를 발생시키고 유효성 검사 프로세스를 중지합니다. 사용법: ```py >>> from huggingface_hub.utils import validate_hf_hub_args >>> @validate_hf_hub_args ... def my_cool_method(repo_id: str): ... print(repo_id) >>> my_cool_method(repo_id="valid_repo_id") valid_repo_id >>> my_cool_method("other..repo..id") huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'. >>> my_cool_method(repo_id="other..repo..id") huggingface_hub.utils._validators.HFValidationError: Cannot have -- or .. in repo_id: 'other..repo..id'. ``` #### validate_hf_hub_args[[huggingface_hub.utils.validate_hf_hub_args]] [[autodoc]] utils.validate_hf_hub_args #### HFValidationError[[huggingface_hub.utils.HFValidationError]] [[autodoc]] utils.HFValidationError ### Argument validators[[argument-validators]] 검증기는 개별적으로도 사용할 수 있습니다. 다음은 검증할 수 있는 모든 인수 목록입니다. #### repo_id[[huggingface_hub.utils.validate_repo_id]] [[autodoc]] utils.validate_repo_id huggingface_hub-1.1.5/docs/source/ko/package_reference/webhooks_server.md000066400000000000000000000067731510763414300266470ustar00rootroot00000000000000 # 웹훅 서버[[webhooks-server]] 웹훅은 MLOps 관련 기능의 기반이 됩니다. 이를 통해 특정 저장소의 새로운 변경 사항을 수신하거나, 관심 있는 특정 사용자/조직에 속한 모든 저장소의 변경 사항을 받아볼 수 있습니다. Huggingface Hub의 웹훅에 대해 더 자세히 알아보려면 이 [가이드](https://huggingface.co/docs/hub/webhooks)를 읽어보세요. > [!TIP] > 웹훅 서버를 설정하고 Space로 배포하는 방법은 이 단계별 [가이드](../guides/webhooks_server)를 확인하세요. > [!WARNING] > 이 기능은 실험적인 기능입니다. 본 API는 현재 개선 작업 중이며, 향후 사전 통지 없이 주요 변경 사항이 도입될 수 있음을 의미합니다. `requirements`에서 `huggingface_hub`의 버전을 고정하는 것을 권장합니다. 참고로 실험적 기능을 사용하면 경고가 트리거 됩니다. 이 경고 트리거를 비활성화 시키길 원한다면 환경변수 `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1`를 설정하세요. ## 서버[[server]] 여기서 서버는 하나의 [Gradio](https://gradio.app/) 앱을 의미합니다. Gradio에는 사용자 또는 사용자에게 지침을 표시하는 UI와 웹훅을 수신하기 위한 API가 있습니다. 웹훅 엔드포인트를 구현하는 것은 함수에 데코레이터를 추가하는 것만큼 간단합니다. 서버를 Space에 배포하기 전에 Gradio 터널을 사용하여 웹훅을 머신으로 리디렉션하여 디버깅할 수 있습니다. ### WebhooksServer[[huggingface_hub.WebhooksServer]] [[autodoc]] huggingface_hub.WebhooksServer ### @webhook_endpoint[[huggingface_hub.webhook_endpoint]] [[autodoc]] huggingface_hub.webhook_endpoint ## 페이로드[[huggingface_hub.WebhookPayload]] [`WebhookPayload`]는 웹훅의 페이로드를 포함하는 기본 데이터 구조입니다. 이것은 `pydantic` 클래스로서 FastAPI에서 매우 쉽게 사용할 수 있습니다. 즉 WebhookPayload를 웹후크 엔드포인트에 매개변수로 전달하면 자동으로 유효성이 검사되고 파이썬 객체로 파싱됩니다. 웹훅 페이로드에 대한 자세한 사항은 이 [가이드](https://huggingface.co/docs/hub/webhooks#webhook-payloads)를 참고하세요. [[autodoc]] huggingface_hub.WebhookPayload ### WebhookPayload[[huggingface_hub.WebhookPayload]] [[autodoc]] huggingface_hub.WebhookPayload ### WebhookPayloadComment[[huggingface_hub.WebhookPayloadComment]] [[autodoc]] huggingface_hub.WebhookPayloadComment ### WebhookPayloadDiscussion[[huggingface_hub.WebhookPayloadDiscussion]] [[autodoc]] huggingface_hub.WebhookPayloadDiscussion ### WebhookPayloadDiscussionChanges[[huggingface_hub.WebhookPayloadDiscussionChanges]] [[autodoc]] huggingface_hub.WebhookPayloadDiscussionChanges ### WebhookPayloadEvent[[huggingface_hub.WebhookPayloadEvent]] [[autodoc]] huggingface_hub.WebhookPayloadEvent ### WebhookPayloadMovedTo[[huggingface_hub.WebhookPayloadMovedTo]] [[autodoc]] huggingface_hub.WebhookPayloadMovedTo ### WebhookPayloadRepo[[huggingface_hub.WebhookPayloadRepo]] [[autodoc]] huggingface_hub.WebhookPayloadRepo ### WebhookPayloadUrl[[huggingface_hub.WebhookPayloadUrl]] [[autodoc]] huggingface_hub.WebhookPayloadUrl ### WebhookPayloadWebhook[[huggingface_hub.WebhookPayloadWebhook]] [[autodoc]] huggingface_hub.WebhookPayloadWebhook huggingface_hub-1.1.5/docs/source/ko/quick-start.md000066400000000000000000000151701510763414300222650ustar00rootroot00000000000000 # 둘러보기 [[quickstart]] [Hugging Face Hub](https://huggingface.co/)는 머신러닝 모델, 데모, 데이터 세트 및 메트릭을 공유할 수 있는 곳입니다. `huggingface_hub` 라이브러리는 개발 환경을 벗어나지 않고도 Hub와 상호작용할 수 있도록 도와줍니다. 리포지토리를 쉽게 만들고 관리하거나, 파일을 다운로드 및 업로드하고, 유용한 모델과 데이터 세트의 메타데이터도 구할 수 있습니다. ## 설치 [[installation]] 시작하려면 `huggingface_hub` 라이브러리를 설치하세요: ```bash pip install --upgrade huggingface_hub ``` 자세한 내용은 [설치](./installation) 가이드를 참조하세요. ## 파일 다운로드 [[download-files]] Hub의 리포지토리는 git으로 버전 관리되며, 사용자는 단일 파일 또는 전체 리포지토리를 다운로드할 수 있습니다. 파일을 다운로드하려면 [`hf_hub_download`] 함수를 사용하면 됩니다. 사용하면 파일을 다운로드하여 로컬 디스크에 캐시하기 때문에, 다음에 해당 파일이 필요하면 캐시에서 가져오므로 다시 다운로드할 필요가 없습니다. 다운로드하려면 리포지토리 ID와 파일명이 필요합니다. 예를 들어, [Pegasus](https://huggingface.co/google/pegasus-xsum) 모델 구성 파일을 다운로드하려면: ```py >>> from huggingface_hub import hf_hub_download >>> hf_hub_download(repo_id="google/pegasus-xsum", filename="config.json") ``` 특정 버전의 파일을 다운로드하려면 `revision` 매개변수를 사용하여 브랜치 이름, 태그 또는 커밋 해시를 지정하세요. 커밋 해시를 사용하기로 선택한 경우, 7자로 된 짧은 커밋 해시 대신 전체 길이의 해시여야 합니다: ```py >>> from huggingface_hub import hf_hub_download >>> hf_hub_download( ... repo_id="google/pegasus-xsum", ... filename="config.json", ... revision="4d33b01d79672f27f001f6abade33f22d993b151" ... ) ``` 자세한 내용과 옵션은 [`hf_hub_download`]에 대한 API 레퍼런스를 참조하세요. ## 로그인 [[login]] 비공개 리포지토리 다운로드, 파일 업로드, PR 생성 등 Hub와 상호 작용하려면 Hugging Face 계정으로 로그인해야 하는 경우가 많습니다. 아직 계정이 없다면 [계정 만들기](https://huggingface.co/join)를 클릭한 다음, 로그인하여 [설정 페이지](https://huggingface.co/settings/tokens)에서 [사용자 액세스 토큰](https://huggingface.co/docs/hub/security-tokens)을 받으세요. 사용자 액세스 토큰은 Hub에 인증하는 데 사용됩니다. 사용자 액세스 토큰을 받으면 터미널에서 다음 명령을 실행하세요: ```bash hf auth login # or using an environment variable hf auth login --token $HUGGINGFACE_TOKEN ``` 또는 주피터 노트북이나 스크립트에서 [`login`]로 프로그래밍 방식으로 로그인할 수도 있습니다: ```py >>> from huggingface_hub import login >>> login() ``` `login(token="hf_xxx")`과 같이 토큰을 [`login`]에 직접 전달하여 토큰을 입력하라는 메시지를 표시하지 않고 프로그래밍 방식으로 로그인할 수도 있습니다. 이렇게 한다면 소스 코드를 공유할 때 주의하세요. 토큰을 소스코드에 명시적으로 저장하는 대신에 보안 저장소에서 토큰을 가져오는 것이 가장 좋습니다. 한 번에 하나의 계정에만 로그인할 수 있습니다. 새 계정으로 로그인하면 이전 계정에서 로그아웃됩니다. 항상 `hf auth whoami` 명령으로 어떤 계정을 사용 중인지 확인하세요. 동일한 스크립트에서 여러 계정을 처리하려면 각 메서드를 호출할 때 토큰을 제공하면 됩니다. 이 방법은 머신에 토큰을 저장하지 않으려는 경우에도 유용합니다. > [!WARNING] > 로그인하면 Hub에 대한 모든 요청(반드시 인증이 필요하지 않은 메소드 포함)은 기본적으로 액세스 토큰을 사용합니다. 토큰의 암시적 사용을 비활성화하려면 `HF_HUB_DISABLE_IMPLICIT_TOKEN` 환경 변수를 설정해야 합니다. ## 리포지토리 만들기 [[create-a-repository]] 등록 및 로그인이 완료되면 [`create_repo`] 함수를 사용하여 리포지토리를 생성하세요: ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.create_repo(repo_id="super-cool-model") ``` 리포지토리를 비공개로 설정하려면 다음과 같이 하세요: ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.create_repo(repo_id="super-cool-model", private=True) ``` 비공개 리포지토리는 본인 외에는 누구에게도 공개되지 않습니다. > [!TIP] > 리포지토리를 생성하거나 Hub에 콘텐츠를 푸시하려면 `write` (쓰기) 권한이 있는 사용자 액세스 토큰을 제공해야 합니다. 토큰을 생성할 때 [설정 페이지](https://huggingface.co/settings/tokens)에서 권한을 선택할 수 있습니다. ## 파일 업로드 [[upload-files]] 새로 만든 리포지토리에 파일을 추가하려면 [`upload_file`] 함수를 사용하세요. 다음을 지정해야 합니다: 1. 업로드할 파일의 경로 2. 리포지토리에 있는 파일의 경로 3. 파일을 추가할 위치의 리포지토리 ID ```py >>> from huggingface_hub import HfApi >>> api = HfApi() >>> api.upload_file( ... path_or_fileobj="/home/lysandre/dummy-test/README.md", ... path_in_repo="README.md", ... repo_id="lysandre/test-model", ... ) ``` 한 번에 두 개 이상의 파일을 업로드하려면 [업로드](./guides/upload) 가이드에서 (git을 포함하거나 제외한) 여러 가지 파일 업로드 방법을 소개하는 가이드를 참조하세요. ## 다음 단계 [[next-steps]] `huggingface_hub` 라이브러리는 사용자가 파이썬으로 Hub와 상호작용할 수 있는 쉬운 방법을 제공합니다. Hub에서 파일과 리포지토리를 관리하는 방법에 대해 자세히 알아보려면 [How-to 가이드](./guides/overview)를 읽어보시기 바랍니다: - 보다 쉽게 [리포지토리를 관리](./guides/repository)해보세요. - Hub에서 [다운로드](./guides/download) 파일을 다운로드해보세요. - Hub에 [업로드](./guides/upload) 파일을 업로드해보세요. - 원하는 모델 또는 데이터 세트에 대한 [Hub에서 검색](./guides/search)해보세요. - 빠른 추론을 원하신다면 [추론 API](./guides/inference)를 사용해보세요. huggingface_hub-1.1.5/docs/source/tm/000077500000000000000000000000001510763414300174775ustar00rootroot00000000000000huggingface_hub-1.1.5/docs/source/tm/_toctree.yml000066400000000000000000000002321510763414300220230ustar00rootroot00000000000000- title: "Get started" sections: - local: index title: குறியீட்டு - local: installation title: நிறுவல்huggingface_hub-1.1.5/docs/source/tm/index.md000066400000000000000000000166601510763414300211410ustar00rootroot00000000000000 # 🤗 ஹப் கிளையன்ட் லைப்ரரி `Huggingface_hub` லைப்ரரி உங்களை [ஹக்கிங் ஃபேஸ் ஹப்](https://hf.co) உடன் தொடர்புகொள்ள அனுமதிக்கிறது, இது படைப்பாளர்கள் மற்றும் கூட்டுப்பணியாளர்களுக்கான இயந்திர கற்றல் தளமாகும். உங்கள் திட்டங்களுக்கான முன் பயிற்சி பெற்ற மாதிரிகள் மற்றும் தரவுத்தொகுப்புகளைக் கண்டறியவும் அல்லது ஹப்பில் ஹோஸ்ட் செய்யப்பட்ட நூற்றுக்கணக்கான இயந்திர கற்றல் பயன்பாடுகளுடன் விளையாடவும். உங்கள் சொந்த மாதிரிகள் மற்றும் தரவுத்தொகுப்புகளை உருவாக்கி சமூகத்துடன் பகிரலாம். `huggingface_hub` லைப்ரரி பைதான் மூலம் இவற்றைச் செய்வதற்கான எளிய வழியை வழங்குகிறது. [இந்த துரிதத் தொடக்கக் கையேட்டை](quick-start) வாசித்தால், `huggingface_hub` நூலகத்துடன் வேலை செய்ய எவ்வாறு ஆரம்பிக்கலாம் என்பதை நீங்கள் கற்றுக்கொள்வீர்கள். இதில், 🤗 ஹப் (Hub) இலிருந்து கோப்புகளை எவ்வாறு பதிவிறக்குவது, ஒரு `repository` உருவாக்குவது மற்றும் கோப்புகளை ஹபுக்கு எவ்வாறு பதிவேற்றுவது என்பதை நீங்கள் கற்றுக்கொள்வீர்கள்.மேலும், 🤗 ஹபில் உங்கள் repositoryகளை எவ்வாறு நிர்வகிக்க வேண்டும், விவாதங்களில் எவ்வாறு ஈடுபட வேண்டும், அல்லது `Inference API`யை எப்படி அணுகுவது என்பதையும் கற்றுக்கொள்ள இந்த வழிகாட்டியை தொடர்ந்து வாசியுங்கள்.
எப்படி செய்ய வேண்டும் கையேடுகள்

ஒரு குறிப்பிட்ட இலக்கை அடைய உதவுவதற்கான நடைமுறை கையேடுகள். உண்மையான உலக பிரச்சினைகளைத் தீர்க்க hஹக்கிங் ஃபேஸ் ஹப் ஐ எவ்வாறு பயன்படுத்துவது கற்றுக்கொள்ள இந்த கையேடுகளைப் பார்க்கவும்.
குறிப்பு

ஹக்கிங் ஃபேஸ் ஹப் வகுப்புகள் மற்றும் முறைகள் பற்றிய முழுமையான மற்றும் தொழில்நுட்ப விவரணம்.
விளக்கக் கையேடுகள்

ஹக்கிங் ஃபேஸ் ஹப் தத்துவத்தை மேலும் புரிந்துகொள்ள உயர்நிலையான விளக்கங்கள்.
## பங்களிப்பு `huggingface_hub`-க்கு அனைத்து பங்களிப்புகளும் வரவேற்கப்படுகின்றன மற்றும் சமமாக மதிக்கப்படுகின்றன! 🤗 கோடில் உள்ள உள்ளமைவுகளையும் அல்லது பிழைகளைச் சரிசெய்வதோடு, ஆவணங்களை சரியாகவும், தற்போதைய நிலையில் இருப்பதையும் உறுதிப்படுத்துவதன் மூலம் தங்களால் உதவலாம், மேலும் இஷ்யூக்களுக்கான கேள்விகளுக்கு பதிலளிக்கவும், நூலகத்தை மேம்படுத்துமாறு நீங்கள் நினைப்பதைத் தொடர்ந்து புதிய அம்சங்களை கோரலாம். பங்களிப்பு குறித்த [வழிகாட்டலை](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) பார்க்கவும், புதிய இஷ்யூவோ அல்லது அம்சக் கோரிக்கையோ எப்படி சமர்ப்பிக்க வேண்டும், புல் ரிக்வெஸ்ட்களை (Pull Request) சமர்ப்பிப்பது எப்படி, மேலும் உங்கள் பங்களிப்புகள் அனைத்தும் எதிர்பார்த்தது போல வேலை செய்கிறதா என்பதைச் சோதிப்பது எப்படி என்பதையும் கற்றுக்கொள்ளலாம். பங்களிப்பாளர்கள் அனைவருக்கும் உள்ளடக்கிய மற்றும் வரவேற்கக்கூடிய ஒத்துழைப்பு நிலையை உருவாக்க, நாங்கள் உருவாக்கிய [நடத்தை விதிகளை](https://github.com/huggingface/huggingface_hub/blob/main/CODE_OF_CONDUCT.md) மதிக்க வேண்டும். huggingface_hub-1.1.5/docs/source/tm/installation.md000066400000000000000000000355221510763414300225310ustar00rootroot00000000000000# நிறுவல் நீங்கள் தொடங்குவதற்கு முன், தகுந்த தொகுப்புகளை நிறுவுவதன் மூலம் உங்கள் சூழலை அமைக்க வேண்டும். `huggingface_hub` **Python 3.9+** மின்பொருள்களில் சோதிக்கப்பட்டுள்ளது. ### பிப் மூலம் நிறுவு **pip மூலம் நிறுவல்** `huggingface_hub`-ஐ ஒரு [மெய்நிகர் சூழலில்](https://docs.python.org/3/library/venv.html) (virtual environment) நிறுவுவது மிகவும் பரிந்துரைக்கப்படுகிறது. நீங்கள் பைதான் மெய்நிகர் சூழல்களைக் குறித்து அறியாதவராக இருந்தால், இந்த [வழிகாட்டலைப்](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)பார்க்கவும். ஒரு மெய்நிகர் சூழல் பல்வேறு திட்டங்களை எளிதில் நிர்வகிக்கவும், சார்புகளுக்கிடையிலான (dependencies) இணக்கமின்மை பிரச்சனைகளைத் தவிர்க்கவும் உதவுகிறது. முதலில், உங்கள் திட்ட அடைவரிசையில் (project directory) ஒரு மெய்நிகர் சூழலை உருவாக்கத் தொடங்குங்கள்: ```bash python -m venv .env ``` மெய்நிகர் சூழலை செயல்படுத்தவும். Linux மற்றும் macOS-இல்: ```bash source .env/bin/activate ``` விண்டோஸ்-இல் மெய்நிகர் சூழலை செயல்படுத்த: ```bash .env/Scripts/activate ``` இப்போது நீங்கள் `huggingface_hub`-ஐ [PyPi பதிவகத்திலிருந்து](https://pypi.org/project/huggingface-hub/) நிறுவ தயாராக இருக்கிறீர்கள். ```bash pip install --upgrade huggingface_hub ``` முடித்த பிறகு, [நிறுவல் சரியாக வேலை](#check-installation) செய்கிறதா என்பதைச் சோதிக்கவும். ### விருப்பத் தேவைப்படும் சார்புகளை நிறுவல்** `huggingface_hub`-இன் சில சார்புகள் விருப்பமானவை, ஏனெனில் அவை `huggingface_hub`-இன் அடிப்படை அம்சங்களை இயக்க தேவையில்லை. எனினும், விருப்பச் சார்புகள் நிறுவப்படாதால், `huggingface_hub`-இன் சில அம்சங்கள் கிடைக்காது. நீங்கள் விருப்பத் தேவைப்படும் சார்புகளை `pip` மூலம் நிறுவலாம்: ```bash # டார்ச்-குறிப்பிட்ட மற்றும் CLI-குறிப்பிட்ட அம்சங்களுக்கு தேவையான பொறுப்புகளை நிறுவவும். pip install 'huggingface_hub[cli,torch]' ``` `huggingface_hub`-இல் உள்ள விருப்பத் தேவைப்படும் சார்புகளின் பட்டியல்: - `cli`: `huggingface_hub`-க்கு மிகவும் வசதியான CLI இடைமுகத்தை வழங்குகிறது. - `fastai`, `torch`: வடிவமைப்பு குறிப்பிட்ட அம்சங்களை இயக்க தேவையான சார்புகள். - `dev`: நூலகத்திற்கு பங்களிக்க தேவையான சார்புகள். இதில் சோதனை (சோதனைகளை இயக்க), வகை சோதனை (வகை சரிபார்ப்பு ஐ இயக்க) மற்றும் தரம் (லிண்டர்கள் ஐ இயக்க) உள்ளன. ### மூலத்திலிருந்து நிறுவல் சில சமயம், `huggingface_hub`-ஐ நேரடியாக மூலத்திலிருந்து நிறுவுவது சுவாரஸ்யமாக இருக்கலாம். இது, சமீபத்திய நிலையான பதிப்பு பதிலாக, புதியதாக இருக்கும் `முக்கிய` பதிப்பைப் பயன்படுத்த அனுமதிக்கிறது. `முக்கிய` பதிப்பு, சமீபத்திய முன்னேற்றங்களுடன் புதுப்பிக்க உதவுகிறது, உதாரணமாக, சமீபத்திய அதிகாரப்பூர்வ வெளியீட்டுக்குப் பிறகு பிழை சரிசெய்யப்பட்டிருந்தாலும் புதிய வெளியீடு வந்ததாக இல்லை. எனினும், இதன் பொருள் `முக்கிய` பதிப்பு எப்போதும் நிலையாக இருக்காது. `முக்கிய` பதிப்பை செயல்படுமாறு வைத்திருக்க நாங்கள் முயற்சிக்கிறோம், மேலும் பெரும்பாலான சிக்கல்களை சில மணி நேரங்கள் அல்லது ஒரு நாளுக்குள் தீர்க்கவேண்டியவை. நீங்கள் ஒரு பிரச்சினையை எதிர்கொண்டால், அதைக் கூட்டுங்கள், அதைக் கூட விரைவில் சரிசெய்ய நாங்கள் முயற்சிக்கிறோம்! ```bash pip install git+https://github.com/huggingface/huggingface_hub ``` மூலத்திலிருந்து நிறுவும் போது, நீங்கள் குறிப்பிட்ட கிளையை (branch) குறிப்படலாம். இது, இன்னும் இணைக்கப்படாத புதிய அம்சம் அல்லது புதிய பிழை சரிசெய்வுகளை சோதிக்க விரும்பும்போது பயனுள்ளதாக இருக்கும்: ```bash pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch ``` முடித்த பிறகு, [நிறுவல் சரியாக வேலை செய்கிறதா]((#check-installation)) என்பதைச் சோதிக்கவும். ### திருத்தக்கூடிய நிறுவல் மூலத்திலிருந்து நிறுவுதல் [எடிடேபிள் இன்ஸ்டால்](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs) அமைப்பதற்கு அனுமதிக்கிறது. இது, `huggingface_hub`-க்கு பங்களிக்க திட்டமிட்டு, கோடில் மாற்றங்களை சோதிக்க விரும்பும் போது மேலும் முற்றிலும் மேம்பட்ட நிறுவல் ஆகும். உங்கள் இயந்திரத்தில் `huggingface_hub`-இன் ஒரு உள்ளூர் நகலை கிளோன் செய்ய வேண்டும். ```bash # முதலில், கிடுகிடுக்கும் தொகுப்பை உள்ளூர் முறையில் கிளோன் செய்யவும். git clone https://github.com/huggingface/huggingface_hub.git # அதன் பிறகு, -e கொள்கையைப் பயன்படுத்தி நிறுவவும். cd huggingface_hub pip install -e . ``` இந்த கட்டளைகள், நீங்கள் தரவுகளை கிளோன் செய்த அடைவை மற்றும் உங்கள் பைதான் நூலகப் பாதைகளை இணைக்கும். பைதான், தற்போது சாதாரண நூலகப் பாதைகளுக்கு கூட, நீங்கள் கிளோன் செய்த அடைவைப் பார்வையிடும். உதாரணமாக, உங்கள் பைதான் தொகுப்புகள் பொதுவாக `./.venv/lib/python3.11/site-packages/` இல் நிறுவப்பட்டிருந்தால், பைதான்n நீங்கள் கிளோன் செய்த `./huggingface_hub/` அடைவையும் தேடுவதாக இருக்கும். ## கொண்டா மூலம் நிறுவல் **நீங்கள் அதனுடன் மேலும் பரிச்சயமாக இருந்தால்**, `huggingface_hub`-ஐ [conda-forge சேனல்](https://anaconda.org/conda-forge/huggingface_hub) பயன்படுத்தி நிறுவலாம்: ```bash conda install -c conda-forge huggingface_hub ``` முடித்த பிறகு, [நிறுவல் சரியாக வேலை செய்கிறதா என்பதைச் சோதிக்கவும்](#check-installation). ## நிறுவலைச் சோதிக்கவும் நிறுவலுக்குப் பிறகு, `huggingface_hub` சரியாக வேலை செய்கிறதா என்பதைக் கீழ்காணும் கட்டளையை இயக்கி சோதிக்கவும்: ```bash python -c "from huggingface_hub import model_info; print(model_info('gpt2'))" ``` இந்த கட்டளை, Hub-இல் உள்ள [gpt2](https://huggingface.co/gpt2) மாடலுக்கான தகவல்களை பெறும். வெளியீடு கீழ்காணும் மாதிரியாக இருக்க வேண்டும்: ```text Model Name: gpt2 Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space'] Task: text-generation ``` ## Windows மரபுகள் எந்த இடத்திலும் சிறந்த ML-ஐ பொதுமக்களுக்கு வழங்கும் எங்கள் இலக்குடன், `huggingface_hub`-ஐ ஒரு குறைவில்லாத தளத்துடன் உருவாக்கினோம் மற்றும் குறிப்பாக Unix அடிப்படையிலான மற்றும் Windows அமைப்புகளில் சரியாக செயல்படவும். ஆனால், Windows-இல் இயங்கும் போது `huggingface_hub`-க்கு சில வரையறைகள் உள்ளன. இங்கே தெரிந்த சிக்கல்களின் முழு பட்டியல் உள்ளது. உங்கள் சந்தர்ப்பத்தில் ஆவணமிடாத சிக்கல் கண்டுபிடித்தால், [Github-ல் ஒரு பிரச்சனை திறக்க](https://github.com/huggingface/huggingface_hub/issues/new/choose) எங்களுக்கு தெரிவிக்கவும். - `huggingface_hub`-இன் காசே அமைப்பு, Hub-இல் இருந்து பதிவிறக்கம் செய்யப்பட்ட கோப்புகளைச் சரியாக காசே செய்ய சிம்லிங்குகளை நம்புகிறது. Windows-இல், சிம்லிங்குகளை இயக்குவதற்கு நீங்கள் டெவலப்பர் முறை அல்லது உங்கள் ஸ்கிரிப்டைப் ஆட்மின் ஆக இயக்க வேண்டும். சிம்லிங்குகள் இயக்கப்படாவிட்டால், காசே அமைப்பு இன்னும் வேலை செய்யும் ஆனால் சரியாக செயல்படாது. மேலும் விவரங்களுக்கு [காசே வரையறைகள்](./guides/manage-cache#limitations) பகுதியைப் படிக்கவும். - Hub-இல் கோப்பு பாதைகள் சிறப்பு எழுத்துக்கள் கொண்டதாக இருக்கலாம் (எ.கா. `"path/to?/my/file"`). Windows, [சிறப்பு எழுத்துக்கள்](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names) மீது அதிக கட்டுப்பாடுகளை கொண்டுள்ளது, இது Windows-இல் அந்த கோப்புகளை பதிவிறக்கம் செய்ய முடியாததாக உருவாக்குகிறது. இது நிச்சயமாக ஒரு புலவியல் சந்தர்ப்பமாக இருக்க வேண்டும். இது தவறு என்று நீங்கள் நினைத்தால், அதற்கான தீர்வைத் தேட எங்களை அணுகவும். ## அடுத்த கட்டங்கள் `huggingface_hub` உங்கள் இயந்திரத்தில் முறையாக நிறுவப்பட்ட பிறகு, [சூழல் மாறிலிகளை](package_reference/environment_variables) கட்டமைக்க அல்லது [எங்கள் வழிகாட்டிகளில்](guides/overview) ஒன்றைப் பார்வையிட தேவையெனில், தொடங்குங்கள்.huggingface_hub-1.1.5/i18n/000077500000000000000000000000001510763414300154065ustar00rootroot00000000000000huggingface_hub-1.1.5/i18n/README_cn.md000066400000000000000000000155711510763414300173560ustar00rootroot00000000000000

huggingface_hub library logo

Hugging Face Hub Python 客户端

Documentation GitHub release PyPi version PyPI - Downloads Code coverage

English | Deutsch | हिंदी | 한국어 | 中文（简体）

--- **文档**: https://hf.co/docs/huggingface_hub **源代码**: https://github.com/huggingface/huggingface_hub --- ## 欢迎使用 Hugging Face Hub 库 通过`huggingface_hub` 库，您可以与面向机器学习开发者和协作者的平台 [Hugging Face Hub](https://huggingface.co/)进行交互，找到适用于您所在项目的预训练模型和数据集，体验在平台托管的数百个机器学习应用，还可以创建或分享自己的模型和数据集并于社区共享。以上所有都可以用Python在`huggingface_hub` 库中轻松实现。 ## 主要特点 - [从hugging face hub下载文件](https://huggingface.co/docs/huggingface_hub/en/guides/download) - [上传文件到 hugging face hub](https://huggingface.co/docs/huggingface_hub/en/guides/upload) - [管理您的存储库](https://huggingface.co/docs/huggingface_hub/en/guides/repository) - [在部署的模型上运行推断](https://huggingface.co/docs/huggingface_hub/en/guides/inference) - [搜索模型、数据集和空间](https://huggingface.co/docs/huggingface_hub/en/guides/search) - [分享模型卡片](https://huggingface.co/docs/huggingface_hub/en/guides/model-cards) - [社区互动](https://huggingface.co/docs/huggingface_hub/en/guides/community) ## 安装 使用pip安装 `huggingface_hub` 包： ```bash pip install huggingface_hub ``` 如果您更喜欢，也可以使用 conda 进行安装 为了默认保持包的最小化，huggingface_hub 带有一些可选的依赖项，适用于某些用例。例如，如果您想要完整的推断体验，请运行： ```bash pip install huggingface_hub[inference] ``` 要了解更多安装和可选依赖项，请查看[安装指南](https://huggingface.co/docs/huggingface_hub/cn/安装) ## 快速入门指南 ### 下载文件 下载单个文件,请运行以下代码： ```py from huggingface_hub import hf_hub_download hf_hub_download(repo_id="tiiuae/falcon-7b-instruct", filename="config.json") ``` 如果下载整个存储库，请运行以下代码： ```py from huggingface_hub import snapshot_download snapshot_download("stabilityai/stable-diffusion-2-1") ``` 文件将被下载到本地缓存文件夹。更多详细信息请参阅此 [指南](https://huggingface.co/docs/huggingface_hub/en/guides/manage-cache). ### 登录 Hugging Face Hub 使用令牌对应用进行身份验证(请参阅[文档](https://huggingface.co/docs/hub/security-tokens)). 要登录您的机器，请运行以下命令行： ```bash hf auth login # or using an environment variable hf auth login --token $HUGGINGFACE_TOKEN ``` ### 创建一个存储库 要创建一个新存储库，请运行以下代码： ```py from huggingface_hub import create_repo create_repo(repo_id="super-cool-model") ``` ### 上传文件 上传单个文件,请运行以下代码 ```py from huggingface_hub import upload_file upload_file( path_or_fileobj="/home/lysandre/dummy-test/README.md", path_in_repo="README.md", repo_id="lysandre/test-model", ) ``` 如果上传整个存储库，请运行以下代码： ```py from huggingface_hub import upload_folder upload_folder( folder_path="/path/to/local/space", repo_id="username/my-cool-space", repo_type="space", ) ``` 有关详细信息，请查看 [上传指南](https://huggingface.co/docs/huggingface_hub/en/guides/upload). ## 集成到 Hub 中 我们正在与一些出色的开源机器学习库合作，提供免费的模型托管和版本控制。您可以在 [这里](https://huggingface.co/docs/hub/libraries)找到现有的集成 优势包括: - 为库及其用户提供免费的模型或数据集托管 - 内置文件版本控制，即使对于非常大的文件也能实现，这得益于基于 Git 的方法 - 为所有公开可用的模型提供托管的推断 API - 在网页端可在线体验所有公开的模型 - 任何人都可以上传新模型到您的库，他们只需为模型添加相应的标签，以便让其被发现 - 快速下载！我们使用 Cloudfront（CDN）进行地理复制下载，因此无论在全球任何地方，下载速度都非常快。 - 使用统计和更多功能即将推出 如果您想要集成您的库，请随时打开一个问题来开始讨论。我们编写了一份逐步指南，以❤️的方式展示如何进行这种集成。 ## 欢迎各种贡献（功能请求、错误等） 💙💚💛💜🧡❤️ 欢迎每个人来进行贡献，我们重视每个人的贡献。编写代码并非唯一的帮助社区的方式。回答问题、帮助他人、积极互动并改善文档对社区来说都是极其有价值的。为此我们编写了一份 [贡献指南](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) 以进行总结，即如何开始为这个存储库做贡献 huggingface_hub-1.1.5/i18n/README_de.md000066400000000000000000000175411510763414300173450ustar00rootroot00000000000000

huggingface_hub library logo

Der offizielle Python-Client für den Huggingface Hub.

Dokumentation GitHub release PyPi version PyPI - Downloads Code coverage

English | Deutsch | हिंदी | 한국인 | 中文（简体）

--- **Dokumentation**: https://hf.co/docs/huggingface_hub **Quellcode**: https://github.com/huggingface/huggingface_hub --- ## Willkommen bei der huggingface_hub Bibliothek Die `huggingface_hub` Bibliothek ermöglicht Ihnen die Interaktion mit dem [Hugging Face Hub](https://huggingface.co/), einer Plattform, die Open-Source Machine Learning für Entwickler und Mitwirkende demokratisiert. Entdecken Sie vortrainierte Modelle und Datensätze für Ihre Projekte oder spielen Sie mit den Tausenden von Machine-Learning-Apps, die auf dem Hub gehostet werden. Sie können auch Ihre eigenen Modelle, Datensätze und Demos mit der Community teilen. Die `huggingface_hub` Bibliothek bietet eine einfache Möglichkeit, all dies mit Python zu tun. ## Hauptmerkmale - Dateien vom Hub [herunterladen](https://huggingface.co/docs/huggingface_hub/de/guides/download). - Dateien auf den Hub [hochladen](https://huggingface.co/docs/huggingface_hub/de/guides/upload). - [Verwalten Ihrer Repositories](https://huggingface.co/docs/huggingface_hub/de/guides/repository). - [Ausführen von Inferenz](https://huggingface.co/docs/huggingface_hub/de/guides/inference) auf bereitgestellten Modellen. - [Suche](https://huggingface.co/docs/huggingface_hub/de/guides/search) nach Modellen, Datensätzen und Spaces. - [Model Cards teilen](https://huggingface.co/docs/huggingface_hub/de/guides/model-cards), um Ihre Modelle zu dokumentieren. - [Mit der Community interagieren](https://huggingface.co/docs/huggingface_hub/de/guides/community), durch PRs und Kommentare. ## Installation Installieren Sie das `huggingface_hub` Paket mit [pip](https://pypi.org/project/huggingface-hub/): ```bash pip install huggingface_hub ``` Wenn Sie möchten, können Sie es auch mit [conda](https://huggingface.co/docs/huggingface_hub/de/installation#installieren-mit-conda) installieren. Um das Paket standardmäßig minimal zu halten, kommt `huggingface_hub` mit optionalen Abhängigkeiten, die für einige Anwendungsfälle nützlich sind. Zum Beispiel, wenn Sie ein vollständiges Erlebnis für Inferenz möchten, führen Sie den folgenden Befehl aus: ```bash pip install huggingface_hub[inference] ``` Um mehr über die Installation und optionale Abhängigkeiten zu erfahren, sehen Sie sich bitte den [Installationsleitfaden](https://huggingface.co/docs/huggingface_hub/de/installation) an. ## Schnellstart ### Dateien herunterladen Eine einzelne Datei herunterladen ```py from huggingface_hub import hf_hub_download hf_hub_download(repo_id="tiiuae/falcon-7b-instruct", filename="config.json") ``` Oder eine gesamte Repository ```py from huggingface_hub import snapshot_download snapshot_download("stabilityai/stable-diffusion-2-1") ``` Dateien werden in einen lokalen Cache-Ordner heruntergeladen. Weitere Details finden Sie in diesem [Leitfaden](https://huggingface.co/docs/huggingface_hub/de/guides/manage-cache). ### Anmeldung Der Hugging Face Hub verwendet Tokens zur Authentifizierung von Anwendungen (siehe [Dokumentation](https://huggingface.co/docs/hub/security-tokens)). Um sich an Ihrem Computer anzumelden, führen Sie das folgende Kommando in der Befehlszeile aus: ```bash hf auth login # oder mit einer Umgebungsvariablen hf auth login --token $HUGGINGFACE_TOKEN ``` ### Eine Repository erstellen ```py from huggingface_hub import create_repo create_repo(repo_id="super-cool-model") ``` ### Dateien hochladen Eine einzelne Datei hochladen ```py from huggingface_hub import upload_file upload_file( path_or_fileobj="/home/lysandre/dummy-test/README.md", path_in_repo="README.md", repo_id="lysandre/test-model", ) ``` Oder einen gesamten Ordner ```py from huggingface_hub import upload_folder upload_folder( folder_path="/path/to/local/space", repo_id="username/my-cool-space", repo_type="space", ) ``` Weitere Informationen finden Sie im [Upload-Leitfaden](https://huggingface.co/docs/huggingface_hub/de/guides/upload). ## Integration in den Hub Wir arbeiten mit coolen Open-Source-ML-Bibliotheken zusammen, um kostenloses Model-Hosting und -Versionierung anzubieten. Die bestehenden Integrationen finden Sie [hier](https://huggingface.co/docs/hub/libraries). Die Vorteile sind: - Kostenloses Hosting von Modellen oder Datensätzen für Bibliotheken und deren Benutzer.. - Eingebaute Dateiversionierung, selbst bei sehr großen Dateien, dank eines git-basierten Ansatzes. - Bereitgestellte Inferenz-API für alle öffentlich verfügbaren Modelle. - In-Browser-Widgets zum Spielen mit den hochgeladenen Modellen. - Jeder kann ein neues Modell für Ihre Bibliothek hochladen, es muss nur das entsprechende Tag hinzugefügt werden, damit das Modell auffindbar ist. - Schnelle Downloads! Wir verwenden Cloudfront (ein CDN), um Downloads zu geo-replizieren, sodass sie von überall auf der Welt blitzschnell sind. - Nutzungsstatistiken und mehr Funktionen in Kürze. Wenn Sie Ihre Bibliothek integrieren möchten, öffnen Sie gerne ein Issue, um die Diskussion zu beginnen. Wir haben mit ❤️ einen [schrittweisen Leitfaden](https://huggingface.co/docs/hub/adding-a-library) geschrieben, der zeigt, wie diese Integration durchgeführt wird. ## Beiträge (Feature-Anfragen, Fehler usw.) sind super willkommen 💙💚💛💜🧡❤️ Jeder ist willkommen beizutragen, und wir schätzen den Beitrag jedes Einzelnen. Code zu schreiben ist nicht der einzige Weg, der Community zu helfen. Fragen zu beantworten, anderen zu helfen, sich zu vernetzen und die Dokumentationen zu verbessern, sind für die Gemeinschaft von unschätzbarem Wert. Wir haben einen [Beitrags-Leitfaden](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) geschrieben, der zusammenfasst, wie Sie beginnen können, zu dieser Repository beizutragen. huggingface_hub-1.1.5/i18n/README_fr.md000066400000000000000000000177121510763414300173640ustar00rootroot00000000000000

logo de la bibliothèque huggingface_hub

Le client Python officiel pour le Huggingface Hub.

Documentation Version GitHub Version PyPI PyPI - Téléchargements Couverture du code

English | Deutsch | Français | हिंदी | 한국어 | 中文 (简体)

--- **Documentation** : https://hf.co/docs/huggingface_hub **Code source** : https://github.com/huggingface/huggingface_hub --- ## Bienvenue sur la bibliothèque huggingface_hub La bibliothèque `huggingface_hub` vous permet d’interagir avec le [Hugging Face Hub](https://huggingface.co/), cette plateforme démocratise le Machine Learning en open source pour les créateurs et les collaborateurs du monde entier. Découvrez des modèles et des jeux de données pré-entraînés pour vos projets, ou amusez-vous avec les milliers d’applications de machine learning hébergées sur le Hub. Vous pouvez aussi créer et partager vos propres modèles, vos jeux de données, vos démos avec la communauté. La bibliothèque `huggingface_hub` vous permet de faire ça simplement avec Python. ## Fonctionnalités clés - [Télécharger des fichiers](https://huggingface.co/docs/huggingface_hub/en/guides/download) depuis le Hub. - [Téléverser des fichiers](https://huggingface.co/docs/huggingface_hub/en/guides/upload) vers le Hub. - [Gérer vos dépôts](https://huggingface.co/docs/huggingface_hub/en/guides/repository). - [Exécuter l’inférence](https://huggingface.co/docs/huggingface_hub/en/guides/inference) sur des modèles déployés. - [Rechercher](https://huggingface.co/docs/huggingface_hub/en/guides/search) des modèles, des jeux de données et des Spaces. - [Partager des Model Cards](https://huggingface.co/docs/huggingface_hub/en/guides/model-cards) pour documenter vos modèles. - [Interagir avec la communauté](https://huggingface.co/docs/huggingface_hub/en/guides/community) via des PR et des commentaires. ## Installation Installez le paquet `huggingface_hub` avec [pip](https://pypi.org/project/huggingface-hub/) : ```bash pip install huggingface_hub ``` Si vous préférez, vous pouvez aussi l’installer avec [conda](https://huggingface.co/docs/huggingface_hub/en/installation#install-with-conda). Afin de garder le paquet minimal par défaut, `huggingface_hub` vient avec des dépendances optionnelles utiles pour certains cas d’usage. Par exemple, si vous voulez utiliser le module MCP, exécutez : ```bash pip install "huggingface_hub[mcp]" ``` Pour en savoir plus sur l'installation et les dépendances optionnelles, consultez le [guide d’installation](https://huggingface.co/docs/huggingface_hub/en/installation). ## Démarrage rapide ### Télécharger des fichiers Télécharger un seul fichier ```py from huggingface_hub import hf_hub_download hf_hub_download(repo_id="tiiuae/falcon-7b-instruct", filename="config.json") ``` Ou un dépôt entier ```py from huggingface_hub import snapshot_download snapshot_download("stabilityai/stable-diffusion-2-1") ``` Les fichiers seront téléchargés dans un dossier de cache local. Pour plus d'informations, consultez [ce guide](https://huggingface.co/docs/huggingface_hub/en/guides/manage-cache). ### Connexion Le Hugging Face Hub utilise des jetons d'authentification pour les applications (voir [docs](https://huggingface.co/docs/hub/security-tokens)). Pour vous connecter sur votre machine, exécutez la commande CLI suivante : ```bash hf auth login # ou en utilisant une variable d'environnement hf auth login --token $HUGGINGFACE_TOKEN ``` ### Créer un dépôt ```py from huggingface_hub import create_repo create_repo(repo_id="super-cool-model") ``` ### Téléverser des fichiers Téléverser un seul fichier ```py from huggingface_hub import upload_file upload_file( path_or_fileobj="/home/lysandre/dummy-test/README.md", path_in_repo="README.md", repo_id="lysandre/test-model", ) ``` Ou un dossier entier ```py from huggingface_hub import upload_folder upload_folder( folder_path="/path/to/local/space", repo_id="username/my-cool-space", repo_type="space", ) ``` Pour plus de détails, consultez le [guide de téléversement](https://huggingface.co/docs/huggingface_hub/en/guides/upload). ## Intégrer votre bibliothèque au Hub Nous collaborons avec des bibliothèques de machine learning open source pour offrir gratuitement de l’hébergement et du versionnage de modèles. Vous pouvez trouver les intégrations existantes [ici](https://huggingface.co/docs/hub/libraries). Les avantages sont : - Hébergement gratuit de modèles et des jeux de données pour les bibliothèques et leurs utilisateurs. - Versionnage des fichiers — y compris très volumineux — grâce à Git. - Widgets interactifs dans le navigateur pour essayer les modèles mis en ligne. - N’importe qui peut téléverser un nouveau modèle pour votre bibliothèque, il suffit d’ajouter l’étiquette correspondante pour que le modèle soit disponible. - Téléchargements rapides ! Nous utilisons CloudFront (un CDN) pour géo-répliquer les téléchargements afin qu’ils soient ultra rapides partout dans le monde. - Statistiques d’utilisation et d’autres fonctionnalités à venir. Si vous souhaitez intégrer votre bibliothèque, n’hésitez pas à ouvrir une issue pour lancer la discussion. Nous avons écrit un [guide pas à pas](https://huggingface.co/docs/hub/adding-a-library) avec ❤️ pour vous accompagner. ## Les contributions (demandes de fonctionnalité, bugs, etc.) sont les bienvenues 💙💚💛💜🧡❤️ Tout le monde est le bienvenu pour contribuer, et nous valorisons la contribution de chacun. Le code n’est pas la seule façon d’aider la communauté. Répondre aux questions, aider les autres, prendre contact et améliorer la documentation sont immensément précieux pour la communauté. Nous avons écrit un [guide de contribution](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) pour vous aider à comprendre comment commencer à contribuer à ce dépôt.huggingface_hub-1.1.5/i18n/README_hi.md000066400000000000000000000276471510763414300173650ustar00rootroot00000000000000

huggingface_hub library logo

Huggingface Hub के लिए आधिकारिक पायथन क्लाइंट।

Documentation GitHub release PyPi version PyPI - Downloads Code coverage

English | Deutsch | हिंदी | 한국어 | 中文（简体）

--- **दस्तावेज़ीकरण**: https://hf.co/docs/huggingface_hub **सोर्स कोड**: https://github.com/huggingface/huggingface_hub --- ## huggingface_hub लाइब्रेरी में आपका स्वागत है `huggingface_hub` लाइब्रेरी आपको [हगिंग फेस हब](https://huggingface.co/) के साथ बातचीत करने की अनुमति देती है, जो रचनाकारों और सहयोगियों के लिए ओपन-सोर्स मशीन लर्निंग का लोकतंत्रीकरण करने वाला एक मंच है। अपनी परियोजनाओं के लिए पूर्व-प्रशिक्षित मॉडल और डेटासेट खोजें या हब पर होस्ट किए गए हजारों मशीन लर्निंग ऐप्स के साथ खेलें। आप समुदाय के साथ अपने स्वयं के मॉडल, डेटासेट और डेमो भी बना और साझा कर सकते हैं। `huggingface_hub` लाइब्रेरी पायथन के साथ इन सभी चीजों को करने का एक आसान तरीका प्रदान करती है। ## प्रमुख विशेषताऐं - [फ़ाइलें डाउनलोड करें](https://huggingface.co/docs/huggingface_hub/en/guides/download) हब से। - [फ़ाइलें अपलोड करें](https://huggingface.co/docs/huggingface_hub/en/guides/upload) हब पर। - [अपनी रिपॉजिटरी प्रबंधित करें](https://huggingface.co/docs/huggingface_hub/en/guides/repository)। - तैनात मॉडलों पर [अनुमान चलाएँ](https://huggingface.co/docs/huggingface_hub/en/guides/inference)। - मॉडल, डेटासेट और स्पेस के लिए [खोज](https://huggingface.co/docs/huggingface_hub/en/guides/search)। - [मॉडल कार्ड साझा करें](https://huggingface.co/docs/huggingface_hub/en/guides/model-cards) अपने मॉडलों का दस्तावेजीकरण करने के लिए। - [समुदाय के साथ जुड़ें](https://huggingface.co/docs/huggingface_hub/en/guides/community) पीआर और टिप्पणियों के माध्यम से। ## स्थापना [pip](https://pypi.org/project/huggingface-hub/) के साथ `huggingface_hub` पैकेज इंस्टॉल करें: ```bash pip install huggingface_hub ``` यदि आप चाहें, तो आप इसे [conda](https://huggingface.co/docs/huggingface_hub/en/installation#install-with-conda) से भी इंस्टॉल कर सकते हैं। पैकेज को डिफ़ॉल्ट रूप से न्यूनतम रखने के लिए, `huggingface_hub` कुछ उपयोग मामलों के लिए उपयोगी वैकल्पिक निर्भरता के साथ आता है। उदाहरण के लिए, यदि आप अनुमान के लिए संपूर्ण अनुभव चाहते हैं, तो चलाएँ: ```bash pip install huggingface_hub[inference] ``` अधिक इंस्टॉलेशन और वैकल्पिक निर्भरता जानने के लिए, [इंस्टॉलेशन गाइड](https://huggingface.co/docs/huggingface_hub/en/installation) देखें। ## जल्दी शुरू ### फ़ाइलें डाउनलोड करें एकल फ़ाइल डाउनलोड करें ```py from huggingface_hub import hf_hub_download hf_hub_download(repo_id="tiiuae/falcon-7b-instruct", filename="config.json") ``` या एक संपूर्ण भंडार ```py from huggingface_hub import snapshot_download snapshot_download("stabilityai/stable-diffusion-2-1") ``` फ़ाइलें स्थानीय कैश फ़ोल्डर में डाउनलोड की जाएंगी. [this_guide] में अधिक विवरण (https://huggingface.co/docs/huggingface_hub/en/guides/manage-cache)। ### लॉग इन करें Hugging Face Hub एप्लिकेशन को प्रमाणित करने के लिए टोकन का उपयोग करता है (देखें [docs](https://huggingface.co/docs/hub/security-tokens))। अपनी मशीन में लॉगिन करने के लिए, निम्नलिखित सीएलआई चलाएँ: ```bash hf auth login # या कृपया इसे एक पर्यावरण चर के रूप में निर्दिष्ट करें। hf auth login --token $HUGGINGFACE_TOKEN ``` ### एक रिपॉजिटरी बनाएं ```py from huggingface_hub import create_repo create_repo(repo_id="super-cool-model") ``` ### फाइलें अपलोड करें एकल फ़ाइल अपलोड करें ```py from huggingface_hub import upload_file upload_file( path_or_fileobj="/home/lysandre/dummy-test/README.md", path_in_repo="README.md", repo_id="lysandre/test-model", ) ``` या एक संपूर्ण फ़ोल्डर ```py from huggingface_hub import upload_folder upload_folder( folder_path="/path/to/local/space", repo_id="username/my-cool-space", repo_type="space", ) ``` [अपलोड गाइड](https://huggingface.co/docs/huggingface_hub/en/guides/upload) में विवरण के लिए। ## हब से एकीकरण। हम मुफ्त मॉडल होस्टिंग और वर्जनिंग प्रदान करने के लिए शानदार ओपन सोर्स एमएल लाइब्रेरीज़ के साथ साझेदारी कर रहे हैं। आप मौजूदा एकीकरण [यहां](https://huggingface.co/docs/hub/libraries) पा सकते हैं। फायदे ये हैं: - पुस्तकालयों और उनके उपयोगकर्ताओं के लिए निःशुल्क मॉडल या डेटासेट होस्टिंग। - गिट-आधारित दृष्टिकोण के कारण, बहुत बड़ी फ़ाइलों के साथ भी अंतर्निहित फ़ाइल संस्करणिंग। - सभी मॉडलों के लिए होस्टेड अनुमान एपीआई सार्वजनिक रूप से उपलब्ध है। - अपलोड किए गए मॉडलों के साथ खेलने के लिए इन-ब्राउज़र विजेट। - कोई भी आपकी लाइब्रेरी के लिए एक नया मॉडल अपलोड कर सकता है, उन्हें मॉडल को खोजने योग्य बनाने के लिए बस संबंधित टैग जोड़ना होगा। - तेज़ डाउनलोड! हम डाउनलोड को जियो-रेप्लिकेट करने के लिए क्लाउडफ्रंट (एक सीडीएन) का उपयोग करते हैं ताकि वे दुनिया में कहीं से भी तेजी से चमक सकें। - उपयोग आँकड़े और अधिक सुविधाएँ आने वाली हैं। यदि आप अपनी लाइब्रेरी को एकीकृत करना चाहते हैं, तो चर्चा शुरू करने के लिए बेझिझक एक मुद्दा खोलें। हमने ❤️ के साथ एक [चरण-दर-चरण मार्गदर्शिका](https://huggingface.co/docs/hub/adding-a-library) लिखी, जिसमें दिखाया गया कि यह एकीकरण कैसे करना है। ## योगदान (सुविधा अनुरोध, बग, आदि) का अति स्वागत है 💙💚💛💜🧡❤️ योगदान के लिए हर किसी का स्वागत है और हम हर किसी के योगदान को महत्व देते हैं। कोड समुदाय की मदद करने का एकमात्र तरीका नहीं है। प्रश्नों का उत्तर देना, दूसरों की मदद करना, उन तक पहुंचना और दस्तावेज़ों में सुधार करना समुदाय के लिए बेहद मूल्यवान है। हमने संक्षेप में बताने के लिए एक [योगदान मार्गदर्शिका](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md) लिखी है इस भंडार में योगदान करने की शुरुआत कैसे करें। huggingface_hub-1.1.5/i18n/README_ko.md000066400000000000000000000177171510763414300173730ustar00rootroot00000000000000

huggingface_hub library logo

공식 Huggingface Hub 파이썬 클라이언트

Documentation GitHub release PyPi version PyPI - Downloads Code coverage

English | Deutsch | हिंदी | 한국어| 中文（简体）

--- **기술 문서**: https://hf.co/docs/huggingface_hub **소스 코드**: https://github.com/huggingface/huggingface_hub --- ## huggingface_hub 라이브러리 개요 `huggingface_hub` 라이브러리는 [Hugging Face Hub](https://huggingface.co/)와 상호작용할 수 있게 해줍니다. Hugging Face Hub는 창작자와 협업자를 위한 오픈소스 머신러닝 플랫폼입니다. 여러분의 프로젝트에 적합한 사전 훈련된 모델과 데이터셋을 발견하거나, Hub에 호스팅된 수천 개의 머신러닝 앱들을 사용해보세요. 또한, 여러분이 만든 모델, 데이터셋, 데모를 커뮤니티와 공유할 수도 있습니다. `huggingface_hub` 라이브러리는 파이썬으로 이 모든 것을 간단하게 할 수 있는 방법을 제공합니다. ## 주요 기능 - Hub에서 [파일을 다운로드](https://huggingface.co/docs/huggingface_hub/main/ko/guides/download) - Hub에 [파일을 업로드](https://huggingface.co/docs/huggingface_hub/main/en/guides/upload) (영어) - [레포지토리를 관리](https://huggingface.co/docs/huggingface_hub/main/en/guides/repository) (영어) - 배포된 모델에 [추론을 실행](https://huggingface.co/docs/huggingface_hub/main/en/guides/inference) (영어) - 모델, 데이터셋, Space를 [검색](https://huggingface.co/docs/huggingface_hub/main/en/guides/search) (영어) - [모델 카드를 공유](https://huggingface.co/docs/huggingface_hub/main/en/guides/model-cards)하여 모델을 문서화 (영어) - PR과 댓글을 통해 [커뮤니티와 소통](https://huggingface.co/docs/huggingface_hub/main/en/guides/community) (영어) ## 설치 [pip](https://pypi.org/project/huggingface-hub/)로 `huggingface_hub` 패키지를 설치하세요: ```bash pip install huggingface_hub ``` 원한다면 [conda](https://huggingface.co/docs/huggingface_hub/ko/installation#install-with-conda)를 이용하여 설치할 수도 있습니다. 기본 패키지를 작게 유지하기 위해 `huggingface_hub`는 유용한 의존성을 추가적으로 제공합니다. 추론과 관련된 기능을 원한다면, 아래를 실행하세요: ```bash pip install huggingface_hub[inference] ``` 설치와 선택적 의존성에 대해 더 알아보려면, [설치 가이드](https://huggingface.co/docs/huggingface_hub/ko/installation)를 참고하세요. ## 맛보기 ### 파일 다운로드 파일 하나의 경우: ```py from huggingface_hub import hf_hub_download hf_hub_download(repo_id="tiiuae/falcon-7b-instruct", filename="config.json") ``` 레포지토리 전체의 경우: ```py from huggingface_hub import snapshot_download snapshot_download("stabilityai/stable-diffusion-2-1") ``` 파일은 로컬 캐시 폴더에 다운로드됩니다. 자세한 내용은 [이 가이드](https://huggingface.co/docs/huggingface_hub/ko/guides/manage-cache)를 참조하세요. ### 로그인 Hugging Face Hub는 토큰을 사용하여 애플리케이션을 인증합니다([문서](https://huggingface.co/docs/hub/security-tokens) 참조). 컴퓨터에서 로그인하려면 CLI를 사용하세요: ```bash hf auth login # 또는 환경 변수로 지정해주세요 hf auth login --token $HUGGINGFACE_TOKEN ``` ### 레포지토리 생성 ```py from huggingface_hub import create_repo create_repo(repo_id="super-cool-model") ``` ### 파일 업로드 파일 하나의 경우: ```py from huggingface_hub import upload_file upload_file( path_or_fileobj="/home/lysandre/dummy-test/README.md", path_in_repo="README.md", repo_id="lysandre/test-model", ) ``` 레포지토리 전체의 경우: ```py from huggingface_hub import upload_folder upload_folder( folder_path="/path/to/local/space", repo_id="username/my-cool-space", repo_type="space", ) ``` 자세한 내용은 [업로드 가이드](https://huggingface.co/docs/huggingface_hub/ko/guides/upload)를 참조하세요. ## Hugging Face Hub와 함께 성장하기 저희는 멋진 오픈소스 ML 라이브러리들과 협력하여, 모델 호스팅과 버전 관리를 무료로 제공하고 있습니다. 이미 통합된 라이브러리들은 [여기](https://huggingface.co/docs/hub/libraries)서 확인할 수 있습니다. 이렇게 하면 다음과 같은 장점이 있습니다: - 라이브러리 사용자들의 모델이나 데이터셋을 무료로 호스팅해줍니다. - git을 기반으로 한 방식으로, 아주 큰 파일들도 버전을 관리할 수 있습니다. - 공개된 모든 모델에 대해 추론 API를 호스팅해줍니다. - 업로드된 모델들을 브라우저에서 쉽게 사용할 수 있는 위젯을 제공합니다. - 누구나 여러분의 라이브러리에 새로운 모델을 업로드할 수 있습니다. 모델이 검색될 수 있도록 해당 태그만 추가하면 됩니다. - 다운로드 속도가 매우 빠릅니다! 왜냐하면 Cloudfront (CDN)를 이용하여 전 세계 어디에서나 빠르게 다운로드할 수 있도록 지역적으로 복제해뒀기 때문입니다. - 사용 통계와 더 많은 기능들을 제공합니다. 여러분의 라이브러리를 통합하고 싶다면, 이슈를 열어서 의견을 나눠주세요. 통합 과정을 안내하기 위해 ❤️을 담아 [단계별 가이드](https://huggingface.co/docs/hub/adding-a-library)를 작성했습니다. ## (기능 요청, 버그 패치 등의) 기여는 대환영입니다 💙💚💛💜🧡❤️ 모든 분들의 기여를 환영하며, 소중히 생각합니다. 코드 작성만이 커뮤니티에 도움을 주는 유일한 방법이 아니에요. 질문에 답하거나, 다른 분들을 돕거나, 컨택하거나, 문서를 개선하는 것도 커뮤니티에 큰 도움이 됩니다. 지금 시작하려면 간단한 [기여 가이드](https://github.com/huggingface/huggingface_hub/blob/main/CONTRIBUTING.md)를 참조해주세요. huggingface_hub-1.1.5/pyproject.toml000066400000000000000000000034701510763414300175470ustar00rootroot00000000000000[tool.mypy] ignore_missing_imports = true [tool.ty] [tool.ty.terminal] # Do not fail CI on warnings; keep output readable error-on-warning = false output-format = "concise" [tool.ty.rules] # Minimize noise from optional/extra dependencies not installed in CI or local unresolved-import = "ignore" unresolved-attribute = "ignore" # Be tolerant with framework/typing edge-cases and runtime-validated code paths unsupported-base = "ignore" unsupported-operator = "ignore" possibly-missing-attribute = "ignore" possibly-missing-implicit-call = "ignore" non-subscriptable = "ignore" call-non-callable = "ignore" # Loosen strictness a bit on type matching missing-argument = "ignore" deprecated = "ignore" [tool.pytest.ini_options] # Add the specified `OPTS` to the set of command line arguments as if they had # been specified by the user. addopts = "-Werror::FutureWarning --log-cli-level=INFO -sv --durations=0" # The defined variables will be added to the environment before any tests are # run, part of pytest-env plugin env = [ "DISABLE_SYMLINKS_IN_WINDOWS_TESTS=1", "HF_TOKEN=", "HUGGINGFACE_CO_STAGING=1", "HUGGING_FACE_HUB_TOKEN=", ] [tool.ruff] exclude = [ ".eggs", ".git", ".git-rewrite", ".hg", ".mypy_cache", ".nox", ".pants.d", ".pytype", ".ruff_cache", ".svn", ".tox", ".venv", ".venv*", "__pypackages__", "_build", "build", "dist", "venv", ] line-length = 119 # Ignored rules: # "E501" -> line length violation lint.ignore = ["E501"] lint.select = ["E", "F", "I", "W"] [tool.ruff.lint.isort] known-first-party = ["huggingface_hub"] lines-after-imports = 2 [tool.tomlsort] all = true in_place = true spaces_before_inline_comment = 2 # Match Python PEP 8 spaces_indent_inline_array = 4 # Match Python PEP 8 trailing_comma_inline_array = true huggingface_hub-1.1.5/setup.py000066400000000000000000000110771510763414300163470ustar00rootroot00000000000000import sys from setuptools import find_packages, setup def get_version() -> str: rel_path = "src/huggingface_hub/__init__.py" with open(rel_path, "r") as fp: for line in fp.read().splitlines(): if line.startswith("__version__"): delim = '"' if '"' in line else "'" return line.split(delim)[1] raise RuntimeError("Unable to find version string.") install_requires = [ "filelock", "fsspec>=2023.5.0", "hf-xet>=1.2.0,<2.0.0; platform_machine=='x86_64' or platform_machine=='amd64' or platform_machine=='AMD64' or platform_machine=='arm64' or platform_machine=='aarch64'", "httpx>=0.23.0, <1", "packaging>=20.9", "pyyaml>=5.1", "shellingham", "tqdm>=4.42.1", "typer-slim", "typing-extensions>=3.7.4.3", # to be able to import TypeAlias ] extras = {} extras["oauth"] = [ "authlib>=1.3.2", # minimum version to include https://github.com/lepture/authlib/pull/644 "fastapi", "httpx", # required for authlib but not included in its dependencies "itsdangerous", # required for starlette SessionMiddleware ] extras["torch"] = [ "torch", "safetensors[torch]", ] extras["fastai"] = [ "toml", "fastai>=2.4", "fastcore>=1.3.27", ] extras["hf_xet"] = ["hf-xet>=1.1.3,<2.0.0"] extras["mcp"] = ["mcp>=1.8.0"] extras["testing"] = ( extras["oauth"] + [ "jedi", "Jinja2", "pytest>=8.4.2", # we need https://github.com/pytest-dev/pytest/pull/12436 "pytest-cov", "pytest-env", "pytest-xdist", "pytest-vcr", # to mock Inference "pytest-asyncio", # for AsyncInferenceClient "pytest-rerunfailures<16.0", # to rerun flaky tests in CI "pytest-mock", "urllib3<2.0", # VCR.py broken with urllib3 2.0 (see https://urllib3.readthedocs.io/en/stable/v2-migration-guide.html) "soundfile", "Pillow", "numpy", # for embeddings "fastapi", # To build the documentation ] ) if sys.version_info >= (3, 10): # We need gradio to test webhooks server # But gradio 5.0+ only supports python 3.10+ so we don't want to test earlier versions extras["gradio"] = [ "gradio>=5.0.0", "requests", # see https://github.com/gradio-app/gradio/pull/11830 ] # Typing extra dependencies list is duplicated in `.pre-commit-config.yaml` # Please make sure to update the list there when adding a new typing dependency. extras["typing"] = [ "typing-extensions>=4.8.0", "types-PyYAML", "types-simplejson", "types-toml", "types-tqdm", "types-urllib3", ] extras["quality"] = [ "ruff>=0.9.0", "mypy==1.15.0", "libcst>=1.4.0", "ty", ] extras["all"] = extras["testing"] + extras["quality"] + extras["typing"] extras["dev"] = extras["all"] setup( name="huggingface_hub", version=get_version(), author="Hugging Face, Inc.", author_email="julien@huggingface.co", description="Client library to download and publish models, datasets and other repos on the huggingface.co hub", long_description=open("README.md", "r", encoding="utf-8").read(), long_description_content_type="text/markdown", keywords="model-hub machine-learning models natural-language-processing deep-learning pytorch pretrained-models", license="Apache", url="https://github.com/huggingface/huggingface_hub", package_dir={"": "src"}, packages=find_packages("src"), extras_require=extras, entry_points={ "console_scripts": [ "hf=huggingface_hub.cli.hf:main", "tiny-agents=huggingface_hub.inference._mcp.cli:app", ], "fsspec.specs": "hf=huggingface_hub.HfFileSystem", }, python_requires=">=3.9.0", install_requires=install_requires, classifiers=[ "Intended Audience :: Developers", "Intended Audience :: Education", "Intended Audience :: Science/Research", "License :: OSI Approved :: Apache Software License", "Operating System :: OS Independent", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", "Programming Language :: Python :: 3.12", "Programming Language :: Python :: 3.13", "Programming Language :: Python :: 3.14", "Topic :: Scientific/Engineering :: Artificial Intelligence", ], include_package_data=True, package_data={"huggingface_hub": ["py.typed"]}, # Needed for wheel installation ) huggingface_hub-1.1.5/src/000077500000000000000000000000001510763414300154165ustar00rootroot00000000000000huggingface_hub-1.1.5/src/huggingface_hub/000077500000000000000000000000001510763414300205235ustar00rootroot00000000000000huggingface_hub-1.1.5/src/huggingface_hub/README.md000066400000000000000000000101711510763414300220020ustar00rootroot00000000000000# Hugging Face Hub Client library ## Download files from the Hub The `hf_hub_download()` function is the main function to download files from the Hub. One advantage of using it is that files are cached locally, so you won't have to download the files multiple times. If there are changes in the repository, the files will be automatically downloaded again. ### `hf_hub_download` The function takes the following parameters, downloads the remote file, stores it to disk (in a version-aware way) and returns its local file path. Parameters: - a `repo_id` (a user or organization name and a repo name, separated by `/`, like `julien-c/EsperBERTo-small`) - a `filename` (like `pytorch_model.bin`) - an optional Git revision id (can be a branch name, a tag, or a commit hash) - a `cache_dir` which you can specify if you want to control where on disk the files are cached. ```python from huggingface_hub import hf_hub_download hf_hub_download("lysandre/arxiv-nlp", filename="config.json") ``` ### `snapshot_download` Using `hf_hub_download()` works well when you know which files you want to download; for example a model file alongside a configuration file, both with static names. There are cases in which you will prefer to download all the files of the remote repository at a specified revision. That's what `snapshot_download()` does. It downloads and stores a remote repository to disk (in a versioning-aware way) and returns its local file path. Parameters: - a `repo_id` in the format `namespace/repository` - a `revision` on which the repository will be downloaded - a `cache_dir` which you can specify if you want to control where on disk the files are cached ### `hf_hub_url` Internally, the library uses `hf_hub_url()` to return the URL to download the actual files: `https://huggingface.co/julien-c/EsperBERTo-small/resolve/main/pytorch_model.bin` Parameters: - a `repo_id` (a user or organization name and a repo name separated by a `/`, like `julien-c/EsperBERTo-small`) - a `filename` (like `pytorch_model.bin`) - an optional `subfolder`, corresponding to a folder inside the model repo - an optional `repo_type`, such as `dataset` or `space` - an optional Git revision id (can be a branch name, a tag, or a commit hash) If you check out this URL's headers with a `HEAD` http request (which you can do from the command line with `curl -I`) for a few different files, you'll see that: - small files are returned directly - large files (i.e. the ones stored through [git-lfs](https://git-lfs.github.com/)) are returned via a redirect to a Cloudfront URL. Cloudfront is a Content Delivery Network, or CDN, that ensures that downloads are as fast as possible from anywhere on the globe.
## Publish files to the Hub If you've used Git before, this will be very easy since Git is used to manage files in the Hub. You can find a step-by-step guide on how to upload your model to the Hub: https://huggingface.co/docs/hub/adding-a-model. ### API utilities in `hf_api.py` You don't need them for the standard publishing workflow (i.e. using git command line), however, if you need a programmatic way of creating a repo, deleting it (`⚠️ caution`), pushing a single file to a repo or listing models from the Hub, you'll find helpers in `hf_api.py`. Some example functionality available with the `HfApi` class: * `whoami()` * `create_repo()` * `list_repo_files()` * `list_repo_objects()` * `delete_repo()` * `update_repo_settings()` * `create_commit()` * `upload_file()` * `delete_file()` * `delete_folder()` Those API utilities are also exposed through the `hf` CLI: ```bash hf auth login hf auth logout hf auth whoami hf repo create ``` With the `HfApi` class there are methods to query models, datasets, and Spaces by specific tags (e.g. if you want to list models compatible with your library): - **Models**: - `list_models()` - `model_info()` - `get_model_tags()` - **Datasets**: - `list_datasets()` - `dataset_info()` - `get_dataset_tags()` - **Spaces**: - `list_spaces()` - `space_info()` These lightly wrap around the API Endpoints. Documentation for valid parameters and descriptions can be found [here](https://huggingface.co/docs/hub/endpoints). huggingface_hub-1.1.5/src/huggingface_hub/__init__.py000066400000000000000000001463661510763414300226540ustar00rootroot00000000000000# Copyright 2020 The HuggingFace Team. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # *********** # `huggingface_hub` init has 2 modes: # - Normal usage: # If imported to use it, all modules and functions are lazy-loaded. This means # they exist at top level in module but are imported only the first time they are # used. This way, `from huggingface_hub import something` will import `something` # quickly without the hassle of importing all the features from `huggingface_hub`. # - Static check: # If statically analyzed, all modules and functions are loaded normally. This way # static typing check works properly as well as autocomplete in text editors and # IDEs. # # The static model imports are done inside the `if TYPE_CHECKING:` statement at # the bottom of this file. Since module/functions imports are duplicated, it is # mandatory to make sure to add them twice when adding one. This is checked in the # `make quality` command. # # To update the static imports, please run the following command and commit the changes. # ``` # # Use script # python utils/check_static_imports.py --update-file # # # Or run style on codebase # make style # ``` # # *********** # Lazy loader vendored from https://github.com/scientific-python/lazy_loader import importlib import os import sys from typing import TYPE_CHECKING __version__ = "1.1.5" # Alphabetical order of definitions is ensured in tests # WARNING: any comment added in this dictionary definition will be lost when # re-generating the file ! _SUBMOD_ATTRS = { "_commit_scheduler": [ "CommitScheduler", ], "_inference_endpoints": [ "InferenceEndpoint", "InferenceEndpointError", "InferenceEndpointStatus", "InferenceEndpointTimeoutError", "InferenceEndpointType", ], "_jobs_api": [ "JobInfo", "JobOwner", "JobStage", "JobStatus", ], "_login": [ "auth_list", "auth_switch", "interpreter_login", "login", "logout", "notebook_login", ], "_oauth": [ "OAuthInfo", "OAuthOrgInfo", "OAuthUserInfo", "attach_huggingface_oauth", "parse_huggingface_oauth", ], "_snapshot_download": [ "snapshot_download", ], "_space_api": [ "SpaceHardware", "SpaceRuntime", "SpaceStage", "SpaceStorage", "SpaceVariable", ], "_tensorboard_logger": [ "HFSummaryWriter", ], "_webhooks_payload": [ "WebhookPayload", "WebhookPayloadComment", "WebhookPayloadDiscussion", "WebhookPayloadDiscussionChanges", "WebhookPayloadEvent", "WebhookPayloadMovedTo", "WebhookPayloadRepo", "WebhookPayloadUrl", "WebhookPayloadWebhook", ], "_webhooks_server": [ "WebhooksServer", "webhook_endpoint", ], "cli._cli_utils": [ "typer_factory", ], "community": [ "Discussion", "DiscussionComment", "DiscussionCommit", "DiscussionEvent", "DiscussionStatusChange", "DiscussionTitleChange", "DiscussionWithDetails", ], "constants": [ "CONFIG_NAME", "FLAX_WEIGHTS_NAME", "HUGGINGFACE_CO_URL_HOME", "HUGGINGFACE_CO_URL_TEMPLATE", "PYTORCH_WEIGHTS_NAME", "REPO_TYPE_DATASET", "REPO_TYPE_MODEL", "REPO_TYPE_SPACE", "TF2_WEIGHTS_NAME", "TF_WEIGHTS_NAME", ], "fastai_utils": [ "_save_pretrained_fastai", "from_pretrained_fastai", "push_to_hub_fastai", ], "file_download": [ "DryRunFileInfo", "HfFileMetadata", "_CACHED_NO_EXIST", "get_hf_file_metadata", "hf_hub_download", "hf_hub_url", "try_to_load_from_cache", ], "hf_api": [ "Collection", "CollectionItem", "CommitInfo", "CommitOperation", "CommitOperationAdd", "CommitOperationCopy", "CommitOperationDelete", "DatasetInfo", "GitCommitInfo", "GitRefInfo", "GitRefs", "HfApi", "ModelInfo", "Organization", "RepoUrl", "SpaceInfo", "User", "UserLikes", "WebhookInfo", "WebhookWatchedItem", "accept_access_request", "add_collection_item", "add_space_secret", "add_space_variable", "auth_check", "cancel_access_request", "cancel_job", "change_discussion_status", "comment_discussion", "create_branch", "create_collection", "create_commit", "create_discussion", "create_inference_endpoint", "create_inference_endpoint_from_catalog", "create_pull_request", "create_repo", "create_scheduled_job", "create_scheduled_uv_job", "create_tag", "create_webhook", "dataset_info", "delete_branch", "delete_collection", "delete_collection_item", "delete_file", "delete_folder", "delete_inference_endpoint", "delete_repo", "delete_scheduled_job", "delete_space_secret", "delete_space_storage", "delete_space_variable", "delete_tag", "delete_webhook", "disable_webhook", "duplicate_space", "edit_discussion_comment", "enable_webhook", "fetch_job_logs", "file_exists", "get_collection", "get_dataset_tags", "get_discussion_details", "get_full_repo_name", "get_inference_endpoint", "get_model_tags", "get_organization_overview", "get_paths_info", "get_repo_discussions", "get_safetensors_metadata", "get_space_runtime", "get_space_variables", "get_user_overview", "get_webhook", "grant_access", "inspect_job", "inspect_scheduled_job", "list_accepted_access_requests", "list_collections", "list_datasets", "list_inference_catalog", "list_inference_endpoints", "list_jobs", "list_lfs_files", "list_liked_repos", "list_models", "list_organization_followers", "list_organization_members", "list_papers", "list_pending_access_requests", "list_rejected_access_requests", "list_repo_commits", "list_repo_files", "list_repo_likers", "list_repo_refs", "list_repo_tree", "list_spaces", "list_user_followers", "list_user_following", "list_webhooks", "merge_pull_request", "model_info", "move_repo", "paper_info", "parse_safetensors_file_metadata", "pause_inference_endpoint", "pause_space", "permanently_delete_lfs_files", "preupload_lfs_files", "reject_access_request", "rename_discussion", "repo_exists", "repo_info", "repo_type_and_id_from_hf_id", "request_space_hardware", "request_space_storage", "restart_space", "resume_inference_endpoint", "resume_scheduled_job", "revision_exists", "run_as_future", "run_job", "run_uv_job", "scale_to_zero_inference_endpoint", "set_space_sleep_time", "space_info", "super_squash_history", "suspend_scheduled_job", "unlike", "update_collection_item", "update_collection_metadata", "update_inference_endpoint", "update_repo_settings", "update_webhook", "upload_file", "upload_folder", "upload_large_folder", "verify_repo_checksums", "whoami", ], "hf_file_system": [ "HfFileSystem", "HfFileSystemFile", "HfFileSystemResolvedPath", "HfFileSystemStreamFile", ], "hub_mixin": [ "ModelHubMixin", "PyTorchModelHubMixin", ], "inference._client": [ "InferenceClient", "InferenceTimeoutError", ], "inference._generated._async_client": [ "AsyncInferenceClient", ], "inference._generated.types": [ "AudioClassificationInput", "AudioClassificationOutputElement", "AudioClassificationOutputTransform", "AudioClassificationParameters", "AudioToAudioInput", "AudioToAudioOutputElement", "AutomaticSpeechRecognitionEarlyStoppingEnum", "AutomaticSpeechRecognitionGenerationParameters", "AutomaticSpeechRecognitionInput", "AutomaticSpeechRecognitionOutput", "AutomaticSpeechRecognitionOutputChunk", "AutomaticSpeechRecognitionParameters", "ChatCompletionInput", "ChatCompletionInputFunctionDefinition", "ChatCompletionInputFunctionName", "ChatCompletionInputGrammarType", "ChatCompletionInputJSONSchema", "ChatCompletionInputMessage", "ChatCompletionInputMessageChunk", "ChatCompletionInputMessageChunkType", "ChatCompletionInputResponseFormatJSONObject", "ChatCompletionInputResponseFormatJSONSchema", "ChatCompletionInputResponseFormatText", "ChatCompletionInputStreamOptions", "ChatCompletionInputTool", "ChatCompletionInputToolCall", "ChatCompletionInputToolChoiceClass", "ChatCompletionInputToolChoiceEnum", "ChatCompletionInputURL", "ChatCompletionOutput", "ChatCompletionOutputComplete", "ChatCompletionOutputFunctionDefinition", "ChatCompletionOutputLogprob", "ChatCompletionOutputLogprobs", "ChatCompletionOutputMessage", "ChatCompletionOutputToolCall", "ChatCompletionOutputTopLogprob", "ChatCompletionOutputUsage", "ChatCompletionStreamOutput", "ChatCompletionStreamOutputChoice", "ChatCompletionStreamOutputDelta", "ChatCompletionStreamOutputDeltaToolCall", "ChatCompletionStreamOutputFunction", "ChatCompletionStreamOutputLogprob", "ChatCompletionStreamOutputLogprobs", "ChatCompletionStreamOutputTopLogprob", "ChatCompletionStreamOutputUsage", "DepthEstimationInput", "DepthEstimationOutput", "DocumentQuestionAnsweringInput", "DocumentQuestionAnsweringInputData", "DocumentQuestionAnsweringOutputElement", "DocumentQuestionAnsweringParameters", "FeatureExtractionInput", "FeatureExtractionInputTruncationDirection", "FillMaskInput", "FillMaskOutputElement", "FillMaskParameters", "ImageClassificationInput", "ImageClassificationOutputElement", "ImageClassificationOutputTransform", "ImageClassificationParameters", "ImageSegmentationInput", "ImageSegmentationOutputElement", "ImageSegmentationParameters", "ImageSegmentationSubtask", "ImageToImageInput", "ImageToImageOutput", "ImageToImageParameters", "ImageToImageTargetSize", "ImageToTextEarlyStoppingEnum", "ImageToTextGenerationParameters", "ImageToTextInput", "ImageToTextOutput", "ImageToTextParameters", "ImageToVideoInput", "ImageToVideoOutput", "ImageToVideoParameters", "ImageToVideoTargetSize", "ObjectDetectionBoundingBox", "ObjectDetectionInput", "ObjectDetectionOutputElement", "ObjectDetectionParameters", "Padding", "QuestionAnsweringInput", "QuestionAnsweringInputData", "QuestionAnsweringOutputElement", "QuestionAnsweringParameters", "SentenceSimilarityInput", "SentenceSimilarityInputData", "SummarizationInput", "SummarizationOutput", "SummarizationParameters", "SummarizationTruncationStrategy", "TableQuestionAnsweringInput", "TableQuestionAnsweringInputData", "TableQuestionAnsweringOutputElement", "TableQuestionAnsweringParameters", "Text2TextGenerationInput", "Text2TextGenerationOutput", "Text2TextGenerationParameters", "Text2TextGenerationTruncationStrategy", "TextClassificationInput", "TextClassificationOutputElement", "TextClassificationOutputTransform", "TextClassificationParameters", "TextGenerationInput", "TextGenerationInputGenerateParameters", "TextGenerationInputGrammarType", "TextGenerationOutput", "TextGenerationOutputBestOfSequence", "TextGenerationOutputDetails", "TextGenerationOutputFinishReason", "TextGenerationOutputPrefillToken", "TextGenerationOutputToken", "TextGenerationStreamOutput", "TextGenerationStreamOutputStreamDetails", "TextGenerationStreamOutputToken", "TextToAudioEarlyStoppingEnum", "TextToAudioGenerationParameters", "TextToAudioInput", "TextToAudioOutput", "TextToAudioParameters", "TextToImageInput", "TextToImageOutput", "TextToImageParameters", "TextToSpeechEarlyStoppingEnum", "TextToSpeechGenerationParameters", "TextToSpeechInput", "TextToSpeechOutput", "TextToSpeechParameters", "TextToVideoInput", "TextToVideoOutput", "TextToVideoParameters", "TokenClassificationAggregationStrategy", "TokenClassificationInput", "TokenClassificationOutputElement", "TokenClassificationParameters", "TranslationInput", "TranslationOutput", "TranslationParameters", "TranslationTruncationStrategy", "TypeEnum", "VideoClassificationInput", "VideoClassificationOutputElement", "VideoClassificationOutputTransform", "VideoClassificationParameters", "VisualQuestionAnsweringInput", "VisualQuestionAnsweringInputData", "VisualQuestionAnsweringOutputElement", "VisualQuestionAnsweringParameters", "ZeroShotClassificationInput", "ZeroShotClassificationOutputElement", "ZeroShotClassificationParameters", "ZeroShotImageClassificationInput", "ZeroShotImageClassificationOutputElement", "ZeroShotImageClassificationParameters", "ZeroShotObjectDetectionBoundingBox", "ZeroShotObjectDetectionInput", "ZeroShotObjectDetectionOutputElement", "ZeroShotObjectDetectionParameters", ], "inference._mcp.agent": [ "Agent", ], "inference._mcp.mcp_client": [ "MCPClient", ], "repocard": [ "DatasetCard", "ModelCard", "RepoCard", "SpaceCard", "metadata_eval_result", "metadata_load", "metadata_save", "metadata_update", ], "repocard_data": [ "CardData", "DatasetCardData", "EvalResult", "ModelCardData", "SpaceCardData", ], "serialization": [ "StateDictSplit", "get_torch_storage_id", "get_torch_storage_size", "load_state_dict_from_file", "load_torch_model", "save_torch_model", "save_torch_state_dict", "split_state_dict_into_shards_factory", "split_torch_state_dict_into_shards", ], "serialization._dduf": [ "DDUFEntry", "export_entries_as_dduf", "export_folder_as_dduf", "read_dduf_file", ], "utils": [ "ASYNC_CLIENT_FACTORY_T", "CLIENT_FACTORY_T", "CacheNotFound", "CachedFileInfo", "CachedRepoInfo", "CachedRevisionInfo", "CorruptedCacheException", "DeleteCacheStrategy", "HFCacheInfo", "cached_assets_path", "close_session", "dump_environment_info", "get_async_session", "get_session", "get_token", "hf_raise_for_status", "logging", "scan_cache_dir", "set_async_client_factory", "set_client_factory", ], } # WARNING: __all__ is generated automatically, Any manual edit will be lost when re-generating this file ! # # To update the static imports, please run the following command and commit the changes. # ``` # # Use script # python utils/check_all_variable.py --update # # # Or run style on codebase # make style # ``` __all__ = [ "ASYNC_CLIENT_FACTORY_T", "Agent", "AsyncInferenceClient", "AudioClassificationInput", "AudioClassificationOutputElement", "AudioClassificationOutputTransform", "AudioClassificationParameters", "AudioToAudioInput", "AudioToAudioOutputElement", "AutomaticSpeechRecognitionEarlyStoppingEnum", "AutomaticSpeechRecognitionGenerationParameters", "AutomaticSpeechRecognitionInput", "AutomaticSpeechRecognitionOutput", "AutomaticSpeechRecognitionOutputChunk", "AutomaticSpeechRecognitionParameters", "CLIENT_FACTORY_T", "CONFIG_NAME", "CacheNotFound", "CachedFileInfo", "CachedRepoInfo", "CachedRevisionInfo", "CardData", "ChatCompletionInput", "ChatCompletionInputFunctionDefinition", "ChatCompletionInputFunctionName", "ChatCompletionInputGrammarType", "ChatCompletionInputJSONSchema", "ChatCompletionInputMessage", "ChatCompletionInputMessageChunk", "ChatCompletionInputMessageChunkType", "ChatCompletionInputResponseFormatJSONObject", "ChatCompletionInputResponseFormatJSONSchema", "ChatCompletionInputResponseFormatText", "ChatCompletionInputStreamOptions", "ChatCompletionInputTool", "ChatCompletionInputToolCall", "ChatCompletionInputToolChoiceClass", "ChatCompletionInputToolChoiceEnum", "ChatCompletionInputURL", "ChatCompletionOutput", "ChatCompletionOutputComplete", "ChatCompletionOutputFunctionDefinition", "ChatCompletionOutputLogprob", "ChatCompletionOutputLogprobs", "ChatCompletionOutputMessage", "ChatCompletionOutputToolCall", "ChatCompletionOutputTopLogprob", "ChatCompletionOutputUsage", "ChatCompletionStreamOutput", "ChatCompletionStreamOutputChoice", "ChatCompletionStreamOutputDelta", "ChatCompletionStreamOutputDeltaToolCall", "ChatCompletionStreamOutputFunction", "ChatCompletionStreamOutputLogprob", "ChatCompletionStreamOutputLogprobs", "ChatCompletionStreamOutputTopLogprob", "ChatCompletionStreamOutputUsage", "Collection", "CollectionItem", "CommitInfo", "CommitOperation", "CommitOperationAdd", "CommitOperationCopy", "CommitOperationDelete", "CommitScheduler", "CorruptedCacheException", "DDUFEntry", "DatasetCard", "DatasetCardData", "DatasetInfo", "DeleteCacheStrategy", "DepthEstimationInput", "DepthEstimationOutput", "Discussion", "DiscussionComment", "DiscussionCommit", "DiscussionEvent", "DiscussionStatusChange", "DiscussionTitleChange", "DiscussionWithDetails", "DocumentQuestionAnsweringInput", "DocumentQuestionAnsweringInputData", "DocumentQuestionAnsweringOutputElement", "DocumentQuestionAnsweringParameters", "DryRunFileInfo", "EvalResult", "FLAX_WEIGHTS_NAME", "FeatureExtractionInput", "FeatureExtractionInputTruncationDirection", "FillMaskInput", "FillMaskOutputElement", "FillMaskParameters", "GitCommitInfo", "GitRefInfo", "GitRefs", "HFCacheInfo", "HFSummaryWriter", "HUGGINGFACE_CO_URL_HOME", "HUGGINGFACE_CO_URL_TEMPLATE", "HfApi", "HfFileMetadata", "HfFileSystem", "HfFileSystemFile", "HfFileSystemResolvedPath", "HfFileSystemStreamFile", "ImageClassificationInput", "ImageClassificationOutputElement", "ImageClassificationOutputTransform", "ImageClassificationParameters", "ImageSegmentationInput", "ImageSegmentationOutputElement", "ImageSegmentationParameters", "ImageSegmentationSubtask", "ImageToImageInput", "ImageToImageOutput", "ImageToImageParameters", "ImageToImageTargetSize", "ImageToTextEarlyStoppingEnum", "ImageToTextGenerationParameters", "ImageToTextInput", "ImageToTextOutput", "ImageToTextParameters", "ImageToVideoInput", "ImageToVideoOutput", "ImageToVideoParameters", "ImageToVideoTargetSize", "InferenceClient", "InferenceEndpoint", "InferenceEndpointError", "InferenceEndpointStatus", "InferenceEndpointTimeoutError", "InferenceEndpointType", "InferenceTimeoutError", "JobInfo", "JobOwner", "JobStage", "JobStatus", "MCPClient", "ModelCard", "ModelCardData", "ModelHubMixin", "ModelInfo", "OAuthInfo", "OAuthOrgInfo", "OAuthUserInfo", "ObjectDetectionBoundingBox", "ObjectDetectionInput", "ObjectDetectionOutputElement", "ObjectDetectionParameters", "Organization", "PYTORCH_WEIGHTS_NAME", "Padding", "PyTorchModelHubMixin", "QuestionAnsweringInput", "QuestionAnsweringInputData", "QuestionAnsweringOutputElement", "QuestionAnsweringParameters", "REPO_TYPE_DATASET", "REPO_TYPE_MODEL", "REPO_TYPE_SPACE", "RepoCard", "RepoUrl", "SentenceSimilarityInput", "SentenceSimilarityInputData", "SpaceCard", "SpaceCardData", "SpaceHardware", "SpaceInfo", "SpaceRuntime", "SpaceStage", "SpaceStorage", "SpaceVariable", "StateDictSplit", "SummarizationInput", "SummarizationOutput", "SummarizationParameters", "SummarizationTruncationStrategy", "TF2_WEIGHTS_NAME", "TF_WEIGHTS_NAME", "TableQuestionAnsweringInput", "TableQuestionAnsweringInputData", "TableQuestionAnsweringOutputElement", "TableQuestionAnsweringParameters", "Text2TextGenerationInput", "Text2TextGenerationOutput", "Text2TextGenerationParameters", "Text2TextGenerationTruncationStrategy", "TextClassificationInput", "TextClassificationOutputElement", "TextClassificationOutputTransform", "TextClassificationParameters", "TextGenerationInput", "TextGenerationInputGenerateParameters", "TextGenerationInputGrammarType", "TextGenerationOutput", "TextGenerationOutputBestOfSequence", "TextGenerationOutputDetails", "TextGenerationOutputFinishReason", "TextGenerationOutputPrefillToken", "TextGenerationOutputToken", "TextGenerationStreamOutput", "TextGenerationStreamOutputStreamDetails", "TextGenerationStreamOutputToken", "TextToAudioEarlyStoppingEnum", "TextToAudioGenerationParameters", "TextToAudioInput", "TextToAudioOutput", "TextToAudioParameters", "TextToImageInput", "TextToImageOutput", "TextToImageParameters", "TextToSpeechEarlyStoppingEnum", "TextToSpeechGenerationParameters", "TextToSpeechInput", "TextToSpeechOutput", "TextToSpeechParameters", "TextToVideoInput", "TextToVideoOutput", "TextToVideoParameters", "TokenClassificationAggregationStrategy", "TokenClassificationInput", "TokenClassificationOutputElement", "TokenClassificationParameters", "TranslationInput", "TranslationOutput", "TranslationParameters", "TranslationTruncationStrategy", "TypeEnum", "User", "UserLikes", "VideoClassificationInput", "VideoClassificationOutputElement", "VideoClassificationOutputTransform", "VideoClassificationParameters", "VisualQuestionAnsweringInput", "VisualQuestionAnsweringInputData", "VisualQuestionAnsweringOutputElement", "VisualQuestionAnsweringParameters", "WebhookInfo", "WebhookPayload", "WebhookPayloadComment", "WebhookPayloadDiscussion", "WebhookPayloadDiscussionChanges", "WebhookPayloadEvent", "WebhookPayloadMovedTo", "WebhookPayloadRepo", "WebhookPayloadUrl", "WebhookPayloadWebhook", "WebhookWatchedItem", "WebhooksServer", "ZeroShotClassificationInput", "ZeroShotClassificationOutputElement", "ZeroShotClassificationParameters", "ZeroShotImageClassificationInput", "ZeroShotImageClassificationOutputElement", "ZeroShotImageClassificationParameters", "ZeroShotObjectDetectionBoundingBox", "ZeroShotObjectDetectionInput", "ZeroShotObjectDetectionOutputElement", "ZeroShotObjectDetectionParameters", "_CACHED_NO_EXIST", "_save_pretrained_fastai", "accept_access_request", "add_collection_item", "add_space_secret", "add_space_variable", "attach_huggingface_oauth", "auth_check", "auth_list", "auth_switch", "cached_assets_path", "cancel_access_request", "cancel_job", "change_discussion_status", "close_session", "comment_discussion", "create_branch", "create_collection", "create_commit", "create_discussion", "create_inference_endpoint", "create_inference_endpoint_from_catalog", "create_pull_request", "create_repo", "create_scheduled_job", "create_scheduled_uv_job", "create_tag", "create_webhook", "dataset_info", "delete_branch", "delete_collection", "delete_collection_item", "delete_file", "delete_folder", "delete_inference_endpoint", "delete_repo", "delete_scheduled_job", "delete_space_secret", "delete_space_storage", "delete_space_variable", "delete_tag", "delete_webhook", "disable_webhook", "dump_environment_info", "duplicate_space", "edit_discussion_comment", "enable_webhook", "export_entries_as_dduf", "export_folder_as_dduf", "fetch_job_logs", "file_exists", "from_pretrained_fastai", "get_async_session", "get_collection", "get_dataset_tags", "get_discussion_details", "get_full_repo_name", "get_hf_file_metadata", "get_inference_endpoint", "get_model_tags", "get_organization_overview", "get_paths_info", "get_repo_discussions", "get_safetensors_metadata", "get_session", "get_space_runtime", "get_space_variables", "get_token", "get_torch_storage_id", "get_torch_storage_size", "get_user_overview", "get_webhook", "grant_access", "hf_hub_download", "hf_hub_url", "hf_raise_for_status", "inspect_job", "inspect_scheduled_job", "interpreter_login", "list_accepted_access_requests", "list_collections", "list_datasets", "list_inference_catalog", "list_inference_endpoints", "list_jobs", "list_lfs_files", "list_liked_repos", "list_models", "list_organization_followers", "list_organization_members", "list_papers", "list_pending_access_requests", "list_rejected_access_requests", "list_repo_commits", "list_repo_files", "list_repo_likers", "list_repo_refs", "list_repo_tree", "list_spaces", "list_user_followers", "list_user_following", "list_webhooks", "load_state_dict_from_file", "load_torch_model", "logging", "login", "logout", "merge_pull_request", "metadata_eval_result", "metadata_load", "metadata_save", "metadata_update", "model_info", "move_repo", "notebook_login", "paper_info", "parse_huggingface_oauth", "parse_safetensors_file_metadata", "pause_inference_endpoint", "pause_space", "permanently_delete_lfs_files", "preupload_lfs_files", "push_to_hub_fastai", "read_dduf_file", "reject_access_request", "rename_discussion", "repo_exists", "repo_info", "repo_type_and_id_from_hf_id", "request_space_hardware", "request_space_storage", "restart_space", "resume_inference_endpoint", "resume_scheduled_job", "revision_exists", "run_as_future", "run_job", "run_uv_job", "save_torch_model", "save_torch_state_dict", "scale_to_zero_inference_endpoint", "scan_cache_dir", "set_async_client_factory", "set_client_factory", "set_space_sleep_time", "snapshot_download", "space_info", "split_state_dict_into_shards_factory", "split_torch_state_dict_into_shards", "super_squash_history", "suspend_scheduled_job", "try_to_load_from_cache", "typer_factory", "unlike", "update_collection_item", "update_collection_metadata", "update_inference_endpoint", "update_repo_settings", "update_webhook", "upload_file", "upload_folder", "upload_large_folder", "verify_repo_checksums", "webhook_endpoint", "whoami", ] def _attach(package_name, submodules=None, submod_attrs=None): """Attach lazily loaded submodules, functions, or other attributes. Typically, modules import submodules and attributes as follows: ```py import mysubmodule import anothersubmodule from .foo import someattr ``` The idea is to replace a package's `__getattr__`, `__dir__`, such that all imports work exactly the way they would with normal imports, except that the import occurs upon first use. The typical way to call this function, replacing the above imports, is: ```python __getattr__, __dir__ = lazy.attach( __name__, ['mysubmodule', 'anothersubmodule'], {'foo': ['someattr']} ) ``` This functionality requires Python 3.7 or higher. Args: package_name (`str`): Typically use `__name__`. submodules (`set`): List of submodules to attach. submod_attrs (`dict`): Dictionary of submodule -> list of attributes / functions. These attributes are imported as they are used. Returns: __getattr__, __dir__, __all__ """ if submod_attrs is None: submod_attrs = {} if submodules is None: submodules = set() else: submodules = set(submodules) attr_to_modules = {attr: mod for mod, attrs in submod_attrs.items() for attr in attrs} def __getattr__(name): if name in submodules: try: return importlib.import_module(f"{package_name}.{name}") except Exception as e: print(f"Error importing {package_name}.{name}: {e}") raise elif name in attr_to_modules: submod_path = f"{package_name}.{attr_to_modules[name]}" try: submod = importlib.import_module(submod_path) except Exception as e: print(f"Error importing {submod_path}: {e}") raise attr = getattr(submod, name) # If the attribute lives in a file (module) with the same # name as the attribute, ensure that the attribute and *not* # the module is accessible on the package. if name == attr_to_modules[name]: pkg = sys.modules[package_name] pkg.__dict__[name] = attr return attr else: raise AttributeError(f"No {package_name} attribute {name}") def __dir__(): return __all__ return __getattr__, __dir__ __getattr__, __dir__ = _attach(__name__, submodules=[], submod_attrs=_SUBMOD_ATTRS) if os.environ.get("EAGER_IMPORT", ""): for attr in __all__: __getattr__(attr) # WARNING: any content below this statement is generated automatically. Any manual edit # will be lost when re-generating this file ! # # To update the static imports, please run the following command and commit the changes. # ``` # # Use script # python utils/check_static_imports.py --update # # # Or run style on codebase # make style # ``` if TYPE_CHECKING: # pragma: no cover from ._commit_scheduler import CommitScheduler # noqa: F401 from ._inference_endpoints import ( InferenceEndpoint, # noqa: F401 InferenceEndpointError, # noqa: F401 InferenceEndpointStatus, # noqa: F401 InferenceEndpointTimeoutError, # noqa: F401 InferenceEndpointType, # noqa: F401 ) from ._jobs_api import ( JobInfo, # noqa: F401 JobOwner, # noqa: F401 JobStage, # noqa: F401 JobStatus, # noqa: F401 ) from ._login import ( auth_list, # noqa: F401 auth_switch, # noqa: F401 interpreter_login, # noqa: F401 login, # noqa: F401 logout, # noqa: F401 notebook_login, # noqa: F401 ) from ._oauth import ( OAuthInfo, # noqa: F401 OAuthOrgInfo, # noqa: F401 OAuthUserInfo, # noqa: F401 attach_huggingface_oauth, # noqa: F401 parse_huggingface_oauth, # noqa: F401 ) from ._snapshot_download import snapshot_download # noqa: F401 from ._space_api import ( SpaceHardware, # noqa: F401 SpaceRuntime, # noqa: F401 SpaceStage, # noqa: F401 SpaceStorage, # noqa: F401 SpaceVariable, # noqa: F401 ) from ._tensorboard_logger import HFSummaryWriter # noqa: F401 from ._webhooks_payload import ( WebhookPayload, # noqa: F401 WebhookPayloadComment, # noqa: F401 WebhookPayloadDiscussion, # noqa: F401 WebhookPayloadDiscussionChanges, # noqa: F401 WebhookPayloadEvent, # noqa: F401 WebhookPayloadMovedTo, # noqa: F401 WebhookPayloadRepo, # noqa: F401 WebhookPayloadUrl, # noqa: F401 WebhookPayloadWebhook, # noqa: F401 ) from ._webhooks_server import ( WebhooksServer, # noqa: F401 webhook_endpoint, # noqa: F401 ) from .cli._cli_utils import typer_factory # noqa: F401 from .community import ( Discussion, # noqa: F401 DiscussionComment, # noqa: F401 DiscussionCommit, # noqa: F401 DiscussionEvent, # noqa: F401 DiscussionStatusChange, # noqa: F401 DiscussionTitleChange, # noqa: F401 DiscussionWithDetails, # noqa: F401 ) from .constants import ( CONFIG_NAME, # noqa: F401 FLAX_WEIGHTS_NAME, # noqa: F401 HUGGINGFACE_CO_URL_HOME, # noqa: F401 HUGGINGFACE_CO_URL_TEMPLATE, # noqa: F401 PYTORCH_WEIGHTS_NAME, # noqa: F401 REPO_TYPE_DATASET, # noqa: F401 REPO_TYPE_MODEL, # noqa: F401 REPO_TYPE_SPACE, # noqa: F401 TF2_WEIGHTS_NAME, # noqa: F401 TF_WEIGHTS_NAME, # noqa: F401 ) from .fastai_utils import ( _save_pretrained_fastai, # noqa: F401 from_pretrained_fastai, # noqa: F401 push_to_hub_fastai, # noqa: F401 ) from .file_download import ( _CACHED_NO_EXIST, # noqa: F401 DryRunFileInfo, # noqa: F401 HfFileMetadata, # noqa: F401 get_hf_file_metadata, # noqa: F401 hf_hub_download, # noqa: F401 hf_hub_url, # noqa: F401 try_to_load_from_cache, # noqa: F401 ) from .hf_api import ( Collection, # noqa: F401 CollectionItem, # noqa: F401 CommitInfo, # noqa: F401 CommitOperation, # noqa: F401 CommitOperationAdd, # noqa: F401 CommitOperationCopy, # noqa: F401 CommitOperationDelete, # noqa: F401 DatasetInfo, # noqa: F401 GitCommitInfo, # noqa: F401 GitRefInfo, # noqa: F401 GitRefs, # noqa: F401 HfApi, # noqa: F401 ModelInfo, # noqa: F401 Organization, # noqa: F401 RepoUrl, # noqa: F401 SpaceInfo, # noqa: F401 User, # noqa: F401 UserLikes, # noqa: F401 WebhookInfo, # noqa: F401 WebhookWatchedItem, # noqa: F401 accept_access_request, # noqa: F401 add_collection_item, # noqa: F401 add_space_secret, # noqa: F401 add_space_variable, # noqa: F401 auth_check, # noqa: F401 cancel_access_request, # noqa: F401 cancel_job, # noqa: F401 change_discussion_status, # noqa: F401 comment_discussion, # noqa: F401 create_branch, # noqa: F401 create_collection, # noqa: F401 create_commit, # noqa: F401 create_discussion, # noqa: F401 create_inference_endpoint, # noqa: F401 create_inference_endpoint_from_catalog, # noqa: F401 create_pull_request, # noqa: F401 create_repo, # noqa: F401 create_scheduled_job, # noqa: F401 create_scheduled_uv_job, # noqa: F401 create_tag, # noqa: F401 create_webhook, # noqa: F401 dataset_info, # noqa: F401 delete_branch, # noqa: F401 delete_collection, # noqa: F401 delete_collection_item, # noqa: F401 delete_file, # noqa: F401 delete_folder, # noqa: F401 delete_inference_endpoint, # noqa: F401 delete_repo, # noqa: F401 delete_scheduled_job, # noqa: F401 delete_space_secret, # noqa: F401 delete_space_storage, # noqa: F401 delete_space_variable, # noqa: F401 delete_tag, # noqa: F401 delete_webhook, # noqa: F401 disable_webhook, # noqa: F401 duplicate_space, # noqa: F401 edit_discussion_comment, # noqa: F401 enable_webhook, # noqa: F401 fetch_job_logs, # noqa: F401 file_exists, # noqa: F401 get_collection, # noqa: F401 get_dataset_tags, # noqa: F401 get_discussion_details, # noqa: F401 get_full_repo_name, # noqa: F401 get_inference_endpoint, # noqa: F401 get_model_tags, # noqa: F401 get_organization_overview, # noqa: F401 get_paths_info, # noqa: F401 get_repo_discussions, # noqa: F401 get_safetensors_metadata, # noqa: F401 get_space_runtime, # noqa: F401 get_space_variables, # noqa: F401 get_user_overview, # noqa: F401 get_webhook, # noqa: F401 grant_access, # noqa: F401 inspect_job, # noqa: F401 inspect_scheduled_job, # noqa: F401 list_accepted_access_requests, # noqa: F401 list_collections, # noqa: F401 list_datasets, # noqa: F401 list_inference_catalog, # noqa: F401 list_inference_endpoints, # noqa: F401 list_jobs, # noqa: F401 list_lfs_files, # noqa: F401 list_liked_repos, # noqa: F401 list_models, # noqa: F401 list_organization_followers, # noqa: F401 list_organization_members, # noqa: F401 list_papers, # noqa: F401 list_pending_access_requests, # noqa: F401 list_rejected_access_requests, # noqa: F401 list_repo_commits, # noqa: F401 list_repo_files, # noqa: F401 list_repo_likers, # noqa: F401 list_repo_refs, # noqa: F401 list_repo_tree, # noqa: F401 list_spaces, # noqa: F401 list_user_followers, # noqa: F401 list_user_following, # noqa: F401 list_webhooks, # noqa: F401 merge_pull_request, # noqa: F401 model_info, # noqa: F401 move_repo, # noqa: F401 paper_info, # noqa: F401 parse_safetensors_file_metadata, # noqa: F401 pause_inference_endpoint, # noqa: F401 pause_space, # noqa: F401 permanently_delete_lfs_files, # noqa: F401 preupload_lfs_files, # noqa: F401 reject_access_request, # noqa: F401 rename_discussion, # noqa: F401 repo_exists, # noqa: F401 repo_info, # noqa: F401 repo_type_and_id_from_hf_id, # noqa: F401 request_space_hardware, # noqa: F401 request_space_storage, # noqa: F401 restart_space, # noqa: F401 resume_inference_endpoint, # noqa: F401 resume_scheduled_job, # noqa: F401 revision_exists, # noqa: F401 run_as_future, # noqa: F401 run_job, # noqa: F401 run_uv_job, # noqa: F401 scale_to_zero_inference_endpoint, # noqa: F401 set_space_sleep_time, # noqa: F401 space_info, # noqa: F401 super_squash_history, # noqa: F401 suspend_scheduled_job, # noqa: F401 unlike, # noqa: F401 update_collection_item, # noqa: F401 update_collection_metadata, # noqa: F401 update_inference_endpoint, # noqa: F401 update_repo_settings, # noqa: F401 update_webhook, # noqa: F401 upload_file, # noqa: F401 upload_folder, # noqa: F401 upload_large_folder, # noqa: F401 verify_repo_checksums, # noqa: F401 whoami, # noqa: F401 ) from .hf_file_system import ( HfFileSystem, # noqa: F401 HfFileSystemFile, # noqa: F401 HfFileSystemResolvedPath, # noqa: F401 HfFileSystemStreamFile, # noqa: F401 ) from .hub_mixin import ( ModelHubMixin, # noqa: F401 PyTorchModelHubMixin, # noqa: F401 ) from .inference._client import ( InferenceClient, # noqa: F401 InferenceTimeoutError, # noqa: F401 ) from .inference._generated._async_client import AsyncInferenceClient # noqa: F401 from .inference._generated.types import ( AudioClassificationInput, # noqa: F401 AudioClassificationOutputElement, # noqa: F401 AudioClassificationOutputTransform, # noqa: F401 AudioClassificationParameters, # noqa: F401 AudioToAudioInput, # noqa: F401 AudioToAudioOutputElement, # noqa: F401 AutomaticSpeechRecognitionEarlyStoppingEnum, # noqa: F401 AutomaticSpeechRecognitionGenerationParameters, # noqa: F401 AutomaticSpeechRecognitionInput, # noqa: F401 AutomaticSpeechRecognitionOutput, # noqa: F401 AutomaticSpeechRecognitionOutputChunk, # noqa: F401 AutomaticSpeechRecognitionParameters, # noqa: F401 ChatCompletionInput, # noqa: F401 ChatCompletionInputFunctionDefinition, # noqa: F401 ChatCompletionInputFunctionName, # noqa: F401 ChatCompletionInputGrammarType, # noqa: F401 ChatCompletionInputJSONSchema, # noqa: F401 ChatCompletionInputMessage, # noqa: F401 ChatCompletionInputMessageChunk, # noqa: F401 ChatCompletionInputMessageChunkType, # noqa: F401 ChatCompletionInputResponseFormatJSONObject, # noqa: F401 ChatCompletionInputResponseFormatJSONSchema, # noqa: F401 ChatCompletionInputResponseFormatText, # noqa: F401 ChatCompletionInputStreamOptions, # noqa: F401 ChatCompletionInputTool, # noqa: F401 ChatCompletionInputToolCall, # noqa: F401 ChatCompletionInputToolChoiceClass, # noqa: F401 ChatCompletionInputToolChoiceEnum, # noqa: F401 ChatCompletionInputURL, # noqa: F401 ChatCompletionOutput, # noqa: F401 ChatCompletionOutputComplete, # noqa: F401 ChatCompletionOutputFunctionDefinition, # noqa: F401 ChatCompletionOutputLogprob, # noqa: F401 ChatCompletionOutputLogprobs, # noqa: F401 ChatCompletionOutputMessage, # noqa: F401 ChatCompletionOutputToolCall, # noqa: F401 ChatCompletionOutputTopLogprob, # noqa: F401 ChatCompletionOutputUsage, # noqa: F401 ChatCompletionStreamOutput, # noqa: F401 ChatCompletionStreamOutputChoice, # noqa: F401 ChatCompletionStreamOutputDelta, # noqa: F401 ChatCompletionStreamOutputDeltaToolCall, # noqa: F401 ChatCompletionStreamOutputFunction, # noqa: F401 ChatCompletionStreamOutputLogprob, # noqa: F401 ChatCompletionStreamOutputLogprobs, # noqa: F401 ChatCompletionStreamOutputTopLogprob, # noqa: F401 ChatCompletionStreamOutputUsage, # noqa: F401 DepthEstimationInput, # noqa: F401 DepthEstimationOutput, # noqa: F401 DocumentQuestionAnsweringInput, # noqa: F401 DocumentQuestionAnsweringInputData, # noqa: F401 DocumentQuestionAnsweringOutputElement, # noqa: F401 DocumentQuestionAnsweringParameters, # noqa: F401 FeatureExtractionInput, # noqa: F401 FeatureExtractionInputTruncationDirection, # noqa: F401 FillMaskInput, # noqa: F401 FillMaskOutputElement, # noqa: F401 FillMaskParameters, # noqa: F401 ImageClassificationInput, # noqa: F401 ImageClassificationOutputElement, # noqa: F401 ImageClassificationOutputTransform, # noqa: F401 ImageClassificationParameters, # noqa: F401 ImageSegmentationInput, # noqa: F401 ImageSegmentationOutputElement, # noqa: F401 ImageSegmentationParameters, # noqa: F401 ImageSegmentationSubtask, # noqa: F401 ImageToImageInput, # noqa: F401 ImageToImageOutput, # noqa: F401 ImageToImageParameters, # noqa: F401 ImageToImageTargetSize, # noqa: F401 ImageToTextEarlyStoppingEnum, # noqa: F401 ImageToTextGenerationParameters, # noqa: F401 ImageToTextInput, # noqa: F401 ImageToTextOutput, # noqa: F401 ImageToTextParameters, # noqa: F401 ImageToVideoInput, # noqa: F401 ImageToVideoOutput, # noqa: F401 ImageToVideoParameters, # noqa: F401 ImageToVideoTargetSize, # noqa: F401 ObjectDetectionBoundingBox, # noqa: F401 ObjectDetectionInput, # noqa: F401 ObjectDetectionOutputElement, # noqa: F401 ObjectDetectionParameters, # noqa: F401 Padding, # noqa: F401 QuestionAnsweringInput, # noqa: F401 QuestionAnsweringInputData, # noqa: F401 QuestionAnsweringOutputElement, # noqa: F401 QuestionAnsweringParameters, # noqa: F401 SentenceSimilarityInput, # noqa: F401 SentenceSimilarityInputData, # noqa: F401 SummarizationInput, # noqa: F401 SummarizationOutput, # noqa: F401 SummarizationParameters, # noqa: F401 SummarizationTruncationStrategy, # noqa: F401 TableQuestionAnsweringInput, # noqa: F401 TableQuestionAnsweringInputData, # noqa: F401 TableQuestionAnsweringOutputElement, # noqa: F401 TableQuestionAnsweringParameters, # noqa: F401 Text2TextGenerationInput, # noqa: F401 Text2TextGenerationOutput, # noqa: F401 Text2TextGenerationParameters, # noqa: F401 Text2TextGenerationTruncationStrategy, # noqa: F401 TextClassificationInput, # noqa: F401 TextClassificationOutputElement, # noqa: F401 TextClassificationOutputTransform, # noqa: F401 TextClassificationParameters, # noqa: F401 TextGenerationInput, # noqa: F401 TextGenerationInputGenerateParameters, # noqa: F401 TextGenerationInputGrammarType, # noqa: F401 TextGenerationOutput, # noqa: F401 TextGenerationOutputBestOfSequence, # noqa: F401 TextGenerationOutputDetails, # noqa: F401 TextGenerationOutputFinishReason, # noqa: F401 TextGenerationOutputPrefillToken, # noqa: F401 TextGenerationOutputToken, # noqa: F401 TextGenerationStreamOutput, # noqa: F401 TextGenerationStreamOutputStreamDetails, # noqa: F401 TextGenerationStreamOutputToken, # noqa: F401 TextToAudioEarlyStoppingEnum, # noqa: F401 TextToAudioGenerationParameters, # noqa: F401 TextToAudioInput, # noqa: F401 TextToAudioOutput, # noqa: F401 TextToAudioParameters, # noqa: F401 TextToImageInput, # noqa: F401 TextToImageOutput, # noqa: F401 TextToImageParameters, # noqa: F401 TextToSpeechEarlyStoppingEnum, # noqa: F401 TextToSpeechGenerationParameters, # noqa: F401 TextToSpeechInput, # noqa: F401 TextToSpeechOutput, # noqa: F401 TextToSpeechParameters, # noqa: F401 TextToVideoInput, # noqa: F401 TextToVideoOutput, # noqa: F401 TextToVideoParameters, # noqa: F401 TokenClassificationAggregationStrategy, # noqa: F401 TokenClassificationInput, # noqa: F401 TokenClassificationOutputElement, # noqa: F401 TokenClassificationParameters, # noqa: F401 TranslationInput, # noqa: F401 TranslationOutput, # noqa: F401 TranslationParameters, # noqa: F401 TranslationTruncationStrategy, # noqa: F401 TypeEnum, # noqa: F401 VideoClassificationInput, # noqa: F401 VideoClassificationOutputElement, # noqa: F401 VideoClassificationOutputTransform, # noqa: F401 VideoClassificationParameters, # noqa: F401 VisualQuestionAnsweringInput, # noqa: F401 VisualQuestionAnsweringInputData, # noqa: F401 VisualQuestionAnsweringOutputElement, # noqa: F401 VisualQuestionAnsweringParameters, # noqa: F401 ZeroShotClassificationInput, # noqa: F401 ZeroShotClassificationOutputElement, # noqa: F401 ZeroShotClassificationParameters, # noqa: F401 ZeroShotImageClassificationInput, # noqa: F401 ZeroShotImageClassificationOutputElement, # noqa: F401 ZeroShotImageClassificationParameters, # noqa: F401 ZeroShotObjectDetectionBoundingBox, # noqa: F401 ZeroShotObjectDetectionInput, # noqa: F401 ZeroShotObjectDetectionOutputElement, # noqa: F401 ZeroShotObjectDetectionParameters, # noqa: F401 ) from .inference._mcp.agent import Agent # noqa: F401 from .inference._mcp.mcp_client import MCPClient # noqa: F401 from .repocard import ( DatasetCard, # noqa: F401 ModelCard, # noqa: F401 RepoCard, # noqa: F401 SpaceCard, # noqa: F401 metadata_eval_result, # noqa: F401 metadata_load, # noqa: F401 metadata_save, # noqa: F401 metadata_update, # noqa: F401 ) from .repocard_data import ( CardData, # noqa: F401 DatasetCardData, # noqa: F401 EvalResult, # noqa: F401 ModelCardData, # noqa: F401 SpaceCardData, # noqa: F401 ) from .serialization import ( StateDictSplit, # noqa: F401 get_torch_storage_id, # noqa: F401 get_torch_storage_size, # noqa: F401 load_state_dict_from_file, # noqa: F401 load_torch_model, # noqa: F401 save_torch_model, # noqa: F401 save_torch_state_dict, # noqa: F401 split_state_dict_into_shards_factory, # noqa: F401 split_torch_state_dict_into_shards, # noqa: F401 ) from .serialization._dduf import ( DDUFEntry, # noqa: F401 export_entries_as_dduf, # noqa: F401 export_folder_as_dduf, # noqa: F401 read_dduf_file, # noqa: F401 ) from .utils import ( ASYNC_CLIENT_FACTORY_T, # noqa: F401 CLIENT_FACTORY_T, # noqa: F401 CachedFileInfo, # noqa: F401 CachedRepoInfo, # noqa: F401 CachedRevisionInfo, # noqa: F401 CacheNotFound, # noqa: F401 CorruptedCacheException, # noqa: F401 DeleteCacheStrategy, # noqa: F401 HFCacheInfo, # noqa: F401 cached_assets_path, # noqa: F401 close_session, # noqa: F401 dump_environment_info, # noqa: F401 get_async_session, # noqa: F401 get_session, # noqa: F401 get_token, # noqa: F401 hf_raise_for_status, # noqa: F401 logging, # noqa: F401 scan_cache_dir, # noqa: F401 set_async_client_factory, # noqa: F401 set_client_factory, # noqa: F401 ) huggingface_hub-1.1.5/src/huggingface_hub/_commit_api.py000066400000000000000000001172531510763414300233660ustar00rootroot00000000000000""" Type definitions and utilities for the `create_commit` API """ import base64 import io import os import warnings from collections import defaultdict from contextlib import contextmanager from dataclasses import dataclass, field from itertools import groupby from pathlib import Path, PurePosixPath from typing import TYPE_CHECKING, Any, BinaryIO, Iterable, Iterator, Literal, Optional, Union from tqdm.contrib.concurrent import thread_map from . import constants from .errors import EntryNotFoundError, HfHubHTTPError, XetAuthorizationError, XetRefreshTokenError from .file_download import hf_hub_url from .lfs import UploadInfo, lfs_upload, post_lfs_batch_info from .utils import ( FORBIDDEN_FOLDERS, XetTokenType, are_progress_bars_disabled, chunk_iterable, fetch_xet_connection_info_from_repo_info, get_session, hf_raise_for_status, logging, sha, tqdm_stream_file, validate_hf_hub_args, ) from .utils import tqdm as hf_tqdm from .utils._runtime import is_xet_available if TYPE_CHECKING: from .hf_api import RepoFile logger = logging.get_logger(__name__) UploadMode = Literal["lfs", "regular"] # Max is 1,000 per request on the Hub for HfApi.get_paths_info # Otherwise we get: # HfHubHTTPError: 413 Client Error: Payload Too Large for url: https://huggingface.co/api/datasets/xxx (Request ID: xxx)\n\ntoo many parameters # See https://github.com/huggingface/huggingface_hub/issues/1503 FETCH_LFS_BATCH_SIZE = 500 UPLOAD_BATCH_MAX_NUM_FILES = 256 @dataclass class CommitOperationDelete: """ Data structure holding necessary info to delete a file or a folder from a repository on the Hub. Args: path_in_repo (`str`): Relative filepath in the repo, for example: `"checkpoints/1fec34a/weights.bin"` for a file or `"checkpoints/1fec34a/"` for a folder. is_folder (`bool` or `Literal["auto"]`, *optional*) Whether the Delete Operation applies to a folder or not. If "auto", the path type (file or folder) is guessed automatically by looking if path ends with a "/" (folder) or not (file). To explicitly set the path type, you can set `is_folder=True` or `is_folder=False`. """ path_in_repo: str is_folder: Union[bool, Literal["auto"]] = "auto" def __post_init__(self): self.path_in_repo = _validate_path_in_repo(self.path_in_repo) if self.is_folder == "auto": self.is_folder = self.path_in_repo.endswith("/") if not isinstance(self.is_folder, bool): raise ValueError( f"Wrong value for `is_folder`. Must be one of [`True`, `False`, `'auto'`]. Got '{self.is_folder}'." ) @dataclass class CommitOperationCopy: """ Data structure holding necessary info to copy a file in a repository on the Hub. Limitations: - Only LFS files can be copied. To copy a regular file, you need to download it locally and re-upload it - Cross-repository copies are not supported. Note: you can combine a [`CommitOperationCopy`] and a [`CommitOperationDelete`] to rename an LFS file on the Hub. Args: src_path_in_repo (`str`): Relative filepath in the repo of the file to be copied, e.g. `"checkpoints/1fec34a/weights.bin"`. path_in_repo (`str`): Relative filepath in the repo where to copy the file, e.g. `"checkpoints/1fec34a/weights_copy.bin"`. src_revision (`str`, *optional*): The git revision of the file to be copied. Can be any valid git revision. Default to the target commit revision. """ src_path_in_repo: str path_in_repo: str src_revision: Optional[str] = None # set to the OID of the file to be copied if it has already been uploaded # useful to determine if a commit will be empty or not. _src_oid: Optional[str] = None # set to the OID of the file to copy to if it has already been uploaded # useful to determine if a commit will be empty or not. _dest_oid: Optional[str] = None def __post_init__(self): self.src_path_in_repo = _validate_path_in_repo(self.src_path_in_repo) self.path_in_repo = _validate_path_in_repo(self.path_in_repo) @dataclass class CommitOperationAdd: """ Data structure holding necessary info to upload a file to a repository on the Hub. Args: path_in_repo (`str`): Relative filepath in the repo, for example: `"checkpoints/1fec34a/weights.bin"` path_or_fileobj (`str`, `Path`, `bytes`, or `BinaryIO`): Either: - a path to a local file (as `str` or `pathlib.Path`) to upload - a buffer of bytes (`bytes`) holding the content of the file to upload - a "file object" (subclass of `io.BufferedIOBase`), typically obtained with `open(path, "rb")`. It must support `seek()` and `tell()` methods. Raises: [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) If `path_or_fileobj` is not one of `str`, `Path`, `bytes` or `io.BufferedIOBase`. [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) If `path_or_fileobj` is a `str` or `Path` but not a path to an existing file. [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) If `path_or_fileobj` is a `io.BufferedIOBase` but it doesn't support both `seek()` and `tell()`. """ path_in_repo: str path_or_fileobj: Union[str, Path, bytes, BinaryIO] upload_info: UploadInfo = field(init=False, repr=False) # Internal attributes # set to "lfs" or "regular" once known _upload_mode: Optional[UploadMode] = field(init=False, repr=False, default=None) # set to True if .gitignore rules prevent the file from being uploaded as LFS # (server-side check) _should_ignore: Optional[bool] = field(init=False, repr=False, default=None) # set to the remote OID of the file if it has already been uploaded # useful to determine if a commit will be empty or not _remote_oid: Optional[str] = field(init=False, repr=False, default=None) # set to True once the file has been uploaded as LFS _is_uploaded: bool = field(init=False, repr=False, default=False) # set to True once the file has been committed _is_committed: bool = field(init=False, repr=False, default=False) def __post_init__(self) -> None: """Validates `path_or_fileobj` and compute `upload_info`.""" self.path_in_repo = _validate_path_in_repo(self.path_in_repo) # Validate `path_or_fileobj` value if isinstance(self.path_or_fileobj, Path): self.path_or_fileobj = str(self.path_or_fileobj) if isinstance(self.path_or_fileobj, str): path_or_fileobj = os.path.normpath(os.path.expanduser(self.path_or_fileobj)) if not os.path.isfile(path_or_fileobj): raise ValueError(f"Provided path: '{path_or_fileobj}' is not a file on the local file system") elif not isinstance(self.path_or_fileobj, (io.BufferedIOBase, bytes)): # ^^ Inspired from: https://stackoverflow.com/questions/44584829/how-to-determine-if-file-is-opened-in-binary-or-text-mode raise ValueError( "path_or_fileobj must be either an instance of str, bytes or" " io.BufferedIOBase. If you passed a file-like object, make sure it is" " in binary mode." ) if isinstance(self.path_or_fileobj, io.BufferedIOBase): try: self.path_or_fileobj.tell() self.path_or_fileobj.seek(0, os.SEEK_CUR) except (OSError, AttributeError) as exc: raise ValueError( "path_or_fileobj is a file-like object but does not implement seek() and tell()" ) from exc # Compute "upload_info" attribute if isinstance(self.path_or_fileobj, str): self.upload_info = UploadInfo.from_path(self.path_or_fileobj) elif isinstance(self.path_or_fileobj, bytes): self.upload_info = UploadInfo.from_bytes(self.path_or_fileobj) else: self.upload_info = UploadInfo.from_fileobj(self.path_or_fileobj) @contextmanager def as_file(self, with_tqdm: bool = False) -> Iterator[BinaryIO]: """ A context manager that yields a file-like object allowing to read the underlying data behind `path_or_fileobj`. Args: with_tqdm (`bool`, *optional*, defaults to `False`): If True, iterating over the file object will display a progress bar. Only works if the file-like object is a path to a file. Pure bytes and buffers are not supported. Example: ```python >>> operation = CommitOperationAdd( ... path_in_repo="remote/dir/weights.h5", ... path_or_fileobj="./local/weights.h5", ... ) CommitOperationAdd(path_in_repo='remote/dir/weights.h5', path_or_fileobj='./local/weights.h5') >>> with operation.as_file() as file: ... content = file.read() >>> with operation.as_file(with_tqdm=True) as file: ... while True: ... data = file.read(1024) ... if not data: ... break config.json: 100%|█████████████████████████| 8.19k/8.19k [00:02<00:00, 3.72kB/s] >>> with operation.as_file(with_tqdm=True) as file: ... httpx.put(..., data=file) config.json: 100%|█████████████████████████| 8.19k/8.19k [00:02<00:00, 3.72kB/s] ``` """ if isinstance(self.path_or_fileobj, str) or isinstance(self.path_or_fileobj, Path): if with_tqdm: with tqdm_stream_file(self.path_or_fileobj) as file: yield file else: with open(self.path_or_fileobj, "rb") as file: yield file elif isinstance(self.path_or_fileobj, bytes): yield io.BytesIO(self.path_or_fileobj) elif isinstance(self.path_or_fileobj, io.BufferedIOBase): prev_pos = self.path_or_fileobj.tell() yield self.path_or_fileobj self.path_or_fileobj.seek(prev_pos, io.SEEK_SET) def b64content(self) -> bytes: """ The base64-encoded content of `path_or_fileobj` Returns: `bytes` """ with self.as_file() as file: return base64.b64encode(file.read()) @property def _local_oid(self) -> Optional[str]: """Return the OID of the local file. This OID is then compared to `self._remote_oid` to check if the file has changed compared to the remote one. If the file did not change, we won't upload it again to prevent empty commits. For LFS files, the OID corresponds to the SHA256 of the file content (used a LFS ref). For regular files, the OID corresponds to the SHA1 of the file content. Note: this is slightly different to git OID computation since the oid of an LFS file is usually the git-SHA1 of the pointer file content (not the actual file content). However, using the SHA256 is enough to detect changes and more convenient client-side. """ if self._upload_mode is None: return None elif self._upload_mode == "lfs": return self.upload_info.sha256.hex() else: # Regular file => compute sha1 # => no need to read by chunk since the file is guaranteed to be <=5MB. with self.as_file() as file: return sha.git_hash(file.read()) def _validate_path_in_repo(path_in_repo: str) -> str: # Validate `path_in_repo` value to prevent a server-side issue if path_in_repo.startswith("/"): path_in_repo = path_in_repo[1:] if path_in_repo == "." or path_in_repo == ".." or path_in_repo.startswith("../"): raise ValueError(f"Invalid `path_in_repo` in CommitOperation: '{path_in_repo}'") if path_in_repo.startswith("./"): path_in_repo = path_in_repo[2:] for forbidden in FORBIDDEN_FOLDERS: if any(part == forbidden for part in path_in_repo.split("/")): raise ValueError( f"Invalid `path_in_repo` in CommitOperation: cannot update files under a '{forbidden}/' folder (path:" f" '{path_in_repo}')." ) return path_in_repo CommitOperation = Union[CommitOperationAdd, CommitOperationCopy, CommitOperationDelete] def _warn_on_overwriting_operations(operations: list[CommitOperation]) -> None: """ Warn user when a list of operations is expected to overwrite itself in a single commit. Rules: - If a filepath is updated by multiple `CommitOperationAdd` operations, a warning message is triggered. - If a filepath is updated at least once by a `CommitOperationAdd` and then deleted by a `CommitOperationDelete`, a warning is triggered. - If a `CommitOperationDelete` deletes a filepath that is then updated by a `CommitOperationAdd`, no warning is triggered. This is usually useless (no need to delete before upload) but can happen if a user deletes an entire folder and then add new files to it. """ nb_additions_per_path: dict[str, int] = defaultdict(int) for operation in operations: path_in_repo = operation.path_in_repo if isinstance(operation, CommitOperationAdd): if nb_additions_per_path[path_in_repo] > 0: warnings.warn( "About to update multiple times the same file in the same commit:" f" '{path_in_repo}'. This can cause undesired inconsistencies in" " your repo." ) nb_additions_per_path[path_in_repo] += 1 for parent in PurePosixPath(path_in_repo).parents: # Also keep track of number of updated files per folder # => warns if deleting a folder overwrite some contained files nb_additions_per_path[str(parent)] += 1 if isinstance(operation, CommitOperationDelete): if nb_additions_per_path[str(PurePosixPath(path_in_repo))] > 0: if operation.is_folder: warnings.warn( "About to delete a folder containing files that have just been" f" updated within the same commit: '{path_in_repo}'. This can" " cause undesired inconsistencies in your repo." ) else: warnings.warn( "About to delete a file that have just been updated within the" f" same commit: '{path_in_repo}'. This can cause undesired" " inconsistencies in your repo." ) @validate_hf_hub_args def _upload_files( *, additions: list[CommitOperationAdd], repo_type: str, repo_id: str, headers: dict[str, str], endpoint: Optional[str] = None, num_threads: int = 5, revision: Optional[str] = None, create_pr: Optional[bool] = None, ): """ Negotiates per-file transfer (LFS vs Xet) and uploads in batches. """ xet_additions: list[CommitOperationAdd] = [] lfs_actions: list[dict[str, Any]] = [] lfs_oid2addop: dict[str, CommitOperationAdd] = {} for chunk in chunk_iterable(additions, chunk_size=UPLOAD_BATCH_MAX_NUM_FILES): chunk_list = [op for op in chunk] transfers: list[str] = ["basic", "multipart"] has_buffered_io_data = any(isinstance(op.path_or_fileobj, io.BufferedIOBase) for op in chunk_list) if is_xet_available(): if not has_buffered_io_data: transfers.append("xet") else: logger.warning( "Uploading files as a binary IO buffer is not supported by Xet Storage. " "Falling back to HTTP upload." ) actions_chunk, errors_chunk, chosen_transfer = post_lfs_batch_info( upload_infos=[op.upload_info for op in chunk_list], repo_id=repo_id, repo_type=repo_type, revision=revision, endpoint=endpoint, headers=headers, token=None, # already passed in 'headers' transfers=transfers, ) if errors_chunk: message = "\n".join( [ f"Encountered error for file with OID {err.get('oid')}: `{err.get('error', {}).get('message')}" for err in errors_chunk ] ) raise ValueError(f"LFS batch API returned errors:\n{message}") # If server returns a transfer we didn't offer (e.g "xet" while uploading from BytesIO), # fall back to LFS for this chunk. if chosen_transfer == "xet" and ("xet" in transfers): xet_additions.extend(chunk_list) else: lfs_actions.extend(actions_chunk) for op in chunk_list: lfs_oid2addop[op.upload_info.sha256.hex()] = op if len(lfs_actions) > 0: _upload_lfs_files( actions=lfs_actions, oid2addop=lfs_oid2addop, headers=headers, endpoint=endpoint, num_threads=num_threads, ) if len(xet_additions) > 0: _upload_xet_files( additions=xet_additions, repo_type=repo_type, repo_id=repo_id, headers=headers, endpoint=endpoint, revision=revision, create_pr=create_pr, ) @validate_hf_hub_args def _upload_lfs_files( *, actions: list[dict[str, Any]], oid2addop: dict[str, CommitOperationAdd], headers: dict[str, str], endpoint: Optional[str] = None, num_threads: int = 5, ): """ Uploads the content of `additions` to the Hub using the large file storage protocol. Relevant external documentation: - LFS Batch API: https://github.com/git-lfs/git-lfs/blob/main/docs/api/batch.md Args: actions (`list[dict[str, Any]]`): LFS batch actions returned by the server. oid2addop (`dict[str, CommitOperationAdd]`): A dictionary mapping the OID of the file to the corresponding `CommitOperationAdd` object. headers (`dict[str, str]`): Headers to use for the request, including authorization headers and user agent. endpoint (`str`, *optional*): The endpoint to use for the request. Defaults to `constants.ENDPOINT`. num_threads (`int`, *optional*): The number of concurrent threads to use when uploading. Defaults to 5. Raises: [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError) If an upload failed for any reason [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) Type of the repo to upload to: `"model"`, `"dataset"` or `"space"`. repo_id (`str`): A namespace (user or an organization) and a repo name separated by a `/`. headers (`dict[str, str]`): Headers to use for the request, including authorization headers and user agent. num_threads (`int`, *optional*): The number of concurrent threads to use when uploading. Defaults to 5. revision (`str`, *optional*): The git revision to upload to. Raises: [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError) If an upload failed for any reason [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) If the server returns malformed responses [`HfHubHTTPError`] If the LFS batch endpoint returned an HTTP error. """ # Filter out files already present upstream filtered_actions = [] for action in actions: if action.get("actions") is None: logger.debug( f"Content of file {oid2addop[action['oid']].path_in_repo} is already present upstream - skipping upload." ) else: filtered_actions.append(action) # Upload according to server-provided actions def _wrapped_lfs_upload(batch_action) -> None: try: operation = oid2addop[batch_action["oid"]] lfs_upload(operation=operation, lfs_batch_action=batch_action, headers=headers, endpoint=endpoint) except Exception as exc: raise RuntimeError(f"Error while uploading '{operation.path_in_repo}' to the Hub.") from exc if len(filtered_actions) == 1: logger.debug("Uploading 1 LFS file to the Hub") _wrapped_lfs_upload(filtered_actions[0]) else: logger.debug( f"Uploading {len(filtered_actions)} LFS files to the Hub using up to {num_threads} threads concurrently" ) thread_map( _wrapped_lfs_upload, filtered_actions, desc=f"Upload {len(filtered_actions)} LFS files", max_workers=num_threads, tqdm_class=hf_tqdm, ) @validate_hf_hub_args def _upload_xet_files( *, additions: list[CommitOperationAdd], repo_type: str, repo_id: str, headers: dict[str, str], endpoint: Optional[str] = None, revision: Optional[str] = None, create_pr: Optional[bool] = None, ): """ Uploads the content of `additions` to the Hub using the xet storage protocol. This chunks the files and deduplicates the chunks before uploading them to xetcas storage. Args: additions (`` of `CommitOperationAdd`): The files to be uploaded. repo_type (`str`): Type of the repo to upload to: `"model"`, `"dataset"` or `"space"`. repo_id (`str`): A namespace (user or an organization) and a repo name separated by a `/`. headers (`dict[str, str]`): Headers to use for the request, including authorization headers and user agent. endpoint: (`str`, *optional*): The endpoint to use for the xetcas service. Defaults to `constants.ENDPOINT`. revision (`str`, *optional*): The git revision to upload to. create_pr (`bool`, *optional*): Whether or not to create a Pull Request with that commit. Raises: [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError) If an upload failed for any reason. [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) If the server returns malformed responses or if the user is unauthorized to upload to xet storage. [`HfHubHTTPError`] If the LFS batch endpoint returned an HTTP error. **How it works:** The file download system uses Xet storage, which is a content-addressable storage system that breaks files into chunks for efficient storage and transfer. `hf_xet.upload_files` manages uploading files by: - Taking a list of file paths to upload - Breaking files into smaller chunks for efficient storage - Avoiding duplicate storage by recognizing identical chunks across files - Connecting to a storage server (CAS server) that manages these chunks The upload process works like this: 1. Create a local folder at ~/.cache/huggingface/xet/chunk-cache to store file chunks for reuse. 2. Process files in parallel (up to 8 files at once): 2.1. Read the file content. 2.2. Split the file content into smaller chunks based on content patterns: each chunk gets a unique ID based on what's in it. 2.3. For each chunk: - Check if it already exists in storage. - Skip uploading chunks that already exist. 2.4. Group chunks into larger blocks for efficient transfer. 2.5. Upload these blocks to the storage server. 2.6. Create and upload information about how the file is structured. 3. Return reference files that contain information about the uploaded files, which can be used later to download them. """ if len(additions) == 0: return # at this point, we know that hf_xet is installed from hf_xet import upload_bytes, upload_files from .utils._xet_progress_reporting import XetProgressReporter try: xet_connection_info = fetch_xet_connection_info_from_repo_info( token_type=XetTokenType.WRITE, repo_id=repo_id, repo_type=repo_type, revision=revision, headers=headers, endpoint=endpoint, params={"create_pr": "1"} if create_pr else None, ) except HfHubHTTPError as e: if e.response.status_code == 401: raise XetAuthorizationError( f"You are unauthorized to upload to xet storage for {repo_type}/{repo_id}. " f"Please check that you have configured your access token with write access to the repo." ) from e raise xet_endpoint = xet_connection_info.endpoint access_token_info = (xet_connection_info.access_token, xet_connection_info.expiration_unix_epoch) def token_refresher() -> tuple[str, int]: new_xet_connection = fetch_xet_connection_info_from_repo_info( token_type=XetTokenType.WRITE, repo_id=repo_id, repo_type=repo_type, revision=revision, headers=headers, endpoint=endpoint, params={"create_pr": "1"} if create_pr else None, ) if new_xet_connection is None: raise XetRefreshTokenError("Failed to refresh xet token") return new_xet_connection.access_token, new_xet_connection.expiration_unix_epoch if not are_progress_bars_disabled(): progress = XetProgressReporter() progress_callback = progress.update_progress else: progress, progress_callback = None, None try: all_bytes_ops = [op for op in additions if isinstance(op.path_or_fileobj, bytes)] all_paths_ops = [op for op in additions if isinstance(op.path_or_fileobj, (str, Path))] if len(all_paths_ops) > 0: all_paths = [str(op.path_or_fileobj) for op in all_paths_ops] upload_files( all_paths, xet_endpoint, access_token_info, token_refresher, progress_callback, repo_type, ) if len(all_bytes_ops) > 0: all_bytes = [op.path_or_fileobj for op in all_bytes_ops] upload_bytes( all_bytes, xet_endpoint, access_token_info, token_refresher, progress_callback, repo_type, ) finally: if progress is not None: progress.close(False) return def _validate_preupload_info(preupload_info: dict): files = preupload_info.get("files") if not isinstance(files, list): raise ValueError("preupload_info is improperly formatted") for file_info in files: if not ( isinstance(file_info, dict) and isinstance(file_info.get("path"), str) and isinstance(file_info.get("uploadMode"), str) and (file_info["uploadMode"] in ("lfs", "regular")) ): raise ValueError("preupload_info is improperly formatted:") return preupload_info @validate_hf_hub_args def _fetch_upload_modes( additions: Iterable[CommitOperationAdd], repo_type: str, repo_id: str, headers: dict[str, str], revision: str, endpoint: Optional[str] = None, create_pr: bool = False, gitignore_content: Optional[str] = None, ) -> None: """ Requests the Hub "preupload" endpoint to determine whether each input file should be uploaded as a regular git blob, as a git LFS blob, or as a XET file. Input `additions` are mutated in-place with the upload mode. Args: additions (`Iterable` of :class:`CommitOperationAdd`): Iterable of :class:`CommitOperationAdd` describing the files to upload to the Hub. repo_type (`str`): Type of the repo to upload to: `"model"`, `"dataset"` or `"space"`. repo_id (`str`): A namespace (user or an organization) and a repo name separated by a `/`. headers (`dict[str, str]`): Headers to use for the request, including authorization headers and user agent. revision (`str`): The git revision to upload the files to. Can be any valid git revision. gitignore_content (`str`, *optional*): The content of the `.gitignore` file to know which files should be ignored. The order of priority is to first check if `gitignore_content` is passed, then check if the `.gitignore` file is present in the list of files to commit and finally default to the `.gitignore` file already hosted on the Hub (if any). Raises: [`~utils.HfHubHTTPError`] If the Hub API returned an error. [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) If the Hub API response is improperly formatted. """ endpoint = endpoint if endpoint is not None else constants.ENDPOINT # Fetch upload mode (LFS or regular) chunk by chunk. upload_modes: dict[str, UploadMode] = {} should_ignore_info: dict[str, bool] = {} oid_info: dict[str, Optional[str]] = {} for chunk in chunk_iterable(additions, 256): payload: dict = { "files": [ { "path": op.path_in_repo, "sample": base64.b64encode(op.upload_info.sample).decode("ascii"), "size": op.upload_info.size, } for op in chunk ] } if gitignore_content is not None: payload["gitIgnore"] = gitignore_content resp = get_session().post( f"{endpoint}/api/{repo_type}s/{repo_id}/preupload/{revision}", json=payload, headers=headers, params={"create_pr": "1"} if create_pr else None, ) hf_raise_for_status(resp) preupload_info = _validate_preupload_info(resp.json()) upload_modes.update(**{file["path"]: file["uploadMode"] for file in preupload_info["files"]}) should_ignore_info.update(**{file["path"]: file["shouldIgnore"] for file in preupload_info["files"]}) oid_info.update(**{file["path"]: file.get("oid") for file in preupload_info["files"]}) # Set upload mode for each addition operation for addition in additions: addition._upload_mode = upload_modes[addition.path_in_repo] addition._should_ignore = should_ignore_info[addition.path_in_repo] addition._remote_oid = oid_info[addition.path_in_repo] # Empty files cannot be uploaded as LFS (S3 would fail with a 501 Not Implemented) # => empty files are uploaded as "regular" to still allow users to commit them. for addition in additions: if addition.upload_info.size == 0: addition._upload_mode = "regular" @validate_hf_hub_args def _fetch_files_to_copy( copies: Iterable[CommitOperationCopy], repo_type: str, repo_id: str, headers: dict[str, str], revision: str, endpoint: Optional[str] = None, ) -> dict[tuple[str, Optional[str]], Union["RepoFile", bytes]]: """ Fetch information about the files to copy. For LFS files, we only need their metadata (file size and sha256) while for regular files we need to download the raw content from the Hub. Args: copies (`Iterable` of :class:`CommitOperationCopy`): Iterable of :class:`CommitOperationCopy` describing the files to copy on the Hub. repo_type (`str`): Type of the repo to upload to: `"model"`, `"dataset"` or `"space"`. repo_id (`str`): A namespace (user or an organization) and a repo name separated by a `/`. headers (`dict[str, str]`): Headers to use for the request, including authorization headers and user agent. revision (`str`): The git revision to upload the files to. Can be any valid git revision. Returns: `dict[tuple[str, Optional[str]], Union[RepoFile, bytes]]]` Key is the file path and revision of the file to copy. Value is the raw content as bytes (for regular files) or the file information as a RepoFile (for LFS files). Raises: [`~utils.HfHubHTTPError`] If the Hub API returned an error. [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) If the Hub API response is improperly formatted. """ from .hf_api import HfApi, RepoFolder hf_api = HfApi(endpoint=endpoint, headers=headers) files_to_copy: dict[tuple[str, Optional[str]], Union["RepoFile", bytes]] = {} # Store (path, revision) -> oid mapping oid_info: dict[tuple[str, Optional[str]], Optional[str]] = {} # 1. Fetch OIDs for destination paths in batches. dest_paths = [op.path_in_repo for op in copies] for offset in range(0, len(dest_paths), FETCH_LFS_BATCH_SIZE): dest_repo_files = hf_api.get_paths_info( repo_id=repo_id, paths=dest_paths[offset : offset + FETCH_LFS_BATCH_SIZE], revision=revision, repo_type=repo_type, ) for file in dest_repo_files: if not isinstance(file, RepoFolder): oid_info[(file.path, revision)] = file.blob_id # 2. Group by source revision and fetch source file info in batches. for src_revision, operations in groupby(copies, key=lambda op: op.src_revision): operations = list(operations) # type: ignore src_paths = [op.src_path_in_repo for op in operations] for offset in range(0, len(src_paths), FETCH_LFS_BATCH_SIZE): src_repo_files = hf_api.get_paths_info( repo_id=repo_id, paths=src_paths[offset : offset + FETCH_LFS_BATCH_SIZE], revision=src_revision or revision, repo_type=repo_type, ) for src_repo_file in src_repo_files: if isinstance(src_repo_file, RepoFolder): raise NotImplementedError("Copying a folder is not implemented.") oid_info[(src_repo_file.path, src_revision)] = src_repo_file.blob_id # If it's an LFS file, store the RepoFile object. Otherwise, download raw bytes. if src_repo_file.lfs: files_to_copy[(src_repo_file.path, src_revision)] = src_repo_file else: # TODO: (optimization) download regular files to copy concurrently url = hf_hub_url( endpoint=endpoint, repo_type=repo_type, repo_id=repo_id, revision=src_revision or revision, filename=src_repo_file.path, ) response = get_session().get(url, headers=headers) hf_raise_for_status(response) files_to_copy[(src_repo_file.path, src_revision)] = response.content # 3. Ensure all operations found a corresponding file in the Hub # and track src/dest OIDs for each operation. for operation in operations: if (operation.src_path_in_repo, src_revision) not in files_to_copy: raise EntryNotFoundError( f"Cannot copy {operation.src_path_in_repo} at revision " f"{src_revision or revision}: file is missing on repo." ) operation._src_oid = oid_info.get((operation.src_path_in_repo, operation.src_revision)) operation._dest_oid = oid_info.get((operation.path_in_repo, revision)) return files_to_copy def _prepare_commit_payload( operations: Iterable[CommitOperation], files_to_copy: dict[tuple[str, Optional[str]], Union["RepoFile", bytes]], commit_message: str, commit_description: Optional[str] = None, parent_commit: Optional[str] = None, ) -> Iterable[dict[str, Any]]: """ Builds the payload to POST to the `/commit` API of the Hub. Payload is returned as an iterator so that it can be streamed as a ndjson in the POST request. For more information, see: - https://github.com/huggingface/huggingface_hub/issues/1085#issuecomment-1265208073 - http://ndjson.org/ """ commit_description = commit_description if commit_description is not None else "" # 1. Send a header item with the commit metadata header_value = {"summary": commit_message, "description": commit_description} if parent_commit is not None: header_value["parentCommit"] = parent_commit yield {"key": "header", "value": header_value} nb_ignored_files = 0 # 2. Send operations, one per line for operation in operations: # Skip ignored files if isinstance(operation, CommitOperationAdd) and operation._should_ignore: logger.debug(f"Skipping file '{operation.path_in_repo}' in commit (ignored by gitignore file).") nb_ignored_files += 1 continue # 2.a. Case adding a regular file if isinstance(operation, CommitOperationAdd) and operation._upload_mode == "regular": yield { "key": "file", "value": { "content": operation.b64content().decode(), "path": operation.path_in_repo, "encoding": "base64", }, } # 2.b. Case adding an LFS file elif isinstance(operation, CommitOperationAdd) and operation._upload_mode == "lfs": yield { "key": "lfsFile", "value": { "path": operation.path_in_repo, "algo": "sha256", "oid": operation.upload_info.sha256.hex(), "size": operation.upload_info.size, }, } # 2.c. Case deleting a file or folder elif isinstance(operation, CommitOperationDelete): yield { "key": "deletedFolder" if operation.is_folder else "deletedFile", "value": {"path": operation.path_in_repo}, } # 2.d. Case copying a file or folder elif isinstance(operation, CommitOperationCopy): file_to_copy = files_to_copy[(operation.src_path_in_repo, operation.src_revision)] if isinstance(file_to_copy, bytes): yield { "key": "file", "value": { "content": base64.b64encode(file_to_copy).decode(), "path": operation.path_in_repo, "encoding": "base64", }, } elif file_to_copy.lfs: yield { "key": "lfsFile", "value": { "path": operation.path_in_repo, "algo": "sha256", "oid": file_to_copy.lfs.sha256, }, } else: raise ValueError( "Malformed files_to_copy (should be raw file content as bytes or RepoFile objects with LFS info." ) # 2.e. Never expected to happen else: raise ValueError( f"Unknown operation to commit. Operation: {operation}. Upload mode:" f" {getattr(operation, '_upload_mode', None)}" ) if nb_ignored_files > 0: logger.info(f"Skipped {nb_ignored_files} file(s) in commit (ignored by gitignore file).") huggingface_hub-1.1.5/src/huggingface_hub/_commit_scheduler.py000066400000000000000000000346371510763414300245770ustar00rootroot00000000000000import atexit import logging import os import time from concurrent.futures import Future from dataclasses import dataclass from io import SEEK_END, SEEK_SET, BytesIO from pathlib import Path from threading import Lock, Thread from typing import Optional, Union from .hf_api import DEFAULT_IGNORE_PATTERNS, CommitInfo, CommitOperationAdd, HfApi from .utils import filter_repo_objects logger = logging.getLogger(__name__) @dataclass(frozen=True) class _FileToUpload: """Temporary dataclass to store info about files to upload. Not meant to be used directly.""" local_path: Path path_in_repo: str size_limit: int last_modified: float class CommitScheduler: """ Scheduler to upload a local folder to the Hub at regular intervals (e.g. push to hub every 5 minutes). The recommended way to use the scheduler is to use it as a context manager. This ensures that the scheduler is properly stopped and the last commit is triggered when the script ends. The scheduler can also be stopped manually with the `stop` method. Checkout the [upload guide](https://huggingface.co/docs/huggingface_hub/guides/upload#scheduled-uploads) to learn more about how to use it. Args: repo_id (`str`): The id of the repo to commit to. folder_path (`str` or `Path`): Path to the local folder to upload regularly. every (`int` or `float`, *optional*): The number of minutes between each commit. Defaults to 5 minutes. path_in_repo (`str`, *optional*): Relative path of the directory in the repo, for example: `"checkpoints/"`. Defaults to the root folder of the repository. repo_type (`str`, *optional*): The type of the repo to commit to. Defaults to `model`. revision (`str`, *optional*): The revision of the repo to commit to. Defaults to `main`. private (`bool`, *optional*): Whether to make the repo private. If `None` (default), the repo will be public unless the organization's default is private. This value is ignored if the repo already exists. token (`str`, *optional*): The token to use to commit to the repo. Defaults to the token saved on the machine. allow_patterns (`list[str]` or `str`, *optional*): If provided, only files matching at least one pattern are uploaded. ignore_patterns (`list[str]` or `str`, *optional*): If provided, files matching any of the patterns are not uploaded. squash_history (`bool`, *optional*): Whether to squash the history of the repo after each commit. Defaults to `False`. Squashing commits is useful to avoid degraded performances on the repo when it grows too large. hf_api (`HfApi`, *optional*): The [`HfApi`] client to use to commit to the Hub. Can be set with custom settings (user agent, token,...). Example: ```py >>> from pathlib import Path >>> from huggingface_hub import CommitScheduler # Scheduler uploads every 10 minutes >>> csv_path = Path("watched_folder/data.csv") >>> CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path=csv_path.parent, every=10) >>> with csv_path.open("a") as f: ... f.write("first line") # Some time later (...) >>> with csv_path.open("a") as f: ... f.write("second line") ``` Example using a context manager: ```py >>> from pathlib import Path >>> from huggingface_hub import CommitScheduler >>> with CommitScheduler(repo_id="test_scheduler", repo_type="dataset", folder_path="watched_folder", every=10) as scheduler: ... csv_path = Path("watched_folder/data.csv") ... with csv_path.open("a") as f: ... f.write("first line") ... (...) ... with csv_path.open("a") as f: ... f.write("second line") # Scheduler is now stopped and last commit have been triggered ``` """ def __init__( self, *, repo_id: str, folder_path: Union[str, Path], every: Union[int, float] = 5, path_in_repo: Optional[str] = None, repo_type: Optional[str] = None, revision: Optional[str] = None, private: Optional[bool] = None, token: Optional[str] = None, allow_patterns: Optional[Union[list[str], str]] = None, ignore_patterns: Optional[Union[list[str], str]] = None, squash_history: bool = False, hf_api: Optional["HfApi"] = None, ) -> None: self.api = hf_api or HfApi(token=token) # Folder self.folder_path = Path(folder_path).expanduser().resolve() self.path_in_repo = path_in_repo or "" self.allow_patterns = allow_patterns if ignore_patterns is None: ignore_patterns = [] elif isinstance(ignore_patterns, str): ignore_patterns = [ignore_patterns] self.ignore_patterns = ignore_patterns + DEFAULT_IGNORE_PATTERNS if self.folder_path.is_file(): raise ValueError(f"'folder_path' must be a directory, not a file: '{self.folder_path}'.") self.folder_path.mkdir(parents=True, exist_ok=True) # Repository repo_url = self.api.create_repo(repo_id=repo_id, private=private, repo_type=repo_type, exist_ok=True) self.repo_id = repo_url.repo_id self.repo_type = repo_type self.revision = revision self.token = token # Keep track of already uploaded files self.last_uploaded: dict[Path, float] = {} # key is local path, value is timestamp # Scheduler if not every > 0: raise ValueError(f"'every' must be a positive integer, not '{every}'.") self.lock = Lock() self.every = every self.squash_history = squash_history logger.info(f"Scheduled job to push '{self.folder_path}' to '{self.repo_id}' every {self.every} minutes.") self._scheduler_thread = Thread(target=self._run_scheduler, daemon=True) self._scheduler_thread.start() atexit.register(self._push_to_hub) self.__stopped = False def stop(self) -> None: """Stop the scheduler. A stopped scheduler cannot be restarted. Mostly for tests purposes. """ self.__stopped = True def __enter__(self) -> "CommitScheduler": return self def __exit__(self, exc_type, exc_value, traceback) -> None: # Upload last changes before exiting self.trigger().result() self.stop() return def _run_scheduler(self) -> None: """Dumb thread waiting between each scheduled push to Hub.""" while True: self.last_future = self.trigger() time.sleep(self.every * 60) if self.__stopped: break def trigger(self) -> Future: """Trigger a `push_to_hub` and return a future. This method is automatically called every `every` minutes. You can also call it manually to trigger a commit immediately, without waiting for the next scheduled commit. """ return self.api.run_as_future(self._push_to_hub) def _push_to_hub(self) -> Optional[CommitInfo]: if self.__stopped: # If stopped, already scheduled commits are ignored return None logger.info("(Background) scheduled commit triggered.") try: value = self.push_to_hub() if self.squash_history: logger.info("(Background) squashing repo history.") self.api.super_squash_history(repo_id=self.repo_id, repo_type=self.repo_type, branch=self.revision) return value except Exception as e: logger.error(f"Error while pushing to Hub: {e}") # Depending on the setup, error might be silenced raise def push_to_hub(self) -> Optional[CommitInfo]: """ Push folder to the Hub and return the commit info. > [!WARNING] > This method is not meant to be called directly. It is run in the background by the scheduler, respecting a > queue mechanism to avoid concurrent commits. Making a direct call to the method might lead to concurrency > issues. The default behavior of `push_to_hub` is to assume an append-only folder. It lists all files in the folder and uploads only changed files. If no changes are found, the method returns without committing anything. If you want to change this behavior, you can inherit from [`CommitScheduler`] and override this method. This can be useful for example to compress data together in a single file before committing. For more details and examples, check out our [integration guide](https://huggingface.co/docs/huggingface_hub/main/en/guides/upload#scheduled-uploads). """ # Check files to upload (with lock) with self.lock: logger.debug("Listing files to upload for scheduled commit.") # List files from folder (taken from `_prepare_upload_folder_additions`) relpath_to_abspath = { path.relative_to(self.folder_path).as_posix(): path for path in sorted(self.folder_path.glob("**/*")) # sorted to be deterministic if path.is_file() } prefix = f"{self.path_in_repo.strip('/')}/" if self.path_in_repo else "" # Filter with pattern + filter out unchanged files + retrieve current file size files_to_upload: list[_FileToUpload] = [] for relpath in filter_repo_objects( relpath_to_abspath.keys(), allow_patterns=self.allow_patterns, ignore_patterns=self.ignore_patterns ): local_path = relpath_to_abspath[relpath] stat = local_path.stat() if self.last_uploaded.get(local_path) is None or self.last_uploaded[local_path] != stat.st_mtime: files_to_upload.append( _FileToUpload( local_path=local_path, path_in_repo=prefix + relpath, size_limit=stat.st_size, last_modified=stat.st_mtime, ) ) # Return if nothing to upload if len(files_to_upload) == 0: logger.debug("Dropping schedule commit: no changed file to upload.") return None # Convert `_FileToUpload` as `CommitOperationAdd` (=> compute file shas + limit to file size) logger.debug("Removing unchanged files since previous scheduled commit.") add_operations = [ CommitOperationAdd( # Cap the file to its current size, even if the user append data to it while a scheduled commit is happening path_or_fileobj=PartialFileIO(file_to_upload.local_path, size_limit=file_to_upload.size_limit), path_in_repo=file_to_upload.path_in_repo, ) for file_to_upload in files_to_upload ] # Upload files (append mode expected - no need for lock) logger.debug("Uploading files for scheduled commit.") commit_info = self.api.create_commit( repo_id=self.repo_id, repo_type=self.repo_type, operations=add_operations, commit_message="Scheduled Commit", revision=self.revision, ) # Successful commit: keep track of the latest "last_modified" for each file for file in files_to_upload: self.last_uploaded[file.local_path] = file.last_modified return commit_info class PartialFileIO(BytesIO): """A file-like object that reads only the first part of a file. Useful to upload a file to the Hub when the user might still be appending data to it. Only the first part of the file is uploaded (i.e. the part that was available when the filesystem was first scanned). In practice, only used internally by the CommitScheduler to regularly push a folder to the Hub with minimal disturbance for the user. The object is passed to `CommitOperationAdd`. Only supports `read`, `tell` and `seek` methods. Args: file_path (`str` or `Path`): Path to the file to read. size_limit (`int`): The maximum number of bytes to read from the file. If the file is larger than this, only the first part will be read (and uploaded). """ def __init__(self, file_path: Union[str, Path], size_limit: int) -> None: self._file_path = Path(file_path) self._file = self._file_path.open("rb") self._size_limit = min(size_limit, os.fstat(self._file.fileno()).st_size) def __del__(self) -> None: self._file.close() return super().__del__() def __repr__(self) -> str: return f"" def __len__(self) -> int: return self._size_limit def __getattribute__(self, name: str): if name.startswith("_") or name in ("read", "tell", "seek", "fileno"): # only 4 public methods supported return super().__getattribute__(name) raise NotImplementedError(f"PartialFileIO does not support '{name}'.") def fileno(self): raise AttributeError("PartialFileIO does not have a fileno.") def tell(self) -> int: """Return the current file position.""" return self._file.tell() def seek(self, __offset: int, __whence: int = SEEK_SET) -> int: """Change the stream position to the given offset. Behavior is the same as a regular file, except that the position is capped to the size limit. """ if __whence == SEEK_END: # SEEK_END => set from the truncated end __offset = len(self) + __offset __whence = SEEK_SET pos = self._file.seek(__offset, __whence) if pos > self._size_limit: return self._file.seek(self._size_limit) return pos def read(self, __size: Optional[int] = -1) -> bytes: """Read at most `__size` bytes from the file. Behavior is the same as a regular file, except that it is capped to the size limit. """ current = self._file.tell() if __size is None or __size < 0: # Read until file limit truncated_size = self._size_limit - current else: # Read until file limit or __size truncated_size = min(__size, self._size_limit - current) return self._file.read(truncated_size) huggingface_hub-1.1.5/src/huggingface_hub/_inference_endpoints.py000066400000000000000000000422711510763414300252630ustar00rootroot00000000000000import time from dataclasses import dataclass, field from datetime import datetime from enum import Enum from typing import TYPE_CHECKING, Optional, Union from huggingface_hub.errors import InferenceEndpointError, InferenceEndpointTimeoutError from .utils import get_session, logging, parse_datetime if TYPE_CHECKING: from .hf_api import HfApi from .inference._client import InferenceClient from .inference._generated._async_client import AsyncInferenceClient logger = logging.get_logger(__name__) class InferenceEndpointStatus(str, Enum): PENDING = "pending" INITIALIZING = "initializing" UPDATING = "updating" UPDATE_FAILED = "updateFailed" RUNNING = "running" PAUSED = "paused" FAILED = "failed" SCALED_TO_ZERO = "scaledToZero" class InferenceEndpointType(str, Enum): PUBlIC = "public" PROTECTED = "protected" PRIVATE = "private" @dataclass class InferenceEndpoint: """ Contains information about a deployed Inference Endpoint. Args: name (`str`): The unique name of the Inference Endpoint. namespace (`str`): The namespace where the Inference Endpoint is located. repository (`str`): The name of the model repository deployed on this Inference Endpoint. status ([`InferenceEndpointStatus`]): The current status of the Inference Endpoint. url (`str`, *optional*): The URL of the Inference Endpoint, if available. Only a deployed Inference Endpoint will have a URL. framework (`str`): The machine learning framework used for the model. revision (`str`): The specific model revision deployed on the Inference Endpoint. task (`str`): The task associated with the deployed model. created_at (`datetime.datetime`): The timestamp when the Inference Endpoint was created. updated_at (`datetime.datetime`): The timestamp of the last update of the Inference Endpoint. type ([`InferenceEndpointType`]): The type of the Inference Endpoint (public, protected, private). raw (`dict`): The raw dictionary data returned from the API. token (`str` or `bool`, *optional*): Authentication token for the Inference Endpoint, if set when requesting the API. Will default to the locally saved token if not provided. Pass `token=False` if you don't want to send your token to the server. Example: ```python >>> from huggingface_hub import get_inference_endpoint >>> endpoint = get_inference_endpoint("my-text-to-image") >>> endpoint InferenceEndpoint(name='my-text-to-image', ...) # Get status >>> endpoint.status 'running' >>> endpoint.url 'https://my-text-to-image.region.vendor.endpoints.huggingface.cloud' # Run inference >>> endpoint.client.text_to_image(...) # Pause endpoint to save $$$ >>> endpoint.pause() # ... # Resume and wait for deployment >>> endpoint.resume() >>> endpoint.wait() >>> endpoint.client.text_to_image(...) ``` """ # Field in __repr__ name: str = field(init=False) namespace: str repository: str = field(init=False) status: InferenceEndpointStatus = field(init=False) health_route: str = field(init=False) url: Optional[str] = field(init=False) # Other fields framework: str = field(repr=False, init=False) revision: str = field(repr=False, init=False) task: str = field(repr=False, init=False) created_at: datetime = field(repr=False, init=False) updated_at: datetime = field(repr=False, init=False) type: InferenceEndpointType = field(repr=False, init=False) # Raw dict from the API raw: dict = field(repr=False) # Internal fields _token: Union[str, bool, None] = field(repr=False, compare=False) _api: "HfApi" = field(repr=False, compare=False) @classmethod def from_raw( cls, raw: dict, namespace: str, token: Union[str, bool, None] = None, api: Optional["HfApi"] = None ) -> "InferenceEndpoint": """Initialize object from raw dictionary.""" if api is None: from .hf_api import HfApi api = HfApi() if token is None: token = api.token # All other fields are populated in __post_init__ return cls(raw=raw, namespace=namespace, _token=token, _api=api) def __post_init__(self) -> None: """Populate fields from raw dictionary.""" self._populate_from_raw() @property def client(self) -> "InferenceClient": """Returns a client to make predictions on this Inference Endpoint. Returns: [`InferenceClient`]: an inference client pointing to the deployed endpoint. Raises: [`InferenceEndpointError`]: If the Inference Endpoint is not yet deployed. """ if self.url is None: raise InferenceEndpointError( "Cannot create a client for this Inference Endpoint as it is not yet deployed. " "Please wait for the Inference Endpoint to be deployed using `endpoint.wait()` and try again." ) from .inference._client import InferenceClient return InferenceClient( model=self.url, token=self._token, # type: ignore[arg-type] # boolean token shouldn't be possible. In practice it's ok. ) @property def async_client(self) -> "AsyncInferenceClient": """Returns a client to make predictions on this Inference Endpoint. Returns: [`AsyncInferenceClient`]: an asyncio-compatible inference client pointing to the deployed endpoint. Raises: [`InferenceEndpointError`]: If the Inference Endpoint is not yet deployed. """ if self.url is None: raise InferenceEndpointError( "Cannot create a client for this Inference Endpoint as it is not yet deployed. " "Please wait for the Inference Endpoint to be deployed using `endpoint.wait()` and try again." ) from .inference._generated._async_client import AsyncInferenceClient return AsyncInferenceClient( model=self.url, token=self._token, # type: ignore[arg-type] # boolean token shouldn't be possible. In practice it's ok. ) def wait(self, timeout: Optional[int] = None, refresh_every: int = 5) -> "InferenceEndpoint": """Wait for the Inference Endpoint to be deployed. Information from the server will be fetched every 1s. If the Inference Endpoint is not deployed after `timeout` seconds, a [`InferenceEndpointTimeoutError`] will be raised. The [`InferenceEndpoint`] will be mutated in place with the latest data. Args: timeout (`int`, *optional*): The maximum time to wait for the Inference Endpoint to be deployed, in seconds. If `None`, will wait indefinitely. refresh_every (`int`, *optional*): The time to wait between each fetch of the Inference Endpoint status, in seconds. Defaults to 5s. Returns: [`InferenceEndpoint`]: the same Inference Endpoint, mutated in place with the latest data. Raises: [`InferenceEndpointError`] If the Inference Endpoint ended up in a failed state. [`InferenceEndpointTimeoutError`] If the Inference Endpoint is not deployed after `timeout` seconds. """ if timeout is not None and timeout < 0: raise ValueError("`timeout` cannot be negative.") if refresh_every <= 0: raise ValueError("`refresh_every` must be positive.") start = time.time() while True: if self.status == InferenceEndpointStatus.FAILED: raise InferenceEndpointError( f"Inference Endpoint {self.name} failed to deploy. Please check the logs for more information." ) if self.status == InferenceEndpointStatus.UPDATE_FAILED: raise InferenceEndpointError( f"Inference Endpoint {self.name} failed to update. Please check the logs for more information." ) if self.status == InferenceEndpointStatus.RUNNING and self.url is not None: # Verify the endpoint is actually reachable _health_url = f"{self.url.rstrip('/')}/{self.health_route.lstrip('/')}" response = get_session().get(_health_url, headers=self._api._build_hf_headers(token=self._token)) if response.status_code == 200: logger.info("Inference Endpoint is ready to be used.") return self if timeout is not None: if time.time() - start > timeout: raise InferenceEndpointTimeoutError("Timeout while waiting for Inference Endpoint to be deployed.") logger.info(f"Inference Endpoint is not deployed yet ({self.status}). Waiting {refresh_every}s...") time.sleep(refresh_every) self.fetch() def fetch(self) -> "InferenceEndpoint": """Fetch latest information about the Inference Endpoint. Returns: [`InferenceEndpoint`]: the same Inference Endpoint, mutated in place with the latest data. """ obj = self._api.get_inference_endpoint(name=self.name, namespace=self.namespace, token=self._token) # type: ignore [arg-type] self.raw = obj.raw self._populate_from_raw() return self def update( self, *, # Compute update accelerator: Optional[str] = None, instance_size: Optional[str] = None, instance_type: Optional[str] = None, min_replica: Optional[int] = None, max_replica: Optional[int] = None, scale_to_zero_timeout: Optional[int] = None, # Model update repository: Optional[str] = None, framework: Optional[str] = None, revision: Optional[str] = None, task: Optional[str] = None, custom_image: Optional[dict] = None, secrets: Optional[dict[str, str]] = None, ) -> "InferenceEndpoint": """Update the Inference Endpoint. This method allows the update of either the compute configuration, the deployed model, or both. All arguments are optional but at least one must be provided. This is an alias for [`HfApi.update_inference_endpoint`]. The current object is mutated in place with the latest data from the server. Args: accelerator (`str`, *optional*): The hardware accelerator to be used for inference (e.g. `"cpu"`). instance_size (`str`, *optional*): The size or type of the instance to be used for hosting the model (e.g. `"x4"`). instance_type (`str`, *optional*): The cloud instance type where the Inference Endpoint will be deployed (e.g. `"intel-icl"`). min_replica (`int`, *optional*): The minimum number of replicas (instances) to keep running for the Inference Endpoint. max_replica (`int`, *optional*): The maximum number of replicas (instances) to scale to for the Inference Endpoint. scale_to_zero_timeout (`int`, *optional*): The duration in minutes before an inactive endpoint is scaled to zero. repository (`str`, *optional*): The name of the model repository associated with the Inference Endpoint (e.g. `"gpt2"`). framework (`str`, *optional*): The machine learning framework used for the model (e.g. `"custom"`). revision (`str`, *optional*): The specific model revision to deploy on the Inference Endpoint (e.g. `"6c0e6080953db56375760c0471a8c5f2929baf11"`). task (`str`, *optional*): The task on which to deploy the model (e.g. `"text-classification"`). custom_image (`dict`, *optional*): A custom Docker image to use for the Inference Endpoint. This is useful if you want to deploy an Inference Endpoint running on the `text-generation-inference` (TGI) framework (see examples). secrets (`dict[str, str]`, *optional*): Secret values to inject in the container environment. Returns: [`InferenceEndpoint`]: the same Inference Endpoint, mutated in place with the latest data. """ # Make API call obj = self._api.update_inference_endpoint( name=self.name, namespace=self.namespace, accelerator=accelerator, instance_size=instance_size, instance_type=instance_type, min_replica=min_replica, max_replica=max_replica, scale_to_zero_timeout=scale_to_zero_timeout, repository=repository, framework=framework, revision=revision, task=task, custom_image=custom_image, secrets=secrets, token=self._token, # type: ignore [arg-type] ) # Mutate current object self.raw = obj.raw self._populate_from_raw() return self def pause(self) -> "InferenceEndpoint": """Pause the Inference Endpoint. A paused Inference Endpoint will not be charged. It can be resumed at any time using [`InferenceEndpoint.resume`]. This is different from scaling the Inference Endpoint to zero with [`InferenceEndpoint.scale_to_zero`], which would be automatically restarted when a request is made to it. This is an alias for [`HfApi.pause_inference_endpoint`]. The current object is mutated in place with the latest data from the server. Returns: [`InferenceEndpoint`]: the same Inference Endpoint, mutated in place with the latest data. """ obj = self._api.pause_inference_endpoint(name=self.name, namespace=self.namespace, token=self._token) # type: ignore [arg-type] self.raw = obj.raw self._populate_from_raw() return self def resume(self, running_ok: bool = True) -> "InferenceEndpoint": """Resume the Inference Endpoint. This is an alias for [`HfApi.resume_inference_endpoint`]. The current object is mutated in place with the latest data from the server. Args: running_ok (`bool`, *optional*): If `True`, the method will not raise an error if the Inference Endpoint is already running. Defaults to `True`. Returns: [`InferenceEndpoint`]: the same Inference Endpoint, mutated in place with the latest data. """ obj = self._api.resume_inference_endpoint( name=self.name, namespace=self.namespace, running_ok=running_ok, token=self._token ) # type: ignore [arg-type] self.raw = obj.raw self._populate_from_raw() return self def scale_to_zero(self) -> "InferenceEndpoint": """Scale Inference Endpoint to zero. An Inference Endpoint scaled to zero will not be charged. It will be resumed on the next request to it, with a cold start delay. This is different from pausing the Inference Endpoint with [`InferenceEndpoint.pause`], which would require a manual resume with [`InferenceEndpoint.resume`]. This is an alias for [`HfApi.scale_to_zero_inference_endpoint`]. The current object is mutated in place with the latest data from the server. Returns: [`InferenceEndpoint`]: the same Inference Endpoint, mutated in place with the latest data. """ obj = self._api.scale_to_zero_inference_endpoint(name=self.name, namespace=self.namespace, token=self._token) # type: ignore [arg-type] self.raw = obj.raw self._populate_from_raw() return self def delete(self) -> None: """Delete the Inference Endpoint. This operation is not reversible. If you don't want to be charged for an Inference Endpoint, it is preferable to pause it with [`InferenceEndpoint.pause`] or scale it to zero with [`InferenceEndpoint.scale_to_zero`]. This is an alias for [`HfApi.delete_inference_endpoint`]. """ self._api.delete_inference_endpoint(name=self.name, namespace=self.namespace, token=self._token) # type: ignore [arg-type] def _populate_from_raw(self) -> None: """Populate fields from raw dictionary. Called in __post_init__ + each time the Inference Endpoint is updated. """ # Repr fields self.name = self.raw["name"] self.repository = self.raw["model"]["repository"] self.status = self.raw["status"]["state"] self.url = self.raw["status"].get("url") self.health_route = self.raw["healthRoute"] # Other fields self.framework = self.raw["model"]["framework"] self.revision = self.raw["model"]["revision"] self.task = self.raw["model"]["task"] self.created_at = parse_datetime(self.raw["status"]["createdAt"]) self.updated_at = parse_datetime(self.raw["status"]["updatedAt"]) self.type = self.raw["type"] huggingface_hub-1.1.5/src/huggingface_hub/_jobs_api.py000066400000000000000000000251671510763414300230350ustar00rootroot00000000000000# coding=utf-8 # Copyright 2025-present, the HuggingFace Inc. team. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. from dataclasses import dataclass from datetime import datetime from enum import Enum from typing import Any, Optional, Union from huggingface_hub import constants from huggingface_hub._space_api import SpaceHardware from huggingface_hub.utils._datetime import parse_datetime class JobStage(str, Enum): """ Enumeration of possible stage of a Job on the Hub. Value can be compared to a string: ```py assert JobStage.COMPLETED == "COMPLETED" ``` Possible values are: `COMPLETED`, `CANCELED`, `ERROR`, `DELETED`, `RUNNING`. Taken from https://github.com/huggingface/moon-landing/blob/main/server/job_types/JobInfo.ts#L61 (private url). """ # Copied from moon-landing > server > lib > Job.ts COMPLETED = "COMPLETED" CANCELED = "CANCELED" ERROR = "ERROR" DELETED = "DELETED" RUNNING = "RUNNING" @dataclass class JobStatus: stage: JobStage message: Optional[str] @dataclass class JobOwner: id: str name: str type: str @dataclass class JobInfo: """ Contains information about a Job. Args: id (`str`): Job ID. created_at (`datetime` or `None`): When the Job was created. docker_image (`str` or `None`): The Docker image from Docker Hub used for the Job. Can be None if space_id is present instead. space_id (`str` or `None`): The Docker image from Hugging Face Spaces used for the Job. Can be None if docker_image is present instead. command (`list[str]` or `None`): Command of the Job, e.g. `["python", "-c", "print('hello world')"]` arguments (`list[str]` or `None`): Arguments passed to the command environment (`dict[str]` or `None`): Environment variables of the Job as a dictionary. secrets (`dict[str]` or `None`): Secret environment variables of the Job (encrypted). flavor (`str` or `None`): Flavor for the hardware, as in Hugging Face Spaces. See [`SpaceHardware`] for possible values. E.g. `"cpu-basic"`. status: (`JobStatus` or `None`): Status of the Job, e.g. `JobStatus(stage="RUNNING", message=None)` See [`JobStage`] for possible stage values. owner: (`JobOwner` or `None`): Owner of the Job, e.g. `JobOwner(id="5e9ecfc04957053f60648a3e", name="lhoestq", type="user")` Example: ```python >>> from huggingface_hub import run_job >>> job = run_job( ... image="python:3.12", ... command=["python", "-c", "print('Hello from the cloud!')"] ... ) >>> job JobInfo(id='687fb701029421ae5549d998', created_at=datetime.datetime(2025, 7, 22, 16, 6, 25, 79000, tzinfo=datetime.timezone.utc), docker_image='python:3.12', space_id=None, command=['python', '-c', "print('Hello from the cloud!')"], arguments=[], environment={}, secrets={}, flavor='cpu-basic', status=JobStatus(stage='RUNNING', message=None), owner=JobOwner(id='5e9ecfc04957053f60648a3e', name='lhoestq', type='user'), endpoint='https://huggingface.co', url='https://huggingface.co/jobs/lhoestq/687fb701029421ae5549d998') >>> job.id '687fb701029421ae5549d998' >>> job.url 'https://huggingface.co/jobs/lhoestq/687fb701029421ae5549d998' >>> job.status.stage 'RUNNING' ``` """ id: str created_at: Optional[datetime] docker_image: Optional[str] space_id: Optional[str] command: Optional[list[str]] arguments: Optional[list[str]] environment: Optional[dict[str, Any]] secrets: Optional[dict[str, Any]] flavor: Optional[SpaceHardware] status: JobStatus owner: JobOwner # Inferred fields endpoint: str url: str def __init__(self, **kwargs) -> None: self.id = kwargs["id"] created_at = kwargs.get("createdAt") or kwargs.get("created_at") self.created_at = parse_datetime(created_at) if created_at else None self.docker_image = kwargs.get("dockerImage") or kwargs.get("docker_image") self.space_id = kwargs.get("spaceId") or kwargs.get("space_id") owner = kwargs.get("owner", {}) self.owner = JobOwner(id=owner["id"], name=owner["name"], type=owner["type"]) self.command = kwargs.get("command") self.arguments = kwargs.get("arguments") self.environment = kwargs.get("environment") self.secrets = kwargs.get("secrets") self.flavor = kwargs.get("flavor") status = kwargs.get("status", {}) self.status = JobStatus(stage=status["stage"], message=status.get("message")) # Inferred fields self.endpoint = kwargs.get("endpoint", constants.ENDPOINT) self.url = f"{self.endpoint}/jobs/{self.owner.name}/{self.id}" @dataclass class JobSpec: docker_image: Optional[str] space_id: Optional[str] command: Optional[list[str]] arguments: Optional[list[str]] environment: Optional[dict[str, Any]] secrets: Optional[dict[str, Any]] flavor: Optional[SpaceHardware] timeout: Optional[int] tags: Optional[list[str]] arch: Optional[str] def __init__(self, **kwargs) -> None: self.docker_image = kwargs.get("dockerImage") or kwargs.get("docker_image") self.space_id = kwargs.get("spaceId") or kwargs.get("space_id") self.command = kwargs.get("command") self.arguments = kwargs.get("arguments") self.environment = kwargs.get("environment") self.secrets = kwargs.get("secrets") self.flavor = kwargs.get("flavor") self.timeout = kwargs.get("timeout") self.tags = kwargs.get("tags") self.arch = kwargs.get("arch") @dataclass class LastJobInfo: id: str at: datetime def __init__(self, **kwargs) -> None: self.id = kwargs["id"] self.at = parse_datetime(kwargs["at"]) @dataclass class ScheduledJobStatus: last_job: Optional[LastJobInfo] next_job_run_at: Optional[datetime] def __init__(self, **kwargs) -> None: last_job = kwargs.get("lastJob") or kwargs.get("last_job") self.last_job = LastJobInfo(**last_job) if last_job else None next_job_run_at = kwargs.get("nextJobRunAt") or kwargs.get("next_job_run_at") self.next_job_run_at = parse_datetime(str(next_job_run_at)) if next_job_run_at else None @dataclass class ScheduledJobInfo: """ Contains information about a Job. Args: id (`str`): Scheduled Job ID. created_at (`datetime` or `None`): When the scheduled Job was created. tags (`list[str]` or `None`): The tags of the scheduled Job. schedule (`str` or `None`): One of "@annually", "@yearly", "@monthly", "@weekly", "@daily", "@hourly", or a CRON schedule expression (e.g., '0 9 * * 1' for 9 AM every Monday). suspend (`bool` or `None`): Whether the scheduled job is suspended (paused). concurrency (`bool` or `None`): Whether multiple instances of this Job can run concurrently. status (`ScheduledJobStatus` or `None`): Status of the scheduled Job. owner: (`JobOwner` or `None`): Owner of the scheduled Job, e.g. `JobOwner(id="5e9ecfc04957053f60648a3e", name="lhoestq", type="user")` job_spec: (`JobSpec` or `None`): Specifications of the Job. Example: ```python >>> from huggingface_hub import run_job >>> scheduled_job = create_scheduled_job( ... image="python:3.12", ... command=["python", "-c", "print('Hello from the cloud!')"], ... schedule="@hourly", ... ) >>> scheduled_job.id '687fb701029421ae5549d999' >>> scheduled_job.status.next_job_run_at datetime.datetime(2025, 7, 22, 17, 6, 25, 79000, tzinfo=datetime.timezone.utc) ``` """ id: str created_at: Optional[datetime] job_spec: JobSpec schedule: Optional[str] suspend: Optional[bool] concurrency: Optional[bool] status: ScheduledJobStatus owner: JobOwner def __init__(self, **kwargs) -> None: self.id = kwargs["id"] created_at = kwargs.get("createdAt") or kwargs.get("created_at") self.created_at = parse_datetime(created_at) if created_at else None self.job_spec = JobSpec(**(kwargs.get("job_spec") or kwargs.get("jobSpec", {}))) self.schedule = kwargs.get("schedule") self.suspend = kwargs.get("suspend") self.concurrency = kwargs.get("concurrency") status = kwargs.get("status", {}) self.status = ScheduledJobStatus( last_job=status.get("last_job") or status.get("lastJob"), next_job_run_at=status.get("next_job_run_at") or status.get("nextJobRunAt"), ) owner = kwargs.get("owner", {}) self.owner = JobOwner(id=owner["id"], name=owner["name"], type=owner["type"]) def _create_job_spec( *, image: str, command: list[str], env: Optional[dict[str, Any]], secrets: Optional[dict[str, Any]], flavor: Optional[SpaceHardware], timeout: Optional[Union[int, float, str]], ) -> dict[str, Any]: # prepare job spec to send to HF Jobs API job_spec: dict[str, Any] = { "command": command, "arguments": [], "environment": env or {}, "flavor": flavor or SpaceHardware.CPU_BASIC, } # secrets are optional if secrets: job_spec["secrets"] = secrets # timeout is optional if timeout: time_units_factors = {"s": 1, "m": 60, "h": 3600, "d": 3600 * 24} if isinstance(timeout, str) and timeout[-1] in time_units_factors: job_spec["timeoutSeconds"] = int(float(timeout[:-1]) * time_units_factors[timeout[-1]]) else: job_spec["timeoutSeconds"] = int(timeout) # input is either from docker hub or from HF spaces for prefix in ( "https://huggingface.co/spaces/", "https://hf.co/spaces/", "huggingface.co/spaces/", "hf.co/spaces/", ): if image.startswith(prefix): job_spec["spaceId"] = image[len(prefix) :] break else: job_spec["dockerImage"] = image return job_spec huggingface_hub-1.1.5/src/huggingface_hub/_local_folder.py000066400000000000000000000416311510763414300236660ustar00rootroot00000000000000# coding=utf-8 # Copyright 2024-present, the HuggingFace Inc. team. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Contains utilities to handle the `../.cache/huggingface` folder in local directories. First discussed in https://github.com/huggingface/huggingface_hub/issues/1738 to store download metadata when downloading files from the hub to a local directory (without using the cache). ./.cache/huggingface folder structure: [4.0K] data ├── [4.0K] .cache │ └── [4.0K] huggingface │ └── [4.0K] download │ ├── [ 16] file.parquet.metadata │ ├── [ 16] file.txt.metadata │ └── [4.0K] folder │ └── [ 16] file.parquet.metadata │ ├── [6.5G] file.parquet ├── [1.5K] file.txt └── [4.0K] folder └── [ 16] file.parquet Download metadata file structure: ``` # file.txt.metadata 11c5a3d5811f50298f278a704980280950aedb10 a16a55fda99d2f2e7b69cce5cf93ff4ad3049930 1712656091.123 # file.parquet.metadata 11c5a3d5811f50298f278a704980280950aedb10 7c5d3f4b8b76583b422fcb9189ad6c89d5d97a094541ce8932dce3ecabde1421 1712656091.123 } ``` """ import base64 import hashlib import logging import os import time from dataclasses import dataclass from pathlib import Path from typing import Optional from .utils import WeakFileLock logger = logging.getLogger(__name__) @dataclass class LocalDownloadFilePaths: """ Paths to the files related to a download process in a local dir. Returned by [`get_local_download_paths`]. Attributes: file_path (`Path`): Path where the file will be saved. lock_path (`Path`): Path to the lock file used to ensure atomicity when reading/writing metadata. metadata_path (`Path`): Path to the metadata file. """ file_path: Path lock_path: Path metadata_path: Path def incomplete_path(self, etag: str) -> Path: """Return the path where a file will be temporarily downloaded before being moved to `file_path`.""" path = self.metadata_path.parent / f"{_short_hash(self.metadata_path.name)}.{etag}.incomplete" resolved_path = str(path.resolve()) # Some Windows versions do not allow for paths longer than 255 characters. # In this case, we must specify it as an extended path by using the "\\?\" prefix. if os.name == "nt" and len(resolved_path) > 255 and not resolved_path.startswith("\\\\?\\"): path = Path("\\\\?\\" + resolved_path) return path @dataclass(frozen=True) class LocalUploadFilePaths: """ Paths to the files related to an upload process in a local dir. Returned by [`get_local_upload_paths`]. Attributes: path_in_repo (`str`): Path of the file in the repo. file_path (`Path`): Path where the file will be saved. lock_path (`Path`): Path to the lock file used to ensure atomicity when reading/writing metadata. metadata_path (`Path`): Path to the metadata file. """ path_in_repo: str file_path: Path lock_path: Path metadata_path: Path @dataclass class LocalDownloadFileMetadata: """ Metadata about a file in the local directory related to a download process. Attributes: filename (`str`): Path of the file in the repo. commit_hash (`str`): Commit hash of the file in the repo. etag (`str`): ETag of the file in the repo. Used to check if the file has changed. For LFS files, this is the sha256 of the file. For regular files, it corresponds to the git hash. timestamp (`int`): Unix timestamp of when the metadata was saved i.e. when the metadata was accurate. """ filename: str commit_hash: str etag: str timestamp: float @dataclass class LocalUploadFileMetadata: """ Metadata about a file in the local directory related to an upload process. """ size: int # Default values correspond to "we don't know yet" timestamp: Optional[float] = None should_ignore: Optional[bool] = None sha256: Optional[str] = None upload_mode: Optional[str] = None remote_oid: Optional[str] = None is_uploaded: bool = False is_committed: bool = False def save(self, paths: LocalUploadFilePaths) -> None: """Save the metadata to disk.""" with WeakFileLock(paths.lock_path): with paths.metadata_path.open("w") as f: new_timestamp = time.time() f.write(str(new_timestamp) + "\n") f.write(str(self.size)) # never None f.write("\n") if self.should_ignore is not None: f.write(str(int(self.should_ignore))) f.write("\n") if self.sha256 is not None: f.write(self.sha256) f.write("\n") if self.upload_mode is not None: f.write(self.upload_mode) f.write("\n") if self.remote_oid is not None: f.write(self.remote_oid) f.write("\n") f.write(str(int(self.is_uploaded)) + "\n") f.write(str(int(self.is_committed)) + "\n") self.timestamp = new_timestamp def get_local_download_paths(local_dir: Path, filename: str) -> LocalDownloadFilePaths: """Compute paths to the files related to a download process. Folders containing the paths are all guaranteed to exist. Args: local_dir (`Path`): Path to the local directory in which files are downloaded. filename (`str`): Path of the file in the repo. Return: [`LocalDownloadFilePaths`]: the paths to the files (file_path, lock_path, metadata_path, incomplete_path). """ # filename is the path in the Hub repository (separated by '/') # make sure to have a cross-platform transcription sanitized_filename = os.path.join(*filename.split("/")) if os.name == "nt": if sanitized_filename.startswith("..\\") or "\\..\\" in sanitized_filename: raise ValueError( f"Invalid filename: cannot handle filename '{sanitized_filename}' on Windows. Please ask the repository" " owner to rename this file." ) file_path = local_dir / sanitized_filename metadata_path = _huggingface_dir(local_dir) / "download" / f"{sanitized_filename}.metadata" lock_path = metadata_path.with_suffix(".lock") # Some Windows versions do not allow for paths longer than 255 characters. # In this case, we must specify it as an extended path by using the "\\?\" prefix if os.name == "nt": if not str(local_dir).startswith("\\\\?\\") and len(os.path.abspath(lock_path)) > 255: file_path = Path("\\\\?\\" + os.path.abspath(file_path)) lock_path = Path("\\\\?\\" + os.path.abspath(lock_path)) metadata_path = Path("\\\\?\\" + os.path.abspath(metadata_path)) file_path.parent.mkdir(parents=True, exist_ok=True) metadata_path.parent.mkdir(parents=True, exist_ok=True) return LocalDownloadFilePaths(file_path=file_path, lock_path=lock_path, metadata_path=metadata_path) def get_local_upload_paths(local_dir: Path, filename: str) -> LocalUploadFilePaths: """Compute paths to the files related to an upload process. Folders containing the paths are all guaranteed to exist. Args: local_dir (`Path`): Path to the local directory that is uploaded. filename (`str`): Path of the file in the repo. Return: [`LocalUploadFilePaths`]: the paths to the files (file_path, lock_path, metadata_path). """ # filename is the path in the Hub repository (separated by '/') # make sure to have a cross-platform transcription sanitized_filename = os.path.join(*filename.split("/")) if os.name == "nt": if sanitized_filename.startswith("..\\") or "\\..\\" in sanitized_filename: raise ValueError( f"Invalid filename: cannot handle filename '{sanitized_filename}' on Windows. Please ask the repository" " owner to rename this file." ) file_path = local_dir / sanitized_filename metadata_path = _huggingface_dir(local_dir) / "upload" / f"{sanitized_filename}.metadata" lock_path = metadata_path.with_suffix(".lock") # Some Windows versions do not allow for paths longer than 255 characters. # In this case, we must specify it as an extended path by using the "\\?\" prefix if os.name == "nt": if not str(local_dir).startswith("\\\\?\\") and len(os.path.abspath(lock_path)) > 255: file_path = Path("\\\\?\\" + os.path.abspath(file_path)) lock_path = Path("\\\\?\\" + os.path.abspath(lock_path)) metadata_path = Path("\\\\?\\" + os.path.abspath(metadata_path)) file_path.parent.mkdir(parents=True, exist_ok=True) metadata_path.parent.mkdir(parents=True, exist_ok=True) return LocalUploadFilePaths( path_in_repo=filename, file_path=file_path, lock_path=lock_path, metadata_path=metadata_path ) def read_download_metadata(local_dir: Path, filename: str) -> Optional[LocalDownloadFileMetadata]: """Read metadata about a file in the local directory related to a download process. Args: local_dir (`Path`): Path to the local directory in which files are downloaded. filename (`str`): Path of the file in the repo. Return: `[LocalDownloadFileMetadata]` or `None`: the metadata if it exists, `None` otherwise. """ paths = get_local_download_paths(local_dir, filename) with WeakFileLock(paths.lock_path): if paths.metadata_path.exists(): try: with paths.metadata_path.open() as f: commit_hash = f.readline().strip() etag = f.readline().strip() timestamp = float(f.readline().strip()) metadata = LocalDownloadFileMetadata( filename=filename, commit_hash=commit_hash, etag=etag, timestamp=timestamp, ) except Exception as e: # remove the metadata file if it is corrupted / not the right format logger.warning( f"Invalid metadata file {paths.metadata_path}: {e}. Removing it from disk and continue." ) try: paths.metadata_path.unlink() except Exception as e: logger.warning(f"Could not remove corrupted metadata file {paths.metadata_path}: {e}") try: # check if the file exists and hasn't been modified since the metadata was saved stat = paths.file_path.stat() if ( stat.st_mtime - 1 <= metadata.timestamp ): # allow 1s difference as stat.st_mtime might not be precise return metadata logger.info(f"Ignored metadata for '{filename}' (outdated). Will re-compute hash.") except FileNotFoundError: # file does not exist => metadata is outdated return None return None def read_upload_metadata(local_dir: Path, filename: str) -> LocalUploadFileMetadata: """Read metadata about a file in the local directory related to an upload process. TODO: factorize logic with `read_download_metadata`. Args: local_dir (`Path`): Path to the local directory in which files are downloaded. filename (`str`): Path of the file in the repo. Return: `[LocalUploadFileMetadata]` or `None`: the metadata if it exists, `None` otherwise. """ paths = get_local_upload_paths(local_dir, filename) with WeakFileLock(paths.lock_path): if paths.metadata_path.exists(): try: with paths.metadata_path.open() as f: timestamp = float(f.readline().strip()) size = int(f.readline().strip()) # never None _should_ignore = f.readline().strip() should_ignore = None if _should_ignore == "" else bool(int(_should_ignore)) _sha256 = f.readline().strip() sha256 = None if _sha256 == "" else _sha256 _upload_mode = f.readline().strip() upload_mode = None if _upload_mode == "" else _upload_mode if upload_mode not in (None, "regular", "lfs"): raise ValueError(f"Invalid upload mode in metadata {paths.path_in_repo}: {upload_mode}") _remote_oid = f.readline().strip() remote_oid = None if _remote_oid == "" else _remote_oid is_uploaded = bool(int(f.readline().strip())) is_committed = bool(int(f.readline().strip())) metadata = LocalUploadFileMetadata( timestamp=timestamp, size=size, should_ignore=should_ignore, sha256=sha256, upload_mode=upload_mode, remote_oid=remote_oid, is_uploaded=is_uploaded, is_committed=is_committed, ) except Exception as e: # remove the metadata file if it is corrupted / not the right format logger.warning( f"Invalid metadata file {paths.metadata_path}: {e}. Removing it from disk and continue." ) try: paths.metadata_path.unlink() except Exception as e: logger.warning(f"Could not remove corrupted metadata file {paths.metadata_path}: {e}") # TODO: can we do better? if ( metadata.timestamp is not None and metadata.is_uploaded # file was uploaded and not metadata.is_committed # but not committed and time.time() - metadata.timestamp > 20 * 3600 # and it's been more than 20 hours ): # => we consider it as garbage-collected by S3 metadata.is_uploaded = False # check if the file exists and hasn't been modified since the metadata was saved try: if metadata.timestamp is not None and paths.file_path.stat().st_mtime <= metadata.timestamp: return metadata logger.info(f"Ignored metadata for '{filename}' (outdated). Will re-compute hash.") except FileNotFoundError: # file does not exist => metadata is outdated pass # empty metadata => we don't know anything expect its size return LocalUploadFileMetadata(size=paths.file_path.stat().st_size) def write_download_metadata(local_dir: Path, filename: str, commit_hash: str, etag: str) -> None: """Write metadata about a file in the local directory related to a download process. Args: local_dir (`Path`): Path to the local directory in which files are downloaded. """ paths = get_local_download_paths(local_dir, filename) with WeakFileLock(paths.lock_path): with paths.metadata_path.open("w") as f: f.write(f"{commit_hash}\n{etag}\n{time.time()}\n") def _huggingface_dir(local_dir: Path) -> Path: """Return the path to the `.cache/huggingface` directory in a local directory.""" # Wrap in lru_cache to avoid overwriting the .gitignore file if called multiple times path = local_dir / ".cache" / "huggingface" path.mkdir(exist_ok=True, parents=True) # Create a .gitignore file in the .cache/huggingface directory if it doesn't exist # Should be thread-safe enough like this. gitignore = path / ".gitignore" gitignore_lock = path / ".gitignore.lock" if not gitignore.exists(): try: with WeakFileLock(gitignore_lock, timeout=0.1): gitignore.write_text("*") except IndexError: pass except OSError: # TimeoutError, FileNotFoundError, PermissionError, etc. pass try: gitignore_lock.unlink() except OSError: pass return path def _short_hash(filename: str) -> str: return base64.urlsafe_b64encode(hashlib.sha1(filename.encode()).digest()).decode() huggingface_hub-1.1.5/src/huggingface_hub/_login.py000066400000000000000000000450331510763414300223510ustar00rootroot00000000000000# Copyright 2020 The HuggingFace Team. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Contains methods to log in to the Hub.""" import os import subprocess from getpass import getpass from pathlib import Path from typing import Optional import typer from . import constants from .utils import ( ANSI, capture_output, get_token, is_google_colab, is_notebook, list_credential_helpers, logging, run_subprocess, set_git_credential, unset_git_credential, ) from .utils._auth import ( _get_token_by_name, _get_token_from_environment, _get_token_from_file, _get_token_from_google_colab, _save_stored_tokens, _save_token, get_stored_tokens, ) logger = logging.get_logger(__name__) _HF_LOGO_ASCII = """ _| _| _| _| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _|_|_|_| _|_| _|_|_| _|_|_|_| _| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _| _|_|_|_| _| _| _| _|_| _| _|_| _| _| _| _| _| _|_| _|_|_| _|_|_|_| _| _|_|_| _| _| _| _| _| _| _| _| _| _| _|_| _| _| _| _| _| _| _| _| _| _|_| _|_|_| _|_|_| _|_|_| _| _| _|_|_| _| _| _| _|_|_| _|_|_|_| """ def login( token: Optional[str] = None, *, add_to_git_credential: bool = False, skip_if_logged_in: bool = False, ) -> None: """Login the machine to access the Hub. The `token` is persisted in cache and set as a git credential. Once done, the machine is logged in and the access token will be available across all `huggingface_hub` components. If `token` is not provided, it will be prompted to the user either with a widget (in a notebook) or via the terminal. To log in from outside of a script, one can also use `hf auth login` which is a cli command that wraps [`login`]. > [!TIP] > [`login`] is a drop-in replacement method for [`notebook_login`] as it wraps and > extends its capabilities. > [!TIP] > When the token is not passed, [`login`] will automatically detect if the script runs > in a notebook or not. However, this detection might not be accurate due to the > variety of notebooks that exists nowadays. If that is the case, you can always force > the UI by using [`notebook_login`] or [`interpreter_login`]. Args: token (`str`, *optional*): User access token to generate from https://huggingface.co/settings/token. add_to_git_credential (`bool`, defaults to `False`): If `True`, token will be set as git credential. If no git credential helper is configured, a warning will be displayed to the user. If `token` is `None`, the value of `add_to_git_credential` is ignored and will be prompted again to the end user. skip_if_logged_in (`bool`, defaults to `False`): If `True`, do not prompt for token if user is already logged in. Raises: [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) If an organization token is passed. Only personal account tokens are valid to log in. [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) If token is invalid. [`ImportError`](https://docs.python.org/3/library/exceptions.html#ImportError) If running in a notebook but `ipywidgets` is not installed. """ if token is not None: if not add_to_git_credential: logger.info( "The token has not been saved to the git credentials helper. Pass " "`add_to_git_credential=True` in this function directly or " "`--add-to-git-credential` if using via `hf`CLI if " "you want to set the git credential as well." ) _login(token, add_to_git_credential=add_to_git_credential) elif is_notebook(): notebook_login(skip_if_logged_in=skip_if_logged_in) else: interpreter_login(skip_if_logged_in=skip_if_logged_in) def logout(token_name: Optional[str] = None) -> None: """Logout the machine from the Hub. Token is deleted from the machine and removed from git credential. Args: token_name (`str`, *optional*): Name of the access token to logout from. If `None`, will log out from all saved access tokens. Raises: [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError): If the access token name is not found. """ if get_token() is None and not get_stored_tokens(): # No active token and no saved access tokens logger.warning("Not logged in!") return if not token_name: # Delete all saved access tokens and token for file_path in (constants.HF_TOKEN_PATH, constants.HF_STORED_TOKENS_PATH): try: Path(file_path).unlink() except FileNotFoundError: pass logger.info("Successfully logged out from all access tokens.") else: _logout_from_token(token_name) logger.info(f"Successfully logged out from access token: {token_name}.") unset_git_credential() # Check if still logged in if _get_token_from_google_colab() is not None: raise EnvironmentError( "You are automatically logged in using a Google Colab secret.\n" "To log out, you must unset the `HF_TOKEN` secret in your Colab settings." ) if _get_token_from_environment() is not None: raise EnvironmentError( "Token has been deleted from your machine but you are still logged in.\n" "To log out, you must clear out both `HF_TOKEN` and `HUGGING_FACE_HUB_TOKEN` environment variables." ) def auth_switch(token_name: str, add_to_git_credential: bool = False) -> None: """Switch to a different access token. Args: token_name (`str`): Name of the access token to switch to. add_to_git_credential (`bool`, defaults to `False`): If `True`, token will be set as git credential. If no git credential helper is configured, a warning will be displayed to the user. If `token` is `None`, the value of `add_to_git_credential` is ignored and will be prompted again to the end user. Raises: [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError): If the access token name is not found. """ token = _get_token_by_name(token_name) if not token: raise ValueError(f"Access token {token_name} not found in {constants.HF_STORED_TOKENS_PATH}") # Write token to HF_TOKEN_PATH _set_active_token(token_name, add_to_git_credential) logger.info(f"The current active token is: {token_name}") token_from_environment = _get_token_from_environment() if token_from_environment is not None and token_from_environment != token: logger.warning( "The environment variable `HF_TOKEN` is set and will override the access token you've just switched to." ) def auth_list() -> None: """List all stored access tokens.""" tokens = get_stored_tokens() if not tokens: logger.info("No access tokens found.") return # Find current token current_token = get_token() current_token_name = None for token_name in tokens: if tokens.get(token_name) == current_token: current_token_name = token_name # Print header max_offset = max(len("token"), max(len(token) for token in tokens)) + 2 print(f" {{:<{max_offset}}}| {{:<15}}".format("name", "token")) print("-" * (max_offset + 2) + "|" + "-" * 15) # Print saved access tokens for token_name in tokens: token = tokens.get(token_name, "") masked_token = f"{token[:3]}****{token[-4:]}" if token != "" else token is_current = "*" if token == current_token else " " print(f"{is_current} {{:<{max_offset}}}| {{:<15}}".format(token_name, masked_token)) if _get_token_from_environment(): logger.warning( "\nNote: Environment variable `HF_TOKEN` is set and is the current active token independently from the stored tokens listed above." ) elif current_token_name is None: logger.warning( "\nNote: No active token is set and no environment variable `HF_TOKEN` is found. Use `hf auth login` to log in." ) ### # Interpreter-based login (text) ### def interpreter_login(*, skip_if_logged_in: bool = False) -> None: """ Displays a prompt to log in to the HF website and store the token. This is equivalent to [`login`] without passing a token when not run in a notebook. [`interpreter_login`] is useful if you want to force the use of the terminal prompt instead of a notebook widget. For more details, see [`login`]. Args: skip_if_logged_in (`bool`, defaults to `False`): If `True`, do not prompt for token if user is already logged in. """ if not skip_if_logged_in and get_token() is not None: logger.info("User is already logged in.") return print(_HF_LOGO_ASCII) if get_token() is not None: logger.info( " A token is already saved on your machine. Run `hf auth whoami`" " to get more information or `hf auth logout` if you want" " to log out." ) logger.info(" Setting a new token will erase the existing one.") logger.info( " To log in, `huggingface_hub` requires a token generated from https://huggingface.co/settings/tokens ." ) if os.name == "nt": logger.info("Token can be pasted using 'Right-Click'.") token = getpass("Enter your token (input will not be visible): ") add_to_git_credential = typer.confirm("Add token as git credential?") _login(token=token, add_to_git_credential=add_to_git_credential) ### # Notebook-based login (widget) ### NOTEBOOK_LOGIN_PASSWORD_HTML = """
Hugging Face
Immediately click login after typing your password or it might be stored in plain text in this notebook file.
""" NOTEBOOK_LOGIN_TOKEN_HTML_START = """
Hugging Face
Copy a token from your Hugging Face tokens page and paste it below.
Immediately click login after copying your token or it might be stored in plain text in this notebook file.
""" NOTEBOOK_LOGIN_TOKEN_HTML_END = """ Pro Tip: If you don't already have one, you can create a dedicated 'notebooks' token with 'write' access, that you can then easily reuse for all notebooks. """ def notebook_login(*, skip_if_logged_in: bool = False) -> None: """ Displays a widget to log in to the HF website and store the token. This is equivalent to [`login`] without passing a token when run in a notebook. [`notebook_login`] is useful if you want to force the use of the notebook widget instead of a prompt in the terminal. For more details, see [`login`]. Args: skip_if_logged_in (`bool`, defaults to `False`): If `True`, do not prompt for token if user is already logged in. """ try: import ipywidgets.widgets as widgets # type: ignore from IPython.display import display # type: ignore except ImportError: raise ImportError( "The `notebook_login` function can only be used in a notebook (Jupyter or" " Colab) and you need the `ipywidgets` module: `pip install ipywidgets`." ) if not skip_if_logged_in and get_token() is not None: logger.info("User is already logged in.") return box_layout = widgets.Layout(display="flex", flex_flow="column", align_items="center", width="50%") token_widget = widgets.Password(description="Token:") git_checkbox_widget = widgets.Checkbox(value=True, description="Add token as git credential?") token_finish_button = widgets.Button(description="Login") login_token_widget = widgets.VBox( [ widgets.HTML(NOTEBOOK_LOGIN_TOKEN_HTML_START), token_widget, git_checkbox_widget, token_finish_button, widgets.HTML(NOTEBOOK_LOGIN_TOKEN_HTML_END), ], layout=box_layout, ) display(login_token_widget) # On click events def login_token_event(t): """Event handler for the login button.""" token = token_widget.value add_to_git_credential = git_checkbox_widget.value # Erase token and clear value to make sure it's not saved in the notebook. token_widget.value = "" # Hide inputs login_token_widget.children = [widgets.Label("Connecting...")] try: with capture_output() as captured: _login(token, add_to_git_credential=add_to_git_credential) message = captured.getvalue() except Exception as error: message = str(error) # Print result (success message or error) login_token_widget.children = [widgets.Label(line) for line in message.split("\n") if line.strip()] token_finish_button.on_click(login_token_event) ### # Login private helpers ### def _login( token: str, add_to_git_credential: bool, ) -> None: from .hf_api import whoami # avoid circular import if token.startswith("api_org"): raise ValueError("You must use your personal account token, not an organization token.") token_info = whoami(token) permission = token_info["auth"]["accessToken"]["role"] logger.info(f"Token is valid (permission: {permission}).") token_name = token_info["auth"]["accessToken"]["displayName"] # Store token locally _save_token(token=token, token_name=token_name) # Set active token _set_active_token(token_name=token_name, add_to_git_credential=add_to_git_credential) logger.info("Login successful.") if _get_token_from_environment(): logger.warning( "Note: Environment variable`HF_TOKEN` is set and is the current active token independently from the token you've just configured." ) else: logger.info(f"The current active token is: `{token_name}`") def _logout_from_token(token_name: str) -> None: """Logout from a specific access token. Args: token_name (`str`): The name of the access token to logout from. Raises: [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError): If the access token name is not found. """ stored_tokens = get_stored_tokens() # If there is no access tokens saved or the access token name is not found, do nothing if not stored_tokens or token_name not in stored_tokens: return token = stored_tokens.pop(token_name) _save_stored_tokens(stored_tokens) if token == _get_token_from_file(): logger.warning(f"Active token '{token_name}' has been deleted.") Path(constants.HF_TOKEN_PATH).unlink(missing_ok=True) def _set_active_token( token_name: str, add_to_git_credential: bool, ) -> None: """Set the active access token. Args: token_name (`str`): The name of the token to set as active. """ token = _get_token_by_name(token_name) if not token: raise ValueError(f"Token {token_name} not found in {constants.HF_STORED_TOKENS_PATH}") if add_to_git_credential: if _is_git_credential_helper_configured(): set_git_credential(token) logger.info( "Your token has been saved in your configured git credential helpers" + f" ({','.join(list_credential_helpers())})." ) else: logger.warning("Token has not been saved to git credential helper.") # Write token to HF_TOKEN_PATH path = Path(constants.HF_TOKEN_PATH) path.parent.mkdir(parents=True, exist_ok=True) path.write_text(token) logger.info(f"Your token has been saved to {constants.HF_TOKEN_PATH}") def _is_git_credential_helper_configured() -> bool: """Check if a git credential helper is configured. Warns user if not the case (except for Google Colab where "store" is set by default by `huggingface_hub`). """ helpers = list_credential_helpers() if len(helpers) > 0: return True # Do not warn: at least 1 helper is set # Only in Google Colab to avoid the warning message # See https://github.com/huggingface/huggingface_hub/issues/1043#issuecomment-1247010710 if is_google_colab(): _set_store_as_git_credential_helper_globally() return True # Do not warn: "store" is used by default in Google Colab # Otherwise, warn user print( ANSI.red( "Cannot authenticate through git-credential as no helper is defined on your" " machine.\nYou might have to re-authenticate when pushing to the Hugging" " Face Hub.\nRun the following command in your terminal in case you want to" " set the 'store' credential helper as default.\n\ngit config --global" " credential.helper store\n\nRead" " https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage for more" " details." ) ) return False def _set_store_as_git_credential_helper_globally() -> None: """Set globally the credential.helper to `store`. To be used only in Google Colab as we assume the user doesn't care about the git credential config. It is the only particular case where we don't want to display the warning message in [`notebook_login()`]. Related: - https://github.com/huggingface/huggingface_hub/issues/1043 - https://github.com/huggingface/huggingface_hub/issues/1051 - https://git-scm.com/docs/git-credential-store """ try: run_subprocess("git config --global credential.helper store") except subprocess.CalledProcessError as exc: raise EnvironmentError(exc.stderr) huggingface_hub-1.1.5/src/huggingface_hub/_oauth.py000066400000000000000000000444071510763414300223650ustar00rootroot00000000000000import datetime import hashlib import logging import os import time import urllib.parse import warnings from dataclasses import dataclass from typing import TYPE_CHECKING, Literal, Optional, Union from . import constants from .hf_api import whoami from .utils import experimental, get_token logger = logging.getLogger(__name__) if TYPE_CHECKING: import fastapi @dataclass class OAuthOrgInfo: """ Information about an organization linked to a user logged in with OAuth. Attributes: sub (`str`): Unique identifier for the org. OpenID Connect field. name (`str`): The org's full name. OpenID Connect field. preferred_username (`str`): The org's username. OpenID Connect field. picture (`str`): The org's profile picture URL. OpenID Connect field. is_enterprise (`bool`): Whether the org is an enterprise org. Hugging Face field. can_pay (`Optional[bool]`, *optional*): Whether the org has a payment method set up. Hugging Face field. role_in_org (`Optional[str]`, *optional*): The user's role in the org. Hugging Face field. security_restrictions (`Optional[list[Literal["ip", "token-policy", "mfa", "sso"]]]`, *optional*): Array of security restrictions that the user hasn't completed for this org. Possible values: "ip", "token-policy", "mfa", "sso". Hugging Face field. """ sub: str name: str preferred_username: str picture: str is_enterprise: bool can_pay: Optional[bool] = None role_in_org: Optional[str] = None security_restrictions: Optional[list[Literal["ip", "token-policy", "mfa", "sso"]]] = None @dataclass class OAuthUserInfo: """ Information about a user logged in with OAuth. Attributes: sub (`str`): Unique identifier for the user, even in case of rename. OpenID Connect field. name (`str`): The user's full name. OpenID Connect field. preferred_username (`str`): The user's username. OpenID Connect field. email_verified (`Optional[bool]`, *optional*): Indicates if the user's email is verified. OpenID Connect field. email (`Optional[str]`, *optional*): The user's email address. OpenID Connect field. picture (`str`): The user's profile picture URL. OpenID Connect field. profile (`str`): The user's profile URL. OpenID Connect field. website (`Optional[str]`, *optional*): The user's website URL. OpenID Connect field. is_pro (`bool`): Whether the user is a pro user. Hugging Face field. can_pay (`Optional[bool]`, *optional*): Whether the user has a payment method set up. Hugging Face field. orgs (`Optional[list[OrgInfo]]`, *optional*): List of organizations the user is part of. Hugging Face field. """ sub: str name: str preferred_username: str email_verified: Optional[bool] email: Optional[str] picture: str profile: str website: Optional[str] is_pro: bool can_pay: Optional[bool] orgs: Optional[list[OAuthOrgInfo]] @dataclass class OAuthInfo: """ Information about the OAuth login. Attributes: access_token (`str`): The access token. access_token_expires_at (`datetime.datetime`): The expiration date of the access token. user_info ([`OAuthUserInfo`]): The user information. state (`str`, *optional*): State passed to the OAuth provider in the original request to the OAuth provider. scope (`str`): Granted scope. """ access_token: str access_token_expires_at: datetime.datetime user_info: OAuthUserInfo state: Optional[str] scope: str @experimental def attach_huggingface_oauth(app: "fastapi.FastAPI", route_prefix: str = "/"): """ Add OAuth endpoints to a FastAPI app to enable OAuth login with Hugging Face. How to use: - Call this method on your FastAPI app to add the OAuth endpoints. - Inside your route handlers, call `parse_huggingface_oauth(request)` to retrieve the OAuth info. - If user is logged in, an [`OAuthInfo`] object is returned with the user's info. If not, `None` is returned. - In your app, make sure to add links to `/oauth/huggingface/login` and `/oauth/huggingface/logout` for the user to log in and out. Example: ```py from huggingface_hub import attach_huggingface_oauth, parse_huggingface_oauth # Create a FastAPI app app = FastAPI() # Add OAuth endpoints to the FastAPI app attach_huggingface_oauth(app) # Add a route that greets the user if they are logged in @app.get("/") def greet_json(request: Request): # Retrieve the OAuth info from the request oauth_info = parse_huggingface_oauth(request) # e.g. OAuthInfo dataclass if oauth_info is None: return {"msg": "Not logged in!"} return {"msg": f"Hello, {oauth_info.user_info.preferred_username}!"} ``` """ # TODO: handle generic case (handling OAuth in a non-Space environment with custom dev values) (low priority) # Add SessionMiddleware to the FastAPI app to store the OAuth info in the session. # Session Middleware requires a secret key to sign the cookies. Let's use a hash # of the OAuth secret key to make it unique to the Space + updated in case OAuth # config gets updated. When ran locally, we use an empty string as a secret key. try: from starlette.middleware.sessions import SessionMiddleware except ImportError as e: raise ImportError( "Cannot initialize OAuth to due a missing library. Please run `pip install huggingface_hub[oauth]` or add " "`huggingface_hub[oauth]` to your requirements.txt file in order to install the required dependencies." ) from e session_secret = (constants.OAUTH_CLIENT_SECRET or "") + "-v1" app.add_middleware( SessionMiddleware, # type: ignore[arg-type] secret_key=hashlib.sha256(session_secret.encode()).hexdigest(), same_site="none", https_only=True, ) # type: ignore # Add OAuth endpoints to the FastAPI app: # - {route_prefix}/oauth/huggingface/login # - {route_prefix}/oauth/huggingface/callback # - {route_prefix}/oauth/huggingface/logout # If the app is running in a Space, OAuth is enabled normally. # Otherwise, we mock the endpoints to make the user log in with a fake user profile - without any calls to hf.co. route_prefix = route_prefix.strip("/") if os.getenv("SPACE_ID") is not None: logger.info("OAuth is enabled in the Space. Adding OAuth routes.") _add_oauth_routes(app, route_prefix=route_prefix) else: logger.info("App is not running in a Space. Adding mocked OAuth routes.") _add_mocked_oauth_routes(app, route_prefix=route_prefix) def parse_huggingface_oauth(request: "fastapi.Request") -> Optional[OAuthInfo]: """ Returns the information from a logged-in user as a [`OAuthInfo`] object. For flexibility and future-proofing, this method is very lax in its parsing and does not raise errors. Missing fields are set to `None` without a warning. Return `None`, if the user is not logged in (no info in session cookie). See [`attach_huggingface_oauth`] for an example on how to use this method. """ if "oauth_info" not in request.session: logger.debug("No OAuth info in session.") return None logger.debug("Parsing OAuth info from session.") oauth_data = request.session["oauth_info"] user_data = oauth_data.get("userinfo", {}) orgs_data = user_data.get("orgs", []) orgs = ( [ OAuthOrgInfo( sub=org.get("sub"), name=org.get("name"), preferred_username=org.get("preferred_username"), picture=org.get("picture"), is_enterprise=org.get("isEnterprise"), can_pay=org.get("canPay"), role_in_org=org.get("roleInOrg"), security_restrictions=org.get("securityRestrictions"), ) for org in orgs_data ] if orgs_data else None ) user_info = OAuthUserInfo( sub=user_data.get("sub"), name=user_data.get("name"), preferred_username=user_data.get("preferred_username"), email_verified=user_data.get("email_verified"), email=user_data.get("email"), picture=user_data.get("picture"), profile=user_data.get("profile"), website=user_data.get("website"), is_pro=user_data.get("isPro"), can_pay=user_data.get("canPay"), orgs=orgs, ) return OAuthInfo( access_token=oauth_data.get("access_token"), access_token_expires_at=datetime.datetime.fromtimestamp(oauth_data.get("expires_at")), user_info=user_info, state=oauth_data.get("state"), scope=oauth_data.get("scope"), ) def _add_oauth_routes(app: "fastapi.FastAPI", route_prefix: str) -> None: """Add OAuth routes to the FastAPI app (login, callback handler and logout).""" try: import fastapi from authlib.integrations.base_client.errors import MismatchingStateError from authlib.integrations.starlette_client import OAuth from fastapi.responses import RedirectResponse except ImportError as e: raise ImportError( "Cannot initialize OAuth to due a missing library. Please run `pip install huggingface_hub[oauth]` or add " "`huggingface_hub[oauth]` to your requirements.txt file." ) from e # Check environment variables msg = ( "OAuth is required but '{}' environment variable is not set. Make sure you've enabled OAuth in your Space by" " setting `hf_oauth: true` in the Space metadata." ) if constants.OAUTH_CLIENT_ID is None: raise ValueError(msg.format("OAUTH_CLIENT_ID")) if constants.OAUTH_CLIENT_SECRET is None: raise ValueError(msg.format("OAUTH_CLIENT_SECRET")) if constants.OAUTH_SCOPES is None: raise ValueError(msg.format("OAUTH_SCOPES")) if constants.OPENID_PROVIDER_URL is None: raise ValueError(msg.format("OPENID_PROVIDER_URL")) # Register OAuth server oauth = OAuth() oauth.register( name="huggingface", client_id=constants.OAUTH_CLIENT_ID, client_secret=constants.OAUTH_CLIENT_SECRET, client_kwargs={"scope": constants.OAUTH_SCOPES}, server_metadata_url=constants.OPENID_PROVIDER_URL + "/.well-known/openid-configuration", ) login_uri, callback_uri, logout_uri = _get_oauth_uris(route_prefix) # Register OAuth endpoints @app.get(login_uri) async def oauth_login(request: fastapi.Request) -> RedirectResponse: """Endpoint that redirects to HF OAuth page.""" redirect_uri = _generate_redirect_uri(request) return await oauth.huggingface.authorize_redirect(request, redirect_uri) # type: ignore @app.get(callback_uri) async def oauth_redirect_callback(request: fastapi.Request) -> RedirectResponse: """Endpoint that handles the OAuth callback.""" try: oauth_info = await oauth.huggingface.authorize_access_token(request) # type: ignore except MismatchingStateError: # Parse query params nb_redirects = int(request.query_params.get("_nb_redirects", 0)) target_url = request.query_params.get("_target_url") # Build redirect URI with the same query params as before and bump nb_redirects count query_params: dict[str, Union[int, str]] = {"_nb_redirects": nb_redirects + 1} if target_url: query_params["_target_url"] = target_url redirect_uri = f"{login_uri}?{urllib.parse.urlencode(query_params)}" # If the user is redirected more than 3 times, it is very likely that the cookie is not working properly. # (e.g. browser is blocking third-party cookies in iframe). In this case, redirect the user in the # non-iframe view. if nb_redirects > constants.OAUTH_MAX_REDIRECTS: host = os.environ.get("SPACE_HOST") if host is None: # cannot happen in a Space raise RuntimeError( "App is not running in a Space (SPACE_HOST environment variable is not set). Cannot redirect to non-iframe view." ) from None host_url = "https://" + host.rstrip("/") return RedirectResponse(host_url + redirect_uri) # Redirect the user to the login page again return RedirectResponse(redirect_uri) # OAuth login worked => store the user info in the session and redirect logger.debug("Successfully logged in with OAuth. Storing user info in session.") request.session["oauth_info"] = oauth_info return RedirectResponse(_get_redirect_target(request)) @app.get(logout_uri) async def oauth_logout(request: fastapi.Request) -> RedirectResponse: """Endpoint that logs out the user (e.g. delete info from cookie session).""" logger.debug("Logged out with OAuth. Removing user info from session.") request.session.pop("oauth_info", None) return RedirectResponse(_get_redirect_target(request)) def _add_mocked_oauth_routes(app: "fastapi.FastAPI", route_prefix: str = "/") -> None: """Add fake oauth routes if app is run locally and OAuth is enabled. Using OAuth will have the same behavior as in a Space but instead of authenticating with HF, a mocked user profile is added to the session. """ try: import fastapi from fastapi.responses import RedirectResponse from starlette.datastructures import URL except ImportError as e: raise ImportError( "Cannot initialize OAuth to due a missing library. Please run `pip install huggingface_hub[oauth]` or add " "`huggingface_hub[oauth]` to your requirements.txt file." ) from e warnings.warn( "OAuth is not supported outside of a Space environment. To help you debug your app locally, the oauth endpoints" " are mocked to return your profile and token. To make it work, your machine must be logged in to Huggingface." ) mocked_oauth_info = _get_mocked_oauth_info() login_uri, callback_uri, logout_uri = _get_oauth_uris(route_prefix) # Define OAuth routes @app.get(login_uri) async def oauth_login(request: fastapi.Request) -> RedirectResponse: """Fake endpoint that redirects to HF OAuth page.""" # Define target (where to redirect after login) redirect_uri = _generate_redirect_uri(request) return RedirectResponse(callback_uri + "?" + urllib.parse.urlencode({"_target_url": redirect_uri})) @app.get(callback_uri) async def oauth_redirect_callback(request: fastapi.Request) -> RedirectResponse: """Endpoint that handles the OAuth callback.""" request.session["oauth_info"] = mocked_oauth_info return RedirectResponse(_get_redirect_target(request)) @app.get(logout_uri) async def oauth_logout(request: fastapi.Request) -> RedirectResponse: """Endpoint that logs out the user (e.g. delete cookie session).""" request.session.pop("oauth_info", None) logout_url = URL("/").include_query_params(**request.query_params) return RedirectResponse(url=logout_url, status_code=302) # see https://github.com/gradio-app/gradio/pull/9659 def _generate_redirect_uri(request: "fastapi.Request") -> str: if "_target_url" in request.query_params: # if `_target_url` already in query params => respect it target = request.query_params["_target_url"] else: # otherwise => keep query params target = "/?" + urllib.parse.urlencode(request.query_params) redirect_uri = request.url_for("oauth_redirect_callback").include_query_params(_target_url=target) redirect_uri_as_str = str(redirect_uri) if redirect_uri.netloc.endswith(".hf.space"): # In Space, FastAPI redirect as http but we want https redirect_uri_as_str = redirect_uri_as_str.replace("http://", "https://") return redirect_uri_as_str def _get_redirect_target(request: "fastapi.Request", default_target: str = "/") -> str: return request.query_params.get("_target_url", default_target) def _get_mocked_oauth_info() -> dict: token = get_token() if token is None: raise ValueError( "Your machine must be logged in to HF to debug an OAuth app locally. Please" " run `hf auth login` or set `HF_TOKEN` as environment variable " "with one of your access token. You can generate a new token in your " "settings page (https://huggingface.co/settings/tokens)." ) user = whoami() if user["type"] != "user": raise ValueError( "Your machine is not logged in with a personal account. Please use a " "personal access token. You can generate a new token in your settings page" " (https://huggingface.co/settings/tokens)." ) return { "access_token": token, "token_type": "bearer", "expires_in": 8 * 60 * 60, # 8 hours "id_token": "FOOBAR", "scope": "openid profile", "refresh_token": "hf_oauth__refresh_token", "expires_at": int(time.time()) + 8 * 60 * 60, # 8 hours "userinfo": { "sub": "0123456789", "name": user["fullname"], "preferred_username": user["name"], "profile": f"https://huggingface.co/{user['name']}", "picture": user["avatarUrl"], "website": "", "aud": "00000000-0000-0000-0000-000000000000", "auth_time": 1691672844, "nonce": "aaaaaaaaaaaaaaaaaaa", "iat": 1691672844, "exp": 1691676444, "iss": "https://huggingface.co", }, } def _get_oauth_uris(route_prefix: str = "/") -> tuple[str, str, str]: route_prefix = route_prefix.strip("/") if route_prefix: route_prefix = f"/{route_prefix}" return ( f"{route_prefix}/oauth/huggingface/login", f"{route_prefix}/oauth/huggingface/callback", f"{route_prefix}/oauth/huggingface/logout", ) huggingface_hub-1.1.5/src/huggingface_hub/_snapshot_download.py000066400000000000000000000502161510763414300247660ustar00rootroot00000000000000import os from pathlib import Path from typing import Iterable, List, Literal, Optional, Union, overload import httpx from tqdm.auto import tqdm as base_tqdm from tqdm.contrib.concurrent import thread_map from . import constants from .errors import ( DryRunError, GatedRepoError, HfHubHTTPError, LocalEntryNotFoundError, RepositoryNotFoundError, RevisionNotFoundError, ) from .file_download import REGEX_COMMIT_HASH, DryRunFileInfo, hf_hub_download, repo_folder_name from .hf_api import DatasetInfo, HfApi, ModelInfo, RepoFile, SpaceInfo from .utils import OfflineModeIsEnabled, filter_repo_objects, is_tqdm_disabled, logging, validate_hf_hub_args from .utils import tqdm as hf_tqdm logger = logging.get_logger(__name__) VERY_LARGE_REPO_THRESHOLD = 50000 # After this limit, we don't consider `repo_info.siblings` to be reliable enough @overload def snapshot_download( repo_id: str, *, repo_type: Optional[str] = None, revision: Optional[str] = None, cache_dir: Union[str, Path, None] = None, local_dir: Union[str, Path, None] = None, library_name: Optional[str] = None, library_version: Optional[str] = None, user_agent: Optional[Union[dict, str]] = None, etag_timeout: float = constants.DEFAULT_ETAG_TIMEOUT, force_download: bool = False, token: Optional[Union[bool, str]] = None, local_files_only: bool = False, allow_patterns: Optional[Union[list[str], str]] = None, ignore_patterns: Optional[Union[list[str], str]] = None, max_workers: int = 8, tqdm_class: Optional[type[base_tqdm]] = None, headers: Optional[dict[str, str]] = None, endpoint: Optional[str] = None, dry_run: Literal[False] = False, ) -> str: ... @overload def snapshot_download( repo_id: str, *, repo_type: Optional[str] = None, revision: Optional[str] = None, cache_dir: Union[str, Path, None] = None, local_dir: Union[str, Path, None] = None, library_name: Optional[str] = None, library_version: Optional[str] = None, user_agent: Optional[Union[dict, str]] = None, etag_timeout: float = constants.DEFAULT_ETAG_TIMEOUT, force_download: bool = False, token: Optional[Union[bool, str]] = None, local_files_only: bool = False, allow_patterns: Optional[Union[list[str], str]] = None, ignore_patterns: Optional[Union[list[str], str]] = None, max_workers: int = 8, tqdm_class: Optional[type[base_tqdm]] = None, headers: Optional[dict[str, str]] = None, endpoint: Optional[str] = None, dry_run: Literal[True] = True, ) -> list[DryRunFileInfo]: ... @overload def snapshot_download( repo_id: str, *, repo_type: Optional[str] = None, revision: Optional[str] = None, cache_dir: Union[str, Path, None] = None, local_dir: Union[str, Path, None] = None, library_name: Optional[str] = None, library_version: Optional[str] = None, user_agent: Optional[Union[dict, str]] = None, etag_timeout: float = constants.DEFAULT_ETAG_TIMEOUT, force_download: bool = False, token: Optional[Union[bool, str]] = None, local_files_only: bool = False, allow_patterns: Optional[Union[list[str], str]] = None, ignore_patterns: Optional[Union[list[str], str]] = None, max_workers: int = 8, tqdm_class: Optional[type[base_tqdm]] = None, headers: Optional[dict[str, str]] = None, endpoint: Optional[str] = None, dry_run: bool = False, ) -> Union[str, list[DryRunFileInfo]]: ... @validate_hf_hub_args def snapshot_download( repo_id: str, *, repo_type: Optional[str] = None, revision: Optional[str] = None, cache_dir: Union[str, Path, None] = None, local_dir: Union[str, Path, None] = None, library_name: Optional[str] = None, library_version: Optional[str] = None, user_agent: Optional[Union[dict, str]] = None, etag_timeout: float = constants.DEFAULT_ETAG_TIMEOUT, force_download: bool = False, token: Optional[Union[bool, str]] = None, local_files_only: bool = False, allow_patterns: Optional[Union[list[str], str]] = None, ignore_patterns: Optional[Union[list[str], str]] = None, max_workers: int = 8, tqdm_class: Optional[type[base_tqdm]] = None, headers: Optional[dict[str, str]] = None, endpoint: Optional[str] = None, dry_run: bool = False, ) -> Union[str, list[DryRunFileInfo]]: """Download repo files. Download a whole snapshot of a repo's files at the specified revision. This is useful when you want all files from a repo, because you don't know which ones you will need a priori. All files are nested inside a folder in order to keep their actual filename relative to that folder. You can also filter which files to download using `allow_patterns` and `ignore_patterns`. If `local_dir` is provided, the file structure from the repo will be replicated in this location. When using this option, the `cache_dir` will not be used and a `.cache/huggingface/` folder will be created at the root of `local_dir` to store some metadata related to the downloaded files. While this mechanism is not as robust as the main cache-system, it's optimized for regularly pulling the latest version of a repository. An alternative would be to clone the repo but this requires git and git-lfs to be installed and properly configured. It is also not possible to filter which files to download when cloning a repository using git. Args: repo_id (`str`): A user or an organization name and a repo name separated by a `/`. repo_type (`str`, *optional*): Set to `"dataset"` or `"space"` if downloading from a dataset or space, `None` or `"model"` if downloading from a model. Default is `None`. revision (`str`, *optional*): An optional Git revision id which can be a branch name, a tag, or a commit hash. cache_dir (`str`, `Path`, *optional*): Path to the folder where cached files are stored. local_dir (`str` or `Path`, *optional*): If provided, the downloaded files will be placed under this directory. library_name (`str`, *optional*): The name of the library to which the object corresponds. library_version (`str`, *optional*): The version of the library. user_agent (`str`, `dict`, *optional*): The user-agent info in the form of a dictionary or a string. etag_timeout (`float`, *optional*, defaults to `10`): When fetching ETag, how many seconds to wait for the server to send data before giving up which is passed to `httpx.request`. force_download (`bool`, *optional*, defaults to `False`): Whether the file should be downloaded even if it already exists in the local cache. token (`str`, `bool`, *optional*): A token to be used for the download. - If `True`, the token is read from the HuggingFace config folder. - If a string, it's used as the authentication token. headers (`dict`, *optional*): Additional headers to include in the request. Those headers take precedence over the others. local_files_only (`bool`, *optional*, defaults to `False`): If `True`, avoid downloading the file and return the path to the local cached file if it exists. allow_patterns (`list[str]` or `str`, *optional*): If provided, only files matching at least one pattern are downloaded. ignore_patterns (`list[str]` or `str`, *optional*): If provided, files matching any of the patterns are not downloaded. max_workers (`int`, *optional*): Number of concurrent threads to download files (1 thread = 1 file download). Defaults to 8. tqdm_class (`tqdm`, *optional*): If provided, overwrites the default behavior for the progress bar. Passed argument must inherit from `tqdm.auto.tqdm` or at least mimic its behavior. Note that the `tqdm_class` is not passed to each individual download. Defaults to the custom HF progress bar that can be disabled by setting `HF_HUB_DISABLE_PROGRESS_BARS` environment variable. dry_run (`bool`, *optional*, defaults to `False`): If `True`, perform a dry run without actually downloading the files. Returns a list of [`DryRunFileInfo`] objects containing information about what would be downloaded. Returns: `str` or list of [`DryRunFileInfo`]: - If `dry_run=False`: Local snapshot path. - If `dry_run=True`: A list of [`DryRunFileInfo`] objects containing download information. Raises: [`~utils.RepositoryNotFoundError`] If the repository to download from cannot be found. This may be because it doesn't exist, or because it is set to `private` and you do not have access. [`~utils.RevisionNotFoundError`] If the revision to download from cannot be found. [`EnvironmentError`](https://docs.python.org/3/library/exceptions.html#EnvironmentError) If `token=True` and the token cannot be found. [`OSError`](https://docs.python.org/3/library/exceptions.html#OSError) if ETag cannot be determined. [`ValueError`](https://docs.python.org/3/library/exceptions.html#ValueError) if some parameter value is invalid. """ if cache_dir is None: cache_dir = constants.HF_HUB_CACHE if revision is None: revision = constants.DEFAULT_REVISION if isinstance(cache_dir, Path): cache_dir = str(cache_dir) if repo_type is None: repo_type = "model" if repo_type not in constants.REPO_TYPES: raise ValueError(f"Invalid repo type: {repo_type}. Accepted repo types are: {str(constants.REPO_TYPES)}") storage_folder = os.path.join(cache_dir, repo_folder_name(repo_id=repo_id, repo_type=repo_type)) api = HfApi( library_name=library_name, library_version=library_version, user_agent=user_agent, endpoint=endpoint, headers=headers, token=token, ) repo_info: Union[ModelInfo, DatasetInfo, SpaceInfo, None] = None api_call_error: Optional[Exception] = None if not local_files_only: # try/except logic to handle different errors => taken from `hf_hub_download` try: # if we have internet connection we want to list files to download repo_info = api.repo_info(repo_id=repo_id, repo_type=repo_type, revision=revision) except httpx.ProxyError: # Actually raise on proxy error raise except (httpx.ConnectError, httpx.TimeoutException, OfflineModeIsEnabled) as error: # Internet connection is down # => will try to use local files only api_call_error = error pass except RevisionNotFoundError: # The repo was found but the revision doesn't exist on the Hub (never existed or got deleted) raise except HfHubHTTPError as error: # Multiple reasons for an http error: # - Repository is private and invalid/missing token sent # - Repository is gated and invalid/missing token sent # - Hub is down (error 500 or 504) # => let's switch to 'local_files_only=True' to check if the files are already cached. # (if it's not the case, the error will be re-raised) api_call_error = error pass # At this stage, if `repo_info` is None it means either: # - internet connection is down # - internet connection is deactivated (local_files_only=True or HF_HUB_OFFLINE=True) # - repo is private/gated and invalid/missing token sent # - Hub is down # => let's look if we can find the appropriate folder in the cache: # - if the specified revision is a commit hash, look inside "snapshots". # - f the specified revision is a branch or tag, look inside "refs". # => if local_dir is not None, we will return the path to the local folder if it exists. if repo_info is None: if dry_run: raise DryRunError( "Dry run cannot be performed as the repository cannot be accessed. Please check your internet connection or authentication token." ) from api_call_error # Try to get which commit hash corresponds to the specified revision commit_hash = None if REGEX_COMMIT_HASH.match(revision): commit_hash = revision else: ref_path = os.path.join(storage_folder, "refs", revision) if os.path.exists(ref_path): # retrieve commit_hash from refs file with open(ref_path) as f: commit_hash = f.read() # Try to locate snapshot folder for this commit hash if commit_hash is not None and local_dir is None: snapshot_folder = os.path.join(storage_folder, "snapshots", commit_hash) if os.path.exists(snapshot_folder): # Snapshot folder exists => let's return it # (but we can't check if all the files are actually there) return snapshot_folder # If local_dir is not None, return it if it exists and is not empty if local_dir is not None: local_dir = Path(local_dir) if local_dir.is_dir() and any(local_dir.iterdir()): logger.warning( f"Returning existing local_dir `{local_dir}` as remote repo cannot be accessed in `snapshot_download` ({api_call_error})." ) return str(local_dir.resolve()) # If we couldn't find the appropriate folder on disk, raise an error. if local_files_only: raise LocalEntryNotFoundError( "Cannot find an appropriate cached snapshot folder for the specified revision on the local disk and " "outgoing traffic has been disabled. To enable repo look-ups and downloads online, pass " "'local_files_only=False' as input." ) elif isinstance(api_call_error, OfflineModeIsEnabled): raise LocalEntryNotFoundError( "Cannot find an appropriate cached snapshot folder for the specified revision on the local disk and " "outgoing traffic has been disabled. To enable repo look-ups and downloads online, set " "'HF_HUB_OFFLINE=0' as environment variable." ) from api_call_error elif isinstance(api_call_error, (RepositoryNotFoundError, GatedRepoError)) or ( isinstance(api_call_error, HfHubHTTPError) and api_call_error.response.status_code == 401 ): # Repo not found, gated, or specific authentication error => let's raise the actual error raise api_call_error else: # Otherwise: most likely a connection issue or Hub downtime => let's warn the user raise LocalEntryNotFoundError( "An error happened while trying to locate the files on the Hub and we cannot find the appropriate" " snapshot folder for the specified revision on the local disk. Please check your internet connection" " and try again." ) from api_call_error # At this stage, internet connection is up and running # => let's download the files! assert repo_info.sha is not None, "Repo info returned from server must have a revision sha." # Corner case: on very large repos, the siblings list in `repo_info` might not contain all files. # In that case, we need to use the `list_repo_tree` method to prevent caching issues. repo_files: Iterable[str] = [f.rfilename for f in repo_info.siblings] if repo_info.siblings is not None else [] unreliable_nb_files = ( repo_info.siblings is None or len(repo_info.siblings) == 0 or len(repo_info.siblings) > VERY_LARGE_REPO_THRESHOLD ) if unreliable_nb_files: logger.info( "Number of files in the repo is unreliable. Using `list_repo_tree` to ensure all files are listed." ) repo_files = ( f.rfilename for f in api.list_repo_tree(repo_id=repo_id, recursive=True, revision=revision, repo_type=repo_type) if isinstance(f, RepoFile) ) filtered_repo_files: Iterable[str] = filter_repo_objects( items=repo_files, allow_patterns=allow_patterns, ignore_patterns=ignore_patterns, ) if not unreliable_nb_files: filtered_repo_files = list(filtered_repo_files) tqdm_desc = f"Fetching {len(filtered_repo_files)} files" else: tqdm_desc = "Fetching ... files" if dry_run: tqdm_desc = "[dry-run] " + tqdm_desc commit_hash = repo_info.sha snapshot_folder = os.path.join(storage_folder, "snapshots", commit_hash) # if passed revision is not identical to commit_hash # then revision has to be a branch name or tag name. # In that case store a ref. if revision != commit_hash: ref_path = os.path.join(storage_folder, "refs", revision) try: os.makedirs(os.path.dirname(ref_path), exist_ok=True) with open(ref_path, "w") as f: f.write(commit_hash) except OSError as e: logger.warning(f"Ignored error while writing commit hash to {ref_path}: {e}.") results: List[Union[str, DryRunFileInfo]] = [] # User can use its own tqdm class or the default one from `huggingface_hub.utils` tqdm_class = tqdm_class or hf_tqdm # Create a progress bar for the bytes downloaded # This progress bar is shared across threads/files and gets updated each time we fetch # metadata for a file. bytes_progress = tqdm_class( desc="Downloading (incomplete total...)", disable=is_tqdm_disabled(log_level=logger.getEffectiveLevel()), total=0, initial=0, unit="B", unit_scale=True, name="huggingface_hub.snapshot_download", ) class _AggregatedTqdm: """Fake tqdm object to aggregate progress into the parent `bytes_progress` bar. In practice the `_AggregatedTqdm` object won't be displayed, it's just used to update the `bytes_progress` bar from each thread/file download. """ def __init__(self, *args, **kwargs): # Adjust the total of the parent progress bar total = kwargs.pop("total", None) if total is not None: bytes_progress.total += total bytes_progress.refresh() # Adjust initial of the parent progress bar initial = kwargs.pop("initial", 0) if initial: bytes_progress.update(initial) def __enter__(self): return self def __exit__(self, exc_type, exc_value, traceback): pass def update(self, n: Optional[Union[int, float]] = 1) -> None: bytes_progress.update(n) # we pass the commit_hash to hf_hub_download # so no network call happens if we already # have the file locally. def _inner_hf_hub_download(repo_file: str) -> None: results.append( hf_hub_download( # type: ignore repo_id, filename=repo_file, repo_type=repo_type, revision=commit_hash, endpoint=endpoint, cache_dir=cache_dir, local_dir=local_dir, library_name=library_name, library_version=library_version, user_agent=user_agent, etag_timeout=etag_timeout, force_download=force_download, token=token, headers=headers, tqdm_class=_AggregatedTqdm, # type: ignore dry_run=dry_run, ) ) thread_map( _inner_hf_hub_download, filtered_repo_files, desc=tqdm_desc, max_workers=max_workers, tqdm_class=tqdm_class, ) bytes_progress.set_description("Download complete") if dry_run: assert all(isinstance(r, DryRunFileInfo) for r in results) return results # type: ignore if local_dir is not None: return str(os.path.realpath(local_dir)) return snapshot_folder huggingface_hub-1.1.5/src/huggingface_hub/_space_api.py000066400000000000000000000125301510763414300231610ustar00rootroot00000000000000# coding=utf-8 # Copyright 2019-present, the HuggingFace Inc. team. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. from dataclasses import dataclass from datetime import datetime from enum import Enum from typing import Optional from huggingface_hub.utils import parse_datetime class SpaceStage(str, Enum): """ Enumeration of possible stage of a Space on the Hub. Value can be compared to a string: ```py assert SpaceStage.BUILDING == "BUILDING" ``` Taken from https://github.com/huggingface/moon-landing/blob/main/server/repo_types/SpaceInfo.ts#L61 (private url). """ # Copied from moon-landing > server > repo_types > SpaceInfo.ts (private repo) NO_APP_FILE = "NO_APP_FILE" CONFIG_ERROR = "CONFIG_ERROR" BUILDING = "BUILDING" BUILD_ERROR = "BUILD_ERROR" RUNNING = "RUNNING" RUNNING_BUILDING = "RUNNING_BUILDING" RUNTIME_ERROR = "RUNTIME_ERROR" DELETING = "DELETING" STOPPED = "STOPPED" PAUSED = "PAUSED" class SpaceHardware(str, Enum): """ Enumeration of hardwares available to run your Space on the Hub. Value can be compared to a string: ```py assert SpaceHardware.CPU_BASIC == "cpu-basic" ``` Taken from https://github.com/huggingface-internal/moon-landing/blob/main/server/repo_types/SpaceHardwareFlavor.ts (private url). """ # CPU CPU_BASIC = "cpu-basic" CPU_UPGRADE = "cpu-upgrade" CPU_XL = "cpu-xl" # ZeroGPU ZERO_A10G = "zero-a10g" # GPU T4_SMALL = "t4-small" T4_MEDIUM = "t4-medium" L4X1 = "l4x1" L4X4 = "l4x4" L40SX1 = "l40sx1" L40SX4 = "l40sx4" L40SX8 = "l40sx8" A10G_SMALL = "a10g-small" A10G_LARGE = "a10g-large" A10G_LARGEX2 = "a10g-largex2" A10G_LARGEX4 = "a10g-largex4" A100_LARGE = "a100-large" H100 = "h100" H100X8 = "h100x8" class SpaceStorage(str, Enum): """ Enumeration of persistent storage available for your Space on the Hub. Value can be compared to a string: ```py assert SpaceStorage.SMALL == "small" ``` Taken from https://github.com/huggingface/moon-landing/blob/main/server/repo_types/SpaceHardwareFlavor.ts#L24 (private url). """ SMALL = "small" MEDIUM = "medium" LARGE = "large" @dataclass class SpaceRuntime: """ Contains information about the current runtime of a Space. Args: stage (`str`): Current stage of the space. Example: RUNNING. hardware (`str` or `None`): Current hardware of the space. Example: "cpu-basic". Can be `None` if Space is `BUILDING` for the first time. requested_hardware (`str` or `None`): Requested hardware. Can be different from `hardware` especially if the request has just been made. Example: "t4-medium". Can be `None` if no hardware has been requested yet. sleep_time (`int` or `None`): Number of seconds the Space will be kept alive after the last request. By default (if value is `None`), the Space will never go to sleep if it's running on an upgraded hardware, while it will go to sleep after 48 hours on a free 'cpu-basic' hardware. For more details, see https://huggingface.co/docs/hub/spaces-gpus#sleep-time. raw (`dict`): Raw response from the server. Contains more information about the Space runtime like number of replicas, number of cpu, memory size,... """ stage: SpaceStage hardware: Optional[SpaceHardware] requested_hardware: Optional[SpaceHardware] sleep_time: Optional[int] storage: Optional[SpaceStorage] raw: dict def __init__(self, data: dict) -> None: self.stage = data["stage"] self.hardware = data.get("hardware", {}).get("current") self.requested_hardware = data.get("hardware", {}).get("requested") self.sleep_time = data.get("gcTimeout") self.storage = data.get("storage") self.raw = data @dataclass class SpaceVariable: """ Contains information about the current variables of a Space. Args: key (`str`): Variable key. Example: `"MODEL_REPO_ID"` value (`str`): Variable value. Example: `"the_model_repo_id"`. description (`str` or None): Description of the variable. Example: `"Model Repo ID of the implemented model"`. updatedAt (`datetime` or None): datetime of the last update of the variable (if the variable has been updated at least once). """ key: str value: str description: Optional[str] updated_at: Optional[datetime] def __init__(self, key: str, values: dict) -> None: self.key = key self.value = values["value"] self.description = values.get("description") updated_at = values.get("updatedAt") self.updated_at = parse_datetime(updated_at) if updated_at is not None else None huggingface_hub-1.1.5/src/huggingface_hub/_tensorboard_logger.py000066400000000000000000000203361510763414300251210ustar00rootroot00000000000000# Copyright 2023 The HuggingFace Team. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Contains a logger to push training logs to the Hub, using Tensorboard.""" from pathlib import Path from typing import Optional, Union from ._commit_scheduler import CommitScheduler from .errors import EntryNotFoundError from .repocard import ModelCard from .utils import experimental # Depending on user's setup, SummaryWriter can come either from 'tensorboardX' # or from 'torch.utils.tensorboard'. Both are compatible so let's try to load # from either of them. try: from tensorboardX import SummaryWriter as _RuntimeSummaryWriter is_summary_writer_available = True except ImportError: try: from torch.utils.tensorboard import SummaryWriter as _RuntimeSummaryWriter is_summary_writer_available = True except ImportError: # Dummy class to avoid failing at import. Will raise on instance creation. class _DummySummaryWriter: pass _RuntimeSummaryWriter = _DummySummaryWriter # type: ignore[assignment] is_summary_writer_available = False class HFSummaryWriter(_RuntimeSummaryWriter): """ Wrapper around the tensorboard's `SummaryWriter` to push training logs to the Hub. Data is logged locally and then pushed to the Hub asynchronously. Pushing data to the Hub is done in a separate thread to avoid blocking the training script. In particular, if the upload fails for any reason (e.g. a connection issue), the main script will not be interrupted. Data is automatically pushed to the Hub every `commit_every` minutes (default to every 5 minutes). > [!WARNING] > `HFSummaryWriter` is experimental. Its API is subject to change in the future without prior notice. Args: repo_id (`str`): The id of the repo to which the logs will be pushed. logdir (`str`, *optional*): The directory where the logs will be written. If not specified, a local directory will be created by the underlying `SummaryWriter` object. commit_every (`int` or `float`, *optional*): The frequency (in minutes) at which the logs will be pushed to the Hub. Defaults to 5 minutes. squash_history (`bool`, *optional*): Whether to squash the history of the repo after each commit. Defaults to `False`. Squashing commits is useful to avoid degraded performances on the repo when it grows too large. repo_type (`str`, *optional*): The type of the repo to which the logs will be pushed. Defaults to "model". repo_revision (`str`, *optional*): The revision of the repo to which the logs will be pushed. Defaults to "main". repo_private (`bool`, *optional*): Whether to make the repo private. If `None` (default), the repo will be public unless the organization's default is private. This value is ignored if the repo already exists. path_in_repo (`str`, *optional*): The path to the folder in the repo where the logs will be pushed. Defaults to "tensorboard/". repo_allow_patterns (`list[str]` or `str`, *optional*): A list of patterns to include in the upload. Defaults to `"*.tfevents.*"`. Check out the [upload guide](https://huggingface.co/docs/huggingface_hub/guides/upload#upload-a-folder) for more details. repo_ignore_patterns (`list[str]` or `str`, *optional*): A list of patterns to exclude in the upload. Check out the [upload guide](https://huggingface.co/docs/huggingface_hub/guides/upload#upload-a-folder) for more details. token (`str`, *optional*): Authentication token. Will default to the stored token. See https://huggingface.co/settings/token for more details kwargs: Additional keyword arguments passed to `SummaryWriter`. Examples: ```diff # Taken from https://pytorch.org/docs/stable/tensorboard.html - from torch.utils.tensorboard import SummaryWriter + from huggingface_hub import HFSummaryWriter import numpy as np - writer = SummaryWriter() + writer = HFSummaryWriter(repo_id="username/my-trained-model") for n_iter in range(100): writer.add_scalar('Loss/train', np.random.random(), n_iter) writer.add_scalar('Loss/test', np.random.random(), n_iter) writer.add_scalar('Accuracy/train', np.random.random(), n_iter) writer.add_scalar('Accuracy/test', np.random.random(), n_iter) ``` ```py >>> from huggingface_hub import HFSummaryWriter # Logs are automatically pushed every 15 minutes (5 by default) + when exiting the context manager >>> with HFSummaryWriter(repo_id="test_hf_logger", commit_every=15) as logger: ... logger.add_scalar("a", 1) ... logger.add_scalar("b", 2) ``` """ @experimental def __new__(cls, *args, **kwargs) -> "HFSummaryWriter": if not is_summary_writer_available: raise ImportError( "You must have `tensorboard` installed to use `HFSummaryWriter`. Please run `pip install --upgrade" " tensorboardX` first." ) return super().__new__(cls) def __init__( self, repo_id: str, *, logdir: Optional[str] = None, commit_every: Union[int, float] = 5, squash_history: bool = False, repo_type: Optional[str] = None, repo_revision: Optional[str] = None, repo_private: Optional[bool] = None, path_in_repo: Optional[str] = "tensorboard", repo_allow_patterns: Optional[Union[list[str], str]] = "*.tfevents.*", repo_ignore_patterns: Optional[Union[list[str], str]] = None, token: Optional[str] = None, **kwargs, ): # Initialize SummaryWriter super().__init__(logdir=logdir, **kwargs) # Check logdir has been correctly initialized and fail early otherwise. In practice, SummaryWriter takes care of it. if not isinstance(self.logdir, str): raise ValueError(f"`self.logdir` must be a string. Got '{self.logdir}' of type {type(self.logdir)}.") # Append logdir name to `path_in_repo` if path_in_repo is None or path_in_repo == "": path_in_repo = Path(self.logdir).name else: path_in_repo = path_in_repo.strip("/") + "/" + Path(self.logdir).name # Initialize scheduler self.scheduler = CommitScheduler( folder_path=self.logdir, path_in_repo=path_in_repo, repo_id=repo_id, repo_type=repo_type, revision=repo_revision, private=repo_private, token=token, allow_patterns=repo_allow_patterns, ignore_patterns=repo_ignore_patterns, every=commit_every, squash_history=squash_history, ) # Exposing some high-level info at root level self.repo_id = self.scheduler.repo_id self.repo_type = self.scheduler.repo_type self.repo_revision = self.scheduler.revision # Add `hf-summary-writer` tag to the model card metadata try: card = ModelCard.load(repo_id_or_path=self.repo_id, repo_type=self.repo_type) except EntryNotFoundError: card = ModelCard("") tags = card.data.get("tags", []) if "hf-summary-writer" not in tags: tags.append("hf-summary-writer") card.data["tags"] = tags card.push_to_hub(repo_id=self.repo_id, repo_type=self.repo_type) def __exit__(self, exc_type, exc_val, exc_tb): """Push to hub in a non-blocking way when exiting the logger's context manager.""" super().__exit__(exc_type, exc_val, exc_tb) future = self.scheduler.trigger() future.result() huggingface_hub-1.1.5/src/huggingface_hub/_upload_large_folder.py000066400000000000000000000715741510763414300252430ustar00rootroot00000000000000# coding=utf-8 # Copyright 2024-present, the HuggingFace Inc. team. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. import enum import logging import os import queue import shutil import sys import threading import time import traceback from datetime import datetime from pathlib import Path from threading import Lock from typing import TYPE_CHECKING, Any, Optional, Union from urllib.parse import quote from ._commit_api import CommitOperationAdd, UploadInfo, _fetch_upload_modes from ._local_folder import LocalUploadFileMetadata, LocalUploadFilePaths, get_local_upload_paths, read_upload_metadata from .constants import DEFAULT_REVISION, REPO_TYPES from .utils import DEFAULT_IGNORE_PATTERNS, _format_size, filter_repo_objects, tqdm from .utils._runtime import is_xet_available from .utils.sha import sha_fileobj if TYPE_CHECKING: from .hf_api import HfApi logger = logging.getLogger(__name__) WAITING_TIME_IF_NO_TASKS = 10 # seconds MAX_NB_FILES_FETCH_UPLOAD_MODE = 100 COMMIT_SIZE_SCALE: list[int] = [20, 50, 75, 100, 125, 200, 250, 400, 600, 1000] UPLOAD_BATCH_SIZE_XET = 256 # Max 256 files per upload batch for XET-enabled repos UPLOAD_BATCH_SIZE_LFS = 1 # Otherwise, batches of 1 for regular LFS upload # Repository limits (from https://huggingface.co/docs/hub/repositories-recommendations) MAX_FILES_PER_REPO = 100_000 # Recommended maximum number of files per repository MAX_FILES_PER_FOLDER = 10_000 # Recommended maximum number of files per folder MAX_FILE_SIZE_GB = 50 # Hard limit for individual file size RECOMMENDED_FILE_SIZE_GB = 20 # Recommended maximum for individual file size def _validate_upload_limits(paths_list: list[LocalUploadFilePaths]) -> None: """ Validate upload against repository limits and warn about potential issues. Args: paths_list: List of file paths to be uploaded Warns about: - Too many files in the repository (>100k) - Too many entries (files or subdirectories) in a single folder (>10k) - Files exceeding size limits (>20GB recommended, >50GB hard limit) """ logger.info("Running validation checks on files to upload...") # Check 1: Total file count if len(paths_list) > MAX_FILES_PER_REPO: logger.warning( f"You are about to upload {len(paths_list):,} files. " f"This exceeds the recommended limit of {MAX_FILES_PER_REPO:,} files per repository.\n" f"Consider:\n" f" - Splitting your data into multiple repositories\n" f" - Using fewer, larger files (e.g., parquet files)\n" f" - See: https://huggingface.co/docs/hub/repositories-recommendations" ) # Check 2: Files and subdirectories per folder # Track immediate children (files and subdirs) for each folder from collections import defaultdict entries_per_folder: dict[str, Any] = defaultdict(lambda: {"files": 0, "subdirs": set()}) for paths in paths_list: path = Path(paths.path_in_repo) parts = path.parts # Count this file in its immediate parent directory parent = str(path.parent) if str(path.parent) != "." else "." entries_per_folder[parent]["files"] += 1 # Track immediate subdirectories for each parent folder # Walk through the path components to track parent-child relationships for i, child in enumerate(parts[:-1]): parent = "." if i == 0 else "/".join(parts[:i]) entries_per_folder[parent]["subdirs"].add(child) # Check limits for each folder for folder, data in entries_per_folder.items(): file_count = data["files"] subdir_count = len(data["subdirs"]) total_entries = file_count + subdir_count if total_entries > MAX_FILES_PER_FOLDER: folder_display = "root" if folder == "." else folder logger.warning( f"Folder '{folder_display}' contains {total_entries:,} entries " f"({file_count:,} files and {subdir_count:,} subdirectories). " f"This exceeds the recommended {MAX_FILES_PER_FOLDER:,} entries per folder.\n" "Consider reorganising into sub-folders." ) # Check 3: File sizes large_files = [] very_large_files = [] for paths in paths_list: size = paths.file_path.stat().st_size size_gb = size / 1_000_000_000 # Use decimal GB as per Hub limits if size_gb > MAX_FILE_SIZE_GB: very_large_files.append((paths.path_in_repo, size_gb)) elif size_gb > RECOMMENDED_FILE_SIZE_GB: large_files.append((paths.path_in_repo, size_gb)) # Warn about very large files (>50GB) if very_large_files: files_str = "\n - ".join(f"{path}: {size:.1f}GB" for path, size in very_large_files[:5]) more_str = f"\n ... and {len(very_large_files) - 5} more files" if len(very_large_files) > 5 else "" logger.warning( f"Found {len(very_large_files)} files exceeding the {MAX_FILE_SIZE_GB}GB hard limit:\n" f" - {files_str}{more_str}\n" f"These files may fail to upload. Consider splitting them into smaller chunks." ) # Warn about large files (>20GB) if large_files: files_str = "\n - ".join(f"{path}: {size:.1f}GB" for path, size in large_files[:5]) more_str = f"\n ... and {len(large_files) - 5} more files" if len(large_files) > 5 else "" logger.warning( f"Found {len(large_files)} files larger than {RECOMMENDED_FILE_SIZE_GB}GB (recommended limit):\n" f" - {files_str}{more_str}\n" f"Large files may slow down loading and processing." ) logger.info("Validation checks complete.") def upload_large_folder_internal( api: "HfApi", repo_id: str, folder_path: Union[str, Path], *, repo_type: str, # Repo type is required! revision: Optional[str] = None, private: Optional[bool] = None, allow_patterns: Optional[Union[list[str], str]] = None, ignore_patterns: Optional[Union[list[str], str]] = None, num_workers: Optional[int] = None, print_report: bool = True, print_report_every: int = 60, ): """Upload a large folder to the Hub in the most resilient way possible. See [`HfApi.upload_large_folder`] for the full documentation. """ # 1. Check args and setup if repo_type is None: raise ValueError( "For large uploads, `repo_type` is explicitly required. Please set it to `model`, `dataset` or `space`." " If you are using the CLI, pass it as `--repo-type=model`." ) if repo_type not in REPO_TYPES: raise ValueError(f"Invalid repo type, must be one of {REPO_TYPES}") if revision is None: revision = DEFAULT_REVISION folder_path = Path(folder_path).expanduser().resolve() if not folder_path.is_dir(): raise ValueError(f"Provided path: '{folder_path}' is not a directory") if ignore_patterns is None: ignore_patterns = [] elif isinstance(ignore_patterns, str): ignore_patterns = [ignore_patterns] ignore_patterns += DEFAULT_IGNORE_PATTERNS if num_workers is None: nb_cores = os.cpu_count() or 1 num_workers = max(nb_cores - 2, 2) # Use all but 2 cores, or at least 2 cores # 2. Create repo if missing repo_url = api.create_repo(repo_id=repo_id, repo_type=repo_type, private=private, exist_ok=True) logger.info(f"Repo created: {repo_url}") repo_id = repo_url.repo_id # 2.1 Check if xet is enabled to set batch file upload size upload_batch_size = UPLOAD_BATCH_SIZE_XET if is_xet_available() else UPLOAD_BATCH_SIZE_LFS # 3. List files to upload filtered_paths_list = filter_repo_objects( (path.relative_to(folder_path).as_posix() for path in folder_path.glob("**/*") if path.is_file()), allow_patterns=allow_patterns, ignore_patterns=ignore_patterns, ) paths_list = [get_local_upload_paths(folder_path, relpath) for relpath in filtered_paths_list] logger.info(f"Found {len(paths_list)} candidate files to upload") # Validate upload against repository limits _validate_upload_limits(paths_list) logger.info("Starting upload...") # Read metadata for each file items = [ (paths, read_upload_metadata(folder_path, paths.path_in_repo)) for paths in tqdm(paths_list, desc="Recovering from metadata files") ] # 4. Start workers status = LargeUploadStatus(items, upload_batch_size) threads = [ threading.Thread( target=_worker_job, kwargs={ "status": status, "api": api, "repo_id": repo_id, "repo_type": repo_type, "revision": revision, }, ) for _ in range(num_workers) ] for thread in threads: thread.start() # 5. Print regular reports if print_report: print("\n\n" + status.current_report()) last_report_ts = time.time() while True: time.sleep(1) if time.time() - last_report_ts >= print_report_every: if print_report: _print_overwrite(status.current_report()) last_report_ts = time.time() if status.is_done(): logging.info("Is done: exiting main loop") break for thread in threads: thread.join() logger.info(status.current_report()) logging.info("Upload is complete!") #################### # Logic to manage workers and synchronize tasks #################### class WorkerJob(enum.Enum): SHA256 = enum.auto() GET_UPLOAD_MODE = enum.auto() PREUPLOAD_LFS = enum.auto() COMMIT = enum.auto() WAIT = enum.auto() # if no tasks are available but we don't want to exit JOB_ITEM_T = tuple[LocalUploadFilePaths, LocalUploadFileMetadata] class LargeUploadStatus: """Contains information, queues and tasks for a large upload process.""" def __init__(self, items: list[JOB_ITEM_T], upload_batch_size: int = 1): self.items = items self.queue_sha256: "queue.Queue[JOB_ITEM_T]" = queue.Queue() self.queue_get_upload_mode: "queue.Queue[JOB_ITEM_T]" = queue.Queue() self.queue_preupload_lfs: "queue.Queue[JOB_ITEM_T]" = queue.Queue() self.queue_commit: "queue.Queue[JOB_ITEM_T]" = queue.Queue() self.lock = Lock() self.nb_workers_sha256: int = 0 self.nb_workers_get_upload_mode: int = 0 self.nb_workers_preupload_lfs: int = 0 self.upload_batch_size: int = upload_batch_size self.nb_workers_commit: int = 0 self.nb_workers_waiting: int = 0 self.last_commit_attempt: Optional[float] = None self._started_at = datetime.now() self._chunk_idx: int = 1 self._chunk_lock: Lock = Lock() # Setup queues for item in self.items: paths, metadata = item if metadata.sha256 is None: self.queue_sha256.put(item) elif metadata.upload_mode is None: self.queue_get_upload_mode.put(item) elif metadata.upload_mode == "lfs" and not metadata.is_uploaded: self.queue_preupload_lfs.put(item) elif not metadata.is_committed: self.queue_commit.put(item) else: logger.debug(f"Skipping file {paths.path_in_repo} (already uploaded and committed)") def target_chunk(self) -> int: with self._chunk_lock: return COMMIT_SIZE_SCALE[self._chunk_idx] def update_chunk(self, success: bool, nb_items: int, duration: float) -> None: with self._chunk_lock: if not success: logger.warning(f"Failed to commit {nb_items} files at once. Will retry with less files in next batch.") self._chunk_idx -= 1 elif nb_items >= COMMIT_SIZE_SCALE[self._chunk_idx] and duration < 40: logger.info(f"Successfully committed {nb_items} at once. Increasing the limit for next batch.") self._chunk_idx += 1 self._chunk_idx = max(0, min(self._chunk_idx, len(COMMIT_SIZE_SCALE) - 1)) def current_report(self) -> str: """Generate a report of the current status of the large upload.""" nb_hashed = 0 size_hashed = 0 nb_preuploaded = 0 nb_lfs = 0 nb_lfs_unsure = 0 size_preuploaded = 0 nb_committed = 0 size_committed = 0 total_size = 0 ignored_files = 0 total_files = 0 with self.lock: for _, metadata in self.items: if metadata.should_ignore: ignored_files += 1 continue total_size += metadata.size total_files += 1 if metadata.sha256 is not None: nb_hashed += 1 size_hashed += metadata.size if metadata.upload_mode == "lfs": nb_lfs += 1 if metadata.upload_mode is None: nb_lfs_unsure += 1 if metadata.is_uploaded: nb_preuploaded += 1 size_preuploaded += metadata.size if metadata.is_committed: nb_committed += 1 size_committed += metadata.size total_size_str = _format_size(total_size) now = datetime.now() now_str = now.strftime("%Y-%m-%d %H:%M:%S") elapsed = now - self._started_at elapsed_str = str(elapsed).split(".")[0] # remove milliseconds message = "\n" + "-" * 10 message += f" {now_str} ({elapsed_str}) " message += "-" * 10 + "\n" message += "Files: " message += f"hashed {nb_hashed}/{total_files} ({_format_size(size_hashed)}/{total_size_str}) | " message += f"pre-uploaded: {nb_preuploaded}/{nb_lfs} ({_format_size(size_preuploaded)}/{total_size_str})" if nb_lfs_unsure > 0: message += f" (+{nb_lfs_unsure} unsure)" message += f" | committed: {nb_committed}/{total_files} ({_format_size(size_committed)}/{total_size_str})" message += f" | ignored: {ignored_files}\n" message += "Workers: " message += f"hashing: {self.nb_workers_sha256} | " message += f"get upload mode: {self.nb_workers_get_upload_mode} | " message += f"pre-uploading: {self.nb_workers_preupload_lfs} | " message += f"committing: {self.nb_workers_commit} | " message += f"waiting: {self.nb_workers_waiting}\n" message += "-" * 51 return message def is_done(self) -> bool: with self.lock: return all(metadata.is_committed or metadata.should_ignore for _, metadata in self.items) def _worker_job( status: LargeUploadStatus, api: "HfApi", repo_id: str, repo_type: str, revision: str, ): """ Main process for a worker. The worker will perform tasks based on the priority list until all files are uploaded and committed. If no tasks are available, the worker will wait for 10 seconds before checking again. If a task fails for any reason, the item(s) are put back in the queue for another worker to pick up. Read `upload_large_folder` docstring for more information on how tasks are prioritized. """ while True: next_job: Optional[tuple[WorkerJob, list[JOB_ITEM_T]]] = None # Determine next task next_job = _determine_next_job(status) if next_job is None: return job, items = next_job # Perform task if job == WorkerJob.SHA256: item = items[0] # single item try: _compute_sha256(item) status.queue_get_upload_mode.put(item) except KeyboardInterrupt: raise except Exception as e: logger.error(f"Failed to compute sha256: {e}") traceback.format_exc() status.queue_sha256.put(item) with status.lock: status.nb_workers_sha256 -= 1 elif job == WorkerJob.GET_UPLOAD_MODE: try: _get_upload_mode(items, api=api, repo_id=repo_id, repo_type=repo_type, revision=revision) except KeyboardInterrupt: raise except Exception as e: logger.error(f"Failed to get upload mode: {e}") traceback.format_exc() # Items are either: # - dropped (if should_ignore) # - put in LFS queue (if LFS) # - put in commit queue (if regular) # - or put back (if error occurred). for item in items: _, metadata = item if metadata.should_ignore: continue if metadata.upload_mode == "lfs": status.queue_preupload_lfs.put(item) elif metadata.upload_mode == "regular": status.queue_commit.put(item) else: status.queue_get_upload_mode.put(item) with status.lock: status.nb_workers_get_upload_mode -= 1 elif job == WorkerJob.PREUPLOAD_LFS: try: _preupload_lfs(items, api=api, repo_id=repo_id, repo_type=repo_type, revision=revision) for item in items: status.queue_commit.put(item) except KeyboardInterrupt: raise except Exception as e: logger.error(f"Failed to preupload LFS: {e}") traceback.format_exc() for item in items: status.queue_preupload_lfs.put(item) with status.lock: status.nb_workers_preupload_lfs -= 1 elif job == WorkerJob.COMMIT: start_ts = time.time() success = True try: _commit(items, api=api, repo_id=repo_id, repo_type=repo_type, revision=revision) except KeyboardInterrupt: raise except Exception as e: logger.error(f"Failed to commit: {e}") traceback.format_exc() for item in items: status.queue_commit.put(item) success = False duration = time.time() - start_ts status.update_chunk(success, len(items), duration) with status.lock: status.last_commit_attempt = time.time() status.nb_workers_commit -= 1 elif job == WorkerJob.WAIT: time.sleep(WAITING_TIME_IF_NO_TASKS) with status.lock: status.nb_workers_waiting -= 1 def _determine_next_job(status: LargeUploadStatus) -> Optional[tuple[WorkerJob, list[JOB_ITEM_T]]]: with status.lock: # 1. Commit if more than 5 minutes since last commit attempt (and at least 1 file) if ( status.nb_workers_commit == 0 and status.queue_commit.qsize() > 0 and status.last_commit_attempt is not None and time.time() - status.last_commit_attempt > 5 * 60 ): status.nb_workers_commit += 1 logger.debug("Job: commit (more than 5 minutes since last commit attempt)") return (WorkerJob.COMMIT, _get_n(status.queue_commit, status.target_chunk())) # 2. Commit if at least 100 files are ready to commit elif status.nb_workers_commit == 0 and status.queue_commit.qsize() >= 150: status.nb_workers_commit += 1 logger.debug("Job: commit (>100 files ready)") return (WorkerJob.COMMIT, _get_n(status.queue_commit, status.target_chunk())) # 3. Get upload mode if at least 100 files elif status.queue_get_upload_mode.qsize() >= MAX_NB_FILES_FETCH_UPLOAD_MODE: status.nb_workers_get_upload_mode += 1 logger.debug(f"Job: get upload mode (>{MAX_NB_FILES_FETCH_UPLOAD_MODE} files ready)") return (WorkerJob.GET_UPLOAD_MODE, _get_n(status.queue_get_upload_mode, MAX_NB_FILES_FETCH_UPLOAD_MODE)) # 4. Preupload LFS file if at least `status.upload_batch_size` files and no worker is preuploading LFS elif status.queue_preupload_lfs.qsize() >= status.upload_batch_size and status.nb_workers_preupload_lfs == 0: status.nb_workers_preupload_lfs += 1 logger.debug("Job: preupload LFS (no other worker preuploading LFS)") return (WorkerJob.PREUPLOAD_LFS, _get_n(status.queue_preupload_lfs, status.upload_batch_size)) # 5. Compute sha256 if at least 1 file and no worker is computing sha256 elif status.queue_sha256.qsize() > 0 and status.nb_workers_sha256 == 0: status.nb_workers_sha256 += 1 logger.debug("Job: sha256 (no other worker computing sha256)") return (WorkerJob.SHA256, _get_one(status.queue_sha256)) # 6. Get upload mode if at least 1 file and no worker is getting upload mode elif status.queue_get_upload_mode.qsize() > 0 and status.nb_workers_get_upload_mode == 0: status.nb_workers_get_upload_mode += 1 logger.debug("Job: get upload mode (no other worker getting upload mode)") return (WorkerJob.GET_UPLOAD_MODE, _get_n(status.queue_get_upload_mode, MAX_NB_FILES_FETCH_UPLOAD_MODE)) # 7. Preupload LFS file if at least `status.upload_batch_size` files elif status.queue_preupload_lfs.qsize() >= status.upload_batch_size: status.nb_workers_preupload_lfs += 1 logger.debug("Job: preupload LFS") return (WorkerJob.PREUPLOAD_LFS, _get_n(status.queue_preupload_lfs, status.upload_batch_size)) # 8. Compute sha256 if at least 1 file elif status.queue_sha256.qsize() > 0: status.nb_workers_sha256 += 1 logger.debug("Job: sha256") return (WorkerJob.SHA256, _get_one(status.queue_sha256)) # 9. Get upload mode if at least 1 file elif status.queue_get_upload_mode.qsize() > 0: status.nb_workers_get_upload_mode += 1 logger.debug("Job: get upload mode") return (WorkerJob.GET_UPLOAD_MODE, _get_n(status.queue_get_upload_mode, MAX_NB_FILES_FETCH_UPLOAD_MODE)) # 10. Preupload LFS file if at least 1 file elif status.queue_preupload_lfs.qsize() > 0: status.nb_workers_preupload_lfs += 1 logger.debug("Job: preupload LFS") return (WorkerJob.PREUPLOAD_LFS, _get_n(status.queue_preupload_lfs, status.upload_batch_size)) # 11. Commit if at least 1 file and 1 min since last commit attempt elif ( status.nb_workers_commit == 0 and status.queue_commit.qsize() > 0 and status.last_commit_attempt is not None and time.time() - status.last_commit_attempt > 1 * 60 ): status.nb_workers_commit += 1 logger.debug("Job: commit (1 min since last commit attempt)") return (WorkerJob.COMMIT, _get_n(status.queue_commit, status.target_chunk())) # 12. Commit if at least 1 file all other queues are empty and all workers are waiting # e.g. when it's the last commit elif ( status.nb_workers_commit == 0 and status.queue_commit.qsize() > 0 and status.queue_sha256.qsize() == 0 and status.queue_get_upload_mode.qsize() == 0 and status.queue_preupload_lfs.qsize() == 0 and status.nb_workers_sha256 == 0 and status.nb_workers_get_upload_mode == 0 and status.nb_workers_preupload_lfs == 0 ): status.nb_workers_commit += 1 logger.debug("Job: commit") return (WorkerJob.COMMIT, _get_n(status.queue_commit, status.target_chunk())) # 13. If all queues are empty, exit elif all(metadata.is_committed or metadata.should_ignore for _, metadata in status.items): logger.info("All files have been processed! Exiting worker.") return None # 14. If no task is available, wait else: status.nb_workers_waiting += 1 logger.debug(f"No task available, waiting... ({WAITING_TIME_IF_NO_TASKS}s)") return (WorkerJob.WAIT, []) #################### # Atomic jobs (sha256, get_upload_mode, preupload_lfs, commit) #################### def _compute_sha256(item: JOB_ITEM_T) -> None: """Compute sha256 of a file and save it in metadata.""" paths, metadata = item if metadata.sha256 is None: with paths.file_path.open("rb") as f: metadata.sha256 = sha_fileobj(f).hex() metadata.save(paths) def _get_upload_mode(items: list[JOB_ITEM_T], api: "HfApi", repo_id: str, repo_type: str, revision: str) -> None: """Get upload mode for each file and update metadata. Also receive info if the file should be ignored. """ additions = [_build_hacky_operation(item) for item in items] _fetch_upload_modes( additions=additions, repo_type=repo_type, repo_id=repo_id, headers=api._build_hf_headers(), revision=quote(revision, safe=""), endpoint=api.endpoint, ) for item, addition in zip(items, additions): paths, metadata = item metadata.upload_mode = addition._upload_mode metadata.should_ignore = addition._should_ignore metadata.remote_oid = addition._remote_oid metadata.save(paths) def _preupload_lfs(items: list[JOB_ITEM_T], api: "HfApi", repo_id: str, repo_type: str, revision: str) -> None: """Preupload LFS files and update metadata.""" additions = [_build_hacky_operation(item) for item in items] api.preupload_lfs_files( repo_id=repo_id, repo_type=repo_type, revision=revision, additions=additions, ) for paths, metadata in items: metadata.is_uploaded = True metadata.save(paths) def _commit(items: list[JOB_ITEM_T], api: "HfApi", repo_id: str, repo_type: str, revision: str) -> None: """Commit files to the repo.""" additions = [_build_hacky_operation(item) for item in items] api.create_commit( repo_id=repo_id, repo_type=repo_type, revision=revision, operations=additions, commit_message="Add files using upload-large-folder tool", ) for paths, metadata in items: metadata.is_committed = True metadata.save(paths) #################### # Hacks with CommitOperationAdd to bypass checks/sha256 calculation #################### class HackyCommitOperationAdd(CommitOperationAdd): def __post_init__(self) -> None: if isinstance(self.path_or_fileobj, Path): self.path_or_fileobj = str(self.path_or_fileobj) def _build_hacky_operation(item: JOB_ITEM_T) -> HackyCommitOperationAdd: paths, metadata = item operation = HackyCommitOperationAdd(path_in_repo=paths.path_in_repo, path_or_fileobj=paths.file_path) with paths.file_path.open("rb") as file: sample = file.peek(512)[:512] if metadata.sha256 is None: raise ValueError("sha256 must have been computed by now!") operation.upload_info = UploadInfo(sha256=bytes.fromhex(metadata.sha256), size=metadata.size, sample=sample) operation._upload_mode = metadata.upload_mode # type: ignore[assignment] operation._should_ignore = metadata.should_ignore operation._remote_oid = metadata.remote_oid return operation #################### # Misc helpers #################### def _get_one(queue: "queue.Queue[JOB_ITEM_T]") -> list[JOB_ITEM_T]: return [queue.get()] def _get_n(queue: "queue.Queue[JOB_ITEM_T]", n: int) -> list[JOB_ITEM_T]: return [queue.get() for _ in range(min(queue.qsize(), n))] def _print_overwrite(report: str) -> None: """Print a report, overwriting the previous lines. Since tqdm in using `sys.stderr` to (re-)write progress bars, we need to use `sys.stdout` to print the report. Note: works well only if no other process is writing to `sys.stdout`! """ report += "\n" # Get terminal width terminal_width = shutil.get_terminal_size().columns # Count number of lines that should be cleared nb_lines = sum(len(line) // terminal_width + 1 for line in report.splitlines()) # Clear previous lines based on the number of lines in the report for _ in range(nb_lines): sys.stdout.write("\r\033[K") # Clear line sys.stdout.write("\033[F") # Move cursor up one line # Print the new report, filling remaining space with whitespace sys.stdout.write(report) sys.stdout.write(" " * (terminal_width - len(report.splitlines()[-1]))) sys.stdout.flush() huggingface_hub-1.1.5/src/huggingface_hub/_webhooks_payload.py000066400000000000000000000070331510763414300245710ustar00rootroot00000000000000# coding=utf-8 # Copyright 2023-present, the HuggingFace Inc. team. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Contains data structures to parse the webhooks payload.""" from typing import Literal, Optional from .utils import is_pydantic_available if is_pydantic_available(): from pydantic import BaseModel else: # Define a dummy BaseModel to avoid import errors when pydantic is not installed # Import error will be raised when trying to use the class class BaseModel: # type: ignore [no-redef] def __init__(self, *args, **kwargs) -> None: raise ImportError( "You must have `pydantic` installed to use `WebhookPayload`. This is an optional dependency that" " should be installed separately. Please run `pip install --upgrade pydantic` and retry." ) # This is an adaptation of the ReportV3 interface implemented in moon-landing. V0, V1 and V2 have been ignored as they # are not in used anymore. To keep in sync when format is updated in # https://github.com/huggingface/moon-landing/blob/main/server/lib/HFWebhooks.ts (internal link). WebhookEvent_T = Literal[ "create", "delete", "move", "update", ] RepoChangeEvent_T = Literal[ "add", "move", "remove", "update", ] RepoType_T = Literal[ "dataset", "model", "space", ] DiscussionStatus_T = Literal[ "closed", "draft", "open", "merged", ] SupportedWebhookVersion = Literal[3] class ObjectId(BaseModel): id: str class WebhookPayloadUrl(BaseModel): web: str api: Optional[str] = None class WebhookPayloadMovedTo(BaseModel): name: str owner: ObjectId class WebhookPayloadWebhook(ObjectId): version: SupportedWebhookVersion class WebhookPayloadEvent(BaseModel): action: WebhookEvent_T scope: str class WebhookPayloadDiscussionChanges(BaseModel): base: str mergeCommitId: Optional[str] = None class WebhookPayloadComment(ObjectId): author: ObjectId hidden: bool content: Optional[str] = None url: WebhookPayloadUrl class WebhookPayloadDiscussion(ObjectId): num: int author: ObjectId url: WebhookPayloadUrl title: str isPullRequest: bool status: DiscussionStatus_T changes: Optional[WebhookPayloadDiscussionChanges] = None pinned: Optional[bool] = None class WebhookPayloadRepo(ObjectId): owner: ObjectId head_sha: Optional[str] = None name: str private: bool subdomain: Optional[str] = None tags: Optional[list[str]] = None type: Literal["dataset", "model", "space"] url: WebhookPayloadUrl class WebhookPayloadUpdatedRef(BaseModel): ref: str oldSha: Optional[str] = None newSha: Optional[str] = None class WebhookPayload(BaseModel): event: WebhookPayloadEvent repo: WebhookPayloadRepo discussion: Optional[WebhookPayloadDiscussion] = None comment: Optional[WebhookPayloadComment] = None webhook: WebhookPayloadWebhook movedTo: Optional[WebhookPayloadMovedTo] = None updatedRefs: Optional[list[WebhookPayloadUpdatedRef]] = None huggingface_hub-1.1.5/src/huggingface_hub/_webhooks_server.py000066400000000000000000000364641510763414300244600ustar00rootroot00000000000000# coding=utf-8 # Copyright 2023-present, the HuggingFace Inc. team. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Contains `WebhooksServer` and `webhook_endpoint` to create a webhook server easily.""" import atexit import inspect import os from functools import wraps from typing import TYPE_CHECKING, Any, Callable, Optional from .utils import experimental, is_fastapi_available, is_gradio_available if TYPE_CHECKING: import gradio as gr from fastapi import Request if is_fastapi_available(): from fastapi import FastAPI, Request from fastapi.responses import JSONResponse else: # Will fail at runtime if FastAPI is not available FastAPI = Request = JSONResponse = None # type: ignore _global_app: Optional["WebhooksServer"] = None _is_local = os.environ.get("SPACE_ID") is None @experimental class WebhooksServer: """ The [`WebhooksServer`] class lets you create an instance of a Gradio app that can receive Huggingface webhooks. These webhooks can be registered using the [`~WebhooksServer.add_webhook`] decorator. Webhook endpoints are added to the app as a POST endpoint to the FastAPI router. Once all the webhooks are registered, the `launch` method has to be called to start the app. It is recommended to accept [`WebhookPayload`] as the first argument of the webhook function. It is a Pydantic model that contains all the information about the webhook event. The data will be parsed automatically for you. Check out the [webhooks guide](../guides/webhooks_server) for a step-by-step tutorial on how to set up your WebhooksServer and deploy it on a Space. > [!WARNING] > `WebhooksServer` is experimental. Its API is subject to change in the future. > [!WARNING] > You must have `gradio` installed to use `WebhooksServer` (`pip install --upgrade gradio`). Args: ui (`gradio.Blocks`, optional): A Gradio UI instance to be used as the Space landing page. If `None`, a UI displaying instructions about the configured webhooks is created. webhook_secret (`str`, optional): A secret key to verify incoming webhook requests. You can set this value to any secret you want as long as you also configure it in your [webhooks settings panel](https://huggingface.co/settings/webhooks). You can also set this value as the `WEBHOOK_SECRET` environment variable. If no secret is provided, the webhook endpoints are opened without any security. Example: ```python import gradio as gr from huggingface_hub import WebhooksServer, WebhookPayload with gr.Blocks() as ui: ... app = WebhooksServer(ui=ui, webhook_secret="my_secret_key") @app.add_webhook("/say_hello") async def hello(payload: WebhookPayload): return {"message": "hello"} app.launch() ``` """ def __new__(cls, *args, **kwargs) -> "WebhooksServer": if not is_gradio_available(): raise ImportError( "You must have `gradio` installed to use `WebhooksServer`. Please run `pip install --upgrade gradio`" " first." ) if not is_fastapi_available(): raise ImportError( "You must have `fastapi` installed to use `WebhooksServer`. Please run `pip install --upgrade fastapi`" " first." ) return super().__new__(cls) def __init__( self, ui: Optional["gr.Blocks"] = None, webhook_secret: Optional[str] = None, ) -> None: self._ui = ui self.webhook_secret = webhook_secret or os.getenv("WEBHOOK_SECRET") self.registered_webhooks: dict[str, Callable] = {} _warn_on_empty_secret(self.webhook_secret) def add_webhook(self, path: Optional[str] = None) -> Callable: """ Decorator to add a webhook to the [`WebhooksServer`] server. Args: path (`str`, optional): The URL path to register the webhook function. If not provided, the function name will be used as the path. In any case, all webhooks are registered under `/webhooks`. Raises: ValueError: If the provided path is already registered as a webhook. Example: ```python from huggingface_hub import WebhooksServer, WebhookPayload app = WebhooksServer() @app.add_webhook async def trigger_training(payload: WebhookPayload): if payload.repo.type == "dataset" and payload.event.action == "update": # Trigger a training job if a dataset is updated ... app.launch() ``` """ # Usage: directly as decorator. Example: `@app.add_webhook` if callable(path): # If path is a function, it means it was used as a decorator without arguments return self.add_webhook()(path) # Usage: provide a path. Example: `@app.add_webhook(...)` @wraps(FastAPI.post) def _inner_post(*args, **kwargs): func = args[0] abs_path = f"/webhooks/{(path or func.__name__).strip('/')}" if abs_path in self.registered_webhooks: raise ValueError(f"Webhook {abs_path} already exists.") self.registered_webhooks[abs_path] = func return _inner_post def launch(self, prevent_thread_lock: bool = False, **launch_kwargs: Any) -> None: """Launch the Gradio app and register webhooks to the underlying FastAPI server. Input parameters are forwarded to Gradio when launching the app. """ ui = self._ui or self._get_default_ui() # Start Gradio App # - as non-blocking so that webhooks can be added afterwards # - as shared if launch locally (to debug webhooks) launch_kwargs.setdefault("share", _is_local) self.fastapi_app, _, _ = ui.launch(prevent_thread_lock=True, **launch_kwargs) # Register webhooks to FastAPI app for path, func in self.registered_webhooks.items(): # Add secret check if required if self.webhook_secret is not None: func = _wrap_webhook_to_check_secret(func, webhook_secret=self.webhook_secret) # Add route to FastAPI app self.fastapi_app.post(path)(func) # Print instructions and block main thread space_host = os.environ.get("SPACE_HOST") url = "https://" + space_host if space_host is not None else (ui.share_url or ui.local_url) if url is None: raise ValueError("Cannot find the URL of the app. Please provide a valid `ui` or update `gradio` version.") url = url.strip("/") message = "\nWebhooks are correctly setup and ready to use:" message += "\n" + "\n".join(f" - POST {url}{webhook}" for webhook in self.registered_webhooks) message += "\nGo to https://huggingface.co/settings/webhooks to setup your webhooks." print(message) if not prevent_thread_lock: ui.block_thread() def _get_default_ui(self) -> "gr.Blocks": """Default UI if not provided (lists webhooks and provides basic instructions).""" import gradio as gr with gr.Blocks() as ui: gr.Markdown("# This is an app to process 🤗 Webhooks") gr.Markdown( "Webhooks are a foundation for MLOps-related features. They allow you to listen for new changes on" " specific repos or to all repos belonging to particular set of users/organizations (not just your" " repos, but any repo). Check out this [guide](https://huggingface.co/docs/hub/webhooks) to get to" " know more about webhooks on the Huggingface Hub." ) gr.Markdown( f"{len(self.registered_webhooks)} webhook(s) are registered:" + "\n\n" + "\n ".join( f"- [{webhook_path}]({_get_webhook_doc_url(webhook.__name__, webhook_path)})" for webhook_path, webhook in self.registered_webhooks.items() ) ) gr.Markdown( "Go to https://huggingface.co/settings/webhooks to setup your webhooks." + "\nYou app is running locally. Please look at the logs to check the full URL you need to set." if _is_local else ( "\nThis app is running on a Space. You can find the corresponding URL in the options menu" " (top-right) > 'Embed the Space'. The URL looks like 'https://{username}-{repo_name}.hf.space'." ) ) return ui @experimental def webhook_endpoint(path: Optional[str] = None) -> Callable: """Decorator to start a [`WebhooksServer`] and register the decorated function as a webhook endpoint. This is a helper to get started quickly. If you need more flexibility (custom landing page or webhook secret), you can use [`WebhooksServer`] directly. You can register multiple webhook endpoints (to the same server) by using this decorator multiple times. Check out the [webhooks guide](../guides/webhooks_server) for a step-by-step tutorial on how to set up your server and deploy it on a Space. > [!WARNING] > `webhook_endpoint` is experimental. Its API is subject to change in the future. > [!WARNING] > You must have `gradio` installed to use `webhook_endpoint` (`pip install --upgrade gradio`). Args: path (`str`, optional): The URL path to register the webhook function. If not provided, the function name will be used as the path. In any case, all webhooks are registered under `/webhooks`. Examples: The default usage is to register a function as a webhook endpoint. The function name will be used as the path. The server will be started automatically at exit (i.e. at the end of the script). ```python from huggingface_hub import webhook_endpoint, WebhookPayload @webhook_endpoint async def trigger_training(payload: WebhookPayload): if payload.repo.type == "dataset" and payload.event.action == "update": # Trigger a training job if a dataset is updated ... # Server is automatically started at the end of the script. ``` Advanced usage: register a function as a webhook endpoint and start the server manually. This is useful if you are running it in a notebook. ```python from huggingface_hub import webhook_endpoint, WebhookPayload @webhook_endpoint async def trigger_training(payload: WebhookPayload): if payload.repo.type == "dataset" and payload.event.action == "update": # Trigger a training job if a dataset is updated ... # Start the server manually trigger_training.launch() ``` """ if callable(path): # If path is a function, it means it was used as a decorator without arguments return webhook_endpoint()(path) @wraps(WebhooksServer.add_webhook) def _inner(func: Callable) -> Callable: app = _get_global_app() app.add_webhook(path)(func) if len(app.registered_webhooks) == 1: # Register `app.launch` to run at exit (only once) atexit.register(app.launch) @wraps(app.launch) def _launch_now(): # Run the app directly (without waiting atexit) atexit.unregister(app.launch) app.launch() func.launch = _launch_now # type: ignore return func return _inner def _get_global_app() -> WebhooksServer: global _global_app if _global_app is None: _global_app = WebhooksServer() return _global_app def _warn_on_empty_secret(webhook_secret: Optional[str]) -> None: if webhook_secret is None: print("Webhook secret is not defined. This means your webhook endpoints will be open to everyone.") print( "To add a secret, set `WEBHOOK_SECRET` as environment variable or pass it at initialization: " "\n\t`app = WebhooksServer(webhook_secret='my_secret', ...)`" ) print( "For more details about webhook secrets, please refer to" " https://huggingface.co/docs/hub/webhooks#webhook-secret." ) else: print("Webhook secret is correctly defined.") def _get_webhook_doc_url(webhook_name: str, webhook_path: str) -> str: """Returns the anchor to a given webhook in the docs (experimental)""" return "/docs#/default/" + webhook_name + webhook_path.replace("/", "_") + "_post" def _wrap_webhook_to_check_secret(func: Callable, webhook_secret: str) -> Callable: """Wraps a webhook function to check the webhook secret before calling the function. This is a hacky way to add the `request` parameter to the function signature. Since FastAPI based itself on route parameters to inject the values to the function, we need to hack the function signature to retrieve the `Request` object (and hence the headers). A far cleaner solution would be to use a middleware. However, since `fastapi==0.90.1`, a middleware cannot be added once the app has started. And since the FastAPI app is started by Gradio internals (and not by us), we cannot add a middleware. This method is called only when a secret has been defined by the user. If a request is sent without the "x-webhook-secret", the function will return a 401 error (unauthorized). If the header is sent but is incorrect, the function will return a 403 error (forbidden). Inspired by https://stackoverflow.com/a/33112180. """ initial_sig = inspect.signature(func) @wraps(func) async def _protected_func(request: Request, **kwargs): request_secret = request.headers.get("x-webhook-secret") if request_secret is None: return JSONResponse({"error": "x-webhook-secret header not set."}, status_code=401) if request_secret != webhook_secret: return JSONResponse({"error": "Invalid webhook secret."}, status_code=403) # Inject `request` in kwargs if required if "request" in initial_sig.parameters: kwargs["request"] = request # Handle both sync and async routes if inspect.iscoroutinefunction(func): return await func(**kwargs) else: return func(**kwargs) # Update signature to include request if "request" not in initial_sig.parameters: _protected_func.__signature__ = initial_sig.replace( # type: ignore parameters=( inspect.Parameter(name="request", kind=inspect.Parameter.POSITIONAL_OR_KEYWORD, annotation=Request), ) + tuple(initial_sig.parameters.values()) ) # Return protected route return _protected_func huggingface_hub-1.1.5/src/huggingface_hub/cli/000077500000000000000000000000001510763414300212725ustar00rootroot00000000000000huggingface_hub-1.1.5/src/huggingface_hub/cli/__init__.py000066400000000000000000000011361510763414300234040ustar00rootroot00000000000000# Copyright 2025 The HuggingFace Team. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. huggingface_hub-1.1.5/src/huggingface_hub/cli/_cli_utils.py000066400000000000000000000124331510763414300237750ustar00rootroot00000000000000# Copyright 2022 The HuggingFace Team. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Contains CLI utilities (styling, helpers).""" import importlib.metadata import os import time from enum import Enum from pathlib import Path from typing import TYPE_CHECKING, Annotated, Optional import click import typer from huggingface_hub import __version__, constants from huggingface_hub.utils import ANSI, get_session, hf_raise_for_status, installation_method, logging logger = logging.get_logger() if TYPE_CHECKING: from huggingface_hub.hf_api import HfApi def get_hf_api(token: Optional[str] = None) -> "HfApi": # Import here to avoid circular import from huggingface_hub.hf_api import HfApi return HfApi(token=token, library_name="huggingface-cli", library_version=__version__) #### TYPER UTILS class AlphabeticalMixedGroup(typer.core.TyperGroup): """ Typer Group that lists commands and sub-apps mixed and alphabetically. """ def list_commands(self, ctx: click.Context) -> list[str]: # type: ignore[name-defined] # click.Group stores both commands and subgroups in `self.commands` return sorted(self.commands.keys()) def typer_factory(help: str) -> typer.Typer: return typer.Typer( help=help, add_completion=True, no_args_is_help=True, cls=AlphabeticalMixedGroup, # Disable rich completely for consistent experience rich_markup_mode=None, rich_help_panel=None, pretty_exceptions_enable=False, ) class RepoType(str, Enum): model = "model" dataset = "dataset" space = "space" RepoIdArg = Annotated[ str, typer.Argument( help="The ID of the repo (e.g. `username/repo-name`).", ), ] RepoTypeOpt = Annotated[ RepoType, typer.Option( help="The type of repository (model, dataset, or space).", ), ] TokenOpt = Annotated[ Optional[str], typer.Option( help="A User Access Token generated from https://huggingface.co/settings/tokens.", ), ] PrivateOpt = Annotated[ bool, typer.Option( help="Whether to create a private repo if repo doesn't exist on the Hub. Ignored if the repo already exists.", ), ] RevisionOpt = Annotated[ Optional[str], typer.Option( help="Git revision id which can be a branch name, a tag, or a commit hash.", ), ] ### PyPI VERSION CHECKER def check_cli_update() -> None: """ Check whether a newer version of `huggingface_hub` is available on PyPI. If a newer version is found, notify the user and suggest updating. If current version is a pre-release (e.g. `1.0.0.rc1`), or a dev version (e.g. `1.0.0.dev1`), no check is performed. This function is called at the entry point of the CLI. It only performs the check once every 24 hours, and any error during the check is caught and logged, to avoid breaking the CLI. """ try: _check_cli_update() except Exception: # We don't want the CLI to fail on version checks, no matter the reason. logger.debug("Error while checking for CLI update.", exc_info=True) def _check_cli_update() -> None: current_version = importlib.metadata.version("huggingface_hub") # Skip if current version is a pre-release or dev version if any(tag in current_version for tag in ["rc", "dev"]): return # Skip if already checked in the last 24 hours if os.path.exists(constants.CHECK_FOR_UPDATE_DONE_PATH): mtime = os.path.getmtime(constants.CHECK_FOR_UPDATE_DONE_PATH) if (time.time() - mtime) < 24 * 3600: return # Touch the file to mark that we did the check now Path(constants.CHECK_FOR_UPDATE_DONE_PATH).touch() # Check latest version from PyPI response = get_session().get("https://pypi.org/pypi/huggingface_hub/json", timeout=2) hf_raise_for_status(response) data = response.json() latest_version = data["info"]["version"] # If latest version is different from current, notify user if current_version != latest_version: method = installation_method() if method == "brew": update_command = "brew upgrade huggingface-cli" elif method == "hf_installer" and os.name == "nt": update_command = 'powershell -NoProfile -Command "iwr -useb https://hf.co/cli/install.ps1 | iex"' elif method == "hf_installer": update_command = "curl -LsSf https://hf.co/cli/install.sh | bash -" else: # unknown => likely pip update_command = "pip install -U huggingface_hub" click.echo( ANSI.yellow( f"A new version of huggingface_hub ({latest_version}) is available! " f"You are using version {current_version}.\n" f"To update, run: {ANSI.bold(update_command)}\n", ) ) huggingface_hub-1.1.5/src/huggingface_hub/cli/auth.py000066400000000000000000000106431510763414300226110ustar00rootroot00000000000000# Copyright 2020 The HuggingFace Team. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Contains commands to authenticate to the Hugging Face Hub and interact with your repositories. Usage: # login and save token locally. hf auth login --token=hf_*** --add-to-git-credential # switch between tokens hf auth switch # list all tokens hf auth list # logout from all tokens hf auth logout # check which account you are logged in as hf auth whoami """ from typing import Annotated, Optional import typer from huggingface_hub.constants import ENDPOINT from huggingface_hub.errors import HfHubHTTPError from huggingface_hub.hf_api import whoami from .._login import auth_list, auth_switch, login, logout from ..utils import ANSI, get_stored_tokens, get_token, logging from ._cli_utils import TokenOpt, typer_factory logger = logging.get_logger(__name__) auth_cli = typer_factory(help="Manage authentication (login, logout, etc.).") @auth_cli.command("login", help="Login using a token from huggingface.co/settings/tokens") def auth_login( token: TokenOpt = None, add_to_git_credential: Annotated[ bool, typer.Option( help="Save to git credential helper. Useful only if you plan to run git commands directly.", ), ] = False, ) -> None: login(token=token, add_to_git_credential=add_to_git_credential) @auth_cli.command("logout", help="Logout from a specific token") def auth_logout( token_name: Annotated[ Optional[str], typer.Option( help="Name of token to logout", ), ] = None, ) -> None: logout(token_name=token_name) def _select_token_name() -> Optional[str]: token_names = list(get_stored_tokens().keys()) if not token_names: logger.error("No stored tokens found. Please login first.") return None print("Available stored tokens:") for i, token_name in enumerate(token_names, 1): print(f"{i}. {token_name}") while True: try: choice = input("Enter the number of the token to switch to (or 'q' to quit): ") if choice.lower() == "q": return None index = int(choice) - 1 if 0 <= index < len(token_names): return token_names[index] else: print("Invalid selection. Please try again.") except ValueError: print("Invalid input. Please enter a number or 'q' to quit.") @auth_cli.command("switch", help="Switch between access tokens") def auth_switch_cmd( token_name: Annotated[ Optional[str], typer.Option( help="Name of the token to switch to", ), ] = None, add_to_git_credential: Annotated[ bool, typer.Option( help="Save to git credential helper. Useful only if you plan to run git commands directly.", ), ] = False, ) -> None: if token_name is None: token_name = _select_token_name() if token_name is None: print("No token name provided. Aborting.") raise typer.Exit() auth_switch(token_name, add_to_git_credential=add_to_git_credential) @auth_cli.command("list", help="List all stored access tokens") def auth_list_cmd() -> None: auth_list() @auth_cli.command("whoami", help="Find out which huggingface.co account you are logged in as.") def auth_whoami() -> None: token = get_token() if token is None: print("Not logged in") raise typer.Exit() try: info = whoami(token) print(ANSI.bold("user: "), info["name"]) orgs = [org["name"] for org in info["orgs"]] if orgs: print(ANSI.bold("orgs: "), ",".join(orgs)) if ENDPOINT != "https://huggingface.co": print(f"Authenticated through private endpoint: {ENDPOINT}") except HfHubHTTPError as e: print(e) print(ANSI.red(e.response.text)) raise typer.Exit(code=1) huggingface_hub-1.1.5/src/huggingface_hub/cli/cache.py000066400000000000000000000707601510763414300227210ustar00rootroot00000000000000# coding=utf-8 # Copyright 2025-present, the HuggingFace Inc. team. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Contains the 'hf cache' command group with cache management subcommands.""" import csv import json import re import sys import time from collections import defaultdict from dataclasses import dataclass from enum import Enum from typing import Annotated, Any, Callable, Dict, List, Mapping, Optional, Tuple import typer from ..utils import ( ANSI, CachedRepoInfo, CachedRevisionInfo, CacheNotFound, HFCacheInfo, _format_size, scan_cache_dir, tabulate, ) from ..utils._parsing import parse_duration, parse_size from ._cli_utils import RepoIdArg, RepoTypeOpt, RevisionOpt, TokenOpt, get_hf_api, typer_factory cache_cli = typer_factory(help="Manage local cache directory.") #### Cache helper utilities class OutputFormat(str, Enum): table = "table" json = "json" csv = "csv" @dataclass(frozen=True) class _DeletionResolution: revisions: frozenset[str] selected: dict[CachedRepoInfo, frozenset[CachedRevisionInfo]] missing: tuple[str, ...] _FILTER_PATTERN = re.compile(r"^(?P[a-zA-Z_]+)\s*(?P==|!=|>=|<=|>|<|=)\s*(?P.+)$") _ALLOWED_OPERATORS = {"=", "!=", ">", "<", ">=", "<="} _FILTER_KEYS = {"accessed", "modified", "refs", "size", "type"} _SORT_KEYS = {"accessed", "modified", "name", "size"} _SORT_PATTERN = re.compile(r"^(?P[a-zA-Z_]+)(?::(?Pasc|desc))?$") _SORT_DEFAULT_ORDER = { # Default ordering: accessed/modified/size are descending (newest/biggest first), name is ascending "accessed": "desc", "modified": "desc", "size": "desc", "name": "asc", } # Dynamically generate SortOptions enum from _SORT_KEYS _sort_options_dict = {} for key in sorted(_SORT_KEYS): _sort_options_dict[key] = key _sort_options_dict[f"{key}_asc"] = f"{key}:asc" _sort_options_dict[f"{key}_desc"] = f"{key}:desc" SortOptions = Enum("SortOptions", _sort_options_dict, type=str, module=__name__) # type: ignore @dataclass(frozen=True) class CacheDeletionCounts: """Simple counters summarizing cache deletions for CLI messaging.""" repo_count: int partial_revision_count: int total_revision_count: int CacheEntry = Tuple[CachedRepoInfo, Optional[CachedRevisionInfo]] RepoRefsMap = Dict[CachedRepoInfo, frozenset[str]] def summarize_deletions( selected_by_repo: Mapping[CachedRepoInfo, frozenset[CachedRevisionInfo]], ) -> CacheDeletionCounts: """Summarize deletions across repositories.""" repo_count = 0 total_revisions = 0 revisions_in_full_repos = 0 for repo, revisions in selected_by_repo.items(): total_revisions += len(revisions) if len(revisions) == len(repo.revisions): repo_count += 1 revisions_in_full_repos += len(revisions) partial_revision_count = total_revisions - revisions_in_full_repos return CacheDeletionCounts(repo_count, partial_revision_count, total_revisions) def print_cache_selected_revisions(selected_by_repo: Mapping[CachedRepoInfo, frozenset[CachedRevisionInfo]]) -> None: """Pretty-print selected cache revisions during confirmation prompts.""" for repo in sorted(selected_by_repo.keys(), key=lambda repo: (repo.repo_type, repo.repo_id.lower())): repo_key = f"{repo.repo_type}/{repo.repo_id}" revisions = sorted(selected_by_repo[repo], key=lambda rev: rev.commit_hash) if len(revisions) == len(repo.revisions): print(f" - {repo_key} (entire repo)") continue print(f" - {repo_key}:") for revision in revisions: refs = " ".join(sorted(revision.refs)) or "(detached)" print(f" {revision.commit_hash} [{refs}] {revision.size_on_disk_str}") def build_cache_index( hf_cache_info: HFCacheInfo, ) -> Tuple[ Dict[str, CachedRepoInfo], Dict[str, Tuple[CachedRepoInfo, CachedRevisionInfo]], ]: """Create lookup tables so CLI commands can resolve repo ids and revisions quickly.""" repo_lookup: dict[str, CachedRepoInfo] = {} revision_lookup: dict[str, tuple[CachedRepoInfo, CachedRevisionInfo]] = {} for repo in hf_cache_info.repos: repo_key = repo.cache_id.lower() repo_lookup[repo_key] = repo for revision in repo.revisions: revision_lookup[revision.commit_hash.lower()] = (repo, revision) return repo_lookup, revision_lookup def collect_cache_entries( hf_cache_info: HFCacheInfo, *, include_revisions: bool ) -> Tuple[List[CacheEntry], RepoRefsMap]: """Flatten cache metadata into rows consumed by `hf cache ls`.""" entries: List[CacheEntry] = [] repo_refs_map: RepoRefsMap = {} sorted_repos = sorted(hf_cache_info.repos, key=lambda repo: (repo.repo_type, repo.repo_id.lower())) for repo in sorted_repos: repo_refs_map[repo] = frozenset({ref for revision in repo.revisions for ref in revision.refs}) if include_revisions: for revision in sorted(repo.revisions, key=lambda rev: rev.commit_hash): entries.append((repo, revision)) else: entries.append((repo, None)) if include_revisions: entries.sort( key=lambda entry: ( entry[0].cache_id, entry[1].commit_hash if entry[1] is not None else "", ) ) else: entries.sort(key=lambda entry: entry[0].cache_id) return entries, repo_refs_map def compile_cache_filter( expr: str, repo_refs_map: RepoRefsMap ) -> Callable[[CachedRepoInfo, Optional[CachedRevisionInfo], float], bool]: """Convert a `hf cache ls` filter expression into the yes/no test we apply to each cache entry before displaying it.""" match = _FILTER_PATTERN.match(expr.strip()) if not match: raise ValueError(f"Invalid filter expression: '{expr}'.") key = match.group("key").lower() op = match.group("op") value_raw = match.group("value").strip() if op not in _ALLOWED_OPERATORS: raise ValueError(f"Unsupported operator '{op}' in filter '{expr}'. Must be one of {list(_ALLOWED_OPERATORS)}.") if key not in _FILTER_KEYS: raise ValueError(f"Unsupported filter key '{key}' in '{expr}'. Must be one of {list(_FILTER_KEYS)}.") # at this point we know that key is in `_FILTER_KEYS` if key == "size": size_threshold = parse_size(value_raw) return lambda repo, revision, _: _compare_numeric( revision.size_on_disk if revision is not None else repo.size_on_disk, op, size_threshold, ) if key in {"modified", "accessed"}: seconds = parse_duration(value_raw.strip()) def _time_filter(repo: CachedRepoInfo, revision: Optional[CachedRevisionInfo], now: float) -> bool: timestamp = ( repo.last_accessed if key == "accessed" else revision.last_modified if revision is not None else repo.last_modified ) if timestamp is None: return False return _compare_numeric(now - timestamp, op, seconds) return _time_filter if key == "type": expected = value_raw.lower() if op != "=": raise ValueError(f"Only '=' is supported for 'type' filters. Got '{op}'.") def _type_filter(repo: CachedRepoInfo, revision: Optional[CachedRevisionInfo], _: float) -> bool: return repo.repo_type.lower() == expected return _type_filter else: # key == "refs" if op != "=": raise ValueError(f"Only '=' is supported for 'refs' filters. Got {op}.") def _refs_filter(repo: CachedRepoInfo, revision: Optional[CachedRevisionInfo], _: float) -> bool: refs = revision.refs if revision is not None else repo_refs_map.get(repo, frozenset()) return value_raw.lower() in [ref.lower() for ref in refs] return _refs_filter def _build_cache_export_payload( entries: List[CacheEntry], *, include_revisions: bool, repo_refs_map: RepoRefsMap ) -> List[Dict[str, Any]]: """Normalize cache entries into serializable records for JSON/CSV exports.""" payload: List[Dict[str, Any]] = [] for repo, revision in entries: if include_revisions: if revision is None: continue record: Dict[str, Any] = { "repo_id": repo.repo_id, "repo_type": repo.repo_type, "revision": revision.commit_hash, "snapshot_path": str(revision.snapshot_path), "size_on_disk": revision.size_on_disk, "last_accessed": repo.last_accessed, "last_modified": revision.last_modified, "refs": sorted(revision.refs), } else: record = { "repo_id": repo.repo_id, "repo_type": repo.repo_type, "size_on_disk": repo.size_on_disk, "last_accessed": repo.last_accessed, "last_modified": repo.last_modified, "refs": sorted(repo_refs_map.get(repo, frozenset())), } payload.append(record) return payload def print_cache_entries_table( entries: List[CacheEntry], *, include_revisions: bool, repo_refs_map: RepoRefsMap ) -> None: """Render cache entries as a table and show a human-readable summary.""" if not entries: message = "No cached revisions found." if include_revisions else "No cached repositories found." print(message) return table_rows: List[List[str]] if include_revisions: headers = ["ID", "REVISION", "SIZE", "LAST_MODIFIED", "REFS"] table_rows = [ [ repo.cache_id, revision.commit_hash, revision.size_on_disk_str.rjust(8), revision.last_modified_str, " ".join(sorted(revision.refs)), ] for repo, revision in entries if revision is not None ] else: headers = ["ID", "SIZE", "LAST_ACCESSED", "LAST_MODIFIED", "REFS"] table_rows = [ [ repo.cache_id, repo.size_on_disk_str.rjust(8), repo.last_accessed_str or "", repo.last_modified_str, " ".join(sorted(repo_refs_map.get(repo, frozenset()))), ] for repo, _ in entries ] print(tabulate(table_rows, headers=headers)) # type: ignore[arg-type] unique_repos = {repo for repo, _ in entries} repo_count = len(unique_repos) if include_revisions: revision_count = sum(1 for _, revision in entries if revision is not None) total_size = sum(revision.size_on_disk for _, revision in entries if revision is not None) else: revision_count = sum(len(repo.revisions) for repo in unique_repos) total_size = sum(repo.size_on_disk for repo in unique_repos) summary = f"\nFound {repo_count} repo(s) for a total of {revision_count} revision(s) and {_format_size(total_size)} on disk." print(ANSI.bold(summary)) def print_cache_entries_json( entries: List[CacheEntry], *, include_revisions: bool, repo_refs_map: RepoRefsMap ) -> None: """Dump cache entries as JSON for scripting or automation.""" payload = _build_cache_export_payload(entries, include_revisions=include_revisions, repo_refs_map=repo_refs_map) json.dump(payload, sys.stdout, indent=2) sys.stdout.write("\n") def print_cache_entries_csv(entries: List[CacheEntry], *, include_revisions: bool, repo_refs_map: RepoRefsMap) -> None: """Export cache entries as CSV rows with the shared payload format.""" records = _build_cache_export_payload(entries, include_revisions=include_revisions, repo_refs_map=repo_refs_map) writer = csv.writer(sys.stdout) if include_revisions: headers = [ "repo_id", "repo_type", "revision", "snapshot_path", "size_on_disk", "last_accessed", "last_modified", "refs", ] else: headers = ["repo_id", "repo_type", "size_on_disk", "last_accessed", "last_modified", "refs"] writer.writerow(headers) if not records: return for record in records: refs = record["refs"] if include_revisions: row = [ record.get("repo_id", ""), record.get("repo_type", ""), record.get("revision", ""), record.get("snapshot_path", ""), record.get("size_on_disk"), record.get("last_accessed"), record.get("last_modified"), " ".join(refs) if refs else "", ] else: row = [ record.get("repo_id", ""), record.get("repo_type", ""), record.get("size_on_disk"), record.get("last_accessed"), record.get("last_modified"), " ".join(refs) if refs else "", ] writer.writerow(row) def _compare_numeric(left: Optional[float], op: str, right: float) -> bool: """Evaluate numeric comparisons for filters.""" if left is None: return False comparisons = { "=": left == right, "!=": left != right, ">": left > right, "<": left < right, ">=": left >= right, "<=": left <= right, } if op not in comparisons: raise ValueError(f"Unsupported numeric comparison operator: {op}") return comparisons[op] def compile_cache_sort(sort_expr: str) -> tuple[Callable[[CacheEntry], tuple[Any, ...]], bool]: """Convert a `hf cache ls` sort expression into a key function for sorting entries. Returns: A tuple of (key_function, reverse_flag) where reverse_flag indicates whether to sort in descending order (True) or ascending order (False). """ match = _SORT_PATTERN.match(sort_expr.strip().lower()) if not match: raise ValueError(f"Invalid sort expression: '{sort_expr}'. Expected format: 'key' or 'key:asc' or 'key:desc'.") key = match.group("key").lower() explicit_order = match.group("order") if key not in _SORT_KEYS: raise ValueError(f"Unsupported sort key '{key}' in '{sort_expr}'. Must be one of {list(_SORT_KEYS)}.") # Use explicit order if provided, otherwise use default for the key order = explicit_order if explicit_order else _SORT_DEFAULT_ORDER[key] reverse = order == "desc" def _sort_key(entry: CacheEntry) -> tuple[Any, ...]: repo, revision = entry if key == "name": # Sort by cache_id (repo type/id) value: Any = repo.cache_id.lower() return (value,) if key == "size": # Use revision size if available, otherwise repo size value = revision.size_on_disk if revision is not None else repo.size_on_disk return (value,) if key == "accessed": # For revisions, accessed is not available per-revision, use repo's last_accessed # For repos, use repo's last_accessed value = repo.last_accessed if repo.last_accessed is not None else 0.0 return (value,) if key == "modified": # Use revision's last_modified if available, otherwise repo's last_modified if revision is not None: value = revision.last_modified if revision.last_modified is not None else 0.0 else: value = repo.last_modified if repo.last_modified is not None else 0.0 return (value,) # Should never reach here due to validation above raise ValueError(f"Unsupported sort key: {key}") return _sort_key, reverse def _resolve_deletion_targets(hf_cache_info: HFCacheInfo, targets: list[str]) -> _DeletionResolution: """Resolve the deletion targets into a deletion resolution.""" repo_lookup, revision_lookup = build_cache_index(hf_cache_info) selected: dict[CachedRepoInfo, set[CachedRevisionInfo]] = defaultdict(set) revisions: set[str] = set() missing: list[str] = [] for raw_target in targets: target = raw_target.strip() if not target: continue lowered = target.lower() if re.fullmatch(r"[0-9a-fA-F]{40}", lowered): match = revision_lookup.get(lowered) if match is None: missing.append(raw_target) continue repo, revision = match selected[repo].add(revision) revisions.add(revision.commit_hash) continue matched_repo = repo_lookup.get(lowered) if matched_repo is None: missing.append(raw_target) continue for revision in matched_repo.revisions: selected[matched_repo].add(revision) revisions.add(revision.commit_hash) frozen_selected = {repo: frozenset(revs) for repo, revs in selected.items()} return _DeletionResolution( revisions=frozenset(revisions), selected=frozen_selected, missing=tuple(missing), ) #### Cache CLI commands @cache_cli.command() def ls( cache_dir: Annotated[ Optional[str], typer.Option( help="Cache directory to scan (defaults to Hugging Face cache).", ), ] = None, revisions: Annotated[ bool, typer.Option( help="Include revisions in the output instead of aggregated repositories.", ), ] = False, filter: Annotated[ Optional[list[str]], typer.Option( "-f", "--filter", help="Filter entries (e.g. 'size>1GB', 'type=model', 'accessed>7d'). Can be used multiple times.", ), ] = None, format: Annotated[ OutputFormat, typer.Option( help="Output format.", ), ] = OutputFormat.table, quiet: Annotated[ bool, typer.Option( "-q", "--quiet", help="Print only IDs (repo IDs or revision hashes).", ), ] = False, sort: Annotated[ Optional[SortOptions], typer.Option( help="Sort entries by key. Supported keys: 'accessed', 'modified', 'name', 'size'. " "Append ':asc' or ':desc' to explicitly set the order (e.g., 'modified:asc'). " "Defaults: 'accessed', 'modified', 'size' default to 'desc' (newest/biggest first); " "'name' defaults to 'asc' (alphabetical).", ), ] = None, limit: Annotated[ Optional[int], typer.Option( help="Limit the number of results returned. Returns only the top N entries after sorting.", ), ] = None, ) -> None: """List cached repositories or revisions.""" try: hf_cache_info = scan_cache_dir(cache_dir) except CacheNotFound as exc: print(f"Cache directory not found: {str(exc.cache_dir)}") raise typer.Exit(code=1) from exc filters = filter or [] entries, repo_refs_map = collect_cache_entries(hf_cache_info, include_revisions=revisions) try: filter_fns = [compile_cache_filter(expr, repo_refs_map) for expr in filters] except ValueError as exc: raise typer.BadParameter(str(exc)) from exc now = time.time() for fn in filter_fns: entries = [entry for entry in entries if fn(entry[0], entry[1], now)] # Apply sorting if requested if sort: try: sort_key_fn, reverse = compile_cache_sort(sort.value) entries.sort(key=sort_key_fn, reverse=reverse) except ValueError as exc: raise typer.BadParameter(str(exc)) from exc # Apply limit if requested if limit is not None: if limit < 0: raise typer.BadParameter(f"Limit must be a positive integer, got {limit}.") entries = entries[:limit] if quiet: for repo, revision in entries: print(revision.commit_hash if revision is not None else repo.cache_id) return formatters = { OutputFormat.table: print_cache_entries_table, OutputFormat.json: print_cache_entries_json, OutputFormat.csv: print_cache_entries_csv, } return formatters[format](entries, include_revisions=revisions, repo_refs_map=repo_refs_map) @cache_cli.command() def rm( targets: Annotated[ list[str], typer.Argument( help="One or more repo IDs (e.g. model/bert-base-uncased) or revision hashes to delete.", ), ], cache_dir: Annotated[ Optional[str], typer.Option( help="Cache directory to scan (defaults to Hugging Face cache).", ), ] = None, yes: Annotated[ bool, typer.Option( "-y", "--yes", help="Skip confirmation prompt.", ), ] = False, dry_run: Annotated[ bool, typer.Option( help="Preview deletions without removing anything.", ), ] = False, ) -> None: """Remove cached repositories or revisions.""" try: hf_cache_info = scan_cache_dir(cache_dir) except CacheNotFound as exc: print(f"Cache directory not found: {str(exc.cache_dir)}") raise typer.Exit(code=1) resolution = _resolve_deletion_targets(hf_cache_info, targets) if resolution.missing: print("Could not find the following targets in the cache:") for entry in resolution.missing: print(f" - {entry}") if len(resolution.revisions) == 0: print("Nothing to delete.") raise typer.Exit(code=0) strategy = hf_cache_info.delete_revisions(*sorted(resolution.revisions)) counts = summarize_deletions(resolution.selected) summary_parts: list[str] = [] if counts.repo_count: summary_parts.append(f"{counts.repo_count} repo(s)") if counts.partial_revision_count: summary_parts.append(f"{counts.partial_revision_count} revision(s)") if not summary_parts: summary_parts.append(f"{counts.total_revision_count} revision(s)") summary_text = " and ".join(summary_parts) print(f"About to delete {summary_text} totalling {strategy.expected_freed_size_str}.") print_cache_selected_revisions(resolution.selected) if dry_run: print("Dry run: no files were deleted.") return if not yes and not typer.confirm("Proceed with deletion?", default=False): print("Deletion cancelled.") return strategy.execute() counts = summarize_deletions(resolution.selected) print( f"Deleted {counts.repo_count} repo(s) and {counts.total_revision_count} revision(s); freed {strategy.expected_freed_size_str}." ) @cache_cli.command() def prune( cache_dir: Annotated[ Optional[str], typer.Option( help="Cache directory to scan (defaults to Hugging Face cache).", ), ] = None, yes: Annotated[ bool, typer.Option( "-y", "--yes", help="Skip confirmation prompt.", ), ] = False, dry_run: Annotated[ bool, typer.Option( help="Preview deletions without removing anything.", ), ] = False, ) -> None: """Remove detached revisions from the cache.""" try: hf_cache_info = scan_cache_dir(cache_dir) except CacheNotFound as exc: print(f"Cache directory not found: {str(exc.cache_dir)}") raise typer.Exit(code=1) selected: dict[CachedRepoInfo, frozenset[CachedRevisionInfo]] = {} revisions: set[str] = set() for repo in hf_cache_info.repos: detached = frozenset(revision for revision in repo.revisions if len(revision.refs) == 0) if not detached: continue selected[repo] = detached revisions.update(revision.commit_hash for revision in detached) if len(revisions) == 0: print("No unreferenced revisions found. Nothing to prune.") return resolution = _DeletionResolution( revisions=frozenset(revisions), selected=selected, missing=(), ) strategy = hf_cache_info.delete_revisions(*sorted(resolution.revisions)) counts = summarize_deletions(selected) print( f"About to delete {counts.total_revision_count} unreferenced revision(s) ({strategy.expected_freed_size_str} total)." ) print_cache_selected_revisions(selected) if dry_run: print("Dry run: no files were deleted.") return if not yes and not typer.confirm("Proceed?"): print("Pruning cancelled.") return strategy.execute() print(f"Deleted {counts.total_revision_count} unreferenced revision(s); freed {strategy.expected_freed_size_str}.") @cache_cli.command() def verify( repo_id: RepoIdArg, repo_type: RepoTypeOpt = RepoTypeOpt.model, revision: RevisionOpt = None, cache_dir: Annotated[ Optional[str], typer.Option( help="Cache directory to use when verifying files from cache (defaults to Hugging Face cache).", ), ] = None, local_dir: Annotated[ Optional[str], typer.Option( help="If set, verify files under this directory instead of the cache.", ), ] = None, fail_on_missing_files: Annotated[ bool, typer.Option( "--fail-on-missing-files", help="Fail if some files exist on the remote but are missing locally.", ), ] = False, fail_on_extra_files: Annotated[ bool, typer.Option( "--fail-on-extra-files", help="Fail if some files exist locally but are not present on the remote revision.", ), ] = False, token: TokenOpt = None, ) -> None: """Verify checksums for a single repo revision from cache or a local directory. Examples: - Verify main revision in cache: `hf cache verify gpt2` - Verify specific revision: `hf cache verify gpt2 --revision refs/pr/1` - Verify dataset: `hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type dataset` - Verify local dir: `hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repo` """ if local_dir is not None and cache_dir is not None: print("Cannot pass both --local-dir and --cache-dir. Use one or the other.") raise typer.Exit(code=2) api = get_hf_api(token=token) result = api.verify_repo_checksums( repo_id=repo_id, repo_type=repo_type.value if hasattr(repo_type, "value") else str(repo_type), revision=revision, local_dir=local_dir, cache_dir=cache_dir, token=token, ) exit_code = 0 has_mismatches = bool(result.mismatches) if has_mismatches: print("❌ Checksum verification failed for the following file(s):") for m in result.mismatches: print(f" - {m['path']}: expected {m['expected']} ({m['algorithm']}), got {m['actual']}") exit_code = 1 if result.missing_paths: if fail_on_missing_files: print("Missing files (present remotely, absent locally):") for p in result.missing_paths: print(f" - {p}") exit_code = 1 else: warning = ( f"{len(result.missing_paths)} remote file(s) are missing locally. " "Use --fail-on-missing-files for details." ) print(f"⚠️ {warning}") if result.extra_paths: if fail_on_extra_files: print("Extra files (present locally, absent remotely):") for p in result.extra_paths: print(f" - {p}") exit_code = 1 else: warning = ( f"{len(result.extra_paths)} local file(s) do not exist on the remote repo. " "Use --fail-on-extra-files for details." ) print(f"⚠️ {warning}") verified_location = result.verified_path if exit_code != 0: print(f"❌ Verification failed for '{repo_id}' ({repo_type.value}) in {verified_location}.") print(f" Revision: {result.revision}") raise typer.Exit(code=exit_code) print(f"✅ Verified {result.checked_count} file(s) for '{repo_id}' ({repo_type.value}) in {verified_location}") print(" All checksums match.") huggingface_hub-1.1.5/src/huggingface_hub/cli/download.py000066400000000000000000000146041510763414300234600ustar00rootroot00000000000000# coding=utf-8 # Copyright 202-present, the HuggingFace Inc. team. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Contains command to download files from the Hub with the CLI. Usage: hf download --help # Download file hf download gpt2 config.json # Download entire repo hf download fffiloni/zeroscope --repo-type=space --revision=refs/pr/78 # Download repo with filters hf download gpt2 --include="*.safetensors" # Download with token hf download Wauplin/private-model --token=hf_*** # Download quietly (no progress bar, no warnings, only the returned path) hf download gpt2 config.json --quiet # Download to local dir hf download gpt2 --local-dir=./models/gpt2 """ import warnings from typing import Annotated, Optional, Union import typer from huggingface_hub import logging from huggingface_hub._snapshot_download import snapshot_download from huggingface_hub.file_download import DryRunFileInfo, hf_hub_download from huggingface_hub.utils import _format_size, disable_progress_bars, enable_progress_bars, tabulate from ._cli_utils import RepoIdArg, RepoTypeOpt, RevisionOpt, TokenOpt logger = logging.get_logger(__name__) def download( repo_id: RepoIdArg, filenames: Annotated[ Optional[list[str]], typer.Argument( help="Files to download (e.g. `config.json`, `data/metadata.jsonl`).", ), ] = None, repo_type: RepoTypeOpt = RepoTypeOpt.model, revision: RevisionOpt = None, include: Annotated[ Optional[list[str]], typer.Option( help="Glob patterns to include from files to download. eg: *.json", ), ] = None, exclude: Annotated[ Optional[list[str]], typer.Option( help="Glob patterns to exclude from files to download.", ), ] = None, cache_dir: Annotated[ Optional[str], typer.Option( help="Directory where to save files.", ), ] = None, local_dir: Annotated[ Optional[str], typer.Option( help="If set, the downloaded file will be placed under this directory. Check out https://huggingface.co/docs/huggingface_hub/guides/download#download-files-to-local-folder for more details.", ), ] = None, force_download: Annotated[ bool, typer.Option( help="If True, the files will be downloaded even if they are already cached.", ), ] = False, dry_run: Annotated[ bool, typer.Option( help="If True, perform a dry run without actually downloading the file.", ), ] = False, token: TokenOpt = None, quiet: Annotated[ bool, typer.Option( help="If True, progress bars are disabled and only the path to the download files is printed.", ), ] = False, max_workers: Annotated[ int, typer.Option( help="Maximum number of workers to use for downloading files. Default is 8.", ), ] = 8, ) -> None: """Download files from the Hub.""" def run_download() -> Union[str, DryRunFileInfo, list[DryRunFileInfo]]: filenames_list = filenames if filenames is not None else [] # Warn user if patterns are ignored if len(filenames_list) > 0: if include is not None and len(include) > 0: warnings.warn("Ignoring `--include` since filenames have being explicitly set.") if exclude is not None and len(exclude) > 0: warnings.warn("Ignoring `--exclude` since filenames have being explicitly set.") # Single file to download: use `hf_hub_download` if len(filenames_list) == 1: return hf_hub_download( repo_id=repo_id, repo_type=repo_type.value, revision=revision, filename=filenames_list[0], cache_dir=cache_dir, force_download=force_download, token=token, local_dir=local_dir, library_name="huggingface-cli", dry_run=dry_run, ) # Otherwise: use `snapshot_download` to ensure all files comes from same revision if len(filenames_list) == 0: allow_patterns = include ignore_patterns = exclude else: allow_patterns = filenames_list ignore_patterns = None return snapshot_download( repo_id=repo_id, repo_type=repo_type.value, revision=revision, allow_patterns=allow_patterns, ignore_patterns=ignore_patterns, force_download=force_download, cache_dir=cache_dir, token=token, local_dir=local_dir, library_name="huggingface-cli", max_workers=max_workers, dry_run=dry_run, ) def _print_result(result: Union[str, DryRunFileInfo, list[DryRunFileInfo]]) -> None: if isinstance(result, str): print(result) return # Print dry run info if isinstance(result, DryRunFileInfo): result = [result] print( f"[dry-run] Will download {len([r for r in result if r.will_download])} files (out of {len(result)}) totalling {_format_size(sum(r.file_size for r in result if r.will_download))}." ) columns = ["File", "Bytes to download"] items: list[list[Union[str, int]]] = [] for info in sorted(result, key=lambda x: x.filename): items.append([info.filename, _format_size(info.file_size) if info.will_download else "-"]) print(tabulate(items, headers=columns)) if quiet: disable_progress_bars() with warnings.catch_warnings(): warnings.simplefilter("ignore") _print_result(run_download()) enable_progress_bars() else: _print_result(run_download()) logging.set_verbosity_warning() huggingface_hub-1.1.5/src/huggingface_hub/cli/hf.py000066400000000000000000000046571510763414300222550ustar00rootroot00000000000000# Copyright 2020 The HuggingFace Team. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. from huggingface_hub import constants from huggingface_hub.cli._cli_utils import check_cli_update, typer_factory from huggingface_hub.cli.auth import auth_cli from huggingface_hub.cli.cache import cache_cli from huggingface_hub.cli.download import download from huggingface_hub.cli.inference_endpoints import ie_cli from huggingface_hub.cli.jobs import jobs_cli from huggingface_hub.cli.lfs import lfs_enable_largefiles, lfs_multipart_upload from huggingface_hub.cli.repo import repo_cli from huggingface_hub.cli.repo_files import repo_files_cli from huggingface_hub.cli.system import env, version from huggingface_hub.cli.upload import upload from huggingface_hub.cli.upload_large_folder import upload_large_folder from huggingface_hub.utils import logging app = typer_factory(help="Hugging Face Hub CLI") # top level single commands (defined in their respective files) app.command(help="Download files from the Hub.")(download) app.command(help="Upload a file or a folder to the Hub.")(upload) app.command(help="Upload a large folder to the Hub. Recommended for resumable uploads.")(upload_large_folder) app.command(name="env", help="Print information about the environment.")(env) app.command(help="Print information about the hf version.")(version) app.command(help="Configure your repository to enable upload of files > 5GB.", hidden=True)(lfs_enable_largefiles) app.command(help="Upload large files to the Hub.", hidden=True)(lfs_multipart_upload) # command groups app.add_typer(auth_cli, name="auth") app.add_typer(cache_cli, name="cache") app.add_typer(repo_cli, name="repo") app.add_typer(repo_files_cli, name="repo-files") app.add_typer(jobs_cli, name="jobs") app.add_typer(ie_cli, name="endpoints") def main(): if not constants.HF_DEBUG: logging.set_verbosity_info() check_cli_update() app() if __name__ == "__main__": main() huggingface_hub-1.1.5/src/huggingface_hub/cli/inference_endpoints.py000066400000000000000000000255511510763414300256750ustar00rootroot00000000000000"""CLI commands for Hugging Face Inference Endpoints.""" import json from typing import Annotated, Optional import typer from huggingface_hub._inference_endpoints import InferenceEndpoint from huggingface_hub.errors import HfHubHTTPError from ._cli_utils import TokenOpt, get_hf_api, typer_factory ie_cli = typer_factory(help="Manage Hugging Face Inference Endpoints.") catalog_app = typer_factory(help="Interact with the Inference Endpoints catalog.") NameArg = Annotated[ str, typer.Argument(help="Endpoint name."), ] NameOpt = Annotated[ Optional[str], typer.Option(help="Endpoint name."), ] NamespaceOpt = Annotated[ Optional[str], typer.Option( help="The namespace associated with the Inference Endpoint. Defaults to the current user's namespace.", ), ] def _print_endpoint(endpoint: InferenceEndpoint) -> None: typer.echo(json.dumps(endpoint.raw, indent=2, sort_keys=True)) @ie_cli.command() def ls( namespace: NamespaceOpt = None, token: TokenOpt = None, ) -> None: """Lists all Inference Endpoints for the given namespace.""" api = get_hf_api(token=token) try: endpoints = api.list_inference_endpoints(namespace=namespace, token=token) except HfHubHTTPError as error: typer.echo(f"Listing failed: {error}") raise typer.Exit(code=error.response.status_code) from error typer.echo( json.dumps( {"items": [endpoint.raw for endpoint in endpoints]}, indent=2, sort_keys=True, ) ) @ie_cli.command(name="deploy") def deploy( name: NameArg, repo: Annotated[ str, typer.Option( help="The name of the model repository associated with the Inference Endpoint (e.g. 'openai/gpt-oss-120b').", ), ], framework: Annotated[ str, typer.Option( help="The machine learning framework used for the model (e.g. 'vllm').", ), ], accelerator: Annotated[ str, typer.Option( help="The hardware accelerator to be used for inference (e.g. 'cpu').", ), ], instance_size: Annotated[ str, typer.Option( help="The size or type of the instance to be used for hosting the model (e.g. 'x4').", ), ], instance_type: Annotated[ str, typer.Option( help="The cloud instance type where the Inference Endpoint will be deployed (e.g. 'intel-icl').", ), ], region: Annotated[ str, typer.Option( help="The cloud region in which the Inference Endpoint will be created (e.g. 'us-east-1').", ), ], vendor: Annotated[ str, typer.Option( help="The cloud provider or vendor where the Inference Endpoint will be hosted (e.g. 'aws').", ), ], *, namespace: NamespaceOpt = None, task: Annotated[ Optional[str], typer.Option( help="The task on which to deploy the model (e.g. 'text-classification').", ), ] = None, token: TokenOpt = None, ) -> None: """Deploy an Inference Endpoint from a Hub repository.""" api = get_hf_api(token=token) endpoint = api.create_inference_endpoint( name=name, repository=repo, framework=framework, accelerator=accelerator, instance_size=instance_size, instance_type=instance_type, region=region, vendor=vendor, namespace=namespace, task=task, token=token, ) _print_endpoint(endpoint) @catalog_app.command(name="deploy") def deploy_from_catalog( repo: Annotated[ str, typer.Option( help="The name of the model repository associated with the Inference Endpoint (e.g. 'openai/gpt-oss-120b').", ), ], name: NameOpt = None, namespace: NamespaceOpt = None, token: TokenOpt = None, ) -> None: """Deploy an Inference Endpoint from the Model Catalog.""" api = get_hf_api(token=token) try: endpoint = api.create_inference_endpoint_from_catalog( repo_id=repo, name=name, namespace=namespace, token=token, ) except HfHubHTTPError as error: typer.echo(f"Deployment failed: {error}") raise typer.Exit(code=error.response.status_code) from error _print_endpoint(endpoint) def list_catalog( token: TokenOpt = None, ) -> None: """List available Catalog models.""" api = get_hf_api(token=token) try: models = api.list_inference_catalog(token=token) except HfHubHTTPError as error: typer.echo(f"Catalog fetch failed: {error}") raise typer.Exit(code=error.response.status_code) from error typer.echo(json.dumps({"models": models}, indent=2, sort_keys=True)) catalog_app.command(name="ls")(list_catalog) ie_cli.command(name="list-catalog", help="List available Catalog models.", hidden=True)(list_catalog) ie_cli.add_typer(catalog_app, name="catalog") @ie_cli.command() def describe( name: NameArg, namespace: NamespaceOpt = None, token: TokenOpt = None, ) -> None: """Get information about an existing endpoint.""" api = get_hf_api(token=token) try: endpoint = api.get_inference_endpoint(name=name, namespace=namespace, token=token) except HfHubHTTPError as error: typer.echo(f"Fetch failed: {error}") raise typer.Exit(code=error.response.status_code) from error _print_endpoint(endpoint) @ie_cli.command() def update( name: NameArg, namespace: NamespaceOpt = None, repo: Annotated[ Optional[str], typer.Option( help="The name of the model repository associated with the Inference Endpoint (e.g. 'openai/gpt-oss-120b').", ), ] = None, accelerator: Annotated[ Optional[str], typer.Option( help="The hardware accelerator to be used for inference (e.g. 'cpu').", ), ] = None, instance_size: Annotated[ Optional[str], typer.Option( help="The size or type of the instance to be used for hosting the model (e.g. 'x4').", ), ] = None, instance_type: Annotated[ Optional[str], typer.Option( help="The cloud instance type where the Inference Endpoint will be deployed (e.g. 'intel-icl').", ), ] = None, framework: Annotated[ Optional[str], typer.Option( help="The machine learning framework used for the model (e.g. 'custom').", ), ] = None, revision: Annotated[ Optional[str], typer.Option( help="The specific model revision to deploy on the Inference Endpoint (e.g. '6c0e6080953db56375760c0471a8c5f2929baf11').", ), ] = None, task: Annotated[ Optional[str], typer.Option( help="The task on which to deploy the model (e.g. 'text-classification').", ), ] = None, min_replica: Annotated[ Optional[int], typer.Option( help="The minimum number of replicas (instances) to keep running for the Inference Endpoint.", ), ] = None, max_replica: Annotated[ Optional[int], typer.Option( help="The maximum number of replicas (instances) to scale to for the Inference Endpoint.", ), ] = None, scale_to_zero_timeout: Annotated[ Optional[int], typer.Option( help="The duration in minutes before an inactive endpoint is scaled to zero.", ), ] = None, token: TokenOpt = None, ) -> None: """Update an existing endpoint.""" api = get_hf_api(token=token) try: endpoint = api.update_inference_endpoint( name=name, namespace=namespace, repository=repo, framework=framework, revision=revision, task=task, accelerator=accelerator, instance_size=instance_size, instance_type=instance_type, min_replica=min_replica, max_replica=max_replica, scale_to_zero_timeout=scale_to_zero_timeout, token=token, ) except HfHubHTTPError as error: typer.echo(f"Update failed: {error}") raise typer.Exit(code=error.response.status_code) from error _print_endpoint(endpoint) @ie_cli.command() def delete( name: NameArg, namespace: NamespaceOpt = None, yes: Annotated[ bool, typer.Option("--yes", help="Skip confirmation prompts."), ] = False, token: TokenOpt = None, ) -> None: """Delete an Inference Endpoint permanently.""" if not yes: confirmation = typer.prompt(f"Delete endpoint '{name}'? Type the name to confirm.") if confirmation != name: typer.echo("Aborted.") raise typer.Exit(code=2) api = get_hf_api(token=token) try: api.delete_inference_endpoint(name=name, namespace=namespace, token=token) except HfHubHTTPError as error: typer.echo(f"Delete failed: {error}") raise typer.Exit(code=error.response.status_code) from error typer.echo(f"Deleted '{name}'.") @ie_cli.command() def pause( name: NameArg, namespace: NamespaceOpt = None, token: TokenOpt = None, ) -> None: """Pause an Inference Endpoint.""" api = get_hf_api(token=token) try: endpoint = api.pause_inference_endpoint(name=name, namespace=namespace, token=token) except HfHubHTTPError as error: typer.echo(f"Pause failed: {error}") raise typer.Exit(code=error.response.status_code) from error _print_endpoint(endpoint) @ie_cli.command() def resume( name: NameArg, namespace: NamespaceOpt = None, fail_if_already_running: Annotated[ bool, typer.Option( "--fail-if-already-running", help="If `True`, the method will raise an error if the Inference Endpoint is already running.", ), ] = False, token: TokenOpt = None, ) -> None: """Resume an Inference Endpoint.""" api = get_hf_api(token=token) try: endpoint = api.resume_inference_endpoint( name=name, namespace=namespace, token=token, running_ok=not fail_if_already_running, ) except HfHubHTTPError as error: typer.echo(f"Resume failed: {error}") raise typer.Exit(code=error.response.status_code) from error _print_endpoint(endpoint) @ie_cli.command() def scale_to_zero( name: NameArg, namespace: NamespaceOpt = None, token: TokenOpt = None, ) -> None: """Scale an Inference Endpoint to zero.""" api = get_hf_api(token=token) try: endpoint = api.scale_to_zero_inference_endpoint(name=name, namespace=namespace, token=token) except HfHubHTTPError as error: typer.echo(f"Scale To Zero failed: {error}") raise typer.Exit(code=error.response.status_code) from error _print_endpoint(endpoint) huggingface_hub-1.1.5/src/huggingface_hub/cli/jobs.py000066400000000000000000000564771510763414300226240ustar00rootroot00000000000000# Copyright 2025 The HuggingFace Team. All rights reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. """Contains commands to interact with jobs on the Hugging Face Hub. Usage: # run a job hf jobs run # List running or completed jobs hf jobs ps [-a] [-f key=value] [--format TEMPLATE] # Stream logs from a job hf jobs logs # Inspect detailed information about a job hf jobs inspect # Cancel a running job hf jobs cancel # Run a UV script hf jobs uv run