> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Moondream

> Vision service implementation using Moondream for local image analysis and question answering

## Overview

`MoondreamService` provides local image analysis and question-answering capabilities using the Moondream model. It runs entirely on your local machine, supporting various hardware acceleration options including CUDA, Intel XPU, and Apple MPS for privacy-focused computer vision applications.

<CardGroup cols={2}>
  <Card title="Moondream Vision API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.moondream.vision.html">
    Pipecat's API methods for Moondream vision integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/vision/vision-openai.py">
    Browse examples using Moondream vision
  </Card>

  <Card title="Moondream Documentation" icon="book" href="https://www.moondream.ai/">
    Official Moondream model documentation
  </Card>

  <Card title="Hugging Face Model" icon="microphone" href="https://huggingface.co/vikhyatk/moondream2">
    Access Moondream model on Hugging Face
  </Card>
</CardGroup>

## Installation

To use Moondream services, install the required dependencies:

```bash theme={null}
uv add "pipecat-ai[moondream]"
```

## Prerequisites

### Local Model Setup

Before using Moondream vision services, you need:

1. **Model Download**: First run will automatically download the Moondream model from Hugging Face
2. **Hardware Configuration**: Set up CUDA, Intel XPU, or Apple MPS for optimal performance
3. **Storage Space**: Ensure sufficient disk space for model files
4. **Memory Requirements**: Adequate RAM/VRAM for model inference

### Hardware Acceleration

The service automatically detects and uses the best available hardware:

* **Intel XPU**: Requires intel\_extension\_for\_pytorch
* **NVIDIA CUDA**: For GPU acceleration
* **Apple Metal (MPS)**: For Apple Silicon optimization
* **CPU**: Fallback option for any system

### Configuration Options

* **Model Selection**: Choose Moondream model version and revision
* **Hardware Override**: Force CPU usage if needed
* **Local Processing**: Complete privacy with no external API calls

<Tip>
  No API keys required - Moondream runs entirely locally for complete privacy
  and control.
</Tip>

## Configuration

<ParamField path="model" type="str" default="vikhyatk/moondream2" deprecated>
  Hugging Face model identifier for the Moondream model. *Deprecated in
  v0.0.105. Use `settings=MoondreamService.Settings(model=...)` instead.*
</ParamField>

<ParamField path="revision" type="str" default="2025-01-09">
  Specific model revision to use.
</ParamField>

<ParamField path="use_cpu" type="bool" default="False">
  Whether to force CPU usage instead of hardware acceleration. When `False`, the
  service automatically detects and uses the best available device (Intel XPU,
  CUDA, MPS, or CPU).
</ParamField>

<ParamField path="settings" type="MoondreamService.Settings" default="None">
  Runtime-configurable settings. See [Settings](#settings) below.
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `MoondreamService.Settings(...)`. See [Service Settings](/pipecat/fundamentals/service-settings) for details.

| Parameter | Type  | Default     | Description                                                   |
| --------- | ----- | ----------- | ------------------------------------------------------------- |
| `model`   | `str` | `NOT_GIVEN` | Moondream model identifier. *(Inherited from base settings.)* |

<Note>
  `NOT_GIVEN` values are omitted, letting the service use its own defaults
  (`"vikhyatk/moondream2"` for model). Only parameters that are explicitly set
  are included.
</Note>

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.moondream import MoondreamService

vision = MoondreamService()
```

### With Settings and CPU Override

```python theme={null}
vision = MoondreamService(
    revision="2025-01-09",
    use_cpu=True,
    settings=MoondreamService.Settings(
        model="vikhyatk/moondream2",
    ),
)
```

<Tip>
  The deprecated `model` constructor parameter is replaced by `Settings` as of
  v0.0.105. Use `Settings` / `settings=` instead. See the [Service Settings
  guide](/pipecat/fundamentals/service-settings) for migration details.
</Tip>

## Notes

* **First-run download**: The model is automatically downloaded from Hugging Face on first use. Ensure sufficient disk space and network access.
* **Hardware auto-detection**: When `use_cpu=False` (the default), the service detects available hardware in this priority order: Intel XPU, NVIDIA CUDA, Apple Metal (MPS), then CPU.
* **Data types**: CUDA and MPS use `float16` for faster inference, while XPU and CPU use `float32`.
* **Blocking inference**: Image analysis runs in a separate thread via `asyncio.to_thread` to avoid blocking the event loop.