AOVIS AWS AI 架构权威文档

本文档面向所有 AI 工具（Claude Code / DeepSeek / Gemini / OpenCode / Codex 等）。任何关于 AOVIS 云存 AI / Bedrock / Rekognition / Nova / Claude / Gemini / 视频分析 / 实时推送 / 缩略图分类的讨论，先读本文档，再去看代码。

0. Source of truth

Source	位置	权威性
AWS SA 官方架构指南 PDF	`~/Library/CloudStorage/OneDrive-Personal/IP Camera/AWS KVS/AOVIS — AWS 技术快速上手指南.pdf`（王红力 SA 编写，陈水生 SA Manager 审核，2026-05-08）	最高 — 任何决策与此冲突必须停下确认
测试床 handoff	`/Users/guorui/Projects/cloud-ai-api-test/docs/TEST_ENV_HANDOFF.md`	测试床设计与执行规范
Bedrock 模型可用性	`aws bedrock list-foundation-models --region us-east-1`	运行时事实
既有 AI 代码	`lib/aws/bedrock.ts` + `lib/aws/bedrock-embedding.ts` + `lib/aws/opensearch.ts`	已实现能力

1. 整体架构（来自 AWS SA PDF）

┌─────────────────────────────────────────────────────────────────┐
│ AWS 云端（全托管）                                                │
│                                                                 │
│  ┌────────────┐    ┌────────────────┐    ┌────────────────┐    │
│  │ IoT Core   │    │ KVS Streams    │    │ KVS WebRTC     │    │
│  │ 设备管理    │    │ 录像存储+回放    │    │ 实时预览+对讲    │    │
│  │ MQTT消息   │    │ HLS/GetClip    │    │ P2P + TURN托管 │    │
│  └─────┬──────┘    └───────┬────────┘    └───────┬────────┘    │
│        │                   │                     │             │
│        └──────────┬────────┴─────────────────────┘             │
│                   │ IoT Credentials Provider                    │
│                   │ (设备统一获取临时凭证)                        │
│                   ▼                                             │
│   ┌──────────┐  ┌─────────────┐  ┌────────────────┐            │
│   │ Cognito  │  │ Lambda      │  │ SNS Push       │            │
│   │ 用户认证  │  │ AI 分类+推送 │  │ APNs / FCM     │            │
│   └────┬─────┘  └─────────────┘  └────────────────┘            │
└────────┼────────────────────────────────────────────────────────┘
         │
         ▼
   ┌─────────┐  ← Cognito 凭证直接访问 ──→  ┌──────────────┐
   │ App/Web │                              │ KVS 回放      │
   │         │  ← Cognito 凭证直接连接 ──→  │ KVS WebRTC   │
   └─────────┘                              └──────────────┘
   
   ┌─────────┐
   │ 设备     │ ── X.509 证书 MQTT 直连 IoT Core
   │ (T32VN) │ ── 临时凭证直传 H.265 视频到 KVS Streams
   │         │ ── 临时凭证直连 KVS WebRTC Signaling
   └─────────┘

唯一自研后端代码：1 个 Lambda 函数（Python，几十行）— AI 分类 + 路由到 SNS。 所有其他能力走 AWS 托管服务，不引入自建微服务。

2. 两条 AI 链路

AOVIS 有两条互补、不竞争的 AI 链路。

链路 A：实时事件推送（AWS SA 主推方案）

NEXA Prime 4K (T32VN, 4K H.265)
  ↓ 边端 SoC 已有人/车/宠物/包裹识别（准确率偏低）+ 抓事件缩略图
  ↓ IoT MQTT 上传 (缩略图 JPEG + 事件元数据)
  ↓
IoT Rule → Lambda
  ↓ Bedrock InvokeModel  
  │   Model: us.amazon.nova-lite-v1:0  (cross-region inference profile)
  │   Input: 1-3 张事件缩略图 JPEG
  │   Output: 4 类分类 (Person/Vehicle/Pet/Package) + 置信度
  ↓
SNS Publish → APNs (iOS) / FCM (Android) → 用户手机 Push

目标延迟：<2 秒
目标成本：~$0.00005 / event

关键点：

输入是 JPEG 缩略图，不是视频——彻底绕开视频 codec 问题
边端粗分类用于触发上行；云端 Nova Lite 做"提高准确率的二次确认"
缩略图 1-3 张即可（更多帧对分类任务边际效益低）

链路 B：深度事件摘要

触发：用户打开 App 查看事件 / Daily Summary 定时任务 / Smart Search 重排索引
  ↓
KVS GetClip(eventTime ± Ns, max 5 min) → S3 clips/{aoviseDeviceId}/{eventId}.mp4
  ↓
