Guía SDK de Python

Guía completa del SDK de Python: clientes sync/async, filtrado del marketplace, ciclo de vida de órdenes, mercado spot, operaciones de wallet y manejo de errores

¿Nuevo en el SDK? Empieza con el inicio rápido de 5 minutos primero.

Para un tutorial de inicio rápido con ejemplos reales, consulta Clore.ai Python SDK — Automatiza tus flujos de trabajo con GPU en 5 minutos

Instalación

pip install clore-ai

El SDK proporciona dos clientes:

• CloreAI — sincrónico (más simple, bueno para scripts)

• AsyncCloreAI — asincrónico (más rápido para operaciones concurrentes)

Ambos comparten los mismos métodos y devuelven los mismos modelos Pydantic.

---

Sincrónico vs Asincrónico — Cuándo usar cada uno

Caso de uso	Cliente	Por qué
Scripts simples, tareas puntuales	CloreAI	Código más simple, sin async/await
Bucles de monitorización	CloreAI	Comprobaciones secuenciales funcionan bien
Consultas masivas al marketplace	AsyncCloreAI	Solicitudes concurrentes = más rápido
Creación por lotes de órdenes	AsyncCloreAI	Crear múltiples órdenes en paralelo
Aplicaciones web	AsyncCloreAI	E/S no bloqueante

Ejemplo sincrónico

from clore_ai import CloreAI

client = CloreAI()  # Usa la variable de entorno CLORE_API_KEY

servers = client.marketplace(gpu="RTX 4090")
print(f"Se encontraron {len(servers)} servidores")

client.close()  # O utiliza un gestor de contexto

Ejemplo asincrónico

import asyncio
from clore_ai import AsyncCloreAI

async def main():
    async with AsyncCloreAI() as client:
        servers = await client.marketplace(gpu="RTX 4090")
        print(f"Se encontraron {len(servers)} servidores")

asyncio.run(main())

Gestores de contexto (recomendado)

Ambos clientes soportan gestores de contexto para limpieza automática:

# Sincrónico
with CloreAI() as client:
    wallets = client.wallets()

# Asincrónico
async with AsyncCloreAI() as client:
    wallets = await client.wallets()

---

Configuración del cliente

client = CloreAI(
    api_key="tu_clave",      # O establece la variable de entorno CLORE_API_KEY
    base_url="https://api.clore.ai/v1",  # Endpoint de API personalizado
    timeout=30.0,            # Tiempo de espera de la solicitud en segundos
    max_retries=3            # Reintentos en límites de tasa / errores de red
)

El SDK incluye un limitador de tasa integrado:

• Solicitudes generales: 1 solicitud/segundo

• create_order: enfriamiento de 5 segundos entre llamadas

• Errores por límite de tasa (código 5): Reintento exponencial automático

---

Filtrado del marketplace

El marketplace() método obtiene todos los servidores disponibles y filtra del lado del cliente:

from clore_ai import CloreAI

client = CloreAI()

# Todos los servidores disponibles
all_servers = client.marketplace()

# Filtrar por modelo de GPU (coincidencia de subcadena sin distinguir mayúsculas)
rtx_4090s = client.marketplace(gpu="RTX 4090")

# Filtrar por múltiples criterios
budget_gpus = client.marketplace(
    gpu="RTX 4090",
    max_price_usd=1.0,       # Máx $1.00/hora
    min_gpu_count=2,          # Al menos 2 GPUs
    min_ram_gb=64.0,          # Al menos 64 GB de RAM del sistema
    available_only=True       # Solo servidores disponibles (por defecto)
)

Filtrado avanzado (lado del cliente)

Para filtros no incorporados en el método, filtra los Server objetos devueltos tú mismo:

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

# Servidores en la UE con alta fiabilidad
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
]

# Ordenar por precio
cheapest = sorted(servers, key=lambda s: s.price_usd or float("inf"))
print(f"El más barato: Servidor {cheapest[0].id} — ${cheapest[0].price_usd:.4f}/h")

Campos del modelo Server

Cada MarketplaceServer objeto tiene estos atributos y propiedades de conveniencia:

Campo	Tipo	Descripción
id	int	ID del servidor (usa esto en create_order)
gpu_model	str | None	Descripción de la GPU según las especificaciones (propiedad)
gpu_count	int	Número de GPUs de gpu_array (propiedad)
ram_gb	float | None	RAM del sistema en GB (propiedad, desde specs.ram)
price_usd	float | None	Precio bajo demanda en USD (propiedad, desde price.usd.on_demand_usd)
spot_price_usd	float | None	Precio spot en USD (propiedad)
available	bool	Si el servidor no está alquilado (propiedad)
location	str | None	Código de país desde las especificaciones de red (propiedad)
specs	ServerSpecs | None	Especificaciones de hardware (CPU, RAM, disco, GPU, red)
price	ServerPrice | None	Estructura de precios completa
rented	bool | None	Si el servidor está actualmente alquilado

---

Gestión de órdenes

Creación de órdenes

