初创-数据飞轮

Catellect Dataset Cloud 项目导读面向新接手者的总览文档：从「这是什么」到「每个细节怎么做的」。其余细节文档散落在docs/，本文只做主干串联，遇到需要展开时再点进去。0. 概述Hub 端：利用Hub Agent采集数据，通过接口将数据分块传给云端。https://test-api.catellect.com/dataset/，这部分数据是动物活动的 IMU、Audio、Video 数据；云端：云端通过流式的方式拿到数据之后，对数据状态进行修改“数据是否接收”，然后将数据的元信息存储到 PostreSQL 中，将数据的媒体信息存储到 OSS 上；具体处理如下：Label端：label 模型评测图片（六帧一组），用的Gemini3.8-Flash，如果全是未见猫则这些数据，就删除；如果出现过猫并且包含猫信息的则保存；Teacher模型：对新进来的数据进行评估，得到指标，然后在识别不出来的数据上做 SFT，然后 OPD 给 student 模型；训练完后更新保存在数据库中的数据字段 status；1. 这个项目到底是什么一句话：一个独立的「猫咪设备原始采集数据 → 云端回流归档 → LLM 打标 / YOLO 预筛 → 人工复核 → 数据集导出」的端到端数据平台。它不接入 Care / Memory / With / 产品 observation 等兄弟系统，是自洽的独立仓库（独立数据库、独立 worker、独立鉴权）。最终目的是把猫项圈设备在 Hub 上产生的录音（WAV）、惯性数据（IMU）和上下文视频（MP4）回流到云端，给 LLM 做行为/质量打标、给人工复核，并产出可用于训练或评估的不可变数据集快照（JSONL）。业务上的典型问题：猫项圈本地采集了多模态样本，但只有一部分里有猫，怎么把「无猫」样本自动剔除出打标视图？同一段录音可能在 Hub 上传时偏移了几秒，怎么在不改原文件、不重写历史的前提下校准音视频？多个 prompt / 多个模型版本下，怎么保证每次导出的快照不被新结果偷偷覆盖？Hub agent 跑在生产猫项圈 Hub 上，Python 版本只有 3.11，怎么在不重启其它源服务的情况下做增量回流？本项目用「不可变修订 + 版本指纹 + 租约 fencing + 内容寻址存储 + 公共前缀部署」一组机制把这些问题落地。2. 顶层架构┌──────────────────────┐ ┌──────────────────────────────────────────────────────┐ │ 物理 Hub（项圈设备）│ │ 测试环境 Dataset Cloud（部署在 HK 测试 VM） │ │ - sqlite 源库 │ │ ┌────────┐ ┌────────┐ ┌──────────────┐ ┌────────┐ │ │ - 源 WAV/IMU/MP4 │ HTTP │ │ API │ │ Worker │ │ cat-detector │ │ Web │ │ │ hub_agent (3.11) │─────▶│ │FastAPI │ │LLM租约 │ │ ONNX YOLO │ │ nginx │ │ └──────────────────────┘ │ └───┬────┘ └────┬───┘ └──────┬───────┘ └───▲────┘ │ │ │ │ │ │ │ ┌──────────────────────┐ │ ┌───▼──────────▼────────────▼────┐ │ │ │ 测试 Cloud 源库 │ GCS │ │ PostgreSQL / GCS │ │ │ │ catellect_test │─rewind▶│ │ catellect_dataset_test │ │ │ │ （历史视频） │ │ └──────────────────────────────┘ │ │ └──────────────────────┘ └──────────────────────────────────────────┼──────┘ 公网：https://test-api.catellect.com/dataset/─┘进程清单（docker-compose.deploy.yml）：服务作用镜像migrate一次性执行alembic upgrade headcatellect-dataset-apiapiFastAPI 管理面 + Hub 上传协议catellect-dataset-apiworkerLLM 打标后台 workercatellect-dataset-apicat-detectorONNX YOLO 预筛 workercatellect-dataset-cat-detectordataset-web静态 nginx + Vue SPAcatellect-dataset-websource-sync历史 Cloud 视频回流连接器（profile=connectors）catellect-dataset-api物理 Hub 上另起catellect-dataset-return.service（systemd 单元），用Python 3.11 标准库实现，因为 Hub 装不了项目自带的 Python 3.12 应用。3. 技术栈与版本约束后端：Python3.12、FastAPI、Pydantic v2、SQLAlchemy 2.0、Alembic、httpx模型：google-genai（Vertex AI）、google-cloud-storage数据库：生产PostgreSQL 16；开发/测试可用 SQLite（PG 是验收目标）前端：Vue 3 + TypeScript + Vue Router + Vite；pnpm（锁文件固定）；Node22.22.0（用fnm exec --using=22.22.0）媒体：生产 GCS（内容寻址 + generation 条件保护）；开发本地内容寻址存储ONNX：onnxruntimeCPU，模型yolo26n（COCO 猫=index 15）CI/包管理：uv+setuptools=69部署：Docker（多 Dockerfile）、Caddy 边缘反代、GCE VM 服务账号 ADC强制约束（写在AGENTS.md和config.validate_runtime()）：生产禁止：演示鉴权、fixture provider、本地文件存储、SQLite、已知开发 secret、隐式create_all生产必须：alembic upgrade head、PostgreSQL、GCS、≥32 字节真 secret、≥24 字符真 operator/hub token媒体/管理 API 分别鉴权；Hub token 不能改 prompt / GT / 导出凭据不入库、不进日志；uvicorn 默认关闭 access log（媒体签名在查询参数中）4. 目录结构速查catellect-dataset-cloud-codex-dataset-foundation/ ├─ src/dataset_cloud/ # 后端核心包 │ ├─ app.py # FastAPI 工厂 + main() │ ├─ config.py # Settings + 生产运行时校验 │ ├─ models.py # SQLAlchemy ORM 模型（不可变约束） │ ├─ auth.py # Operator / Hub 双鉴权 │ ├─ canonical.py # 规范化 JSON + 指纹哈希 │ ├─ locks.py # PG advisory xact lock / SQLite Lock │ ├─ worker.py # 独立 worker 进程（SIGTERM 友好） │ ├─ cli_upload.py # dataset-upload CLI │ ├─ seed_demo.py # dataset-seed（合成 fixture） │ ├─ bootstrap_return.py # dataset-bootstrap-return │ ├─ imu_normalize.py # imu-normalize-v1 预处理器 │ ├─ alignment.py # 逐版本时间校准 │ ├─ curation.py # 可恢复隐藏 + 自动预筛 │ ├─ routers/ # admin / ingest / cat_detection / health │ ├─ ingest/service.py # prepare → HEAD → PUT → finalize │ ├─ labeling/ # stage / job / schema 守卫 / 模板 │ ├─ providers/ # vertex / fixture / base │ ├─ media/ # local_store / gcs_store / signed │ ├─ review/service.py # 人工修订（GroundTruthRevision） │ ├─ export/service.py # 不可变 JSONL 快照 │ ├─ source_sync/ # Cloud 历史视频回流连接器 │ └─ cat_detection/ # ONNX YOLO 引擎 + jobs + worker ├─ hub_agent/ # Python 3.11 stdlib，跑在物理 Hub 上 │ ├─ runner.py # flock 单实例 + 失败隔离 │ ├─ manifest.py # 从 sqlite + clip 行构造样本 │ ├─ http.py # stdlib 上传客户端 │ ├─ identity.py # 校验 cloud-sync 进程 environ │ └─ systemd/ # catellect-dataset-return.service ├─ web/ # Vue SPA │ ├─ src/pages/ # 9 个页面 │ ├─ src/components/ # AppShell / TimelinePlayer / ImuChart ... │ └─ nginx/ # 生产静态 nginx 配置 ├─ alembic/ # 数据库迁移（独立 schema） ├─ tests/ # 25 个测试模块，隔离 PG 集群 ├─ docs/ # 15 篇专题文档 ├─ config/cat-detector-model.json # ONNX 模型 SHA 校验配置 ├─ docker-compose.yml # 本地开发（PG + 本地媒体） ├─ docker-compose.deploy.yml # 测试环境（GCS + 边缘网络） ├─ Dockerfile # api/worker ├─ Dockerfile.cat-detector # ONNX runtime 独立镜像 ├─ pyproject.toml # 入口点 dataset-api / -worker / -upload / -seed / -source-sync / -bootstrap-return ├─ README.md # 本地起服命令 └─ AGENTS.md # 执行者边界与合同/