refactor: standardize HF_CACHE to HF_HOME across codebase (use Hugging Face convention)

[keivenchang]

Overview:

This PR standardizes the use of HF_HOME instead of HF_CACHE across the codebase to align with Hugging Face's standard environment variable naming conventions. The changes maintain backward compatibility while updating the container run script and documentation.

Details:

• Update container/run.sh to use HF_HOME variable instead of HF_CACHE
• Add --hf-home command line option while maintaining --hf-cache for backward compatibility
• Update help text to reference both options
• Use ${HF_HOME:-} parameter expansion for safe environment variable initialization
• Update documentation references in multinode and performance sweep examples
• Align with existing Kubernetes configurations that already use HF_HOME

Where should the reviewer start?

• container/run.sh - Main changes to variable names, command line options, and logic
• components/backends/trtllm/multinode/multinode-examples.md - Documentation update
• components/backends/trtllm/performance_sweeps/README.md - Documentation update

/coderabbit profile chill

Summary by CodeRabbit

• New Features

  • Added support for HF_HOME as the primary cache location, with a combined --hf-home|--hf-cache option.
  • Improved defaulting: when mounting a workspace, HF_HOME auto-populates if unset.
  • Updated NONE handling to clear HF_HOME appropriately.
  • Ensured volume mounting creates and mounts HF_HOME to the expected cache path.
  • Help text updated to reflect new option and semantics.

• Documentation

  • Updated guides to reference HF_HOME instead of HF_CACHE for model weight caching and pre-download instructions.

[coderabbitai]

Walkthrough

Documentation references switched from HF_CACHE to HF_HOME. The container run script replaced HF_CACHE/DEFAULT_HF_CACHE with HF_HOME/DEFAULT_HF_HOME, updated option parsing to accept --hf-home|--hf-cache, adjusted defaulting, NONE handling, directory creation, volume mounting, and help text accordingly.

Changes

Cohort / File(s)	Summary
Docs: HF_HOME reference update components/backends/trtllm/multinode/multinode-examples.md, components/backends/trtllm/performance_sweeps/README.md	Replace references to HF_CACHE with HF_HOME in guidance about model weights/pre-download location; no behavioral changes.
Container run script: HF_HOME migration container/run.sh	Migrate env/flags from HF_CACHE to HF_HOME, add combined flag `--hf-cache

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant U as User
  participant RS as container/run.sh
  participant ENV as Env Vars
  participant DK as Docker

  U->>RS: Invoke with args (--hf-home|--hf-cache, --workspace, etc.)
  RS->>RS: Parse options (map --hf-cache|--hf-home -> HF_HOME)
  RS->>ENV: Read HF_HOME / DEFAULT_HF_HOME
  alt Workspace mounted and HF_HOME empty
    RS->>RS: Set HF_HOME = DEFAULT_HF_HOME
  end
  alt HF_HOME == "NONE"
    RS->>RS: Clear HF_HOME
  else HF_HOME set
    RS->>RS: mkdir -p $HF_HOME
    RS->>DK: Run with volume: $HF_HOME -> /root/.cache/huggingface
  end
  RS-->>U: Container started with updated HF_HOME semantics
  note over RS,Dk: All previous HF_CACHE references now map to HF_HOME

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I swapped my cache for homes so neat,
Hop-hop, my flags now both compete.
A NONE means none—so clean, so light,
Mounts align and volumes right.
With HF_HOME my burrow’s set,
Carrots cached? The best one yet! 🥕🐇

Pre-merge checks

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description Check	⚠️ Warning	The pull request description follows the Overview, Details, and Where should the reviewer start sections but omits the mandatory “Related Issues” section required by the repository’s template, and includes an extraneous “/coderabbit profile chill” line that is not part of the template.	Please add the “Related Issues” section with the appropriate action keyword and issue reference (e.g., “closes GitHub issue: #123”), and remove any lines not covered by the template to fully comply with the repository’s description requirements.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The pull request title clearly and concisely describes the primary change—standardizing the environment variable from HF_CACHE to HF_HOME across the codebase to align with Hugging Face conventions—without extraneous details or ambiguity. It accurately reflects the refactoring scope and intent of the PR in a single sentence.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🧪 Early access (Sonnet 4.5): enabled

We are currently testing the Sonnet 4.5 model, which is expected to improve code review quality. However, this model may lead to increased noise levels in the review comments. Please disable the early access features if the noise level causes any inconvenience.

Note:

• Public repositories are always opted into early access features.
• You can enable or disable early access features from the CodeRabbit UI or by updating the CodeRabbit configuration file.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

container/run.sh (1)

270-273: Consider quoting the variable in the volume mount for safety.

While the current implementation works for typical paths, the $HF_HOME variable in line 272 should be quoted to handle edge cases where the path might contain spaces.

Apply this diff to add defensive quoting:

     if [ -n "$HF_HOME" ]; then
         mkdir -p "$HF_HOME"
-        VOLUME_MOUNTS+=" -v $HF_HOME:/root/.cache/huggingface"
+        VOLUME_MOUNTS+=" -v \"$HF_HOME\":/root/.cache/huggingface"
     fi

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 74a5667 and bb96ce1.

📒 Files selected for processing (3)

• components/backends/trtllm/multinode/multinode-examples.md (1 hunks)
• components/backends/trtllm/performance_sweeps/README.md (1 hunks)
• container/run.sh (5 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: sglang
• GitHub Check: Build and Test - dynamo

🔇 Additional comments (7)

components/backends/trtllm/multinode/multinode-examples.md (1)

114-114: LGTM!

Documentation updated correctly to reference HF_HOME instead of HF_CACHE, aligning with Hugging Face conventions.

components/backends/trtllm/performance_sweeps/README.md (1)

77-77: LGTM!

Documentation updated correctly to reference HF_HOME, maintaining consistency with the first documentation file.

container/run.sh (5)

34-35: LGTM!

Safe parameter expansion syntax correctly used. The variable initialization properly defaults to an empty string if HF_HOME is unset, and the default path is appropriately updated.

---

88-94: LGTM!

Excellent backward compatibility approach. The combined option flag --hf-cache|--hf-home ensures existing scripts using --hf-cache continue to work while encouraging migration to the standardized --hf-home.

---

253-255: LGTM!

Defaulting logic correctly updated to use HF_HOME. When workspace is mounted and HF_HOME is not set, it appropriately defaults to DEFAULT_HF_HOME.

---

266-268: LGTM!

NONE handling correctly updated. Setting --hf-home NONE appropriately clears the HF_HOME variable to prevent mounting.

---

322-322: LGTM!

Help text accurately updated to reflect the combined --hf-home|--hf-cache option and correctly describes the new semantics.