Skip to content

Commit

Permalink
minor fixes
Browse files Browse the repository at this point in the history
  • Loading branch information
@IraGR
IraGR committed Jul 18, 2021
1 parent 3835812 commit dbbb178
Show file tree
Hide file tree
Showing 2 changed files with 38 additions and 49 deletions.
32 changes: 9 additions & 23 deletions deployment/ludwig.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,9 @@ pip install teachablehub

### 2. Setup Deployment Keys

To deploy any model to your Teachable, you'll need a Deployment Key. Deployment keys can be restricted for a particular environment and for a specific period of time. Such constraints might ensure the better security of your awesome project. It's quite a useful feature for the times when only the most experienced members of your team need to have deployment permission for the production environment or you have some colleague working on the project only for a month.
To deploy any model to your Teachable, you'll need a Deployment Key. Deployment keys can be restricted for a particular environment and for a specific period of time. Such constraints might ensure the better security of your awesome project. It's quite a useful feature for the times when only a few members of your team are responsible for deployments in production and need to have permission or you when have some colleague working on the project only for a month.

You can create New Deployment Key from Settings -> Deploy Keys -> Add Key, where you'll need to supply a Key Name and Environment for which this key will be valid. Best practices suggest the name for each key to be descriptive, some good examples include: `production`, `staging`, `backenders-team`, `ds-team`, `john-dev`, `jane-staging` etc.
You can create New Deployment Key from Settings -> Deploy Keys -> Add Key, where you'll need to supply a Key Name and Environment for which this key will be valid. Best practices suggest the name for each key to be descriptive, some good examples include: `production`, `staging`, `backend-team`, `ds-team`, `john-dev`, `jane-staging` etc.

{{button: { to: "/{{handler}}/{{teachable}}/settings/deploy-keys/new", type: "primary", size: "medium", title: "Create a new Deploy Key" } }}

Expand Down Expand Up @@ -80,19 +80,15 @@ Designed with simplicity in mind, TeachbaleHub provides you with free-of-charge

## Advanced Deployment Guide

We have enriched the Deployment with many options to ensure a seamless and clear process.
The Deployment process in TeachableHub is quite automated and seamless, but it also offers many additional options that help you and your team to keep a neat workflow and speak the same language.

### Schema & Features Validation (optional)

Although TeachableHub has some built-in validation options, you can further fine-tune those in accordance with your specific case.
TeachableHub has built-in mechanisms for **`Schema and Features Validation` that are automatically received from your Ludwig model `input_features` and `output_features`**. Still, you can further fine-tune those in accordance with your specific case.

WE ARE TRYING TO DO IT AUTOMATICALLY. Change the text here.???//
For Data Scientists working with ndarrays and with numbers is business as usual. On the other side for the Back-end or the Front-end engineers working with JSON data and object is an everyday job. Not getting lost in translation is essential and configuring this is the connection between these two worlds. You'll surely become your Team's SuperHero right away! 😉

For Data Scientists working with ndarrays and with numbers is business as usual. On the other side for the Back-end or the Front-end engineers working with JSON data and object is an everyday job. Not getting lost in translation is essential and configuring this is the connection between these two worlds. Surely, you'll become your Team's SuperHero right away! 😉

Deployment schema enables the TeachableHub Serving API to accept human-readable features. Furthermore, it ensures those features will be validated before they are sent to the model.

The schema validation feature eliminates any involuntary mistakes and errors when you are working with your Teachable Predict API and will generate better documentation free of charge.
Deployment schema enables the TeachableHub Serving API to accept human-readable features. Furthermore, it ensures those features will be validated before they are sent to the model. The cool thing is that it eliminates any involuntary mistakes and errors while working with your Teachable Predict API and will generate better documentation with no effort and free of charge.

#### Structure

