Skip to content

SSF Config

The SSF Config is a YAML format file.
A detailed description of all the supported YAML fields is provided below.
Required fields are flagged with 'Y'.

For a quick overview of the SSF Config file and how it works with the application interface, see model format.

Field Required Example Description
ssf_version Y 1.0.0 The version of SSF for which this config was written and tested
application Y Application information - see following section
application:
..id Y my_app A unique identifier without spaces or special characters
..name Y My application The application name in human-readable format
..desc Y This is my application A description of the application in human-readable format
..version Y 1.0 The version number for this application
..module Y my_application.py The Python module that provides the SSF application interface
..license_name N CreativeML Open RAIL++-M License License type/name for the application (model or API)
..license_url N https://my.co/my_app/LICENSE URL to the license for the application (model or API)
..terms_of_service N https://my.co/my_app/TERMS URL to terms of service for the application (model or API)
..ipus N 4 Minimum number of required IPUs (can be zero)
..max_batch_size N 1 Maximum batch size supported ; see batching
..startup_timeout N 60 When testing, maximum time in seconds to wait for the application to be ready
..artifacts N ["weights.onnx", "exe_cache/*/"] List of 'globs' for files that are built when build is issued.
These are the files removed when init is issued
..trace N True Enable endpoint logging
..syspaths N ["../my_model_src"] List of directories used to extend the Python sys.path (module search path)
..dependencies N Dependencies - see following section
application:dependencies:
..python N requirements.txt Comma-separated list of packages and/or requirements files
..poplar N ["3.2.0", "3.3.0"] List of Poplar SDK versions that are compatible with the application
..poplar_location N /sdks/20.04/3.3.0 Location to find the Poplar SDK if it is not already enabled
..poplar_wheels N poptorch,poptorch_geometric Comma-separated list of Poplar wheels to install if SSF needs to enable the Poplar SDK
..package N Packaging - see following section
application:package:
..inclusions N ["weights.onnx", "exe_cache/*/"] List of 'globs' for application-specific files to include when packaging
..exclusions N ["intermediates/*/"] List of 'globs' for application-specific files to exclude when packaging
..name N "my_app_bundle_v{{application.version}}.tar.gz" Filename for package tarball; if not specified then defaults to <application.name>.<application.version>.tar.gz
..tag N "my-repo/{{application.id}}:{{application.version}}" Tag for package image; if not specified then defaults to <application.name>:<application.version>
..docker N Docker packaging - see following section
application:package:docker:
..baseimage N "graphcore/pytorch:3.3.0-ubuntu-20.04" Use this specific base image when packaging the image (else the current SSF default will be used)
..run N |-2
  RUN apt-get install -y \
  libsm6 libxext6 libboost-all-dev \
  libjpeg-dev libtiff-dev libpng-dev		 Custom Dockerfile lines
endpoints Y List of end-points - see following section
endpoints:
..id Y "MyAPI" An identifier without spaces or special characters. See end-points
..version N 2 The version number for this end-point (defaults to 1)
..desc N "This is my API end-point" A description of the end-point in human-readable format
..http_param_format N query How to pass input data. More details in the section Requests data format.
..custom N "my_custom_endpoint.py" Use this Python file as the FastAPI endpoint implementation
..inputs Y List of inputs - see following section
endpoints:inputs:
..id Y x A unique identifier without spaces or special characters
..type Y Integer One of the SSF defined types
..desc N "An integer value" A description of the input in human-readable format
..example N 10 An example value for this input
..outputs Y List of outputs - see following section
endpoints:outputs: ls
..id Y x_times_1000 A unique identifier without spaces or special characters
..type Y Integer One of the SSF defined types
..desc N "Input value x times 1000" A description of the input in human-readable format

Notes

FastAPI End-points

SSF will code-generate the server endpoint for the inputs/outputs and map it through the user application request function provided in the SSFApplicationInterface instance. The endpoint code is automatically generated as:

/v<version>/<id>

For example, if version is 1 and id is my_endpoint, then it will generate:

/v1/my_endpoint

The combination of version and id must be unique for the application.

You can override the SSF code-generated endpoint and use your own module by specifying an endpoint file to import with the custom option.

