Back to Details

vastai-sdk

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Vast.ai Python SDK (
vastai
/ 
vastai_sdk
)

Vast.ai Python SDK (
vastai
/ 
vastai_sdk
)

The 
vastai
package provides a Python SDK for managing GPU instances, volumes, serverless endpoints, and billing on Vast.ai. The 
vastai_sdk
package is a backward-compatibility shim that re-exports 
vastai
.
vastai
包提供了一个Python SDK，用于在Vast.ai上管理GPU实例、存储卷、无服务器端点及账单。
vastai_sdk
包是一个向后兼容的垫片，会重新导出
vastai
的内容。

Installation

安装

bash
pip install vastai
For serverless and async support:
bash
pip install "vastai[serverless]"
bash
pip install vastai
如需无服务器和异步支持：
bash
pip install "vastai[serverless]"

Authentication

身份验证

The SDK reads the API key from 
~/.vast_api_key
by default. You can also pass it explicitly:
python
from vastai import VastAI
vast = VastAI()                        # reads ~/.vast_api_key
vast = VastAI(api_key="YOUR_API_KEY")  # explicit key
Get your API key from https://console.vast.ai/manage-keys/
SDK默认从
~/.vast_api_key
读取API密钥。你也可以显式传入：
python
from vastai import VastAI
vast = VastAI()                        # 读取~/.vast_api_key
vast = VastAI(api_key="YOUR_API_KEY")  # 显式传入密钥
从https://console.vast.ai/manage-keys/获取你的API密钥。

Backward Compatibility

向后兼容性

The old 
vastai_sdk
import still works:
python
from vastai_sdk import VastAI  # equivalent to: from vastai import VastAI
旧的
vastai_sdk
导入方式仍然可用：
python
from vastai_sdk import VastAI  # 等价于: from vastai import VastAI

VastAI Class (High-Level SDK)

VastAI类（高级SDK）

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

Instance Management

实例管理

python
undefined
python
undefined

List all your instances

列出所有实例

instances = vast.show_instances()
instances = vast.show_instances()

Get a single instance

获取单个实例

instance = vast.show_instance(id=12345)
instance = vast.show_instance(id=12345)

Search GPU offers

搜索GPU报价

offers = vast.search_offers(query='gpu_name=RTX_4090 num_gpus>=4 reliability>0.99')
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)
result = vast.create_instance(id=<offer_id>, image="pytorch/pytorch:latest", disk=50)

Lifecycle

生命周期管理

vast.start_instance(id=12345) vast.stop_instance(id=12345) vast.reboot_instance(id=12345) vast.destroy_instance(id=12345)
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")
vast.label_instance(id=12345, label="my-training-run")

Get SSH connection string

获取SSH连接字符串

ssh_url = vast.ssh_url(id=12345) # returns "ssh -p PORT user@host" scp_url = vast.scp_url(id=12345) # returns scp-compatible URL
undefined
ssh_url = vast.ssh_url(id=12345) # 返回 "ssh -p PORT user@host" scp_url = vast.scp_url(id=12345) # 返回兼容scp的URL
undefined

Search

搜索功能

python
undefined
python
undefined

Search GPU offers (use help(vast.search_offers) for full query syntax)

搜索GPU报价（使用help(vast.search_offers)查看完整查询语法）

offers = vast.search_offers(query='gpu_name=RTX_3090 num_gpus>=2')
offers = vast.search_offers(query='gpu_name=RTX_3090 num_gpus>=2')

Search volume offers

搜索存储卷报价

volumes = vast.search_volumes(query='...')
volumes = vast.search_volumes(query='...')

Search network volumes

搜索网络存储卷

net_vols = vast.search_network_volumes()
net_vols = vast.search_network_volumes()

Search templates

搜索模板

templates = vast.search_templates()
templates = vast.search_templates()

Search invoices

搜索账单

invoices = vast.search_invoices()
undefined
invoices = vast.search_invoices()
undefined

Serverless Deployments

无服务器部署

python
undefined
python
undefined

List all deployments

列出所有部署

deployments = vast.show_deployments()
deployments = vast.show_deployments()

Get a deployment

获取单个部署

deployment = vast.show_deployment(id=42)
deployment = vast.show_deployment(id=42)

Delete a deployment

删除部署

vast.delete_deployment(id=42)
undefined
vast.delete_deployment(id=42)
undefined

Machine Management (Hosting)

机器管理（托管）

python
machines = vast.show_machines()
machine = vast.show_machine(id=10)
vast.list_machine(id=10, price_gpu=0.30)
vast.unlist_machine(id=10)
python
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

SSH密钥管理

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

Team Management

团队管理

python
members = vast.show_members()
vast.invite_member(email="user@example.com", role="developer")
vast.remove_member(id=7)
python
members = vast.show_members()
vast.invite_member(email="user@example.com", role="developer")
vast.remove_member(id=7)

SyncClient (Low-Level Sync)

SyncClient（底层同步客户端）

SyncClient
provides typed, synchronous access to GPU offers and instances.
python
from vastai import SyncClient

client = SyncClient(api_key="YOUR_API_KEY")  # or reads ~/.vast_api_key
SyncClient
提供类型化的同步访问，用于操作GPU报价和实例。
python
from vastai import SyncClient

client = SyncClient(api_key="YOUR_API_KEY")  # 或读取~/.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, )
offers = client.search( num_gpus=2, gpu_name="RTX_4090", min_reliability=0.99, max_dph_total=2.0, )

Create an instance

创建实例

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

List your instances

列出你的实例

instances = client.show_instances() # returns list[SyncInstance]
instances = client.show_instances() # 返回list[SyncInstance]

Destroy an instance

删除实例

client.destroy_instance(instance_or_id=12345)
undefined
client.destroy_instance(instance_or_id=12345)
undefined

AsyncClient (Low-Level Async)

AsyncClient（底层异步客户端）

AsyncClient
provides async access to GPU offers and instances. Use as an async context manager.
python
import asyncio
from vastai import AsyncClient

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>, 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())
AsyncClient
提供异步访问，用于操作GPU报价和实例。可作为异步上下文管理器使用。
python
import asyncio
from vastai import AsyncClient

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

        # 创建实例
        instance = await client.create_instance(offer_id=<id>, image="ubuntu:22.04")

        # 列出实例
        instances = await client.show_instances()  # 返回list[AsyncInstance]

        # 删除实例
        await client.destroy_instance(instance_or_id=instance.id)

asyncio.run(main())

Serverless Client

无服务器客户端

For inference endpoints (requires 
pip install "vastai[serverless]"
):
python
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())
用于推理端点（需要执行
pip install "vastai[serverless]"
）：
python
import asyncio
from vastai import Serverless

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

    # 获取端点
    endpoint = await serverless.get_endpoint("my-endpoint")

    # 发起请求
    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())

Common Patterns

常见用法示例

python
undefined
python
undefined

Find cheapest 4x RTX 4090 and launch a job

找到最便宜的4卡RTX 4090并启动任务

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']}")
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()查看方法签名

help(vast.search_offers) help(vast.create_instance)
undefined
help(vast.search_offers) help(vast.create_instance)
undefined