ODSC-38627: update docs

Author: z7ye

docs/source/user_guide/model_registration/framework_specific_instruction.rst

@@ -9,6 +9,7 @@
     frameworks/sparkpipelinemodel
     frameworks/lightgbmmodel
     frameworks/xgboostmodel
+    frameworks/huggingfacemodel
     frameworks/automlmodel
     frameworks/genericmodel
-    
+

docs/source/user_guide/model_registration/frameworks/huggingface.rst renamed to docs/source/user_guide/model_registration/frameworks/huggingfacemodel.rst

@@ -10,7 +10,7 @@ See `API Documentation <../../../ads.model_framework.html#ads.model.framework.hu
 Overview
 ========
 
-The ``ads.model.framework.huggingface_model.HuggingFacePipelineModel`` class in ADS is designed to allow you to rapidly get a HuggingFace Pipeline into production. The ``.prepare()`` method creates the model artifacts that are needed to deploy a functioning pipeline without you having to configure it or write code. However, you can customize the required ``score.py`` file.
+The ``ads.model.framework.huggingface_model.HuggingFacePipelineModel`` class in ADS is designed to allow you to rapidly get a HuggingFace pipelines into production. The ``.prepare()`` method creates the model artifacts that are needed to deploy a functioning pipeline without you having to configure it or write code. However, you can customize the required ``score.py`` file.
 
 .. include:: ../_template/overview.rst
 
@@ -22,15 +22,13 @@ Load a `ImageSegmentationPipeline <https://huggingface.co/docs/transformers/main
 
 .. code-block:: python3
 
-    from transformers import pipeline
-
-    segmenter = pipeline(task="image-segmentation", model="facebook/detr-resnet-50-panoptic", revision="fc15262")
-    preds = segmenter(
-        "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
-    )
-
-    preds
+    >>> from transformers import pipeline
 
+    >>> segmenter = pipeline(task="image-segmentation", model="facebook/detr-resnet-50-panoptic", revision="fc15262")
+    >>> preds = segmenter(
+    ...     "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
+    ... )
+    >>> preds
     [{'score': 0.987885,
         'label': 'LABEL_184',
         'mask': <PIL.Image.Image image mode=L size=960x686>},
@@ -65,17 +63,10 @@ Prepare Model Artifact
     # More info here - https://huggingface.co/docs/transformers/main_classes/pipelines#transformers.pipeline
 
 
-Instantiate a ``HuggingFacePipelineModel()`` object with a HuggingFace Pipelines model. Each instance accepts the following parameters:
-
-* ``artifact_dir: str``. Artifact directory to store the files needed for deployment.
-* ``auth: (Dict, optional)``: Defaults to ``None``. The default authentication is set using the ``ads.set_auth`` API. To override the default, use ``ads.common.auth.api_keys()`` or ``ads.common.auth.resource_principal()`` and create the appropriate authentication signer and the ``**kwargs`` required to instantiate the ``IdentityClient`` object.
-* ``estimator: Callable``. Any model object generated by the PyTorch framework.
-* ``properties: (ModelProperties, optional)``. Defaults to ``None``. The ``ModelProperties`` object required to save and deploy model.
+Instantiate a ``HuggingFacePipelineModel()`` object with HuggingFace pipelines. All the pipelines related files are saved under the ``artifact_dir``.
 
 For more detailed information on what parameters that ``HuggingFacePipelineModel`` takes, refer to the `API Documentation <../../../ads.model_framework.html#ads.model.framework.huggingface_model.HuggingFacePipelineModel>`__
-All the pipelines related files are saved under the ``artifact_dir``.
 
-.. include:: ../_template/initialize.rst
 
 
 Summary Status
@@ -106,35 +97,31 @@ Deploy and Generate Endpoint
 
     >>> # Deploy and create an endpoint for the huggingface_pipeline_model 
     >>> huggingface_pipeline_model.deploy(
-            display_name="HuggingFace Pipeline Model For Image Segmentation",
-            deployment_log_group_id="ocid1.loggroup.oc1.xxx.xxxxx",
-            deployment_access_log_id="ocid1.log.oc1.xxx.xxxxx",
-            deployment_predict_log_id="ocid1.log.oc1.xxx.xxxxx",
-        )
+    ...     display_name="HuggingFace Pipeline Model For Image Segmentation",
+    ...     deployment_log_group_id="ocid1.loggroup.oc1.xxx.xxxxx",
+    ...     deployment_access_log_id="ocid1.log.oc1.xxx.xxxxx",
+    ...     deployment_predict_log_id="ocid1.log.oc1.xxx.xxxxx",
+    ... )
     >>> print(f"Endpoint: {huggingface_pipeline_model.model_deployment.url}")
-.. parsed-literal::
     https://modeldeployment.{region}.oci.customer-oci.com/ocid1.datasciencemodeldeployment.oc1.xxx.xxxxx
 
 Run Prediction against Endpoint
 ===============================
 
 .. code-block:: python3
 
