deepdata: core product code (backend, frontend, runtime, deepflow module)

2026-08-30 19:23:38 +08:00
commit bd3db30be9
1405 changed files with 271727 additions and 0 deletions
@@ -0,0 +1,297 @@
+# 自定义算子开发规范指南
+
+本文档旨在为开发者提供一套标准的自定义数据处理算子开发规范。通过遵循本指南，您可以开发出能够无缝集成到数据处理系统中的高质量算子。
+
+## 1. 目录结构规范
+
+一个标准的算子开发包（Package）应包含以下核心文件。请确保文件命名准确，以便系统正确识别。
+
+```text
+operator_package/
+├── __init__.py        # [必要] 算子注册入口，用于将算子注册到全局工厂
+├── metadata.yml       # [必要] 算子元数据、UI 参数定义及资源配置
+├── process.py         # [必要] 算子核心逻辑代码
+├── requirements.txt   # [可选] 算子运行所需的第三方 Python 依赖
+└── README.md          # [可选] 算子功能说明文档
+
+```
+
+---
+
+## 2. 元数据与配置 (metadata.yml)
+
+`metadata.yml` 定义了算子在系统中的“身份”、前端显示的配置组件以及运行时资源限制。
+
+### 2.1 基础信息配置
+
+| 字段 | 说明                                 | 示例 |
+| --- |------------------------------------| --- |
+| `name` | 算子显示名称                             | 测试算子 |
+| `description` | 算子描述                               | 这是一个测试算子。 |
+| `language` | 算子使用的语言，当前仅支持python                | python |
+| `raw_id` | **关键字段**，必须与 `process.py` 中的类名完全一致 | TestMapper |
+| `version` | 语义化版本号                             | 1.0.0 |
+| `vendor` | 厂商                             | deepdata |
+| `modal` | 支持的数据模态 (text/image/audio/video)   | text |
+| `inputs` | 输入的数据模态 (text/image/audio/video)   | text |
+| `outputs` | 输出的数据模态 (text/image/audio/video)   | text |
+
+### 2.2 算子功能分类
+
+定义算子功能分类，支持清洗与标注。
+
+```yaml
+types:
+  - 'cleaning'
+  - 'annotation'
+```
+
+### 2.3 算子版本更新日志 (release)
+
+定义算子当前版本较上版本更新内容。
+
+```yaml
+release:
+  - '首次发布'
+  - '支持基本处理操作'
+```
+
+### 2.4 运行时资源与指标 (runtime & metrics)
+
+定义算子运行时的资源配额及性能指标参考。
+
+```yaml
+runtime:
+  memory: 10485760  # 内存 单位bytes
+  cpu: 0.05    # CPU 核心数
+  gpu: 0.1      # GPU 卡数
+  npu: 0.1      # NPU 卡数
+  storage: 10MB # 存储空间
+
+metrics:        # 算子性能参考指标
+  - name: '吞吐量'
+    metric: '20 images/sec'
+  - name: '准确率'
+    metric: '99.5%'
+```
+
+### 2.5 参数设置 (settings) - UI 组件规范
+
+通过 `settings` 字段，开发者可以自定义用户在前端界面配置算子时的交互组件。系统支持以下类型：
+
+* **Slider (滑动条)** - 用于数值范围调整
+```yaml
+sliderParam:            # 参数的唯一标识符，process.py 中通过该参数获取值
+  name: '参数展示名称'    # 界面上显示给用户的参数标题
+  description: '参数展示描述'   # 用户鼠标悬停时显示的详细功能说明或帮助文本
+  type: 'slider'      # 组件类型
+  defaultVal: 0.5     # 算子加载时的初始值，必须位于 min 和 max 之间
+  required: false     # 是否必填
+  min: 0    # [下限] 滑动条允许调整的最小值
+  max: 1    # [上限] 滑动条允许调整的最大值
+  step: 0.1 # [步长] 每次拖动的增量 (例如 0.1 代表保留一位小数，1 代表整数)
+```
+
+* **Switch (开关)** - 用于布尔值控制
+```yaml
+switchParam:
+  name: '参数展示名称'
+  description: '参数展示描述'
+  type: 'switch'
+  defaultVal: 'true'        # 注意 yaml 中布尔值建议使用引号或标准写法
+  required: false           # 是否必须参数
+  checkedLabel: '选中'       # 选中时的展示
+  unCheckedLabel: '未选中'   # 未选中时的展示
+```
+
+* **Select / Radio (下拉 / 单选)** - 用于枚举选项
+```yaml
+selectParam:
+  name: '参数展示名称'
+  description: '参数展示描述'
+  type: 'select' # 或 'radio'
+  defaultVal: 'option1'   # 默认后端传递值，为options其中一个选项
+  required: false
+  options:
+    - label: '选项1'      # 前端显示标签
+      value: 'option1'   # 后端传递值
+    - label: '选项2'
+      value: 'option2'
+```
+
+* **Range (范围区间)**
+```yaml
+rangeParam:
+  name: '参数展示名称'
+  description: '参数展示描述'
+  type: 'range'
+  properties:
+    - name: 'rangeLeft'   # 范围下限
+      type: 'inputNumber'
+      defaultVal: 100
+      min: 0
+      max: 10000
+      step: 1
+    - name: 'rangeRight'  # 范围上限
+      type: 'inputNumber'
+      defaultVal: 8000
+      min: 0
+      max: 10000
+      step: 1
+```
+
+* **Checkbox (多选)**
+```yaml
+checkboxParam:
+  name: '参数展示名称'
+  description: '参数展示描述'
+  type: 'checkbox'
+  defaultVal: 'option1,option2'   # 多个值用逗号分隔
+  required: false
+  options:
+    - label: '选项1'
+      value: 'option1'
+    - label: '选项2'
+      value: 'option2'
+
+```
+
+* **Input (文本输入)**
+```yaml
+inputParam:
+  name: '参数展示名称'
+  description: '参数展示描述'
+  type: 'input'
+  defaultVal: '默认值'
+  required: false
+```
+
+---
+
+## 3. 核心逻辑实现 (`process.py`)
+
+`process.py` 是算子的执行主体。开发者需继承基础类并实现数据处理逻辑。
+
+### 开发规范
+
+1. **继承基类**：必须从 `deepdata.core.base_op` 继承 `Mapper`或 `Filter`。
+2. **类名一致性**：Python 类名建议与后续 `metadata.yml` 中的 `raw_id` 保持一致。
+3. **Execute 方法**：必须实现 `execute` 方法，接收 `sample` (字典) 并返回处理后的字典。
+
+### 代码模板
+
+```python
+from typing import Dict, Any
+from deepdata.core.base_op import Mapper
+
+class YourOperatorName(Mapper):
+    """
+    算子类名建议使用驼峰命名法定义，例如 TestMapper
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.slider_param = float(kwargs.get("sliderParam", 0.5))
+        self.switch_param = kwargs.get('switchParam', False)
+        self.select_param = kwargs.get('selectParam', '')
+        self.radio_param = kwargs.get('radioParam', '')
+        self.range_param = kwargs.get('rangeParam', [0, 0])
+        self.checkbox_param = kwargs.get('checkboxParam', [])
+        self.input_param = kwargs.get('inputParam', '').strip()
+
+    def execute(self, sample: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        核心处理逻辑
+        :param sample: 输入的数据样本，通常包含 text_key 等字段
+        :return: 处理后的数据样本
+        """
+        # 示例：获取文本并进行修改
+        # input_text = sample['text']
+        # processed_text = do_something(input_text)
+        # sample['text'] = processed_text
+
+        return sample
+
+```
+
+其中，sample字段包含如下参数：
+
+```json
+{
+  "text": "源文件读取的文本内容",
+  "data": "源文件读取的二进制数据（针对图片等）",
+  "fileName": "源文件名",
+  "fileType": "源文件类型（扩展名）",
+  "fileId": "源文件ID",
+  "filePath": "源文件路径",
+  "fileSize": "源文件大小",
+  "export_path": "目标文件导出路径信息",
+  "ext_params": "额外扩展参数",
+  "target_type": "目标文件类型"
+}
+```
+
+---
+
+## 4. 算子注册 (`__init__.py`)
+
+`__init__.py` 用于将开发好的算子注册到系统中。
+
+### 注册规范
+
+使用 `OPERATORS.register_module` 方法进行注册。
+
+* **module_name**: 对应 `metadata.yml` 中的 `raw_id` 及 Python 类名。
+* **module_path**: 指向 `process.py` 的引用路径（注意路径层级）。
+
+### 代码模板
+
+```python
+# -*- coding: utf-8 -*-
+from deepdata.core.base_op import OPERATORS
+
+# 假设 process.py 位于 operator_package 目录下
+OPERATORS.register_module(
+    module_name='YourOperatorName',
+    module_path="ops.user.operator_package.process"
+)
+
+```
+
+---
+
+## 5. 开发注意事项
+
+1. **依赖管理**：如果算子依赖非标准库（如 pandas, numpy），请在 `requirements.txt` 中列出。
+2. **异常处理**：在 `process.py` 中建议添加适当的 try-catch 逻辑，避免单条数据异常导致整个任务崩溃。
+3. **数据类型**：在 `metadata.yml` 中定义的参数类型（如 slider 返回 float，input 返回 string），在 Python 代码中使用时需注意类型转换。
+
+---
+
+## 6. 算子打包与上传
+
+开发完成后，需将所有文件打包为一个压缩包进行上传。**包名必须严格遵循注册路径规范**。
+
+### 打包规范
+
+1. **文件完整性**：压缩包内必须包含 `__init__.py`, `metadata.yml`, `process.py` 及相关依赖。
+2. **命名一致性（重要）**：压缩包的文件名（不含后缀）必须与 `__init__.py` 中 `module_path` 所指定的**包目录名**保持一致。
+
+### 示例说明
+
+假设您在 `__init__.py` 中的注册代码如下：
+
+```python
+OPERATORS.register_module(
+    module_name='TestMapper',
+    # 这里 ops.user.my_custom_op.process 中的 'my_custom_op' 为包目录名
+    module_path="ops.user.my_custom_op.process"
+)
+
+```
+
+则您的压缩包名称必须命名为：
+
+> **`my_custom_op.zip`** (或 .tar)
+
+系统解压后将基于此名称构建导入路径，名称不一致将导致 `ModuleNotFoundError`。