order = client.create_order(
    server_id=142,
    image="cloreai/ubuntu22.04-cuda12",
    type="on-demand",               # "on-demand" o "spot"
    currency="bitcoin",             # Moneda de pago
    ssh_password="MySecurePass",    # Acceso SSH
    ports={"22": "tcp", "8888": "http"},  # Mapas de puertos
    env={"HF_TOKEN": "hf_xxx"},    # Variables de entorno
    command="bash /start.sh",       # Comando de inicio personalizado
    jupyter_token="my_token"        # Token de Jupyter notebook
)

print(f"ID de la orden: {order.id}")
print(f"IP: {order.pub_cluster}")
print(f"Puertos: {order.tcp_ports}")

Parámetros create_order Completos

Parámetro	Tipo	Requerido	Descripción
server_id	int	✅	Servidor a alquilar
image	str	✅	Imagen Docker
type	str	✅	"on-demand" o "spot"
currency	str	✅	Moneda de pago (p. ej., "bitcoin")
ssh_password	str	—	Contraseña SSH
ssh_key	str	—	Clave pública SSH
ports	dict	—	Mapeos de puertos ({"22": "tcp"})
env	dict	—	Variables de entorno
jupyter_token	str	—	Token de Jupyter notebook
command	str	—	Comando de inicio
spot_price	float	—	Precio de oferta spot
required_price	float	—	Precio requerido
autossh_entrypoint	str	—	Punto de entrada Auto SSH

Listado de órdenes

# Solo órdenes activas
active = client.my_orders()
for o in active:
    print(f"Orden {o.id}: type={o.type}, IP={o.pub_cluster}, status={o.status}")

# Incluir órdenes completadas
all_orders = client.my_orders(include_completed=True)

Campos del modelo Order

Campo	Tipo	Descripción
id	int	ID de la orden
server_id	int | None	ID del servidor alquilado
type	str	"on-demand" o "spot"
status	str | None	Estado de la orden
image	str | None	Imagen Docker
currency	str | None	Moneda de pago
price	float | None	Precio
pub_cluster	str | None	IP pública / nombre de host
tcp_ports	dict | None	Mapeos de puertos (p. ej., {"22": 50022})
created_at	str | None	Marca temporal de creación

Monitorización de órdenes

import time

def wait_for_ready(client, order_id, timeout=120):
    """Esperar a que una orden obtenga una IP pública."""
    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"Orden {order_id} no lista después de {timeout}s")

# Uso
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)}")

Cancelación de órdenes

# Cancelar con razón opcional
client.cancel_order(order_id=38, issue="Trabajo completado")

# Cancelar todas las órdenes activas
orders = client.my_orders()
for order in orders:
    client.cancel_order(order.id, issue="Limpieza")
    print(f"Orden cancelada {order.id}")

---

Gestión de servidores (para anfitriones)

Si alojas GPUs en Clore, el SDK te permite gestionar tus servidores:

Listar tus servidores

my_servers = client.my_servers()
for s in my_servers:
    print(f"Servidor {s.id}: {s.gpu_model} — {s.status}")

Obtener configuración del servidor

config = client.server_config("MyGPU-Rig")
print(f"Nombre: {config.name}")
print(f"Visibilidad: {config.visibility}")
print(f"En línea: {config.online}")
print(f"Alquiler mínimo: {config.mrl}h")
print(f"Precio on-demand: {config.on_demand_price}")
print(f"Precio spot: {config.spot_price}")

Actualizar ajustes del servidor

client.set_server_settings(
    name="MyGPU-Rig",
    availability=True,       # Hacer el servidor disponible
    mrl=24,                  # Alquiler mínimo 24h
    on_demand=0.0001,        # Precio on-demand en BTC
    spot=0.00000113          # Precio spot en BTC
)
print("Ajustes actualizados")

---

Mercado spot

Las órdenes spot son 30–50% más baratas pero pueden ser interrumpidas si alguien te supera la puja.

Ver ofertas spot

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

Crear una orden spot

order = client.create_order(
    server_id=142,
    image="cloreai/ubuntu22.04-cuda12",
    type="spot",
    currency="bitcoin",
    spot_price=0.0001,       # Tu precio de puja
    ssh_password="MyPass"
)
print(f"Orden spot {order.id} creada")

Ajustar precio spot

# Aumenta tu puja para evitar ser superado
client.set_spot_price(order_id=39, price=0.000003)

Estrategia de puja spot

from clore_ai import CloreAI

client = CloreAI()

def smart_spot_bid(server_id, premium_pct=5):
    """Pujar ligeramente por encima del precio mínimo spot actual."""
    offers = client.spot_marketplace(server_id=server_id)
    if not offers:
        print("No hay ofertas spot — usa el precio on-demand como referencia")
        return None

    min_price = min(o["price"] for o in offers)
    bid = min_price * (1 + premium_pct / 100)
    print(f"Mínimo del mercado: {min_price}, pujando: {bid:.8f} (+{premium_pct}%)")
    return bid

# Uso
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
    )

---

Operaciones con billeteras

