This is an automated email from the ASF dual-hosted git repository.
morningman 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 18b66e61e9af [docs] Document AI structured output and dedicated
embedding properties (#4442)
18b66e61e9af is described below
commit 18b66e61e9af61e6d1931ebfbd09279ece2161b0
Author: linrrarity <[email protected]>
AuthorDate: Thu Oct 29 11:49:55 2026 +0800
[docs] Document AI structured output and dedicated embedding properties
(#4442)
## Versions
- [x] dev
- [x] 4.x
- [ ] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [ ] Checked by AI
- [ ] Test Cases Built
- [ ] Updated required version and language counterparts, or explained
why not
- [ ] If only one language changed, confirmed whether source/translation
counterparts need sync
---
docs/ai/ai-function-overview.md | 35 ++++++++++++++++++++++
.../ai-functions/distance-functions/embed.md | 2 ++
.../sql-functions/ai-functions/overview.md | 7 ++++-
.../current/ai/ai-function-overview.md | 35 ++++++++++++++++++++++
.../ai-functions/distance-functions/embed.md | 2 ++
.../sql-functions/ai-functions/overview.md | 6 ++++
.../version-4.x/ai/ai-function-overview.md | 35 ++++++++++++++++++++++
.../ai-functions/distance-functions/embed.md | 2 ++
.../sql-functions/ai-functions/overview.md | 6 ++++
.../version-4.x/ai/ai-function-overview.md | 35 ++++++++++++++++++++++
.../ai-functions/distance-functions/embed.md | 2 ++
.../sql-functions/ai-functions/overview.md | 7 ++++-
12 files changed, 172 insertions(+), 2 deletions(-)
diff --git a/docs/ai/ai-function-overview.md b/docs/ai/ai-function-overview.md
index 887f790d2deb..2c9244c096db 100644
--- a/docs/ai/ai-function-overview.md
+++ b/docs/ai/ai-function-overview.md
@@ -48,6 +48,8 @@ Doris uses the [resource
mechanism](../sql-manual/sql-statements/cluster-managem
### Resource parameters
+Configure at least one complete connection group: general `ai.*`, text
embedding `ai.embed.*`, or multimodal embedding `ai.embed.mm.*`. Each
configured group requires `provider_type`, `endpoint`, and `model_name`;
`api_key` is also required unless that group's provider is `LOCAL`. The
required connection fields below apply when configuring the general group.
Scalar AI functions and `AI_AGG` require the general group.
+
| Parameter | Required |
Description
|
| ----------------------- | ----------------------------------------- |
-------------------------------------------------------------------------------------------------------------
|
| `type` | Required | Must
be `ai`, used as the type identifier of an AI resource.
|
@@ -59,6 +61,39 @@ Doris uses the [resource
mechanism](../sql-manual/sql-statements/cluster-managem
| `ai.max_tokens` | Optional | Limits
the maximum number of tokens in the generated content. The default `-1` means
the parameter is not set; the default for Anthropic is `2048`. |
| `ai.max_retries` | Optional | The
maximum number of retries for a single request. The default value is `3`.
|
| `ai.retry_delay_second` | Optional | The
delay between retries, in seconds. The default value is `0`.
|
+| `ai.enable_structured_output` | Optional | Boolean, defaults to `true`.
Doris batches input rows for scalar AI functions. Enabling this option adds
provider-specific format fields to improve response-format reliability. Doris
does not check the configured model's support; LOCAL and MiniMax omit these
fields. Set it to `false` if the model or endpoint rejects them. Batching,
system-prompt format instructions, and response validation remain enabled. Does
not apply to `AI_AGG` or `EMBED`. |
+| `ai.effort` | Optional | String controlling reasoning effort for generation
requests; unset by default. Doris accepts `none`, `minimal`, `low`, `medium`,
`high`, `xhigh`, or `max` for OpenAI-compatible providers; Anthropic accepts
`low`, `medium`, `high`, `xhigh`, or `max`; Gemini accepts `minimal`, `low`,
`medium`, or `high`. The configured model must support the selected value. Set
it to an empty string with `ALTER RESOURCE` to remove it. |
+
+### Dedicated embedding properties
+
+All properties below are strings and have no default value. A configured group
must be complete; missing fields are not filled from another group.
+
+| Parameter | Description |
+| --- | --- |
+| `ai.embed.provider_type` | Provider for text embedding. |
+| `ai.embed.endpoint` | API endpoint for text embedding. |
+| `ai.embed.model_name` | Text embedding model name. |
+| `ai.embed.api_key` | API key for text embedding; optional for `LOCAL`. |
+| `ai.embed.mm.provider_type` | Provider for multimodal embedding. |
+| `ai.embed.mm.endpoint` | API endpoint for multimodal embedding. |
+| `ai.embed.mm.model_name` | Multimodal embedding model name. |
+| `ai.embed.mm.api_key` | API key for multimodal embedding; optional for
`LOCAL`. |
+
+For text input, `EMBED` selects the complete `ai.embed.*` group, then the
general group. For JSON multimodal input, it selects `ai.embed.mm.*`, then
`ai.embed.*`, then the general group. Selection uses a complete group as a
unit; the selected provider and model must support the input type. API keys in
all three groups are masked in `SHOW RESOURCES`. Parameters such as
`ai.dimensions` and retry settings are shared across groups.
+
+For example, create a resource used only for text embedding:
+
+```sql
+CREATE RESOURCE 'text_embedding' PROPERTIES (
+ 'type' = 'ai',
+ 'ai.embed.provider_type' = 'QWEN',
+ 'ai.embed.endpoint' =
'https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings',
+ 'ai.embed.model_name' = 'text-embedding-v4',
+ 'ai.embed.api_key' = '<api-key>'
+);
+```
+
+After replacing `<api-key>` with a valid key, the resource can be used by
`EMBED('text_embedding', 'example text')`. Add a complete general group to use
the same resource for scalar AI functions or `AI_AGG`.
:::caution Authentication notes
Currently only static API key authentication is supported (the credential is
sent directly in the request header). Authentication mechanisms that require
signing with a private key and exchanging for a temporary access token (such as
OAuth or Service Account) are not supported.
diff --git
a/docs/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
b/docs/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
index 9f3937fb404f..80d32664bc9d 100644
--- a/docs/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
+++ b/docs/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
@@ -82,6 +82,8 @@ The lifetime of the presigned URL is controlled by the
session variable `file_pr
SET file_presigned_url_ttl_seconds = 7200;
```
+For text input, `EMBED` uses the resource's complete `ai.embed.*` connection
group when configured, otherwise its general `ai.*` group. For JSON multimodal
input, the selection order is `ai.embed.mm.*`, `ai.embed.*`, then general
`ai.*`. Each group contains `endpoint`, `provider_type`, `model_name`, and
`api_key` (optional for `LOCAL`). Selection uses complete groups; the selected
provider and model must support the input type. A resource containing only
embedding properties is valid for [...]
+
## Return Value
The return type is `ARRAY<FLOAT>`, representing the generated vector.
diff --git a/docs/sql-manual/sql-functions/ai-functions/overview.md
b/docs/sql-manual/sql-functions/ai-functions/overview.md
index d02c1cfbe2f4..a7fa2546d79f 100644
--- a/docs/sql-manual/sql-functions/ai-functions/overview.md
+++ b/docs/sql-manual/sql-functions/ai-functions/overview.md
@@ -60,6 +60,8 @@ PROPERTIES (
##### Parameter Description
+An AI resource must contain at least one complete connection group: general
`ai.*`, text embedding `ai.embed.*`, or multimodal embedding `ai.embed.mm.*`.
Each configured group requires `endpoint`, `provider_type`, `model_name`, and
an `api_key` unless its provider is `LOCAL`. The required connection fields
below describe the general group, which scalar AI functions and `AI_AGG` use.
Text `EMBED` prefers `ai.embed.*` over the general group; JSON multimodal
`EMBED` prefers `ai.embed.mm.*`, [...]
+
`type`: Required, must be `ai`, used as the type identifier for ai.
`ai.provider_type`: Required for the general model group. Specifies the
external AI provider. Supported providers include OpenAI, Anthropic, Gemini,
DeepSeek, Local, MoonShot, MiniMax, Zhipu, QWen, Baichuan, VoyageAI, and Jina.
If another provider uses an API compatible with
[OpenAI](https://platform.openai.com/docs/overview),
[Anthropic](https://docs.anthropic.com/en/api/messages-examples), or
[Gemini](https://ai.google.dev/gemini-api/docs/quickstart#rest_1), specify the
corresponding c [...]
@@ -82,6 +84,8 @@ The default value is -1, which means this parameter is not
set. The default valu
`ai.retry_delay_second`: Optional. The delay before retrying, in seconds. The
default value on the development branch is 1; in Doris 4.1.5 it is 0.
+`ai.enable_structured_output`: Optional Boolean, defaults to `true`. Doris
batches input rows for scalar AI functions. Enabling this option adds
provider-specific format fields to improve response-format reliability. Doris
does not check the configured model's support; LOCAL and MiniMax omit these
fields. Set it to `false` if the model or endpoint rejects them. Batching,
system-prompt format instructions, and response validation remain enabled. This
property does not apply to `AI_AGG` or [...]
+
`ai.dimensions`: Optional, control the vector dimension of
[EMBED](./distance-functions/embed.md) output.
**Make sure to confirm that the model filled in `ai.model_name` supports
custom vector dimension before setting**,
otherwise it may cause model call failure.
@@ -125,6 +129,8 @@ Since version 4.1.5, the optional string property
`ai.effort` specifies reasonin
Passing property validation does not mean every model supports that effort
level. Choose a value supported by your service and model. `ai.effort` does not
replace `ai.max_token`.
+An empty string in `ALTER RESOURCE` removes the `ai.effort` setting.
+
### Create, Alter, and Drop Permissions (Since 4.1.5)
Creating an AI Resource requires global `ADMIN` privileges. Since version
4.1.5, the FE configuration
[`ai_resource_allowed_user`](../../../admin-manual/config/fe-config.md#ai_resource_allowed_user)
can further restrict the creator's identity. Its default value, `*`, adds no
identity restriction.
@@ -208,4 +214,3 @@ SELECT AI_SENTIMENT('Apache Doris is a great DBMS.');
```
For detailed function and usage, please refer to the documentation of each
specific function.
-
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 e5563d68db31..7a1fe9d9c197 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
@@ -48,6 +48,8 @@ Doris 通过
[资源（Resource）机制](../sql-manual/sql-statements/cluster-m
### 资源参数
+资源至少需要一组完整的连接配置：通用 `ai.*`、文本 embedding 的 `ai.embed.*` 或多模态 embedding 的
`ai.embed.mm.*`。每个配置组都需要 `provider_type`、`endpoint` 和 `model_name`；该组 provider
为 `LOCAL` 时可以省略 `api_key`，其他情况必须填写。下表连接字段的必填要求适用于通用配置组。标量 AI 函数和 `AI_AGG`
需要完整的通用配置组。
+
| 参数 | 是否必填 | 说明
|
| ----------------------- | --------------------------------------- |
-------------------------------------------------------------------------------------------------------------
|
| `type` | 必填 | 必须为
`ai`，作为 AI 资源的类型标识。
|
@@ -59,6 +61,39 @@ Doris 通过
[资源（Resource）机制](../sql-manual/sql-statements/cluster-m
| `ai.max_tokens` | 可选 | 限制生成内容的最大
token 数。默认 `-1` 表示不设置该参数；Anthropic 默认值为 `2048`。 |
| `ai.max_retries` | 可选 |
单次请求的最大重试次数。默认值 `3`。
|
| `ai.retry_delay_second` | 可选 |
重试的延迟时间（秒）。默认值 `0`。
|
+| `ai.enable_structured_output` | 可选 | Boolean 类型，默认 `true`。Doris 将标量 AI
函数的多行输入收集成批发送。开启该选项会附加 provider 对应的格式约束字段，以提高返回格式的稳定性。Doris
不检查所配置模型是否支持这些字段；LOCAL 和 MiniMax 省略这些字段。如果模型或 endpoint 拒绝这些字段，请设置为
`false`。关闭后仍然批量发送，通过系统提示词规定格式，并校验返回结果。该选项不适用于 `AI_AGG` 和 `EMBED`。 |
+| `ai.effort` | 可选 | 字符串类型，控制生成请求的推理强度，默认不设置。Doris 对 OpenAI 兼容 provider 接受
`none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`；对 Anthropic 接受
`low`、`medium`、`high`、`xhigh`、`max`；对 Gemini 接受
`minimal`、`low`、`medium`、`high`。配置的模型必须支持所选值。通过 `ALTER RESOURCE`
将该属性设为空字符串可以取消设置。 |
+
+### Embedding 专用配置
+
+以下属性均为字符串类型，没有默认值。填写某组配置时需要填写完整，缺失字段不会从其他配置组补充。
+
+| 参数 | 说明 |
+| --- | --- |
+| `ai.embed.provider_type` | 文本 embedding 的 provider。 |
+| `ai.embed.endpoint` | 文本 embedding 的 API endpoint。 |
+| `ai.embed.model_name` | 文本 embedding 的模型名称。 |
+| `ai.embed.api_key` | 文本 embedding 的 API Key；`LOCAL` 可以省略。 |
+| `ai.embed.mm.provider_type` | 多模态 embedding 的 provider。 |
+| `ai.embed.mm.endpoint` | 多模态 embedding 的 API endpoint。 |
+| `ai.embed.mm.model_name` | 多模态 embedding 的模型名称。 |
+| `ai.embed.mm.api_key` | 多模态 embedding 的 API Key；`LOCAL` 可以省略。 |
+
+文本输入的 `EMBED` 优先选择完整的 `ai.embed.*`，其次选择通用配置组。多模态输入依次选择
`ai.embed.mm.*`、`ai.embed.*`、通用配置组。选择以完整配置组为单位，选中的 provider 和模型必须支持输入类型。三组 API
Key 在 `SHOW RESOURCES` 中均会隐藏。`ai.dimensions` 和重试设置等参数由各组共用。
+
+例如，创建仅用于文本 embedding 的资源：
+
+```sql
+CREATE RESOURCE 'text_embedding' PROPERTIES (
+ 'type' = 'ai',
+ 'ai.embed.provider_type' = 'QWEN',
+ 'ai.embed.endpoint' =
'https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings',
+ 'ai.embed.model_name' = 'text-embedding-v4',
+ 'ai.embed.api_key' = '<api-key>'
+);
+```
+
+将 `<api-key>` 替换为有效密钥后，可以通过 `EMBED('text_embedding', 'example text')`
使用该资源。补充完整的通用配置组后，同一个资源也可以用于标量 AI 函数和 `AI_AGG`。
:::caution 鉴权方式说明
当前仅支持静态 API Key 方式进行鉴权（通过请求头直接携带凭证）。需要通过私钥签名并交换临时访问令牌的鉴权机制（如 OAuth、Service
Account 等）暂不支持。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
index e2e9b4887942..3d33e7640d6f 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
@@ -83,6 +83,8 @@ EMBED([<resource_name>], <input>)
SET file_presigned_url_ttl_seconds = 7200;
```
+文本输入的 `EMBED` 优先使用资源中完整的 `ai.embed.*` 连接配置组，未配置时使用通用 `ai.*`。JSON 多模态输入依次选择
`ai.embed.mm.*`、`ai.embed.*`、通用 `ai.*`。每组包含
`endpoint`、`provider_type`、`model_name` 和 `api_key`（`LOCAL`
可以省略）。选择以完整配置组为单位，选中的 provider 和模型需要支持输入类型。仅包含 embedding 配置的资源可以用于对应的 `EMBED`
调用。参见 [Embedding 专用配置](../../../../ai/ai-function-overview.md#embedding-专用配置)。
+
## 返回值
返回类型为 `ARRAY<FLOAT>`，表示生成的嵌入向量。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/ai-functions/overview.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/ai-functions/overview.md
index dd5b9171ebb9..1c7bb0e8cf94 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/ai-functions/overview.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/ai-functions/overview.md
@@ -56,6 +56,8 @@ PROPERTIES (
##### 参数说明
+AI 资源至少需要一组完整的连接配置：通用 `ai.*`、文本 embedding 的 `ai.embed.*` 或多模态 embedding 的
`ai.embed.mm.*`。每组都需要 `endpoint`、`provider_type`、`model_name`，该组 provider 为
`LOCAL` 时可以省略 `api_key`，其他情况必须填写。下文连接字段的必填要求适用于标量 AI 函数和 `AI_AGG` 使用的通用配置组。文本
`EMBED` 优先选择 `ai.embed.*`，其次选择通用配置组；JSON 多模态 `EMBED` 依次选择
`ai.embed.mm.*`、`ai.embed.*`、通用配置组。八个专用字段及示例见 [Embedding
专用配置](../../../ai/ai-function-overview.md#embedding-专用配置)。
+
`type`: 必填，且必须为 `ai`，作为 ai 的类型标识。
`ai.provider_type`: 通用模型配置组的必填项，外部 AI 厂商类型。目前支持
OpenAI、Anthropic、Gemini、DeepSeek、Local、MoonShot、MiniMax、Zhipu、QWen、Baichuan、VoyageAI
和 Jina。若其他厂商的 API 格式与
[OpenAI](https://platform.openai.com/docs/overview)/[Anthropic](https://docs.anthropic.com/en/api/messages-examples)/[Gemini](https://ai.google.dev/gemini-api/docs/quickstart#rest_1)
相同，可填写对应的兼容厂商类型。
@@ -76,6 +78,8 @@ Provider 类型校验通过不代表它支持全部 AI 函数。例如 VoyageAI
`ai.retry_delay_second`: 可选，重试前的延迟时间（秒）。开发分支默认值为 1，Doris 4.1.5 的默认值为 0。
+`ai.enable_structured_output`: 可选，Boolean 类型，默认 `true`。Doris 将标量 AI
函数的多行输入收集成批发送。开启该选项会附加 provider 对应的格式约束字段，以提高返回格式的稳定性。Doris
不检查所配置模型是否支持这些字段；LOCAL 和 MiniMax 省略这些字段。如果模型或 endpoint 拒绝这些字段，请设置为
`false`。关闭后仍然批量发送，通过系统提示词规定格式，并校验返回结果。该选项不适用于 `AI_AGG` 和 `EMBED`。
+
`ai.dimensions`:
可选，控制[EMBED](./distance-functions/embed.md)输出的向量维度。**设置前务必确认`ai.model_name`所填模型支持自定义向量维度**，否则可能会导致模型调用失败。
### Embedding 专用模型配置（4.1.5 起）
@@ -117,6 +121,8 @@ PROPERTIES (
属性校验通过不代表所有模型都支持该强度；应选择目标服务和模型支持的值。`ai.effort` 不会替代 `ai.max_token`。
+通过 `ALTER RESOURCE` 将 `ai.effort` 设置为空字符串可以取消设置。
+
### 创建、修改与删除权限（4.1.5 起）
创建 AI Resource 需要全局 `ADMIN` 权限。自 4.1.5 版本起，FE 配置
[`ai_resource_allowed_user`](../../../admin-manual/config/fe-config.md#ai_resource_allowed_user)
可进一步限制创建者身份，默认 `*` 不增加身份限制。
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 e5563d68db31..2a6708da50e2 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
@@ -48,6 +48,8 @@ Doris 通过
[资源（Resource）机制](../sql-manual/sql-statements/cluster-m
### 资源参数
+**Since 4.1.5。** 资源至少需要一组完整的连接配置：通用 `ai.*`、文本 embedding 的 `ai.embed.*` 或多模态
embedding 的 `ai.embed.mm.*`。每个配置组都需要 `provider_type`、`endpoint` 和
`model_name`；该组 provider 为 `LOCAL` 时可以省略
`api_key`，其他情况必须填写。下表连接字段的必填要求适用于通用配置组。标量 AI 函数和 `AI_AGG`
需要完整的通用配置组。更早版本需要完整的通用配置组。
+
| 参数 | 是否必填 | 说明
|
| ----------------------- | --------------------------------------- |
-------------------------------------------------------------------------------------------------------------
|
| `type` | 必填 | 必须为
`ai`，作为 AI 资源的类型标识。
|
@@ -59,6 +61,39 @@ Doris 通过
[资源（Resource）机制](../sql-manual/sql-statements/cluster-m
| `ai.max_tokens` | 可选 | 限制生成内容的最大
token 数。默认 `-1` 表示不设置该参数；Anthropic 默认值为 `2048`。 |
| `ai.max_retries` | 可选 |
单次请求的最大重试次数。默认值 `3`。
|
| `ai.retry_delay_second` | 可选 |
重试的延迟时间（秒）。默认值 `0`。
|
+| `ai.enable_structured_output` | 可选 | **Since 4.2。** Boolean 类型，默认
`true`。Doris 将标量 AI 函数的多行输入收集成批发送。开启该选项会附加 provider 对应的格式约束字段，以提高返回格式的稳定性。Doris
不检查所配置模型是否支持这些字段；LOCAL 和 MiniMax 省略这些字段。如果模型或 endpoint 拒绝这些字段，请设置为
`false`。关闭后仍然批量发送，通过系统提示词规定格式，并校验返回结果。该选项不适用于 `AI_AGG` 和 `EMBED`。 |
+| `ai.effort` | 可选 | **Since 4.1.5。** 字符串类型，控制生成请求的推理强度，默认不设置。Doris 对 OpenAI
兼容 provider 接受 `none`、`minimal`、`low`、`medium`、`high`、`xhigh`、`max`；对 Anthropic
接受 `low`、`medium`、`high`、`xhigh`、`max`；对 Gemini 接受
`minimal`、`low`、`medium`、`high`。配置的模型必须支持所选值。通过 `ALTER RESOURCE`
将该属性设为空字符串可以取消设置。 |
+
+### Embedding 专用配置
+
+**Since 4.1.5。** 以下属性均为字符串类型，没有默认值。填写某组配置时需要填写完整，缺失字段不会从其他配置组补充。
+
+| 参数 | 说明 |
+| --- | --- |
+| `ai.embed.provider_type` | 文本 embedding 的 provider。 |
+| `ai.embed.endpoint` | 文本 embedding 的 API endpoint。 |
+| `ai.embed.model_name` | 文本 embedding 的模型名称。 |
+| `ai.embed.api_key` | 文本 embedding 的 API Key；`LOCAL` 可以省略。 |
+| `ai.embed.mm.provider_type` | 多模态 embedding 的 provider。 |
+| `ai.embed.mm.endpoint` | 多模态 embedding 的 API endpoint。 |
+| `ai.embed.mm.model_name` | 多模态 embedding 的模型名称。 |
+| `ai.embed.mm.api_key` | 多模态 embedding 的 API Key；`LOCAL` 可以省略。 |
+
+文本输入的 `EMBED` 优先选择完整的 `ai.embed.*`，其次选择通用配置组。JSON 多模态输入依次选择
`ai.embed.mm.*`、`ai.embed.*`、通用配置组。选择以完整配置组为单位，选中的 provider 和模型必须支持输入类型。三组 API
Key 在 `SHOW RESOURCES` 中均会隐藏。`ai.dimensions` 和重试设置等参数由各组共用。
+
+例如，创建仅用于文本 embedding 的资源：
+
+```sql
+CREATE RESOURCE 'text_embedding' PROPERTIES (
+ 'type' = 'ai',
+ 'ai.embed.provider_type' = 'QWEN',
+ 'ai.embed.endpoint' =
'https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings',
+ 'ai.embed.model_name' = 'text-embedding-v4',
+ 'ai.embed.api_key' = '<api-key>'
+);
+```
+
+将 `<api-key>` 替换为有效密钥后，可以通过 `EMBED('text_embedding', 'example text')`
使用该资源。补充完整的通用配置组后，同一个资源也可以用于标量 AI 函数和 `AI_AGG`。
:::caution 鉴权方式说明
当前仅支持静态 API Key 方式进行鉴权（通过请求头直接携带凭证）。需要通过私钥签名并交换临时访问令牌的鉴权机制（如 OAuth、Service
Account 等）暂不支持。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
index e2e9b4887942..28f3be66e4f0 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
@@ -83,6 +83,8 @@ EMBED([<resource_name>], <input>)
SET file_presigned_url_ttl_seconds = 7200;
```
+**Since 4.1.5。** 文本输入的 `EMBED` 优先使用资源中完整的 `ai.embed.*` 连接配置组，未配置时使用通用
`ai.*`。JSON 多模态输入依次选择 `ai.embed.mm.*`、`ai.embed.*`、通用 `ai.*`。每组包含
`endpoint`、`provider_type`、`model_name` 和 `api_key`（`LOCAL`
可以省略）。选择以完整配置组为单位，选中的 provider 和模型需要支持输入类型。仅包含 embedding 配置的资源可以用于对应的 `EMBED`
调用。更早版本使用通用配置组。参见 [Embedding
专用配置](../../../../ai/ai-function-overview.md#embedding-专用配置)。
+
## 返回值
返回类型为 `ARRAY<FLOAT>`，表示生成的嵌入向量。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/overview.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/overview.md
index eace7ea50eaa..7090008ed819 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/overview.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/overview.md
@@ -56,6 +56,8 @@ PROPERTIES (
##### 参数说明
+**Since 4.1.5。** AI 资源至少需要一组完整的连接配置：通用 `ai.*`、文本 embedding 的 `ai.embed.*` 或多模态
embedding 的 `ai.embed.mm.*`。每组都需要 `endpoint`、`provider_type`、`model_name`，该组
provider 为 `LOCAL` 时可以省略 `api_key`，其他情况必须填写。下文连接字段的必填要求适用于标量 AI 函数和 `AI_AGG`
使用的通用配置组。文本 `EMBED` 优先选择 `ai.embed.*`，其次选择通用配置组；JSON 多模态 `EMBED` 依次选择
`ai.embed.mm.*`、`ai.embed.*`、通用配置组。更早版本需要完整的通用配置组。八个专用字段及示例见 [Embedding
专用配置](../../../ai/ai-function-overview.md#embedding-专用配置)。
+
`type`: 必填，且必须为 `ai`，作为 ai 的类型标识。
`ai.provider_type`: 通用模型配置组的必填项，外部 AI 厂商类型。目前支持
OpenAI、Anthropic、Gemini、DeepSeek、Local、MoonShot、MiniMax、Zhipu、QWen、Baichuan、VoyageAI
和 Jina。若其他厂商的 API 格式与
[OpenAI](https://platform.openai.com/docs/overview)/[Anthropic](https://docs.anthropic.com/en/api/messages-examples)/[Gemini](https://ai.google.dev/gemini-api/docs/quickstart#rest_1)
相同，可填写对应的兼容厂商类型。
@@ -76,6 +78,8 @@ Provider 类型校验通过不代表它支持全部 AI 函数。例如 VoyageAI
`ai.retry_delay_second`: 可选，重试的延迟时间（秒）。默认值为 0。
+`ai.enable_structured_output`（**Since 4.2**）：可选，Boolean 类型，默认 `true`。Doris 将标量
AI 函数的多行输入收集成批发送。开启该选项会附加 provider 对应的格式约束字段，以提高返回格式的稳定性。Doris
不检查所配置模型是否支持这些字段；LOCAL 和 MiniMax 省略这些字段。如果模型或 endpoint 拒绝这些字段，请设置为
`false`。关闭后仍然批量发送，通过系统提示词规定格式，并校验返回结果。该选项不适用于 `AI_AGG` 和 `EMBED`。
+
`ai.dimensions`:
可选，控制[EMBED](./distance-functions/embed.md)输出的向量维度。**设置前务必确认`ai.model_name`所填模型支持自定义向量维度**，否则可能会导致模型调用失败。
### Embedding 专用模型配置（4.1.5 起）
@@ -117,6 +121,8 @@ PROPERTIES (
属性校验通过不代表所有模型都支持该强度；应选择目标服务和模型支持的值。`ai.effort` 不会替代 `ai.max_token`。
+通过 `ALTER RESOURCE` 将 `ai.effort` 设置为空字符串可以取消设置。
+
### 创建、修改与删除权限（4.1.5 起）
创建 AI Resource 需要全局 `ADMIN` 权限。自 4.1.5 版本起，FE 配置
[`ai_resource_allowed_user`](../../../admin-manual/config/fe-config.md#ai_resource_allowed_user)
可进一步限制创建者身份，默认 `*` 不增加身份限制。
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 887f790d2deb..af6c01bb9c22 100644
--- a/versioned_docs/version-4.x/ai/ai-function-overview.md
+++ b/versioned_docs/version-4.x/ai/ai-function-overview.md
@@ -48,6 +48,8 @@ Doris uses the [resource
mechanism](../sql-manual/sql-statements/cluster-managem
### Resource parameters
+**Since 4.1.5**, configure at least one complete connection group: general
`ai.*`, text embedding `ai.embed.*`, or multimodal embedding `ai.embed.mm.*`.
Each configured group requires `provider_type`, `endpoint`, and `model_name`;
`api_key` is also required unless that group's provider is `LOCAL`. The
required connection fields below apply when configuring the general group.
Scalar AI functions and `AI_AGG` require the general group. Earlier versions
require the general group.
+
| Parameter | Required |
Description
|
| ----------------------- | ----------------------------------------- |
-------------------------------------------------------------------------------------------------------------
|
| `type` | Required | Must
be `ai`, used as the type identifier of an AI resource.
|
@@ -59,6 +61,39 @@ Doris uses the [resource
mechanism](../sql-manual/sql-statements/cluster-managem
| `ai.max_tokens` | Optional | Limits
the maximum number of tokens in the generated content. The default `-1` means
the parameter is not set; the default for Anthropic is `2048`. |
| `ai.max_retries` | Optional | The
maximum number of retries for a single request. The default value is `3`.
|
| `ai.retry_delay_second` | Optional | The
delay between retries, in seconds. The default value is `0`.
|
+| `ai.enable_structured_output` | Optional | **Since 4.2.** Boolean, defaults
to `true`. Doris batches input rows for scalar AI functions. Enabling this
option adds provider-specific format fields to improve response-format
reliability. Doris does not check the configured model's support; LOCAL and
MiniMax omit these fields. Set it to `false` if the model or endpoint rejects
them. Batching, system-prompt format instructions, and response validation
remain enabled. Does not apply to `AI_A [...]
+| `ai.effort` | Optional | **Since 4.1.5.** String controlling reasoning
effort for generation requests; unset by default. Doris accepts `none`,
`minimal`, `low`, `medium`, `high`, `xhigh`, or `max` for OpenAI-compatible
providers; Anthropic accepts `low`, `medium`, `high`, `xhigh`, or `max`; Gemini
accepts `minimal`, `low`, `medium`, or `high`. The configured model must
support the selected value. Set it to an empty string with `ALTER RESOURCE` to
remove it. |
+
+### Dedicated embedding properties
+
+**Since 4.1.5.** All properties below are strings and have no default value. A
configured group must be complete; missing fields are not filled from another
group.
+
+| Parameter | Description |
+| --- | --- |
+| `ai.embed.provider_type` | Provider for text embedding. |
+| `ai.embed.endpoint` | API endpoint for text embedding. |
+| `ai.embed.model_name` | Text embedding model name. |
+| `ai.embed.api_key` | API key for text embedding; optional for `LOCAL`. |
+| `ai.embed.mm.provider_type` | Provider for multimodal embedding. |
+| `ai.embed.mm.endpoint` | API endpoint for multimodal embedding. |
+| `ai.embed.mm.model_name` | Multimodal embedding model name. |
+| `ai.embed.mm.api_key` | API key for multimodal embedding; optional for
`LOCAL`. |
+
+For text input, `EMBED` selects the complete `ai.embed.*` group, then the
general group. For JSON multimodal input, it selects `ai.embed.mm.*`, then
`ai.embed.*`, then the general group. Selection uses a complete group as a
unit; the selected provider and model must support the input type. API keys in
all three groups are masked in `SHOW RESOURCES`. Parameters such as
`ai.dimensions` and retry settings are shared across groups.
+
+For example, create a resource used only for text embedding:
+
+```sql
+CREATE RESOURCE 'text_embedding' PROPERTIES (
+ 'type' = 'ai',
+ 'ai.embed.provider_type' = 'QWEN',
+ 'ai.embed.endpoint' =
'https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings',
+ 'ai.embed.model_name' = 'text-embedding-v4',
+ 'ai.embed.api_key' = '<api-key>'
+);
+```
+
+After replacing `<api-key>` with a valid key, the resource can be used by
`EMBED('text_embedding', 'example text')`. Add a complete general group to use
the same resource for scalar AI functions or `AI_AGG`.
:::caution Authentication notes
Currently only static API key authentication is supported (the credential is
sent directly in the request header). Authentication mechanisms that require
signing with a private key and exchanging for a temporary access token (such as
OAuth or Service Account) are not supported.
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
index 9f3937fb404f..f48656edd15c 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/embed.md
@@ -82,6 +82,8 @@ The lifetime of the presigned URL is controlled by the
session variable `file_pr
SET file_presigned_url_ttl_seconds = 7200;
```
+**Since 4.1.5**, for text input, `EMBED` uses the resource's complete
`ai.embed.*` connection group when configured, otherwise its general `ai.*`
group. For JSON multimodal input, the selection order is `ai.embed.mm.*`,
`ai.embed.*`, then general `ai.*`. Each group contains `endpoint`,
`provider_type`, `model_name`, and `api_key` (optional for `LOCAL`). Selection
uses complete groups; the selected provider and model must support the input
type. A resource containing only embedding proper [...]
+
## Return Value
The return type is `ARRAY<FLOAT>`, representing the generated vector.
diff --git
a/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/overview.md
b/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/overview.md
index 7616f6c4e4cd..29524a3d0c12 100644
---
a/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/overview.md
+++
b/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/overview.md
@@ -60,6 +60,8 @@ PROPERTIES (
##### Parameter Description
+**Since 4.1.5**, an AI resource must contain at least one complete connection
group: general `ai.*`, text embedding `ai.embed.*`, or multimodal embedding
`ai.embed.mm.*`. Each configured group requires `endpoint`, `provider_type`,
`model_name`, and an `api_key` unless its provider is `LOCAL`. The required
connection fields below describe the general group, which scalar AI functions
and `AI_AGG` use. Text `EMBED` prefers `ai.embed.*` over the general group;
JSON multimodal `EMBED` prefers [...]
+
`type`: Required, must be `ai`, used as the type identifier for ai.
`ai.provider_type`: Required for the general model group. Specifies the
external AI provider. Supported providers include OpenAI, Anthropic, Gemini,
DeepSeek, Local, MoonShot, MiniMax, Zhipu, QWen, Baichuan, VoyageAI, and Jina.
If another provider uses an API compatible with
[OpenAI](https://platform.openai.com/docs/overview),
[Anthropic](https://docs.anthropic.com/en/api/messages-examples), or
[Gemini](https://ai.google.dev/gemini-api/docs/quickstart#rest_1), specify the
corresponding c [...]
@@ -82,6 +84,8 @@ The default value is -1, which means this parameter is not
set. The default valu
`ai.retry_delay_second`: Optional. The delay time (in seconds) before
retrying. The default value is 0.
+`ai.enable_structured_output` (**Since 4.2**): Optional Boolean, defaults to
`true`. Doris batches input rows for scalar AI functions. Enabling this option
adds provider-specific format fields to improve response-format reliability.
Doris does not check the configured model's support; LOCAL and MiniMax omit
these fields. Set it to `false` if the model or endpoint rejects them.
Batching, system-prompt format instructions, and response validation remain
enabled. This property does not appl [...]
+
`ai.dimensions`: Optional, control the vector dimension of
[EMBED](./distance-functions/embed.md) output.
**Make sure to confirm that the model filled in `ai.model_name` supports
custom vector dimension before setting**,
otherwise it may cause model call failure.
@@ -125,6 +129,8 @@ Since version 4.1.5, the optional string property
`ai.effort` specifies reasonin
Passing property validation does not mean every model supports that effort
level. Choose a value supported by your service and model. `ai.effort` does not
replace `ai.max_token`.
+An empty string in `ALTER RESOURCE` removes the `ai.effort` setting.
+
### Create, Alter, and Drop Permissions (Since 4.1.5)
Creating an AI Resource requires global `ADMIN` privileges. Since version
4.1.5, the FE configuration
[`ai_resource_allowed_user`](../../../admin-manual/config/fe-config.md#ai_resource_allowed_user)
can further restrict the creator's identity. Its default value, `*`, adds no
identity restriction.
@@ -208,4 +214,3 @@ SELECT AI_SENTIMENT('Apache Doris is a great DBMS.');
```
For detailed function and usage, please refer to the documentation of each
specific function.
-
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
