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, please install remotes and acumos dependencies first:
apt-get update
apt install -y libssl-dev libcurl4-openssl-dev make protobuf-compiler libprotoc-dev libprotobuf-dev
Install acumos:
install.packages("acumos")
To install this development version, please use remotes or devtools:
remotes::install_github("acumos/acumos-r-client", subdir="acumos-package")
or
devtools::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.zip 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:
if(!require("randomForest")) 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.zip"
)
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.zip",
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.zip 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.zip",
token = "<username>:<token>",
create = FALSE, deploy = 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.zip (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)
deploy : logical parameter (Boolean) to trigger the deployment of microservice at the end of
on-boarding process. By default deploy = FALSE, if you want the Acumos platform to deploy automatically
the microservice modify the value to TRUE (deploy = TRUE). Note that this parameter cannot take
the value TRUE, when the parameter create takes the value 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, deploy = 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