[FLINK-37797][doc] Add model documentation (#26694)

Author: lihaosky

docs/content.zh/docs/dev/table/sql/alter.md

@@ -37,6 +37,7 @@ Flink SQL 目前支持以下 ALTER 语句：
 - ALTER DATABASE
 - ALTER FUNCTION
 - ALTER CATALOG
+- ALTER MODEL
 
 ## 执行 ALTER 语句
 
@@ -604,3 +605,51 @@ ALTER CATALOG cat2 COMMENT 'comment for catalog ''cat2''';
 ```
 
 {{< top >}}
+
+## ALTER MODEL
+
+```sql
+ALTER MODEL [IF EXISTS] [catalog_name.][db_name.]model_name
+    SET (key1=val1, key2=val2, ...)
+  | RESET (key1, key2, ...)
+  | RENAME TO new_model_name
+```
+
+**IF EXISTS**
+
+若模型不存在，则不进行任何操作。
+
+### SET
+
+为指定的模型设置一个或多个属性。若个别属性已经存在，则使用新值覆盖旧值。
+
+`SET` 语句示例如下。
+
+```sql
+-- 设置模型的属性
+ALTER MODEL MyModel SET ('model-type'='linear', 'version'='2.0');
+```
+
+### RESET
+
+为指定的模型重置一个或多个属性。
+
+`RESET` 语句示例如下。
+
+```sql
+-- 重置模型的属性
+ALTER MODEL MyModel RESET ('model-type', 'version');
+```
+
+### RENAME TO
+
+将模型重命名为新的名称。
+
+`RENAME TO` 语句示例如下。
+
+```sql
+-- 重命名模型
+ALTER MODEL MyModel RENAME TO NewModel;
+```
+
+{{< top >}}

docs/content.zh/docs/dev/table/sql/create.md

@@ -38,6 +38,7 @@ CREATE 语句用于向当前或指定的 [Catalog]({{< ref "docs/dev/table/catal
 - CREATE DATABASE
 - CREATE VIEW
 - CREATE FUNCTION
+- CREATE MODEL
 
 ## 执行 CREATE 语句
 
@@ -893,3 +894,64 @@ Language tag 用于指定 Flink runtime 如何执行这个函数。目前，只
 指定包含该函数的实现及其依赖的 jar 资源列表。该 jar 应该位于 Flink 当前支持的本地或远程[文件系统]({{< ref "docs/deployment/filesystems/overview" >}}) 中，比如 hdfs/s3/oss。
 
 <span class="label label-danger">注意</span> 目前只有 JAVA、SCALA 语言支持 USING 子句。
+
+## CREATE MODEL
+```sql
+CREATE [TEMPORARY] MODEL [IF NOT EXISTS] [catalog_name.][db_name.]model_name
+  [(
+    { <input_column_definition> }[ , ...n]
+    { <output_column_definition> }[ , ...n]
+  )]
+  [COMMENT model_comment]
+  WITH (key1=val1, key2=val2, ...)
+
+<input_column_definition>:
+  column_name column_type [COMMENT column_comment]
+
+<output_column_definition>:
+  column_name column_type [COMMENT column_comment]
+```
+
+创建一个有 catalog 和数据库命名空间的模型。若 catalog 中已经存在同名模型，则无法注册。
+
+**TEMPORARY**
+
+创建一个有 catalog 和数据库命名空间的临时模型，并覆盖原有的模型。
+
+**IF NOT EXISTS**
+
+若该模型已经存在，则不会进行任何操作。
+
+**Input/Output**
+
+输入列定义了将用于模型推理的特征。输出列定义了模型将产生的预测结果。每个列必须有名称和数据类型。
+
+**COMMENT**
+
+为模型添加注释。
+
+**WITH OPTIONS**
+
+用于存储与此模型相关的额外信息的模型属性。这些属性通常用于查找和创建底层模型提供者。表达式 `key1=val1` 中的键和值都应该是字符串字面量。
+
+**注意：** 模型属性和支持的模型类型可能因底层模型提供者而异。
+
+### 示例
+
+以下示例展示了 `CREATE MODEL` 语句的使用方法：
+
+```sql
+CREATE MODEL sentiment_analysis_model 
+INPUT (text STRING COMMENT '用于情感分析的输入文本') 
+OUTPUT (sentiment STRING COMMENT '预测的情感（positive/negative/neutral/mixed）')
+COMMENT '用于文本情感分析的模型'
+WITH (
+    'provider' = 'openai',
+    'endpoint' = 'https://api.openai.com/v1/chat/completions',
+    'api-key' = '<YOUR KEY>',
+    'model'='gpt-3.5-turbo',
+    'system-prompt' = 'Classify the text below into one of the following labels: [positive, negative, neutral, mixed]. Output only the label.'
+);
+```
+
+{{< top >}}

docs/content.zh/docs/dev/table/sql/describe.md

@@ -486,3 +486,10 @@ Flink SQL> DESC JOB '228d70913eab60dda85c5e7f78b5782c';
 ```
 
 <span class="label label-danger">Attention</span> DESCRIBE JOB 语句仅适用于 [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}) 或者 [SQL Gateway]({{< ref "docs/dev/table/sql-gateway/overview" >}}).