Parameter examples will be provided in the FastAPI generated OpenAPI definition and Swagger UI.
Parameter examples are supported only when using the FastAPI runtime and only for the basic types (Integer, String, Float, Boolean) and the list variants (ListInteger, ListString, ListFloat, ListBoolean).
The provided example values must be convertible to the parameter's declared type. Examples for List type parameters must be a comma-separated list of values; for example, given a parameter with type ListInteger: example: 1,2,3.

Requests data format

SSF will declare inputs to be delivered in the request body parameters (json) by default. The exceptions are:

  • If http_param_format: query is declared in the SSF config for the end point, or
  • If the end-point includes a custom input type (such as TempFile).

In these cases SFF will declare inputs to be delivered query parameters. You might use http_param_format: query in your SSF config to force query-in-request-params. Note that using query parameters for long inputs is not recommended, this can cause unwanted behaviour due to URL size https://stackoverflow.com/questions/417142/what-is-the-maximum-length-of-a-url-in-different-browsers/417184#417184.

SSF types

Basic types

The following basic types are supported:

ssf_config.yml expected Python type (in app)
String str
Integer int
Float float
Boolean bool

List types:

List types can also be used as a single input/output:

ssf_config.yml expected Python type (in app)
ListString List[str]
ListInteger List[int]
ListFloat: List[float]
ListBoolean List[bool]
ListAny* list

*Experimental

Input file handling

The following file handling types are supported as input:

  • TempFile (input only): This supports upload of file over interface, the file is saved in the server (temporary) and queued to the request as a filename.

Specialised types

  • PngImageBytes (output only): This can be used to return a PNG image as content with media_type="image/png".

Self-reference Expansion

  • The SSF config yaml file supports self-reference expansion for string entries; so, for our example, "{{application.id}}.tar.gz" would expand to "simple_test.tar.gz".

Modifying the config with the CLI

  • The SSF config can be modified at run-time using the --modify-config CLI argument. Modifications are applied immediately after the yaml is loaded and before self-reference expansion. New fields are added as string type. Modifications to existing fields must match the existing type.

Primary application context

  • The SSF config folder can be considered the primary application folder or context. All files, modules and directories should be specified relative to the SSF config folder. The current working directory will be set to the application module folder before SSF calls any of the application entry points (build or request etc.).

Application dependencies

  • Your application will run in its own virtual environment with the version of Python used to run SSF. If your application has dependencies on external Python packages, then add them to the SSF config setting dependencies\python.

  • If SSF needs the Poplar SDK to run your application then it will follow this priority sequence:

  • If a Poplar SDK is already enabled and is one of the Poplar versions declared as supporting your application, then it will be used.
  • Else, SSF will attempt to automatically enable Poplar SDK by downloading a release SDK tar.gz from https://www.graphcore.ai/downloads

Downloaded SDKs are cached in ~/.cache/ssf
The SSF config setting dependencies\poplar_location can be used to override the release download. It can be a custom URL from which SSF will download the SDK tar.gz or can be the directory path to an existing unpacked SDK.

Python module search paths

  • SSF adds the SSF config folder and application module folder (if it is different) to the Python module search path before the application module is loaded. The SSF config field syspaths can be used to add any additional directories. The search priority order is: syspaths first, in declared order, followed by the application module folder, followed by the SSF config folder last.

Glob declaration

  • The SSF config settings that take 'globs' (artifacts, inclusions and exclusions) follow the behaviour documented here: glob documentation for Python 3.9. The recursive argument is set to True for inclusions and exclusions for convenience, so the pattern ** can be used and will match any files and zero or more directories. The recursive argument is set to False for artifacts for safety (see WARNINGS).

WARNINGS:

  • The SSF config setting artifacts supports 'glob' matching of files that will be removed when the init command is issued. This feature is intended to remove only files that are generated by the build command, so that the next build will re-generate these files. SSF does not apply any checks or limits on the set of files matched for removal - take care that only the necessary expected files will be matched.

Default versions

Use gc-ssf --help to find version information such as:

  • Which SSF config versions are supported
  • The default base image used for packaging
  • The default SSF image used when deploying using a pre-built SSF image

For example:

Simple Server Framework 1.1.0

Supports application config ssf_version: 0.0.1 - 1.1.0
Package default base image: graphcore/pytorch:3.3.0-ubuntu-20.04-20230703
Deploy default SSF image: graphcore/simple-server-framework:1.1.0