Moondream：能装下的视觉模型 partout

#是一组模型，而非单个模型

Moondream 由 M87 Labs 发布。其最初作者 Vikhyat Korrapati 在 GitHub 仓库中将其描述为“a tiny vision language model that kicks ass and runs anywhere”。如今，Moondream 这一名称指代四种特性截然不同的变体，而较早的指南经常将它们混为一谈。

规模差异改变了使用场景的本质。一个拥有 20 亿参数的模型可以在没有专用显卡的笔记本电脑或嵌入式设备上加载。一个总参数量为 90 亿的模型，即使每个 token 只激活 20 亿参数，也必须将所有权重保留在内存中：这就是为什么第三代模型需要约 10 GB 的内存，其 Preview 版本的 FP8 文件大小为 10.51 GB。Moondream 的文档明确指出，配备 16 GB 内存的基础款 Mac mini M4 可以运行 Moondream 2，但 Moondream 3 的权重超出了其统一内存的容量。

#功能特性

Moondream 模型提供原生能力，输出采用结构化格式，而不是需要自行解析的自由文本。根据 3.1 版本的模型说明，每项能力都有固定的输出规范。

Query（回答问题）

用自然语言针对图像提问，获得自由形式的回答。这是通用入口。模型说明指出，不提供经过校准的置信度：请提出可核实的问题。

Caption（描述图像）

图像描述有三种长度：short、normal 或 long。模型说明提醒，较长的描述以更高的幻觉风险为代价换取更高的召回率，而且不应通过分析描述来提取计数或坐标。

Detect（检测）

为任意表达生成边界框，坐标以左上角为原点，归一化到 0 到 1 之间。每次调用最多生成 200 个边界框，默认阈值为 0.30。

定位（pointer）

标出每个实例的中心，最多 64 个点：比边界框更节省资源，适合计数。

Segment（图像分割）

为每个匹配的对象生成一个掩码，最多支持 50 个对象实例；不提供掩码的置信度分数。

Moondream 2 逐步获得了这些能力。作者发布的变更日志提到，2025 年 3 月加入了长篇图像描述、开放词汇标注，并改进了计数能力（CountBenchQA 从 80 提升至 86.4）。2025 年 4 月，文档和图表的阅读能力有所提升（ChartQA 从 74.8 提升至 77.5）。2025 年 6 月加入了锚定推理模式，在 query 功能中通过 reasoning=True 启用，以牺牲速度换取更高的准确性；作者还表示，文本生成速度提高了 20% 至 40%。这些数字来自作者自己的评估：可用来了解模型的演进，不应用来与其他模型比较。

一个使用要点：Moondream 并非处理整张图像，而是将其切分。根据其 FAQ，它会调整图像尺寸，使一个由约 378 × 378 像素的图块组成的网格覆盖图像，最多包含 12 个局部图块加一个全局视图，局部图块总计约 170 万像素。3.1 版本的说明确认了最多 12 个图块的自适应切分，适用于长边最大为 4 096 像素的 PNG、JPEG 或 WebP 图像。因此，一张 1200 万像素的照片在分析前会被大幅缩小：若要读取细节，请先裁剪该区域。

#它的资源消耗

这些数字来自 Moondream 的模型页面，必须结合测试条件理解：使用的是 RTX 3090 显卡、int4 量化和 compile()，测量的是文本生成速度，而不是每张图片的处理时间。每张图片的处理时间取决于输出长度和图像切片数量。同一页面还宣称，int4 量化能减少 42% 的内存占用，代价是 0.6% 的准确率损失，但没有说明采用了什么评估；请将其视为发布方的声明。

对于 3.1 代，Photon 引擎支持的硬件包括：在 Linux 或 Windows 下运行的 NVIDIA Ampere 或更新架构的显卡，或运行 macOS 13 及以上版本的 Apple Silicon Mac，使用 Python 3.10 至 3.14。模型说明页还列出了 NVIDIA SM75 及以上架构、至少 10 GB 显存的要求，以及适用于 x86 或 ARM 处理器的 GGUF 版本和适用于 Apple Silicon 的 MLX 版本。文档最后还将 Jetson 系列设备列为受支持的平台，其中包括配备 8 GB 内存的 Jetson Orin Nano。

• VRAM 是什么，运行 AI 需要多少？

#三种启动方式

1. 01
   使用 moondream 库和 Photon

   安装软件包，然后加载模型：首次调用时会从 Hugging Face 下载权重；根据文档，基础模型无需 API 密钥。Photon 只能在 NVIDIA Ampere 或更新架构的 GPU 上运行，或在搭载 Apple Silicon 的 Mac 上运行。
