2026-06-16 22:26:42 +08:00

61 lines
3.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 自定义算子 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/` 暂时只有索引页
- 这并不影响先把自定义算子的文档模板和规范建立好