fix(docs): add external ai function tutorial (#1884)

* fix(docs): add external ai function tutorial

Signed-off-by: Jianxiang Ran <rxan_embedded@163.com>

* fix(docs): add docs

Signed-off-by: Jianxiang Ran <rxan_embedded@163.com>

* fix(docs): fix English words cases problem

Signed-off-by: Jianxiang Ran <rxan_embedded@163.com>

---------

Signed-off-by: Jianxiang Ran <rxan_embedded@163.com>

docs/en_US/api/cli/services.md

@@ -0,0 +1,117 @@
+# Services management
+
+The eKuiper command line tools allows you to manage services, such as create, show, drop, describe services.
+
+## Register service
+
+The command is used for creating a service. The service's definition is specified with JSON format
+
+```shell
+create service $service_name $service_json
+```
+
+Service package file should be prepared at first and put at a place that eKuiper can access.
+
+Example：
+
+```shell
+# bin/kuiper create service sample '{"name": "sample","file": "file:///tmp/sample.zip"}'
+```
+
+This command creates a service named sample whose content is provided by `file` field in the json. 
+
+
+## Show services and service_funcs
+
+The command is used for describing all services and service_funcs defined in the server.
+
+```shell
+# bin/kuiper show services
+```
+
+```shell
+# bin/kuiper show service_funcs
+```
+
+## Describe a service
+
+The command prints the detailed definition of a service.
+
+```shell
+describe service $service_name
+```
+
+Example：
+
+```shell
+# bin/kuiper describe service sample
+{
+  "About": {
+    "author": {
+      "name": "EMQ",
+      "email": "contact@emqx.io",
+      "company": "EMQ Technologies Co., Ltd",
+      "website": "https://www.emqx.io"
+    },
+    "helpUrl": {
+      "en_US": "https://github.com/lf-edge/ekuiper/blob/master/docs/en_US/plugins/functions/functions.md",
+      "zh_CN": "https://github.com/lf-edge/ekuiper/blob/master/docs/zh_CN/plugins/functions/functions.md"
+    },
+    "description": {
+      "en_US": "Sample external services for test only",
+      "zh_CN": "示例外部函数配置，仅供测试"
+    }
+  },
+  "Interfaces": {
+    "trueno": {
+      "Desc": null,
+      "Addr": "tcp://localhost:50051",
+      "Protocol": "grpc",
+      "Schema": {
+        "SchemaType": "protobuf",
+        "SchemaFile": "sample.proto"
+      },
+      "Functions": [
+        "label"
+      ],
+      "Options": null
+    }
+  }
+}
+
+```
+
+
+## Describe a service function
+
+The command prints the detailed information of a service function.
+
+```shell
+describe service_func $service_name
+```
+
+Example：
+
+```shell
+# bin/kuiper describe service_func label
+{
+  "ServiceName": "sample",
+  "InterfaceName": "trueno",
+  "MethodName": "label"
+}
+```
+
+
+## Drop a service
+
+The command drops the service.
+
+```shell
+drop service $service_name
+```
+
+Example：
+
+```shell
+# bin/kuiper drop service sample
+```

docs/en_US/guide/ai/tensorflow_lite_external_function_tutorial.md

@@ -0,0 +1,138 @@
+# Run TensorFlow Lite model with eKuiper external function
+
+[LF Edge eKuiper](https://www.lfedge.org/projects/ekuiper/) is an edge lightweight IoT data analytics / streaming
+software which can be run at all kinds of resource constrained IoT devices.
+
+[TensorFlow Lite](https://www.tensorflow.org/lite/guide) is a set of tools to help developers run TensorFlow models on
+mobile, embedded, and IoT devices. It enables on-device machine learning inference with low latency and a small binary
+size.
+
+By integrating eKuiper and TensorFlow Lite, users can analyze the data in stream by AI with prebuilt TensorFlow models.
+In this tutorial, we will walk you through building a eKuiper external function plugin to label pictures produced by an edge
+device in stream by pre-trained image recognition TensorFlow model. By using the external functions, eKuiper and external functions
+can run in totally different processes or host machines, which means eKuiper and external functions can have different lifecycles, what's more, external functions 
+can provide services to others except eKuiper.
+
+## Prerequisite
+
+The external functions plugins will be a gRPC Server, so users should have knowledge of gRPC. This tutorial will give the example code to set up the GRPC server.
+Users can download the example code [here](https://github.com/lf-edge/ekuiper/blob/master/docs/resources/pythonGRPC.zip). 
+
+Users also need have basic knowledge of Docker. 
+
+## Develop the external function
+
+In the example code, the gRPC Server provide ``label`` method, and users just need write an interface description file and register them into eKuiper. Then eKuiper can call the RPC method
+just as built-in functions. The ``label`` method is powered by ``tflite_runtime`` image classification, for more detail, please check the `label.py` file in the example code.
+
+This is the proto file for the external functions plugins that provide services. The parameter of ``label`` method should be base64 encoded image. 
+
+```proto
+syntax = "proto3";
+
+package sample;
+
+// The algorithms service definition.
+service Algorithms {
+  rpc label(LabelRequest) returns(LabelReply) {}
+}
+
+// The request message containing the base64 encoded image.
+message LabelRequest {
+  string base64_img = 1;
+}
+
+message LabelResult {
+  float  confidence = 1;
+  string label = 2;
+}
+
+// The response message containing the greetings
+message LabelReply {
+  repeated LabelResult results = 1;
+}
+```
+
+## Build and run the gRPC Server
+
+We provide Dockerfile to build the gRPC server, go to the root path of [example code](https://github.com/lf-edge/ekuiper/blob/master/docs/resources/pythonGRPC.zip) pythonGRPC.zip, run the following command to build the gRPC Server docker image
+
+```shell
+ docker build  -t test:1.1.1 -f deploy/Dockerfile-slim-python .
+```
+
+And then set up the service by following command
+
+```shell
+ docker run -d  -p 50051:50051 --name rpc-test test:1.1.1
+```
+
+Now, the gRPC server are providing services on 50051 port. 
+
+
+## Package and register the external function
+
+### Package
+
+Package a json description file and a proto file for the services in gRPC server by zip. The file structure inside the zip file should be like:
+For more detail about the file format and content, please refer to [this](../../extension/external/external_func.md).
+
+- schemas
+  - sample.proto
+- sample.json
+
+You can get the example zip file in [example code](https://github.com/lf-edge/ekuiper/blob/master/docs/resources/pythonGRPC.zip) in ``ekuiper_package`` folder
+
+
+### Register the external function
+
+put the sample.zip file in /tmp directory in the same machine with eKuiper and register by cli
+
+```shell
+# bin/kuiper create service sample '{"name": "sample","file": "file:///tmp/sample.zip"}'
+```
+
+## Run the external function 
+
+Once the external function registered, we can use it in our rule. We will create a rule to receive base64 encoded image data from a mqtt topic and label the image by tflite model.
+
+### Create the stream
+
+Define the stream by eKuiper Cli. We create a mqtt stream named demo, it subscribe to topic ``tfdemo``.
+
+```shell
+#/bin/kuiper create stream demo '() with (DATASOURCE="tfdemo")'
+```
+
+### Create the rule
+
+Define the rule by eKuiper cli.  We will create a select query. We just read the base64 encoded images from demo stream and run the custom function ``label`` against it. The result will be the label of the image recognized by the AI.
+
+```shell
+#/bin/kuiper query
+
+Connecting to 127.0.0.1:20498... 
+kuiper >  select label(image) from demo
+
+```
+
+### Feed the data
+
+User need send the data in json format like this
+```json
+{"image": "base64 encoded data"}
+```
+
+User can get the real data from the example code in ``images/example.json`` file, just send it to the MQTT broker by a MQTT client
+
+### Check the result
+
+You can get the result after you publish the base64 encoded image. 
+
+```shell
+kuiper > [{"label":{"results":[{"confidence":0.5789139866828918,"label":"tailed frog"},{"confidence":0.3095814287662506,"label":"bullfrog"},{"confidence":0.040725912898778915,"label":"whiptail"},{"confidence":0.03226377069950104,"label":"frilled lizard"},{"confidence":0.01566782221198082,"label":"agama"}]}}]
+```
+
+## Conclusion
+
+In this tutorial, we walk you through building external function to leverage a pre-trained TensorFlowLite model. If you need to use other gRPC services, just follow the steps to create customized function. Enjoy the AI in edge device.

docs/zh_CN/api/cli/services.md

@@ -0,0 +1,119 @@
+# 服务管理
+
+eKuiper 命令行工具允许您管理服务，例如创建、显示、删除、描述服务。
+
+## 注册服务
+
+该命令用于创建服务。服务的定义以 JSON 格式指定
+
+```shell
+create service $service_name $service_json
+```
+
+首先要准备打包好的服务描述信息，放在 eKuiper 可以访问的地方
+
+示例：
+
+```shell
+# bin/kuiper create service sample '{"name": "sample","file": "file:///tmp/sample.zip"}'
+```
+
+这个命令创建了一个名为 sample 的服务，该服务的具体描述信息放在了 file 路径指定的地方。
+
+
+## 查看服务和服务函数
+
+此命令查看 eKuiper 系统中注册的所有服务
+
+```shell
+# bin/kuiper show services
+```
+
+此命令查看 eKuiper 系统中注册的所有服务函数
+
+```shell
+# bin/kuiper show service_funcs
+```
+
+## 查看服务的详细信息
+
+此命令可以查看服务的详细信息
+
+```shell
+describe service $service_name
+```
+
+示例：
+
+```shell
+# bin/kuiper describe service sample
+{
+  "About": {
+    "author": {
+      "name": "EMQ",
+      "email": "contact@emqx.io",
+      "company": "EMQ Technologies Co., Ltd",
+      "website": "https://www.emqx.io"
+    },
+    "helpUrl": {
+      "en_US": "https://github.com/lf-edge/ekuiper/blob/master/docs/en_US/plugins/functions/functions.md",
+      "zh_CN": "https://github.com/lf-edge/ekuiper/blob/master/docs/zh_CN/plugins/functions/functions.md"
+    },
+    "description": {
+      "en_US": "Sample external services for test only",
+      "zh_CN": "示例外部函数配置，仅供测试"
+    }
+  },
+  "Interfaces": {
+    "trueno": {
+      "Desc": null,
+      "Addr": "tcp://localhost:50051",
+      "Protocol": "grpc",
+      "Schema": {
+        "SchemaType": "protobuf",
+        "SchemaFile": "sample.proto"
+      },
+      "Functions": [
+        "label"
+      ],
+      "Options": null
+    }
+  }
+}
+
+```
+
+
+## 描述服务函数详细信息
+
+此命令可以列出服务函数详细信息
+
+```shell
+describe service_func $service_name
+```
+
+示例：
+
+```shell
+# bin/kuiper describe service_func label
+{
+  "ServiceName": "sample",
+  "InterfaceName": "trueno",
+  "MethodName": "label"
+}
+```
+
+
+## 删除服务
+
+此命令可以删除服务
+
+```shell
+drop service $service_name
+```
+
+示例：
+
+```shell
+# bin/kuiper drop service sample
+```

docs/zh_CN/guide/ai/tensorflow_lite_external_function_tutorial.md

@@ -0,0 +1,137 @@
+# 使用外部函数运行 AI 算法
+
+[LF Edge eKuiper](https://www.lfedge.org/projects/ekuiper/) 是一款边缘轻量级物联网数据分析/流软件，可在各种资源受限的物联网设备上运行。
+
+[TensorFlow Lite](https://www.tensorflow.org/lite/guide) 是一组帮助开发人员在移动端、嵌入式和物联网设备上运行 TensorFlow
+模型的工具，它使得设备上的机器学习预测具有低延迟和较小的二进制容量。
+
+通过集成 eKuiper 和 TensorFlow Lite，用户可以使用预建的 TensorFlow 模型通过 AI 分析流中的数据。
+在本教程中，我们将通过预先训练的图像识别 TensorFlow 模型, 来带您构建一个 eKuiper 外部函数插件来标记边缘生成的图片。
+通过使用外部函数，eKuiper和外部函数可以运行在完全不同的进程或主机中，这意味着 eKuiper 和外部函数可以有不同的生命周期，更重要的是，外部函数
+可以为除 eKuiper 以外的其他系统程序提供服务。
+
+
+## 先决条件
+
+外部功能插件将是一个 gRPC 服务器，因此用户应该了解 gRPC。本教程将给出设置 gRPC 服务器的示例代码。
+用户可以在[这里](https://github.com/lf-edge/ekuiper/blob/master/docs/resources/pythonGRPC.zip)下载示例代码。
+
+用户还需要具备 Docker 的基本知识。
+
+## 开发外部函数
+
+在示例代码中，gRPC 服务器提供了 ``label`` 方法，用户只需要编写一个接口描述文件，注册到 eKuiper 中即可。然后eKuiper就可以调用 gRPC 方法,
+就像内置函数一样。 ``label`` 方法由 ``tflite_runtime`` 图像分类提供支持，有关更多详细信息，请查看示例代码中的 `label.py` 文件。
+
+这是提供服务的外部功能的 proto 文件描述。 ``label`` 方法的参数应该是 base64 编码的图像。
+
+```proto
+syntax = "proto3";
+
+package sample;
+
+// The algorithms service definition.
+service Algorithms {
+  rpc label(LabelRequest) returns(LabelReply) {}
+}
+
+// The request message containing the base64 encoded image.
+message LabelRequest {
+  string base64_img = 1;
+}
+
+message LabelResult {
+  float  confidence = 1;
+  string label = 2;
+}
+
+// The response message containing the greetings
+message LabelReply {
+  repeated LabelResult results = 1;
+}
+```
+
+## 构建和运行 gRPC Server
+
+我们提供 Dockerfile 来构建 gRPC 服务器，进入[示例代码](https://github.com/lf-edge/ekuiper/blob/master/docs/resources/pythonGRPC.zip) pythonGRPC.zip 的根路径，运行以下命令来构建 gRPC docker 镜像
+
+```shell
+ docker build  -t test:1.1.1 -f deploy/Dockerfile-slim-python .
+```
+
+然后通过以下命令来启动服务
+
+```shell
+ docker run -d  -p 50051:50051 --name rpc-test test:1.1.1
+```
+
+现在，gRPC 服务器在 50051 端口上提供服务。
+
+## 打包并注册外部函数
+
+### 打包
+
+将 gRPC Server 中服务的 json 描述文件和 proto 文件打包成 zip。 zip 文件中的文件结构应如下所示：
+
+- schemas
+  - sample.proto
+- sample.json
+
+- 有关文件格式和内容的更多详细信息，请参阅[这里](../../extension/external/external_func.md)。
+
+
+您可以在[示例代码]((https://github.com/lf-edge/ekuiper/blob/master/docs/resources/pythonGRPC.zip))的文件夹 ``kuiper_package`` 中获取示例 zip 文件。
+
+
+### 注册外部函数
+
+将 sample.zip 文件放到 eKuiper 同一台机器的 /tmp 目录下，通过 cli 注册
+
+```shell
+# bin/kuiper create service sample '{"name": "sample","file": "file:///tmp/sample.zip"}'
+```
+
+## 使用外部函数
+
+一旦注册了外部函数，我们就可以在我们的规则中使用它。我们将创建一个规则来从 mqtt 主题接收图像数据，并通过 tflite 模型标记图像。
+
+### 创建流
+
+通过 eKuiper Cli 创建流。我们创建一个名为 demo 的 mqtt 流，它订阅主题 “tfdemo”。
+
+```shell
+#/bin/kuiper create stream demo '() with (DATASOURCE="tfdemo")'
+```
+
+### 创建规则
+
+通过 eKuiper cli 创建规则。我们将创建一个查询。我们从 demo 流中读取 base64 编码的图像，并针对它进行自定义函数 label 运算, 其结果将是 AI 识别的图像标签。
+```shell
+#/bin/kuiper query
+
+Connecting to 127.0.0.1:20498... 
+kuiper >  select label(image) from demo
+
+```
+
+### 测试数据
+
+用户需要像这样以 json 格式发送数据
+
+```json
+{"image": "base64 encoded data"}
+```
+
+用户可以从 ``images/example.json`` 文件中的示例代码中获取真实数据，只需通过 MQTT 客户端将其发送到 MQTT Broker 即可。
+
+### 查询结果
+
+发布 base64 编码的图像后，您可以得到结果。
+
+```shell
+kuiper > [{"label":{"results":[{"confidence":0.5789139866828918,"label":"tailed frog"},{"confidence":0.3095814287662506,"label":"bullfrog"},{"confidence":0.040725912898778915,"label":"whiptail"},{"confidence":0.03226377069950104,"label":"frilled lizard"},{"confidence":0.01566782221198082,"label":"agama"}]}}]
+```
+
+## 总结
+
+在本教程中，我们将引导您构建外部函数以利用预训练的 TensorFlowLite 模型。如果您需要使用其他 gRPC 服务，只需按照创建自定义函数的步骤操作即可。在边缘设备中享受 AI吧。