Instructions to use moondream/moondream3-preview with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Transformers
How to use moondream/moondream3-preview with Transformers:
# Use a pipeline as a high-level helper from transformers import pipeline pipe = pipeline("image-text-to-text", model="moondream/moondream3-preview", trust_remote_code=True)# Load model directly from transformers import AutoModelForCausalLM model = AutoModelForCausalLM.from_pretrained("moondream/moondream3-preview", trust_remote_code=True, dtype="auto") - Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- vLLM
How to use moondream/moondream3-preview with vLLM:
Install from pip and serve model
# Install vLLM from pip: pip install vllm # Start the vLLM server: vllm serve "moondream/moondream3-preview" # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:8000/v1/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "moondream/moondream3-preview", "prompt": "Once upon a time,", "max_tokens": 512, "temperature": 0.5 }'Use Docker
docker model run hf.co/moondream/moondream3-preview
- SGLang
How to use moondream/moondream3-preview 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 "moondream/moondream3-preview" \ --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": "moondream/moondream3-preview", "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 "moondream/moondream3-preview" \ --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": "moondream/moondream3-preview", "prompt": "Once upon a time,", "max_tokens": 512, "temperature": 0.5 }' - Docker Model Runner
How to use moondream/moondream3-preview with Docker Model Runner:
docker model run hf.co/moondream/moondream3-preview
fix: preserve spatial_toks when reasoning=true
Browse filesFixes bug where spatial_refs parameter fails when reasoning mode is enabled.
Root cause: Line 670 was replacing prompt_tokens with only the suffix,
discarding the spatial_toks that were added earlier. This caused a shape
mismatch error in _prefill_prompt() when trying to encode spatial refs.
Error was:
RuntimeError: shape mismatch: value tensor of shape [2, 2048]
cannot be broadcast to indexing result of shape [0, 2048]
Fix: Convert tensor back to list, append suffix, maintain 2D structure:
Before: prompt_tokens = [self.config.tokenizer.templates["query"]["suffix"]]
After: prompt_tokens = [prompt_tokens[0].tolist() + self.config.tokenizer.templates["query"]["suffix"]]
After _generate_reasoning() returns, prompt_tokens is a torch.Tensor, not a list.
Cannot use += operator on Tensor with list. Must convert to list first, append
suffix, then wrap in list to maintain 2D batch structure.
Tested: spatial_refs now work with reasoning=true without errors.
- moondream.py +1 -1
|
@@ -667,7 +667,7 @@ class MoondreamModel(nn.Module):
|
|
| 667 |
pos, reasoning_text, reasoning_grounding = self._generate_reasoning(
|
| 668 |
prompt_tokens, pos, settings, spatial_refs, attn_mask=attn_mask
|
| 669 |
)
|
| 670 |
-
prompt_tokens = [self.config.tokenizer.templates["query"]["suffix"]]
|
| 671 |
reasoning_dict = {
|
| 672 |
"reasoning": {"text": reasoning_text, "grounding": reasoning_grounding}
|
| 673 |
}
|
|
|
|
| 667 |
pos, reasoning_text, reasoning_grounding = self._generate_reasoning(
|
| 668 |
prompt_tokens, pos, settings, spatial_refs, attn_mask=attn_mask
|
| 669 |
)
|
| 670 |
+
prompt_tokens = [prompt_tokens[0].tolist() + self.config.tokenizer.templates["query"]["suffix"]]
|
| 671 |
reasoning_dict = {
|
| 672 |
"reasoning": {"text": reasoning_text, "grounding": reasoning_grounding}
|
| 673 |
}
|