Руководство по Python SDK

Полное руководство по Python SDK — синхронные/асинхронные клиенты, фильтрация на маркетплейсе, жизненный цикл ордеров, спотовый рынок, операции с кошельком и обработка ошибок

Новичок в SDK? Начните с 5-минутного быстрого старта сначала.

Для краткого руководства с реальными примерами см. Clore.ai Python SDK — автоматизируйте свои GPU-рабочие процессы за 5 минут

Установка

pip install clore-ai

SDK предоставляет два клиента:

• CloreAI — синхронный (проще, хорошо подходит для скриптов)

• AsyncCloreAI — асинхронный (быстрее для параллельных операций)

Оба используют одни и те же методы и возвращают одни и те же модели Pydantic.

---

Синхронный vs асинхронный — когда использовать каждый

Сценарий использования	Клиент	Почему
Простые скрипты, разовые задачи	CloreAI	Более простой код, без async/await
Циклы мониторинга	CloreAI	Последовательные проверки работают нормально
Массовые запросы к маркетплейсу	AsyncCloreAI	Параллельные запросы = быстрее
Пакетное создание заказов	AsyncCloreAI	Создание нескольких заказов параллельно
Веб-приложения	AsyncCloreAI	Неблокирующий ввод-вывод

Пример синхронного использования

from clore_ai import CloreAI

client = CloreAI()  # Использует переменную окружения CLORE_API_KEY

servers = client.marketplace(gpu="RTX 4090")
print(f"Найдено {len(servers)} серверов")

client.close()  # Или используйте контекстный менеджер

Пример асинхронного использования

import asyncio
from clore_ai import AsyncCloreAI

async def main():
    async with AsyncCloreAI() as client:
        servers = await client.marketplace(gpu="RTX 4090")
        print(f"Найдено {len(servers)} серверов")

asyncio.run(main())

Контекстные менеджеры (рекомендуется)

Оба клиента поддерживают контекстные менеджеры для автоматической очистки:

# Синхронно
with CloreAI() as client:
    wallets = client.wallets()

# Асинхронно
async with AsyncCloreAI() as client:
    wallets = await client.wallets()

---

Конфигурация клиента

client = CloreAI(
    api_key="your_key",      # Или задайте переменную окружения CLORE_API_KEY
    base_url="https://api.clore.ai/v1",  # Пользовательская API-эндпоинт
    timeout=30.0,            # Таймаут запроса в секундах
    max_retries=3            # Повторы при ограничении скорости / сетевых ошибках
)

SDK включает встроенный ограничитель скорости:

• Общие запросы: 1 запрос/секунду

• create_order: 5-секундная пауза между вызовами

• Ошибки ограничения скорости (код 5): Автоматический экспоненциальный backoff

---

Фильтрация маркетплейса

Параметр marketplace() метод получает все доступные серверы и фильтрует их на стороне клиента:

from clore_ai import CloreAI

client = CloreAI()

# Все доступные серверы
all_servers = client.marketplace()

# Фильтр по модели GPU (регистронезависимое совпадение подстроки)
rtx_4090s = client.marketplace(gpu="RTX 4090")

# Фильтр по нескольким критериям
budget_gpus = client.marketplace(
    gpu="RTX 4090",
    max_price_usd=1.0,       # Макс. $1.00/час
    min_gpu_count=2,          # Не менее 2 GPU
    min_ram_gb=64.0,          # Не менее 64 ГБ системной RAM
    available_only=True       # Только доступные серверы (по умолчанию)
)

Продвинутая фильтрация (на стороне клиента)

Для фильтров, не встроенных в метод, отфильтруйте возвращённые объекты Server самостоятельно:

servers = client.marketplace(gpu="RTX 4090")

# Серверы в ЕС с высокой надёжностью
eu_servers = [
    s for s in servers
    if s.location and s.location.upper() in ("DE", "FR", "NL", "FI")
    and s.reliability and s.reliability >= 0.95
]

# Сортировка по цене
cheapest = sorted(servers, key=lambda s: s.price_usd or float("inf"))
print(f"Самый дешёвый: сервер {cheapest[0].id} — ${cheapest[0].price_usd:.4f}/ч")

Поля модели сервера

Каждый объект MarketplaceServer имеет следующие атрибуты и удобные свойства:

Поле	Тип	Описание
id	int	ID сервера (используйте это в create_order)
gpu_model	str | None	Описание GPU из спецификаций (свойство)
gpu_count	int	Количество GPU из gpu_array (свойство)
ram_gb	float | None	Системная RAM в ГБ (свойство, из specs.ram)
price_usd	float | None	Цена по требованию в USD (свойство, из price.usd.on_demand_usd)
spot_price_usd	float | None	Спотовая цена в USD (свойство)
доступные	bool	Находится ли сервер не в аренде (свойство)
location	str | None	Код страны из сетевых спецификаций (свойство)
specs	ServerSpecs | None	Аппаратные характеристики (cpu, ram, disk, gpu, net)
price	ServerPrice | None	Полная структура ценообразования
rented	bool | None	Арендован ли сервер в данный момент

---

Управление заказами

Создание заказов

order = client.create_order(
    server_id=142,
    image="cloreai/ubuntu22.04-cuda12",
    type="on-demand",               # "on-demand" или "spot"
    currency="bitcoin",             # Валюта оплаты
    ssh_password="MySecurePass",    # Доступ по SSH
    ports={"22": "tcp", "8888": "http"},  # Сопоставление портов
    env={"HF_TOKEN": "hf_xxx"},    # Переменные окружения
    command="bash /start.sh",       # Пользовательская команда запуска
    jupyter_token="my_token"        # Токен Jupyter Notebook
)

print(f"ID заказа: {order.id}")
print(f"IP: {order.pub_cluster}")
print(f"Порты: {order.tcp_ports}")

Полная create_order Параметры

Параметр	Тип	Требуется	Описание
server_id	int	✅	Сервер для аренды
image	str	✅	Docker-образ
type	str	✅	"on-demand" или "spot"
currency	str	✅	Валюта оплаты (например, "bitcoin")
ssh_password	str	—	Пароль SSH
ssh_key	str	—	Публичный ключ SSH
ports	dict	—	Сопоставление портов ({"22": "tcp"})
env	dict	—	Переменные окружения
jupyter_token	str	—	Токен Jupyter Notebook
command	str	—	Команда запуска
spot_price	float	—	Цена ставки для спота
required_price	float	—	Требуемая цена
autossh_entrypoint	str	—	Точка входа Auto SSH

Список заказов

# Только активные заказы
active = client.my_orders()
for o in active:
    print(f"Заказ {o.id}: type={o.type}, IP={o.pub_cluster}, status={o.status}")

# Включить завершённые заказы
all_orders = client.my_orders(include_completed=True)

Поля модели заказа

Поле	Тип	Описание
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	Сопоставление портов (например, {"22": 50022})
created_at	str | None	Временная метка создания

Мониторинг заказов

import time

