cortexa-v2-sdk 0.1.0__py3-none-any.whl

cortexa_sdk/README.md

@@ -0,0 +1,340 @@
+# Cortexa V2 SDK
+
+`cortexa_v2_sdk` 让训练平台通过稳定的 Python API 查询数基已发布归档，并在 Ray Worker 开训时按不可变 `archive_id` 下载训练数据。发行包使用新名称，Python 导入路径仍为 `cortexa_sdk`，CLI 命令仍为 `cortexa-sdk`。列表发现不依赖共享数据库、对象存储扫描或 `manifest.json`。
+
+## 运行要求
+
+- Python 3.10 或更高版本
+- 可访问 Cortexa API
+- 有效的 Cortexa API Key
+
+## 安装
+
+安装正式版本：
+
+```bash
+python3 -m pip install "cortexa_v2_sdk==0.1.0"
+```
+
+仓库内开发安装：
+
+```bash
+git clone https://github.com/verteklab/cortexa.git
+cd cortexa
+python3 -m pip install -e .
+```
+
+验证：
+
+```bash
+python3 -c "from importlib.metadata import version; print(version('cortexa_v2_sdk'))"
+# 期望输出：0.1.0
+```
+
+## 配置
+
+配置优先级固定为：函数参数 > JSON 配置文件 > 环境变量。
+
+### 环境变量
+
+```bash
+export CORTEXA_API_KEY="<API Key>"
+export CORTEXA_BASE_URL="https://cortexa.example.com/api/v1"
+export CORTEXA_DATASET_DIR="/data/ray_dataset_zip_cache"
+```
+
+| 变量 | 必填 | 说明 |
+|---|---|---|
+| `CORTEXA_API_KEY` | 是 | 请求头 `X-API-KEY` 的值 |
+| `CORTEXA_BASE_URL` | 是 | Cortexa v1 API 基址；SDK 自动从 `/api/v1` 派生归档 `/api/v2` 地址 |
+| `CORTEXA_DATASET_DIR` | 否 | 默认下载目录，缺省为 `~/.cortexa/datasets` |
+| `CORTEXA_CONFIG` | 否 | JSON 配置路径，缺省为 `~/.cortexa/config.json` |
+
+### 配置文件
+
+生成模板：
+
+```bash
+cortexa-sdk --init-config
+```
+
+编辑 `~/.cortexa/config.json`：
+
+```json
+{
+  "api_key": "<API Key>",
+  "base_url": "https://cortexa.example.com/api/v1",
+  "dataset_dir": "/data/ray_dataset_zip_cache"
+}
+```
+
+不要把 API Key 提交到 Git、镜像或训练任务配置中；通过部署环境或密钥管理服务注入。
+
+## 查询训练可用归档
+
+数基归档详情选择“同步到鼎算”时只发布归档引用，不预生成 ZIP。鼎算后端通过 SDK 查询这个列表：
+
+```python
+from cortexa_sdk import CortexaClient
+
+client = CortexaClient()
+result = client.list_training_archives(
+    keyword="桥梁",
+    page=1,
+    page_size=20,
+)
+
+for archive in result["list"]:
+    print(
+        archive["_id"],
+        archive["name"],
+        archive.get("dataset_id"),
+        archive.get("display", {}).get("format"),
+    )
+```
+
+返回分页结构：
+
+```json
+{
+  "list": [
+    {
+      "_id": "归档ID",
+      "dataset_id": "来源数据集ID",
+      "name": "桥梁病害检测",
+      "status": "approved",
+      "display": {
+        "registered": true,
+        "training_name": "桥梁病害训练集",
+        "format": "YOLO",
+        "samples": 8600,
+        "version": "v1.0"
+      }
+    }
+  ],
+  "total": 1,
+  "page": 1,
+  "page_size": 20
+}
+```
+
+训练平台必须保存 `_id` 作为 `archive_id`。`dataset_id` 只用于来源追溯，不能替代不可变归档 ID。
+
+## 读取归档详情
+
+```python
+archive = client.archive_detail("<archive_id>")
+print(archive["name"])
+print(archive["asset_snapshot"])
+```
+
+训练平台应先从 `list_training_archives()` 取得可用 ID，再读取详情。直接知道归档 ID 不等于该归档已发布给训练平台。
+
+## Ray Worker 按需下载
+
+Worker 开训时按 `archive_id` 请求训练格式。该调用会在数基创建或复用普通归档导出任务，等待任务完成并把 ZIP 下载到本地；它不会创建跨平台 manifest 或共享存储副本。
+
+使用客户端：
+
+```python
+from cortexa_sdk import CortexaClient, ExportType
+
+client = CortexaClient()
+zip_path = client.download_archive(
+    archive_id="<archive_id>",
+    export_type=ExportType.YOLO,
+    split_ratio="8:2",
+    download_dir="/data/ray_dataset_zip_cache",
+    assets_included=True,
+)
+print(zip_path)
+```
+
+Ray Worker 也可以调用模块级函数：
+
+```python
+from cortexa_sdk import ExportType, download_archive
+
+zip_path = download_archive(
+    archive_id="<archive_id>",
+    export_type=ExportType.COCO,
+    split_ratio="7:3",
+    api_key="<API Key>",
+    base_url="https://cortexa.example.com/api/v1",
+    download_dir="/data/ray_dataset_zip_cache",
+)
+```
+
+归档训练下载只支持：
+
+- 格式：`ExportType.YOLO`、`ExportType.COCO`
+- 划分：`8:2`、`7:3`、`9:1`
+
+同一 Worker 节点应按 `archive_id` 复用本地缓存，避免多个训练进程重复下载。
+
+## 下载旧数据集
+
+旧流程仍可按 `dataset_id` 下载：
+
+```python
+from cortexa_sdk import AnnotationType, ExportType, download_dataset
+
+zip_path = download_dataset(
+    dataset_id="<dataset_id>",
+    export_type=ExportType.JSON,
+    annotation_type=AnnotationType.RECT,
+    assets_included=True,
+)
+```
+
+CLI 当前只支持旧 `dataset_id` 下载，不支持归档列表和 `archive_id` 下载：
+
+```bash
+cortexa-sdk \
+  --dataset-id "<dataset_id>" \
+  --export-type YOLO \
+  --annotation-type rect \
+  --download-dir ./tmp/datasets
+```
+
+归档发现和归档下载必须使用 Python API。
+
+## 解析下载包
+
+```python
+from cortexa_sdk.parser import extract_zip, load_dataset
+
+dataset_dir = extract_zip("./tmp/datasets/<dataset_id>.zip")
+samples = load_dataset(dataset_dir)
+print(f"samples={len(samples)}")
+```
+
+`load_dataset()` 返回结构化 `EvalSample` 列表，可读取样本 split、媒体路径和问答标注。
+
+## 异常处理
+
+```python
+from cortexa_sdk import CortexaClient, ExportType
+
+try:
+    client = CortexaClient()
+    path = client.download_archive(
+        "<archive_id>",
+        export_type=ExportType.YOLO,
+    )
+except ValueError as exc:
+    # 配置、格式或划分参数错误
+    print(exc)
+except RuntimeError as exc:
+    # Cortexa 返回业务错误或导出任务失败
+    print(exc)
+```
+
+HTTP 连接、鉴权和超时错误由 `requests` 异常体系抛出。生产 Worker 应让任务框架记录异常并按任务策略重试，不要把失败当作空数据集继续训练。
+
+## 发布到 PyPI
+
+PyPI 上的版本不可覆盖。`cortexa_v2_sdk` 是独立于 `cortexa-sdk` 的新发行包，版本从 `0.1.0` 开始；后续发布前必须把 `pyproject.toml` 中的版本改为一个从未上传过的新版本。
+
+### 1. 准备发布提交
+
+```bash
+git checkout <release-branch>
+python3 -m pytest -q cortexa_sdk/test_sdk.py
+black .
+python3 .docsmith/scripts/gen.example.py
+git diff --check
+```
+
+确认 `pyproject.toml`、SDK 源码、测试和文档属于同一提交，然后提交：
+
+```bash
+git add -p
+git diff --cached --name-only
+git diff --cached --check
+git commit -m "chore(sdk): release cortexa_v2_sdk 0.1.0"
+```
+
+逐项确认暂存内容只包含本次 SDK 版本、源码、测试和受影响文档。仓库存在其他未提交改动时，不要使用 `git add .` 或暂存整个目录。
+
+### 2. 构建并校验产物
+
+```bash
+RELEASE_DIR="$(mktemp -d)"
+python3 -m build --outdir "$RELEASE_DIR"
+python3 -m twine check "$RELEASE_DIR"/*
+ls -lh "$RELEASE_DIR"
+```
+
+期望生成：
+
+- `cortexa_v2_sdk-0.1.0-py3-none-any.whl`
+- `cortexa_v2_sdk-0.1.0.tar.gz`
+- Twine 输出 `PASSED`
+
+使用隔离环境安装 wheel：
+
+```bash
+python3 -m venv /tmp/cortexa-v2-sdk-release-venv
+/tmp/cortexa-v2-sdk-release-venv/bin/python -m pip install \
+  "$RELEASE_DIR/cortexa_v2_sdk-0.1.0-py3-none-any.whl"
+/tmp/cortexa-v2-sdk-release-venv/bin/python -c \
+  "from cortexa_sdk import CortexaClient, download_archive; from importlib.metadata import version; print(version('cortexa_v2_sdk'))"
+```
+
+期望输出 `0.1.0`，且导入不报错。
+
+### 3. TestPyPI 验证
+
+在 TestPyPI 创建 API Token，并只放在当前终端环境中：
+
+```bash
+export TWINE_USERNAME="__token__"
+read -s TWINE_PASSWORD
+export TWINE_PASSWORD
+python3 -m twine upload \
+  --repository-url https://test.pypi.org/legacy/ \
+  "$RELEASE_DIR"/*
+```
+
+从 TestPyPI 安装时，运行依赖仍从正式 PyPI 获取：
+
+```bash
+python3 -m venv /tmp/cortexa-v2-sdk-testpypi-venv
+/tmp/cortexa-v2-sdk-testpypi-venv/bin/python -m pip install \
+  --index-url https://test.pypi.org/simple/ \
+  --extra-index-url https://pypi.org/simple/ \
+  "cortexa_v2_sdk==0.1.0"
+```
+
+### 4. 正式发布并打标签
+
+确认 TestPyPI 安装和 SDK 冒烟调用正常后，上传同一目录中的原始产物，不要重新构建：
+
+```bash
+git push origin HEAD
+python3 -m twine upload "$RELEASE_DIR"/*
+unset TWINE_PASSWORD TWINE_USERNAME
+
+git tag -a cortexa-v2-sdk-v0.1.0 -m "cortexa_v2_sdk 0.1.0"
+git push origin cortexa-v2-sdk-v0.1.0
+```
+
+验证正式版本：
+
+```bash
+python3 -m pip index versions cortexa_v2_sdk
+python3 -m pip install --no-cache-dir "cortexa_v2_sdk==0.1.0"
+```
+
+## 发版检查表
+
+- [ ] `pyproject.toml` 版本未在 PyPI 使用
+- [ ] SDK 测试全部通过
+- [ ] `black .`、docsmith 和 `git diff --check` 通过
+- [ ] wheel 与 sdist 均通过 `twine check`
+- [ ] 隔离环境可导入 SDK，版本正确
+- [ ] TestPyPI 安装及关键 API 冒烟通过
+- [ ] 正式 PyPI 上传的是已经验证过的同一批产物
+- [ ] 已推送 `sdk-v<version>` 标签
+- [ ] API Token 未写入文件、命令参数、提交或日志