Instructions to use vikhyatk/moondream2 with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Transformers
How to use vikhyatk/moondream2 with Transformers:
# Use a pipeline as a high-level helper from transformers import pipeline pipe = pipeline("image-text-to-text", model="vikhyatk/moondream2", trust_remote_code=True)# Load model directly from transformers import AutoModelForCausalLM model = AutoModelForCausalLM.from_pretrained("vikhyatk/moondream2", trust_remote_code=True, device_map="auto") - Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- vLLM
How to use vikhyatk/moondream2 with vLLM:
Install from pip and serve model
# Install vLLM from pip: pip install vllm # Start the vLLM server: vllm serve "vikhyatk/moondream2" # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:8000/v1/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "vikhyatk/moondream2", "prompt": "Once upon a time,", "max_tokens": 512, "temperature": 0.5 }'Use Docker
docker model run hf.co/vikhyatk/moondream2
- SGLang
How to use vikhyatk/moondream2 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 "vikhyatk/moondream2" \ --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": "vikhyatk/moondream2", "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 "vikhyatk/moondream2" \ --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": "vikhyatk/moondream2", "prompt": "Once upon a time,", "max_tokens": 512, "temperature": 0.5 }' - Docker Model Runner
How to use vikhyatk/moondream2 with Docker Model Runner:
docker model run hf.co/vikhyatk/moondream2
Support transformers 5: call post_init() and recompute non-persistent buffers
With transformers 5.x, AutoModelForCausalLM.from_pretrained("vikhyatk/moondream2", trust_remote_code=True) either fails to load or loads a model that generates garbage. This PR adds the two hooks transformers 5 expects from model classes to HfMoondream.
1. Loading on CUDA/MPS fails
AttributeError: 'HfMoondream' object has no attribute 'all_tied_weights_keys'. Did you mean: '_tied_weights_keys'?
Transformers 5 sets all_tied_weights_keys and other loading metadata in PreTrainedModel.post_init(), which every model's __init__ is expected to call. HfMoondream.__init__ now calls it.
2. The model loads but generates garbage
Even when loading succeeds (e.g. on CPU), query() returns noise such as "].append].append…". Transformers 5 builds the model on the meta device, and non-persistent buffers aren't in the checkpoint, so they're materialized uninitialized and must be recomputed in _init_weights(). Moondream has two, MoondreamModel.attn_mask and text.freqs_cis. HfMoondream._init_weights() now recomputes both, using the same logic as their constructors.
Transformers maintainers confirmed both requirements for remote code in huggingface/transformers#43883 (post_init) and huggingface/transformers#43644 (non-persistent buffers).
Testing
Loaded with AutoModelForCausalLM.from_pretrained(..., trust_remote_code=True, device_map={"": "mps"}, dtype=torch.float16) on transformers 5.17.0 and 4.57.6. On both, the loaded buffers are identical to an eager (non-meta) build, and query() / caption() return correct answers. Behavior on 4.57.6 is unchanged from the current main.