[Docs] Add better docs for using mlflow models serve (mlflow#1495)

* [Docs] Add better docs for using `mlflow models serve`

* Address comments

docs/Makefile

@@ -64,12 +64,16 @@ javadocs:
 rdocs:
 	./build-rdoc.sh
 
-.PHONY: html
-html: javadocs rdocs
+# Builds only the RST-based documentation (i.e., everything but Java & R docs)
+.PHONY: rsthtml
+rsthtml:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+.PHONY: html
+html: javadocs rdocs rsthtml
+
 .PHONY: dirhtml
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml

docs/source/models.rst

@@ -490,7 +490,7 @@ be used to safely deploy the model to various environments such as Kubernetes.
 You deploy MLflow model locally or generate a Docker image using the CLI interface to the
 :py:mod:`mlflow.models` module.
 
-The REST API server accepts the following data formats as inputs:
+The REST API server accepts the following data formats as POST input to the ``/invocations`` path:
 
 * JSON-serialized pandas DataFrames in the ``split`` orientation. For example,
   ``data = pandas_df.to_json(orient='split')``. This format is specified using a ``Content-Type``
@@ -504,6 +504,20 @@ The REST API server accepts the following data formats as inputs:
 * CSV-serialized pandas DataFrames. For example, ``data = pandas_df.to_csv()``. This format is
   specified using a ``Content-Type`` request header value of ``text/csv``.
 
+Example requests:
+
+.. code-block:: bash
+
+    # split-oriented
+    curl http://127.0.0.1:5000/invocations -H 'Content-Type: application/json' -d '{
+        "columns": ["a", "b", "c"],
+        "data": [[1, 2, 3], [4, 5, 6]]
+    }'
+
+    # record-oriented (fine for vector rows, loses ordering for JSON records)
+    curl http://127.0.0.1:5000/invocations -H 'Content-Type: application/json; format=pandas-records' -d '[[1, 2, 3], [4, 5, 6]]'
+
+
 For more information about serializing pandas DataFrames, see
 `pandas.DataFrame.to_json <https://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.to_json.html>`_.
 

mlflow/models/cli.py

@@ -35,6 +35,19 @@ def serve(model_uri, port, host, workers, no_conda=False, install_mlflow=False):
     Serve a model saved with MLflow by launching a webserver on the specified host and port. For
     information about the input data formats accepted by the webserver, see the following
     documentation: https://www.mlflow.org/docs/latest/models.html#model-deployment.
+
+    You can make requests to ``POST /invocations`` in pandas split- or record-oriented formats.
+
+    Example:
+
+    .. code-block:: bash
+
+        $ mlflow models serve -m runs:/my-run-id/model-path &
+
+        $ curl http://127.0.0.1:5000/invocations -H 'Content-Type: application/json' -d '{
+            "columns": ["a", "b", "c"],
+            "data": [[1, 2, 3], [4, 5, 6]]
+        }'
     """
     return _get_flavor_backend(model_uri,
                                no_conda=no_conda,