给智能体装上“眼睛“：Qwen-MM-Plugins 多模态插件 5 分钟上手指南

给智能体装上"眼睛"：Qwen-MM-Plugins 多模态插件 5 分钟上手指南

【免费下载链接】Qwen-MM-PluginsMake any agent harness multimodal-native.项目地址: https://gitcode.com/gh_mirrors/qw/Qwen-MM-Plugins

想让智能体读懂图片、听懂音频、看得懂视频？试试Qwen-MM-Plugins——这个开源多模态插件工具集的目标只有一句话：让任何智能体框架都具备多模态原生能力。装上它，你的助手就不再是"文盲"：截图、PDF、长视频、3D 模型统统能看，还能顺带完成 OCR、语音转写、看图定位和网页搜索。本文用最短路径带你跑通全流程。

先看效果：装好之后你只需要"指一下文件"

最爽的一点：核心能力装完后，你不用学任何新 API。把文件丢给智能体，用大白话说需求，模型会自动挑选合适工具。官方 cookbook 里就有可照抄复现的真实案例：

• 读视频：@promo.mp4→ "总结这条视频讲了什么"
• 读文档：@report.pdf→ "概括第 3 页的内容"
• OCR：@receipt.jpg→ "识别文字并帮我算总额"
• 定位：@street.jpg→ "框出画面里所有车辆"

背后的机制是"技能 + MCP 服务器"双件套：技能负责让模型知道工具有哪些，MCP 服务器提供工具本体、由uvx按需拉起，全程无需手动 pip。

环境清单：三条打勾项

开跑前先核对三件事，缺一不可：

• ✅操作系统：Linux；Windows 用户请装 WSL2，并在 WSL 的 home 目录下操作（别放在/mnt/c）
• ✅Python：3.8 及以上，建议顺带装上 uv（MCP 服务器靠uvx启动）
• ✅系统工具：ffmpeg（视频/音频处理）、libreoffice（文档可视化）

Ubuntu/Debian 一条命令补齐：

sudo apt install ffmpeg libreoffice

3 步跑通：安装 → 配密钥 → 自检

Step 1：克隆仓库并启动引导安装器

git clone https://gitcode.com/gh_mirrors/qw/Qwen-MM-Plugins cd Qwen-MM-Plugins bash install.sh

安装器是交互式菜单：先选目标 harness（支持 Claude Code、Codex、Qoder、OpenClaw、Qwen Code、Gemini CLI），再勾选能力模块，底层调用各 harness 自己的原生插件市场命令，不重复造轮子。常用模块如下：

模块	干什么用的
core	基础视觉：读图/视频/文档 + OCR、定位、分割、ASR、视觉对话
video-memory	超长视频的层次化记忆与问答
video-edit/omni-av	视频剪辑生成 / 音视频综合理解
blender/freecad	驱动运行中的 Blender / FreeCAD 做 3D 建模与参数化 CAD
edu-agent	数学/科学题秒变分步讲解视频（纯技能，无 MCP）

Step 2：配置 API 密钥

视觉问答、OCR、定位、语音识别等工具依赖DASHSCOPE_API_KEY（阿里云 DashScope 控制台申请）；网页搜索类工具需要SERPER_API_KEY。两种写法任选：导出为环境变量，或运行bash install.sh configure把密钥写进统一的~/.qwen-mm-plugins/config——这个文件所有 harness 都会读，GUI 里启动的智能体也能生效（优先级：环境变量 > 配置文件）。

Step 3：运行自检

bash install.sh verify

或直接对核心模块做系统检查：

python3 src/capabilities/core/qwen_mm_plugins_core --check-system

不想用交互式安装器？手动路线也不复杂：先scripts/dev-install.sh core做可编辑安装，再把技能软链到~/.claude/skills/，用claude mcp add注册 MCP 服务器即可。

两种安装方式怎么选

方式	适用场景	上手成本
引导式bash install.sh	有插件市场的智能体（Claude Code 等）	⭐ 最低，菜单点选即可
手动dev-install.sh+mcp add	无插件市场的环境	中等，命令逐个敲
让 agent 自己装	GUI 类工具（QwenWork 等）	⭐ 最低，直接说"帮我装一下 core 插件"

新手最常踩的 3 个坑

坑 1：装完工具调不动→ 多半是密钥没配或没生效。先跑bash install.sh verify看DASHSCOPE_API_KEY是否就位；想确认工具已注册，可以用tools/list协议直接问 MCP 服务器。

坑 2：视频处理又慢又卡→ 抽帧太多拖慢速度。调小QWEN_MM_MAX_TOTAL_FRAMES（默认 600），或把QWEN_MM_FFMPEG_TIMEOUT（默认 120 秒）改短。

坑 3：图表中文全变方块→ 系统缺中文字体。sudo apt install fonts-noto-cjk装字体，再用MATPLOTLIBRC指向自定义的 matplotlib 配置。

进阶：这些模块值得继续挖

• 长视频问答：src/capabilities/video-memory/——两小时讲座也能按时间点精准检索
• 3D 建模：src/capabilities/blender/——22 个工具驱动运行中的 Blender
• 教学视频生成：src/capabilities/edu-agent/——拍一道数学题，直接产出分步讲解视频

完整文档在docs/zh/，每个能力的工具清单与实战案例在cookbooks/。挑一个你最头疼的场景，克隆项目照着做，10 分钟后你的智能体就不再是"文盲"了。🚀

【免费下载链接】Qwen-MM-PluginsMake any agent harness multimodal-native.项目地址: https://gitcode.com/gh_mirrors/qw/Qwen-MM-Plugins