Perceptron — Vision SDK

文档：https://docs.perceptron.inc/

通过 Perceptron Python SDK 进行图像与视频分析。可直接传入文件路径或 URL，SDK 会自动处理 base64 编码转换。

环境准备

pip install perceptron
export PERCEPTRON_API_KEY=ak_...

快速参考

Python SDK

from perceptron import configure, detect, caption, ocr, ocr_markdown, question

# 配置（或通过环境变量 PERCEPTRON_API_KEY 设置）
configure(provider="perceptron", api_key="ak_...")

# 视觉问答（最常用操作）
result = question("photo.jpg", "这张图中正在发生什么？")
print(result.text)

# 定位式问答（返回带边框坐标的答案）
result = question("photo.jpg", "损伤在哪里？", expects="box")
for box in result.points or []:
    print(f"{box.mention}: ({box.top_left.x},{box.top_left.y}) → ({box.bottom_right.x},{box.bottom_right.y})")

# 目标检测
result = detect("warehouse.jpg", classes=["forklift", "person"])
for box in result.points or []:
    print(f"{box.mention}: ({box.top_left.x},{box.top_left.y}) → ({box.bottom_right.x},{box.bottom_right.y})")

# OCR
result = ocr("receipt.jpg", prompt="提取总金额")
print(result.text)

result = ocr_markdown("document.png")  # 结构化 Markdown 输出
print(result.text)

# 图像描述
result = caption("scene.png", style="detailed")
print(result.text)

DSL 组合（高级用法）

构建自定义多模态工作流：

from perceptron import perceive, image, text, system

@perceive(expects="box", model="isaac-0.2-2b-preview")
def find_hazards(img_path):
    return [system("BOX"), image(img_path), text("定位所有安全隐患")]

result = find_hazards("factory.jpg")

结构化输出

将响应约束为 Pydantic 模型、JSON Schema 或正则表达式格式：

from perceptron import perceive, image, text, pydantic_format
from pydantic import BaseModel

class Scene(BaseModel):
    objects: list[str]
    count: int

@perceive(response_format=pydantic_format(Scene))
def count_objects(path):
    return image(path) + text("列出所有物体并统计数量。返回 JSON 格式。")

result = count_objects("photo.jpg")
scene = Scene.model_validate_json(result.text)

像素坐标转换

所有空间类输出均使用归一化坐标（范围 0–1000）。可转换为像素坐标：

pixel_boxes = result.points_to_pixels(width=1920, height=1080)

# 或独立调用：
from perceptron import scale_points_to_pixels
pixel_pts = scale_points_to_pixels(result.points, width=1920, height=1080)

CLI 脚本

脚本位置：/scripts/perceptron_cli.py

需设置 PERCEPTRON_API_KEY 环境变量。provider 固定为 perceptron。

P=/scripts/perceptron_cli.py

# 视觉问答
python3 $P question photo.jpg "你看到了什么？"
python3 $P question photo.jpg "车在哪里？" --expects box

# 目标检测
python3 $P detect photo.jpg --classes person,car
python3 $P detect photo.jpg --classes forklift --format json --pixels
python3 $P detect ./frames/ --classes defect  # 批量处理目录

# OCR
python3 $P ocr document.png
python3 $P ocr receipt.jpg --output markdown

# 图像描述
python3 $P caption scene.png --style detailed

# 自定义 perceive
python3 $P perceive frame.png --prompt "描述该场景" --expects box

# 批量处理
python3 $P batch --images img1.jpg img2.jpg --prompt "描述" --output results.json

# 解析原始模型输出
python3 $P parse "" --mode points

# 列出可用模型
python3 $P models

模型

可在任意 SDK 调用中通过 model="..." 参数覆盖，或在 CLI 中使用 --model ... 参数指定。

定位能力（expects 参数）

视频分析

使用 ffmpeg 提取关键帧后进行分析：

# 提取视频第 5 秒处的单帧
ffmpeg -ss 5 -i video.mp4 -frames:v 1 -q:v 2 /tmp/frame.jpg

# 然后分析该帧
python3 $P question /tmp/frame.jpg "正在发生什么？"

如需持续监控，请提取多个帧并批量处理。

参考文档

如需深入使用 SDK，请按需查阅以下参考文件：

• references/capabilities.md —— 聚焦模式（Focus mode）、推理能力、流式响应、上下文学习（ICL）、结构化输出、标注类型
• references/prompting.md —— 各类任务的最佳提示词（Prompt）、视觉提示（BOX）、温度参数指南
• references/api.md —— SDK 配置选项、模型列表、图像格式支持、流式响应、最佳实践