Bedrock InvokeModel
  │   Model: us.amazon.nova-lite-v1:0 (主) 或 us.amazon.nova-pro-v1:0 (按需升级)
  │   ⚠️ Claude on Bedrock 对 AOVIS 账户 geo-restricted 不可用（2026-05-17 实测，详见 §3.7）
  │   Input: S3 视频 URI（H.265 直吃无需 transcode，verified）
  │   Output: English narrative (140 chars push 友好) + event_type + tags + confidence
  │   实测延迟: Nova Lite/Pro 同为 ~4.5s 端到端
  │   实测成本: Nova Lite $0.000196/event vs Nova Pro $0.002582/event（13x 差距）
  ↓
写 PostgreSQL CloudEvent.aiSummary
  ↓ Bedrock Titan Embedding
OpenSearch 索引（支持 Smart Search 语义检索）

目标延迟：数秒-数十秒
目标成本：~$0.001-0.005 / event

已实现位置：lib/aws/bedrock.ts → analyzeVideo(s3Uri)（手动触发，由 /api/ai/summary 调用）。待补：(a) 自动触发（IoT 事件 → 自动跑 analyzeVideo）；(b) CloudEvent 表的 Prisma model；(c) DailySummary 表与定时聚合。

3. 关键技术决策

3.1 不使用 Amazon Rekognition

AWS SA PDF 中 AI 服务只有 Bedrock，没有 Rekognition。理由：

Rekognition Video (Stored) 仅支持 H.264，与 AOVIS 设备 H.265 输出不兼容
Rekognition 输出是固定词表的结构化标签，不输出自然语言；对 push notification 用户体验不友好
Nova Lite 看缩略图就能做"4 类分类"，比 Rekognition Streaming Video Events 成本低一个数量级、架构简单
Nova Pro / Claude / Gemini 在 NEXA Prime 4K 户外场景下能直接出 English narrative，不需要 Rekognition labels 作为中间层

AI 工具切记：不要再设计 "Rekognition Streaming Video Events" / "Rekognition 标签 + Bedrock 摘要组合" 等路径，AOVIS 架构里没这个东西。任何包含 Rekognition 的代码或文档讨论，先停下回到本节确认必要性。

3.2 设备 codec = H.265，KVS 全链路支持

设备 SoC = Ingenic T32VN（NX/ZX/P 按供应链选型）
视频编码 = H.265 (HEVC) — 行业现状决定（4K + 太阳能 + 4G LTE 场景下 H.264 已不可选；H.265 同画质省 30-50% 带宽）
AWS SA PDF §一表格"参考示例代码 (H.264/H.265/P2P)"明示 KVS Producer Embedded C SDK / KVS WebRTC C SDK 都支持 H.265
KVS HLS / DASH 自 2019 年起原生支持 H.265 (AWS 2019-07 announcement)

KVS MediaType 字段事实（2026-05-17 verified via AWS docs）:

MediaType 是描述性 metadata，不强校验，仅作消费方提示
HLS / GetClip 实际读 Matroska track header (V_MPEG/ISO/HEVC)，不读 MediaType
但 AWS Console 视频预览依赖 MediaType；声明错值会导致 Console 看不了视频，运维监控会误判
可通过 UpdateStream 在线修改，无需 delete+recreate

lib/aws/kvs.ts:39 修复要求：

当前 hardcode MediaType: "video/h264" 是 NEXA Prime 4K 正式上线前必修项
改为 MediaType: "video/h265" （或读 env.kvsMediaType 默认 video/h265 以便将来灵活配）
现存生产账户 (288669178338) 的 2 条 stream (aovis-stream-aovis-n4k-000001 / 000002) 是 2026-05 样机出来前的模拟流，与真实设备无关，可忽略或随手删除

Bedrock Nova Lite 对 H.265 视频的支持（2026-05-17 verified）：

✅ us.amazon.nova-lite-v1:0 直接消费 HEVC 视频（S3 s3://aovis-video-storage/ai-lab/inputs/AOVIS_test_short_00001.mp4，ffprobe 确认 codec=hevc）
端到端 4.9 秒拿到 valid JSON，$0.000195/event
生产链路 B 不需要 MediaConvert / Lambda+ffmpeg 转码流水线——节省数千美金/月运营开销
Nova Pro / Claude Sonnet 4.5 / Claude Haiku 4.5 对 H.265 的支持待 P2/P3 实测，但官方文档表明 Bedrock 视频 API 后端统一处理 codec，预期同样兼容

3.3 AI 输出语言 = English only

aovis 服务美国市场。所有面向用户的 AI 输出（push notification、Daily Summary、App 内 narrative）统一 English，不做中文/双语字段。

落到代码：

Bedrock system prompt 统一约束 Write in concise English suitable for a mobile push notification.
Prisma schema 中 summary 单字段，不要 summary_zh / summary_en 双列
event_type 用 snake_case English（如 vehicle_entry, person_loitering）
开发者文档可中文；用户对外文本必须 English

