AI Demos：用最小化脚本揭开视觉 AI 的黑箱

利用视觉语言模型自动读取表单复选框，并标注出每一项的勾选状态与标签。

---

从"这效果太炫酷了"到"原来这么简单"

你在刷 X（Twitter）或 LinkedIn 时，是否经常看到这样的 AI 演示——"上传一张照片，AI 自动标出里面的所有人、汽车、自行车""拍一张表格，AI 读取所有复选框的状态"。你心里会想：这技术含量一定很高吧？

AI Demos 这个项目用实际行动告诉你：这些效果，用几百行 Python 代码就能实现。

作者 Maziyar Panahi 是医疗 AI 开源项目 OpenMed 的创始人（OpenMed 拥有超过 5000 star，是本地化临床 AI 领域的标杆项目）。他创建 AI Demos 的目的很简单：把社交媒体上那些"看起来不可能"的 AI 演示，拆解成每个人都能理解、运行和改造的开源脚本。

---

项目定位：AI 领域的"拆弹手册"

AI Demos 的定位非常独特——它不是一个应用，不是一个框架，而是一本可执行的可视化教程。

每个 demo 都遵循同一个契约：

• Small（小巧）：一个 demo 只解决一个具体问题，不贪多
• Readable（可读）：入口点明确，代码量控制在 200 行以内
• Reproducible（可复现）：copy-paste 即可运行，有明确的预期输出
• Portable（可移植）：使用标准接口而非特定 SDK
• Hackable（可改造）：核心的 prompt、schema 和渲染逻辑极易修改

这种设计哲学与市面上大多数"大而全"的 AI 项目形成鲜明对比。它的价值不在于功能多强大，而在于拆解得足够清晰，让学习者真正理解 AI 到底在做什么。

---

核心功能拆解

Demo 1：物体边界框标注（vision/draw-object-boxes）

这是整个项目最经典的 demo。输入一张照片和一组标签（如 "person, car, bicycle"），输出是一张标注了所有目标边界框的图片。

工作流程：

1. 图片以 base64 编码成 data URL，随文字 prompt 一起发给视觉语言模型
2. 模型返回严格 JSON Schema 格式的检测结果，包含标签名和归一化坐标
3. 代码对模型输出做容错解析（JSON 提取、坐标验证、标签白名单过滤）
4. 将 0-1000 归一化坐标转换为像素坐标，用 Pillow 在原图上绘制矩形框和标签

为什么这样做？ 传统的目标检测需要 YOLO、Faster R-CNN 等专用模型，部署复杂。而 AI Demos 告诉你：只需一个支持视觉输入的 LLM，加上正确的 prompt，就能完成类似的任务。这对快速原型验证特别有价值。

Demo 2：表单复选框读取（documents/read-form-checkboxes）

这个 demo 展示了更精细的文档理解能力。输入一张表单图片，输出包含：

• 每个复选框的标签文字（如"上午场"）
• 勾选状态（checked / unchecked / unknown）
• 归一化边界框坐标

然后在原图上用不同颜色标注：绿色代表已勾选，橙色代表未勾选，灰色代表状态不明。

这个 demo 用了 json_schema 严格模式，要求模型必须按照预定义 schema 输出，解决了传统 LLM 输出 JSON 不稳定的问题。

---

技术栈：极简但专业

组件	技术选型	作用
运行时	Python 3.10+	基础运行环境
AI 接口	OpenAI Python SDK (openai>=2.0)	调用 OpenAI 兼容 API
图像处理	Pillow (pillow>=11)	图片加载、标注绘制
推理端点	任意 OpenAI 兼容端点	Ollama、LM Studio、llama.cpp server 等

支持的推理方式（按难度排序）：

• 本地 Ollama（最简单）：export OPENAI_BASE_URL="http://localhost:11434/v1"
• 本地 LM Studio：http://localhost:1234/v1
• 本地 llama.cpp server：http://localhost:8080/v1
• 托管服务（如 OpenRouter）：直接替换 base URL 即可

代码质量评分：7/10

代码结构清晰，类型注解完备，错误处理合理，但缺乏单元测试是主要扣分点。值得注意的是，每个脚本都有完整的命令行参数解析（argparse）和帮助文档，这在 demo 类项目中难得一见。

---

上手体验：真的能跑吗？

爱好者路径：

如果你只是想体验效果，安装过程非常友好。官方 README 提供了逐步指导，只需：

git clone https://github.com/maziyarpanahi/ai-demos.git
cd ai-demos/vision/draw-object-boxes
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
# 配置 Ollama 或其他兼容端点
python detect.py your-photo.jpg --labels "person, car, bicycle"

唯一需要跨过的门槛是：你需要有一个能处理图像输入的视觉语言模型。本地运行推荐 Ollama + qwen2.5-vl 或 llava 系列模型。

开发者路径：

对于想深入研究的开发者，项目提供了标准化的目录结构，每个 demo 都是一个独立的学习单元：

<category>/<outcome>/
├── README.md          # 功能说明与运行指南
├── <entry-point>     # 入口脚本
├── requirements.txt  # 直接依赖
└── assets/           # 示例输入输出

---

项目现状与局限

需要正视的问题：

1. star 数极低：目前仅 7 star，项目尚处早期，demo 数量只有 2 个（vision 和 documents 各一），覆盖范围有限
2. 无 Docker 支持：无法容器化快速部署，对非 Python 环境用户不友好
3. 无 Web UI：纯 CLI 工具，普通用户使用门槛相对较高
4. 输出稳定性：依赖视觉模型的 JSON Schema 输出能力，不同模型表现差异较大
5. 隐私风险：文档类 demo 会将图片完整发送到远程 API 端点，不适合处理敏感文件

但这些问题并不致命，因为项目本身就定位为"学习导向"，而非"生产级应用"。

---

行业意义：填补了一个真实的空白

AI 领域从来不缺"超级应用"，但缺的是能把超级应用拆解成教学单元的资源。大多数人看到 AI 演示时，要么惊叹"太神奇了"，要么放弃"这太复杂了"。AI Demos 的出现，让这个中间地带有了可操作的工具。

作者 Maziyar Panahi 的背景也值得关注——他是 OpenMed（本地化医疗 AI，5000+ star）的创始人，在开源社区有良好口碑。他选择用 AI Demos 来补充 OpenMed 的学习生态，形成了从"理解原理"到"动手实践"的完整闭环。

随着 demo 数量持续增长（项目规划覆盖 vision、audio、documents、agents、video、text-and-code 六大方向），这个项目有望成为 AI 入门者从"观众"变"玩家"的第一站。

---

总结

维度	评分
创新性	★★★★☆（定位独特，教学价值高）
代码质量	★★★☆☆（代码清晰但无测试）
部署难度	★★☆☆☆（纯 CLI，需手动配置环境）
社区活跃度	★★☆☆☆（star 极少，demo 数量少）
学习价值	★★★★★（拆解彻底，易于改造）

如果你是一个想真正理解 AI 模型在做什么的开发者，或者一个想快速验证 AI 概念的爱好者，AI Demos 是目前 GitHub 上最干净、最诚实的起点之一。虽然它还很"小"，但方向对了。