Title: | Version, Share, Deploy, and Monitor Models |
---|---|
Description: | The goal of 'vetiver' is to provide fluent tooling to version, share, deploy, and monitor a trained model. Functions handle both recording and checking the model's input data prototype, and predicting from a remote API endpoint. The 'vetiver' package is extensible, with generics that can support many kinds of models. |
Authors: | Julia Silge [cre, aut] , Posit Software, PBC [cph, fnd] |
Maintainer: | Julia Silge <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.2.5.9000 |
Built: | 2024-10-09 17:19:10 UTC |
Source: | https://github.com/rstudio/vetiver-r |
Update the OpenAPI specification using model metadata
api_spec(spec, vetiver_model, path, all_docs = TRUE) glue_spec_summary(prototype, return_type) ## Default S3 method: glue_spec_summary(prototype, return_type = NULL) ## S3 method for class 'data.frame' glue_spec_summary(prototype, return_type = "predictions") ## S3 method for class 'array' glue_spec_summary(prototype, return_type = "predictions")
api_spec(spec, vetiver_model, path, all_docs = TRUE) glue_spec_summary(prototype, return_type) ## Default S3 method: glue_spec_summary(prototype, return_type = NULL) ## S3 method for class 'data.frame' glue_spec_summary(prototype, return_type = "predictions") ## S3 method for class 'array' glue_spec_summary(prototype, return_type = "predictions")
spec |
An OpenAPI Specification formatted list object |
vetiver_model |
A deployable |
path |
The endpoint path |
all_docs |
Should the interactive visual API documentation be created
for all POST endpoints in the router |
prototype |
An input data prototype from a model |
return_type |
Character string to describe what endpoint returns, such as "predictions" |
api_spec()
returns the updated OpenAPI Specification object. This
function uses glue_spec_summary()
internally, which returns a glue
character string.
library(plumber) cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") glue_spec_summary(v$prototype) modify_spec <- function(spec) api_spec(spec, v, "/predict") pr() %>% pr_set_api_spec(api = modify_spec)
library(plumber) cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") glue_spec_summary(v$prototype) modify_spec <- function(spec) api_spec(spec, v, "/predict") pr() %>% pr_set_api_spec(api = modify_spec)
These are developer-facing functions, useful for supporting new model types. Some models require one or more R packages to be fully attached to make predictions, and some require only that the namespace of one or more R packages is loaded.
attach_pkgs(pkgs) load_pkgs(pkgs)
attach_pkgs(pkgs) load_pkgs(pkgs)
pkgs |
A character vector of package names to load or fully attach. |
These two functions will attempt either to:
fully attach or
load
the namespace of the pkgs
vector of package names, preserving the current
random seed.
To learn more about load vs. attach, read the "Dependencies" chapter of R Packages. For deploying a model, it is likely safer to fully attach needed packages but that comes with the risk of naming conflicts between packages.
An invisible TRUE
.
## succeed load_pkgs(c("knitr", "readr")) attach_pkgs(c("knitr", "readr")) ## fail try(load_pkgs(c("bloopy", "readr"))) try(attach_pkgs(c("bloopy", "readr")))
## succeed load_pkgs(c("knitr", "readr")) attach_pkgs(c("knitr", "readr")) ## fail try(load_pkgs(c("bloopy", "readr"))) try(attach_pkgs(c("bloopy", "readr")))
Post new data to a deployed model API endpoint and augment with predictions
## S3 method for class 'vetiver_endpoint' augment(x, new_data, ...)
## S3 method for class 'vetiver_endpoint' augment(x, new_data, ...)
x |
A model API endpoint object created with |
new_data |
New data for making predictions, such as a data frame. |
... |
Extra arguments passed to |
The new_data
with added prediction column(s).
if (FALSE) { endpoint <- vetiver_endpoint("http://127.0.0.1:8088/predict") augment(endpoint, mtcars[4:7, -1]) }
if (FALSE) { endpoint <- vetiver_endpoint("http://127.0.0.1:8088/predict") augment(endpoint, mtcars[4:7, -1]) }
Post new data to a deployed SageMaker model endpoint and augment with predictions
## S3 method for class 'vetiver_endpoint_sagemaker' augment(x, new_data, ...)
## S3 method for class 'vetiver_endpoint_sagemaker' augment(x, new_data, ...)
x |
A SageMaker model endpoint object created with |
new_data |
New data for making predictions, such as a data frame. |
... |
Extra arguments passed to |
The new_data
with added prediction column(s).
predict.vetiver_endpoint_sagemaker()
if (FALSE) { endpoint <- vetiver_endpoint_sagemaker("sagemaker-demo-model") augment(endpoint, mtcars[4:7, -1]) }
if (FALSE) { endpoint <- vetiver_endpoint_sagemaker("sagemaker-demo-model") augment(endpoint, mtcars[4:7, -1]) }
These are developer-facing functions, useful for supporting new model types.
Each model supported by vetiver_model()
uses two handler functions
in vetiver_api()
:
The handler_startup
function executes when the API starts. Use this
function for tasks like loading packages. A model can use the default
method here, which is NULL
(to do nothing at startup).
The handler_predict
function executes at each API call. Use this
function for calling predict()
and any other tasks that must be executed
at each API call.
## S3 method for class 'train' handler_startup(vetiver_model) ## S3 method for class 'train' handler_predict(vetiver_model, ...) ## S3 method for class 'gam' handler_startup(vetiver_model) ## S3 method for class 'gam' handler_predict(vetiver_model, ...) ## S3 method for class 'glm' handler_predict(vetiver_model, ...) handler_startup(vetiver_model) ## Default S3 method: handler_startup(vetiver_model) handler_predict(vetiver_model, ...) ## Default S3 method: handler_predict(vetiver_model, ...) ## S3 method for class 'keras.engine.training.Model' handler_startup(vetiver_model) ## S3 method for class 'keras.engine.training.Model' handler_predict(vetiver_model, ...) ## S3 method for class 'kproto' handler_predict(vetiver_model, ...) ## S3 method for class 'lm' handler_predict(vetiver_model, ...) ## S3 method for class 'luz_module_fitted' handler_startup(vetiver_model) ## S3 method for class 'luz_module_fitted' handler_predict(vetiver_model, ...) ## S3 method for class 'Learner' handler_startup(vetiver_model) ## S3 method for class 'Learner' handler_predict(vetiver_model, ...) ## S3 method for class 'ranger' handler_startup(vetiver_model) ## S3 method for class 'ranger' handler_predict(vetiver_model, ...) ## S3 method for class 'recipe' handler_startup(vetiver_model) ## S3 method for class 'recipe' handler_predict(vetiver_model, ...) ## S3 method for class 'model_stack' handler_startup(vetiver_model) ## S3 method for class 'model_stack' handler_predict(vetiver_model, ...) ## S3 method for class 'workflow' handler_startup(vetiver_model) ## S3 method for class 'workflow' handler_predict(vetiver_model, ...) ## S3 method for class 'xgb.Booster' handler_startup(vetiver_model) ## S3 method for class 'xgb.Booster' handler_predict(vetiver_model, ...)
## S3 method for class 'train' handler_startup(vetiver_model) ## S3 method for class 'train' handler_predict(vetiver_model, ...) ## S3 method for class 'gam' handler_startup(vetiver_model) ## S3 method for class 'gam' handler_predict(vetiver_model, ...) ## S3 method for class 'glm' handler_predict(vetiver_model, ...) handler_startup(vetiver_model) ## Default S3 method: handler_startup(vetiver_model) handler_predict(vetiver_model, ...) ## Default S3 method: handler_predict(vetiver_model, ...) ## S3 method for class 'keras.engine.training.Model' handler_startup(vetiver_model) ## S3 method for class 'keras.engine.training.Model' handler_predict(vetiver_model, ...) ## S3 method for class 'kproto' handler_predict(vetiver_model, ...) ## S3 method for class 'lm' handler_predict(vetiver_model, ...) ## S3 method for class 'luz_module_fitted' handler_startup(vetiver_model) ## S3 method for class 'luz_module_fitted' handler_predict(vetiver_model, ...) ## S3 method for class 'Learner' handler_startup(vetiver_model) ## S3 method for class 'Learner' handler_predict(vetiver_model, ...) ## S3 method for class 'ranger' handler_startup(vetiver_model) ## S3 method for class 'ranger' handler_predict(vetiver_model, ...) ## S3 method for class 'recipe' handler_startup(vetiver_model) ## S3 method for class 'recipe' handler_predict(vetiver_model, ...) ## S3 method for class 'model_stack' handler_startup(vetiver_model) ## S3 method for class 'model_stack' handler_predict(vetiver_model, ...) ## S3 method for class 'workflow' handler_startup(vetiver_model) ## S3 method for class 'workflow' handler_predict(vetiver_model, ...) ## S3 method for class 'xgb.Booster' handler_startup(vetiver_model) ## S3 method for class 'xgb.Booster' handler_predict(vetiver_model, ...)
vetiver_model |
A deployable |
... |
Other arguments passed to |
These are two generics that use the class of vetiver_model$model
for dispatch.
A handler_startup
function should return invisibly, while a
handler_predict
function should return a function with the signature
function(req)
. The request body (req$body
) consists of the new data
at prediction time; this function should return predictions either as a
tibble or as a list coercable to a tibble via tibble::as_tibble()
.
cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") handler_startup(v) handler_predict(v)
cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") handler_startup(v) handler_predict(v)
The OpenAPI specification of a Plumber API created via plumber::pr()
can
be modified via plumber::pr_set_api_spec()
, and this helper function will
identify data types of predictors and create a list to use in this
specification. These are not R data types, but instead basic JSON data
types. For example, factors in R will be documented as strings in the
OpenAPI specification.
map_request_body(prototype)
map_request_body(prototype)
prototype |
An input data prototype from a model |
This is a developer-facing function, useful for supporting new model types.
It is called by api_spec()
.
A list to be used within plumber::pr_set_api_spec()
map_request_body(vctrs::vec_slice(chickwts, 0))
map_request_body(vctrs::vec_slice(chickwts, 0))
Post new data to a deployed model API endpoint and return predictions
## S3 method for class 'vetiver_endpoint' predict(object, new_data, ...)
## S3 method for class 'vetiver_endpoint' predict(object, new_data, ...)
object |
A model API endpoint object created with |
new_data |
New data for making predictions, such as a data frame. |
... |
Extra arguments passed to |
A tibble of model predictions with as many rows as in new_data
.
if (FALSE) { endpoint <- vetiver_endpoint("http://127.0.0.1:8088/predict") predict(endpoint, mtcars[4:7, -1]) }
if (FALSE) { endpoint <- vetiver_endpoint("http://127.0.0.1:8088/predict") predict(endpoint, mtcars[4:7, -1]) }
Post new data to a deployed SageMaker model endpoint and return predictions
## S3 method for class 'vetiver_endpoint_sagemaker' predict(object, new_data, ...)
## S3 method for class 'vetiver_endpoint_sagemaker' predict(object, new_data, ...)
object |
A SageMaker model endpoint object created with |
new_data |
New data for making predictions, such as a data frame. |
... |
Extra arguments passed to |
A tibble of model predictions with as many rows as in new_data
.
augment.vetiver_endpoint_sagemaker()
if (FALSE) { endpoint <- vetiver_endpoint_sagemaker("sagemaker-demo-model") predict(endpoint, mtcars[4:7, -1]) }
if (FALSE) { endpoint <- vetiver_endpoint_sagemaker("sagemaker-demo-model") predict(endpoint, mtcars[4:7, -1]) }
vetiver_model()
objectUse vetiver_api()
to add a POST endpoint for predictions from a
trained vetiver_model()
to a Plumber router.
vetiver_api( pr, vetiver_model, path = "/predict", debug = is_interactive(), ... ) vetiver_pr_post( pr, vetiver_model, path = "/predict", debug = is_interactive(), ..., check_prototype = TRUE, check_ptype = deprecated() ) vetiver_pr_docs(pr, vetiver_model, path = "/predict", all_docs = TRUE)
vetiver_api( pr, vetiver_model, path = "/predict", debug = is_interactive(), ... ) vetiver_pr_post( pr, vetiver_model, path = "/predict", debug = is_interactive(), ..., check_prototype = TRUE, check_ptype = deprecated() ) vetiver_pr_docs(pr, vetiver_model, path = "/predict", all_docs = TRUE)
pr |
A Plumber router, such as from |
vetiver_model |
A deployable |
path |
The endpoint path |
debug |
|
... |
Other arguments passed to |
check_prototype |
Should the input data prototype stored in
|
check_ptype |
|
all_docs |
Should the interactive visual API documentation be created
for all POST endpoints in the router |
You can first store and version your vetiver_model()
with
vetiver_pin_write()
, and then create an API endpoint with vetiver_api()
.
Setting debug = TRUE
may expose any sensitive data from your model in
API errors.
Several GET endpoints will also be added to the router pr
, depending on the
characteristics of the model object:
a /pin-url
endpoint to return the URL of the pinned model
a /metadata
endpoint to return any metadata stored with the model
a /ping
endpoint for the API health
a /prototype
endpoint for the model's input data prototype (use
cereal::cereal_from_json()
) to convert this back to a vctrs ptype
The function vetiver_api()
uses:
vetiver_pr_post()
for endpoint definition and
vetiver_pr_docs()
to create visual API documentation
These modular functions are available for more advanced use cases.
A Plumber router with the prediction endpoint added.
cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") library(plumber) pr() %>% vetiver_api(v) ## is the same as: pr() %>% vetiver_pr_post(v) %>% vetiver_pr_docs(v) ## for either, next, pipe to `pr_run()`
cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") library(plumber) pr() %>% vetiver_api(v) ## is the same as: pr() %>% vetiver_pr_post(v) %>% vetiver_pr_docs(v) ## for either, next, pipe to `pr_run()`
These three functions can be used for model monitoring (such as in a monitoring dashboard):
vetiver_compute_metrics()
computes metrics (such as accuracy for a
classification model or RMSE for a regression model) at a chosen time
aggregation period
vetiver_pin_metrics()
updates an existing pin storing model metrics
over time
vetiver_plot_metrics()
creates a plot of metrics over time
vetiver_compute_metrics( data, date_var, period, truth, estimate, ..., metric_set = yardstick::metrics, every = 1L, origin = NULL, before = 0L, after = 0L, complete = FALSE )
vetiver_compute_metrics( data, date_var, period, truth, estimate, ..., metric_set = yardstick::metrics, every = 1L, origin = NULL, before = 0L, after = 0L, complete = FALSE )
data |
A |
date_var |
The column in |
period |
A string defining the period to group by. Valid inputs can be roughly broken into:
|
truth |
The column identifier for the true results (that
is |
estimate |
The column identifier for the predicted results
(that is also |
... |
A set of unquoted column names or one or more
|
metric_set |
A |
every |
The number of periods to group together. For example, if the period was set to |
origin |
The reference date time value. The default when left as This is generally used to define the anchor time to count from, which is
relevant when the every value is |
before , after
|
The number of values before or after the current element to
include in the sliding window. Set to |
complete |
Should the function be evaluated on complete windows only? If |
For arguments used more than once in your monitoring dashboard,
such as date_var
, consider using
R Markdown parameters
to reduce repetition and/or errors.
A dataframe of metrics.
vetiver_pin_metrics()
, vetiver_plot_metrics()
library(dplyr) library(parsnip) data(Chicago, package = "modeldata") Chicago <- Chicago %>% select(ridership, date, all_of(stations)) training_data <- Chicago %>% filter(date < "2009-01-01") testing_data <- Chicago %>% filter(date >= "2009-01-01", date < "2011-01-01") monitoring <- Chicago %>% filter(date >= "2011-01-01", date < "2012-12-31") lm_fit <- linear_reg() %>% fit(ridership ~ ., data = training_data) library(pins) b <- board_temp() original_metrics <- augment(lm_fit, new_data = testing_data) %>% vetiver_compute_metrics(date, "week", ridership, .pred, every = 4L) new_metrics <- augment(lm_fit, new_data = monitoring) %>% vetiver_compute_metrics(date, "week", ridership, .pred, every = 4L)
library(dplyr) library(parsnip) data(Chicago, package = "modeldata") Chicago <- Chicago %>% select(ridership, date, all_of(stations)) training_data <- Chicago %>% filter(date < "2009-01-01") testing_data <- Chicago %>% filter(date >= "2009-01-01", date < "2011-01-01") monitoring <- Chicago %>% filter(date >= "2011-01-01", date < "2012-12-31") lm_fit <- linear_reg() %>% fit(ridership ~ ., data = training_data) library(pins) b <- board_temp() original_metrics <- augment(lm_fit, new_data = testing_data) %>% vetiver_compute_metrics(date, "week", ridership, .pred, every = 4L) new_metrics <- augment(lm_fit, new_data = monitoring) %>% vetiver_compute_metrics(date, "week", ridership, .pred, every = 4L)
These are developer-facing functions, useful for supporting new model types.
Each model supported by vetiver_model()
uses up to four methods when the
deployable object is created:
The vetiver_create_description()
function generates a helpful description
of the model based on its characteristics. This method is required.
The vetiver_create_meta()
function creates the correct vetiver_meta()
for the model. This is especially helpful for specifying which packages are
needed for prediction. A model can use the default method here, which is
to have no special metadata.
The vetiver_ptype()
function finds an input data prototype from the
training data (a zero-row slice) to use for checking at prediction time.
This method is required.
The vetiver_prepare_model()
function executes last. Use this function
for tasks like checking if the model is trained and reducing the size of the
model via butcher::butcher()
. A model can use the default method here,
which is to return the model without changes.
## S3 method for class 'train' vetiver_create_description(model) ## S3 method for class 'train' vetiver_prepare_model(model) ## S3 method for class 'gam' vetiver_create_description(model) ## S3 method for class 'gam' vetiver_prepare_model(model) ## S3 method for class 'glm' vetiver_create_description(model) ## S3 method for class 'glm' vetiver_prepare_model(model) ## S3 method for class 'keras.engine.training.Model' vetiver_create_description(model) ## S3 method for class 'keras.engine.training.Model' vetiver_prepare_model(model) ## S3 method for class 'kproto' vetiver_create_description(model) ## S3 method for class 'kproto' vetiver_prepare_model(model) ## S3 method for class 'lm' vetiver_create_description(model) ## S3 method for class 'lm' vetiver_prepare_model(model) ## S3 method for class 'luz_module_fitted' vetiver_create_description(model) ## S3 method for class 'luz_module_fitted' vetiver_prepare_model(model) ## S3 method for class 'Learner' vetiver_create_description(model) ## S3 method for class 'Learner' vetiver_prepare_model(model) vetiver_create_description(model) ## Default S3 method: vetiver_create_description(model) vetiver_prepare_model(model) ## Default S3 method: vetiver_prepare_model(model) ## S3 method for class 'ranger' vetiver_create_description(model) ## S3 method for class 'ranger' vetiver_prepare_model(model) ## S3 method for class 'recipe' vetiver_create_description(model) ## S3 method for class 'recipe' vetiver_prepare_model(model) ## S3 method for class 'model_stack' vetiver_create_description(model) ## S3 method for class 'model_stack' vetiver_prepare_model(model) ## S3 method for class 'workflow' vetiver_create_description(model) ## S3 method for class 'workflow' vetiver_prepare_model(model) ## S3 method for class 'xgb.Booster' vetiver_create_description(model) ## S3 method for class 'xgb.Booster' vetiver_prepare_model(model)
## S3 method for class 'train' vetiver_create_description(model) ## S3 method for class 'train' vetiver_prepare_model(model) ## S3 method for class 'gam' vetiver_create_description(model) ## S3 method for class 'gam' vetiver_prepare_model(model) ## S3 method for class 'glm' vetiver_create_description(model) ## S3 method for class 'glm' vetiver_prepare_model(model) ## S3 method for class 'keras.engine.training.Model' vetiver_create_description(model) ## S3 method for class 'keras.engine.training.Model' vetiver_prepare_model(model) ## S3 method for class 'kproto' vetiver_create_description(model) ## S3 method for class 'kproto' vetiver_prepare_model(model) ## S3 method for class 'lm' vetiver_create_description(model) ## S3 method for class 'lm' vetiver_prepare_model(model) ## S3 method for class 'luz_module_fitted' vetiver_create_description(model) ## S3 method for class 'luz_module_fitted' vetiver_prepare_model(model) ## S3 method for class 'Learner' vetiver_create_description(model) ## S3 method for class 'Learner' vetiver_prepare_model(model) vetiver_create_description(model) ## Default S3 method: vetiver_create_description(model) vetiver_prepare_model(model) ## Default S3 method: vetiver_prepare_model(model) ## S3 method for class 'ranger' vetiver_create_description(model) ## S3 method for class 'ranger' vetiver_prepare_model(model) ## S3 method for class 'recipe' vetiver_create_description(model) ## S3 method for class 'recipe' vetiver_prepare_model(model) ## S3 method for class 'model_stack' vetiver_create_description(model) ## S3 method for class 'model_stack' vetiver_prepare_model(model) ## S3 method for class 'workflow' vetiver_create_description(model) ## S3 method for class 'workflow' vetiver_prepare_model(model) ## S3 method for class 'xgb.Booster' vetiver_create_description(model) ## S3 method for class 'xgb.Booster' vetiver_prepare_model(model)
model |
A trained model, such as an |
These are four generics that use the class of model
for dispatch.
cars_lm <- lm(mpg ~ ., data = mtcars) vetiver_create_description(cars_lm) vetiver_prepare_model(cars_lm)
cars_lm <- lm(mpg ~ ., data = mtcars) vetiver_create_description(cars_lm) vetiver_prepare_model(cars_lm)
vetiver_model()
objectThese are developer-facing functions, useful for supporting new model types.
The metadata stored in a vetiver_model()
object has four elements:
$user
, the metadata supplied by the user
$version
, the version of the pin (which can be NULL
before pinning)
$url
, the URL where the pin is located, if any
$required_pkgs
, a character string of R packages required for prediction
## S3 method for class 'train' vetiver_create_meta(model, metadata) ## S3 method for class 'gam' vetiver_create_meta(model, metadata) ## S3 method for class 'keras.engine.training.Model' vetiver_create_meta(model, metadata) ## S3 method for class 'kproto' vetiver_create_meta(model, metadata) ## S3 method for class 'luz_module_fitted' vetiver_create_meta(model, metadata) vetiver_meta(user = list(), version = NULL, url = NULL, required_pkgs = NULL) vetiver_create_meta(model, metadata) ## Default S3 method: vetiver_create_meta(model, metadata) ## S3 method for class 'Learner' vetiver_create_meta(model, metadata) ## S3 method for class 'ranger' vetiver_create_meta(model, metadata) ## S3 method for class 'recipe' vetiver_create_meta(model, metadata) ## S3 method for class 'model_stack' vetiver_create_meta(model, metadata) ## S3 method for class 'workflow' vetiver_create_meta(model, metadata) ## S3 method for class 'xgb.Booster' vetiver_create_meta(model, metadata)
## S3 method for class 'train' vetiver_create_meta(model, metadata) ## S3 method for class 'gam' vetiver_create_meta(model, metadata) ## S3 method for class 'keras.engine.training.Model' vetiver_create_meta(model, metadata) ## S3 method for class 'kproto' vetiver_create_meta(model, metadata) ## S3 method for class 'luz_module_fitted' vetiver_create_meta(model, metadata) vetiver_meta(user = list(), version = NULL, url = NULL, required_pkgs = NULL) vetiver_create_meta(model, metadata) ## Default S3 method: vetiver_create_meta(model, metadata) ## S3 method for class 'Learner' vetiver_create_meta(model, metadata) ## S3 method for class 'ranger' vetiver_create_meta(model, metadata) ## S3 method for class 'recipe' vetiver_create_meta(model, metadata) ## S3 method for class 'model_stack' vetiver_create_meta(model, metadata) ## S3 method for class 'workflow' vetiver_create_meta(model, metadata) ## S3 method for class 'xgb.Booster' vetiver_create_meta(model, metadata)
model |
A trained model, such as an |
metadata |
A list containing additional metadata to store with the pin.
When retrieving the pin, this will be stored in the |
user |
Metadata supplied by the user |
version |
Version of the pin |
url |
URL for the pin, if any |
required_pkgs |
Character string of R packages required for prediction |
The vetiver_meta()
constructor returns a list. The
vetiver_create_meta
function returns a vetiver_meta()
list.
vetiver_meta() cars_lm <- lm(mpg ~ ., data = mtcars) vetiver_create_meta(cars_lm, list())
vetiver_meta() cars_lm <- lm(mpg ~ ., data = mtcars) vetiver_create_meta(cars_lm, list())
Use vetiver_create_rsconnect_bundle()
to create a
Posit Connect model API bundle for a
vetiver_model()
that has been versioned and stored via
vetiver_pin_write()
.
vetiver_create_rsconnect_bundle( board, name, version = NULL, predict_args = list(), filename = fs::file_temp(pattern = "bundle", ext = ".tar.gz"), additional_pkgs = character(0) )
vetiver_create_rsconnect_bundle( board, name, version = NULL, predict_args = list(), filename = fs::file_temp(pattern = "bundle", ext = ".tar.gz"), additional_pkgs = character(0) )
board |
A pin board, created by |
name |
Pin name. |
version |
Retrieve a specific version of a pin. Use |
predict_args |
A list of optional arguments passed to |
filename |
The path for the model API bundle to be created (can be
used as the argument to |
additional_pkgs |
Any additional R packages that need to be attached
via |
This function creates a deployable bundle. See Posit Connect docs for how to deploy this bundle, as well as the connectapi R package for how to integrate with Connect's API from R.
The two functions vetiver_create_rsconnect_bundle()
and
vetiver_deploy_rsconnect()
are alternatives to each other, providing
different strategies for deploying a vetiver model API to Posit Connect.
The location of the model API bundle filename
, invisibly.
vetiver_write_plumber()
, vetiver_deploy_rsconnect()
library(pins) b <- board_temp(versioned = TRUE) cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(b, v) ## when you pin to Posit Connect, your pin name will be typically be like: ## "user.name/cars_linear" vetiver_create_rsconnect_bundle( b, "cars_linear", predict_args = list(debug = TRUE) )
library(pins) b <- board_temp(versioned = TRUE) cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(b, v) ## when you pin to Posit Connect, your pin name will be typically be like: ## "user.name/cars_linear" vetiver_create_rsconnect_bundle( b, "cars_linear", predict_args = list(debug = TRUE) )
R Markdown format for model monitoring dashboards
vetiver_dashboard(pins = list(), display_pins = TRUE, ...) get_vetiver_dashboard_pins() pin_example_kc_housing_model(board = pins::board_local(), name = "seattle_rf")
vetiver_dashboard(pins = list(), display_pins = TRUE, ...) get_vetiver_dashboard_pins() pin_example_kc_housing_model(board = pins::board_local(), name = "seattle_rf")
pins |
A list containing |
display_pins |
Should the dashboard display a link to the pin(s)?
Defaults to |
... |
Arguments passed to |
board |
A pin board, created by |
name |
Pin name. |
The vetiver_dashboard()
function is a specialized type of
flexdashboard. See the flexdashboard website for additional
documentation:
https://pkgs.rstudio.com/flexdashboard/
Before knitting the example vetiver_dashboard()
template, execute the
helper function pin_example_kc_housing_model()
to set up demonstration
model and metrics pins needed for the monitoring demo. This function will:
fit an example model to training data
pin the vetiver model to your own pins::board_local()
compute metrics from testing data
pin these metrics to the same local board
These are the steps you need to complete before setting up monitoring your real model.
Use vetiver_deploy_rsconnect()
to deploy a vetiver_model()
that has been
versioned and stored via vetiver_pin_write()
as a Plumber API on Posit Connect.
vetiver_deploy_rsconnect( board, name, version = NULL, predict_args = list(), appTitle = glue::glue("{name} model API"), ..., additional_pkgs = character(0) )
vetiver_deploy_rsconnect( board, name, version = NULL, predict_args = list(), appTitle = glue::glue("{name} model API"), ..., additional_pkgs = character(0) )
board |
A pin board, created by |
name |
Pin name. |
version |
Retrieve a specific version of a pin. Use |
predict_args |
A list of optional arguments passed to |
appTitle |
The API title on Posit Connect. Use the default based on
|
... |
Other arguments passed to |
additional_pkgs |
Any additional R packages that need to be attached
via |
The two functions vetiver_deploy_rsconnect()
and
vetiver_create_rsconnect_bundle()
are alternatives to each other, providing
different strategies for deploying a vetiver model API to Posit Connect.
When you first deploy to Connect, your API will only be accessible to you. You can change the access settings so others can also access the API. For all access settings other than "Anyone - no login required", anyone querying your API (including you) will need to pass authentication details with your API call, as shown in the Connect documentation.
The deployment success (TRUE
or FALSE
), invisibly.
vetiver_write_plumber()
, vetiver_create_rsconnect_bundle()
library(pins) b <- board_temp(versioned = TRUE) cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(b, v) if (FALSE) { ## pass args for predicting: vetiver_deploy_rsconnect( b, "user.name/cars_linear", predict_args = list(debug = TRUE) ) ## specify an account name through `...`: vetiver_deploy_rsconnect( b, "user.name/cars_linear", account = "user.name" ) }
library(pins) b <- board_temp(versioned = TRUE) cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(b, v) if (FALSE) { ## pass args for predicting: vetiver_deploy_rsconnect( b, "user.name/cars_linear", predict_args = list(debug = TRUE) ) ## specify an account name through `...`: vetiver_deploy_rsconnect( b, "user.name/cars_linear", account = "user.name" ) }
Use vetiver_deploy_sagemaker()
to deploy a vetiver_model()
that has been versioned and stored via vetiver_pin_write()
as a Plumber API
on Amazon SageMaker.
vetiver_deploy_sagemaker( board, name, instance_type, ..., predict_args = list(), docker_args = list(), build_args = list(), endpoint_args = list(), repo_name = glue("vetiver-sagemaker-{name}") )
vetiver_deploy_sagemaker( board, name, instance_type, ..., predict_args = list(), docker_args = list(), build_args = list(), endpoint_args = list(), repo_name = glue("vetiver-sagemaker-{name}") )
board |
An AWS S3 board created with |
name |
Pin name. |
instance_type |
Type of EC2 instance to use; see Amazon SageMaker pricing. |
... |
Not currently used. |
predict_args |
A list of optional arguments passed to |
docker_args |
A list of optional arguments passed to
|
build_args |
A list of optional arguments passed to
|
endpoint_args |
A list of optional arguments passed to
|
repo_name |
The name for the AWS ECR repository to store the model. |
This function stores your model deployment image in the same bucket used
by board
.
The function vetiver_deploy_sagemaker()
uses:
vetiver_sm_build()
to build and push a Docker image to ECR,
vetiver_sm_model()
to create a SageMaker model, and
vetiver_sm_endpoint()
to deploy a SageMaker model endpoint.
These modular functions are available for more advanced use cases.
If you are working locally, you will likely need to explicitly set up your execution role to work correctly. Check out "Execution role requirements" in the smdocker documentation, and especially note that the bucket containing your vetiver model needs to be added as a resource in your IAM role policy.
The deployed vetiver_endpoint_sagemaker()
.
vetiver_sm_build()
, vetiver_sm_model()
, vetiver_sm_endpoint()
if (FALSE) { library(pins) b <- board_s3(bucket = "my-existing-bucket") cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(b, v) endpoint <- vetiver_deploy_sagemaker( board = b, name = "cars_linear", instance_type = "ml.t2.medium", predict_args = list(type = "class", debug = TRUE) ) }
if (FALSE) { library(pins) b <- board_s3(bucket = "my-existing-bucket") cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(b, v) endpoint <- vetiver_deploy_sagemaker( board = b, name = "cars_linear", instance_type = "ml.t2.medium", predict_args = list(type = "class", debug = TRUE) ) }
This function creates a model API endpoint for prediction from a URL. No
HTTP calls are made until you actually
predict()
with your endpoint.
vetiver_endpoint(url)
vetiver_endpoint(url)
url |
An API endpoint URL |
A new vetiver_endpoint
object
vetiver_endpoint("https://colorado.rstudio.com/rsc/seattle-housing/predict")
vetiver_endpoint("https://colorado.rstudio.com/rsc/seattle-housing/predict")
This function creates a model API endpoint for prediction from a Sagemaker Model.
No HTTP calls are made until you actually
predict()
with your endpoint.
vetiver_endpoint_sagemaker(model_endpoint)
vetiver_endpoint_sagemaker(model_endpoint)
model_endpoint |
The name of the Amazon SageMaker model endpoint. |
A new vetiver_endpoint_sagemaker
object
vetiver_endpoint_sagemaker("vetiver-sagemaker-demo-model")
vetiver_endpoint_sagemaker("vetiver-sagemaker-demo-model")
A vetiver_model()
object collects the information needed to store, version,
and deploy a trained model. Once your vetiver_model()
object has been
created, you can:
store and version it as a pin with vetiver_pin_write()
create an API endpoint for it with vetiver_api()
vetiver_model( model, model_name, ..., description = NULL, metadata = list(), save_prototype = TRUE, save_ptype = deprecated(), versioned = NULL ) new_vetiver_model( model, model_name, description, metadata, prototype, versioned )
vetiver_model( model, model_name, ..., description = NULL, metadata = list(), save_prototype = TRUE, save_ptype = deprecated(), versioned = NULL ) new_vetiver_model( model, model_name, description, metadata, prototype, versioned )
model |
A trained model, such as an |
model_name |
Model name or ID. |
... |
Other method-specific arguments passed to |
description |
A detailed description of the model. If omitted, a brief description of the model will be generated. |
metadata |
A list containing additional metadata to store with the pin.
When retrieving the pin, this will be stored in the |
save_prototype |
Should an input data prototype be stored with the model?
The options are |
save_ptype |
|
versioned |
Should the model object be versioned when stored with
|
prototype |
An input data prototype. If |
You can provide your own data to save_prototype
to use as examples in the
visual documentation created by vetiver_api()
. If you do this,
consider checking that your input data prototype has the same structure
as your training data (perhaps with hardhat::scream()
) and/or simulating
data to avoid leaking PII via your deployed model.
Some models, like ranger::ranger()
, keras,
and luz (torch),
require that you pass in example training data as prototype_data
or else explicitly set save_prototype = FALSE
. For non-rectangular data
input to models, such as image input for a keras or torch model, we currently
recommend that you turn off prototype checking via save_prototype = FALSE
.
A new vetiver_model
object.
cars_lm <- lm(mpg ~ ., data = mtcars) vetiver_model(cars_lm, "cars-linear")
cars_lm <- lm(mpg ~ ., data = mtcars) vetiver_model(cars_lm, "cars-linear")
These three functions can be used for model monitoring (such as in a monitoring dashboard):
vetiver_compute_metrics()
computes metrics (such as accuracy for a
classification model or RMSE for a regression model) at a chosen time
aggregation period
vetiver_pin_metrics()
updates an existing pin storing model metrics
over time
vetiver_plot_metrics()
creates a plot of metrics over time
vetiver_pin_metrics( board, df_metrics, metrics_pin_name, .index = .index, overwrite = FALSE, type = NULL, ... )
vetiver_pin_metrics( board, df_metrics, metrics_pin_name, .index = .index, overwrite = FALSE, type = NULL, ... )
board |
A pin board, created by |
df_metrics |
A tidy dataframe of metrics over time, such as created by
|
metrics_pin_name |
Pin name for where the metrics are stored (as
opposed to where the model object is stored with |
.index |
The variable in |
overwrite |
If |
type |
File type used to save metrics to disk. With the default |
... |
Additional arguments passed on to methods for a specific board. |
Sometimes when you monitor a model at a given time aggregation, you
may end up with dates in your new metrics (like new_metrics
in the example)
that are the same as dates in your existing aggregated metrics (like
original_metrics
in the example). This can happen if you need to re-run a
monitoring report because something failed. With overwrite = FALSE
(the
default), vetiver_pin_metrics()
will error when there are overlapping
dates. With overwrite = TRUE
, vetiver_pin_metrics()
will replace such
metrics with the new values. You probably want FALSE
for interactive use
and TRUE
for dashboards or reports that run on a schedule.
You can initially create your pin with type = "arrow"
or the default
(type = "rds"
). vetiver_pin_metrics()
will update the pin using the
same type
by default.
A dataframe of metrics.
vetiver_compute_metrics()
, vetiver_plot_metrics()
library(dplyr) library(parsnip) data(Chicago, package = "modeldata") Chicago <- Chicago %>% select(ridership, date, all_of(stations)) training_data <- Chicago %>% filter(date < "2009-01-01") testing_data <- Chicago %>% filter(date >= "2009-01-01", date < "2011-01-01") monitoring <- Chicago %>% filter(date >= "2011-01-01", date < "2012-12-31") lm_fit <- linear_reg() %>% fit(ridership ~ ., data = training_data) library(pins) b <- board_temp() ## before starting monitoring, initiate the metrics and pin ## (for example, with the testing data): original_metrics <- augment(lm_fit, new_data = testing_data) %>% vetiver_compute_metrics(date, "week", ridership, .pred, every = 4L) pin_write(b, original_metrics, "lm_fit_metrics", type = "arrow") ## to continue monitoring with new data, compute metrics and update pin: new_metrics <- augment(lm_fit, new_data = monitoring) %>% vetiver_compute_metrics(date, "week", ridership, .pred, every = 4L) vetiver_pin_metrics(b, new_metrics, "lm_fit_metrics")
library(dplyr) library(parsnip) data(Chicago, package = "modeldata") Chicago <- Chicago %>% select(ridership, date, all_of(stations)) training_data <- Chicago %>% filter(date < "2009-01-01") testing_data <- Chicago %>% filter(date >= "2009-01-01", date < "2011-01-01") monitoring <- Chicago %>% filter(date >= "2011-01-01", date < "2012-12-31") lm_fit <- linear_reg() %>% fit(ridership ~ ., data = training_data) library(pins) b <- board_temp() ## before starting monitoring, initiate the metrics and pin ## (for example, with the testing data): original_metrics <- augment(lm_fit, new_data = testing_data) %>% vetiver_compute_metrics(date, "week", ridership, .pred, every = 4L) pin_write(b, original_metrics, "lm_fit_metrics", type = "arrow") ## to continue monitoring with new data, compute metrics and update pin: new_metrics <- augment(lm_fit, new_data = monitoring) %>% vetiver_compute_metrics(date, "week", ridership, .pred, every = 4L) vetiver_pin_metrics(b, new_metrics, "lm_fit_metrics")
Use vetiver_pin_write()
to pin a trained model to a board of models,
along with an input prototype for new data and other model metadata. Use
vetiver_pin_read()
to retrieve that pinned object.
vetiver_pin_write(board, vetiver_model, ..., check_renv = FALSE) vetiver_pin_read(board, name, version = NULL, check_renv = FALSE)
vetiver_pin_write(board, vetiver_model, ..., check_renv = FALSE) vetiver_pin_read(board, name, version = NULL, check_renv = FALSE)
board |
A pin board, created by |
vetiver_model |
A deployable |
... |
Additional arguments passed on to methods for a specific board. |
check_renv |
Use renv to record the
packages used at training time with |
name |
Pin name. |
version |
Retrieve a specific version of a pin. Use |
These functions read and write a vetiver_model()
pin on the
specified board
containing the model object itself and other elements
needed for prediction, such as the model's input data prototype or which
packages are needed at prediction time. You may use pins::pin_read()
or
pins::pin_meta()
to handle the pin, but vetiver_pin_read()
returns a
vetiver_model()
object ready for deployment.
vetiver_pin_read()
returns a vetiver_model()
; vetiver_pin_write()
returns the name of the new pin, invisibly.
library(pins) model_board <- board_temp() cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(model_board, v) model_board vetiver_pin_read(model_board, "cars_linear") # can use `version` argument to read a specific version: pin_versions(model_board, "cars_linear") # can store an renv lockfile as part of the pin: vetiver_pin_write(model_board, v, check_renv = TRUE)
library(pins) model_board <- board_temp() cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(model_board, v) model_board vetiver_pin_read(model_board, "cars_linear") # can use `version` argument to read a specific version: pin_versions(model_board, "cars_linear") # can store an renv lockfile as part of the pin: vetiver_pin_write(model_board, v, check_renv = TRUE)
These three functions can be used for model monitoring (such as in a monitoring dashboard):
vetiver_compute_metrics()
computes metrics (such as accuracy for a
classification model or RMSE for a regression model) at a chosen time
aggregation period
vetiver_pin_metrics()
updates an existing pin storing model metrics
over time
vetiver_plot_metrics()
creates a plot of metrics over time
vetiver_plot_metrics( df_metrics, .index = .index, .estimate = .estimate, .metric = .metric, .n = .n )
vetiver_plot_metrics( df_metrics, .index = .index, .estimate = .estimate, .metric = .metric, .n = .n )
df_metrics |
A tidy dataframe of metrics over time, such as created by
|
.index |
The variable in |
.estimate |
The variable in |
.metric |
The variable in |
.n |
The variable in |
A ggplot2
object.
vetiver_compute_metrics()
, vetiver_pin_metrics()
library(dplyr) library(parsnip) data(Chicago, package = "modeldata") Chicago <- Chicago %>% select(ridership, date, all_of(stations)) training_data <- Chicago %>% filter(date < "2009-01-01") testing_data <- Chicago %>% filter(date >= "2009-01-01", date < "2011-01-01") monitoring <- Chicago %>% filter(date >= "2011-01-01", date < "2012-12-31") lm_fit <- linear_reg() %>% fit(ridership ~ ., data = training_data) library(pins) b <- board_temp() ## before starting monitoring, initiate the metrics and pin ## (for example, with the testing data): original_metrics <- augment(lm_fit, new_data = testing_data) %>% vetiver_compute_metrics(date, "week", ridership, .pred, every = 4L) pin_write(b, original_metrics, "lm_fit_metrics", type = "arrow") ## to continue monitoring with new data, compute metrics and update pin: new_metrics <- augment(lm_fit, new_data = monitoring) %>% vetiver_compute_metrics(date, "week", ridership, .pred, every = 4L) vetiver_pin_metrics(b, new_metrics, "lm_fit_metrics") library(ggplot2) vetiver_plot_metrics(new_metrics) + scale_size(range = c(2, 4))
library(dplyr) library(parsnip) data(Chicago, package = "modeldata") Chicago <- Chicago %>% select(ridership, date, all_of(stations)) training_data <- Chicago %>% filter(date < "2009-01-01") testing_data <- Chicago %>% filter(date >= "2009-01-01", date < "2011-01-01") monitoring <- Chicago %>% filter(date >= "2011-01-01", date < "2012-12-31") lm_fit <- linear_reg() %>% fit(ridership ~ ., data = training_data) library(pins) b <- board_temp() ## before starting monitoring, initiate the metrics and pin ## (for example, with the testing data): original_metrics <- augment(lm_fit, new_data = testing_data) %>% vetiver_compute_metrics(date, "week", ridership, .pred, every = 4L) pin_write(b, original_metrics, "lm_fit_metrics", type = "arrow") ## to continue monitoring with new data, compute metrics and update pin: new_metrics <- augment(lm_fit, new_data = monitoring) %>% vetiver_compute_metrics(date, "week", ridership, .pred, every = 4L) vetiver_pin_metrics(b, new_metrics, "lm_fit_metrics") library(ggplot2) vetiver_plot_metrics(new_metrics) + scale_size(range = c(2, 4))
Deploying a vetiver model via Docker requires several files. Use this
function to create these needed files in the directory located at path
.
vetiver_prepare_docker( board, name, version = NULL, path = ".", predict_args = list(), docker_args = list() )
vetiver_prepare_docker( board, name, version = NULL, path = ".", predict_args = list(), docker_args = list() )
board |
A pin board, created by |
name |
Pin name. |
version |
Retrieve a specific version of a pin. Use |
path |
A path to write the Plumber file, Dockerfile, and lockfile, capturing the model's dependencies. |
predict_args |
A list of optional arguments passed to |
docker_args |
A list of optional arguments passed to
|
The function vetiver_prepare_docker()
uses:
vetiver_write_plumber()
to create a Plumber file and
vetiver_write_docker()
to create a Dockerfile and renv lockfile
These modular functions are available for more advanced use cases. For
models such as keras and torch, you will need to edit the generated
Dockerfile to, for example, COPY requirements.txt requirements.txt
or
similar.
An invisible TRUE
.
library(pins) b <- board_temp(versioned = TRUE) cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(b, v) vetiver_prepare_docker(b, "cars_linear", path = tempdir())
library(pins) b <- board_temp(versioned = TRUE) cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(b, v) vetiver_prepare_docker(b, "cars_linear", path = tempdir())
Optionally find and return an input data prototype for a model.
## S3 method for class 'train' vetiver_ptype(model, ...) ## S3 method for class 'gam' vetiver_ptype(model, ...) ## S3 method for class 'glm' vetiver_ptype(model, ...) ## S3 method for class 'keras.engine.training.Model' vetiver_ptype(model, ...) ## S3 method for class 'kproto' vetiver_ptype(model, ...) ## S3 method for class 'lm' vetiver_ptype(model, ...) ## S3 method for class 'luz_module_fitted' vetiver_ptype(model, ...) ## S3 method for class 'Learner' vetiver_ptype(model, ...) vetiver_ptype(model, ...) ## Default S3 method: vetiver_ptype(model, ...) vetiver_create_ptype(model, save_prototype, ...) ## S3 method for class 'ranger' vetiver_ptype(model, ...) ## S3 method for class 'recipe' vetiver_ptype(model, ...) ## S3 method for class 'model_stack' vetiver_ptype(model, ...) ## S3 method for class 'workflow' vetiver_ptype(model, ...) ## S3 method for class 'xgb.Booster' vetiver_ptype(model, ...)
## S3 method for class 'train' vetiver_ptype(model, ...) ## S3 method for class 'gam' vetiver_ptype(model, ...) ## S3 method for class 'glm' vetiver_ptype(model, ...) ## S3 method for class 'keras.engine.training.Model' vetiver_ptype(model, ...) ## S3 method for class 'kproto' vetiver_ptype(model, ...) ## S3 method for class 'lm' vetiver_ptype(model, ...) ## S3 method for class 'luz_module_fitted' vetiver_ptype(model, ...) ## S3 method for class 'Learner' vetiver_ptype(model, ...) vetiver_ptype(model, ...) ## Default S3 method: vetiver_ptype(model, ...) vetiver_create_ptype(model, save_prototype, ...) ## S3 method for class 'ranger' vetiver_ptype(model, ...) ## S3 method for class 'recipe' vetiver_ptype(model, ...) ## S3 method for class 'model_stack' vetiver_ptype(model, ...) ## S3 method for class 'workflow' vetiver_ptype(model, ...) ## S3 method for class 'xgb.Booster' vetiver_ptype(model, ...)
model |
A trained model, such as an |
... |
Other method-specific arguments passed to |
save_prototype |
Should an input data prototype be stored with the model?
The options are |
These are developer-facing functions, useful for supporting new model types.
A vetiver_model()
object optionally stores an input data prototype for
checking at prediction time.
The default for save_prototype
, TRUE
, finds an input data prototype (a
zero-row slice of the training data) via vetiver_ptype()
.
save_prototype = FALSE
opts out of storing any input data prototype.
You may pass your own data to save_prototype
, but be sure to check that it
has the same structure as your training data, perhaps with
hardhat::scream()
.
A vetiver_ptype
method returns a zero-row dataframe, and
vetiver_create_ptype()
returns either such a zero-row dataframe, NULL
,
or the dataframe passed to save_prototype
.
cars_lm <- lm(mpg ~ cyl + disp, data = mtcars) vetiver_create_ptype(cars_lm, TRUE) ## calls the right method for `model` via: vetiver_ptype(cars_lm) ## can also turn off prototype vetiver_create_ptype(cars_lm, FALSE) ## some models require that you pass in training features cars_rf <- ranger::ranger(mpg ~ ., data = mtcars) vetiver_ptype(cars_rf, prototype_data = mtcars[,-1])
cars_lm <- lm(mpg ~ cyl + disp, data = mtcars) vetiver_create_ptype(cars_lm, TRUE) ## calls the right method for `model` via: vetiver_ptype(cars_lm) ## can also turn off prototype vetiver_create_ptype(cars_lm, FALSE) ## some models require that you pass in training features cars_rf <- ranger::ranger(mpg ~ ., data = mtcars) vetiver_ptype(cars_rf, prototype_data = mtcars[,-1])
Use the function vetiver_deploy_sagemaker()
for basic deployment on
SageMaker, or these three functions
together for more advanced use cases:
vetiver_sm_build()
generates and builds a Docker image on SageMaker for
a vetiver model
vetiver_sm_model()
creates an Amazon SageMaker model
vetiver_sm_endpoint()
deploys an Amazon SageMaker model endpoint
vetiver_sm_build( board, name, version = NULL, path = fs::dir_create(tempdir(), "vetiver"), predict_args = list(), docker_args = list(), repository = NULL, compute_type = c("BUILD_GENERAL1_SMALL", "BUILD_GENERAL1_MEDIUM", "BUILD_GENERAL1_LARGE", "BUILD_GENERAL1_2XLARGE"), role = NULL, bucket = NULL, vpc_id = NULL, subnet_ids = list(), security_group_ids = list(), log = TRUE, ... ) vetiver_sm_model( image_uri, model_name, role = NULL, vpc_config = list(), enable_network_isolation = FALSE, tags = list() ) vetiver_sm_endpoint( model_name, instance_type, endpoint_name = NULL, initial_instance_count = 1, accelerator_type = NULL, tags = list(), kms_key = NULL, data_capture_config = list(), volume_size = NULL, model_data_download_timeout = NULL, wait = TRUE )
vetiver_sm_build( board, name, version = NULL, path = fs::dir_create(tempdir(), "vetiver"), predict_args = list(), docker_args = list(), repository = NULL, compute_type = c("BUILD_GENERAL1_SMALL", "BUILD_GENERAL1_MEDIUM", "BUILD_GENERAL1_LARGE", "BUILD_GENERAL1_2XLARGE"), role = NULL, bucket = NULL, vpc_id = NULL, subnet_ids = list(), security_group_ids = list(), log = TRUE, ... ) vetiver_sm_model( image_uri, model_name, role = NULL, vpc_config = list(), enable_network_isolation = FALSE, tags = list() ) vetiver_sm_endpoint( model_name, instance_type, endpoint_name = NULL, initial_instance_count = 1, accelerator_type = NULL, tags = list(), kms_key = NULL, data_capture_config = list(), volume_size = NULL, model_data_download_timeout = NULL, wait = TRUE )
board |
An AWS S3 board created with |
name |
Pin name. |
version |
Retrieve a specific version of a pin. Use |
path |
A path to write the Plumber file, Dockerfile, and lockfile, capturing the model's dependencies. |
predict_args |
A list of optional arguments passed to |
docker_args |
A list of optional arguments passed to
|
repository |
The ECR repository and tag for the image as a character.
Defaults to |
compute_type |
The CodeBuild
compute type as a character. Defaults to |
role |
The ARN IAM role name (as a character) to be used with:
Defaults to the SageMaker Studio execution role. |
bucket |
The S3 bucket to use for sending data to CodeBuild as a character. Defaults to the SageMaker SDK default bucket. |
vpc_id |
ID of the VPC that will host the CodeBuild project such as
|
subnet_ids |
List of subnet IDs for the CodeBuild project, such as
|
security_group_ids |
List of security group IDs for the CodeBuild
project, such as |
log |
A logical to show the logs of the running CodeBuild build.
Defaults to |
... |
Docker build parameters
(Use "_" instead of "-"; for example, Docker optional parameter
|
image_uri |
The AWS ECR image URI for the Amazon SageMaker Model to be
created (for example, as returned by |
model_name |
The Amazon SageMaker model name to be deployed. |
vpc_config |
A list containing the VPC configuration for the Amazon SageMaker model API VpcConfig (optional).
|
enable_network_isolation |
A logical to specify whether the container
will run in network isolation mode. Defaults to |
tags |
A named list of tags for labeling the Amazon SageMaker model or model endpint to be created. |
instance_type |
Type of EC2 instance to use; see Amazon SageMaker pricing. |
endpoint_name |
The name to use for the Amazon SageMaker model endpoint
to be created, if to be different from |
initial_instance_count |
The initial number of instances to run in the endpoint. |
accelerator_type |
Type of Elastic Inference accelerator to
attach to an endpoint for model loading and inference, for
example, |
kms_key |
The ARN of the KMS key used to encrypt the data on the storage volume attached to the instance hosting the endpoint. |
data_capture_config |
A list for configuration to control how Amazon SageMaker captures inference data. |
volume_size |
The size, in GB, of the ML storage volume attached to the individual inference instance associated with the production variant. Currently only Amazon EBS gp2 storage volumes are supported. |
model_data_download_timeout |
The timeout value, in seconds, to download and extract model data from Amazon S3. |
wait |
A logical for whether to wait for the endpoint to be deployed.
Defaults to |
The function vetiver_sm_build()
generates the files necessary to
build a Docker container to deploy a vetiver model in SageMaker and then
builds the image on AWS CodeBuild. The
resulting image is stored in AWS ECR.
This function creates a Plumber file and Dockerfile appropriate for
SageMaker, for example, with path = "/invocations"
and port = 8080
.
If you run into problems with Docker rate limits, then either
authenticate to Docker from SageMaker, or
use a public ECR base image,
passed through docker_args
vetiver_sm_build()
returns the AWS ECR image URI and
vetiver_sm_model()
returns the model name (both as characters).
vetiver_sm_endpoint()
returns a new vetiver_endpoint_sagemaker()
object.
vetiver_prepare_docker()
, vetiver_deploy_sagemaker()
, vetiver_endpoint_sagemaker()
if (FALSE) { library(pins) b <- board_s3(bucket = "my-existing-bucket") cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(b, v) new_image_uri <- vetiver_sm_build( board = b, name = "cars_linear", predict_args = list(type = "class", debug = TRUE), docker_args = list( base_image = "FROM public.ecr.aws/docker/library/r-base:4.2.2" ) ) model_name <- vetiver_sm_model( new_image_uri, tags = list("my_custom_tag" = "fuel_efficiency") ) vetiver_sm_endpoint(model_name, "ml.t2.medium") }
if (FALSE) { library(pins) b <- board_s3(bucket = "my-existing-bucket") cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(b, v) new_image_uri <- vetiver_sm_build( board = b, name = "cars_linear", predict_args = list(type = "class", debug = TRUE), docker_args = list( base_image = "FROM public.ecr.aws/docker/library/r-base:4.2.2" ) ) model_name <- vetiver_sm_model( new_image_uri, tags = list("my_custom_tag" = "fuel_efficiency") ) vetiver_sm_endpoint(model_name, "ml.t2.medium") }
Use this function to delete the Amazon SageMaker components used in a
vetiver_endpoint_sagemaker()
object. This function does not delete
any pinned model object in S3.
vetiver_sm_delete(object, delete_model = TRUE, delete_endpoint = TRUE)
vetiver_sm_delete(object, delete_model = TRUE, delete_endpoint = TRUE)
object |
The model API endpoint object to be deleted, created with
|
delete_model |
Delete the SageMaker model? Defaults to |
delete_endpoint |
Delete both the endpoint and endpoint configuration?
Defaults to |
TRUE
, invisibly
vetiver_deploy_sagemaker()
, vetiver_sm_build()
, vetiver_endpoint_sagemaker()
This is a developer-facing function, useful for supporting new model types. At prediction time, new observations typically must be checked and sometimes converted to the data types from training time.
vetiver_type_convert(new_data, ptype)
vetiver_type_convert(new_data, ptype)
new_data |
New data for making predictions, such as a data frame. |
ptype |
An input data prototype, such as a 0-row slice of the training data |
A converted dataframe
library(tibble) training_df <- tibble(x = as.Date("2021-01-01") + 0:9, y = LETTERS[1:10], z = letters[11:20]) training_df prototype <- vctrs::vec_slice(training_df, 0) vetiver_type_convert(tibble(x = "2021-02-01", y = "J", z = "k"), prototype) ## unsuccessful conversion generates an error: try(vetiver_type_convert(tibble(x = "potato", y = "J", z = "k"), prototype)) ## error for missing column: try(vetiver_type_convert(tibble(x = "potato", y = "J"), prototype))
library(tibble) training_df <- tibble(x = as.Date("2021-01-01") + 0:9, y = LETTERS[1:10], z = letters[11:20]) training_df prototype <- vctrs::vec_slice(training_df, 0) vetiver_type_convert(tibble(x = "2021-02-01", y = "J", z = "k"), prototype) ## unsuccessful conversion generates an error: try(vetiver_type_convert(tibble(x = "potato", y = "J", z = "k"), prototype)) ## error for missing column: try(vetiver_type_convert(tibble(x = "potato", y = "J"), prototype))
After creating a Plumber file with vetiver_write_plumber()
, use
vetiver_write_docker()
to create a Dockerfile plus a vetiver_renv.lock
file for a pinned vetiver_model()
.
vetiver_write_docker( vetiver_model, plumber_file = "plumber.R", path = ".", ..., lockfile = "vetiver_renv.lock", rspm = TRUE, base_image = glue::glue("FROM rocker/r-ver:{getRversion()}"), port = 8000, expose = TRUE, additional_pkgs = character(0) )
vetiver_write_docker( vetiver_model, plumber_file = "plumber.R", path = ".", ..., lockfile = "vetiver_renv.lock", rspm = TRUE, base_image = glue::glue("FROM rocker/r-ver:{getRversion()}"), port = 8000, expose = TRUE, additional_pkgs = character(0) )
vetiver_model |
A deployable |
plumber_file |
A path for your Plumber file, created via
|
path |
A path to write the Dockerfile and |
... |
Not currently used. |
lockfile |
The generated lockfile in |
rspm |
A logical to use the
RStudio Public Package Manager for
|
base_image |
The base Docker image to start with. Defaults to
|
port |
The server port for listening: a number such as 8080 or an
expression like |
expose |
Add |
additional_pkgs |
A character vector of additional package names to add
to the Docker image. For example, some boards like |
The content of the Dockerfile, invisibly.
library(pins) tmp_plumber <- tempfile() b <- board_temp(versioned = TRUE) cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(b, v) vetiver_write_plumber(b, "cars_linear", file = tmp_plumber) ## default port vetiver_write_docker(v, tmp_plumber, tempdir()) ## install more pkgs, like those required to access board vetiver_write_docker(v, tmp_plumber, tempdir(), additional_pkgs = required_pkgs(b)) ## port from env variable vetiver_write_docker(v, tmp_plumber, tempdir(), port = 'as.numeric(Sys.getenv("PORT"))', expose = FALSE)
library(pins) tmp_plumber <- tempfile() b <- board_temp(versioned = TRUE) cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(b, v) vetiver_write_plumber(b, "cars_linear", file = tmp_plumber) ## default port vetiver_write_docker(v, tmp_plumber, tempdir()) ## install more pkgs, like those required to access board vetiver_write_docker(v, tmp_plumber, tempdir(), additional_pkgs = required_pkgs(b)) ## port from env variable vetiver_write_docker(v, tmp_plumber, tempdir(), port = 'as.numeric(Sys.getenv("PORT"))', expose = FALSE)
Use vetiver_write_plumber()
to create a plumber.R
file for a
vetiver_model()
that has been versioned and stored via
vetiver_pin_write()
.
vetiver_write_plumber( board, name, version = NULL, ..., file = "plumber.R", rsconnect = TRUE, additional_pkgs = character(0) )
vetiver_write_plumber( board, name, version = NULL, ..., file = "plumber.R", rsconnect = TRUE, additional_pkgs = character(0) )
board |
A pin board, created by |
name |
Pin name. |
version |
Retrieve a specific version of a pin. Use |
... |
Other arguments passed to |
file |
A path to write the Plumber file. Defaults to |
rsconnect |
Create a Plumber file with features needed for Posit Connect? Defaults to |
additional_pkgs |
Any additional R packages that need to be attached
via |
By default, this function will find and use the latest version of your
vetiver model; the model API (when deployed) will be linked to that specific
version. You can override this default behavior by choosing a specific
version
.
The content of the plumber.R
file, invisibly.
library(pins) tmp <- tempfile() b <- board_temp(versioned = TRUE) cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(b, v) vetiver_write_plumber(b, "cars_linear", file = tmp)
library(pins) tmp <- tempfile() b <- board_temp(versioned = TRUE) cars_lm <- lm(mpg ~ ., data = mtcars) v <- vetiver_model(cars_lm, "cars_linear") vetiver_pin_write(b, v) vetiver_write_plumber(b, "cars_linear", file = tmp)