Instructions to use ByteDance/Dolphin-v2 with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use ByteDance/Dolphin-v2 with Transformers:

# Use a pipeline as a high-level helper
from transformers import pipeline

pipe = pipeline("image-text-to-text", model="ByteDance/Dolphin-v2")
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"},
            {"type": "text", "text": "What animal is on the candy?"}
        ]
    },
]
pipe(text=messages)

# Load model directly
from transformers import AutoProcessor, AutoModelForMultimodalLM

processor = AutoProcessor.from_pretrained("ByteDance/Dolphin-v2")
model = AutoModelForMultimodalLM.from_pretrained("ByteDance/Dolphin-v2")
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"},
            {"type": "text", "text": "What animal is on the candy?"}
        ]
    },
]
inputs = processor.apply_chat_template(
	messages,
	add_generation_prompt=True,
	tokenize=True,
	return_dict=True,
	return_tensors="pt",
).to(model.device)

outputs = model.generate(**inputs, max_new_tokens=40)
print(processor.decode(outputs[0][inputs["input_ids"].shape[-1]:]))

Notebooks
Google Colab
Kaggle
Local Apps Settings

vLLM

How to use ByteDance/Dolphin-v2 with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "ByteDance/Dolphin-v2"
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "ByteDance/Dolphin-v2",
		"messages": [
			{
				"role": "user",
				"content": [
					{
						"type": "text",
						"text": "Describe this image in one sentence."
					},
					{
						"type": "image_url",
						"image_url": {
							"url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
						}
					}
				]
			}
		]
	}'

Use Docker

docker model run hf.co/ByteDance/Dolphin-v2

SGLang

How to use ByteDance/Dolphin-v2 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 "ByteDance/Dolphin-v2" \
    --host 0.0.0.0 \
    --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "ByteDance/Dolphin-v2",
		"messages": [
			{
				"role": "user",
				"content": [
					{
						"type": "text",
						"text": "Describe this image in one sentence."
					},
					{
						"type": "image_url",
						"image_url": {
							"url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
						}
					}
				]
			}
		]
	}'

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 "ByteDance/Dolphin-v2" \
        --host 0.0.0.0 \
        --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "ByteDance/Dolphin-v2",
		"messages": [
			{
				"role": "user",
				"content": [
					{
						"type": "text",
						"text": "Describe this image in one sentence."
					},
					{
						"type": "image_url",
						"image_url": {
							"url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
						}
					}
				]
			}
		]
	}'

Docker Model Runner
How to use ByteDance/Dolphin-v2 with Docker Model Runner:
```
docker model run hf.co/ByteDance/Dolphin-v2
```

HaoFeng2025 commited on Dec 12, 2025

Commit

4e206d9

verified ·

1 Parent(s): 026980a

Update README.md

Browse files

Files changed (1) hide show

README.md +0 -36

README.md CHANGED Viewed

@@ -46,7 +46,6 @@ Dolphin-v2 follows a document-type-aware two-stage paradigm:
 ### Stage 1: Joint Classification and Layout Analysis
 - **Document Type Classification**: Distinguishes between digital-born and photographed documents
 - **Layout Analysis**: Generates element sequences in reading order with 21 supported categories
-- **Precise Localization**: Absolute coordinate system for pixel-level accuracy
 ### Stage 2: Hybrid Content Parsing
 - **Photographed Documents**: Holistic page-level parsing to handle distortions
@@ -63,7 +62,6 @@ Built on **Qwen2.5-VL-3B** backbone with:
 ## 📈 Performance
 Dolphin-v2 achieves superior performance on comprehensive benchmarks:
 **OmniDocBench (v1.5):**
 - Overall Score: **89.45** (+14.78 over original Dolphin)
 - Text Recognition: **0.054** Edit Distance
@@ -73,7 +71,6 @@ Dolphin-v2 achieves superior performance on comprehensive benchmarks:
 ## 🎯 Supported Element Types
 Dolphin-v2 supports 21 document element categories:
 | Element Type | Description |
@@ -94,39 +91,6 @@ Dolphin-v2 supports 21 document element categories:
 | `watermark` | Watermarks |
 | `anno` | Annotations |
-## 💻 Usage
-Please refer to our [GitHub repository](https://github.com/bytedance/Dolphin) for detailed usage:
-- Page-wise parsing for complete document images
-- Element-wise parsing for specific regions
-- Examples for digital and photographed documents
-## 🔧 Training Details
-- **Backbone**: Qwen2.5-VL-3B
-- **Training Data**:
-  - 200K photographed documents with realistic distortions
-  - 200K code images (C++, Python, Go, JavaScript)
-  - 200K catalog images with hierarchical structures
-- **Optimizer**: AdamW (lr=8e-5, weight decay=0)
-- **Training**: 10 epochs on 40 A100 GPUs
-- **Max Sequence Length**: 131,072 tokens
-## 📊 Benchmarks
-We evaluate on two complementary benchmarks:
-- **OmniDocBench**: Diverse document types (academic papers, textbooks, slides, reports)
-- **RealDoc-160**: Real-world photographed documents with authentic distortions
-## 🚀 Key Features
-✅ Handles both digital and photographed documents seamlessly
-✅ 21 element categories with fine-grained detection
-✅ Precise LaTeX formula recognition
-✅ Code block parsing with indentation preservation
-✅ Robust to distortions, lighting variations, and perspective changes
-✅ Efficient parallel processing for digital documents
-✅ Lightweight 3B parameter model
 ## 📚 Citation
 ```bibtex

 ### Stage 1: Joint Classification and Layout Analysis
 - **Document Type Classification**: Distinguishes between digital-born and photographed documents
 - **Layout Analysis**: Generates element sequences in reading order with 21 supported categories
 ### Stage 2: Hybrid Content Parsing
 - **Photographed Documents**: Holistic page-level parsing to handle distortions
 ## 📈 Performance
 Dolphin-v2 achieves superior performance on comprehensive benchmarks:
 **OmniDocBench (v1.5):**
 - Overall Score: **89.45** (+14.78 over original Dolphin)
 - Text Recognition: **0.054** Edit Distance
 ## 🎯 Supported Element Types
 Dolphin-v2 supports 21 document element categories:
 | Element Type | Description |
 | `watermark` | Watermarks |
 | `anno` | Annotations |
 ## 📚 Citation
 ```bibtex