You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@doris.apache.org by zc...@apache.org on 2026/04/20 11:20:41 UTC
(doris-website) branch master updated: [doc] add cautions for pythonUDF and AI functions (#3562)
This is an automated email from the ASF dual-hosted git repository.
zclllyybb pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 069425f3566 [doc] add cautions for pythonUDF and AI functions (#3562)
069425f3566 is described below
commit 069425f3566b010708b67094e14ddcd0833498a2
Author: linrrarity <li...@selectdb.com>
AuthorDate: Mon Apr 20 19:20:34 2026 +0800
[doc] add cautions for pythonUDF and AI functions (#3562)
---
docs/ai/ai-function-overview.md | 5 ++
.../query-data/udf/python-user-defined-function.md | 57 ++++++++++++++++++++++
.../current/ai/ai-function-overview.md | 5 ++
.../query-data/udf/python-user-defined-function.md | 57 ++++++++++++++++++++++
.../version-4.x/ai/ai-function-overview.md | 5 ++
.../version-4.x/ai/ai-function-overview.md | 5 ++
6 files changed, 134 insertions(+)
diff --git a/docs/ai/ai-function-overview.md b/docs/ai/ai-function-overview.md
index 6ab1d5f2605..197a72833d7 100644
--- a/docs/ai/ai-function-overview.md
+++ b/docs/ai/ai-function-overview.md
@@ -96,6 +96,11 @@ The currently available parameters are as follows:
`ai.retry_delay_second`: Optional, delay time (in seconds) between retries. Default is 0.
+:::caution Note
+Currently, only static API Key authentication is supported (credentials are carried directly in request headers).
+Authentication mechanisms that require private-key signing and temporary access token exchange (such as OAuth / Service Account) are not supported yet.
+:::
+
## Supported Providers
Currently supported providers include: OpenAI, Anthropic, Gemini, DeepSeek, Local, MoonShot, MiniMax, Zhipu, Qwen, Baichuan.
diff --git a/docs/query-data/udf/python-user-defined-function.md b/docs/query-data/udf/python-user-defined-function.md
index 43bf45e89f9..a0294edd533 100644
--- a/docs/query-data/udf/python-user-defined-function.md
+++ b/docs/query-data/udf/python-user-defined-function.md
@@ -449,6 +449,8 @@ Vectorized mode uses Pandas for batch data processing, offering better performan
:::caution Note
To ensure the system correctly recognizes vectorized mode, please use type annotations in function signatures (such as `a: pd.Series`) and directly operate on batch data structures in function logic. If vectorized types are not explicitly used, the system will fall back to Scalar Mode.
+
+If a function signature mixes `pd.Series` parameters with regular (non-Series) parameters, Doris treats the regular-parameter input columns as constant columns (that is, one value is reused for the whole batch), which may produce results different from expectations. To avoid this, keep parameter styles consistent in vectorized scenarios: either all parameters use `pandas.Series` annotations, or all parameters are regular scalar parameters (Scalar Mode).
:::
```python
@@ -530,6 +532,61 @@ $$;
SELECT py_vec_sqrt(16); -- Result: 4.0
```
+**Example 4: Function signature parameter types are inconsistent(mixes `pd.Series` parameters with regular (non-Series) parameters)**
+```sql
+CREATE TABLE t_bug_013 (
+ id INT,
+ a INT,
+ b INT
+) ENGINE=OLAP
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO t_bug_013 VALUES
+ (1, 1, 10),
+ (2, 2, 20),
+ (3, 3, 30),
+ (4, 4, NULL),
+ (5, NULL, 50);
+
+DROP FUNCTION IF EXISTS py_mixed_vector_add(INT, INT);
+
+CREATE FUNCTION py_mixed_vector_add(INT, INT)
+RETURNS INT
+PROPERTIES (
+ "type"="PYTHON_UDF",
+ "symbol"="py_mixed_vector_add_impl",
+ "always_nullable"="true",
+ "runtime_version"="3.12.11"
+)
+AS $$
+import pandas as pd
+
+# Suggest to maintain consistent parameter style
+def py_mixed_vector_add_impl(x: pd.Series, y: int):
+ return x + y
+$$;
+
+SELECT
+ id
+ a,
+ b,
+ py_mixed_vector_add(a, b) AS vector_val
+FROM t_bug_013
+ORDER BY id;
+-- treat column b as a constant column
++------+------+------+------------+
+| id | a | b | vector_val |
++------+------+------+------------+
+| 1 | 1 | 10 | 11 |
+| 2 | 2 | 20 | 12 |
+| 3 | 3 | 30 | 13 |
+| 4 | 4 | NULL | 14 |
+| 5 | NULL | 50 | NULL |
++------+------+------+------------+
+```
+
#### Advantages of Vectorized Mode
1. **Performance Optimization**: Batch processing reduces interaction frequency between Python and Doris
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai/ai-function-overview.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai/ai-function-overview.md
index afcd0197b19..2a796a5c16e 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai/ai-function-overview.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/ai/ai-function-overview.md
@@ -96,6 +96,11 @@ Doris 通过[资源机制](../sql-manual/sql-statements/cluster-management/compu
`ai.retry_delay_second`: 可选,重试的延迟时间(秒)。默认值为 0。
+:::caution Note
+当前仅支持静态 API Key 方式进行鉴权(通过请求头直接携带凭证)。
+对于需要通过私钥签名并交换临时访问令牌的鉴权机制(如 OAuth / Service Account 等),暂不支持。
+:::
+
## 厂商支持
目前直接支持的厂商有:OpenAI、Anthropic、Gemini、DeepSeek、Local、MoonShot、MiniMax、Zhipu、Qwen、Baichuan。
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/query-data/udf/python-user-defined-function.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/query-data/udf/python-user-defined-function.md
index 3bb626a9122..750b6ccc768 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/query-data/udf/python-user-defined-function.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/query-data/udf/python-user-defined-function.md
@@ -449,6 +449,8 @@ SELECT py_safe_divide(10.0, NULL); -- 结果: NULL
:::caution 注意
为确保系统正确识别向量化模式,请在函数签名中使用类型注解(如 `a: pd.Series`)并在函数逻辑中直接操作批量数据结构。若未明确使用向量化类型,系统将回退到标量模式(Scalar Mode)。
+
+若函数签名同时包含 `pd.Series` 类型与普通类型参数,系统会将普通类型参数对应的输入列按常量列处理(即整批数据复用同一个值),可能导致结果与预期不一致。建议在向量化模式下保持入参风格一致:要么全部使用 `pandas.Series` 类型注解,要么全部使用普通类型参数(标量模式)。
:::
```python
@@ -530,6 +532,61 @@ $$;
SELECT py_vec_sqrt(16); -- 结果: 4.0
```
+**示例 4: 函数签名参数类型不一致(同时包含 `pd.Series` 类型与普通类型)**
+```sql
+CREATE TABLE t_bug_013 (
+ id INT,
+ a INT,
+ b INT
+) ENGINE=OLAP
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 1
+PROPERTIES ("replication_num" = "1");
+
+INSERT INTO t_bug_013 VALUES
+ (1, 1, 10),
+ (2, 2, 20),
+ (3, 3, 30),
+ (4, 4, NULL),
+ (5, NULL, 50);
+
+DROP FUNCTION IF EXISTS py_mixed_vector_add(INT, INT);
+
+CREATE FUNCTION py_mixed_vector_add(INT, INT)
+RETURNS INT
+PROPERTIES (
+ "type"="PYTHON_UDF",
+ "symbol"="py_mixed_vector_add_impl",
+ "always_nullable"="true",
+ "runtime_version"="3.12.11"
+)
+AS $$
+import pandas as pd
+
+# 建议保持入参风格一致
+def py_mixed_vector_add_impl(x: pd.Series, y: int):
+ return x + y
+$$;
+
+SELECT
+ id
+ a,
+ b,
+ py_mixed_vector_add(a, b) AS vector_val
+FROM t_bug_013
+ORDER BY id;
+-- 将 b 列视为常量列处理
++------+------+------+------------+
+| id | a | b | vector_val |
++------+------+------+------------+
+| 1 | 1 | 10 | 11 |
+| 2 | 2 | 20 | 12 |
+| 3 | 3 | 30 | 13 |
+| 4 | 4 | NULL | 14 |
+| 5 | NULL | 50 | NULL |
++------+------+------+------------+
+```
+
#### 向量化模式的优势
1. **性能优化**: 批量处理数据,减少 Python 与 Doris 之间的交互次数
diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/ai/ai-function-overview.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/ai/ai-function-overview.md
index e5d00c1068e..637b89581a8 100644
--- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/ai/ai-function-overview.md
+++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/ai/ai-function-overview.md
@@ -96,6 +96,11 @@ Doris 通过[资源机制](../sql-manual/sql-statements/cluster-management/compu
`ai.retry_delay_second`: 可选,重试的延迟时间(秒)。默认值为 0。
+:::caution Note
+当前仅支持静态 API Key 方式进行鉴权(通过请求头直接携带凭证)。
+对于需要通过私钥签名并交换临时访问令牌的鉴权机制(如 OAuth / Service Account 等),暂不支持。
+:::
+
## 厂商支持
目前直接支持的厂商有:OpenAI、Anthropic、Gemini、DeepSeek、Local、MoonShot、MiniMax、Zhipu、Qwen、Baichuan。
diff --git a/versioned_docs/version-4.x/ai/ai-function-overview.md b/versioned_docs/version-4.x/ai/ai-function-overview.md
index 6ab1d5f2605..197a72833d7 100644
--- a/versioned_docs/version-4.x/ai/ai-function-overview.md
+++ b/versioned_docs/version-4.x/ai/ai-function-overview.md
@@ -96,6 +96,11 @@ The currently available parameters are as follows:
`ai.retry_delay_second`: Optional, delay time (in seconds) between retries. Default is 0.
+:::caution Note
+Currently, only static API Key authentication is supported (credentials are carried directly in request headers).
+Authentication mechanisms that require private-key signing and temporary access token exchange (such as OAuth / Service Account) are not supported yet.
+:::
+
## Supported Providers
Currently supported providers include: OpenAI, Anthropic, Gemini, DeepSeek, Local, MoonShot, MiniMax, Zhipu, Qwen, Baichuan.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@doris.apache.org
For additional commands, e-mail: commits-help@doris.apache.org