visionhub-client 0.1.0

Client SDK for connecting Colab or local YOLO training runs to VisionHub AI.

visionhub-client

Python SDK de ket noi Google Colab hoac may local ve VisionHub AI trong luc train model computer vision. Thu vien nay duoc viet moi theo dac ta chuc nang, khong copy source code, endpoint rieng, logo hay tai san cua Ultralytics HUB/hub-sdk.

Install

pip install -U visionhub-client

Neu train YOLO bang Ultralytics:

pip install -U "visionhub-client[yolo]"

Trong repo nay co the cai local:

pip install -e ./visionhub-client

Google Colab quickstart

!pip install -U visionhub-client ultralytics

from visionhub_client import VisionHubClient
from ultralytics import YOLO

client = VisionHubClient(
    api_url="https://hub.example.com",
    job_id="job_123",
    token="vhc_xxxxx",
)

client.connect()
client.start_heartbeat(interval=30)

dataset_yaml = client.download_dataset()
config = client.get_training_config()
checkpoint = client.download_latest_checkpoint()

model = YOLO(checkpoint or config["base_model"])
client.attach_ultralytics_callbacks(model)

model.train(
    data=dataset_yaml,
    epochs=config["epochs"],
    imgsz=config["imgsz"],
    batch=config["batch"],
    optimizer=config.get("optimizer", "auto"),
    lr0=config.get("lr0", 0.01),
    patience=config.get("patience", 50),
    resume=bool(checkpoint),
)

client.upload_final_model()
client.finish()

Env-based usage

export VISIONHUB_API_URL="https://hub.example.com"
export VISIONHUB_JOB_ID="job_123"
export VISIONHUB_TOKEN="vhc_xxxxx"
export VISIONHUB_RUNTIME_ID="runtime_456"

from visionhub_client import VisionHubClient

client = VisionHubClient.from_env()
client.connect()
client.prepare()
client.train_yolo()
client.finish()

Resume from a specific checkpoint

from visionhub_client import VisionHubClient
from ultralytics import YOLO

client = VisionHubClient.from_env()
client.connect()

checkpoint_path = client.download_checkpoint("ckpt_abc123")
config = client.get_training_config()

model = YOLO(checkpoint_path)
client.attach_ultralytics_callbacks(model)

model.train(
    data=client.download_dataset(),
    epochs=config["epochs"],
    imgsz=config["imgsz"],
    batch=config["batch"],
    resume=True,
)

client.finish()

Mock training

Dung de test Hub UI khi chua co Colab/training that:

from visionhub_client import VisionHubClient

client = VisionHubClient(
    api_url="http://localhost:4010",
    job_id="job-colab-traffic",
    token="dev-token",
)

client.simulate_training(
    epochs=20,
    disconnect_at_epoch=8,
    checkpoint_every_epoch=True,
)

CLI

visionhub connect --api-url http://localhost:4010 --job-id job-colab-traffic --token dev-token
visionhub heartbeat --api-url http://localhost:4010 --job-id job-colab-traffic --token dev-token
visionhub download-dataset --api-url http://localhost:4010 --job-id job-colab-traffic --token dev-token
visionhub download-checkpoint --api-url http://localhost:4010 --job-id job-colab-traffic --token dev-token
visionhub upload-checkpoint --api-url http://localhost:4010 --job-id job-colab-traffic --token dev-token --file last.pt --epoch 10
visionhub train-yolo --api-url http://localhost:4010 --job-id job-colab-traffic --token dev-token --simulate --epochs 5

API endpoints used

• POST /api/colab/connect
• POST /api/colab/heartbeat
• POST /api/colab/disconnect
• POST /api/colab/finish
• POST /api/colab/fail
• POST /api/colab/status
• GET /api/colab/jobs/:jobId/config
• GET /api/colab/jobs/:jobId/dataset
• GET /api/colab/jobs/:jobId/base-model
• GET /api/colab/jobs/:jobId/checkpoints/latest
• GET /api/colab/jobs/:jobId/checkpoints/:checkpointId/download
• POST /api/colab/jobs/:jobId/logs
• POST /api/colab/jobs/:jobId/metrics
• POST /api/colab/jobs/:jobId/system-metrics
• POST /api/colab/jobs/:jobId/checkpoints/init-upload
• PUT /api/colab/jobs/:jobId/checkpoints/:checkpointId/chunks/:chunkIndex
• POST /api/colab/jobs/:jobId/checkpoints/:checkpointId/complete
• POST /api/colab/jobs/:jobId/checkpoints/:checkpointId/abort

Security notes

• Do not use user passwords in Colab.
• Use job-scoped tokens with narrow permissions.
• Tokens are sent as Authorization: Bearer <token>.
• The SDK masks tokens in summaries and never logs the full token intentionally.
• Checkpoints become usable only after the server verifies checksum.
• Metric/log upload failures are buffered and should not stop training.

Local state

The SDK writes local state under /content/visionhub/state/{job_id}.json in Colab, or .visionhub/state/{job_id}.json locally. This helps resume or debug interrupted sessions.