跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.cyberun.cloud/llms.txt

Use this file to discover all available pages before exploring further.

容器服务是托管在你团队代理上的长时运行容器（概念见 容器服务，部署流程见 部署容器服务）。 当服务进入 running 状态后，三个运行时端点可以访问它。 全部接受 JWT、sk-、dk- 作为 Bearer 凭证。

​
服务发现

列出你团队可见的服务： 
GET /api/v1/r/containers HTTP/1.1
Authorization: Bearer sk-...
或按 slug 查询单个服务： 
GET /api/v1/r/containers/{serviceSlug} HTTP/1.1
Authorization: Bearer sk-...
响应中的关键字段：
字段含义
service_slugURL 安全的标识。用在代理和 invoke 路径中。
service_statuscreated、deploying、running、stopping、stopped、failed 之一。
exposed_port容器内部监听的端口。
service_typedeployed（运行在团队代理上）或 external（出口到外部 URL）。
usage_prompt可选的面向 AI 代理的自然语言描述。能列出该服务的任何成员都能读到 —— 不要在这里放密钥。
openapi_url可选的、容器上提供 OpenAPI 文档的路径。AI 客户端可在调用前抓取它取得 schema。

​
透明代理

对于 shell 脚本、原始 HTTP 客户端、以及任何已经能讲容器协议的代码， 使用 catch-all 代理： 
ANY /api/v1/r/containers/{serviceSlug}/*
slug 之后的路径会原样转发到容器，容器的响应也原样返回。 
# vLLM 暴露 OpenAI 兼容 API
curl -H "Authorization: Bearer sk-..." \
  https://core.cyberun.cloud/api/v1/r/containers/my-llm/v1/models

curl -X POST \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"model":"llama3","messages":[{"role":"user","content":"hi"}]}' \
  https://core.cyberun.cloud/api/v1/r/containers/my-llm/v1/chat/completions
由于代理保留了 OpenAI 的请求和响应结构，你可以把任意 OpenAI 兼容 SDK 的 baseURL 直接指向代理： 
import OpenAI from 'openai';

const client = new OpenAI({
	apiKey: process.env.CYBERUN_KEY,
	baseURL: 'https://core.cyberun.cloud/api/v1/r/containers/my-llm'
});

const reply = await client.chat.completions.create({
	model: 'llama3',
	messages: [{ role: 'user', content: 'hi' }]
});
任何底层 HTTP 形状与容器暴露的协议匹配的厂商 SDK 都可以用同样的方式。

​
结构化 invoke（适合 MCP）

对于希望使用单一固定请求形状（而非 catch-all 路径）的程序化客户端 和 MCP 调用方： 
POST /api/v1/r/invoke/{serviceSlug} HTTP/1.1
Authorization: Bearer sk-...
Content-Type: application/json

{
  "method": "POST",
  "path": "/v1/chat/completions",
  "headers": { "Content-Type": "application/json" },
  "body_base64": "eyJtb2RlbCI6Imxsb..."
}
请求体字段：
字段必填含义
method是HTTP 方法（GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS）。
path是容器上的路径，含开头的 /。允许查询串。绝对 URL 或协议相对 URL 会被拒绝。
body_base64否请求体，base64 编码以让二进制数据安全穿过 JSON。GET / DELETE 可省略。
headers否要转发的请求头。逐跳头（Host、Connection、Upgrade、Transfer-Encoding、TE、Trailer）服务端会剥离。
响应： 
{
  "status_code": 200,
  "headers": { "Content-Type": "application/json" },
  "body_base64": "eyJjaG9pY2VzIjpbey4uLn1dfQ=="
}
/r/invoke/{slug} 单独占用一条路径，而不是 /r/containers/{slug}/invoke —— 这样如果容器自身暴露了 /invoke 端点，它仍然可以通过 catch-all 代理访问。

​
何时用哪个

场景用法
shell 脚本、curl、OpenAI SDK baseURL 重定向透明代理
用固定请求形状把服务接进 MCP 工具结构化 /r/invoke/
从非流式调用方转发二进制负载结构化 /r/invoke/

​
状态码

两个端点都会在请求到达容器之前用这些代码暴露网关层错误：
状态码含义
400服务未处于 running 状态（仍在 created、deploying、stopping、stopped 或 failed）。
404此团队中找不到该 service slug。
502代理或网关隧道与容器通信时返回错误。
503服务正在运行但不可用 —— 没有健康实例,或没有在线代理能访问它。
其他状态码都是容器自己返回的。

​
相关