+
+### DESCRIBE MODEL
+```sql
+{ DESCRIBE | DESC } [catalog_name.][db_name.]model_name
+```
+
+{{< top >}}

docs/content.zh/docs/dev/table/sql/drop.md

@@ -37,6 +37,7 @@ Flink SQL 目前支持以下 DROP 语句：
 - DROP DATABASE
 - DROP VIEW
 - DROP FUNCTION
+- DROP MODEL
 
 ## 执行 DROP 语句
 
@@ -229,3 +230,19 @@ DROP [TEMPORARY|TEMPORARY SYSTEM] FUNCTION [IF EXISTS] [catalog_name.][db_name.]
 **IF EXISTS**
 
 若函数不存在，则不会进行任何操作。
+
+## DROP MODEL
+
+```sql
+DROP [TEMPORARY] MODEL [IF EXISTS] [catalog_name.][db_name.]model_name
+```
+
+删除一个有 catalog 和数据库命名空间的模型。若需要删除的模型不存在并且没有用 `IF EXISTS`，则会产生异常。
+
+**TEMPORARY**
+
+删除一个有 catalog 和数据库命名空间的临时模型。
+
+**IF EXISTS**
+
+若模型不存在，则不会进行任何操作。

docs/content.zh/docs/dev/table/sql/queries/model-inference.md

@@ -0,0 +1,134 @@
+---
+title: "模型推理"
+weight: 7
+type: docs
+---
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  The ASF licenses this file
+to you 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.
+-->
+
+# 模型推理
+
+{{< label Streaming >}}
+
+Flink SQL 提供了 `ML_PREDICT` 表值函数（TVF）来在 SQL 查询中执行模型推理。该函数允许您直接在 SQL 中对数据流应用机器学习模型。
+请参阅[模型创建]({{< ref "docs/dev/table/sql/create#create-model" >}})了解如何创建模型。
+
+## ML_PREDICT 函数
+
+`ML_PREDICT` 函数接收一个表输入，对其应用模型，并返回一个包含模型预测结果的新表。当底层模型允许时，该函数提供同步/异步推理模式支持。
+
+### 语法
+
+```sql
+SELECT * FROM
+ML_PREDICT(
+  TABLE input_table,
+  MODEL model_name,
+  DESCRIPTOR(feature_columns),
+  [CONFIG => MAP['key', 'value']]
+)
+```
+
+### 参数
+
+- `input_table`：包含待处理数据的输入表
+- `model_name`：用于推理的模型名称
+- `feature_columns`：指定输入表中哪些列应作为模型特征的描述符
+- `config`：（可选）模型推理的配置选项映射
+
+### 配置选项
+
+以下配置选项可以在配置映射中指定：
+
+{{< generated/ml_predict_runtime_config_configuration >}}
+
+### 示例
+
+```sql
+-- 基本用法
+SELECT * FROM ML_PREDICT(
+  TABLE input_table,
+  MODEL my_model,
+  DESCRIPTOR(feature1, feature2)
+);
+
+-- 使用配置选项
+SELECT * FROM ML_PREDICT(
+  TABLE input_table,
+  MODEL my_model,
+  DESCRIPTOR(feature1, feature2),
+  MAP['async', 'true', 'timeout', '100s']
+);
+
+-- 使用命名参数
+SELECT * FROM ML_PREDICT(
+  INPUT => TABLE input_table,
+  MODEL => MODEL my_model,
+  ARGS => DESCRIPTOR(feature1, feature2),
+  CONFIG => MAP['async', 'true']
+);
+```
+
+### 输出
+
+输出表包含输入表的所有列以及模型的预测列。预测列根据模型的输出模式添加。
+
+### 注意事项
+
+1. 在使用 `ML_PREDICT` 之前，模型必须在目录中注册。
+2. 描述符中指定的特征列数量必须与模型的输入模式匹配。
+3. 如果输出中的列名与输入表中的现有列名冲突，将在输出列名中添加索引以避免冲突。例如，如果输出列名为 `prediction`，且输入表中已存在同名列，则输出列将被重命名为 `prediction0`。
+4. 对于异步推理，模型提供者必须支持 `AsyncPredictRuntimeProvider` 接口。
+5. `ML_PREDICT` 仅支持仅追加表。不支持 CDC（变更数据捕获）表，因为 `ML_PREDICT` 的结果是非确定性的。
+
+### 模型提供者
+
+`ML_PREDICT` 函数使用 `ModelProvider` 执行实际的模型推理。提供者根据注册模型时指定的提供者标识符进行查找。有两种类型的模型提供者：
+
+1. `PredictRuntimeProvider`：用于同步模型推理
+   - 实现 `createPredictFunction` 方法以创建同步预测函数
+   - 当配置中 `async` 设置为 `false` 时使用
+
+2. `AsyncPredictRuntimeProvider`：用于异步模型推理
+   - 实现 `createAsyncPredictFunction` 方法以创建异步预测函数
+   - 当配置中 `async` 设置为 `true` 时使用
+   - 需要额外的超时和缓冲区容量配置
+
+如果配置中未设置 `async`，系统将选择同步或异步模型提供者，如果两者都存在，则优先使用异步模型提供者。
+
+### 错误处理
+
+在以下情况下，函数将抛出异常：
+- 模型中不存在于目录中
+- 特征列数量与模型的输入模式不匹配
+- 缺少模型参数
+- 提供的参数过少或过多
+
+### 性能考虑
+
+1. 对于高吞吐量场景，考虑使用异步推理模式。
+2. 为异步推理配置适当的超时和缓冲区容量值。
+3. 函数的性能取决于底层模型提供者的实现。
+
+### 相关语句
+
+- [模型创建]({{< ref "docs/dev/table/sql/create#create-model" >}})
+- [模型修改]({{< ref "docs/dev/table/sql/alter#alter-model" >}})
+
+{{< top >}}

