通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

ai_embed_text插件（预览版）

  • 项目

适用于：✅Azure 数据资源管理器

该 ai_embed_text 插件允许使用语言模型嵌入文本，从而启用各种与 AI 相关的方案，例如检索扩充生成（RAG）应用程序和语义搜索。 该插件支持使用托管标识访问的 Azure OpenAI 服务嵌入模型。

先决条件

语法

evaluateai_embed_text (text， connectionString [, options [, IncludeErrorMessages]])

详细了解语法约定。

参数

客户 类型​​ 必需 说明
text string ✔️ 要嵌入的文本。 该值可以是列引用或常量标量。
connectionString string ✔️ 格式<ModelDeploymentUri>;<AuthenticationMethod>的语言模型连接字符串;分别替换为 <ModelDeploymentUri> <AuthenticationMethod> AI 模型部署 URI 和身份验证方法。
options dynamic 控制对嵌入模型终结点的调用的选项。 请参阅选项。
IncludeErrorMessages bool 指示是否在输出表中的新列中输出错误。 默认值：false。

选项

下表介绍了控制向嵌入模型终结点发出请求的方式的选项。

名称 Type 描述
RecordsPerRequest int 指定要处理每个请求的记录数。 默认值：1。
CharsPerRequest int 指定要处理每个请求的最大字符数。 默认值： 0 （无限制）。 Azure OpenAI 对令牌进行计数，每个令牌大约转换为四个字符。
RetriesOnThrottling int 指定发生限制时重试尝试次数。 默认值：0。
GlobalTimeout timespan 指定等待嵌入模型响应的最长时间。 默认值：30null
ModelParameters dynamic 特定于嵌入模型的参数，例如用于监视的嵌入维度或用户标识符。 默认值：null。
ReturnSuccessfulOnly bool 指示是否仅返回已成功处理的项。 默认值：false。 如果 IncludeErrorMessages 参数设置为 true，则此选项始终设置为 false。

配置托管标识和标注策略

若要使用该 ai_embed_text 插件，必须配置以下策略：

  • 托管标识：允许系统分配的托管标识向 Azure OpenAI 服务进行身份验证。
  • 标注：授权 AI 模型终结点域。

若要配置这些策略，请使用以下步骤中的命令：

  1. 配置托管标识：

    .alter-merge cluster policy managed_identity
```
[
  {
    "ObjectId": "system",
    "AllowedUsages": "AzureAI"
  }
]
```

  2. 配置标注策略：

    .alter-merge cluster policy callout
```
[
    {
        "CalloutType": "azure_openai",
        "CalloutUriRegex": "https://[A-Za-z0-9\\-]{3,63}\\.openai\\.azure\\.com/.*",
        "CanCall": true
    }
]
```

返回

返回以下新的嵌入列：

  • 包含 嵌入值的_embedding 后缀的列
  • 如果配置为返回错误，则为 _embedding_error 后缀的列，其中包含错误字符串;如果操作成功，则为空。

插件根据输入类型返回不同的结果：

  • 列引用：返回一个或多个包含其他列的记录以引用列名称为前缀。 例如，如果输入列名为 TextData，则输出列将命名 为TextData_embedding ，如果配置为返回错误， TextData_embedding_error。
  • 常量标量：返回包含不带前缀的其他列的单个记录。 列名称 _embedding ，如果配置为返回错误， _embedding_error。

示例

以下示例使用 Azure OpenAI 嵌入模型嵌入文本 Embed this text using AI 。

let expression = 'Embed this text using AI';
let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
evaluate ai_embed_text(expression, connectionString)

以下示例使用 Azure OpenAI 嵌入模型嵌入多个文本。

let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
let options = dynamic({
    "RecordsPerRequest": 10,
    "CharsPerRequest": 10000,
    "RetriesOnThrottling": 1,
    "GlobalTimeout": 2m
});
datatable(TextData: string)
[
    "First text to embed",
    "Second text to embed",
    "Third text to embed"
]
| evaluate ai_embed_text(TextData, connectionString, options , true)

最佳做法

Azure OpenAI 嵌入模型受重限制的约束，并且频繁调用此插件可以快速达到限制。

若要有效地使用 ai_embed_text 插件，同时最大程度地减少限制和成本，请遵循以下最佳做法：

  • 控制请求大小：调整每个请求的记录数（RecordsPerRequest）和字符数（CharsPerRequest）。
  • 控制查询超时：设置为GlobalTimeout低于查询超时的值，以确保在成功调用到该时间点时不会丢失进度。
  • 更正常地处理速率限制：对限制设置重试（RetriesOnThrottling）。

相关内容