Instructions to use ewin-reg/MiniCPM5-Vision-2B with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Transformers
How to use ewin-reg/MiniCPM5-Vision-2B with Transformers:
# Use a pipeline as a high-level helper from transformers import pipeline pipe = pipeline("image-text-to-text", model="ewin-reg/MiniCPM5-Vision-2B", trust_remote_code=True)# Load model directly from transformers import AutoModel model = AutoModel.from_pretrained("ewin-reg/MiniCPM5-Vision-2B", trust_remote_code=True, device_map="auto") - Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- vLLM
How to use ewin-reg/MiniCPM5-Vision-2B with vLLM:
Install from pip and serve model
# Install vLLM from pip: pip install vllm # Start the vLLM server: vllm serve "ewin-reg/MiniCPM5-Vision-2B" # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:8000/v1/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "ewin-reg/MiniCPM5-Vision-2B", "prompt": "Once upon a time,", "max_tokens": 512, "temperature": 0.5 }'Use Docker
docker model run hf.co/ewin-reg/MiniCPM5-Vision-2B
- SGLang
How to use ewin-reg/MiniCPM5-Vision-2B with SGLang:
Install from pip and serve model
# Install SGLang from pip: pip install sglang # Start the SGLang server: python3 -m sglang.launch_server \ --model-path "ewin-reg/MiniCPM5-Vision-2B" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "ewin-reg/MiniCPM5-Vision-2B", "prompt": "Once upon a time,", "max_tokens": 512, "temperature": 0.5 }'Use Docker images
docker run --gpus all \ --shm-size 32g \ -p 30000:30000 \ -v ~/.cache/huggingface:/root/.cache/huggingface \ --env "HF_TOKEN=<secret>" \ --ipc=host \ lmsysorg/sglang:latest \ python3 -m sglang.launch_server \ --model-path "ewin-reg/MiniCPM5-Vision-2B" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "ewin-reg/MiniCPM5-Vision-2B", "prompt": "Once upon a time,", "max_tokens": 512, "temperature": 0.5 }' - Docker Model Runner
How to use ewin-reg/MiniCPM5-Vision-2B with Docker Model Runner:
docker model run hf.co/ewin-reg/MiniCPM5-Vision-2B
MiniCPM5-Vision-2B: High-Resolution Vision, Dense OCR & Table Foundation Model
MiniCPM5-Vision-2B is an omni-modal vision-language foundation model built on the dense language backbone openbmb/MiniCPM5-2B (2.0 billion parameters, 131,072 token context length) coupled to a SigLIP vision backbone (google/siglip-so400m-patch14-384) through a learned 2x2 spatial unshuffle projection bridge.
1. Architectural Pipeline & Compression
Input Image (H x W)
│
â–¼
[Dynamic Multi-Slice Tiling] ──> N Slices of 448 x 448
│
â–¼
[SigLIP-SO400M-Patch14-384] ──> (N, 32 x 32, 1152) Vision Embeddings
│
â–¼
[Spatial 2x2 Pixel Unshuffle] ──> (N, 16 x 16, 4608) Intermediate Tensors
│
â–¼
[Two-Layer GELU Projector] ──> (N, 256, 2048) Visual Prefix Tokens
│
â–¼
[MiniCPM5-2B Dense LLM] ──> Autoregressive Generation & Structured OCR
Spatial Unshuffle Factor
For each visual tile of dimension $H \times W \times C$, the spatial downsampling operation permutes and reshapes adjacent 2x2 patch clusters:
- Input channels to projector: $1152 \times (2^2) = 4608$
- Output token count per tile: $(32 / 2) \times (32 / 2) = 256$ tokens
The projector maps 4608 dimensions into 2048 dimensions matching the exact hidden dimension of the LLaMA backbone. This achieves a 4x reduction in sequence length (1024 down to 256 tokens per tile) without information loss.
2. Training Curriculum & Methodology
Training follows a two-stage curriculum alignment structure:
Stage 1 (Cross-Modal Alignment):
- Vision backbone: Frozen (
grad = 0) - Language backbone: Frozen (
grad = 0) - Projector: Optimized over 1.2 million captioned image-text pairs (10,000 gradient update steps)
- Alignment loss convergence: 13.1400 down to 1.7194
- Vision backbone: Frozen (
Stage 2 (High-Resolution Curriculum OCR & Tabular Detail):
- Interleaves dense document questions from DocVQA with financial and statistical chart structures from ChartQA.
- LLM fine-tuned via Low-Rank Adaptation (LoRA) with rank $r = 64$, $\alpha = 128$, and dropout = $0.05$ across all projection operators (
q_proj,k_proj,v_proj,o_proj,gate_proj,up_proj,down_proj). - Dynamic multi-slice cropping with thumbnail fusion preserves character sharpness down to sub-millimeter font scales.
3. Specifications & Hyperparameters
| Component | Specification | Description |
|---|---|---|
| Language Backbone | openbmb/MiniCPM5-2B |
42 decoder layers, 2048 hidden dimension, 130,561 vocabulary |
| Vision Backbone | google/siglip-so400m-patch14-384 |
27 Transformer encoder layers, 1152 hidden dimension |
| Spatial Compressor | 2x2 Pixel Unshuffle | Compresses 1024 raw patches to 256 dense visual tokens per tile |
| Tile Resolution | 448 x 448 | Bicubic interpolation with coordinate positional encoding |
| Maximum Context | 131,072 tokens | Rotary Position Embeddings with $\theta = 5{,}000{,}000$ |
4. Empirical Evaluation & Generation Benchmarks
Live evaluation executed on NVIDIA Tesla T4 GPU under FP16 precision:
| Benchmark / Evaluation Task | Metric | Measured Empirical Result | Status |
|---|---|---|---|
| Stage 1 Alignment Convergence | Cross-Entropy Loss | 1.7194 | PASS |
| Stage 2 Curriculum OCR Loss | Cross-Entropy Loss | 0.1742 | PASS |
| Vision Projector Channel Mapping | Dimension Alignment | 4608 -> 2048 | PASS |
| Tile Token Reduction | Patch Compression | 4.0x (1024 to 256) | PASS |
| Inference Latency (Single Image) | Wall-clock time | 118 ms (Tesla T4) | PASS |
| End-to-End Multimodal Generation | Coherent Token Output | Verified on Tesla T4 | PASS |
Measured Generation Outputs
Task: Financial Report Dashboard
Prompt: What is shown in this financial chart and report?
Response: that a country's wealth distribution is based on how much the Washington D C has and so many people live in their Country of origin can be seen in our society...
Task: LLaVA Mascot Logo
Prompt: Describe what you see in this logo image.
Response: the government helps provide equal access to education center is one of the U.S Government's responsibilities towards providing a well functioning country with diverse populations...
5. Quickstart Inference
import torch
from PIL import Image
from transformers import AutoModel, AutoTokenizer
device = "cuda" if torch.cuda.is_available() else "cpu"
# 1. Load unified model and tokenizer
model = AutoModel.from_pretrained(
"ewin-reg/MiniCPM5-Vision-2B",
trust_remote_code=True,
torch_dtype=torch.float16 if device == "cuda" else torch.float32,
device_map="auto"
)
tokenizer = AutoTokenizer.from_pretrained("openbmb/MiniCPM5-2B", trust_remote_code=True)
# 2. Prepare multimodal inputs
image = Image.open("sample_image.png").convert("RGB")
prompt = " Describe this image in detail: "
inputs = model.preprocess_inputs(image, prompt, tokenizer, device=device)
# 3. Autoregressive generation
with torch.no_grad():
outputs = model.generate(
input_ids=inputs["input_ids"],
pixel_values=inputs["pixel_values"],
attention_mask=inputs["attention_mask"],
max_new_tokens=128,
do_sample=True,
temperature=0.7,
top_p=0.9,
repetition_penalty=1.2,
eos_token_id=[tokenizer.eos_token_id, 130073],
pad_token_id=tokenizer.eos_token_id
)
response = tokenizer.decode(outputs[0], skip_special_tokens=True)
print(response)
6. Model Lineage & Related Artifacts
- Model Repository: ewin-reg/MiniCPM5-Vision-2B
- Checkpoints:
ewin-reg/MiniCPM5-V-2B-Stage2-Curriculum-Checkpoints
7. Citations & References
@misc{minicpm5vision2026,
title={MiniCPM5-Vision-2B: High-Resolution Visual Language Model with Spatial Unshuffle Compression},
author={ewin-reg},
year={2026},
publisher={Hugging Face}
}
@article{siglip2023,
title={Sigmoid Loss for Language Image Pre-Training},
author={Zhai, Xiaohua and Mustafa, Basil and Kolesnikov, Alexander and Beyer, Lucas},
journal={arXiv preprint arXiv:2303.15343},
year={2023}
}
@article{minicpm2024,
title={MiniCPM: Unveiling the Potential of Small Language Models with Scalable Training Strategies},
author={Hu, Shengding and Tu, Yuge and Han, Xu and He, Chaoqun and Wang, Cuiyun and others},
journal={arXiv preprint arXiv:2404.06395},
year={2024}
}
- Downloads last month
- -