Python SDK（clore-ai）

该 clore-ai 软件包是官方的 Python SDK，用于 Clore.ai GPU 市场。它将完整的 REST API 封装为一个简洁、类型安全的接口，内置速率限制、自动重试和结构化错误处理 —— 让你可以专注于租用 GPU，而不是处理 HTTP 细节。

---

安装

pip install clore-ai

要求： Python 3.9+

该软件包同时安装 Python SDK 和 clore 命令行工具（CLI）.

---

认证

从 Clore.ai 仪表板 → API 部分获取你的 API 密钥。

选项 1：环境变量（推荐）

export CLORE_API_KEY=your_api_key_here

SDK 会自动读取 CLORE_API_KEY —— 无需更改代码。

选项 2：CLI 配置文件

clore config set api_key YOUR_API_KEY

这会将密钥存储在 ~/.clore/config.json.

选项 3：在代码中直接传入

from clore_ai import CloreAI

client = CloreAI(api_key="your_api_key_here")

⚠️ 重要： Clore.ai API 使用 auth 头进行认证， 而不是 Authorization: Bearer。SDK 会自动处理这一点。

---

快速开始

from clore_ai import CloreAI

client = CloreAI()
servers = client.marketplace(gpu="RTX 4090", max_price_usd=5.0)
for s in servers:
    print(f"Server {s.id}: {s.gpu_model} — ${s.price_usd:.4f}/h")

---

同步客户端（CloreAI)

构造函数

CloreAI(
    api_key: str | None = None,       # 回退到 CLORE_API_KEY 环境变量 / 配置
    base_url: str | None = None,       # 默认： https://api.clore.ai/v1
    timeout: float = 30.0,             # 请求超时（秒）
    max_retries: int = 3               # 在速率限制 / 网络错误时的重试次数
)

客户端支持上下文管理器以自动清理：

with CloreAI() as client:
    wallets = client.wallets()
    # client.close() 会自动调用

---

wallets()

获取你的钱包余额和充值地址。

wallets = client.wallets()

for wallet in wallets:
    print(f"{wallet.name}: {wallet.balance:.8f}")
    if wallet.deposit:
        print(f"  Deposit: {wallet.deposit}")

返回： List[Wallet]

字段	类型	描述
name	str	货币名称（例如 "bitcoin", "CLORE-Blockchain", "USD-Blockchain")
balance	float | None	当前余额
deposit	str | None	充值地址
withdrawal_fee	float | None	提现费用

---

marketplace()

使用可选的客户端过滤器搜索 GPU 市场。

# 所有可用服务器
servers = client.marketplace()

# 按 GPU 型号和最高价格过滤
servers = client.marketplace(
    gpu="RTX 4090",
    max_price_usd=5.0
)

# 多 GPU 机组并配备大量内存
servers = client.marketplace(
    min_gpu_count=4,
    min_ram_gb=128.0
)

参数：

参数	类型	默认	描述
gpu	str | None	None	按 GPU 型号过滤（不区分大小写的子字符串匹配）
min_gpu_count	int | None	None	最少 GPU 数量
min_ram_gb	float | None	None	最小内存（GB）
max_price_usd	float | None	None	每小时最高价格（美元）
available_only	bool	True	仅返回可租用的服务器

返回： List[MarketplaceServer]

每个 MarketplaceServer 为最常用字段提供便捷属性，并可访问完整的嵌套数据：

属性	类型	描述
id	int	唯一服务器 ID
gpu_model	str | None	主 GPU 描述（例如 "1x NVIDIA GeForce RTX 4090")
gpu_count	int	GPU 数量（来自 gpu_array)
ram_gb	float | None	内存（GB）
price_usd	float | None	按需价格（美元）
spot_price_usd	float | None	竞价价格（美元）
available	bool	服务器是否可用（未被租用）
location	str | None	来自网络规格的国家代码

对于高级用例，你可以访问完整的嵌套结构：