Comprobar saldos

wallets = client.wallets()
for w in wallets:
    print(f"{w.name}: {w.balance:.8f}")
    if w.deposit:
        print(f"  Dirección de depósito: {w.deposit}")

Alerta de saldo bajo

from clore_ai import CloreAI

def check_balance(min_btc=0.001):
    """Alertar si el saldo en BTC está por debajo del umbral."""
    client = CloreAI()
    wallets = client.wallets()

    for w in wallets:
        if w.name.lower() == "bitcoin" and w.balance < min_btc:
            print(f"⚠️  Saldo BTC bajo: {w.balance:.8f} (mínimo: {min_btc})")
            return False

    print("✅ Saldos OK")
    return True

check_balance(min_btc=0.001)

---

Buenas prácticas para el manejo de errores

Jerarquía de excepciones

CloreAPIError (base)
├── DBError           (código 1) — error de base de datos
├── InvalidInputError (código 2) — entrada incorrecta
├── AuthError         (código 3) — clave API inválida
├── InvalidEndpointError (código 4) — endpoint incorrecto
├── RateLimitError    (código 5) — límite de tasa (reintentado automáticamente)
└── FieldError        (código 6) — error específico de campo

Manejo básico de errores

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("Clave API inválida — verifica CLORE_API_KEY")
except InvalidInputError as e:
    print(f"Entrada incorrecta: {e}")
except RateLimitError:
    print("Límite de tasa — el SDK reintenta automáticamente, pero se excedió el máximo de reintentos")
except CloreAPIError as e:
    print(f"Error de API (código {e.code}): {e}")

Patrón de reintento con backoff

El SDK tiene reintentos integrados para límites de tasa y errores de red (max_retries=3). Para reintentos a nivel de aplicación:

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):
    """Reintentar una operación de la API de Clore con backoff exponencial."""
    for attempt in range(max_attempts):
        try:
            return func()
        except RateLimitError:
            if attempt < max_attempts - 1:
                delay = base_delay * (2 ** attempt)
                print(f"Límite de tasa, reintentando en {delay}s...")
                time.sleep(delay)
            else:
                raise
        except CloreAPIError as e:
            if e.code in (1,):  # Los errores de BD pueden ser transitorios
                if attempt < max_attempts - 1:
                    time.sleep(base_delay)
                    continue
            raise

# Uso
client = CloreAI()
servers = retry_operation(lambda: client.marketplace(gpu="RTX 4090"))

---

Consejos de rendimiento

1. Reutiliza el cliente

# ❌ Malo — crea una conexión HTTP nueva cada vez
for _ in range(10):
    client = CloreAI()
    client.marketplace()
    client.close()

# ✅ Bueno — reutiliza la conexión HTTP
client = CloreAI()
for _ in range(10):
    client.marketplace()
client.close()

2. Usa asincronía para operaciones concurrentes

import asyncio
from clore_ai import AsyncCloreAI

async def compare_gpus():
    async with AsyncCloreAI() as client:
        # Ejecutar 3 búsquedas concurrentes
        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)} servidores")
        print(f"RTX 3090: {len(rtx3090)} servidores")
        print(f"A100: {len(a100)} servidores")

asyncio.run(compare_gpus())

3. Creación de órdenes por lotes asincrónica

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"Servidor {sid}: FALLÓ — {result}")
            else:
                print(f"Servidor {sid}: Orden {result.id} creada")

        return orders

# Desplegar en 3 servidores a la vez
asyncio.run(batch_deploy([142, 305, 891]))

Nota: El SDK aplica un enfriamiento de 5 segundos entre create_order llamadas. Incluso en modo asincrónico, las órdenes se espacian para respetar los límites de tasa.

4. Cierra los clientes cuando termines

# El gestor de contexto se encarga de esto automáticamente
with CloreAI() as client:
    # trabajo...
    pass  # client.close() llamado automáticamente

# O cierra manualmente
client = CloreAI()
try:
    # trabajo...
    pass
finally:
    client.close()

---

Ejemplo completo: Autoescalar trabajadores 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"
):
    """Mantener un grupo de trabajadores GPU."""
    async with AsyncCloreAI() as client:
        # 1. Comprobar órdenes actuales
        current_orders = await client.my_orders()
        active_count = len(current_orders)
        print(f"Trabajadores activos: {active_count}/{target_workers}")

        if active_count >= target_workers:
            print("Ya en el objetivo. Nada que hacer.")
            return

        # 2. Encontrar servidores disponibles
        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"Only {len(candidates)} servers available (need {needed})")

        # 3. Deploy
        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"Deployed on server {server.id} → order {order.id}")
            except CloreAPIError as e:
                print(f"Failed to deploy on {server.id}: {e}")

asyncio.run(auto_scale())

---

Siguientes pasos

• Automatización CLI — Scripts Bash, CI/CD, operaciones por lotes

• Procesamiento por lotes — Procesar grandes cargas de trabajo en GPUs de Clore

• Integración de API — Conectar servicios de IA a tus aplicaciones