This repository holds the Acumos R Client(https://gerrit.acumos.org/r/acumos-R-client) which helps provide a way to use R in the Acumos Platform. It has to be used in conjunction with the Model Runner (https://gerrit.acumos.org/r/generic-model-runner).
Please see the documentation in the "docs" folder.
Under Debian/Ubuntu, install remotes
and acumos
dependencies first:
apt-get update
apt install -y git-core libssl-dev libcurl4-openssl-dev make protobuf-compiler libprotoc-dev libprotobuf-dev
Then, in R, install remotes
:
install.packages("remotes")
Install this development version of acumos
using remotes
:
remotes::install_github("acumos/acumos-r-client", subdir="acumos-package")
To create a deployment component, use acumos::compose()
with the functions to expose. If type specs are not defined, they default to c(x="character")
.
The component consists of a bundle component.amc
which is a ZIP file with meta.json
defining the component and its metadata, component.bin
the binary payload, component.proto
with the protobuf specs
and component.swagger.yaml
with the Swagger API definition.
Please consult R documentation page for details, i.e., use ?compose
in R.
Example:
install.packages("randomForest")
library(randomForest)
library(acumos)
compose(predict=function(..., inputs=lapply(iris[-5], class)) as.character(predict(rf, as.data.frame(list(...)))),
aux = list(rf = randomForest(Species ~ ., data=iris)),
name="Random Forest",
file="component.amc"
)
You can also compose your model bundle directly from the R source code you used to build your model.
A regular component source code file is an R script in which at least one of the three following functions are defined:
acumos_predict
, acumos_transform
or acumos_fit
. They respectively correspond to the functions predict
, transform
and fit
of compose()
. In that script, if the functions acumos_generate
, acumos_service
or acumos_initialize
are defined,
they will also correspond to the other function type arguments of compose()
, namely generate
, service
and initialize
.
acumos::composeFromSource(file = "path/to/your/R/script/acumos.R",
name = "MyComponentName",
outputfile = "component.amc",
addSource = TRUE)
The addSource
parameter is a boolean that allows you to add the R source code (component.R) in your model bundle.
The path to an example component source code file can be found by executing the following R command:
print(system.file("examples", "example_0", "acumos.R", package = "acumos"))
To run the component you have to create a runtime.json
file with at least {"input_port":8100}
or similar to define which port the component should listen to. If there are output components there should also be a "output_url"
entry to specify where to send the result to. It can be either a single entry or a list if the results are to be sent to multiple components. Example:
{"input_port":8100, "output_url":"http://127.0.0.1:8101/predict"}
With the component bundle component.amc
plus runtime.json
in place the component can be run using
R -e 'acumos:::run()'
The run()
function can be configured to set the component directory and/or location of the component bundle. If you don't want to create a file, the runtime
parameter also accepts the runtime structure, so you can also use
R -e 'acumos:::run(runtime=list(input_port=8100, data_response=TRUE))'
See also ?run
in R.
Once the model bundle is created, you can use the push()
API client to on-board it on Acumos. This is CLI
(Command Line Interface) on-boarding. An example R command is the following:
acumos::push(url = "https://<hostname>/onboarding-app/v2/models",
file = "component.amc",
token = "<username>:<token>",
create = FALSE,
license = "path/to/your/license.json")
url
: can be found in the ON-BOARDING MODEL page of your Acumos portal and looks like :
<hostname>/onboarding-app/v2/models
file
: component.amc (your model bundle)
username
: your Acumos username
token
: API token available in the Acumos portal in your profile section
create
: logical parameter (Boolean) to trigger the creation of microservice at the end of
on-boarding process. By default create=TRUE, if you don't want to create the microservice modify the
value to FALSE (create =FALSE)
license
: path to the license profile file : The license profile file name must be "license.json".
Rather than creating the model bundle with compose()
and then on-boarding it with push()
, you can use the
pushFromSource()
function that allow you to on-board your model directly from your R source code and put this R
source code inside the model bundle.
acumos::pushFromSource(url = "https://<hostname>/onboarding-app/v2/models",
file = "path/to/your/R/script/acumos.R",
name = "MyComponentName", addSource = FALSE,
token = "<username>:<token>", create = FALSE,
license = "path/to/your/license.json")
The path to an example component source code file can be found by executing the following R command:
print(system.file("examples", "example_0", "acumos.R", package = "acumos"))
The use of API token is recommended to avoid typing your password in command line, but you can also authenticate yourself by using the auth()
API:
acumos::auth("https://<hostname>", "username", "password")
url
: can be found in the ON-BOARDING MODEL page of your Acumos portal and looks like "https:///onboarding-app/v2/auth"
username
: your Acumos username
password
: your Acumos password
In response, you will receive an authentication token to be used in the push()
or pushFromSource()
function instead of ":"
Whatever the function you used, at the end of a successful CLI on-boarding with microservice creation, you will receive a message with the Acumos docker URI of your model.
You can also drag & drop your model bundle on the "ON-BORADING BY WEB" page in your Acumos instance, or browse you model bundle from this page. This is Web on-boarding.
You can on-board your model with a license profile, you just have to browse your license profile file or drag and drop it.
Whatever the case, CLI or WEB on-boarding, if the license profile file extension is not 'json' the license on-boarding will not be possible and if the name is not 'license' Acumos will rename your license file as license.json and you will see your license profile file as "license-1.json" in the artifacts table. If you upload a new version of your license through the portal, the license number revision will be increased by one like that "license-2.json". To help user create the license profile file expected by Acumos a license profile editor user guide is available here : https://docs.acumos.org/en/latest/submodules/license-manager/docs/user-guide-license-profile-editor.html