forked from longtao.wu/droboticflow
61 lines
3.0 KiB
Markdown
61 lines
3.0 KiB
Markdown
# 自定义算子 Markdown 体系
|
||
|
||
当前目录用于承载“自定义算子的详细 Markdown 文档”,目标不是只放一篇总手册,而是把设计、实现、验收和实例说明拆开。
|
||
|
||
目录结构:
|
||
|
||
- 模板:
|
||
- [自定义算子设计模板](./templates/自定义算子设计模板.md)
|
||
- [自定义算子实现模板](./templates/自定义算子实现模板.md)
|
||
- [自定义算子验收模板](./templates/自定义算子验收模板.md)
|
||
- 方法文档:
|
||
- [AI 生成到正式算子文档流程](./AI-生成到正式算子文档流程.md)
|
||
- [skillDefinition 编写指南](./skillDefinition-编写指南.md)
|
||
- [百度云 CCR `xspark` 自定义算子接入指南](./百度云-CCR-xspark-自定义算子接入指南.md)
|
||
- 示例:
|
||
- [示例:自定义 JSON 聚合算子](./examples/示例-自定义-JSON-聚合算子.md)
|
||
- [示例:自定义视频窗口采样算子](./examples/示例-自定义-视频窗口采样算子.md)
|
||
- [示例:自定义关键帧抽取算子](./examples/示例-自定义-关键帧抽取算子.md)
|
||
- [示例:自定义图像分割算子](./examples/示例-自定义-图像分割算子.md)
|
||
- 实例级导出:
|
||
- [实例索引](./instances/README.md)
|
||
|
||
使用方式:
|
||
|
||
1. 先阅读 [`../custom-operator-manual.zh-CN.md`](../custom-operator-manual.zh-CN.md)
|
||
2. 用模板写出自己的算子说明
|
||
3. 参考示例补齐输入输出契约、失败模式和验收章节
|
||
4. 当环境中存在真实 `custom` 算子实例时,运行文档生成脚本把实例级 Markdown 导出到 `instances/`
|
||
|
||
自定义镜像使用约束:
|
||
|
||
- 用户自己构建并推送镜像到可被集群拉取的容器仓库
|
||
- 用户自己把完整镜像地址填写到算子的 `image` 字段
|
||
- 平台不会帮你构建或推送自定义镜像
|
||
- 建议填写明确 tag 的完整地址,例如 `ccr-29eug8s3-pub.cnc.bj.baidubce.com/dataflow/custom-<operator-name>:<tag>`
|
||
- 当前 `wjzh` 环境已经真实验证过 `ccr-29eug8s3-pub.cnc.bj.baidubce.com/xspark/<image>:<tag>` 这类私有镜像可正常拉取和执行,详见 [百度云 CCR `xspark` 自定义算子接入指南](./百度云-CCR-xspark-自定义算子接入指南.md)
|
||
- 不要把 `droboticflow-operator-runner:*` 当成自定义镜像填写
|
||
|
||
生成命令示例:
|
||
|
||
```bash
|
||
python3 scripts/generate_operator_docs.py
|
||
```
|
||
|
||
默认输入是仓库内的 `internal/api/builtin_operators_catalog.json`,不会隐式连接本机 API。如果要从某个真实环境导出自定义算子实例,显式传入目标 API:
|
||
|
||
```bash
|
||
python3 scripts/generate_operator_docs.py --api-base-url http://<api-host>:30080
|
||
```
|
||
|
||
如果你手上只有一个 AI 生成的单算子 JSON,也可以直接生成文档,不必先手工包装成 `{ "items": [...] }`:
|
||
|
||
```bash
|
||
python3 scripts/generate_operator_docs.py --input-json /path/to/generated-operator.json
|
||
```
|
||
|
||
说明:
|
||
|
||
- 当前线上算子目录里还没有稳定存在的 `custom` 实例,因此 `instances/` 暂时只有索引页
|
||
- 这并不影响先把自定义算子的文档模板和规范建立好
|