字段	类型	描述
specs	ServerSpecs | None	完整硬件规格（specs.gpu, specs.ram, specs.cpu, specs.disk, specs.net，等等）
price	ServerPrice | None	完整价格对象（price.usd.on_demand_usd, price.usd.spot, price.on_demand，等等）
rented	bool | None	服务器当前是否被租用
reliability	float | None	服务器可靠性评分
rating	ServerRating | None	服务器评分（rating.avg, rating.cnt)

注意： 该 marketplace() 该端点是公开的 — 无需 API 密钥即可使用。

---

my_servers()

列出你在 Clore.ai 市场上提供的服务器。

my_servers = client.my_servers()

for server in my_servers:
    print(f"{server.name}: {server.gpu_model} [{server.status}]")

返回： List[MyServer]

属性	类型	描述
id	int	服务器 ID
name	str | None	服务器名称
gpu_model	str | None	主 GPU 描述
ram_gb	float | None	内存（GB）
status	str	可读的状态： "Online", "Offline", "Disconnected"，或 "Not Working"
connected	bool | None	服务器是否已连接
online	bool | None	服务器是否在线
visibility	str | None	"public" 或 "private"

---

server_config(server_name)

获取你托管的特定服务器的配置。

config = client.server_config("MyGPU")

print(f"Server: {config.name}")
print(f"GPU: {config.gpu_model}")
print(f"Min rental: {config.mrl}h")
print(f"On-demand: ${config.on_demand_price}")
print(f"Spot: ${config.spot_price}")

参数：

参数	类型	描述
server_name	str	服务器名称

返回： ServerConfig

属性	类型	描述
name	str | None	服务器名称
gpu_model	str | None	主 GPU 描述
mrl	int | None	最短租期（小时）
on_demand_price	float | None	可用的首个按需美元价格
spot_price	float | None	可用的首个竞价美元价格
specs	ServerSpecs | None	完整硬件规格
connected	bool | None	服务器是否已连接
visibility	str | None	"public" 或 "private"

---

my_orders(include_completed)

获取你当前的订单，可选择包含已完成/已过期的订单。

# 仅活动订单
orders = client.my_orders()

# 包含已完成的订单
all_orders = client.my_orders(include_completed=True)

for order in orders:
    print(f"Order {order.id}: {order.type} — {order.status}")
    if order.pub_cluster:
        print(f"  IP: {order.pub_cluster}")
    if order.tcp_ports:
        print(f"  Ports: {order.tcp_ports}")

参数：

参数	类型	默认	描述
include_completed	bool	False	是否包含已完成/已过期的订单

返回： List[Order]

字段	类型	描述
id	int	唯一订单 ID
server_id	int | None	服务器 ID
type	str	"on-demand" 或 "spot"
status	str | None	订单状态
image	str | None	Docker 镜像
currency	str | None	支付货币
price	float | None	订单每日价格
pub_cluster	str | None	用于访问的公共主机名 / IP
tcp_ports	dict | None	TCP 端口映射

---

spot_marketplace(server_id)

查看特定服务器的竞价市场报价。

spot = client.spot_marketplace(server_id=6)

if spot.offers:
    for offer in spot.offers:
        print(f"Order {offer.order_id}: ${offer.price}/day (server {offer.server_id})")

if spot.currency_rates_in_usd:
    for coin, rate in spot.currency_rates_in_usd.items():
        print(f"  {coin}: ${rate}")

参数：

参数	类型	描述
server_id	int	要检查的服务器 ID

返回： SpotMarket

字段	类型	描述
offers	List[SpotOffer] | None	竞价报价列表（order_id, price, server_id)
server	SpotServerInfo | None	服务器信息（最低定价、可见性、在线状态）
currency_rates_in_usd	Dict[str, float] | None	以美元计的货币汇率

---

create_order(...)

创建新的按需或竞价订单。这是你租用 GPU 的方式。

按需订单

order = client.create_order(
    server_id=123,
    image="cloreai/ubuntu22.04-cuda12",
    type="on-demand",
    currency="bitcoin",
    ssh_password="MySecurePass123",
    ports={"22": "tcp", "8888": "http"}
)

