Documentation

Getting started on AiSilicon

Welcome. The goal of this guide is to help you get started on our platform. We've designed things to be simple without sacrificing flexibility, and this guide should have you up and running in about 10 minutes.

Prerequisites

This guide assumes that you have already:

  • Created an AiSilicon account and verified your email address.
  • Installed the git version control system.
  • Recommended: Installed the git-lfs extension, which improves large file support. AiSilicon automatically uses git-lfs to push files greater than 1MB in size to your repositories, and you won't be able to pull them without it. This saves you both time when running git commands, and costs on storage fees.

1. Pick a team

Your teams are available on the dashboard page which loads after logging in. When you created your account, we created a personal team for you automatically to help get you started. This team should have a name that is very similar to the email address you signed up with, except the @ and . symbols will have been replaced with dashes.

Select your personal team, or create a new one.

Add funds

Before you can launch GPU compute jobs for any projects belonging to a team, you will need to add funds to the team's account balance. Use the billing tab on the team's page to add funds - you can get started for as little as ten dollars.

2. Create a project

On the team page, hit the "Create project" button. This will prompt you to enter a name for the new project, and will ask for the following configuration options:

  • GPU type and number of GPUs
  • Docker image to use for jobs

These are the settings that will be used to launch your jobs, and they can be changed at any time on the project page. Changing these settings will not affect any jobs that are already running, but will apply to subsequently launched jobs.

Create your project with the configuration you need to continue.

3. Add or clone your git remote

Once created, your project comes with a brand-new git remote, hosted by yours truly, that you can use to push to and pull from. On the project page, click the copy button next to the git remote URL to copy it to your clipboard.

If you already have a local git repository for your project, run the following command to add a new remote named aisilicon:

git remote add aisilicon {paste your remote URL here}

If you don't have a git repository yet, run this command to clone the empty repository from AiSilicon and get started:

git clone -o aisilicon {paste your remote URL here}

4. Creating the aisilicon-entrypoint.sh script

In order to run jobs, AiSilicon needs to know how to run your project. To do this, we ask you to create a bash script called aisilicon-entrypoint.sh in the root project folder. This script will be executed automatically whenever a job starts.

This script should normally kick off your GPU compute process, but here is a small "hello world" example you can use:

#!/bin/bash

echo "Hello, world!"
echo "I am running on the AiSilicon platform" >> hello-world.txt
echo "Job done, now exiting"

5. Start a job and pull the results

Now that you've created a project, linked up the git remote, and created an entrypoint script, you're ready to start your first job. Create a new git branch, add your local changes and commit them to it, then push it to the aisilicon remote to start a job:

git checkout -b my-first-job
git add .
git commit -m "Run my first job on AiSilicon"
git push aisilicon my-first-job

Each git branch corresponds to a separate job on AiSilicon. Head back to your project page to view the status of your new job.

Once the process exits and the job completes, and AiSilicon will automatically commit and push any filesystem changes back to the same branch that started the job, and billing will stop. Pull the changes using the following command:

git pull aisilicon my-first-job

You should now see the hello-world.txt file that your entrypoint script created on an AiSilicon server.

Congratulations on running your first job, and happy computing!

Jobs

The job is the basic context in which your GPU compute projects run on AiSilicon, and every job belongs to a project.

Configuration

You can control job configuration on the project page. Any changes will not affect jobs that are currently running, but will apply for any subsequently launched jobs.

  • GPU configuration

    As AiSilicon is a GPU compute platform, all jobs run in containers with one or more GPUs attached to them. Use the project page to configure the type and number of GPUs you wish to use. Currently, we support up to four NVIDIA A4000 GPUs or two NVIDIA A6000 GPUs for any given job, and are actively working to add more options.

  • Docker image configuration

    You can specify any public Docker image to run your jobs. We do not support private images or pull credentials at this time, but are working to add this functionality soon. Visit the project page to edit the Docker image your jobs should use.

