vastai-sdk

Vast.ai Python SDK（vastai／vastai_sdk）

vastai パッケージは、Vast.ai の GPU インスタンス、ボリューム、サーバーレスエンドポイント、請求を管理するための Python SDK を提供します。vastai_sdk パッケージは、後方互換性のために vastai を再エクスポートする shim です。

インストール

pip install vastai

サーバーレス機能と非同期処理をサポートするには：

pip install "vastai[serverless]"

認証

SDK は、デフォルトで ~/.vast_api_key から API キーを読み込みます。明示的に渡すこともできます。

from vastai import VastAI
vast = VastAI()                        # reads ~/.vast_api_key
vast = VastAI(api_key="YOUR_API_KEY")  # explicit key

API キーは https://console.vast.ai/manage-keys/ から取得してください。

後方互換性

以前の vastai_sdk インポートも引き続き機能します。

from vastai_sdk import VastAI  # equivalent to: from vastai import VastAI

VastAI クラス（高レベル SDK）

from vastai import VastAI
vast = VastAI(api_key=None, server_url=None, retry=3, raw=False, quiet=False)

インスタンス管理

# List all your instances
instances = vast.show_instances()

# Get a single instance
instance = vast.show_instance(id=12345)

# Search GPU offers
offers = vast.search_offers(query='gpu_name=RTX_4090 num_gpus>=4 reliability>0.99')

# Create an instance from an offer
result = vast.create_instance(id=<offer_id>, image="pytorch/pytorch:latest", disk=50)

# ...as a jupyter instance on a direct connection
result = vast.create_instance(id=<offer_id>, image="pytorch/pytorch:latest", disk=50,
                              jupyter=True, direct=True, jupyter_lab=True)

# Lifecycle
vast.start_instance(id=12345)
vast.stop_instance(id=12345)
vast.reboot_instance(id=12345)
vast.destroy_instance(id=12345)

# Label an instance
vast.label_instance(id=12345, label="my-training-run")

# Get SSH connection string
ssh_url = vast.ssh_url(id=12345)   # returns "ssh -p PORT user@host"
scp_url = vast.scp_url(id=12345)   # returns scp-compatible URL

中断可能な（スポット）レンタル

中断可能な（スポット）インスタンスはオンデマンドインスタンスより低価格ですが、より低い入札額を提示した別のユーザーによって、いつでも中断される可能性があります。注：vast.search_offers(type='bid', ...) は min_bid を公開しますが、vast.create_instance(...) は bid_price=<floor> を渡さない限り、デフォルトで dph_total によるオンデマンドインスタンスになります。type='bid' で検索した後は、必ず bid_price を渡してください。渡さない場合、中断可能なインスタンスではなく、オンデマンドのインスタンス／料金でレンタルされます。

入札で負けると、インスタンスは破棄されず stopped に移行し、ストレージ料金は引き続き発生します。vast.change_bid(id=..., price=...) で入札額を引き上げると再開できます。

検索

# Search GPU offers (use help(vast.search_offers) for full query syntax)
offers = vast.search_offers(query='gpu_name=RTX_3090 num_gpus>=2')

# Search volume offers
volumes = vast.search_volumes(query='...')

# Search network volumes
net_vols = vast.search_network_volumes()

# Search templates
templates = vast.search_templates()

# Search invoices
invoices = vast.search_invoices()

データ転送

# copy() takes vast URLs: "[C.|V.]id:path", "cloud_service[.id]:path", or "local:path"
vast.copy("local:./data/", "C.12345:/workspace/data/")   # Local → instance
vast.copy("C.12345:/workspace/results/", "local:./out/") # Instance → local
vast.copy("12345:/workspace/", "67890:/workspace/")      # Instance → instance (legacy format)
vast.copy("s3.101:/data/", "C.12345:/workspace/")        # Cloud service → instance
vast.copy("V.1234:/file", "C.5678:/workspace/")          # Volume → instance
vast.copy("V.1234:/file", "s3.101:/workspace/")          # Volume → cloud service

vast.cancel_copy(dst_id=12345)                           # Cancel an in-progress copy

