Dahua AI Device Image Analysis

调用大华云平台大模型进行图像分析。完整的抓图→AI 分析流程！

完整功能

本技能提供端到端的大华云图像分析服务:

✅ 设备抓拍 - 实时拍摄监控摄像头画面
✅ 本地保存 - 抓拍图片自动下载到本地
✅ AI 分析 - 调用大华云大型模型进行智能分析
✅ 零冗余配置 - 仅需 Cloud 凭证（ProductId、AK、SK）即可，无多余参数
✅ 图形界面支持 - Windows GUI 方式设置环境变量

配置凭证

需要设置 Cloud 凭证（ProductId、AK、SK）！

方式 1: 图形界面设置 (Windows GUI)

最适合初学者和不想用命令行的用户！

步骤 1: 打开系统设置

按下 Win + R 键，输入 sysdm.cpl 并回车
或者右键点击"此电脑" → "属性" → "高级系统设置"

步骤 2: 进入环境变量设置

在弹出的"系统属性"窗口中，切换到 "高级" 选项卡
点击底部的 "环境变量(N)..." 按钮

步骤 3: 创建用户环境变量

在 "当前用户的变量(U)" 区域（窗口上半部分），点击 "新建(W)..."：

变量名	变量值	说明
`DAHUA_CLOUD_PRODUCT_ID`	你的 AppID	应用 ID
`DAHUA_CLOUD_AK`	你的 AccessKey	访问密钥
`DAHUA_CLOUD_SK`	你的 SecretKey	保密密钥

示例:

变量名：DAHUA_CLOUD_PRODUCT_ID
变量值：138XXXX731

变量名：DAHUA_CLOUD_AK  
变量值：196XXXXXXXXXXXXX808

变量名：DAHUA_CLOUD_SK
变量值：naumXXXXXXXXXXXXXXXXyHxh

步骤 4: 确认并保存

每个变量都点击 "确定" 保存
关闭所有窗口
重要: 重新打开命令行窗口才能生效

快速截图指引

如果需要更详细的图文教程，请参考以下操作要点:

确保在"用户变量"区域添加，而非"系统变量"
变量名必须完全一致（区分大小写）
变量值不要有多余空格
添加完成后需要重启终端

方式 2: 命令行快速设置

适合熟悉命令行的用户！

Windows PowerShell (推荐 - 用户级别):

[Environment]::SetEnvironmentVariable("DAHUA_CLOUD_PRODUCT_ID", "your_app_id", "User")
[Environment]::SetEnvironmentVariable("DAHUA_CLOUD_AK", "your_access_key", "User")
[Environment]::SetEnvironmentVariable("DAHUA_CLOUD_SK", "your_secret_key", "User")

Linux/Mac (当前会话临时):

export DAHUA_CLOUD_PRODUCT_ID='your_app_id'
export DAHUA_CLOUD_AK='your_access_key'
export DAHUA_CLOUD_SK='your_secret_key'

⚠️ 安全建议: 避免将凭证写入 ~/.bashrc、~/.zshrc 等启动文件进行长期存储，以防凭证泄露。建议优先使用 Windows 用户环境变量或临时的当前会话导出方式。

方式 3: 命令行临时设置

适合快速测试！

Windows PowerShell (临时):

$env:DAHUA_CLOUD_PRODUCT_ID='your_app_id'
$env:DAHUA_CLOUD_AK='your_access_key'
$env:DAHUA_CLOUD_SK='your_secret_key'

注意: 仅在当前窗口有效，关闭后失效

验证环境变量是否生效

Linux/Mac:

echo $DAHUA_CLOUD_PRODUCT_ID
echo $DAHUA_CLOUD_AK
# 注意：不要打印 SK，避免泄露

Windows PowerShell:

$env:DAHUA_CLOUD_PRODUCT_ID
$env:DAHUA_CLOUD_AK

快速开始

基本使用

python device_image_analysis.py \
  --device-sn BA5918431 \
  --prompt "请判断这张图片中是否有人"

完整示例

