# HuggingFace Python API Notes

## Listing Models — Working Pattern

```python
from huggingface_hub import HfApi
import json

api = HfApi()

# CORRECT — no 'direction' param
models = api.list_models(sort="downloads", limit=30)

model_list = []
for model in models:
    model_list.append({
        "id": model.id,
        "pipeline_tag": model.pipeline_tag,
        "downloads": model.downloads,
        "likes": model.likes,
        "tags": model.tags[:5] if model.tags else [],
        "library_name": model.library_name,
    })

print(json.dumps(model_list, indent=2, ensure_ascii=False))
```

### WRONG — will raise TypeError
```python
# ❌ No 'direction' parameter exists
models = api.list_models(sort="downloads", direction=-1, limit=30)
```

## Proxy Configuration

```bash
# For Python API calls
export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890

# For hf CLI — use mirror endpoint
export HF_ENDPOINT=https://hf-mirror.com
```

If proxy returns empty responses or connection refused, the proxy may not be running or may block HuggingFace domains.

## Offline Fallback: Curated Model List

When API is unreachable, use this known-popular-models data (as of 2025):

### LLM (text-generation)
- `meta-llama/Llama-2-7b-hf` — Meta Llama 2, 7B
- `mistralai/Mistral-7B-v0.1` — Mistral 7B, GQA+SWA
- `Qwen/Qwen-7B` — Alibaba Qwen, strong Chinese
- `THUDM/chatglm3-6b` — Zhipu ChatGLM3, bilingual
- `google/gemma-7b` — Google Gemma, based on Gemini
- `microsoft/phi-2` — 2.7B, punches above weight
- `TinyLlama/TinyLlama-1.1B-Chat` — compact, resource-friendly
- `01-ai/Yi-6B` — Zero One AI, strong Chinese

### Text Embedding
- `sentence-transformers/all-MiniLM-L6-v2` — 384d, most popular
- `BAAI/bge-large-zh-v1.5` — 1024d, best Chinese embedding
- `intfloat/multilingual-e5-large` — 1024d, 100+ languages
- `thenlper/gte-large` — Alibaba DAMO, 1024d
- `jinaai/jina-embeddings-v2-base-en` — 8K context, 768d

### Image Generation (text-to-image)
- `stabilityai/stable-diffusion-xl-base-1.0` — SDXL, 1024px
- `runwayml/stable-diffusion-v1-5` — Classic SD, largest ecosystem
- `CompVis/stable-diffusion-v1-4` — Early SD
- `prompthero/openjourney` — Midjourney-style fine-tune

### Audio/Speech
- `openai/whisper-large-v3` — 99 languages ASR
- `facebook/wav2vec2-large-960h` — Self-supervised ASR
- `microsoft/speecht5_tts` — Text-to-speech
- `suno/bark` — TTS + music + sound effects

### Computer Vision
- `google/vit-base-patch16-224` — Vision Transformer
- `facebook/detr-resnet-50` — Object detection, no NMS
- `microsoft/resnet-50` — Classic ResNet
- `openai/clip-vit-base-patch32` — Zero-shot image classification

### Multimodal
- `llava-hf/llava-1.5-7b-hf` — LLaVA vision-language
- `Salesforce/blip2-opt-2.7b` — Image captioning + VQA
- `microsoft/git-base-coco` — Image description
- `Qwen/Qwen-VL-Chat` — Chinese multimodal

## HTML Showcase Generation

When user asks for a visual model overview, generate an HTML page with:
- Category-based grouping (LLM, Embedding, Image, Audio, Vision, Multimodal)
- Card layout with model name, description, stats (downloads/likes), tags
- Link to HuggingFace model page
- Responsive design, gradient background

See `/home/longshao/huggingface-models.html` for a reference implementation.
Key CSS patterns: gradient header, card grid with `auto-fill minmax(300px, 1fr)`, hover lift effect.