# Cloud sync via a saved cloud connection (see the UI settings page for connection IDs)
vast.cloud_copy(src="./data", dst="s3://bucket/path", instance=12345,
                connection=<conn_id>, transfer="Instance To Cloud")
vast.cancel_sync(dst_id=12345)

ボリュームのコピーは現在、別のボリューム、インスタンス、またはクラウドサービスへのコピーのみサポートしており、ローカルへのコピーはサポートしていません。コピー先のディレクトリに /root や / を指定しないでください。インスタンスの SSH 権限が壊れ、以降のコピーが失敗します。https://vast.ai/docs/gpu-instances/data-movement#constraints を参照してください。

サーバーレスデプロイ

# List all deployments
deployments = vast.show_deployments()

# Get a deployment
deployment = vast.show_deployment(id=42)

# Delete a deployment
vast.delete_deployment(id=42)

マシン管理（ホスティング）

machines = vast.show_machines()
machine = vast.show_machine(id=10)
vast.list_machine(id=10, price_gpu=0.30)
vast.unlist_machine(id=10)

SSH キー

keys = vast.show_ssh_keys()
vast.create_ssh_key(ssh_key="ssh-rsa AAAA...")
vast.delete_ssh_key(id=5)

チーム管理

members = vast.show_members()
vast.invite_member(email="[email protected]", role="developer")
vast.remove_member(id=7)

SyncClient（低レベルの同期処理）

SyncClient は、GPU オファーとインスタンスに対する型付きの同期アクセスを提供します。

from vastai import SyncClient

client = SyncClient(api_key="YOUR_API_KEY")  # or reads ~/.vast_api_key

# Search offers with structured filters
offers = client.search(
    num_gpus=2,
    gpu_name="RTX_4090",
    min_reliability=0.99,
    max_dph_total=2.0,
)

# Create an instance (SyncClient takes an InstanceConfig, not loose kwargs)
from vastai.data.instance import InstanceConfig

instance = client.create_instance(
    offer_id=<id>,
    config=InstanceConfig(image="pytorch/pytorch:latest", disk=50),
)

# List your instances
instances = client.show_instances()  # returns list[SyncInstance]

# Destroy an instance
client.destroy_instance(instance_or_id=12345)

AsyncClient（低レベルの非同期処理）

AsyncClient は、GPU オファーとインスタンスへの非同期アクセスを提供します。非同期コンテキストマネージャーとして使用してください。

import asyncio
from vastai import AsyncClient
from vastai.data.instance import InstanceConfig

async def main():
    async with AsyncClient(api_key="YOUR_API_KEY") as client:
        # Search offers
        offers = await client.search(num_gpus=1, gpu_name="A100")

        # Create instance
        instance = await client.create_instance(
            offer_id=<id>, config=InstanceConfig(image="ubuntu:22.04"))

        # List instances
        instances = await client.show_instances()  # returns list[AsyncInstance]

        # Destroy instance
        await client.destroy_instance(instance_or_id=instance.id)

asyncio.run(main())

サーバーレスクライアント

推論エンドポイント用（pip install "vastai[serverless]" が必要です）：

import asyncio
from vastai import Serverless

async def main():
    serverless = Serverless()  # reads ~/.vast_api_key

    # Get an endpoint
    endpoint = await serverless.get_endpoint("my-endpoint")

    # Make a request
    response = await serverless.request("/v1/completions", {
        "model": "Qwen/Qwen3-8B",
        "prompt": "Who are you?",
        "max_tokens": 100,
        "temperature": 0.7,
    })

    text = response["response"]["choices"][0]["text"]
    print(text)

asyncio.run(main())

よくあるパターン

# Find cheapest 4x RTX 4090 and launch a job
from vastai import VastAI
vast = VastAI()

offers = vast.search_offers(query='gpu_name=RTX_4090 num_gpus=4 reliability>0.99')
cheapest = min(offers, key=lambda o: o['dph_total'])
result = vast.create_instance(id=cheapest['id'], image="pytorch/pytorch:latest", disk=100)
print(f"Launched instance: {result['new_contract']}")

# Use help() to explore method signatures
help(vast.search_offers)
help(vast.create_instance)