Ratio1 end-to-end tutorial

Ready to experience the simplicity of building and deploying AI-powered endpoints on the Ratio1 network? 

In this guide, we’ll walk you through everything: launching a new node, installing the Ratio1 SDK, and deploying a basic AI time-series prediction endpoint. By the end, you’ll see just how frictionless decentralized AI can be.

1. Launch Your Ratio1 Node

We begin by spinning up a Ratio1 Edge Node. If you prefer to run nodes on separate machines - like a cloud VM or a spare computer - feel free to adapt the commands.

docker run -d --rm --name r1node --platform linux/amd64 --pull=always -v r1vol:/edge_node/_local_cache/ ratio1/edge_node:develop

• -d runs the container in the background.

• --rm cleans up the container upon stopping.

• --platform linux/amd64 ensures compatibility on certain architecture (e.g.: running on arm64, if you run on x86_64 you can skip this param)

• -v r1vol:/edge_node/_local_cache/ attaches a persistent volume to store node data.

• ratio1/edge_node:develop is the latest development image for the Ratio1 Edge Node.

No GPU is required for this simple app, and dAuth handles all authentication - so no manual passwords or credentials needed.

Note: Docker must be installed and running on your machine (Docker Desktop for Windows and macOS).

For more about Ratio1 Node Edge running read:
https://ratio1.ai/blog/never-settle-build-simplify-optimize-and-repeat

2. Set Up Your Environment and the Ratio1 SDK

Next, confirm that Python and pip are installed on your local machine (Windows, macOS, or Linux). If necessary, install them:

python3 --version
pip --version

On Linux:

sudo apt-get install python3
sudo apt-get install python3-pip

On Windows, download Python at python.org/downloads.

Install the Ratio1 SDK

We recommend adding --upgrade to ensure you’re always on the latest version:

pip install ratio1 --upgrade

3. Link the Node to Your Local SDK

To allow the newly created node to accept requests, we’ll whitelist your SDK client address in the node. First, retrieve your SDK address:

r1ctl config show

You should see output similar to:

SDK Client address: 0xai_ApB0JuEIWAyRB0dUIhbYPC87yK-bSO5X6HwfdRVelFgD

Then, run this command on the machine hosting the Docker container to grant access:

docker exec r1node add_allowed 0xai_ApB0JuEIWAyRB0dUIhbYPC87yK-bSO5X6HwfdRVelFgD

(Replace the example address with the actual one from your r1ctl config show.)

To verify, run:

docker exec r1node get_node_info

You’ll see the SDK address listed in the node’s whitelist.

4. Build and Deploy a Simple AI Endpoint

It’s time to show off how straightforward it is to create an AI prediction endpoint on Ratio1. In this example, we’ll define a simple time series model for demonstration. The Ratio1 SDK automatically packages your custom function into a FastAPI service and deploys it to the Edge Node, meaning no extra servers or complicated DevOps steps.

Sample Code: Time Series Prediction

Create a new file, e.g. time_series_prediction.py, and add the following Python code that uses the pre-existing local SDK and the remote nodes internal APIs:

from ratio1 import Session, CustomPluginTemplate, PLUGIN_TYPES
def run_predict(plugin: CustomPluginTemplate, inputs: list[int], nr_steps: int) -> list:
  preds = plugin.basic_ts_fit_predict(inputs, nr_steps)
  # Apply a simple heuristic for lower and upper bounds
  lower_bound = []
  upper_bound = []
  heuristic_factor = 0.1
  for pred in preds:
    lower_bound.append(int(pred - abs(pred * heuristic_factor)))
    upper_bound.append(int(pred + abs(pred * heuristic_factor)))
  
  result = {
    "predictions": [round(x,1) for x in preds],
    "lower_bound": lower_bound,
    "upper_bound": upper_bound
  }
  return result
if __name__ == '__main__':
  
  session = Session(silent=True)
  my_node = "0xai_ApM1AbzLq1VtsLIidmvzt1Nv4Cyl5Wed0fHNMoZv9u4X"
  
  app, _ = session.create_web_app(
    node=my_node,
    name="ratio1_simple_predict_webapp",
    endpoints=[
      {
        "function": run_predict,
        "method": "post",
      },        
    ]
  )
  try:
    url = app.deploy()
    print("Webapp deployed at: ", url)
    print("Access Swagger UI:  ", url + "/docs")
  except Exception as e:
    print("Error deploying webapp: ", e)
  
  session.wait(
    close_pipeline_on_timeout=True,
    close_session_on_timeout=True,
    seconds=180
  )

