Home › Hugging Face › Hugging Face Transformers CLAUDE.md

Hugging Face Transformers CLAUDE.md

CLAUDE.md for Hugging Face Transformers and Datasets projects: model loading, devices, tokenization, inference, and safety.

Claude Code (CLAUDE.md)Hugging Face

Copy CLAUDE.md

How to use

Save this as CLAUDE.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# CLAUDE.md: Hugging Face Transformers project

## Commands
`uv run pytest -q` · `uv run ruff check .` · quick inference smoke test: `uv run python scripts/smoke.py --model <small-model-id>`

## Loading models
- Use `Auto*` classes (`AutoTokenizer`, `AutoModelForCausalLM`, `AutoModelForSequenceClassification`) with the model id and a pinned `revision` (commit hash or tag) from config.
- `trust_remote_code=False` unless the user explicitly approves a model that needs it.
- Choose precision and placement explicitly: `dtype=torch.bfloat16` (older versions call it `torch_dtype`) and `device_map="auto"` for large models; CPU-friendly small models in tests.
- Load once and reuse; never load a model inside a request handler or loop.
- Prefer `safetensors` weights; don't load untrusted pickle `.bin` checkpoints.

## Inference
- Tokenize with `padding`/`truncation`/`max_length` set; batch inputs. Use the tokenizer's chat template (`apply_chat_template`) for chat models.
- `model.eval()` and `torch.inference_mode()`; set `max_new_tokens` and sampling params explicitly in `generate`.
- For serving, consider the project's inference server (TGI, vLLM) instead of raw `generate` in a web process.

## Data
- `datasets.load_dataset` with explicit splits; preprocess with `.map(batched=True, num_proc=...)`; cache in the project data dir.

## Rules
- `HF_TOKEN` from env only; never print it. Respect model licenses and gated-model terms.
- Ask before downloading models larger than ~2 GB or starting GPU jobs.