clarifai 11.0.5__py3-none-any.whl → 11.0.6rc2__py3-none-any.whl

clarifai/__init__.py

@@ -1 +1 @@
-__version__ = "11.0.5"
+__version__ = "11.0.6rc2"

clarifai/cli/model.py

@@ -5,8 +5,7 @@ from clarifai.cli.base import cli
 
 @cli.group(['model'])
 def model():
-  """Manage models: upload, test locally, run_locally, predict"""
-  pass
+  """Manage models: upload, test locally, run locally, predict, and more"""
 
 
 @model.command()
@@ -34,6 +33,20 @@ def upload(model_path, download_checkpoints, skip_dockerfile):
   model_upload.main(model_path, download_checkpoints, skip_dockerfile)
 
 
+@model.command()
+@click.option(
+    '--model_path',
+    type=click.Path(exists=True),
+    required=True,
+    help='Path to the model directory.')
+def download_checkpoints(model_path):
+  """Download checkpoints from external source to local model_path"""
+
+  from clarifai.runners.models.model_upload import ModelUploader
+  uploader = ModelUploader(model_path, download_validation_only=True)
+  uploader.download_checkpoints()
+
+
 @model.command()
 @click.option(
     '--model_path',

clarifai/models/model_serving/README.md

@@ -0,0 +1,158 @@
+# Clarifai Model Serving
+
+## Overview
+
+Model Serving is a part of user journey at Clarifai offers a user-friendly interface for deploying your local model into production with Clarifai, featuring:
+
+* A convenient command-line interface (CLI)
+* Easy implementation and testing in Python
+* No need for MLops expertise.
+
+## Quickstart Guide
+
+Quick example for deploying a `text-to-text` model
+
+### Initialize a Clarifai model repository
+
+Suppose your working directory name is `your_model_dir`. Then run
+
+```bash
+$ clarifai create model --type text-to-text --working-dir your_model_dir
+$ cd your_model_dir
+```
+
+In `your_model_dir` folder you will see essential files for deployment process
+
+```bash
+your_model_dir
+├── clarifai_config.yaml
+├── inference.py
+├── test.py
+└── requirements.txt
+```
+
+### Implementation
+
+Write your code in class `InferenceModel` which is an interface between your model and Clarifai server in `inference.py`, there are 2 functions you must implement:
+
+* `__init__`: load your model checkpoint once.
+* `predict`: make prediction, called everytime when you make request from API.
+
+For example, a complete implementation of a hf text-generation model
+
+```python
+import os
+from typing import Dict, Union
+from clarifai.models.model_serving.model_config import *
+
+import torch
+from transformers import AutoTokenizer
+import transformers
+
+class InferenceModel(TextToText):
+  """User model inference class."""
+
+  def __init__(self) -> None:
+    """
+    Load inference time artifacts that are called frequently .e.g. models, tokenizers, etc.
+    in this method so they are loaded only once for faster inference.
+    """
+    # current directory
+    self.base_path = os.path.dirname(__file__)
+    # where you save hf checkpoint in your working dir e.i. `your_model_dir`
+    model_path = os.path.join(self.base_path, "checkpoint")
+    self.tokenizer = AutoTokenizer.from_pretrained(model_path)
+    self.pipeline = transformers.pipeline(
+        "text-generation",
+        model=model_path,
+        torch_dtype=torch.float16,
+        device_map="auto",
+    )
+
+  def predict(self, input_data: list,
+              inference_parameters: Dict[str, Union[str, float, int]]) -> list:
+    """ Custom prediction function for `text-to-text` (also called as `text generation`) model.
+
+    Args:
+      input_data (List[str]): List of text
+      inference_parameters (Dict[str, Union[str, float, int]]): your inference parameters
+
+    Returns:
+      list of TextOutput
+
+    """
+    output_sequences = self.pipeline(
+        input_data,
+        eos_token_id=self.tokenizer.eos_token_id,
+        **inference_parameters)
+
+    # wrap outputs in Clarifai defined output
+    return [TextOutput(each[0]) for each in output_sequences]
+```
+
+Update dependencies in `requirements.txt`
+
+```
+clarifai
+torch=2.1.1
+transformers==4.36.2
+accelerate==0.26.1
+```
+
+### Test (optional)
+
+> NOTE: Running `test` is also involved in `build` and `upload` command.
+
+Test and play with your implementation by executing `test.py`.
+
+Install pytest
+
+```bash
+$ pip install pytest
+```
+
+Execute test
+
+```bash
+$ pytest test.py
+```
+
+### Build
+
+Prepare for deployment step. Run:
+
+```bash
+$ clarifai build model
+```
+
+You will obtain `*.clarifai` file, it's simply a zip having all nessecary files in it to get your model work on Clarifai platform.
+
+`NOTE`: you need to upload your built file to cloud storage to get direct download `url` for next step
+
+### Deployment
+
+Login to Clarifai
+
+```bash
+$ clarifai login
+Get your PAT from https://clarifai.com/settings/security and pass it here: <insert your pat here>
+```
+
+Upload
+
+```bash
+# upload built file directly
+$ clarifai upload model <your-working-dir> --user-app <your_user_id>/<your_app_id> --id <your_model_id>
+# or using direct download url of cloud storage
+$ clarifai upload model --url <url> --user-app <your_user_id>/<your_app_id> --id <your_model_id>
+```
+
+## Learn More
+
+* [Detail Instruction](./docs/concepts.md)
+* [Examples](https://github.com/Clarifai/examples/tree/main/model_upload)
+* [Initialize from example](./docs/cli.md)
+* [CLI usage](./docs/cli.md)
+* [Inference parameters](./docs/inference_parameters.md)
+* [Model Types](./docs/model_types.md)
+* [Dependencies](./docs/dependencies.md)

clarifai/models/model_serving/__init__.py

@@ -0,0 +1,14 @@
+# Copyright 2023 Clarifai, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from .model_config import *  # noqa
+from .repo_build import *  # noqa

clarifai/models/model_serving/cli/__init__.py

@@ -0,0 +1,12 @@
+# Copyright 2023 Clarifai, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

clarifai/models/model_serving/cli/_utils.py

@@ -0,0 +1,53 @@
+from __future__ import annotations  # isort: skip
+import os
+import shutil
+import subprocess
+from typing import Dict, Union
+
+from ..constants import (CLARIFAI_EXAMPLES_REPO, CLARIFAI_EXAMPLES_REPO_PATH,
+                         MODEL_UPLOAD_EXAMPLE_FOLDER)
+
+
+def download_examples_repo(forced_download: bool = False):
+
+  def _pull():
+    subprocess.run(f"git clone {CLARIFAI_EXAMPLES_REPO} {CLARIFAI_EXAMPLES_REPO_PATH}", shell=True)
+
+  if not os.path.isdir(CLARIFAI_EXAMPLES_REPO_PATH):
+    print(f"Download examples to {CLARIFAI_EXAMPLES_REPO_PATH}")
+    _pull()
+  else:
+    if forced_download:
+
+      def _rm_dir_readonly(func, path, _):
+        import stat
+        os.chmod(path, stat.S_IWRITE)
+        func(path)
+
+      print("Removing old examples...")
+      shutil.rmtree(CLARIFAI_EXAMPLES_REPO_PATH, onerror=_rm_dir_readonly)
+      _pull()
+
+
+def list_model_upload_examples(
+    forced_download: bool = False) -> Dict[str, tuple[str, Union[str, None]]]:
+  download_examples_repo(forced_download)
+  model_upload_folder = MODEL_UPLOAD_EXAMPLE_FOLDER
+  model_upload_path = os.path.join(CLARIFAI_EXAMPLES_REPO_PATH, model_upload_folder)
+  examples = {}
+  for model_type_ex in os.listdir(model_upload_path):
+    _folder = os.path.join(model_upload_path, model_type_ex)
+    if os.path.isdir(_folder):
+      _walk = list(os.walk(_folder))
+      if len(_walk) > 0:
+        _, model_names, _files = _walk[0]
+        readme = [item for item in _files if "readme" in item.lower()]
+        for name in model_names:
+          examples.update({
+              f"{model_type_ex}/{name}": [
+                  os.path.join(_folder, name),
+                  os.path.join(_folder, readme[0]) or None
+              ]
+          })
+
+  return examples

clarifai/models/model_serving/cli/base.py

@@ -0,0 +1,14 @@
+from abc import ABC, abstractmethod
+from argparse import _SubParsersAction
+
+
+class BaseClarifaiCli(ABC):
+
+  @staticmethod
+  @abstractmethod
+  def register(parser: _SubParsersAction):
+    raise NotImplementedError()
+
+  @abstractmethod
+  def run(self):
+    raise NotImplementedError()

clarifai/models/model_serving/cli/build.py

@@ -0,0 +1,79 @@
+# Copyright 2023 Clarifai, Inc.
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Commandline interface for model upload utils."""
+import argparse
+import os
+import subprocess
+
+from ..repo_build import RepositoryBuilder
+from .base import BaseClarifaiCli
+
+
+class BuildCli(BaseClarifaiCli):
+
+  @staticmethod
+  def register(parser: argparse._SubParsersAction):
+    parser = parser.add_parser("build", help="Build clarifai model for uploading")
+    sub_parser = parser.add_subparsers()
+
+    BuildModelSubCli.register(sub_parser)
+
+    parser.set_defaults(func=BuildCli)
+
+
+class BuildModelSubCli(BaseClarifaiCli):
+
+  @staticmethod
+  def register(parser: argparse._SubParsersAction):
+    sub_parser = parser.add_parser("model", help="Build Clarifai model")
+    sub_parser.add_argument(
+        "path",
+        type=str,
+        nargs='?',
+        help="Path to working directory, default is current directory",
+        default=".")
+    sub_parser.add_argument(
+        "--out-path", type=str, required=False, help="Output path of built model", default=None)
+    sub_parser.add_argument(
+        "--name",
+        type=str,
+        required=False,
+        help="Name of built file, default is `clarifai_model_id` in config if set or `model`",
+        default=None)
+    sub_parser.add_argument(
+        "--no-test",
+        action="store_true",
+        help="Trigger this flag to skip testing before uploading")
+    sub_parser.set_defaults(func=BuildModelSubCli)
+
+  def __init__(self, args: argparse.Namespace) -> None:
+    self.path = args.path
+    self.no_test = args.no_test
+    self.test_path = os.path.join(self.path, "test.py")
+    self.output_path = args.out_path or self.path
+    self.serving_backend = "triton"
+    self.name = args.name
+
+  def run(self):
+
+    # Run test before uploading
+    if not self.no_test:
+      assert os.path.exists(
+          self.test_path), FileNotFoundError(f"Could not find `test.py` in {self.path}")
+      result = subprocess.run(f"pytest -s --log-level=INFO {self.test_path}", shell=True)
+      assert result.returncode == 0, "Test has failed. Please make sure no error exists in your code."
+
+    # build
+    print("Start building...")
+    RepositoryBuilder.build(
+        self.path, backend=self.serving_backend, output_dir=self.output_path, name=self.name)

clarifai/models/model_serving/cli/clarifai_clis.py

@@ -0,0 +1,33 @@
+from argparse import ArgumentParser
+
+from .build import BuildCli
+from .create import CreateCli
+from .example_cli import ExampleCli
+from .login import LoginCli
+from .upload import UploadCli
+
+
+def main():
+
+  parser = ArgumentParser("clarifai")
+  cmd_parser = parser.add_subparsers(help="Clarifai cli helpers")
+
+  UploadCli.register(cmd_parser)
+  CreateCli.register(cmd_parser)
+  LoginCli.register(cmd_parser)
+  ExampleCli.register(cmd_parser)
+  BuildCli.register(cmd_parser)
+
+  args = parser.parse_args()
+
+  if not hasattr(args, "func"):
+    parser.print_help()
+    exit(1)
+
+  # Run
+  service = args.func(args)
+  service.run()
+
+
+if __name__ == "__main__":
+  main()