cortexa-sdk 0.3.0

Python SDK for Cortexa: download & parse datasets (JSON/YOLO/COCO), list datasets with template-annotation filter, and structured EvalSample output for evaluation pipelines.

---

audience: [engineering, business] edit_policy: factual_direct source_of_truth:

• backend/server/settings.py
• backend/server/urls.py
• backend/requirements.txt
• frontend/package.json
• pyproject.toml
• .docsmith/features.yml
• {fact: "仓库结构与开发者入口"}

---

Cortexa

把原始图片和视频变成可训练数据集：上传素材、标注（人工或 AI 预标注）、审查、打包导出，一条线走完。

• 多种标注类型：矩形框、多边形、3D 立方体、折线、自定义答题模板，覆盖检测/分割/3D/质检场景
• AI 预标注加速：接入 PaddleX 小目标检测、SAM2/SAM3 语义分割、3D-MOOD 立方体检测模型，标注员只需修正
• 一行代码拉数据集：Python SDK 支持 JSON/YOLO/COCO 格式导出，按标签过滤、按模板分组打包

架构

graph TD
    Browser["UmiJS + Ant Design 前端<br/>:8001"]
    API["Django REST Framework<br/>:8000"]
    Worker["Celery Worker"]
    Beat["Celery Beat"]
    Mongo[(MongoDB)]
    MinIO[(MinIO 对象存储)]
    RabbitMQ[(RabbitMQ)]
    AI["AI 模型服务<br/>(PaddleX / SAM2 / SAM3 / 3D-MOOD)"]
    SDK["cortexa-sdk<br/>Python CLI + API"]

    Browser -->|HTTP /api/v1/| API
    SDK -->|HTTP /api/v1/| API
    API --> Mongo
    API --> MinIO
    API --> RabbitMQ
    RabbitMQ --> Worker
    Beat -->|定时任务| RabbitMQ
    Worker --> Mongo
    Worker --> MinIO
    Worker --> AI

前置条件

依赖	版本	用途
Python	>= 3.10	后端运行时
Node.js	>= 18	前端构建
pnpm	>= 8	前端包管理
MongoDB	>= 6	主数据库
MinIO	最新	对象存储（图片/视频/zip）
RabbitMQ	>= 3.12	Celery 消息队列

快速启动

# 1. 克隆仓库
git clone <repo-url> && cd cortexa

# 2. 启动后端
cd backend
cp .env.example .env          # 填写 MongoDB / MinIO / RabbitMQ 地址
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python manage.py runserver 0.0.0.0:8000   # API 服务

# 3. 启动 Celery（另开两个终端）
celery -A server worker -l info           # 异步任务处理
celery -A server beat -l info             # 定时任务调度

# 4. 启动前端
cd ../frontend
pnpm install && pnpm dev                  # 开发模式，访问 http://localhost:8001

# 5. 安装 SDK（可选，用于脚本化下载数据集）
pip install cortexa-sdk
cortexa-sdk --init-config                 # 生成 ~/.cortexa/config.json

仓库结构

目录	说明
backend/	Django REST Framework API 服务（Python 3.10 + MongoDB）
frontend/	UmiJS + Ant Design 标注 Web 界面（TypeScript + React）
cortexa_sdk/	用户侧 Python SDK（pip install cortexa-sdk）

文档导航

文档	说明
PRODUCT.md	产品能力总览
docs/product/feature-map.md	完整能力矩阵
docs/reference/api.md	HTTP 接口清单
docs/reference/config.md	环境变量配置参考
docs/reference/data-model.md	数据模型
docs/reference/glossary.md	术语表
docs/how-to/local-development.md	本地开发
docs/how-to/deploy.md	部署
docs/how-to/troubleshooting.md	排障
docs/explanation/architecture.md	架构设计

Contributing

1. 从 main 拉分支，命名 feat/xxx 或 fix/xxx
2. 后端改完跑 pytest，前端改完跑 pnpm build
3. 提 PR 并填写 .github/pull_request_template.md 模板

License

Copyright (c) 2025 Vortek Inc. and Tuanliu (Hainan Special Economic Zone) Technology Co., Ltd. All rights reserved.