# 抓拍并调用 AI 分析（仅需要 Cloud 凭证）
python device_image_analysis.py \
  -d BA5918431 \
  -p "请判断图片中是否有白色轿车。回答格式：有{是} 或 无{否}" \
  -c 0

Python SDK 调用

from device_image_analysis import analyze_device_camera

result = analyze_device_camera(
    device_sn="BA5918431",
    prompt="请判断图中是否有人玩手机",
    channel_no=0
)

print(f"Analysis Result: {result['analysis']['result']}")

工作流程

┌─────────────┐
│ 1. 获取 Cloud Token │
│   (AppAccessToken)  │
└──────┬──────┘
       ▼
┌─────────────┐
│ 2. 设备抓图    │
│   setDeviceSnapEnhanced │
└──────┬──────┘
       ▼
┌─────────────┐
│ 3. 等待 OSS    │
│   URL 生效(1s) │
└──────┬──────┘
       ▼
┌─────────────┐
│ 4. 下载保存    │
│   图片到本地   │
│   (支持5次重试) │
└──────┬──────┘
       ▼
┌─────────────┐
│ 5. 调用 AI 分析   │
│   imageAnalysis API │
└──────┬──────┘
       ▼
┌─────────────┐
│ 6. 返回结果    │
│   含分析内容和本地路径    │
└─────────────┘

响应格式

{
    "success": True,
    "device_sn": "BA5918431",
    "channel_no": 0,
    "image_url": "https://oss-cn-hangzhou.aliyuncs.com/...",
    "local_image_path": "./captured_images/BA5918431/ch0_1234567890.jpg",
    "analysis": {
        "success": True,
        "code": "200",
        "message": "操作成功",
        "data": {"content": "图中有 2 个人"},
        "result": "图中有 2 个人"
    }
}

使用场景

1️ 人员检测

python device_image_analysis.py \
  -d YOUR_SN \
  -p "图中是否有人？请回答'有'或'无'"

2️ 车辆识别

python device_image_analysis.py \
  -d YOUR_SN \
  -p "图中有多少辆车？分别是什么颜色？"

3️ 异常行为检测

python device_image_analysis.py \
  -d YOUR_SN \
  -p "图中是否有打架、摔倒等异常情况？"

4️ 物体识别

python device_image_analysis.py \
  -d YOUR_SN \
  -p "识别图中的主要物体，按重要性排序"

技术细节

API 端点

端点	路径	说明
认证	`/open-api/api-base/auth/getAppAccessToken`	获取 AppAccessToken
抓图	`/open-api/api-iot/device/setDeviceSnapEnhanced`	设备实时抓图
AI 分析	`/open-api/api-ai/largeModelDetect/imageAnalysis`	大模型图像分析

认证机制

SHA512 HMAC 签名 - 两种签名方式：
- get_token_sign() - 获取 Token 签名 (access_key + timestamp + nonce)
- business_api_sign() - 业务 API 签名 (access_key + app_access_token + timestamp + nonce)
AppAccessToken 自动刷新 - 1 小时有效期，自动管理
依赖 Cloud 凭证 - 使用 ProductId、AccessKey、SecretKey 进行认证

代码架构

┌─────────────────────────────────────────────────────────────┐
│                    常量配置层 (Constants)                      │
│  - API 端点、超时时间、环境变量名                               │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                    工具函数层 (Utilities)                      │
│  - get_token_sign()          获取Token签名                    │
│  - business_api_sign()       业务API签名                      │
│  - verify_image_url_accessible()  URL可访问性验证(备用)        │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                 DahuaSnapshotClient 类                       │
│  - get_app_access_token()    获取/刷新 Token                 │
│  - capture_snapshot()        设备抓图                       │
│  - download_and_save()       图片下载保存(含1s等待+5次重试)   │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│                   AI 分析函数层                               │
│  - analyze_with_dahua_ai()   调用大模型分析                   │
│  - analyze_device_camera()   完整流程封装                     │
└─────────────────────────────────────────────────────────────┘

核心函数说明

`analyze_device_camera(device_sn, prompt, channel_no=0)`

完整的图像分析流程封装函数。