How It Works

1. Session Setup: We create a Session to connect to the Ratio1 network, leveraging dAuth for trustless authentication.

2. create_web_app: This command lets you define a new web app (with a custom function exposed as a REST endpoint) for your target node.

3. Deploy: The script packages and sends the app to your designated node (my_node), returning a public URL. Note: In a production environment the R1 supervisor/oracle network will be taking care of this distribution and balancing task

4. Predict & Bounds: The run_predict function uses a built-in no-GPU model for a basic time-series forecast, then applies a heuristic to generate lower/upper bounds. This was done to demonstrate the high potential to add your own heuristics and even construct complex neuro-symbolic pipelines - albeit in this case no GPU-based neural graph is used.

5. Session Wait: For convenience the script then waits for 180 seconds before terminating. Note: If close_pipeline_on_timeout is set to False, your endpoint remains live even after the script ends.

Notes: 

1. For my_node, copy the SDK address as shown by r1ctl (same you used for add_allowed) and replace the address in the example.

2. If you have previously installed the SDK and run the node, ensure that you have the latest versions of both. Most likely if you dont you’ll get some warning or even required update. 

5. Test Your Newly Created Endpoint

Upon running python3 time_series_prediction.py, you might see something like this:

Webapp deployed at:  https://82f21cc31c7d.ngrok.app
Access Swagger UI:   https://82f21cc31c7d.ngrok.app/docs

This means that our ngrok based system has finalized the endpoints deployment process and we have both the webapp deployed at our url as well as the Swagger neat doc website. Please note that the “Webapp deployed at” shows only the base URL and not the actual endpoint or endpoints. Check the Swagger for full details on your deployed endpoints and have fun!

Navigate to the Swagger UI link for a user-friendly interface to test your endpoint. Alternatively, you can hit the endpoint via curl:

curl -X 'POST' \
  'https://82f21cc31c7d.ngrok.app/run_predict' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "inputs": [
    1, 2, 3, 4, 5, 6, 7, 8, 9
  ],
  "nr_steps": 5
}'

Sample Response:

{
  "result": {
    "predictions": [
      10,
      10.9,
      11.9,
      12.9,
      13.9
    ],
    "lower_bound": [9, 9, 10, 11, 12],
    "upper_bound": [11, 12, 13, 14, 15]
  },
"server_node_addr": "0xai_ApM1AbzLq1VtsLIidmvzt1Nv4Cyl5Wed0fHNMoZv9u4X"
}

You’ve just built and deployed a live AI-powered microservice - no separate hosting, no building Docker images, and minimal overhead.

The Bigger Picture: Why This Matters

1. Developer-Friendly: Ratio1 transforms the typical AI development process, eliminating complex DevOps while making advanced AI capabilities accessible via straightforward Python scripts.

2. Investor Confidence: This tutorial highlights Ratio1’s ability to streamline AI deployment and reduce infrastructure overhead, illustrating a scalable and future-proof tech stack.

3. Multi-Node Scalability: With minimal tweaks, you can target multiple nodes, add GPU resources, or expand your API’s functionality - opening doors for more advanced real-time workloads.

4. Trustless Infrastructure: dAuth ensures secure authentication and data management without central authority, aligning with the broader decentralized ethos.

Conclusion

You’ve just witnessed an end-to-end example of how the Ratio1 ecosystem simplifies AI application deployment - unlocking powerful, decentralized infrastructure at your fingertips. Whether you’re a developer looking to prototype quickly, a data scientist wanting hassle-free experiment deployments, or an investor eyeing the next big step in AI and blockchain convergence, Ratio1 delivers a cohesive, future-focused approach.

Ready to do more?

• Spin up additional Edge Nodes for load balancing.

• Explore advanced plugins that integrate custom Python business logic.

• Scale up to GPU-enabled nodes for ML training or heavy computations.

By embracing Ratio1, you step into a world where decentralization meets true usability - no more trade-offs between innovation and complexity. Welcome to the new frontier of AI infrastructure!

For more tutorials, FAQs, and advanced examples, stay tuned to our official channels and documentation. 

The future of decentralized AI starts here.