Running jobs

To start a job, simply push a branch to your project's git remote. You can push as many separate branches as you want to start multiple jobs simultaneously, but you cannot start two jobs on the same branch at the same time.

Jobs are billed based on the type and number of GPUs used, prorated by the minute. Jobs cannot be started if the team's balance is less than $1.00, which leaves you a small amount to cover any storage fees.

When a job starts, the platform will create a container using your project's GPU and Docker image configurations, pull your git branch, and begin execution.

  • aisilicon-entrypoint.sh

    All jobs begin by executing the aisilicon-entrypoint.sh bash script in the root of your project. You must create this script and push it to your repository, otherwise AiSilicon will not know how to run your job.

  • Completion

    Once the process running your job exits, AiSilicon will automatically commit and push any filesystem changes back to the same branch, and billing will stop. You can then pull these changes with git.

    Please note that we will use git-lfs to track and push any files larger than 1MB, and you must have the git-lfs plugin installed on your computer to pull those files.

Network access

Upon creation, jobs are automatically assigned a random forwarded port between 10000 and 65535.

  • The IP address and port of your job can be found on the job monitoring page (only available while the job is still running).
  • The job container will have a PORT environment variable specified automatically. If you need network access, please configure your job to bind to the port specified in this environment variable.

Canceling jobs

You can cancel jobs by clicking the cancel link next to the RUNNING status on the job page. Job cancellations are typically processed within 10 seconds, and after the container exits, local filesystem changes will be pushed and billing will stop.

If the account balance for the team that owns the project reaches $0, all running jobs will be automatically canceled. Filesystem changes up to that point will still be committed and pushed.

Projects

On AiSilicon, all jobs belong to a project, and all projects belong to a team. Every project comes with a built-in git repository that you can use to create jobs and pull job results. On the project page, you can view the following information:

  • Recent job activity
  • A list of all jobs started for the project
  • Storage statistics for git and git-lfs files
  • GPU type and count configuration
  • Docker image configuration
Important note:

Please understand you should not use AiSilicon as your primary source control system. While we do the best we can to store your data safely by utilizing redundancy and backups, we are not a first-class git hosting service. Git storage is offered on a best-effort basis and we cannot guarantee that your repository will be available at all times.

Storage

All projects use some amount of storage for their git repositories, and storage is currently billed at $0.10/GB per month. Storage fees are prorated by the minute and charged to the team's balance.

  • We highly recommend using git-lfs to push large files. Due to the way git works, files are forever part of a repository's changelog once committed, and the size of the repository will subsequently increase permanently.

  • At this time, files stored via git-lfs cannot currently be deleted from the remote repository - but we are working on dashboard functionality that will allow you to delete git-lfs files that are no longer needed from the repository to save on storage costs.

Deleting projects

If you are an owner or administrator of the team, you can also delete your project, but you should be absolutely certain before doing so. When a project is deleted, its git repository and all related jobs (and job data) are immediately and permanently deleted. We cannot recover projects that have been deleted.

Teams

AiSilicon can be used by individuals, but is also built to serve teams in a first-class manner. We work hard to give teams the tools they need to work collaboratively in an effective manner.

Team members and permissions

There are three levels of permissions for team members:

  • User - can edit project configurations, interact with git repositories, and start jobs.
  • Administrator - can add and remove team members, add funds to the team balance, and can create and delete projects.
  • Owner - the person that created the team. Has all the capabilities of an administrator, and can also delete the team. Cannot be removed from the team by other administrators.

Billing

Every team has an account balance that projects and jobs draw from for storage and GPU compute fees. Administrators and owners can add funds to this balance by using the Billing tab on the project page. Jobs cannot be started when the balance falls below $1.00, and running jobs will be canceled automatically when the balance falls below $0.

Teams with a negative balance risk having their data deleted if they are inactive or using excessive data. We will always try and contact you before deleting any data.