# Moondream Vlm

> Use al analizar imágenes con un VLM diminuto (Moondream).

- Skill: `ntizar/moondream-vlm` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ntizar/moondream-vlm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ntizar/moondream-vlm/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ntizar (https://skillmd.com/u/ntizar)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ntizar/moondream-vlm

---


# Moondream — Vision Language Model diminuto (10k⭐)

## When to Use

Cuando hace falta entender imágenes con consultas en lenguaje natural abierto (VQA, captioning, detección por texto, pointing, OCR) sin entrenar un modelo, y GPT-4o/gemini vision es caro o lento. Encaja con el stack de visión de David (onnx-webgpu-inference, cctv-yolo, satellite-ai-vision): YOLO para clases fijas en tiempo real; Moondream para preguntas abiertas ("¿hay operarios sin casco?").

## Resumen

Moondream (M87 Labs, Apache-2.0) es un VLM de ~2B parámetros (variante destilada 0.5B para edge) "que corre en cualquier sitio".

| Modelo | Params | Uso |
|--------|--------|-----|
| Moondream 2B | 2B | general: caption, VQA, detect |
| Moondream 0.5B | 0.5B | edge/dispositivos restringidos (destilado) |
| moondream3.1-9B-A2B | 9B (MoE A2B) | variante que sirve la API cloud actual |

## API Cloud (la vía rápida — verificado en docs oficiales)

Base: `https://api.moondream.ai/v1` · Auth: header `X-Moondream-Auth: API_KEY` (clave en https://moondream.ai/c/cloud/api-keys)

```bash
# VQA
curl -X POST https://api.moondream.ai/v1/query \
  -H 'Content-Type: application/json' -H 'X-Moondream-Auth: KEY' \
  -d '{"model":"moondream3.1-9B-A2B","image_url":"URL","question":"¿Qué hay en la imagen?"}'
# -> {"answer": "...", "request_id": "..."}
```

Endpoints (todos POST, JSON, imagen por `image_url`):

| Endpoint | Payload extra | Respuesta |
|----------|---------------|-----------|
| `/v1/query` | `question` | `{answer}` |
| `/v1/caption` | `length: "normal"`, `stream` | `{caption, metrics{ttft_ms,...}}` |
| `/v1/detect` | `object: "perro"` | `{objects:[{x_min,y_min,x_max,y_max}]}` **coords normalizadas 0-1** |
| `/v1/point` | `object` | `{points:[{x,y}]}` normalizadas |

**Pitfall clave:** las coordenadas de detect/point vienen normalizadas [0,1] — multiplicar por `width`/`height` de la imagen real antes de dibujar boxes o recortar.

## SDK Python / Node

```python
import moondream as md
from PIL import Image

model = md.vl(api_key="KEY")           # cloud
image = Image.open("foto.jpg")
model.query(image, "¿Qué hace la niña?")     # {"answer": ...}
model.detect(image, "coche")                  # {"objects": [...]}
model.point(image, "semáforo")                # {"points": [...]}
model.caption(image, length="normal")         # {"caption": ...}
```

`pip install moondream` · `npm install moondream` (misma superficie: `new vl({apiKey})`, métodos query/detect/point/caption).

## Uso local

El repo remite a https://moondream.ai/c/docs/quickstart (sección "Running Locally") para inferencia en hardware propio. Históricamente las variantes 0.5B/2B corren en CPU/GPU modestas vía `transformers` con `trust_remote_code=True` desde HuggingFace (`m87-labs/moondream-2b`). Los modelos 3.x usan pesos propios: verificar la variante local exacta en docs antes de integrar en producción.

## Comparativa rápida

- **Vs YOLO (cctv-yolo, onnx-webgpu):** YOLO gana en clases fijas, tiempo real y navegador; Moondream en consultas abiertas y OCR/VQA sin entrenar.
- **Vs GPT-4o vision:** Moondream mucho más barato y rápido (TTFT ~80ms en cloud) con pesos abiertos; menos capaz en razonamiento complejo.
- **Vs CLIP (clip-multimodal):** CLIP solo hace matching texto-imagen; Moondream genera texto y boxes.

## Patrón integrado Mastermind (auditoría de fotos de obra/infra)

```python
import moondream as md
model = md.vl(api_key=KEY)
for path in fotos:
    img = Image.open(path)
    cap = model.caption(img)["caption"]
    boxes = model.detect(img, "persona")["objects"]
    # escalar coords 0-1 → píxeles antes de anotar
```

## Verificación

```bash
python -c "import moondream as md, os; from PIL import Image; m = md.vl(api_key=os.environ['MOONDREAM_API_KEY']); print(m.caption(Image.open('test.jpg'))['caption'][:80])"
```

## Referencia

- Repo: https://github.com/m87-labs/moondream · Web: https://moondream.ai/ · Playground: https://moondream.ai/playground
- Examples: https://github.com/m87-labs/moondream-examples (incluye cómo correr en Modal)