2. 02
   使用 Transformers

   仓库 vikhyatk/moondream2 使用 AutoModelForCausalLM 加载。请明确指定版本：作者提醒该模型频繁更新，建议在生产环境中固定版本。启用 trust_remote_code=True 会执行仓库提供的代码：仅在信任来源时开启。
3. 03
   使用 Ollama

   moondream 的第 Ollama 页显示占用 1.7 GB 内存，上下文长度为 2000 个标记，最后更新时间为两年前，因此早于 2025 年发布的 Moondream 2 版本，且不支持生成 3 版本。在采用前，请确认该版本具备您所需的功能。

# pip install --upgrade moondream
import moondream as md
from PIL import Image

model = md.photon("moondream2")   # ou "moondream3.1-9B-A2B" avec une carte de 10 Go ou plus
image = Image.open("photo.jpg")

print(model.caption(image, length="short")["caption"])
print(model.query(image, "Combien de personnes sont visibles ?")["answer"])
for obj in model.detect(image, "casque")["objects"]:
    print(obj)

请记住，detect能力返回的是归一化坐标：将其乘以原始图像的宽度和高度，即可还原为像素坐标。

• 本地多模态模型概览
• 来源：本地运行的官方文档
• 来源：Moondream 2在Hugging Face的模型页面

#它具有优势的使用场景

1. 01
   对照片库进行索引

   为每张图片生成说明文字，让照片库可以通过文本搜索。每张图片的处理成本决定了可行性，而这正是小模型的优势所在。请使用简短的说明文字：过长的说明可能会编造细节。
2. 02
   先过滤，再交给大模型

   进行粗略筛选，只将值得交给高成本模型处理的图像发送给它。point 功能用于计数，detect 功能用于自动裁剪出随后要分析的区域。
3. 03
   为无障碍访问描述图像

   在现有网站上本地批量生成文本替代内容，无需将图像发送至第三方服务。请检查样本：一段图注仍属于假设性内容。
4. 04
   监控图像流

   在一台持续运行、配置不高的电脑上，针对连续图像提出封闭式问题。0.5B模型的设计目标是针对范围较窄的任务进行微调；据 M87 Labs 所述，这能大幅提高其准确率。

从3.1版本的说明中可以得出一个良好实践：提出明确且具体的问题。小模型能准确回答‘人物头上有没有耳机？’，但对‘分析这个场景’这类问题则会泛化扩散。

#不应要求它做的事

3.1 版本的模型说明专门用一整节介绍其局限性，这种做法少见而可贵。它描述了评估中最常见的失效情况，其中给出的阈值可作为同系列模型的参考。

小字号文字

在图像分块的分辨率下，小于约 10 像素的文字往往会被误读或忽略：请先裁剪并放大该区域。

小物体

长边小于 12 像素的物体会被 detect 漏检：请对裁剪后的区域使用 point。

物体密集的场景

当实例数量超过约 50 时，召回率下降，相邻的相同对象会合并。超过 50 的计数结果可靠性较低。

读取模糊文本

在文字模糊、风格化或部分遮挡的情况下，模型可能生成看似合理但错误的文本，且不会发出低置信度的提示。对于完整文档，建议使用OCR引擎以获得更可靠的结果。

高风险用途

未经人工复核就根据文档进行医疗解读或作出法律、财务决策，均明确不在适用范围内。小模型的输出需要核查。

• 阅读扫描文档需依赖OCR
• Qwen VL：高端本地视觉能力

#许可证：您可以做什么

如果您要为自己的照片库建立索引，或描述自己网站上的图片，这些许可证都不会构成障碍：内部使用或作为产品组件使用均获允许。限制仅针对出售 Moondream 本身访问权限的情况，例如提供托管的通用视觉 API。若对商业用途有疑问，应以许可证为准，而非本摘要。

#Moondream 或一个大型视觉模型

应该问自己的不是“哪个最好”，而是“要处理多少张图像，以及要用来做什么决策”。每天只有少量图像，问题又是开放式的：选择您的显卡能容纳的最大模型。需要处理成千上万张图像，并反复回答同一个封闭式问题：小模型能让项目成为可能。

级联架构结合了两种方案：小模型处理所有输入，并标记出值得关注的案例，大模型只处理这些案例。面对规模较大的资料库，这是在质量与计算时间之间取得最佳平衡的方案。此时，Moondream 的检测能力起到筛选作用：它裁剪出目标对象，再由大模型分析裁剪后的区域。

• 使用Ollama在本地运行多模态模型
• 本地运行 Qwen3-VL
• PaddleOCR：理解页面的 OCR
• 来源：Moondream 的 GitHub 仓库
• 来源：Moondream模型页面

#FAQ