算子 API¶

算子 API 将一个系统算子或自定义算子发布为同步 REST 服务，外部应用提交该算子的输入并直接取得结果。解析、分段、嵌入和信息提取等单步处理适合使用这种方式；包含多个步骤或执行时间较长的任务更适合编排为工作流。

调用模型与工作流的区别¶

需求	使用的能力
直接调用大模型推理	Genesis 模型 API
调用一个已发布的数据处理算子	算子 API
执行多步骤、长时间或需要作业状态的任务	工作流及当前部署提供的作业能力

算子 API 是同步调用。算子层不提供独立的异步作业模型，调用方应按服务页配置的超时处理请求。

发布前准备¶

发布之前确认：

目标算子版本已保存并处于可用状态；
输入参数的名称、类型、必填项和默认值符合预期；
非模型类算子已具备可用的任务型计算资源；
当前账号具有管理该 Catalog 资源和发布服务的权限；
调用方能够使用服务所配置的 API Key、OAuth 2.0 或公开访问方式。

系统算子和自定义算子都可能提供 API 发布入口。具体入口受资源类型、版本状态、权限和部署版本影响。

发布并取得调用契约¶

进入资源中心 > Catalog，打开目标数据库和算子。
选择要发布的算子版本，进入 API 服务。
按页面提供的操作发布或启用服务，并配置鉴权与运行参数。
记录服务状态、调用地址、请求参数、响应说明和调用示例。
先使用在线试用或页面示例验证一组无敏感信息的输入，再接入应用。

页面可能提供超时、最大并发和调用频率等运行配置。可用字段及其生效范围以当前页面为准。

构造请求¶

服务地址和 JSON 结构随算子签名变化。下面只展示使用 API Key 时的请求外形，不代表某个算子的固定字段：

curl --request POST "$OPERATOR_ENDPOINT" \
  --header "Authorization: Bearer $GENESIS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"input":"..."}'

请求体中的 input 仅为结构示意。实际调用时，应完整复制服务页为当前版本生成的字段名称与层级。若服务配置为 OAuth 2.0 或公开访问，也应使用页面显示的方式，不要继续发送示例中的 API Key。

参数与结果¶

输入对应算子的参数签名和发布时选择的输入来源。
必填项、默认值和类型以所发布版本为准；不同版本可能不兼容。
响应结构由算子输出决定。本页不约定统一的 data、result 或错误对象。
HTTP 状态码、错误正文和请求标识应按实际响应记录，便于排查。

版本与变更¶

修改算子逻辑时，优先创建新版本并在测试后发布。切换服务版本或重新发布后：

对比新旧参数签名和输出；
用固定测试样本验证结果；
检查调用方的超时和重试策略；
再逐步切换生产流量。

停用或删除版本前，先确认没有工作流、智能体工具或外部应用依赖该版本。资源页面显示“发布成功”并不等于业务调用已经通过，应以一次真实请求的结果为准。

调用方的可靠性处理¶

为请求设置略高于服务配置的客户端超时，避免连接无限等待。
只有在能够判断操作可安全重复时才自动重试；算子是否有副作用由其实现决定。
对大输入、敏感数据和并发调用设置业务侧限制。
分别监控 HTTP 失败、超时和内容校验失败，不要仅统计请求次数。
凭证应保存在密钥管理系统或环境变量中，并按部署策略轮换。

排查¶

现象	检查项
401 或 403	服务鉴权方式、密钥是否有效、账号或应用权限
404	是否使用当前版本显示的完整调用地址，服务是否已启用
参数校验失败	字段名称、层级、类型、必填项以及版本是否匹配
超时或 5xx	算子在线试用是否成功、任务型计算资源是否可用、服务运行限制
发布后结果未变化	实际调用的服务版本、重新发布状态和调用方缓存

操作步骤见 Catalog 管理，算子范围见系统算子库，开放能力边界见平台开放能力。

最后更新于 2026 年 8 月 8 日