-    # Download an image
-    import PIL.Image
-    import requests
-    import cloudpickle
-    image_url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
-
-    image = PIL.Image.open(requests.get(image_url, stream=True).raw)
-    image_bytes = cloudpickle.dumps(image)
-
-    # Generate prediction by invoking the deployed endpoint
-    preds = huggingface_pipeline_model.predict(image)["prediction"]
-    print([{"score": round(pred["score"], 4), "label": pred["label"]} for pred in preds['prediction']])
+    >>> # Download an image
+    >>> import PIL.Image
+    >>> import requests
+    >>> import cloudpickle
+    >>> image_url = "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/pipeline-cat-chonk.jpeg"
 
-.. parsed-literal::
+    >>> image = PIL.Image.open(requests.get(image_url, stream=True).raw)
+    >>> image_bytes = cloudpickle.dumps(image)
 
+    >>> # Generate prediction by invoking the deployed endpoint
+    >>> preds = huggingface_pipeline_model.predict(image)["prediction"]
+    >>> print([{"score": round(pred["score"], 4), "label": pred["label"]} for pred in preds['prediction']])
     [{'score': 0.9879, 'label': 'LABEL_184'},
     {'score': 0.9973, 'label': 'snow'},
     {'score': 0.9972, 'label': 'cat'}]
@@ -157,6 +144,7 @@ Predict with Multiple Arguments
 If your model takes more than one argument, you can pass in through dictionary with the keys as the argument name and values as the value of the arguement.
 
 .. code-block:: python3
+
     >>> your_huggingface_pipeline_model.verify({"parameter_name_1": "parameter_value_1", ..., "parameter_name_n": "parameter_value_n"})
     >>> your_huggingface_pipeline_model.predict({"parameter_name_1": "parameter_value_1", ..., "parameter_name_n": "parameter_value_n"})
 
@@ -166,7 +154,7 @@ Run Prediction with oci sdk
 
 Model deployment endpoints can be invoked with the oci sdk. This example invokes a model deployment with the oci sdk with a ``bytes`` payload:
 
-`bytes` payload example
+``bytes`` payload example
 ------------------------------
 
 .. code-block:: python3
@@ -183,7 +171,6 @@ Model deployment endpoints can be invoked with the oci sdk. This example invokes
 
     >>> preds = requests.post(endpoint, data=image_bytes, auth=ads.common.auth.default_signer()['signer'], headers=headers).json()
     >>> print([{"score": round(pred["score"], 4), "label": pred["label"]} for pred in preds['prediction']])
-.. parsed-literal::
     [{'score': 0.9879, 'label': 'LABEL_184'},
     {'score': 0.9973, 'label': 'snow'},
     {'score': 0.9972, 'label': 'cat'}]

docs/source/user_guide/model_registration/quick_start.rst

@@ -257,6 +257,67 @@ Create a model, prepare it, verify that it works, save it to the model catalog,
     #Register TensorFlow model
     model_id = tf_model.save(display_name="TensorFlow Model")
 
+HuggingFace Pipelines
+---------------------
+
+.. code-block:: python3
+
+    from transformers import pipeline
+    import tempfile
+    import PIL.Image
+    import ads
+    import requests
+    import cloudpickle
+
+    ## download the image
+    image_url = "https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png"
+    image = PIL.Image.open(requests.get(image_link, stream=True).raw)
+    image_bytes = cloudpickle.dumps(image)
+
+    ## download the pretrained model
+    classifier = pipeline(model="openai/clip-vit-large-patch14")
+    classifier(
+            images=image,
+            candidate_labels=["animals", "humans", "landscape"],
+        )
+
+    ## Initiate a HuggingFacePipelineModel instance
+    zero_shot_image_classification_model = HuggingFacePipelineModel(classifier, artifact_dir=empfile.mkdtemp())
+
+    ## Prepare a model artifact
+    conda = "oci://bucket@namespace/path/to/conda/pack"
+    python_version = "3.8"
+    zero_shot_image_classification_model.prepare(inference_conda_env=conda, inference_python_version = python_version, force_overwrite=True)
+
+    ## Test data
+    data = {"images": image, "candidate_labels": ["animals", "humans", "landscape"]}
+    body = cloudpickle.dumps(data) # convert image to bytes
+
+    ## Verify
+    zero_shot_image_classification_model.verify(data=data)
+    zero_shot_image_classification_model.verify(data=body)
+
+    ## Save
+    zero_shot_image_classification_model.save()
+
+    ## Deploy
+    log_group_id = "<log_group_id>"
+    log_id = "<log_id>"
+    zero_shot_image_classification_model.deploy(deployment_bandwidth_mbps=100,
+                    wait_for_completion=False,
+                    deployment_log_group_id = log_group_id,
+                    deployment_access_log_id = log_id,
+                    deployment_predict_log_id = log_id)
+    zero_shot_image_classification_model.predict(image)
+    zero_shot_image_classification_model.predict(body)
+
+    ### Invoke the model by sending bytes
+    auth = ads.common.auth.default_signer()['signer']
+    endpoint = zero_shot_image_classification_model.model_deployment.url + "/predict"
+    headers = {"Content-Type": "application/octet-stream"}
+    requests.post(endpoint, data=body, auth=auth, headers=headers).json()
+
+
 Other Frameworks
 ----------------
 

docs/source/user_guide/model_serialization/index.rst

@@ -13,6 +13,7 @@ Model Serialization
     quick_start
     automlmodel
     genericmodel
+    huggingfacemodel
     lightgbmmodel
     pytorchmodel
     sklearnmodel