参数:

参数	类型	必填	说明
`device_sn`	`str`	✅	设备序列号 (SN)
`prompt`	`str`	✅	AI 分析问题
`channel_no`	`int`	❌	通道号 (默认：0)

返回值: Dict[str, Any]

{
    "success": True,           # 整体成功状态
    "device_sn": "BA5918431",  # 设备序列号
    "channel_no": 0,           # 通道号
    "image_url": "...",        # 图片 URL
    "local_image_path": "...", # 本地保存路径
    "analysis": {              # AI 分析结果
        "success": True,
        "code": "200",
        "message": "操作成功",
        "data": {"content": "..."},
        "result": "..."
    }
}

请求头结构

认证请求头 (获取 Token):

{
    "Content-Type": "application/json",
    "AccessKey": access_key,
    "Timestamp": timestamp,
    "Nonce": nonce,
    "X-TraceId-Header": trace_id,
    "Sign": signature,           # get_token_sign() 生成
    "ProductId": app_id,         # DAHUA_CLOUD_PRODUCT_ID
    "Version": "V1",
    "Sign-Type": "simple"
}

业务请求头 (抓图/AI分析):

{
    "Content-Type": "application/json",
    "AccessKey": access_key,
    "Timestamp": timestamp,
    "Nonce": nonce,
    "X-TraceId-Header": trace_id,
    "Sign": signature,           # business_api_sign() 生成
    "Version": "V1",
    "Sign-Type": "simple",
    "AppAccessToken": app_token, # 获取Token后传入
    "ProductId": app_id          # DAHUA_CLOUD_PRODUCT_ID
}

可配置常量

常量名	默认值	说明
`DEFAULT_API_BASE_URL`	`https://open.cloud-dahua.com/`	API 基础地址
`DEFAULT_CHANNEL_NO`	`0`	默认通道号
`TOKEN_EXPIRY_SECONDS`	`3600`	Token 有效期(秒)
`TIMEOUT_AUTH`	`60`	认证超时(秒)
`TIMEOUT_SNAPSHOT`	`60`	抓图超时(秒)
`TIMEOUT_DOWNLOAD`	`300`	下载超时(秒)
`TIMEOUT_ANALYSIS`	`120`	AI分析超时(秒)
`URL_VERIFY_RETRIES`	`3`	URL 验证重试次数
`URL_VERIFY_DELAY`	`1`	URL 验证重试间隔(秒)
`SNAPSHOT_RETRY_DELAY`	`2`	抓拍重试间隔(秒)

命令行参数

参数	简写	类型	必填	说明
`--device-sn`	`-d`	`str`	✅	设备序列号 (SN)
`--prompt`	`-p`	`str`	✅	AI 分析问题
`--channel`	`-c`	`int`	❌	通道号 (默认：0)

依赖要求

Python 3.8+
requests>=2.31.0

安装依赖:

pip install requests

安全提示

不要将真实的 Cloud 凭证提交到 Git!

本项目包含 .gitignore 文件，会自动忽略敏感配置文件。建议：

使用环境变量存储凭证
定期轮换密钥
限制应用权限范围
Windows 用户建议使用 GUI 方式设置（更安全）

目录结构

dahua-cloud-open-device-image-analysis/
├── README.md                         # 说明文件
├── SKILL.md                          # 本文件
├── FAQ.md                            # 常见问题解答
├── device_image_analysis.py # 主程序
├── requirements.txt                  # Python 依赖
└── .gitignore                        # Git 忽略规则

核心优势

✅ 极简配置 - 仅需要 3 个必要参数 (SN, Prompt, Channel)
✅ 代码优化 - 统一的签名/请求头生成，完整类型注解
✅ 可配置 - 超时、重试等参数通过常量统一管理
✅ 跨平台支持 - Windows/Linux/Mac 完美运行
✅ GUI 友好 - Windows 图形界面设置环境变量
✅ 轻量依赖 - 仅依赖 requests 库，单文件实现
✅ 安全可靠 - 标准 API 认证，无密码泄露风险

License

MIT License