Proofread documentation
This commit is contained in:
parent
08a40bfaaf
commit
b5a69fea67
12 changed files with 73 additions and 74 deletions
|
|
@ -1,23 +1,23 @@
|
|||
# Summarising scientific publications from a tech-transfer perspective
|
||||
|
||||
This is a simplified example illustrating how `great-ai` is used in practice at [ScoutinScience](https://www.scoutinscience.com/){ target=_blank }. The subpages show `great-ai` in action by going over the life-cycle of finetuning and deploying a BERT-based software service.
|
||||
This is a simplified example illustrating how `great-ai` is used in practice at [ScoutinScience](https://www.scoutinscience.com/){ target=_blank }. The subpages show `great-ai` in action by going over the lifecycle of fine-tuning and deploying a BERT-based software service.
|
||||
|
||||
??? note "Propriety data"
|
||||
The purpose of this example is to show you different ways in which `great-ai` can assist you. The exact NLP task being solved is not central. Stemming from this, and from the difficult nature of obtaining appropriate training data, the propriety dataset used for the experiments is not shared.
|
||||
The purpose of this example is to show you different ways in which `great-ai` can assist you. The exact NLP task being solved is not central. Stemming from this and from the difficult nature of obtaining appropriate training data, the propriety dataset used for the experiments is not shared.
|
||||
|
||||
## Objectives
|
||||
|
||||
1. You will see how the [great_ai.utilities](/reference/utilities) can integrate into your Data Science workflow.
|
||||
2. You will see how [great_ai.large_file](/reference/large-file) can be used to version and store your trained model.
|
||||
3. You will see how [GreatAI][great_ai.GreatAI] should be used prepare your model for a robust and responsible deployment.
|
||||
3. You will see how [GreatAI][great_ai.GreatAI] should be used to prepare your model for a robust and responsible deployment.
|
||||
4. You will see multiple ways of customising your deployment.
|
||||
|
||||
## Overview
|
||||
|
||||
One of the core features of the ScoutinScience platform is summarising research papers from a tech-transfer perspective. In short, extractive summarisation is preferred using a binary classifier trained on clients' judgement of sentence interestingness. Thus, documents are sentences and the expected output is a binary label showing whether a sentence is "worthy" of being in the tech-transfer summary. Providing an explanation for each decision is imperative since ScoutinScience embraces applying only explainable AI (XAI) methods wherever feasible.
|
||||
One of the core features of the ScoutinScience platform is summarising research papers from a tech-transfer perspective. In short, extractive summarisation is preferred using a binary classifier trained on clients' judgement of sentence interestingness. Thus, documents are sentences, and the expected output is a binary label showing whether a sentence is "worthy" of being in the tech-transfer summary. Explaining each decision is imperative since ScoutinScience embraces applying only explainable AI (XAI) methods wherever feasible.
|
||||
|
||||
!!! success
|
||||
You are ready to start the tutorial. Feel free to come back to the [summary](#summary) section once you're finished.
|
||||
You are ready to start the tutorial. Feel free to return to the [summary](#summary) section once you're finished.
|
||||
|
||||
<div style="display: flex; justify-content: space-evenly;" markdown>
|
||||
[:material-database: Examine data](data.ipynb){ .md-button .md-button--primary }
|
||||
|
|
@ -37,14 +37,14 @@ We load and analyse the data by calculating inter-rater reliability and checking
|
|||
|
||||
We simply fine-tune SciBERT.
|
||||
|
||||
After training and evaluating a model, it is exported using [great_ai.save_model][]. For more info, checkout [the configuration how-to page](/how-to-guides/configure-service).
|
||||
After training and evaluating a model, it is exported using [great_ai.save_model][]. For more info, check out [the configuration how-to page](/how-to-guides/configure-service).
|
||||
|
||||
### [Deployment notebook](deploy.ipynb)
|
||||
|
||||
We customise the GreatAI configuration, create custom cahcing for the model and implement an inference function that can be hardened by wrapping it in a [GreatAI][great_ai.GreatAI] instance. We also extract the attention weights as a quasi-explanation.
|
||||
We customise the GreatAI configuration, create custom caching for the model and implement an inference function that can be hardened by wrapping it in a [GreatAI][great_ai.GreatAI] instance. We also extract the attention weights as a quasi-explanation.
|
||||
|
||||
Finally, we test the model's inference function through the GreatAI dashboard. [The only thing left is to deploy the hardened service properly.](/how-to-guides/use-service)
|
||||
|
||||
#### [Additional files](additional-files.md)
|
||||
|
||||
There are some other files required for deploying the notebook. For example, the config file for S3 and MongoDB or a Dockerfile for building a custom image. These are compiled and shown on a separate page.
|
||||
There are some other files required for deploying the notebook. For example, the config file for S3 and MongoDB or a Dockerfile for building a custom image. These are gathered and shown on a separate page.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Explanation
|
||||
|
||||
A lot more details and discussion about the problem context and approaches of GreatAI along with its evaluation can be found in my thesis.
|
||||
A lot more details and discussion about the problem context and approaches of GreatAI, along with its evaluation, can be found in my thesis.
|
||||
|
||||
<div style="display: flex; justify-content: center;">
|
||||
<img src="/media/thesis-frontpage.png" style="height: 500px;" alt="front page"/>
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# How to call remote GreatAI instances
|
||||
|
||||
Microservices architecture (or [SOA](https://en.wikipedia.org/wiki/Service-oriented_architecture)) work well with ML applications. This is because their interfaces are usually very narrow, while the functionality provided quite comprehensive. Hence, drawing the boundaries of responsibilities is more straightforward in the case of ML services than in the case of more traditional business applications. For this reason, it is common to have a tree of models (preferably wrapped in GreatAI instances) communicating with each other.
|
||||
Microservices architecture (or [SOA](https://en.wikipedia.org/wiki/Service-oriented_architecture)) work well with ML applications. This is because their interfaces are usually very narrow, while the functionality provided is quite comprehensive. Hence, drawing the boundaries of responsibilities is more straightforward in the case of ML services than in the case of more traditional business applications. For this reason, it is common to have a tree of models (preferably wrapped in GreatAI instances) communicating with each other.
|
||||
|
||||
Although regular HTTP POST requests could be sent to each service's `/predict` endpoint, `great-ai` comes with two convenience functions: [call_remote_great_ai][great_ai.call_remote_great_ai] and [call_remote_great_ai_async][great_ai.call_remote_great_ai_async] to wrap this request. These provide you with some level of robustness and deserialisation.
|
||||
|
||||
|
|
@ -44,21 +44,21 @@ results = [
|
|||
print(results)
|
||||
```
|
||||
|
||||
1. Only return the outputs so we don't clutter up the terminal.
|
||||
1. Only return the outputs, so we don't clutter up the terminal.
|
||||
|
||||
> Run this script as a regular Python script by executing `python3 client.py`.
|
||||
|
||||
{ loading=lazy }
|
||||
|
||||
As you can see, everything worked as expected. There is one way to improve it though.
|
||||
As you can see, everything worked as expected. There is one way to improve it, though.
|
||||
## An `async` example
|
||||
|
||||
Let's send multiple requests at the same time to speed up the overall execution time. To do this, we will use the [call_remote_great_ai_async][great_ai.call_remote_great_ai_async] function.
|
||||
Let's send multiple requests simultaneously to speed up the overall execution time. To do this, we will use the [call_remote_great_ai_async][great_ai.call_remote_great_ai_async] function.
|
||||
|
||||
??? note "Why is this possible?"
|
||||
Note, that in `server.py`, the inference function is declared `async`. This means that multiple "copies" of it can run at the same time in the same thread. Since, there is no CPU bottleneck, the server has a quite large throughput (requests responded to per second), but its latency will stay around 2 seconds due to the async `sleep` command.
|
||||
Note that in `server.py`, the inference function is declared `async`. This means that multiple "copies" of it can run at the same time in the same thread. Since there is no CPU bottleneck, the server has a quite large throughput (requests responded to per second), but its latency will stay around 2 seconds due to the async `sleep` command.
|
||||
|
||||
If your great-ai server is not `async`, higher throughput can be achieved by running multiple instances of it, either manually, or by running it with multiple `uvicorn` workers like this: `ENVIRONMENT=production great-ai server.py --worker_count 4`
|
||||
If your great-ai server is not `async`, higher throughput can be achieved by running multiple instances of it, either manually or by running it with multiple `uvicorn` workers like this: `ENVIRONMENT=production great-ai server.py --worker_count 4`
|
||||
|
||||
### Async client
|
||||
|
||||
|
|
@ -84,8 +84,8 @@ async def main():
|
|||
asyncio.run(main())
|
||||
```
|
||||
|
||||
> Replace `client.py` with this async client. Note that even though async support is significantly more streamlined in recent Python versions, it still requires a bit more boilerplate than its synchronous counterpart.
|
||||
> Replace `client.py` with this async client. Note that although async support is significantly more streamlined in recent Python versions, it still requires a bit more boilerplate than its synchronous counterpart.
|
||||
|
||||
{ loading=lazy }
|
||||
|
||||
This also works, and in some use-cases might be considerably quicker.
|
||||
This also works and might be considerably quicker in some use cases.
|
||||
|
|
|
|||
|
|
@ -28,8 +28,8 @@ configure(
|
|||
)
|
||||
```
|
||||
|
||||
1. Completely disable caching.
|
||||
2. The unspecified routes are enabled by default.
|
||||
1. Completely disable caching.
|
||||
2. The unspecified routes are enabled by default.
|
||||
|
||||
## Using remote storage
|
||||
|
||||
|
|
@ -63,7 +63,7 @@ model = [4, 3]
|
|||
save_model(model, 'my-model')
|
||||
```
|
||||
|
||||
1. This line isn't strictly necessary because if `s3.ini` (or `mongo.ini`) is available in the current working directory, they are automatically used to configure their respective LargeFile implementations/databases.
|
||||
1. This line isn't strictly necessary because if `s3.ini` (or `mongo.ini`) is available in the current working directory, they are automatically used to configure their respective LargeFile implementations/databases.
|
||||
|
||||
??? note "Departing from AWS"
|
||||
With the `aws_endpoint_url` argument, it is possible to use any other S3-compatible service such as [Backblaze](https://www.backblaze.com/){ target=_blank }. In that case, it would be `aws_endpoint_url=https://s3.us-west-002.backblazeb2.com`.
|
||||
|
|
@ -77,7 +77,7 @@ MONGO_CONNECTION_STRING=mongodb://localhost:27017 # this is the default value
|
|||
# if `MONGO_CONNECTION_STRING` is specified, this default is overridden
|
||||
MONGO_CONNECTION_STRING=ENV:MONGO_CONNECTION_STRING
|
||||
|
||||
MONGO_DATABASE=my-database # it is automatically created if doesn't exist
|
||||
MONGO_DATABASE=my-database # it is automatically created if it doesn't exist
|
||||
```
|
||||
|
||||
```python title="use-mongo.py"
|
||||
|
|
@ -99,4 +99,4 @@ By default, a thread-safe version of [TinyDB](https://tinydb.readthedocs.io/en/l
|
|||
|
||||
### MongoDB
|
||||
|
||||
At the moment, only MongoDB is supported as a production-ready `TracingDatabase`. In order to use it, you have to either place a file named `mongo.ini` in your working directory, or explicitly call either [MongoDbDriver.configure_credentials_from_file][great_ai.MongoDbDriver] or [MongoDbDriver.configure_credentials][great_ai.MongoDbDriver.configure_credentials].
|
||||
Currently, only MongoDB is supported as a production-ready `TracingDatabase`. In order to use it, you have to either place a file named `mongo.ini` in your working directory or explicitly call either [MongoDbDriver.configure_credentials_from_file][great_ai.MongoDbDriver] or [MongoDbDriver.configure_credentials][great_ai.MongoDbDriver.configure_credentials].
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# How to create a GreatAI service
|
||||
|
||||
The core value of `great-ai` lies in its [GreatAI][great_ai.GreatAI] class. In order to take advantage of it, you need to create an instance wrapping your code.
|
||||
The core value of `great-ai` lies in its [GreatAI][great_ai.GreatAI] class. To take advantage of it, you need to create an instance wrapping your code.
|
||||
|
||||
Let's say that you have the following greeter function:
|
||||
|
||||
|
|
@ -20,11 +20,11 @@ def greeter(your_name):
|
|||
```
|
||||
|
||||
??? info "Why not simply use `@GreatAI?`"
|
||||
The purpose of [@GreatAI.create][great_ai.GreatAI.create] is simply to provide you with type-checking through MyPy, Pylance, and similar libraries. However, the overloading support for `__new__` is lacking in MyPy, thus, a static factory method is used instead.
|
||||
The purpose of [@GreatAI.create][great_ai.GreatAI.create] is simply to provide you with type-checking through MyPy, Pylance, and similar libraries. However, the overloading support for `__new__` is lacking in MyPy. Thus, a static factory method is used instead.
|
||||
|
||||
## With types
|
||||
|
||||
Even though it's not required by GreatAI, [type annotating your codebase](https://realpython.com/python-type-checking/){ target=_blank } can save you from lots of trivial mistakes, that's why it's highly advised. Simply add the expected types to your function's signature.
|
||||
Even though it's not required by GreatAI, [type annotating your codebase](https://realpython.com/python-type-checking/){ target=_blank } can save you from lots of trivial mistakes; that's why it's highly advised. Simply add the expected types to your function's signature.
|
||||
|
||||
```python title="type_safe_greeter.py"
|
||||
from great_ai import GreatAI
|
||||
|
|
@ -34,11 +34,11 @@ def type_safe_greeter(your_name: str) -> str:
|
|||
return f'Hi {your_name}!'
|
||||
```
|
||||
|
||||
This not only allows you to statically typecheck your code, but by default, GreatAI will check it during runtime as well using [typeguard](https://github.com/agronholm/typeguard){ target=_blank }.
|
||||
This not only allows you to statically type-check your code, but by default, GreatAI will check it during runtime as well using [typeguard](https://github.com/agronholm/typeguard){ target=_blank }.
|
||||
|
||||
## With async
|
||||
|
||||
Asynchronous code can result in immense performance gains in certain cases. For example, you might rely on a third-party service, do database access, or [call a remote GreatAI instance](/how-to-guides/call-remote). In these cases, you can simply make your function `async` without any other changes.
|
||||
Asynchronous code can result in immense performance gains in some instances. For example, you might rely on a third-party service, do database access, or [call a remote GreatAI instance](/how-to-guides/call-remote). In these cases, you can make your function `async` without any other changes.
|
||||
|
||||
```python title="async_greeter.py"
|
||||
from great_ai import GreatAI
|
||||
|
|
@ -52,7 +52,7 @@ async def async_greeter(your_name: str) -> str:
|
|||
|
||||
## With decorators
|
||||
|
||||
GreatAI can decorate already decorated functions. The only restriction is that [@GreatAI.create][great_ai.GreatAI.create] must come last. There are two built-in decorators that you can use to customise your function but you can you use any third-party decorator as well.
|
||||
GreatAI can decorate already decorated functions. The only restriction is that [@GreatAI.create][great_ai.GreatAI.create] must come last. There are two built-in decorators that you can use to customise your function, but you can use any third-party decorator as well.
|
||||
|
||||
### Using `@use_model`
|
||||
|
||||
|
|
@ -69,10 +69,10 @@ def type_safe_greeter(your_name: str, model) -> str:
|
|||
assert type_safe_greeter('Andras').output == 'Hi Andras'
|
||||
```
|
||||
|
||||
1. By default, the parameter named `model` will be replaced by the loaded model. This behaviour can be customised by setting the `model_kwarg_name`. This way, even multiple models can be injected into a single function.
|
||||
1. By default, the parameter named `model` will be replaced by the loaded model. This behaviour can be customised by setting the `model_kwarg_name`. This way, even multiple models can be injected into a single function.
|
||||
|
||||
!!! important
|
||||
You must call [@use_model][great_ai.use_model] before [@GreatAI.create][great_ai.GreatAI.create]. Note, that decorators are applied starting from the bottom-most one. Feel free to use [@use_model][great_ai.use_model] in other places of the codebase, it works equally well outside of GreatAI services.
|
||||
You must call [@use_model][great_ai.use_model] before [@GreatAI.create][great_ai.GreatAI.create]. Note that decorators are applied starting from the bottom-most one. Feel free to use [@use_model][great_ai.use_model] in other places of the codebase, and it works equally well outside GreatAI services.
|
||||
|
||||
### Using `@parameter`
|
||||
|
||||
|
|
@ -93,11 +93,11 @@ assert type_safe_greeter('Andras').output == 'Hi Andras'
|
|||
```
|
||||
|
||||
!!! important
|
||||
You must call [@parameter][great_ai.parameter] before [@GreatAI.create][great_ai.GreatAI.create]. Note, that decorators are applied starting from the bottom-most one. Feel free to use [@parameter][great_ai.parameter] in other places of the codebase, it works equally well outside of GreatAI services.
|
||||
You must call [@parameter][great_ai.parameter] before [@GreatAI.create][great_ai.GreatAI.create]. Note that decorators are applied starting from the bottom-most one. Feel free to use [@parameter][great_ai.parameter] in other places of the codebase, and it works equally well outside GreatAI services.
|
||||
|
||||
## Complex example
|
||||
|
||||
Refer to the following example summarising the options you have when instantiating a GreatAI service.
|
||||
The following example summarises the options you have when instantiating a GreatAI service.
|
||||
|
||||
```python title="complex.py"
|
||||
from great_ai import save_model, GreatAI, parameter, use_model, log_metric
|
||||
|
|
@ -117,4 +117,4 @@ def add_number(positive_number: int, secret: int) -> int:
|
|||
assert add_number(1).output == 5
|
||||
```
|
||||
|
||||
1. Refer to [the configuration page](/how-to-guides/configure-service) for specifying where to store your models.
|
||||
1. Refer to [the configuration page](/how-to-guides/configure-service) for specifying where to store your models.
|
||||
|
|
|
|||
|
|
@ -1,13 +1,13 @@
|
|||
# How to manage training data
|
||||
|
||||
In order to simplify your training data management, `great-ai` provide two complementing approaches for inputting new data-points.
|
||||
In order to simplify your training data management, `great-ai` provide two complementing approaches for inputting new data points.
|
||||
|
||||
## Upload data
|
||||
|
||||
At the start of your experiments' first iteration, after you've gathered suitable samples for training, you can call [great_ai.add_ground_truth][]. This automatically stores a timestamp and also allows you to assign tags to the data. Using these attributes, [great_ai.query_ground_truth][] can be called to get a filtered view of the training data.
|
||||
|
||||
!!! important "Train-test-validation splits"
|
||||
It is a best practice to lock-away the test split of your data that is only used for the final quality assessment. This prevents you from accidentally training on it, or inadvertently tuning the model to have the highest accuracy metrics on the test split. This, of course, may lead to dubious results, hence, care must be taken to avoid it.
|
||||
It is a best practice to lock away the test split of your data that is only used for the final quality assessment. This prevents you from accidentally training on it or inadvertently tuning the model to have the highest accuracy metrics on the test split. This, of course, may lead to dubious results; hence, care must be taken to avoid it.
|
||||
|
||||
With [great_ai.add_ground_truth][], there is an option to tag the samples with `train`, `test`, and `validation` randomly, following a predefined distribution. This happens as soon as they're written in the database. Later, these can be queried by providing the name of the appropriate tags.
|
||||
|
||||
|
|
@ -25,7 +25,7 @@ add_ground_truth(
|
|||
)
|
||||
```
|
||||
|
||||
1. Note that the ratios don't have to add up to 1. They are just weights. There is also a `validation_split_ratio` which is 0 by default.
|
||||
1. Note that the ratios don't have to add up to 1. They are just weights. There is also a `validation_split_ratio` which is 0 by default.
|
||||
|
||||
```python
|
||||
>>> from great_ai import query_ground_truth
|
||||
|
|
@ -50,13 +50,13 @@ add_ground_truth(
|
|||
'trace_id': 'abee0671-beb9-4284-8c3b-c65e5836ce38'})]
|
||||
```
|
||||
|
||||
1. Expected output. This can be also accessed through the `.output` property.
|
||||
1. Expected output. This can also be accessed through the `.output` property.
|
||||
2. The input value is stored here.
|
||||
3. Notice how `ground_truth` is always included as a tag when using [great_ai.add_ground_truth][].
|
||||
|
||||
## Get feedback
|
||||
|
||||
After the initial data gathering, end-to-end feedback can be also integrated into the dataset.
|
||||
After the initial data gathering, end-to-end feedback can also be integrated into the dataset.
|
||||
|
||||
The scaffolded REST API contains endpoints for managing traces and their feedbacks.
|
||||
|
||||
|
|
|
|||
|
|
@ -20,16 +20,16 @@ pip install great-ai pyyaml==5.4.1
|
|||
|
||||
## Command-line tools
|
||||
|
||||
After installation, `great-ai` and `large-file` are available as commands. The former is required for deploying your application while the latter lets you manage models and datasets from your terminal.
|
||||
After installation, `great-ai` and `large-file` are available as commands. The former is required for deploying your application, while the latter lets you manage models and datasets from your terminal.
|
||||
|
||||
??? note "Snakes & kebabs"
|
||||
The library is called `great-ai`, therefore, its command-line entrypoint is also called `great-ai`. However, Python module names cannot contain hyphens, that's why you have to `import great_ai` with an underscore. The `great-ai` CLI tool is also available as `python3 -m great_ai`.
|
||||
The library is called `great-ai`; therefore, its command-line entry point is also called `great-ai`. However, Python module names cannot contain hyphens, that's why you have to `import great_ai` with an underscore. The `great-ai` CLI tool is also available as `python3 -m great_ai`.
|
||||
|
||||
To help with the confusion, a CLI executable called `great_ai` (and `large_file`) are also installed, thus, if you prefer, you can always refer to GreatAI using its underscored name variant (`great_ai`).
|
||||
To help with the confusion, a CLI executable called `great_ai` (and `large_file`) are also installed. Thus, if you prefer, you can always refer to GreatAI using its underscored name variant (`great_ai`).
|
||||
|
||||
!!! warning "Windows"
|
||||
On Windows, you might encounter a similar warning from `pip`:
|
||||
> `WARNING: The scripts great-ai.exe, great_ai.exe, large-file.exe and large_file.exe are installed in 'C:\Users\...\Scripts' which is not on PATH.`
|
||||
> `WARNING: The scripts great-ai.exe, great_ai.exe, large-file.exe and large_file.exe are installed in 'C:\Users\...\Scripts', which is not on PATH.`
|
||||
|
||||
> `Consider adding this directory to PATH or, if you prefer to suppress this warning, use --no-warn-script-location.`
|
||||
|
||||
|
|
@ -37,7 +37,7 @@ After installation, `great-ai` and `large-file` are available as commands. The f
|
|||
|
||||
## Update
|
||||
|
||||
If you wish to update to the latest version execute:
|
||||
If you wish to update to the latest version, execute:
|
||||
|
||||
```sh
|
||||
pip install --upgrade great-ai
|
||||
|
|
|
|||
|
|
@ -4,12 +4,12 @@ The functions [save_model][great_ai.use_model] and [@use_model][great_ai.use_mod
|
|||
|
||||
## Motivation
|
||||
|
||||
Oftentimes, especially when working with data-heavy applications, large files can proliferate in a repository. Version controlling them is an obvious next step, however, GitHub's git LFS implementation [doesn't support deleting](https://docs.github.com/en/repositories/working-with-files/managing-large-files/removing-files-from-git-large-file-storage#git-lfs-objects-in-your-repository) large files, making it easy for them to eat-up the LFS quota and explode the size of your repos.
|
||||
Often, especially when working with data-heavy applications, large files can proliferate in a repository. Version controlling them is an obvious next step. However, GitHub's git LFS implementation [doesn't support deleting](https://docs.github.com/en/repositories/working-with-files/managing-large-files/removing-files-from-git-large-file-storage#git-lfs-objects-in-your-repository) large files, making it easy for them to eat-up the LFS quota and explode the size of your repos.
|
||||
|
||||
[DVC](https://dvc.org/) is a viable alternative, however, it requires users to learn to use one more CLI tool.
|
||||
[DVC](https://dvc.org/) is a viable alternative; however, it requires users to learn to use one more CLI tool.
|
||||
|
||||
??? note "Using LargeFile-s directly (usually not needed)"
|
||||
LargeFile doesn't require users to learn too much new. It is a nearly exact copy of the built-in `open()` function of Python with which users are certainly already familiar.
|
||||
LargeFile doesn't require users to learn too much new. It is a nearly exact copy of Python's built-in `open()` function, with which users are undoubtedly already familiar.
|
||||
|
||||
## Simple example
|
||||
|
||||
|
|
@ -24,7 +24,7 @@ Oftentimes, especially when working with data-heavy applications, large files ca
|
|||
})
|
||||
|
||||
# Creates a new version and deletes the older version
|
||||
# leaving the 3 most recently used intact
|
||||
# leaving the three most recently used intact
|
||||
with LargeFileS3("test.txt", "w", keep_last_n=3) as f:
|
||||
for i in range(100000):
|
||||
f.write('test\n')
|
||||
|
|
@ -35,11 +35,11 @@ Oftentimes, especially when working with data-heavy applications, large files ca
|
|||
print(f.readlines()[0])
|
||||
```
|
||||
|
||||
1. In this case, the latest version is already in the local cache, no download is required.
|
||||
1. The latest version is already in the local cache; no download is required.
|
||||
|
||||
### More details
|
||||
|
||||
`LargeFile` behaves like an opened file (in the background it is a temp file after all). Binary reads and writes are supported along with the [different keywords `open()` accepts](https://docs.python.org/3/library/functions.html#open){ target=_blank }.
|
||||
`LargeFile` behaves like an opened file (in the background, it is a temp file after all). Binary reads and writes are supported along with the [different keywords `open()` accepts](https://docs.python.org/3/library/functions.html#open){ target=_blank }.
|
||||
|
||||
The local cache can be configured with these properties:
|
||||
|
||||
|
|
@ -64,7 +64,7 @@ Oftentimes, especially when working with data-heavy applications, large files ca
|
|||
LargeFileS3("folder-of-my-bert-model").push('path_to_local/folder_or_file')
|
||||
```
|
||||
|
||||
> This way both regular files and folders can be handled. The uploaded file is called **folder-of-my-bert-model**, the local name is ignored.
|
||||
> This way, both regular files and folders can be handled. The uploaded file is called **folder-of-my-bert-model**, the local name is ignored.
|
||||
|
||||
Lastly, all version of the remote object can be deleted by calling `LargeFileS3("my-file").delete()`. It will still reside in your local cache afterwards; its deletion will happen next time your local cache has to be pruned.
|
||||
|
||||
|
|
@ -90,14 +90,14 @@ large-file --backend s3 --secrets secrets.ini \
|
|||
--push my_first_file.json folder/my_second_file my_folder
|
||||
```
|
||||
|
||||
> Only the filename is used as the S3 name, the rest of the path is ignored.
|
||||
> Only the filename is used as the S3 name; the rest of the path is ignored.
|
||||
|
||||
!!! important "Using MongoDB"
|
||||
The possible values for `--backend` are `s3`, `mongo`, and `local`. The latter doesn't need credentials, it only versions and stores your files in a local folder. MongoDB on the other hand requires a `mongo_connection_string` and a `mongo_database` to be specified. For storing large files, it uses the [GridFS](https://www.mongodb.com/docs/manual/core/gridfs){ target=_blank } specification.
|
||||
The possible values for `--backend` are `s3`, `mongo`, and `local`. The latter doesn't need credentials. It only versions and stores your files in a local folder. MongoDB, on the other hand, requires a `mongo_connection_string` and a `mongo_database` to be specified. For storing large files, it uses the [GridFS](https://www.mongodb.com/docs/manual/core/gridfs){ target=_blank } specification.
|
||||
|
||||
### Download some files to the local cache
|
||||
|
||||
This can be useful when building a Docker image for example. This way, the files can already reside inside the container and need not be downloaded later.
|
||||
This can be useful when building a Docker image, for example. This way, the files can already reside inside the container and need not be downloaded later.
|
||||
|
||||
```sh
|
||||
large-file --backend s3 --secrets ~/.aws/credentials \
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ As you can see, the original return value is wrapped in a [Trace][great_ai.Trace
|
|||
|
||||
Likely, the main way you would like to expose your model is through an HTTP API. [@GreatAI.create][great_ai.GreatAI.create] scaffolds many REST API endpoints for your model and creates a [FastAPI](https://fastapi.tiangolo.com/){ target=_blank } app available under [GreatAI.app][great_ai.GreatAI]. This can be served using [uvicorn](https://www.uvicorn.org/){ target=_blank } or any other [ASGI server](https://asgi.readthedocs.io/en/latest/){ target=_blank }.
|
||||
|
||||
Since most ML code lives in [Jupyter](https://jupyter.org/){ target=_blank } notebooks, therefore, deploying a notebook containing the inference function is supported. To achieve this, `uvicorn` is wrapped by the `great-ai` command-line utility which — among others — takes care of feeding a notebook into `uvicorn`. It also supports auto-reloading.
|
||||
Since most ML code lives in [Jupyter](https://jupyter.org/){ target=_blank } notebooks, therefore, deploying a notebook containing the inference function is supported. To achieve this, `uvicorn` is wrapped by the `great-ai` command-line utility, which — among others — takes care of feeding a notebook into `uvicorn`. It also supports auto-reloading.
|
||||
|
||||
### In development
|
||||
|
||||
|
|
@ -97,12 +97,11 @@ RUN pip install --no-cache-dir --requirement requirements.txt
|
|||
# have to download it each time a container starts
|
||||
RUN large-file --backend s3 --secrets s3.ini --cache my-domain-predictor
|
||||
|
||||
# Add you application code to the image
|
||||
# Add your application code to the image
|
||||
COPY . .
|
||||
|
||||
# The default ENTRYPOINT is great-ai, specify its argument using CMD
|
||||
# The default ENTRYPOINT is great-ai; specify its argument using CMD
|
||||
CMD ["deploy.ipynb"]
|
||||
|
||||
```
|
||||
|
||||
## Batch prediction
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@
|
|||
[](https://sonar.scoutinscience.com/dashboard?id=great-ai)
|
||||
[](https://sonar.scoutinscience.com/dashboard?id=great-ai)
|
||||
|
||||
Applying AI is becoming increasingly easier but many case studies have shown that these applications are often deployed poorly. This may lead to suboptimal performance and to introducing [unintended biases](https://en.wikipedia.org/wiki/Weapons_of_Math_Destruction){ target=_blank }. GreatAI helps fixing this by allowing you to ==easily transform your prototype AI code into production-ready software==.
|
||||
Applying AI is becoming increasingly easier, but many case studies have shown that these applications are often deployed poorly. This may lead to suboptimal performance and to introducing [unintended biases](https://en.wikipedia.org/wiki/Weapons_of_Math_Destruction){ target=_blank }. GreatAI helps fix this by allowing you to ==easily transform your prototype AI code into production-ready software==.
|
||||
|
||||
??? quote "Case studies"
|
||||
"There is a need to consider and adapt well established SE practices which have been ignored or had a very narrow focus in ML literature."
|
||||
|
|
@ -20,11 +20,11 @@ Applying AI is becoming increasingly easier but many case studies have shown tha
|
|||
|
||||
"Because a mature system might end up being (at most) 5% machine learning code and (at least) 95% glue code, it may be less costly to create a clean native solution rather than re-use a generic package." — [Sculley et al.](https://www.researchgate.net/profile/Todd-Phillips/publication/319769912_Hidden_Technical_Debt_in_Machine_Learning_Systems/links/61e716d68d338833e37a7fd6/Hidden-Technical-Debt-in-Machine-Learning-Systems.pdf){ target=_blank }
|
||||
|
||||
"For example, practice 25 is very important for “Traceability", yet relatively weakly adopted. We expect that the results from this type of analysis can, in the future, provide useful guidance for practitioners in terms of aiding them to assess their rate of adoption for each practice and to create roadmaps for improving their processes. — [Serban et al.](https://dl.acm.org/doi/abs/10.1145/3382494.3410681?casa_token=uCFz0dtDR6gAAAAA:4_8OMJ-5njwopYkB1KSGAu9JfbNq4nfa8LRE0fj84ckjfo-GgtcYQivZTGxal3M4haoA8r_xwpw){ target=_blank }
|
||||
"For example, practice 25 is very important for "Traceability", yet relatively weakly adopted. We expect that the results from this type of analysis can, in the future, provide useful guidance for practitioners in terms of aiding them to assess their rate of adoption for each practice and to create roadmaps for improving their processes. — [Serban et al.](https://dl.acm.org/doi/abs/10.1145/3382494.3410681?casa_token=uCFz0dtDR6gAAAAA:4_8OMJ-5njwopYkB1KSGAu9JfbNq4nfa8LRE0fj84ckjfo-GgtcYQivZTGxal3M4haoA8r_xwpw){ target=_blank }
|
||||
|
||||
## Features
|
||||
|
||||
- [x] Save prediction traces of each prediction including arguments and model versions
|
||||
- [x] Save prediction traces of each prediction, including arguments and model versions
|
||||
- [x] Save feedback and merge it into a ground-truth database
|
||||
- [x] Version and store models and data on shared infrastructure *(MongoDB GridFS, S3-compatible storage, shared volume)*
|
||||
- [x] Automatically scaffolded custom REST API (and OpenAPI schema) for easy integration
|
||||
|
|
@ -72,7 +72,7 @@ def greeter(name: str) -> str: #(2)
|
|||
2. [Typing functions](https://docs.python.org/3/library/typing.html){ target=_blank } is recommended in general, however, not required for GreatAI to work.
|
||||
|
||||
??? note
|
||||
In practice, `greeter` could be an inference function of some AI/ML application. But it could also just wrap a black-box solution of some SaaS. Either way, it is [imperative to have continuous oversight](https://digital-strategy.ec.europa.eu/en/library/ethics-guidelines-trustworthy-ai){ target=_blank } of the services you provide and data you process especially in the context of AI/ML applications.
|
||||
In practice, `greeter` could be an inference function of some AI/ML application. But it could also just wrap a black-box solution of some SaaS. Either way, it is [imperative to have continuous oversight](https://digital-strategy.ec.europa.eu/en/library/ethics-guidelines-trustworthy-ai){ target=_blank } of the services you provide and the data you process, especially in the context of AI/ML applications.
|
||||
|
||||
```sh title="terminal"
|
||||
great-ai demo.py
|
||||
|
|
@ -88,7 +88,7 @@ great-ai demo.py
|
|||
|
||||
|
||||
|
||||
GreatAI fits between the prototype and deployment phases of your (or your organisation's) AI development lifecycle. This is highlighted with blue in the diagram. Here, several best practices can be automatically implemented aiming to achieve the following attributes:
|
||||
GreatAI fits between the prototype and deployment phases of your (or your organisation's) AI development lifecycle. This is highlighted in blue in the diagram. Here, several best practices can be automatically implemented, aiming to achieve the following attributes:
|
||||
|
||||
- **G**eneral: use any Python library without restriction
|
||||
- **R**obust: have error-handling and well-tested utilities out-of-the-box
|
||||
|
|
@ -98,9 +98,9 @@ GreatAI fits between the prototype and deployment phases of your (or your organi
|
|||
|
||||
## Why GreatAI?
|
||||
|
||||
There are other, existing solutions aiming to facilitate this phase. [Amazon SageMaker](https://aws.amazon.com/sagemaker){ target=_blank } and [Seldon Core](https://www.seldon.io/solutions/open-source-projects/core){ target=_blank } provide the most comprehensive suite of features. If you have the opportunity to use them, do that because they're great.
|
||||
There are other existing solutions aiming to facilitate this phase. [Amazon SageMaker](https://aws.amazon.com/sagemaker){ target=_blank } and [Seldon Core](https://www.seldon.io/solutions/open-source-projects/core){ target=_blank } provide the most comprehensive suite of features. If you have the opportunity to use them, do that because they're great.
|
||||
|
||||
However, research indicates that professionals rarely use them. This may be due to their inherent setup and operating complexity. ==GreatAI is designed to be as simple to use as possible.== Its clear, high-level API and sensible default configuration makes it extremely easy to start using. Despite its relative simplicity over Seldon Core, it still implements many of the [SE4ML best practices](https://se-ml.github.io){ target=_blank }, and thus, can meaningfully improve your deployment without requiring prohibitively large effort.
|
||||
However, research indicates that professionals rarely use them. This may be due to their inherent setup and operational complexity. ==GreatAI is designed to be as simple to use as possible.== Its straightforward, high-level API and sensible default configuration make it extremely easy to start using. Despite its relative simplicity over Seldon Core, it still implements many of the [SE4ML best practices](https://se-ml.github.io){ target=_blank }, and thus, can meaningfully improve your deployment without requiring prohibitively great effort.
|
||||
|
||||
|
||||
<div style="display: flex; justify-content: space-evenly; flex-wrap: wrap;" markdown>
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Train and deploy a SOTA model
|
||||
|
||||
Let's see `great-ai` in action by going over the life-cycle of a simple service.
|
||||
Let's see `great-ai` in action by going over the lifecycle of a simple service.
|
||||
|
||||
## Objectives
|
||||
|
||||
|
|
@ -10,12 +10,12 @@ Let's see `great-ai` in action by going over the life-cycle of a simple service.
|
|||
|
||||
## Overview
|
||||
|
||||
You are going to train a field of study (domain) classifier for scientific sentences. The exact task was proposed by the [SciBERT paper](https://arxiv.org/abs/1903.10676){ target=_blank } in which SciBERT [achieved an F1-score of 0.6571](https://paperswithcode.com/sota/sentence-classification-on-paper-field){ target=_blank }. We are going to outperform it using a trivial text classification model: a [Linear SVM](https://scikit-learn.org/stable/modules/generated/sklearn.svm.LinearSVC.html){ target=_blank }.
|
||||
You will train a field of study (domain) classifier for scientific sentences. The exact task was proposed by the [SciBERT paper](https://arxiv.org/abs/1903.10676){ target=_blank } in which SciBERT [achieved an F1-score of 0.6571](https://paperswithcode.com/sota/sentence-classification-on-paper-field){ target=_blank }. We are going to outperform it using a trivial text classification model: a [Linear SVM](https://scikit-learn.org/stable/modules/generated/sklearn.svm.LinearSVC.html){ target=_blank }.
|
||||
|
||||
We use the same synthetic dataset derived from the [Microsoft Academic Graph](https://www.microsoft.com/en-us/research/project/microsoft-academic-graph/){ target=_blank }. The dataset is [available here](https://github.com/allenai/scibert/tree/master/data/text_classification/mag){ target=_blank }.
|
||||
|
||||
!!! success
|
||||
You are ready to start the tutorial. Feel free to come back to the [summary](#summary) section once you're finished.
|
||||
You are ready to start the tutorial. Feel free to return to the [summary](#summary) section once you're finished.
|
||||
|
||||
<div style="display: flex; justify-content: space-evenly;" markdown>
|
||||
[:fontawesome-solid-chart-simple: Train it](train.ipynb){ .md-button .md-button--primary }
|
||||
|
|
@ -32,7 +32,7 @@ We load and preprocess the dataset while relying on [great_ai.utilities.clean][g
|
|||
After training and evaluating a model, it is exported using [great_ai.save_model][].
|
||||
|
||||
??? tip "Remote storage"
|
||||
To store your model remotely, you need to set your credentials before calling `save_model`.
|
||||
To store your model remotely, you must set your credentials before calling `save_model`.
|
||||
|
||||
For example, to use [AWS S3](https://aws.amazon.com/s3){ target=_blank }:
|
||||
```python
|
||||
|
|
@ -68,7 +68,7 @@ def predict_domain(sentence, model):
|
|||
```
|
||||
|
||||
1. [@use_model][great_ai.use_model] loads and injects your model into the `predict_domain` function's `model` argument.
|
||||
You can freely reference it knowing that the function is always provided with it.
|
||||
You can freely reference it, knowing that the function is always provided with it.
|
||||
|
||||
Finally, we test the model's inference function through the GreatAI dashboard. [The only thing left is to deploy the hardened service properly.](/how-to-guides/use-service)
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue