# VisionAI 企业级计算机视觉算法平台产品手册

版本：1.0
适用部署：Windows + NVIDIA GPU 开发机、Linux 服务端、纯 CPU 演示环境
文档状态：交付版

## 1. 产品概览

VisionAI 将计算机视觉项目的全部资产和决策放在同一条可追溯链路中：

```text
项目与权限
  → 数据资产
  → CVAT 标注/预标注
  → 不可变数据集版本
  → 训练实验
  → FiftyOne 评估与回归门禁
  → 模型注册与四眼审批
  → 部署修订与在线推理
  → 生产反馈
  → 回流标注与再训练
```

平台对每个异步操作建立作业、尝试记录、领域事件和审计事件。数据集版本、标注修订、模型制品和部署修订均不可变，任何线上结果都能回溯到模型、训练运行、数据集和标注来源。

## 2. 安装与启动

### 2.1 系统要求

- Windows 11 + WSL2 + Docker Desktop，或主流 x86_64 Linux
- Docker Engine 27+，Docker Compose v2.30+
- 最低 8 CPU、16 GB RAM、30 GB 可用磁盘
- GPU 工作负载可选：NVIDIA 驱动、NVIDIA Container Toolkit、支持 CUDA 12 的 GPU
- 默认端口 48080、58080、23316、25672、25673、27316、28000、28080、29000、29001、25151、25152 未被占用

### 2.2 环境诊断

Windows：

```powershell
.\scripts\doctor.ps1
.\scripts\doctor-gpu.ps1  # 仅 GPU 场景
```

Linux：

```bash
./scripts/doctor.sh
./scripts/doctor-gpu.sh   # 仅 GPU 场景
```

### 2.3 一键启动

```bash
docker compose up -d --build --wait
```

或执行 `scripts/bootstrap.ps1` / `scripts/bootstrap.sh`。脚本仅在项目目录中创建 `.env`，不会修改用户已有的系统文件。

首次启动会拉取并构建镜像、执行数据库迁移、创建默认租户和管理员、初始化 MinIO Bucket，并创建 CVAT 管理员。完整栈包含：

| 服务 | 地址 | 用途 |
| --- | --- | --- |
| VisionAI Web | http://localhost:48080 | 统一产品界面 |
| VisionAI API | http://localhost:58080 | 管理与业务 API |
| Swagger | http://localhost:58080/swagger/index.html | OpenAPI 调试 |
| CVAT | http://localhost:28080 | 标注工作台 |
| FiftyOne | http://localhost:25151 | 评估分析工作台 |
| Inference | http://localhost:28000/docs | 在线推理 Provider |
| MinIO Console | http://localhost:29001 | 对象存储管理 |
| RabbitMQ | http://localhost:25673 | 异步事件管理 |

### 2.4 登录

本地默认租户为 `Nimbus Framework`，账号为 `admin / admin123`。CVAT 默认账号为 `visionai / visionai_cvat_dev`。部署到共享环境前必须修改 `.env` 中所有口令和 JWT Secret。

## 3. 角色与权限

平台提供租户级 RBAC，并在业务查询中同时执行租户与项目数据域约束。

| 角色 | 典型职责 |
| --- | --- |
| 平台管理员 | 租户、用户、角色、集成、资源和全局审计 |
| 项目管理员 | 项目配置、成员、配额和全流程管理 |
| 数据工程师 | 资产导入、质量治理、集合与数据集版本 |
| 标注员 | CVAT 标注与任务提交 |
| 复核员 | 标注复核、模型审批；不能审批本人提交 |
| 算法工程师 | 训练模板、实验、评估和模型注册 |
| 部署运维 | 部署、告警、回滚、资源与故障处理 |
| 只读审计员 | 只读查看和审计导出 |

通过“系统管理 → 角色管理”为角色分配菜单和权限；在“项目中心 → 成员”中设置项目角色。所有写操作均记录操作者、租户、项目、Trace ID、对象和时间。

## 4. 黄金路径操作指南

### 4.1 创建项目

进入“VisionAI → 项目中心”，创建项目并选择任务类型。随后配置成员、存储、CVAT、训练 Provider、FiftyOne 和推理 Provider。项目可停用、归档和克隆；克隆只复制配置，不复制敏感凭证。

### 4.2 导入和治理数据资产

进入“数据资产”：

1. 使用浏览器分片上传，或创建服务端目录批量导入任务。
2. 平台计算 SHA-256，重复内容自动去重并建立引用。
3. 查看分辨率、格式、损坏状态和重复率等质量指标。
4. 为资产设置标签，并加入集合。
5. 冻结集合，使其成为可复现的下游输入。

删除分为软删除、恢复和显式清理。存在数据集、标注或模型引用时，平台拒绝物理清理。

### 4.3 标注与预标注

进入“标注任务”：

1. 选择冻结集合并创建任务。
2. 点击“准备”，平台通过 Provider 在 CVAT 创建项目资源并上传预签名媒体。
3. 点击“内嵌 CVAT”，在 VisionAI 全屏工作台中继续标注；顶部始终保留任务编号、类型、状态、刷新、外部打开和“返回 VisionAI”。
4. 可选择已批准模型发起预标注；每次预标注保存覆盖率、接受率和耗时。
5. 完成后同步状态，由复核员批准或驳回。
6. 点击“导出”，平台保存不可变 Annotation Revision、格式、校验和与源 CVAT Task。

CVAT 暂时不可用时，作业按指数退避重试；集成页面会展示同步故障并允许重放。
CVAT 首次使用可能在内嵌区域显示登录页；完成一次登录后，同源会话会继续用于后续任务。平台通过受控 CSP 只允许配置的 VisionAI 来源嵌入 CVAT；共享环境应将 `.env` 的 `VISIONAI_WORKBENCH_ORIGIN` 设置为实际工作台域名。加载异常时可在原弹窗重试，或使用“外部打开”兜底，不丢失 VisionAI 当前任务上下文。

### 4.4 创建数据集版本

进入“数据集注册表”：

1. 创建数据集。
2. 从集合或标注修订创建语义版本。
3. 设置 train/val/test 比例与固定随机种子。
4. 执行校验，修复缺失标注、类别异常、重复或泄漏问题。
5. 冻结版本。

冻结后，Manifest、样本列表、拆分、标注修订和校验和不可修改。版本比较展示样本和类别差异。已被实验或模型引用的版本不能物理删除，只能弃用。

### 4.5 训练实验

进入“训练与实验”：

1. 创建模板及版本，填写镜像、启动命令、参数 Schema、资源需求和输出约定。
2. 运行 Smoke Test；通过后发布模板版本。
3. 选择冻结数据集、模板版本、超参数、队列和资源启动训练。
4. 编排器通过 LocalDocker 或 ClearML Provider 执行。
5. 查看状态、日志、指标、环境快照和权重/报告/日志/指标制品。
6. 克隆运行以复现实验，或对多个运行执行指标对比。

运行记录固定训练镜像摘要、Git Commit、数据集 Manifest 哈希、参数和随机种子。

### 4.6 评估与回归门禁

进入“模型评估”：

1. 创建 Evaluation Suite，定义指标、阈值和最大允许回归。
2. 选择训练运行和冻结数据集发起评估。
3. 平台同步真实样本、Ground Truth、预测框、置信度、IoU 和错误类型到 FiftyOne。
4. 在困难样本、低置信度、误检和漏检切片中检查问题。
5. 将当前运行与基线比较。

只有门禁通过的评估才能用于模型审批。评估结果保存 mAP、Precision、Recall、F1、分类/检测明细、切片和 FiftyOne Dataset ID。
在评估运行详情点击“受控工作台”，FiftyOne 会以全屏 iframe 嵌入 VisionAI，并直接载入该运行隔离的数据集；顶部保留运行编号、数据集名、刷新、外部打开和返回入口。若嵌入加载超过 15 秒，工作台会给出重试与外部打开选项。

### 4.7 模型注册与审批

进入“模型注册表”：

1. 从成功训练运行注册模型版本，或导入外部制品。
2. 平台保存权重、配置、Model Card、SBOM/依赖、SHA-256 和完整谱系。
3. 对比候选版本的训练数据、指标和制品。
4. 提交审批。
5. 由另一位复核员批准或驳回。

平台强制四眼原则：提交人不能审批自己的请求。审批证据保存当时的 Model Card、评估结果和哈希快照，后续内容变化不会改写历史。

### 4.8 部署、推理与监控

进入“部署与监控”：

1. 选择已批准模型版本，创建开发、预发布或生产部署。
2. 每次配置变化产生新的不可变 Revision。
3. 调用图片或视频推理；响应包含 Trace ID、模型版本、修订号、检测结果和耗时。
4. 查看 QPS、错误率、空结果率、平均置信度和 P50/P95/P99 延迟。
5. 创建阈值告警并确认告警事件。
6. 出现问题时回滚到历史修订，或停止/重启部署。

视频接口会真实解码视频帧并返回逐帧检测结果。回滚不会覆盖历史，而是克隆目标配置为一个新修订并原子切换。

### 4.9 生产反馈闭环

进入“生产反馈”：

1. 设置低置信度阈值、空结果/错误采集、每日上限、保留期和脱敏策略。
2. 在线推理自动按策略捕获样本；SHA-256 防止重复采集。
3. 筛选反馈样本并创建 Batch。
4. 将 Batch 送至 CVAT 复核或重新标注。
5. 审核通过后生成新的 Annotation Revision，再进入数据集版本和训练流程。

Batch 始终保留源 Deployment Revision、Model Version、推理 Trace、反馈策略和目标 Annotation Task，实现线上问题到新模型的完整谱系。

### 4.10 资源、集成与审计

“资源与集成”展示 GPU 节点心跳、驱动/CUDA、显存、队列映射、项目并发/GPU 时/存储配额、CVAT/ClearML/FiftyOne/MinIO/推理集成健康、兼容规则和同步故障。

所有关键业务事件可以在审计列表查询并导出 CSV。同步故障支持幂等重放；兼容规则用于阻止不支持的驱动、CUDA、模型格式或 Provider 组合。

## 5. API 使用

API Base URL 为 `/admin-api`。登录请求必须带 `tenant-id`：

```bash
curl -H "tenant-id: 1" \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}' \
  http://localhost:58080/admin-api/system/auth/login
```

后续请求使用 `Authorization: Bearer <accessToken>`。完整契约、请求模型和在线调试位于 Swagger。VisionAI 业务 API 前缀为 `/admin-api/ai-platform`。

## 6. 运维

### 6.1 停止与升级

```bash
docker compose down            # 保留数据
docker compose pull
docker compose up -d --build --wait
```

升级前先备份，并在预发布环境验证数据库迁移、对象 Manifest 和模型推理兼容性。回退应用镜像不会自动回退数据库；需要按发布说明恢复备份。

### 6.2 备份与恢复

```bash
./scripts/backup.sh
./scripts/restore.sh backups/20260724-120000
```

备份包含 MySQL 逻辑转储、MinIO 数据和解析后的 Compose 配置。生产环境还应对 CVAT、FiftyOne 和推理状态卷实施基础设施级快照。

### 6.3 安全重置

`docker compose down` 不删除数据。只有显式设置确认变量才会删除本项目 Compose 管理的数据卷：

```bash
CONFIRM=YES ./scripts/reset.sh
```

脚本执行前会打印精确卷列表，不操作仓库之外的用户文件。

### 6.4 健康检查

```bash
docker compose ps
docker compose logs --tail=200 backend orchestrator
./scripts/e2e.sh
```

每个核心服务均有健康检查。异步任务可在工作台查看阶段、进度、最近心跳、失败原因、重试次数和事件时间线。

## 7. 故障排查

| 现象 | 检查 | 处理 |
| --- | --- | --- |
| 页面无法打开 | `docker compose ps frontend backend` | 查看日志，确认 48080/58080 未占用 |
| 登录提示参数错误 | 请求是否带 `tenant-id` | 浏览器清缓存；API 调用加请求头 |
| 媒体在 CVAT/FiftyOne 不可见 | MinIO 29000、预签名 Host | 运行 doctor，检查防火墙与 `NIMBUS_S3_PUBLIC_ENDPOINT` |
| 标注准备失败 | CVAT 健康与账号映射 | 集成测试后在同步故障中重放 |
| 训练长期排队 | 节点心跳、队列、配额 | 恢复 GPU Worker，调整项目并发配额 |
| 评估失败 | FiftyOne 5152、数据集冻结状态 | 查看作业阶段和错误，修复后重试 |
| 模型无法审批 | 门禁状态或本人审批 | 使用独立复核员，确保评估通过 |
| 推理返回 409 | 部署/修订未 RUNNING | 等待部署成功或执行重启 |
| GPU 不可见 | `doctor-gpu` | 修复驱动、WSL2 或 Container Toolkit |
| 磁盘增长 | 各卷、反馈保留策略 | 备份后清理过期反馈和无引用制品 |

## 8. 数据与路径可移植性

数据库仅保存 S3 URI、对象 Key、相对工作目录和内容哈希，不保存 `C:\...`、`/mnt/c/...` 等开发机绝对路径。Manifest、Model Card 和参数快照因此可在 Windows 开发机与 Linux 服务端之间迁移。

## 9. 版本与支持

镜像版本固定在 Compose 和 Dockerfile 中；升级时应同时验证 CVAT、FiftyOne、MinIO、CUDA/驱动和模型格式兼容矩阵。问题报告应附 Trace ID、作业 ID、部署修订、相关日志和复现步骤，切勿附真实凭证。