print(f"Order created: {order.id}")
print(f"Connect: {order.pub_cluster}")

竞价订单

order = client.create_order(
    server_id=123,
    image="cloreai/pytorch",
    type="spot",
    currency="bitcoin",
    spot_price=0.000005,
    ssh_password="MySecurePass123",
    ports={"22": "tcp"}
)

参数：

参数	类型	必需	描述
server_id	int	是	要租用的服务器 ID
image	str	是	Docker 镜像（例如 "cloreai/ubuntu22.04-cuda12")
type	str	是	"on-demand" 或 "spot"
currency	str	是	支付货币（例如 "bitcoin")
ssh_password	str	否	SSH 密码（字母数字，最多 32 个字符）
ssh_key	str	否	SSH 公钥（最多 3072 个字符）
ports	dict	否	端口映射，例如 {"22": "tcp", "8888": "http"}
env	dict	否	环境变量
jupyter_token	str	否	Jupyter 笔记本令牌（最多 32 个字符）
command	str	否	容器启动后要运行的 shell 命令
spot_price	float	仅限竞价	竞价订单的每日价格
required_price	float	否	锁定特定价格（仅限按需）
autossh_entrypoint	str	否	使用 Clore.ai SSH 入口点

返回： 订单

速率限制： create_order 在调用之间有一个特殊的 5 秒冷却时间。SDK 会自动强制执行。

---

cancel_order(order_id, issue)

取消活动订单或竞价报价。可选地报告服务器问题。

# 简单取消
client.cancel_order(order_id=38)

# 带问题报告的取消
client.cancel_order(
    order_id=38,
    issue="GPU #1 was overheating and throttling"
)

参数：

参数	类型	必需	描述
order_id	int	是	要取消的订单 ID
issue	str	否	取消原因 / 问题报告（最多 2048 个字符）

返回： Dict[str, Any]

---

set_server_settings(...)

更新你在市场上托管的服务器的设置。

client.set_server_settings(
    name="MyGPU",
    availability=True,
    mrl=96,
    on_demand=0.0001,
    spot=0.00000113
)

参数：

参数	类型	必需	描述
name	str	是	服务器名称
availability	bool	否	服务器是否可以被租用
mrl	int	否	最短租期（小时）
on_demand	float	否	按需每日价格
spot	float	否	最低竞价每日价格

返回： Dict[str, Any]

---

set_spot_price(order_id, price)

更新你在竞价市场报价的价格。

client.set_spot_price(order_id=39, price=0.000003)

参数：

参数	类型	描述
order_id	int	竞价订单/报价 ID
price	float	新的每日价格

返回： Dict[str, Any]

注意： 你只能每 600 秒降低一次竞价价格，且降幅有步进限制。如果超出这些限制，API 会返回 code: 6 并提供详细信息。

---

异步客户端（AsyncCloreAI)

该 AsyncCloreAI 客户端提供与 CloreAI相同的方法，但所有方法都返回协程。当你需要并发 API 调用或在异步应用中工作时使用它。

基本用法

import asyncio
from clore_ai import AsyncCloreAI

async def main():
    async with AsyncCloreAI(api_key="your_key") as client:
        wallets = await client.wallets()
        for w in wallets:
            print(f"{w.name}: {w.balance:.8f}")

asyncio.run(main())

并发操作

使用 asyncio.gather:

import asyncio
from clore_ai import AsyncCloreAI

async def compare_gpus():
    async with AsyncCloreAI() as client:
        # 并发搜索多个 GPU 型号
        rtx4090, rtx3090, a100 = await asyncio.gather(
            client.marketplace(gpu="RTX 4090"),
            client.marketplace(gpu="RTX 3090"),
            client.marketplace(gpu="A100"),
        )

        for name, servers in [("RTX 4090", rtx4090), ("RTX 3090", rtx3090), ("A100", a100)]:
            if servers:
                cheapest = min(s.price_usd or float('inf') for s in servers)
                print(f"{name}: {len(servers)} available, cheapest ${cheapest:.4f}/h")
            else:
                print(f"{name}: none available")

