Publishing a YOLOv11x Model on Hugging Face

This article introduces the steps to publish a YOLOv11x model trained on the Japanese Classical Kuzushiji Dataset on Hugging Face and create a demo with Gradio Spaces.

Overview

• Model: YOLOv11x (for kuzushiji character detection)
• Dataset: Japanese Classical Kuzushiji Dataset
• Publication: Hugging Face Models + Spaces

1. Register the Model on Hugging Face Models

1.1 Install huggingface_hub

pip install huggingface_hub

1.2 Login

huggingface-cli login

Or from Python:

from huggingface_hub import login
login()

You can obtain a token from https://huggingface.co/settings/tokens (Write permission required).

1.3 Upload the Model

from huggingface_hub import HfApi, create_repo

api = HfApi()
repo_id = "your-username/yolov11x-codh-char"

# リポジトリ作成
create_repo(repo_id, repo_type="model", exist_ok=True)

# モデルファイルをアップロード
api.upload_file(
    path_or_fileobj="best.pt",
    path_in_repo="best.pt",
    repo_id=repo_id,
    repo_type="model"
)

1.4 Create a Model Card (README.md)

Create a README.md with usage instructions and license information and upload it.

2. Publish a Demo on Hugging Face Spaces

2.1 Spaces Configuration (README.md)

---
title: YOLOv11x Character
emoji: 👁
colorFrom: pink
colorTo: green
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
---

Key points:

• Specifying sdk: gradio pre-installs Gradio
• sdk_version can be used to pin the version
• No need to add gradio to requirements.txt

2.2 requirements.txt

ultralytics
Pillow

2.3 Load the Model in app.py

Use hf_hub_download to load the model from Hugging Face Hub.

from ultralytics import YOLO
from huggingface_hub import hf_hub_download

# Hugging Face からモデルをダウンロード
model_path = hf_hub_download(
    repo_id="nakamura196/yolov11x-codh-char",
    filename="best.pt"
)

# モデルを読み込み
model = YOLO(model_path)

# 推論
results = model.predict("image.jpg", conf=0.25, iou=0.45)

2.4 Notes on Gradio 5.x

In Gradio 5.x, SSR (Server-Side Rendering) is enabled by default as an experimental feature. This can cause the following error:

IndexError: function has no backend method.

To work around this issue, specify ssr_mode=False in launch().

demo.launch(share=False, ssr_mode=False)

3. Benefits of This Architecture

4. Published Resources

• Model: https://huggingface.co/nakamura196/yolov11x-codh-char
• Spaces: https://huggingface.co/spaces/nakamura196/yolov11x-codh-char

References

• Hugging Face Spaces - Gradio Documentation
• Ultralytics YOLO Documentation
• Japanese Classical Kuzushiji Dataset