3.4 云存 retention 双层架构

两层独立机制，不要混淆：

层	谁负责	数值	作用域
L1 物理保留	S3 lifecycle + KVS retention	30 天 = 720h	`clips/` 前缀 + KVS 流
L2 应用层访问窗口	Entitlement	local 0d / starter 1d / standard 7d / premium 30d	API 查询时校验

lib/cloud-storage-retention.ts: TARGET_KVS_RETENTION_HOURS = 720
lib/cloud-storage-plans.ts: 套餐 retentionDays 配置
lib/cloud-access-window.ts: L2 校验，返回 time_range_exceeds_entitlement
S3 lifecycle 按 Filter.Prefix 物理隔离：新加前缀（如 ai-lab/, thumbnails/）配独立规则不会影响生产 clips/
加新套餐若 retentionDays > 30 → 必须同步抬高 L1，否则物理删除会先于应用层窗口到期

3.7 Claude on Bedrock 对 AOVIS 账户 geo-restricted，只能用 Nova

2026-05-17 实测：AOVIS 生产账户 288669178338 调 us.anthropic.claude-haiku-4-5-* / us.anthropic.claude-sonnet-4-5-* 全部返回：

ValidationException: ... unsupported countries/regions/territories

inference profile 状态 ACTIVE 但 Anthropic 仍拒绝。这是账户注册国别问题，不是技术问题。

落到架构：AOVIS 所有 AI 调用只用 Nova 系列（亚马逊自家模型，不受此限制）：

链路 A: us.amazon.nova-lite-v1:0 （主，看缩略图分类）
链路 B: us.amazon.nova-lite-v1:0 主 / us.amazon.nova-pro-v1:0 按需升级

不要做的事：

不要给 AOVIS 写 us.anthropic.claude-* 调用代码
不要在 prompt 工程时假设可以"切到 Claude 看效果"
不要在 fallback / failover 设计里把 Claude 当 backup

未来如确实需要 Claude：

选项 A：走 Anthropic direct API（不经 Bedrock），单独 vendor 账单
选项 B：注册支持国家的新 AWS 账号承担这部分 workload
现阶段两个都不做——Nova Lite/Pro 覆盖足够

3.6 Bedrock model id 必须用 cross-region inference profile（`us.` 前缀）

us-east-1 区域 Nova 系列 + Claude 4.x 系列强制走 cross-region inference profile。直接用 foundation model id（无前缀）会触发：

ValidationException: To access Amazon Bedrock, you must provide further information
so we can verify you are a corporate customer and that we can grant you access
given applicable law and internal policy.

这个错误信息严重误导——看上去是 enterprise allowlist / 合规问题，实际只是 model id 格式错。

❌ 错的	✅ 对的
`amazon.nova-lite-v1:0`	`us.amazon.nova-lite-v1:0`
`amazon.nova-pro-v1:0`	`us.amazon.nova-pro-v1:0`
`anthropic.claude-sonnet-4-5-20250929-v1:0`	`us.anthropic.claude-sonnet-4-5-20250929-v1:0`
`anthropic.claude-haiku-4-5-20251001-v1:0`	`us.anthropic.claude-haiku-4-5-20251001-v1:0`

落到代码：

lib/aws/bedrock.ts 用 env.bedrockModelId，确认 .env 里这个变量值带 us. 前缀
任何新的 Bedrock 调用代码，model id 都必须带 us. 前缀
报 ValidationException: must verify corporate customer 时，第一反应检查 model id 格式，不要去提 AWS Support 工单

查可用 inference profile：

aws bedrock list-inference-profiles --region us-east-1 \
  --query 'inferenceProfileSummaries[?contains(inferenceProfileId, `nova`) || contains(inferenceProfileId, `claude`)].inferenceProfileId'

3.5 订阅与 AI feature 等价分发

所有付费档（starter / standard / premium）解锁同一组 AI feature (ai_summary, smart_search)；差异只在 cloud_playback 配额（retention 1/7/30 天）。 没有"高级 AI 套餐"——架构层不需要为 AI feature 做分层 gate。

4. 当前实现状态（盘点）