asyncio.run(compare_gpus())

可用方法

AsyncCloreAI 支持与 CloreAI:

相同的所有方法	描述
方法	await wallets()
获取钱包余额	await marketplace(...)
搜索市场	await my_servers()
列出你托管的服务器	await server_config(name)
获取服务器配置	await my_orders(...)
列出你的订单	await spot_marketplace(server_id)
获取竞价市场报价	await create_order(...)
创建新订单	await cancel_order(...)
取消订单	await set_server_settings(...)
更新服务器设置	await set_spot_price(...)

---

更新竞价价格

错误处理

from clore_ai import CloreAI
SDK 为每个 API 错误代码提供结构化的异常类。
    from clore_ai.exceptions import (
    CloreAPIError,      # 所有 API 错误的基类
    AuthError,          # 代码 3 — 无效的 API 密钥
    RateLimitError,     # 代码 5 — 超出速率限制
    InvalidInputError,  # 代码 2 — 错误的请求数据
    DBError,            # 代码 1 — 数据库错误（DBError）或数据库相关错误）
    FieldError，        # 代码 6 — 字段特定错误
)

client = CloreAI()

try:
    order = client.create_order(
        server_id=123,
        image="cloreai/ubuntu22.04-cuda12",
        type="on-demand",
        currency="bitcoin",
    )
except AuthError:
    print("无效的 API 密钥。请检查您的 CLORE_API_KEY。")
except RateLimitError:
    print("已触发速率限制。SDK 会自动重试，但您已达到最大重试次数。")
except InvalidInputError as e:
    print(f"错误的请求：{e}")
except FieldError as e:
    # 代码 6 的错误在响应中包含详细信息
    print(f"字段错误：{e}（详细信息：{e.response}）")
except CloreAPIError as e:
    print(f"API 错误：{e}（代码：{e.code}）")

错误代码

代码	异常	描述
0	—	成功
1	DBError	数据库错误
2	InvalidInputError	无效的输入数据
3	AuthError	无效的 API 令牌
4	InvalidEndpointError	无效的端点
5	RateLimitError	超出速率限制
6	FieldError	特定字段的错误（参见 error 响应中的 field）

所有异常类都继承自 CloreAPIError 并包含：

• e.code — 数字错误代码

• e.response — 完整的 API 响应字典（如可用）

---

速率限制

SDK 包含内置速率限制器，会自动强制执行 Clore.ai 的限制：

端点	限制
大多数端点	每秒 1 次请求
create_order	每 5 秒 1 次请求

当 API 返回速率限制错误（代码 5）时，SDK 会应用 指数退避 并重试最多 max_retries 次（默认：3）。您无需在调用之间添加 time.sleep() 。

工作原理

1. 在每次请求之前，速率限制器会等待直到最小间隔过去。

2. create_order 调用会强制额外的 5 秒冷却期。

3. 在速率限制错误时，SDK 会以指数方式退避：1s → 2s → 4s → ...

4. 在 max_retries 次失败尝试后，会引发 RateLimitError 。

自定义重试行为

client = CloreAI(
    max_retries=5,    # 长时间运行脚本可增加重试次数
    timeout=60.0      # 网络较慢时可延长超时时间
)

---

配置

配置文件

CLI 将配置存储在 ~/.clore/config.json:

{
  "api_key": "your_api_key_here"
}

解析顺序

SDK 按以下顺序解析 API 密钥：

1. api_key 传递给构造函数的参数

2. CLORE_API_KEY 环境变量

3. api_key 字段位于 ~/.clore/config.json

环境变量

变量	描述
CLORE_API_KEY	用于身份验证的 API 密钥

---

下一步

• CLI 参考 — 从终端使用 Clore.ai

• REST API — 用于自定义集成的原始 API 文档

• 按需与抢占式 — 了解定价模型

• 可用的 Docker 镜像 — 用于 GPU 工作负载的预构建镜像