docs/content.zh/docs/dev/table/sql/show.md

@@ -49,6 +49,8 @@ SHOW CREATE 语句用于打印给定对象的创建 DDL 语句。当前的 SHOW
 - SHOW FULL MODULES
 - SHOW JARS
 - SHOW JOBS
+- SHOW MODELS
+- SHOW CREATE MODEL
 
 
 ## 执行 SHOW 语句
@@ -1028,4 +1030,59 @@ SHOW JOBS
 
 <span class="label label-danger">Attention</span> 当前 SHOW JOBS 命令只能在 [SQL CLI]({{< ref "docs/dev/table/sqlClient" >}}) 或者 [SQL Gateway]({{< ref "docs/dev/table/sql-gateway/overview" >}}) 中使用.
 
+## SHOW MODELS
+
+```sql
+SHOW MODELS [ ( FROM | IN ) [catalog_name.]database_name ] [ [NOT] (LIKE | ILIKE) <sql_like_pattern> ]
+```
+
+展示指定 catalog 和 database 下的所有模型。
+如果没有指定 catalog 和 database，则将使用当前 catalog 和当前 database。另外可以用 `<sql_like_pattern>` 来过滤要返回的模型。
+
+**LIKE**
+根据可选的 `LIKE` 语句与 `<sql_like_pattern>` 是否模糊匹配的所有模型。
+
+`LIKE` 子句中 SQL 正则式的语法与 `MySQL` 方言中的语法相同。
+* `%` 匹配任意数量的字符, 也包括0数量字符, `\%` 匹配一个 `%` 字符.
+* `_` 只匹配一个字符, `\_` 匹配一个 `_` 字符.
+
+**ILIKE**
+它的行为和 LIKE 相同，只是对于大小写是不敏感的。
+
+## SHOW CREATE MODEL
+
+```sql
+SHOW CREATE MODEL [[catalog_name.]db_name.]model_name
+```
+
+展示创建指定模型的 create 语句。
+
+该语句的输出内容包括模型名称、模型输入和输出、模型参数和配置信息，使您可以直观地了解相应模型的元数据。
+
+假设 `model1` 是按如下方式创建的：
+```sql
+CREATE MODEL my_model
+INPUT(text STRING)
+OUTPUT(response STRING)
+WITH (
+  'provider' = 'openai',
+);
+```
+
+展示模型创建语句：
+```sql
+show create model model1;
++---------------------------------------------------------------------------------------------+
+|                                                                                      result |
++---------------------------------------------------------------------------------------------+
+| CREATE MODEL `default_catalog`.`default_database`.`my_model` 
+  INPUT (`text` STRING)
+  OUTPUT (`response` STRING) WITH (
+    'provider' = 'openai'
+)
+ |
++---------------------------------------------------------------------------------------------+
+1 row in set
+```
+
 {{< top >}}