> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/clore.ai/clore.ai-eng-zh/kai-fa-zhe/cli-sdk.md).

# CLI 与 SDK 指南

## 概述

Clore.ai 提供了一个 **REST API** ，可实现对 GPU 市场的完全编程访问——列出服务器、创建订单、监控部署以及取消租用。

> **注意：** 目前没有官方的 CLI 二进制文件。所有自动化都直接通过 REST API 完成，使用诸如 `curl`、Python 或 Node.js 等工具。

**基础 URL：** `https://api.clore.ai/v1`

**响应格式：** JSON。每个响应都包含一个 `code` 字段，用于指示状态。

***

## 身份验证

从以下位置生成你的 API 密钥： [Clore.ai 仪表板](https://clore.ai):

1. 登录到你的账户
2. 导航到 **API** 设置中的部分
3. 生成并复制你的 API 密钥

**头部格式：**

```
auth: YOUR_API_KEY
```

> ⚠️ **重要：** auth 头部是 `auth`, **而不是** `Authorization: Bearer`。使用错误格式将返回代码 `3` （无效的 API 令牌）。

**示例：**

```bash
curl -H 'auth: YOUR_API_KEY' 'https://api.clore.ai/v1/marketplace'
```

***

## 快速开始

### 列出市场服务器

浏览所有可用的 GPU 服务器：

```bash
curl -XGET \
  -H 'auth: YOUR_API_KEY' \
  'https://api.clore.ai/v1/marketplace'
```

**响应：**

```json
{
  "servers": [
    {
      "id": 6,
      "owner": 4,
      "mrl": 73,
      "price": {
        "on_demand": { "bitcoin": 0.00001 },
        "spot": { "bitcoin": 0.000001 }
      },
      "rented": false,
      "specs": {
        "cpu": "Intel Core i9-11900",
        "ram": 62.67,
        "gpu": "1x NVIDIA GeForce GTX 1080 Ti",
        "gpuram": 11,
        "net": { "up": 26.38, "down": 118.42, "cc": "CZ" }
      }
    }
  ],
  "my_servers": [1, 2, 4],
  "code": 0
}
```

***

### 获取你的订单

```bash
curl -XGET \
  -H 'auth: YOUR_API_KEY' \
  'https://api.clore.ai/v1/my_orders'
```

包含已完成/已过期订单：

```bash
curl -XGET \
  -H 'auth: YOUR_API_KEY' \
  'https://api.clore.ai/v1/my_orders?return_completed=true'
```

***

### 创建订单（按需）

```bash
curl -XPOST \
  -H 'auth: YOUR_API_KEY' \
  -H 'Content-type: application/json' \
  -d '{
    "currency": "bitcoin",
    "image": "cloreai/ubuntu20.04-jupyter",
    "renting_server": 6,
    "type": "on-demand",
    "ports": {
      "22": "tcp",
      "8888": "http"
    },
    "ssh_password": "YourSSHPassword123",
    "jupyter_token": "YourJupyterToken123"
  }' \
  'https://api.clore.ai/v1/create_order'
```

**响应：**

```json
{ "code": 0 }
```

***

### 创建一个现货订单

现货订单更便宜，但可能会被更高出价者抢走。你可以设置每天的价格：

```bash
curl -XPOST \
  -H 'auth: YOUR_API_KEY' \
  -H 'Content-type: application/json' \
  -d '{
    "currency": "bitcoin",
    "image": "cloreai/ubuntu20.04-jupyter",
    "renting_server": 6,
    "type": "spot",
    "spotprice": 0.000005,
    "ports": {
      "22": "tcp",
      "8888": "http"
    },
    "ssh_password": "YourSSHPassword123"
  }' \
  'https://api.clore.ai/v1/create_order'
```

***

### 自动续租 48 小时

在最大租期（`mrl`）短于 48 小时的服务器上，只要续租价格不高于你的 `auto_renew_max_price` 每一天的上限，订单会在每个期限结束时按当时主机的价格续租，并在 48 小时用完后结束。省略 `rental_hours` 即可一直续租直到你取消。若没有 `auto_renew`，超过服务器 `mrl` 的小时数将被拒绝，返回 `rental_hours_exceeds_mrl`.

```bash
curl -XPOST \
  -H 'auth: YOUR_API_KEY' \
  -H 'Content-type: application/json' \
  -d '{
    "currency": "CLORE-Blockchain",
    "image": "cloreai/jupyter:ubuntu24.04-v2",
    "renting_server": 6,
    "type": "on-demand",
    "rental_hours": 48,
    "auto_renew": true,
    "auto_renew_max_price": 250,
    "ports": {
      "22": "tcp",
      "8888": "http"
    },
    "ssh_password": "YourSSHPassword123"
  }' \
  'https://api.clore.ai/v1/create_order'
```

**响应：**

```json
{ "code": 0 }
```

***

### 检查订单状态

```bash
curl -XGET \
  -H 'auth: YOUR_API_KEY' \
  'https://api.clore.ai/v1/my_orders'
```

活动订单包括 `pub_cluster` （主机名）和 `tcp_ports` 用于 SSH 访问：

```json
{
  "id": 38,
  "pub_cluster": ["n1.c1.clorecloud.net", "n2.c1.clorecloud.net"],
  "tcp_ports": ["22:10000"],
  "http_port": "8888"
}
```

SSH 登录到你的租用服务器：

```bash
ssh root@n1.c1.clorecloud.net -p 10000
```

### 更改自动续租

开启续租、更改价格上限，或更改正在运行的按需订单的总小时数。省略的字段会保持其值，并且 `"rental_hours": null` 会移除小时限制。此请求会让订单持续续租，直到你取消它：

```bash
curl -XPOST \
  -H 'auth: YOUR_API_KEY' \
  -H 'Content-type: application/json' \
  -d '{
    "order_id": 38,
    "rental_hours": null,
    "auto_renew": true,
    "auto_renew_max_price": 250
  }' \
  'https://api.clore.ai/v1/set_order_auto_renew'
```

发送 `{ "order_id": 38, "auto_renew": false }` 以停止续租；随后订单将在当前期限结束时终止。在一个期限的最后 60 秒内，该请求会被拒绝，返回 `renewal_in_progress`；请在订单续租或结束后重试。 `my_orders` 会在以下字段中显示结果： `auto_renew`, `auto_renew_max_price`, `rental_hours`, `rental_end` 和 `term_end`.

### 读取续租历史

```bash
curl -XPOST \
  -H 'auth: YOUR_API_KEY' \
  -H 'Content-type: application/json' \
  -d '{ "order_id": 38 }' \
  'https://api.clore.ai/v1/order_renewals'
```

**响应** （最新在前，每次续租决策一行，已续租或已拒绝）：

```json
{
  "renewals": [
    {
      "order_id": 38,
      "renewal_no": 1,
      "outcome": "renewed",
      "decided_at": 1667487630,
      "applied_at": 1667487631,
      "old_price": 200,
      "new_price": 220,
      "cap": 250,
      "term_seconds": 86400,
      "term_start": 1667487600,
      "term_end": 1667574000
    }
  ],
  "code": 0
}
```

***

### 取消订单

```bash
curl -XPOST \
  -H 'auth: YOUR_API_KEY' \
  -H 'Content-type: application/json' \
  -d '{
    "id": 38
  }' \
  'https://api.clore.ai/v1/cancel_order'
```

可选地报告服务器问题：

```bash
curl -XPOST \
  -H 'auth: YOUR_API_KEY' \
  -H 'Content-type: application/json' \
  -d '{
    "id": 38,
    "issue": "GPU 过热并导致性能降频"
  }' \
  'https://api.clore.ai/v1/cancel_order'
```

***

## Python SDK

一个使用 `requests` 库的轻量级封装。安装方式：

```bash
pip install requests
```

### CloreClient 类

```python
import requests
import time

class CloreClient:
    """Clore.ai REST API 的简单 Python SDK。"""
    
    BASE_URL = "https://api.clore.ai/v1"
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.session = requests.Session()
        self.session.headers.update({"auth": api_key})
    
    def _get(self, endpoint: str, params: dict = None) -> dict:
        url = f"{self.BASE_URL}/{endpoint}"
        response = self.session.get(url, params=params)
        response.raise_for_status()
        data = response.json()
        if data.get("code") != 0:
            raise CloreAPIError(data)
        return data
    
    def _post(self, endpoint: str, body: dict) -> dict:
        url = f"{self.BASE_URL}/{endpoint}"
        self.session.headers.update({"Content-type": "application/json"})
        response = self.session.post(url, json=body)
        response.raise_for_status()
        data = response.json()
        if data.get("code") != 0:
            raise CloreAPIError(data)
        return data
    
    def list_servers(self) -> list:
        """获取市场上所有可用服务器。"""
        data = self._get("marketplace")
        return data["servers"]
    
    def get_server_details(self, server_id: int) -> dict:
        """获取特定服务器的现货市场信息。"""
        data = self._get("spot_marketplace", params={"market": server_id})
        return data["market"]
    
    def create_order(
        self,
        server_id: int,
        image: str,
        order_type: str = "on-demand",
        currency: str = "bitcoin",
        spotprice: float = None,
        ports: dict = None,
        ssh_password: str = None,
        ssh_key: str = None,
        jupyter_token: str = None,
        env: dict = None,
        command: str = None,
    ) -> dict:
        """
        创建按需或现货订单。
        
        参数：
            server_id：要租用的服务器 ID
            image：Docker 镜像（例如 'cloreai/ubuntu20.04-jupyter'）
            order_type：'on-demand' 或 'spot'
            currency：'bitcoin'（默认）
            spotprice：现货订单必需——以 BTC 计的每日价格
            ports：端口转发，例如 {"22": "tcp", "8888": "http"}
            ssh_password：SSH 密码（仅限字母数字字符）
            ssh_key：SSH 公钥
            jupyter_token：Jupyter 笔记本令牌
            env：环境变量字典
            command：容器启动后运行的 Shell 命令
        """
        if order_type == "spot" and spotprice is None:
            raise ValueError("spotprice 是现货订单所必需的")
        
        body = {
            "currency": currency,
            "image": image,
            "renting_server": server_id,
            "type": order_type,
        }
        
        if spotprice is not None:
            body["spotprice"] = spotprice
        if ports:
            body["ports"] = ports
        if ssh_password:
            body["ssh_password"] = ssh_password
        if ssh_key:
            body["ssh_key"] = ssh_key
        if jupyter_token:
            body["jupyter_token"] = jupyter_token
        if env:
            body["env"] = env
        if command:
            body["command"] = command
        
        return self._post("create_order", body)
    
    def get_orders(self, include_completed: bool = False) -> list:
        """获取你的活动（以及可选的已完成）订单。"""
        params = {"return_completed": "true"} if include_completed else {}
        data = self._get("my_orders", params=params)
        return data["orders"]
    
    def cancel_order(self, order_id: int, issue: str = None) -> dict:
        """取消订单。可选地报告问题。"""
        body = {"id": order_id}
        if issue:
            body["issue"] = issue
        return self._post("cancel_order", body)
    
    def get_wallets(self) -> list:
        """获取你的钱包和余额。"""
        data = self._get("wallets")
        return data["wallets"]
    
    def get_my_servers(self) -> list:
        """获取你提供给市场的服务器。"""
        data = self._get("my_servers")
        return data["servers"]


class CloreAPIError(Exception):
    """当 Clore API 返回非零代码时抛出。"""
    
    ERROR_CODES = {
        0: "正常",
        1: "数据库错误",
        2: "无效输入数据",
        3: "无效 API 令牌",
        4: "无效端点",
        5: "超过速率限制（1 请求/秒）",
        6: "错误（参见 error 字段）",
    }
    
    def __init__(self, response: dict):
        self.code = response.get("code")
        self.error = response.get("error", "")
        message = self.ERROR_CODES.get(self.code, f"未知代码 {self.code}")
        if self.error:
            message = f"{message}：{self.error}"
        super().__init__(f"Clore API 错误 {self.code}：{message}")
```

### 完整可运行示例

```python
import os
from clore_client import CloreClient, CloreAPIError

# 初始化客户端
client = CloreClient(api_key=os.environ["CLORE_API_KEY"])

# 1. 浏览市场
servers = client.list_servers()
print(f"在市场上找到 {len(servers)} 台服务器")

# 2. 筛选可用的 RTX 4090 服务器
rtx4090_servers = [
    s for s in servers
    if "4090" in s["specs"].get("gpu", "") and not s["rented"]
]

if not rtx4090_servers:
    print("未找到可用的 RTX 4090 服务器")
    exit(1)

# 3. 选择最便宜的那个
cheapest = min(rtx4090_servers, key=lambda s: s["price"]["on_demand"]["bitcoin"] )
print(f"最便宜的 RTX 4090：服务器 ID {cheapest['id']}，"
      f"价格 {cheapest['price']['on_demand']['bitcoin']:.8f} BTC/天")

# 4. 创建订单
try:
    client.create_order(
        server_id=cheapest["id"],
        image="cloreai/ubuntu20.04-jupyter",
        order_type="on-demand",
        currency="bitcoin",
        ports={"22": "tcp", "8888": "http"},
        ssh_password="SecurePass123",
        jupyter_token="MyToken123",
    )
    print("订单创建成功！")
except CloreAPIError as e:
    print(f"创建订单失败：{e}")
    exit(1)

# 5. 检查你的订单
orders = client.get_orders()
for order in orders:
    if not order.get("expired"):
        cluster = order.get("pub_cluster", [])
        tcp = order.get("tcp_ports", [])
        print(f"订单 {order['id']}: 服务器 {order['si']}")
        if cluster and tcp:
            ssh_port = tcp[0].split(":")[1]
            print(f"  SSH: ssh root@{cluster[0]} -p {ssh_port}")
```

***

## Node.js 示例

使用原生 `fetch` API（Node.js 18+）：

```javascript
const BASE_URL = 'https://api.clore.ai/v1';

class CloreClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.defaultHeaders = {
      'auth': apiKey,
    };
  }

  async get(endpoint, params = {}) {
    const url = new URL(`${BASE_URL}/${endpoint}`);
    Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
    
    const res = await fetch(url.toString(), {
      headers: this.defaultHeaders,
    });
    
    const data = await res.json();
    if (data.code !== 0) {
      throw new Error(`Clore API 错误 ${data.code}: ${data.error || 'unknown'}`);
    }
    return data;
  }

  async post(endpoint, body) {
    const res = await fetch(`${BASE_URL}/${endpoint}`, {
      method: 'POST',
      headers: {
        ...this.defaultHeaders,
        'Content-type': 'application/json',
      },
      body: JSON.stringify(body),
    });
    
    const data = await res.json();
    if (data.code !== 0) {
      throw new Error(`Clore API 错误 ${data.code}: ${data.error || 'unknown'}`);
    }
    return data;
  }

  async listServers() {
    const data = await this.get('marketplace');
    return data.servers;
  }

  async getOrders(includeCompleted = false) {
    const params = includeCompleted ? { return_completed: 'true' } : {};
    const data = await this.get('my_orders', params);
    return data.orders;
  }

  async createOrder({ serverId, image, type = 'on-demand', currency = 'bitcoin', spotprice, ports, sshPassword, jupyterToken, env, command }) {
    const body = {
      currency,
      image,
      renting_server: serverId,
      type,
      ...(spotprice && { spotprice }),
      ...(ports && { ports }),
      ...(sshPassword && { ssh_password: sshPassword }),
      ...(jupyterToken && { jupyter_token: jupyterToken }),
      ...(env && { env }),
      ...(command && { command }),
    };
    return this.post('create_order', body);
  }

  async cancelOrder(orderId, issue = null) {
    const body = { id: orderId };
    if (issue) body.issue = issue;
    return this.post('cancel_order', body);
  }
}

// 用法示例
const client = new CloreClient(process.env.CLORE_API_KEY);

async function main() {
  // 列出市场
  const servers = await client.listServers();
  console.log(`市场中有 ${servers.length} 台服务器`);

  // 查找可用的 RTX 4090 服务器
  const available = servers.filter(
    s => s.specs.gpu.includes('4090') && !s.rented
  );
  console.log(`可用的 RTX 4090 服务器：${available.length}`);

  // 获取当前订单
  const orders = await client.getOrders();
  const activeOrders = orders.filter(o => !o.expired);
  console.log(`活跃订单：${activeOrders.length}`);

  for (const order of activeOrders) {
    const host = order.pub_cluster?.[0];
    const portMapping = order.tcp_ports?.[0];
    if (host && portMapping) {
      const sshPort = portMapping.split(':')[1];
      console.log(`订单 ${order.id} → ssh root@${host} -p ${sshPort}`);
    }
  }
}

main().catch(console.error);
```

***

## 常见工作流

### 寻找最便宜的 RTX 4090 并租用

```python
from clore_client import CloreClient

client = CloreClient(api_key="YOUR_API_KEY")

def rent_cheapest_rtx4090(image="cloreai/ubuntu20.04-jupyter", ssh_password="SecurePass123"):
    servers = client.list_servers()
    
    # 筛选：可用的 RTX 4090
    candidates = [
        s for s in servers
        if "4090" in s["specs"].get("gpu", "")
        and not s["rented"]
    ]
    
    if not candidates:
        raise RuntimeError("未找到可用的 RTX 4090 服务器")
    
    # 按按需 BTC 价格排序
    candidates.sort(key=lambda s: s["price"]["on_demand"]["bitcoin"])

    best = candidates[0]
    
    price_btc = best["price"]["on_demand"]["bitcoin"]
    print(f"正在租用服务器 {best['id']}: {best['specs']['gpu']} @ {price_btc:.8f} BTC/天")
    
    client.create_order(
        server_id=best["id"],
        image=image,
        order_type="on-demand",
        currency="bitcoin",
        ports={"22": "tcp"},
        ssh_password=ssh_password,
    )
    
    print("完成！请在订单中查看 SSH 连接详情。")
    return best["id"]

rent_cheapest_rtx4090()
```

***

### 监控我的订单

```python
import time
from clore_client import CloreClient

client = CloreClient(api_key="YOUR_API_KEY")

def monitor_orders(poll_interval_seconds=60):
    """轮询订单并打印状态更新。"""
    print(f"监控订单中（每 {poll_interval_seconds} 秒轮询一次）。按 Ctrl+C 停止。\n")
    
    while True:
        orders = client.get_orders(include_completed=False)
        active = [o for o in orders if not o.get("expired")]
        
        print(f"--- {len(active)} 个活跃订单 ---")
        for order in active:
            cluster = order.get("pub_cluster", [])
            tcp = order.get("tcp_ports", [])
            spend = order.get("spend", 0)
            
            ssh_info = ""
            if cluster and tcp:
                port = tcp[0].split(":")[1]
                ssh_info = f" | SSH: {cluster[0]}:{port}"
            
            print(f"  订单 {order['id']}: 服务器 {order['si']}"
                  f" | 已花费 {spend:.8f} BTC{ssh_info}")
        
        if not active:
            print("  没有活跃订单。")
        
        print()
        time.sleep(poll_interval_seconds)

monitor_orders()
```

***

### 当价格跌破 X 时自动租用

```python
import time
from clore_client import CloreClient

client = CloreClient(api_key="YOUR_API_KEY")

def auto_rent_on_price_drop(
    gpu_model: str = "RTX 4090",
    max_price_btc: float = 0.00015,
    image: str = "cloreai/ubuntu20.04-jupyter",
    ssh_password: str = "SecurePass123",
    check_interval_seconds: int = 120,
):
    """
    监控市场，当价格低于阈值时自动租用 GPU。
    
    参数：
        gpu_model: 要搜索的 GPU 名称（不区分大小写）
        max_price_btc: 每天可接受的最高 BTC 价格
        image: 要部署的 Docker 镜像
        ssh_password: 容器的 SSH 密码
        check_interval_seconds: 检查频率（请注意速率限制！）
    """
    print(f"正在监视 {gpu_model}，价格不高于 {max_price_btc:.8f} BTC/天...")
    
    while True:
        servers = client.list_servers()
        
        for server in servers:
            gpu = server["specs"].get("gpu", "")
            if gpu_model.lower() not in gpu.lower():
                continue
            if server["rented"]:
                continue
            
            price = server["price"]["on_demand"]["bitcoin"]
            if price <= max_price_btc:
                print(f"🎯 找到匹配项！服务器 {server['id']}: {gpu} @ {price:.8f} BTC/天")
                
                try:
                    client.create_order(
                        server_id=server["id"],
                        image=image,
                        order_type="on-demand",
                        currency="bitcoin",
                        ports={"22": "tcp"},
                        ssh_password=ssh_password,
                        required_price=price,  # 锁定此价格
                    )
                    print(f"✅ 已为服务器 {server['id']} 创建订单！")
                    return server["id"]
                except Exception as e:
                    print(f"创建订单失败：{e}。将重试...")
        
        print(f"暂未匹配。将在 {check_interval_seconds}s 后再次检查...")
        time.sleep(check_interval_seconds)

auto_rent_on_price_drop(gpu_model="4090", max_price_btc=0.00012)
```

***

## WebSocket

Clore.ai REST API 目前不提供 WebSocket 端点。对于实时监控，请使用合理间隔的轮询（见下方速率限制）。

***

## 速率限制

| 端点                    | 限制            |
| --------------------- | ------------- |
| 大多数端点                 | **1 次请求/秒**   |
| `create_order`        | **1 次请求/5 秒** |
| `set_spot_price` （降价） | 每 **600 秒一次** |

**速率限制响应（代码 5）：**

```json
{ "code": 5 }
```

**最佳实践：**

* 添加 `time.sleep(1)` 在连续 API 调用之间
* 对于 `create_order`，请求之间至少等待 5 秒
* 监控循环建议使用 60 秒以上的轮询间隔
* 如果需要频繁查询，可将市场数据缓存在本地

**Python 辅助函数：**

```python
import time

def safe_api_call(fn, *args, delay=1.1, **kwargs):
    """对 API 调用进行速率限制安全封装。"""
    result = fn(*args, **kwargs)
    time.sleep(delay)
    return result
```

***

## 错误处理

每个 API 响应都包含一个 `code` 字段。值为 `0` 表示成功。

### 错误代码

| 代码  | 含义                | 操作               |
| --- | ----------------- | ---------------- |
| `0` | 成功                | —                |
| `1` | 数据库错误             | 延迟后重试            |
| `2` | 无效输入数据            | 检查你的请求体/参数       |
| `3` | 无效的 API 令牌        | 在仪表板中验证你的 API 密钥 |
| `4` | 无效端点              | 检查端点 URL         |
| `5` | 超过速率限制（1 次请求/秒）   | 在请求之间添加延迟        |
| `6` | 应用程序错误（见 `错误` 字段） | 阅读 `错误` 字段以了解详情  |

### 代码 6 子错误

| `错误` 值                        | 含义                                    |
| ----------------------------- | ------------------------------------- |
| `exceeded_max_step`           | 现货价格降幅过大；检查 `max_step` 字段             |
| `can_lower_every_600_seconds` | 必须等待后才能再次降低现货价格；检查 `time_to_lowering` |

### Python 错误处理示例

```python
from clore_client import CloreClient, CloreAPIError
import time

client = CloreClient(api_key="YOUR_API_KEY")

def create_order_with_retry(server_id, image, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.create_order(
                server_id=server_id,
                image=image,
                order_type="on-demand",
                currency="bitcoin",
                ports={"22": "tcp"},
                ssh_password="SecurePass123",
            )
        except CloreAPIError as e:
            if e.code == 5:  # 速率限制
                print(f"速率受限。等待 5 秒...（第 {attempt+1}/{max_retries} 次尝试）")
                time.sleep(5)
            elif e.code == 3:  # 无效 API 密钥
                print("无效的 API 密钥！请检查你的 CLORE_API_KEY。")
                raise
            elif e.code == 2:  # 输入错误
                print(f"无效请求：{e}")
                raise
            else:
                print(f"API 错误：{e}。3 秒后重试...")
                time.sleep(3)
    
    raise RuntimeError(f"在 {max_retries} 次尝试后失败")
```

### JavaScript 错误处理示例

```javascript
async function createOrderWithRetry(client, serverConfig, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.createOrder(serverConfig);
    } catch (err) {
      const code = parseInt(err.message.match(/error (\d+)/)?.[1]);
      
      if (code === 5) {
        console.log(`速率受限。等待 5 秒...（第 ${attempt + 1}/${maxRetries} 次尝试）`);
        await new Promise(r => setTimeout(r, 5000));
      } else if (code === 3) {
        throw new Error('无效的 API 密钥');
      } else {
        console.log(`API 错误：${err.message}。3 秒后重试...`);
        await new Promise(r => setTimeout(r, 3000));
      }
    }
  }
  throw new Error(`在 ${maxRetries} 次尝试后失败`);
}
```

***

## 可用的 Docker 镜像

Clore.ai 提供了针对 GPU 工作负载优化的预构建镜像：

| 镜像                            | 描述                        |
| ----------------------------- | ------------------------- |
| `cloreai/ubuntu20.04-jupyter` | Ubuntu 20.04 + JupyterLab |
| `cloreai/ubuntu22.04-jupyter` | Ubuntu 22.04 + JupyterLab |

你也可以使用任何公共 Docker Hub 镜像。要访问 GPU，请使用启用 CUDA 的镜像，例如：

```
nvidia/cuda:12.1.0-devel-ubuntu22.04
```

***

## 端口转发

创建订单时，请指定要暴露的端口：

```json
{
  "ports": {
    "22": "tcp",
    "8888": "http",
    "6006": "http"
  }
}
```

* **`"tcp"`** — 直接 TCP 端口转发（用于 SSH、自定义服务器）
* **`"http"`** — HTTPS 代理（用于 Jupyter、Web 界面）。每个只能允许一个 HTTP 端口 `http_port` 字段。

创建订单后，连接详情会显示在 `my_orders`:

```json
{
  "pub_cluster": ["n1.c1.clorecloud.net", "n2.c1.clorecloud.net"],
  "tcp_ports": ["22:10000"],
  "http_port": "8888"
}
```

通过 SSH 连接：

```bash
ssh root@n1.c1.clorecloud.net -p 10000
```

通过浏览器访问 Jupyter： `https://n1.c1.clorecloud.net` （使用 `http_port`)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.clore.ai/clore.ai/clore.ai-eng-zh/kai-fa-zhe/cli-sdk.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