Expand Down Expand Up @@ -177,16 +173,6 @@ deployment.schema({
})
```

### Model Classes (optional)

**This are set automatically. Change it or remove it.**

The TeachableHub's Auto-Generated Serving API will use the Model Classes in the prediction results to return human-readable predictions outputs. If classes are configured for the deployment, Scikit-Learn will use the `predict_proba` method, otherwise, it will use the regular `predict` method.

```python
deployment.classes({"0": "Setosa", "1": "Versicolour", "2": "Virginica" })
```

### Usage Samples (required)

Maintaining these deployment samples, you receive free-of-charge Auto-Generated Serving API Documentation, Model Validation that protects you from deploying models that are not working as expected, and better usage examples for everyone who will integrate the Teachable in their software. These examples are the ones used in the `PredictMan` as well. **At least one of `ndarray` or `features` is required**. If your `Teachable` is using the `Features Validation` feature both are required.
Expand Down Expand Up @@ -216,13 +202,13 @@ deployment.context({
### Deployment Deploy (required)
This is the final stop of the required deployment steps. Congrats, you're almost there! 😊 Here are the three important params to keep in mind:
Congrats, you're almost done! 😊 This is the final stop of the required deployment steps. Here are the three important params to keep in mind:
> `summary` - Just like the git commit messages, 'summary' lets you provide some information about the deployment. It's always great to have the details that will help you refer to this specific deployment or rollback.
> `description` - The description can be used as a changelog when needed. It should contain valuable clues on what's new stuff in this model deployment. I imagine how this can be very helpful for the engineers that are integrating the Serving APIs or maintaining the platforms, using this Teachable. You can change the 'description' from the TeachableHub UI as well.
> `activate` - This option set to 'true' automatically sets the newly deployed model as the latest version of the environment to which it's deployed. Keep in mind that it might be dangerous to execute in the production environment directly. However, it's entirely okay for experimentation or staging environments.
> `activate` - This option set to 'true' automatically sets the newly deployed model as the latest version of the environment to which it's deployed. Keep in mind that it might be dangerous to execute in the production environment directly. However, it's entirely okay for experiments or staging environments.
```
Expand All @@ -239,7 +225,7 @@ Here are a couple of useful functions that can assist in automating your model d
### `.successful()`
The `successful` method returns a boolen result whether or not the deployment is created on the TeachableHub platform. Кeep in mind that the deployment need to be verfied successfuly as well in order to be served by the TeachableHub's Serving API. Check the next point for more details on verification.
The `successful` method returns a boolean result whether or not the deployment is created on the TeachableHub platform. Кeep in mind that the deployment needs to be verified successfully as well in order to be served by the TeachableHub's Serving API. Check the next point for more details on verification.
```python
if deployment.successful():
Expand Down
55 changes: 29 additions & 26 deletions serving/docs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,13 @@

## <a id="how-to-predict-getting-started"></a> Getting Started

Teachables могат да бъдат интегрирани във всяка една платформа, чрез SDK или Rest API. И тнт локуми

Teachables are a powerful machine learning models deployed as an API, entirely documented, available to be consumed by any server-side or client-side applications. Teachables are easily integrated in any platform via the TeachableHub REST API or the Python SDK.

### 1. Setup Serving Keys

Тук кратка информация за serving кийс, че чрез тях контролираш, кой може да прави предикшъни към кой environment за по-добро секюрити и тнт. Добри примери за serving keys са `production`, `staging`, `rails-backoffice`, `ios-app-production` etc.
Serving Keys are the authorization you use for controlling who can make predictions and to which environment of your Teachable. Serving keys can be issued for a particular and environment and for a specific period of time. Such constraints ensure the better security of your awesome project. It's quite a useful feature for the times when you have some colleague working on the project only for a month, for example.

You can create New Serving Key from Settings -> Serving Keys -> Add Key, where you'll need to supply a Key Name and Environment for which this key will be valid. Best practices suggest the name for each key to be descriptive, some good examples include: `production`, `staging`, `rails-backoffice`, `ios-app-production` etc.

{{button: { to: "/{{handler}}/{{teachable}}/settings/serving-keys/new", type: "primary", size: "medium", title: "Create a new Serving Key" } }}

Expand All @@ -16,7 +17,9 @@ Teachables могат да бъдат интегрирани във всяка

### 2. Install Python SDK

За ползват python sdk-то. трябва да го инсталират с тази команда. Изисква минимална пайтън версия Python 3.4+
Requirements: Python 3.4+

To get predictions via the Python SDK, you'll first need to install the SDK with the following command:

```
pip install teachablehub
Expand All @@ -25,7 +28,7 @@ pip install teachablehub