组件	状态	位置
KVS Streams	✅ 实现	`lib/aws/kvs.ts` — ⚠️ `MediaType: "video/h264"` 需在样机上线前改为 `video/h265`（§3.2）
KVS WebRTC	✅ 实现	`lib/aws/kvs-webrtc.ts`
KVS GetClip → S3	✅ 实现	`lib/aws/kvs.ts`
IoT Core 设备注册	✅ 实现	`lib/aws/iot-core.ts`
IoT 事件 webhook	✅ 实现	`app/api/internal/aws/iot-event/route.ts`（IotEvent 表 + HMAC）
Bedrock analyzeVideo (Nova Pro/Lite 看视频)	✅ 实现，手动触发	`lib/aws/bedrock.ts`
Bedrock embedding	✅ 实现	`lib/aws/bedrock-embedding.ts`
OpenSearch Smart Search	✅ 实现	`lib/aws/opensearch.ts`
SNS Push 代码	⚠️ 写好，SNS_TOPIC_ARN 未配置 = 休眠	`lib/aws/sns.ts`
链路 A: Nova Lite 看缩略图分类	❌ 未实现	测试床 `cloud-ai-api-test` 验证中
链路 A: Lambda (IoT Rule → AI 分类)	❌ 未实现	需要新 Lambda 函数
链路 B: 自动触发（事件到达 → 自动 analyzeVideo）	❌ 未实现	需要在 IoT webhook 后挂 async worker
Prisma: CloudEvent / PushToken / DailySummary	❌ 未实现	测试床定型后 migration
Daily Summary 定时聚合	❌ 未实现	EventBridge Scheduler 或 Vercel Cron
SNS Platform Application (APNs/FCM endpoint-based)	❌ 未实现	现有 `lib/aws/sns.ts` 是 Topic-based，需重做 endpoint-based
Bedrock model id 必须用 `us.` 前缀	⚠️ verify `env.bedrockModelId` 当前值	us-east-1 强制 cross-region inference profile，直调 foundation model 报误导性 ValidationException。详见 §3.6

5. 关联项目与外部依赖

项目/资源	用途	位置
cloud-ai-api-test	AI 模型横向评测床（PA / P2 / P3 / P5）	`/Users/guorui/Projects/cloud-ai-api-test/`
AWS SA PDF	架构 source of truth	`~/Library/CloudStorage/OneDrive-Personal/IP Camera/AWS KVS/AOVIS — AWS 技术快速上手指南.pdf`
Bedrock InvokeModel allowlist 工单	Case 177898222100371（2026-05-17 提交，实际无阻塞，可忽略或关闭——见 §3.6）	https://support.console.aws.amazon.com/support/home#/case/?displayId=177898222100371
AWS 账户	288669178338（与生产同账号）	`~/.aws/credentials` default profile
主要区域	us-east-1	KVS、Bedrock、S3 全部
S3 bucket	`aovis-video-storage`	生产 `clips/` / `thumbnails/` / `archive/` + 测试床 `ai-lab/`（独立 lifecycle 7 天）

6. 给 AI 工具的执行指引

收到任何 AOVIS 云存 / AI / Bedrock / Nova / Claude / 视频分析 / 推送相关任务时，按以下顺序处理：

先读本文档 §1-§3，确认架构边界
看 §4 盘点，确认你要做的事是"补未实现"还是"改已实现"
如果工作涉及 Bedrock InvokeModel，先看 §5 工单状态（未批准前任何 InvokeModel 都会 ValidationException）
如果设计涉及 Rekognition：停下，回到 §3.1 确认是否真的需要——95% 的情况下不需要
如果设计要做 Daily Summary / 用户对外文案 / Prisma schema：必须 English-only（§3.3）
如果设计涉及 retention 配置：必须区分 L1/L2 两层（§3.4）
测试床（cloud-ai-api-test）跑出来的 prompt 模板和模型选型结论，是把 lib/aws/bedrock.ts 改进的依据；改之前先看测试床 reports/ 下的最新对比报告

禁止行为：

凭通用 IPC / 安防 AI 行业经验脑补架构（已经踩过几次坑）
引入 Amazon Rekognition 服务到任何新代码或新文档
在面向最终用户的输出里写中文
把 KVS_DATA_RETENTION_HOURS=720 这种 L1 常量泄漏到应用层 entitlement 判定

文档版本: v1.0 (2026-05-17) 维护: 任何架构变化必须同步更新本文档；以本文档为准而非散落在各 design doc 的描述 实施规划: 见 ai-push-pipeline-implementation-plan.md — Sprint 1 / Sprint 2 / Sprint 3 的逐任务清单

0. Source of truth​

1. 整体架构（来自 AWS SA PDF）​

2. 两条 AI 链路​

链路 A：实时事件推送（AWS SA 主推方案）​

链路 B：深度事件摘要​

3. 关键技术决策​

3.1 不使用 Amazon Rekognition​

3.2 设备 codec = H.265，KVS 全链路支持​

3.3 AI 输出语言 = English only​

3.4 云存 retention 双层架构​

3.7 Claude on Bedrock 对 AOVIS 账户 geo-restricted，只能用 Nova​

3.6 Bedrock model id 必须用 cross-region inference profile（us. 前缀）​

3.5 订阅与 AI feature 等价分发​

4. 当前实现状态（盘点）​

5. 关联项目与外部依赖​

6. 给 AI 工具的执行指引​