集成
API
通过 HTTP API 进行身份验证、启动运行并读取结果。
Skynet HTTP API 让脚本和工具能够做到 Web 应用能做的事:启动运行、观察运行并读取结果。本页介绍如何为请求签名、完整参考文档在哪里,并提供一个完整示例。
基础 URL
把每个请求发送到:
https://api.skynetml.com身份验证
API 使用 API 令牌。
- 在 Skynet 中打开 设置,然后打开 API 标签页。
- 点击 生成令牌。
- 立即复制令牌。Skynet 只会显示一次完整令牌。
在每个请求的 Authorization 请求头中发送令牌:
Authorization: Bearer skyd_...- 令牌以
skyd_开头。 - 每个用户最多只有一个有效令牌。生成新令牌会使旧令牌失效。
- 点击 吊销令牌 可使令牌失效。
交互式参考文档
完整参考文档位于 api.skynetml.com/scalar。它列出了每个公开端点、其字段和响应。你可以在该页面发送测试请求。
参考文档读取的是位于 https://api.skynetml.com/openapi.public.json 的 OpenAPI 文档。你可以用这个文件为你的语言生成客户端。
主要端点
| 方法和路径 | 作用 |
|---|---|
GET /models | 列出你可以使用的模型。 |
GET /optimizers | 列出适合某个设置的优化器。 |
GET /blackbox/engines | 列出原生引擎以及每个引擎是否可用。 |
POST /optimize | 为提示词、代码、文本或 DSPy 程序启动运行。 |
POST /blackbox/run | 在 GitHub 仓库上启动运行。 |
GET /optimizations | 列出你的运行。 |
GET /optimizations/{optimization_id} | 返回一次运行:状态、进度、日志和结果。 |
GET /optimizations/{optimization_id}/artifact | 返回运行找到的最佳版本。 |
POST /optimizations/{optimization_id}/cancel | 停止一次运行。 |
POST /serve/{optimization_id} | 在新输入上运行最佳版本。 |
GET /health | 显示服务是否正常运行。 |
启动运行
POST /optimize 接受与提交向导相同的设置。本示例改进一个把客服消息归类到标签的提示词。
curl https://api.skynetml.com/optimize \
-H "Authorization: Bearer $SKYNET_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: support-labels-001" \
-d @run.json{
"name": "Support labels",
"task": {
"objective": "Sort each support message into billing, bug or other.",
"artifact": {
"kind": "prompt",
"starting_version": "Label this support message as billing, bug or other."
}
},
"data": {
"mode": "pairs",
"cases": [
{ "input": { "message": "I was charged twice." }, "expected": { "label": "billing" } },
{ "input": { "message": "The export button does nothing." }, "expected": { "label": "bug" } },
{
"input": { "message": "Do you have a Hebrew interface?" },
"expected": { "label": "other" }
}
]
},
"optimizer": { "choice": "auto", "budget": { "max_scorer_runs": 200 } },
"models": {
"task_model": { "name": "<model from GET /models>" },
"reflection_model": { "name": "<model from GET /models>" }
},
"workspace": {
"run_code": "from skynet import llm\n\ndef run(artifact, input):\n return llm(artifact, input=input[\"message\"])\n",
"metric_code": "def score(input, output, expected=None):\n ok = str(output).strip().lower() == expected[\"label\"]\n return (1.0 if ok else 0.0), {\"feedback\": \"Correct.\" if ok else \"Wrong label.\"}\n"
},
"max_cost_cents": 500
}重要字段:
task.artifact.kind取值为prompt、code、text或dspy_program。data.mode取值为pairs(带期望输出的输入)或single(恰好一个用例)。optimizer.choice取值为auto,或GET /optimizers返回的某个优化器名称。max_cost_cents是本次运行的支出上限,单位为美分。is_private默认为false。设为true可将运行设为私有。
关于 run_code 和 metric_code 的规则,请阅读指标与评分器。
响应
| 状态码 | 含义 |
|---|---|
201 | Skynet 已将运行加入队列。响应体包含 optimization_id 和 status。 |
202 | 设置检查仍在进行。等待 Retry-After 请求头中给出的秒数,然后用相同的 Idempotency-Key 发送相同的请求体。 |
402 | 你的余额不足。 |
409 | 你达到了配额,或者设置检查已过期。 |
422 | 请求或工作区代码与优化器不匹配。 |
观察运行
轮询运行,直到其状态变为最终状态:
curl https://api.skynetml.com/optimizations/$RUN_ID \
-H "Authorization: Bearer $SKYNET_TOKEN"status 字段的取值为以下之一:
| 状态 | 最终状态 |
|---|---|
pending、validating、running | 否 |
paused | 否 |
success | 是 |
failed、cancelled、stopped | 是 |
每 10 到 30 秒轮询一次。一次运行可能需要几分钟到几小时。
API 参考文档列出了运行响应的每个字段。
使用结果
当状态为 success 时,获取最佳版本:
curl https://api.skynetml.com/optimizations/$RUN_ID/artifact \
-H "Authorization: Bearer $SKYNET_TOKEN"要在新输入上运行最佳版本,请发送 POST /serve/{optimization_id}。关于每个分数的含义,请阅读结果。