### 3. Start making Predictions

Тук трябва да обишем, че на всеки един деплойнът модел без никаква допълнителна настройка може да се правят тези ndarray predictions.
Each model you have already deployed can serve ndarray predictions without any additional setting. Check the example below:

{{#if(deployment_has_features_sample)}}
```python
Expand Down Expand Up @@ -61,11 +64,13 @@ print(predictions)

<br/><br/>

# Advanced Predictions Guide
# <a id="advanced-prediction-guide"></a> Advanced Predictions Guide

With advanced predictions, you can apply specifications, ordering, and a variety of options to the serving request.

## This Version Predictions
## Specific Version Predictions

When you want to work with a specific deployment version. This is useful when you want to test with a oldest version or when you want to improve the security and to have more control of what will be used in the software when this teachable is integrated it.
This is useful when you want to test with an older version of the model or when you want to improve the security and to have more control of what will be used in the software when this teachable is integrated. It gives you the option to get predictions from a specific deployment version.

```python
teachable = TeachableHubPredictAPI(
Expand All @@ -79,7 +84,7 @@ teachable = TeachableHubPredictAPI(

## Latest Version Predictions

In cases when you want to use always latest and greatest version this is the best approach. By not specifying any version the teachable will always return predictions from the latest model deployed in the specific environment. This is recommended and very helpful when you are automating your deployment pipeline.
That's the way to go, when you want to use always latest and greatest version. Do not specify any version and your Teachable will always return predictions from the latest model activated in the specific environment. Such approach is recommended and very helpful for automating your deployment pipeline.

```python
teachable = TeachableHubPredictAPI(
Expand All @@ -92,7 +97,7 @@ teachable = TeachableHubPredictAPI(

## Developer Friendly Predictions

As Data Scientists working with ndarrays and with numbers is business as usual. On the other side for the Back-end or the Front-end engineers working with JSON data and object is everyday job. Using the `Features Validation` feature of TeachableHub is the connection between these two worlds.
For Data Scientists working with ndarrays and with numbers is business as usual. On the other side for the Back-end or the Front-end engineers working with JSON data and object is an everyday job. Not getting lost in translation is essential and using the `Features Validation` feature of TeachableHub is the connection between these two worlds.


{{#if(deployment_has_features_sample)}}
Expand All @@ -115,9 +120,9 @@ print(predictions)

{{#if(!deployment_has_features_sample)}}

**This deployment doesn't support Developer Friendly Predictions** to configure them, please take a look at the `Schema & Features Validation` section of the Deployment docs. If you do it, your developers will love you and you'll be their superhero :)
**This deployment doesn't support Developer Friendly Predictions**. To configure Developer Friendly Predictions, take a look at the `Schema & Features Validation` section of the Deployment docs. Once you add those, your developers will love you and you'll surely become their superhero.🦸

Until then, you can work with your teachable this way.
Of course, when on your own you can always work with your Teachable without the `Features Validation`.

```python
from teachablehub.clients import TeachableHubPredictAPI
Expand All @@ -137,15 +142,15 @@ print(predictions)

### `.predict(ndarray_or_features, **kwargs)`

The `teachable.predict` method can work both with ndarrays (as well as np.ndarray) and features dict. In order to make much more useful it has support of couple additional kwargs that will eliminate some boring tasks for you when working with the classification models.
The `teachable.predict` method works both with ndarrays (as well as np.ndarray) and features dict. In order to make it much more useful, we've added support for a couple of additional kwargs that eliminate some boring tasks for you when working with the classification models.

#### Params/kwargs:

| Param | Type | Values | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| order | `string` | `desc` or `asc` | `desc` | сортира резултат когато имаме много класове. това работи единственно, когато teachable-a има дефинирани classes в deployment-а. |
| limit | `int` | **min**: `0` **max** `2000` | `-1` | колко класа да върне. това работи единственно, когато teachable-a има дефинирани classes в deployment-а. |
| threshold | `float` | **min**: `0.0` **max** `1.0` | `0.0` | да върне всички класове които конфиденса на модела е над този трешхолд. |
| order | `string` | `desc` or `asc` | `desc` | Very useful option for sorting the results when working with multiple number of classes. That works only when you've defined the classes in the Teachable Deployment|
| limit | `int` | **min**: `0` **max** `2000` | `-1` | Set limitation on the number of classes that will be returned. That works only when you've defined the classes in the Teachable Deployment|
| threshold | `float` | **min**: `0.0` **max** `1.0` | `0.0` | Returns all classes that the model confidence classifies above the given threshold.|


## Errors
Expand All @@ -159,10 +164,8 @@ The SDK raise the following exceptions:
| `UnsuccessfulRequestError` | General Serving API errors 4xx and 5xx |
| `UnauthorizedError` | Wrong Serving Key or configuration |

<a id="how-to-predict-rest-api"></a>
# REST API

{{serving_api_base_url}}
# <a id="how-to-predict-rest-api"></a> REST API

> You can play around with your teachables via the [TeachbaleHub's Serving API Swagger UI](https://serve-teachablehub-dev.scalabl.cloud/docs#/predictions/predict__user___teachable__predict__post) or following the examples below.
Expand All @@ -180,21 +183,21 @@ All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

## Query Params:

Със всеки един предикшън към Rest API могат да се подават и следните Query Params
For each prediction request towards the Rest API, you can pass the following Query Params

| Param | Type | Values | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| environment | `string` | `your-teachable-env` | `production` | към deployment от кой енв ще се прави предикшън |
| version | `int` | **min**: `0` **max** `2000` | `0` | към коя версия на deployment ще се прави предикшън |
| order | `string` | `desc` or `asc` | `desc` | сортира резултат когато имаме много класове. това работи единственно, когато teachable-a има дефинирани classes в deployment-а. |
| limit | `int` | **min**: `0` **max** `2000` | `-1` | колко класа да върне. това работи единственно, когато teachable-a има дефинирани classes в deployment-а. |
| threshold | `float` | **min**: `0.0` **max** `1.0` | `0.0` | да върне всички класове които конфиденса на модела е над този трешхолд. |
| environment | `string` | `your-teachable-env` | `production` | Specifies towards which deployment environment the prediction will be made. |
| version | `int` | **min**: `0` **max** `2000` | `0` | Specifies towards which deployment version the prediction will be made. |
| order | `string` | `desc` or `asc` | `desc` | Sorts the results when working with multiple number of classes. That works only when you've defined the classes in the Teachable Deployment |
| limit | `int` | **min**: `0` **max** `2000` | `-1` | Sets limitation on the number of classes that will be returned. That works only when you've defined the classes in the Teachable Deployment|
| threshold | `float` | **min**: `0.0` **max** `1.0` | `0.0` | Returns all classes that the model confidence classifies above the given threshold.|

<br />

## Making Prediction Requests

Тук трябва да опишем, че TH поддържа schema validation, която гарантира, че всеки един предикшън към модела, ще бъде с правилните features, по правилния начин и ще връща правилни релзултати всеки път. От друга страна, по този начин всеки един в екипа ще знае, модела колко и какви фийчъри очаква.
Another great feature that TeachableHub supports is 'Schema Validation'. It guarantees that every single prediction towards your model will hold the correct features, passed in the right order, and will return accurate results each time you make a prediction. Moreover, your teammates will be always informed of what features the model is expecting, their number, and order. How cool is that!

{{#if(deployment_has_features_sample)}}
```bash
Expand Down

0 comments on commit dbbb178

Please sign in to comment.