def wait_for_ready(client, order_id, timeout=120):
    """Ждать, пока заказ получит публичный IP."""
    for _ in range(timeout // 10):
        orders = client.my_orders()
        order = next((o for o in orders if o.id == order_id), None)
        if order and order.pub_cluster:
            return order
        time.sleep(10)
    raise TimeoutError(f"Заказ {order_id} не готов через {timeout}с")

# Использование
order = client.create_order(server_id=142, image="cloreai/ubuntu22.04-cuda12", type="on-demand", currency="bitcoin")
ready = wait_for_ready(client, order.id)
print(f"SSH: ssh root@{ready.pub_cluster} -p {ready.tcp_ports.get('22', 22)}")

Отмена заказов

# Отмена с необязательной причиной
client.cancel_order(order_id=38, issue="Задача завершена")

# Отменить все активные заказы
orders = client.my_orders()
for order in orders:
    client.cancel_order(order.id, issue="Очистка")
    print(f"Заказ {order.id} отменён")

---

Управление сервером (для хостеров)

Если вы размещаете GPU на Clore, SDK позволяет управлять вашими серверами:

Список ваших серверов

my_servers = client.my_servers()
for s in my_servers:
    print(f"Сервер {s.id}: {s.gpu_model} — {s.status}")

Получить конфигурацию сервера

config = client.server_config("MyGPU-Rig")
print(f"Имя: {config.name}")
print(f"Видимость: {config.visibility}")
print(f"Онлайн: {config.online}")
print(f"Мин. аренда: {config.mrl}ч")
print(f"Цена по требованию: {config.on_demand_price}")
print(f"Спотовая цена: {config.spot_price}")

Обновить настройки сервера

client.set_server_settings(
    name="MyGPU-Rig",
    availability=True,       # Сделать сервер доступным
    mrl=24,                  # Минимальная аренда 24ч
    on_demand=0.0001,        # Цена по требованию в BTC
    spot=0.00000113          # Спотовая цена в BTC
)
print("Настройки обновлены")

---

Спотовый рынок

Спотовые заказы могут быть прерваны, если кто-то перебьёт вашу ставку. Примерно у трети серверов спотовая цена ниже цены по требованию (медиана ~13% ниже); у остальных спотовая цена равна цене по требованию.

Просмотреть спотовые предложения

offers = client.spot_marketplace(server_id=6)
for offer in offers:
    print(f"Заказ {offer.get('order_id')}: price={offer.get('price')}")

Создать спотовый заказ

order = client.create_order(
    server_id=142,
    image="cloreai/ubuntu22.04-cuda12",
    type="spot",
    currency="bitcoin",
    spot_price=0.0001,       # Ваша цена ставки
    ssh_password="MyPass"
)
print(f"Спотовый заказ {order.id} создан")

Изменить спотовую цену

# Повышайте ставку, чтобы вас не перебили
client.set_spot_price(order_id=39, price=0.000003)

Стратегия спотовых ставок

from clore_ai import CloreAI

client = CloreAI()

def smart_spot_bid(server_id, premium_pct=5):
    """Ставьте немного выше текущей минимальной спотовой цены."""
    offers = client.spot_marketplace(server_id=server_id)
    if not offers:
        print("Нет спотовых предложений — используйте цену по требованию как базовую")
        return None

    min_price = min(o["price"] for o in offers)
    bid = min_price * (1 + premium_pct / 100)
    print(f"Мин. цена рынка: {min_price}, ставка: {bid:.8f} (+{premium_pct}%)")
    return bid

# Использование
bid = smart_spot_bid(server_id=142, premium_pct=10)
if bid:
    order = client.create_order(
        server_id=142,
        image="cloreai/ubuntu22.04-cuda12",
        type="spot",
        currency="bitcoin",
        spot_price=bid
    )

---

Операции с кошельком

Проверка балансов

wallets = client.wallets()
for w in wallets:
    print(f"{w.name}: {w.balance:.8f}")
    if w.deposit:
        print(f"  Адрес для пополнения: {w.deposit}")

Оповещение о низком балансе

from clore_ai import CloreAI

def check_balance(min_btc=0.001):
    """Оповестить, если баланс BTC ниже порога."""
    client = CloreAI()
    wallets = client.wallets()

    for w in wallets:
        if w.name.lower() == "bitcoin" and w.balance < min_btc:
            print(f"⚠️  Низкий баланс BTC: {w.balance:.8f} (минимум: {min_btc})")
            return False

    print("✅ Балансы в порядке")
    return True

check_balance(min_btc=0.001)

---

Лучшие практики обработки ошибок

Иерархия исключений

CloreAPIError (базовый)
├── DBError           (код 1) — ошибка базы данных
├── InvalidInputError (код 2) — некорректный ввод
├── AuthError         (код 3) — неверный API-ключ
├── InvalidEndpointError (код 4) — неверная конечная точка
├── RateLimitError    (код 5) — ограничение скорости (автоповтор)
└── FieldError        (код 6) — ошибка конкретного поля

Базовая обработка ошибок

from clore_ai import CloreAI
from clore_ai.exceptions import (
    CloreAPIError,
    AuthError,
    RateLimitError,
    InvalidInputError
)

client = CloreAI()

try:
    order = client.create_order(
        server_id=999999,
        image="cloreai/ubuntu22.04-cuda12",
        type="on-demand",
        currency="bitcoin"
    )
except AuthError:
    print("Неверный API-ключ — проверьте CLORE_API_KEY")
except InvalidInputError as e:
    print(f"Некорректный ввод: {e}")
except RateLimitError:
    print("Ограничение скорости — SDK пытается повторно автоматически, но число повторов исчерпано")
except CloreAPIError as e:
    print(f"Ошибка API (код {e.code}): {e}")

Паттерн повторных попыток с backoff

В SDK встроены повторные попытки для ограничений по частоте и сетевых ошибок (max_retries=3). Для повторных попыток на уровне приложения:

import time
from clore_ai import CloreAI
from clore_ai.exceptions import CloreAPIError, RateLimitError

def retry_operation(func, max_attempts=3, base_delay=2.0):
    """Повторяет операцию API Clore с экспоненциальной задержкой."""
    for attempt in range(max_attempts):
        try:
            return func()
        except RateLimitError:
            if attempt < max_attempts - 1:
                delay = base_delay * (2 ** attempt)
                print(f"Превышен лимит частоты, повтор через {delay}s...")
                time.sleep(delay)
            else:
                raise
        except CloreAPIError as e:
            if e.code in (1,):  # Ошибки БД могут быть временными
                if attempt < max_attempts - 1:
                    time.sleep(base_delay)
                    continue
            raise

# Использование
client = CloreAI()
servers = retry_operation(lambda: client.marketplace(gpu="RTX 4090"))

---

Советы по производительности

1. Используйте клиента повторно

# ❌ Плохо — каждый раз создаёт новое HTTP-соединение
for _ in range(10):
    client = CloreAI()
    client.marketplace()
    client.close()

# ✅ Хорошо — повторно использует HTTP-соединение
client = CloreAI()
for _ in range(10):
    client.marketplace()
client.close()

2. Используйте async для одновременных операций

import asyncio
from clore_ai import AsyncCloreAI

async def compare_gpus():
    async with AsyncCloreAI() as client:
        # Запустите 3 поиска одновременно
        rtx4090, rtx3090, a100 = await asyncio.gather(
            client.marketplace(gpu="RTX 4090"),
            client.marketplace(gpu="RTX 3090"),
            client.marketplace(gpu="A100"),
        )

        print(f"RTX 4090: {len(rtx4090)} серверов")
        print(f"RTX 3090: {len(rtx3090)} серверов")
        print(f"A100: {len(a100)} серверов")

asyncio.run(compare_gpus())

3. Создание пакетных заказов в async

import asyncio
from clore_ai import AsyncCloreAI

async def batch_deploy(server_ids):
    async with AsyncCloreAI() as client:
        tasks = [
            client.create_order(
                server_id=sid,
                image="cloreai/ubuntu22.04-cuda12",
                type="on-demand",
                currency="bitcoin",
                ssh_password="BatchPass123",
                ports={"22": "tcp"}
            )
            for sid in server_ids
        ]
        orders = await asyncio.gather(*tasks, return_exceptions=True)

        for sid, result in zip(server_ids, orders):
            if isinstance(result, Exception):
                print(f"Сервер {sid}: ОШИБКА — {result}")
            else:
                print(f"Сервер {sid}: Заказ {result.id} создан")

        return orders

# Разверните на 3 серверах одновременно
asyncio.run(batch_deploy([142, 305, 891]))

Примечание: SDK требует 5-секундную паузу между create_order вызовами. Даже в async-режиме заказы распределяются по времени, чтобы соблюдать ограничения по частоте.

4. Закрывайте клиентов после завершения

# Контекстный менеджер делает это автоматически
with CloreAI() as client:
    # работа...
    pass  # client.close() вызывается автоматически

# Или закройте вручную
client = CloreAI()
try:
    # работа...
    pass
finally:
    client.close()

---

Полный пример: автоматическое масштабирование GPU-воркеров

import asyncio
import time
from clore_ai import AsyncCloreAI
from clore_ai.exceptions import CloreAPIError

async def auto_scale(
    gpu_model="RTX 4090",
    max_price=2.0,
    target_workers=3,
    image="cloreai/ubuntu22.04-cuda12"
):
    """Поддерживает пул GPU-воркеров."""
    async with AsyncCloreAI() as client:
        # 1. Проверьте текущие заказы
        current_orders = await client.my_orders()
        active_count = len(current_orders)
        print(f"Активных воркеров: {active_count}/{target_workers}")

        if active_count >= target_workers:
            print("Уже достигнут целевой уровень. Делать ничего не нужно.")
            return

        # 2. Найдите доступные серверы
        servers = await client.marketplace(gpu=gpu_model, max_price_usd=max_price)
        servers.sort(key=lambda s: s.price_usd or float("inf"))

        needed = target_workers - active_count
        candidates = servers[:needed]

        if len(candidates) < needed:
            print(f"Доступно только {len(candidates)} серверов (нужно {needed})")

        # 3. Развертывание
        for server in candidates:
            try:
                order = await client.create_order(
                    server_id=server.id,
                    image=image,
                    type="on-demand",
                    currency="bitcoin",
                    ssh_password="WorkerPass123",
                    ports={"22": "tcp"}
                )
                print(f"Развернуто на сервере {server.id} → заказ {order.id}")
            except CloreAPIError as e:
                print(f"Не удалось развернуть на {server.id}: {e}")

asyncio.run(auto_scale())

---

Дальнейшие шаги

• Автоматизация CLI — Bash-скрипты, CI/CD, пакетные операции

• Пакетная обработка — Обрабатывайте большие нагрузки на GPU Clore

• Интеграция API — Подключайте ИИ-сервисы к своим приложениям