如何使用 Azure AI 模型推理服务生成嵌入内容 - Azure AI Foundry

重要

本文中标记了“（预览版）”的项目目前为公共预览版。此预览版未提供服务级别协议，不建议将其用于生产工作负载。某些功能可能不受支持或者受限。有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

本文介绍如何在 Azure AI 服务中将嵌入 API 与部署到 Azure AI 模型推理的模型配合使用。

先决条件

若要在应用程序中使用嵌入模型，你需要：

Azure 订阅。如果你正在使用 GitHub 模型，则可以升级体验并在此过程中创建 Azure 订阅。如果是这种情况，请阅读从 GitHub 模型升级到 Azure AI 模型推理。
Azure AI 服务资源。有关详细信息，请参阅创建 Azure AI 服务资源。
终结点 URL 和密钥。

嵌入模型部署。如果你没有，请阅读添加模型并将其配置到 Azure AI 服务，以便向资源添加嵌入模型。
请使用以下命令安装 Azure AI 推理包：
```
pip install -U azure-ai-inference
```
提示

详细了解 Azure AI 推理包和参考。

使用嵌入

首先，创建客户端以使用模型。以下代码使用存储在环境变量中的终结点 URL 和密钥。

import os
from azure.ai.inference import EmbeddingsClient
from azure.core.credentials import AzureKeyCredential

model = EmbeddingsClient(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=AzureKeyCredential(os.environ["AZURE_INFERENCE_CREDENTIAL"]),
    model="text-embedding-3-small"
)

如果将资源配置为具有 Microsoft Entra ID 支持，则可以使用以下代码片段创建客户端。

import os
from azure.ai.inference import EmbeddingsClient
from azure.core.credentials import AzureKeyCredential

model = EmbeddingsClient(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredential(),
    model="text-embedding-3-small"
)

创建嵌入

创建嵌入请求以查看模型的输出。

response = model.embed(
    input=["The ultimate answer to the question of life"],
)

提示

创建请求时，请考虑模型的标记输入限制。如果需要嵌入较大的文本，则需要分块策略。

响应如下所示，可从中查看模型的使用统计信息：

import numpy as np

for embed in response.data:
    print("Embeding of size:", np.asarray(embed.embedding).shape)

print("Model:", response.model)
print("Usage:", response.usage)

在输入批处理中计算嵌入可能很有用。参数 inputs 可以是字符串列表，其中每个字符串都是不同的输入。反过来，响应是嵌入列表，其中每个嵌入对应于同一位置的输入。

response = model.embed(
    input=[
        "The ultimate answer to the question of life", 
        "The largest planet in our solar system is Jupiter",
    ],
)

响应如下所示，可从中查看模型的使用统计信息：

import numpy as np

for embed in response.data:
    print("Embeding of size:", np.asarray(embed.embedding).shape)

print("Model:", response.model)
print("Usage:", response.usage)

提示

创建请求批处理时，请考虑每个模型的批处理限制。大多数模型都有 1024 的批限制。

指定嵌入维度

可以指定嵌入的维度数。以下示例代码演示如何创建具有 1024 维度的嵌入内容。请注意，并非所有嵌入模型都支持在请求中指示维度数，在这些情况下会返回 422 错误。

response = model.embed(
    input=["The ultimate answer to the question of life"],
    dimensions=1024,
)

创建不同类型的嵌入

某些模型可以为同一输入生成多个嵌入，具体取决于你计划如何使用它们。此功能允许检索 RAG 模式的更准确的嵌入。

以下示例演示如何创建嵌入，这些嵌入用于为要存储在矢量数据库中的文档创建嵌入：

from azure.ai.inference.models import EmbeddingInputType

response = model.embed(
    input=["The answer to the ultimate question of life, the universe, and everything is 42"],
    input_type=EmbeddingInputType.DOCUMENT,
)

处理查询以检索此类文档时，可以使用以下代码片段为查询创建嵌入，并最大程度地提高检索性能。

from azure.ai.inference.models import EmbeddingInputType

response = model.embed(
    input=["What's the ultimate meaning of life?"],
    input_type=EmbeddingInputType.QUERY,
)

请注意，并非所有嵌入模型都支持在请求中指示输入类型，在这些情况下会返回 422 错误。默认情况下，返回类型 Text 的嵌入。

重要

本文中标记了“（预览版）”的项目目前为公共预览版。此预览版未提供服务级别协议，不建议将其用于生产工作负载。某些功能可能不受支持或者受限。有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

本文介绍如何在 Azure AI 服务中将嵌入 API 与部署到 Azure AI 模型推理的模型配合使用。

先决条件

若要在应用程序中使用嵌入模型，你需要：

Azure 订阅。如果你正在使用 GitHub 模型，则可以升级体验并在此过程中创建 Azure 订阅。如果是这种情况，请阅读从 GitHub 模型升级到 Azure AI 模型推理。
Azure AI 服务资源。有关详细信息，请参阅创建 Azure AI 服务资源。
终结点 URL 和密钥。

嵌入模型部署。如果你没有，请阅读添加模型并将其配置到 Azure AI 服务，以便向资源添加嵌入模型。
使用以下命令安装适用于 JavaScript 的 Azure 推理库：
```
npm install @azure-rest/ai-inference
```
提示

详细了解 Azure AI 推理包和参考。

使用嵌入

首先，创建客户端以使用模型。以下代码使用存储在环境变量中的终结点 URL 和密钥。

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { AzureKeyCredential } from "@azure/core-auth";

const client = new ModelClient(
    process.env.AZURE_INFERENCE_ENDPOINT, 
    new AzureKeyCredential(process.env.AZURE_INFERENCE_CREDENTIAL),
    "text-embedding-3-small"
);

如果将资源配置为具有 Microsoft Entra ID 支持，则可以使用以下代码片段创建客户端。

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential }  from "@azure/identity";

const client = new ModelClient(
    process.env.AZURE_INFERENCE_ENDPOINT, 
    new DefaultAzureCredential(),
    "text-embedding-3-small"
);

创建嵌入

创建嵌入请求以查看模型的输出。

var response = await client.path("/embeddings").post({
    body: {
        input: ["The ultimate answer to the question of life"],
    }
});

提示

创建请求时，请考虑模型的标记输入限制。如果需要嵌入较大的文本，则需要分块策略。

响应如下所示，可从中查看模型的使用统计信息：

if (isUnexpected(response)) {
    throw response.body.error;
}

console.log(response.embedding);
console.log(response.body.model);
console.log(response.body.usage);

在输入批处理中计算嵌入可能很有用。参数 inputs 可以是字符串列表，其中每个字符串都是不同的输入。反过来，响应是嵌入列表，其中每个嵌入对应于同一位置的输入。

var response = await client.path("/embeddings").post({
    body: {
        input: [
            "The ultimate answer to the question of life", 
            "The largest planet in our solar system is Jupiter",
        ],
    }
});

响应如下所示，可从中查看模型的使用统计信息：

if (isUnexpected(response)) {
    throw response.body.error;
}

console.log(response.embedding);
console.log(response.body.model);
console.log(response.body.usage);

提示

创建请求批处理时，请考虑每个模型的批处理限制。大多数模型都有 1024 的批限制。

指定嵌入维度

可以指定嵌入的维度数。以下示例代码演示如何创建具有 1024 维度的嵌入内容。请注意，并非所有嵌入模型都支持在请求中指示维度数，在这些情况下会返回 422 错误。

var response = await client.path("/embeddings").post({
    body: {
        input: ["The ultimate answer to the question of life"],
        dimensions: 1024,
    }
});

创建不同类型的嵌入

某些模型可以为同一输入生成多个嵌入，具体取决于你计划如何使用它们。此功能允许检索 RAG 模式的更准确的嵌入。

以下示例演示如何创建嵌入，这些嵌入用于为要存储在矢量数据库中的文档创建嵌入：

var response = await client.path("/embeddings").post({
    body: {
        input: ["The answer to the ultimate question of life, the universe, and everything is 42"],
        input_type: "document",
    }
});

处理查询以检索此类文档时，可以使用以下代码片段为查询创建嵌入，并最大程度地提高检索性能。

var response = await client.path("/embeddings").post({
    body: {
        input: ["What's the ultimate meaning of life?"],
        input_type: "query",
    }
});

请注意，并非所有嵌入模型都支持在请求中指示输入类型，在这些情况下会返回 422 错误。默认情况下，返回类型 Text 的嵌入。

重要

本文中标记了“（预览版）”的项目目前为公共预览版。此预览版未提供服务级别协议，不建议将其用于生产工作负载。某些功能可能不受支持或者受限。有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

本文介绍如何在 Azure AI 服务中将嵌入 API 与部署到 Azure AI 模型推理的模型配合使用。

先决条件

若要在应用程序中使用嵌入模型，你需要：

Azure 订阅。如果你正在使用 GitHub 模型，则可以升级体验并在此过程中创建 Azure 订阅。如果是这种情况，请阅读从 GitHub 模型升级到 Azure AI 模型推理。
Azure AI 服务资源。有关详细信息，请参阅创建 Azure AI 服务资源。
终结点 URL 和密钥。

嵌入模型部署。如果你没有，请阅读添加模型并将其配置到 Azure AI 服务，以便向资源添加嵌入模型。

将 Azure AI 推理包添加到项目：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>

提示

详细了解 Azure AI 推理包和参考。

如果使用 Entra ID，则还需要以下包：

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.13.3</version>
</dependency>

导入下列命名空间：

package com.azure.ai.inference.usage;

import com.azure.ai.inference.EmbeddingsClient;
import com.azure.ai.inference.EmbeddingsClientBuilder;
import com.azure.ai.inference.models.EmbeddingsResult;
import com.azure.ai.inference.models.EmbeddingItem;
import com.azure.core.credential.AzureKeyCredential;
import com.azure.core.util.Configuration;

import java.util.ArrayList;
import java.util.List;

使用嵌入

首先，创建客户端以使用模型。以下代码使用存储在环境变量中的终结点 URL 和密钥。

EmbeddingsClient client = new EmbeddingsClient(
    URI.create(System.getProperty("AZURE_INFERENCE_ENDPOINT")),
    new AzureKeyCredential(System.getProperty("AZURE_INFERENCE_CREDENTIAL")),
    "text-embedding-3-small"
);

如果将资源配置为具有 Microsoft Entra ID 支持，则可以使用以下代码片段创建客户端。

client = new EmbeddingsClient(
    URI.create(System.getProperty("AZURE_INFERENCE_ENDPOINT")),
    new DefaultAzureCredential(),
    "text-embedding-3-small"
);

创建嵌入

创建嵌入请求以查看模型的输出。

EmbeddingsOptions requestOptions = new EmbeddingsOptions()
    .setInput(Arrays.asList("The ultimate answer to the question of life"));

Response<EmbeddingsResult> response = client.embed(requestOptions);

提示

创建请求时，请考虑模型的标记输入限制。如果需要嵌入较大的文本，则需要分块策略。

响应如下所示，可从中查看模型的使用统计信息：

System.out.println("Embedding: " + response.getValue().getData());
System.out.println("Model: " + response.getValue().getModel());
System.out.println("Usage:");
System.out.println("\tPrompt tokens: " + response.getValue().getUsage().getPromptTokens());
System.out.println("\tTotal tokens: " + response.getValue().getUsage().getTotalTokens());

在输入批处理中计算嵌入可能很有用。参数 inputs 可以是字符串列表，其中每个字符串都是不同的输入。反过来，响应是嵌入列表，其中每个嵌入对应于同一位置的输入。

requestOptions = new EmbeddingsOptions()
    .setInput(Arrays.asList(
        "The ultimate answer to the question of life", 
        "The largest planet in our solar system is Jupiter"
    ));

response = client.embed(requestOptions);

响应如下所示，可从中查看模型的使用统计信息：

提示

创建请求批处理时，请考虑每个模型的批处理限制。大多数模型都有 1024 的批限制。

指定嵌入维度

可以指定嵌入的维度数。以下示例代码演示如何创建具有 1024 维度的嵌入内容。请注意，并非所有嵌入模型都支持在请求中指示维度数，在这些情况下会返回 422 错误。

创建不同类型的嵌入

某些模型可以为同一输入生成多个嵌入，具体取决于你计划如何使用它们。此功能允许检索 RAG 模式的更准确的嵌入。

以下示例演示如何创建嵌入，这些嵌入用于为要存储在矢量数据库中的文档创建嵌入：

List<String> input = Arrays.asList("The answer to the ultimate question of life, the universe, and everything is 42");
requestOptions = new EmbeddingsOptions(input, EmbeddingInputType.DOCUMENT);

response = client.embed(requestOptions);

处理查询以检索此类文档时，可以使用以下代码片段为查询创建嵌入，并最大程度地提高检索性能。

input = Arrays.asList("What's the ultimate meaning of life?");
requestOptions = new EmbeddingsOptions(input, EmbeddingInputType.QUERY);

response = client.embed(requestOptions);

请注意，并非所有嵌入模型都支持在请求中指示输入类型，在这些情况下会返回 422 错误。默认情况下，返回类型 Text 的嵌入。

重要

本文中标记了“（预览版）”的项目目前为公共预览版。此预览版未提供服务级别协议，不建议将其用于生产工作负载。某些功能可能不受支持或者受限。有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

本文介绍如何在 Azure AI 服务中将嵌入 API 与部署到 Azure AI 模型推理的模型配合使用。

先决条件

若要在应用程序中使用嵌入模型，你需要：

Azure 订阅。如果你正在使用 GitHub 模型，则可以升级体验并在此过程中创建 Azure 订阅。如果是这种情况，请阅读从 GitHub 模型升级到 Azure AI 模型推理。
Azure AI 服务资源。有关详细信息，请参阅创建 Azure AI 服务资源。
终结点 URL 和密钥。

嵌入模型部署。如果你没有，请阅读添加模型并将其配置到 Azure AI 服务，以便向资源添加嵌入模型。
请使用以下命令安装 Azure AI 推理包：
```
dotnet add package Azure.AI.Inference --prerelease
```
提示

详细了解 Azure AI 推理包和参考。
如果使用 Entra ID，则还需要以下包：
```
dotnet add package Azure.Identity
```

使用嵌入

首先，创建客户端以使用模型。以下代码使用存储在环境变量中的终结点 URL 和密钥。

EmbeddingsClient client = new EmbeddingsClient(
    new Uri(Environment.GetEnvironmentVariable("AZURE_INFERENCE_ENDPOINT")),
    new AzureKeyCredential(Environment.GetEnvironmentVariable("AZURE_INFERENCE_CREDENTIAL")),
    "text-embedding-3-small"
);

如果将资源配置为具有 Microsoft Entra ID 支持，则可以使用以下代码片段创建客户端。

client = new EmbeddingsClient(
    new Uri(Environment.GetEnvironmentVariable("AZURE_INFERENCE_ENDPOINT")),
    new DefaultAzureCredential(includeInteractiveCredentials: true),
    "text-embedding-3-small"
);

创建嵌入

创建嵌入请求以查看模型的输出。

EmbeddingsOptions requestOptions = new EmbeddingsOptions()
{
    Input = {
        "The ultimate answer to the question of life"
    },
};

Response<EmbeddingsResult> response = client.Embed(requestOptions);

提示

创建请求时，请考虑模型的标记输入限制。如果需要嵌入较大的文本，则需要分块策略。

响应如下所示，可从中查看模型的使用统计信息：

Console.WriteLine($"Embedding: {response.Value.Data}");
Console.WriteLine($"Model: {response.Value.Model}");
Console.WriteLine("Usage:");
Console.WriteLine($"\tPrompt tokens: {response.Value.Usage.PromptTokens}");
Console.WriteLine($"\tTotal tokens: {response.Value.Usage.TotalTokens}");

在输入批处理中计算嵌入可能很有用。参数 inputs 可以是字符串列表，其中每个字符串都是不同的输入。反过来，响应是嵌入列表，其中每个嵌入对应于同一位置的输入。

EmbeddingsOptions requestOptions = new EmbeddingsOptions()
{
    Input = {
        "The ultimate answer to the question of life", 
        "The largest planet in our solar system is Jupiter"
    },
};

Response<EmbeddingsResult> response = client.Embed(requestOptions);

响应如下所示，可从中查看模型的使用统计信息：

提示

创建请求批处理时，请考虑每个模型的批处理限制。大多数模型都有 1024 的批限制。

指定嵌入维度

可以指定嵌入的维度数。以下示例代码演示如何创建具有 1024 维度的嵌入内容。请注意，并非所有嵌入模型都支持在请求中指示维度数，在这些情况下会返回 422 错误。

创建不同类型的嵌入

某些模型可以为同一输入生成多个嵌入，具体取决于你计划如何使用它们。此功能允许检索 RAG 模式的更准确的嵌入。

以下示例演示如何创建嵌入，这些嵌入用于为要存储在矢量数据库中的文档创建嵌入：

var input = new List<string> { 
    "The answer to the ultimate question of life, the universe, and everything is 42"
};
var requestOptions = new EmbeddingsOptions(input, EmbeddingInputType.DOCUMENT);

Response<EmbeddingsResult> response = client.Embed(requestOptions);

处理查询以检索此类文档时，可以使用以下代码片段为查询创建嵌入，并最大程度地提高检索性能。

var input = new List<string> { 
    "What's the ultimate meaning of life?"
};
var requestOptions = new EmbeddingsOptions(input, EmbeddingInputType.QUERY);

Response<EmbeddingsResult> response = client.Embed(requestOptions);

请注意，并非所有嵌入模型都支持在请求中指示输入类型，在这些情况下会返回 422 错误。默认情况下，返回类型 Text 的嵌入。

重要

本文中标记了“（预览版）”的项目目前为公共预览版。此预览版未提供服务级别协议，不建议将其用于生产工作负载。某些功能可能不受支持或者受限。有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

本文介绍如何在 Azure AI 服务中将嵌入 API 与部署到 Azure AI 模型推理的模型配合使用。

先决条件

若要在应用程序中使用嵌入模型，你需要：

Azure 订阅。如果你正在使用 GitHub 模型，则可以升级体验并在此过程中创建 Azure 订阅。如果是这种情况，请阅读从 GitHub 模型升级到 Azure AI 模型推理。
Azure AI 服务资源。有关详细信息，请参阅创建 Azure AI 服务资源。
终结点 URL 和密钥。

嵌入模型部署。如果你没有，请阅读添加模型并将其配置到 Azure AI 服务，以便向资源添加嵌入模型。

使用嵌入

若要使用文本嵌入，请使用追加到基 URL 的路由 /embeddings 以及 api-key 中指示的凭据。 Bearer <key> 格式也支持 Authorization 标头。

POST https://<resource>.services.ai.azure.com/models/embeddings?api-version=2024-05-01-preview
Content-Type: application/json
api-key: <key>

如果已将资源配置为具有 Microsoft Entra ID 支持，请在 Authorization 标头中传递令牌：

POST https://<resource>.services.ai.azure.com/models/embeddings?api-version=2024-05-01-preview
Content-Type: application/json
Authorization: Bearer <token>

创建嵌入

创建嵌入请求以查看模型的输出。

{
    "input": [
        "The ultimate answer to the question of life"
    ]
}

提示

创建请求时，请考虑模型的标记输入限制。如果需要嵌入较大的文本，则需要分块策略。

响应如下所示，可从中查看模型的使用统计信息：

{
    "id": "0ab1234c-d5e6-7fgh-i890-j1234k123456",
    "object": "list",
    "data": [
        {
            "index": 0,
            "object": "embedding",
            "embedding": [
                0.017196655,
                // ...
                -0.000687122,
                -0.025054932,
                -0.015777588
            ]
        }
    ],
    "model": "text-embedding-3-small",
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 0,
        "total_tokens": 9
    }
}

在输入批处理中计算嵌入可能很有用。参数 inputs 可以是字符串列表，其中每个字符串都是不同的输入。反过来，响应是嵌入列表，其中每个嵌入对应于同一位置的输入。

{
    "input": [
        "The ultimate answer to the question of life", 
        "The largest planet in our solar system is Jupiter"
    ]
}

响应如下所示，可从中查看模型的使用统计信息：

{
    "id": "0ab1234c-d5e6-7fgh-i890-j1234k123456",
    "object": "list",
    "data": [
        {
            "index": 0,
            "object": "embedding",
            "embedding": [
                0.017196655,
                // ...
                -0.000687122,
                -0.025054932,
                -0.015777588
            ]
        },
        {
            "index": 1,
            "object": "embedding",
            "embedding": [
                0.017196655,
                // ...
                -0.000687122,
                -0.025054932,
                -0.015777588
            ]
        }
    ],
    "model": "text-embedding-3-small",
    "usage": {
        "prompt_tokens": 19,
        "completion_tokens": 0,
        "total_tokens": 19
    }
}

提示

创建请求批处理时，请考虑每个模型的批处理限制。大多数模型都有 1024 的批限制。

指定嵌入维度

可以指定嵌入的维度数。以下示例代码演示如何创建具有 1024 维度的嵌入内容。请注意，并非所有嵌入模型都支持在请求中指示维度数，在这些情况下会返回 422 错误。

{
    "input": [
        "The ultimate answer to the question of life"
    ],
    "dimensions": 1024
}

创建不同类型的嵌入

某些模型可以为同一输入生成多个嵌入，具体取决于你计划如何使用它们。此功能允许检索 RAG 模式的更准确的嵌入。

以下示例演示如何创建嵌入，这些嵌入用于为要存储在矢量数据库中的文档创建嵌入：

{
    "input": [
        "The answer to the ultimate question of life, the universe, and everything is 42"
    ],
    "input_type": "document"
}

处理查询以检索此类文档时，可以使用以下代码片段为查询创建嵌入，并最大程度地提高检索性能。

{
    "input": [
        "What's the ultimate meaning of life?"
    ],
    "input_type": "query"
}

请注意，并非所有嵌入模型都支持在请求中指示输入类型，在这些情况下会返回 422 错误。默认情况下，返回类型 Text 的嵌入。

通过

如何使用 Azure AI 模型推理生成嵌入内容

先决条件

使用嵌入

创建嵌入

指定嵌入维度

创建不同类型的嵌入

先决条件

使用嵌入

创建嵌入

指定嵌入维度

创建不同类型的嵌入

先决条件

使用嵌入

创建嵌入

指定嵌入维度

创建不同类型的嵌入

先决条件

使用嵌入

创建嵌入

指定嵌入维度

创建不同类型的嵌入

先决条件

使用嵌入

创建嵌入

指定嵌入维度

创建不同类型的嵌入

反馈

其他资源

通过

如何使用 Azure AI 模型推理生成嵌入内容

先决条件

使用嵌入

创建嵌入

指定嵌入维度

创建不同类型的嵌入

先决条件

使用嵌入

创建嵌入

指定嵌入维度

创建不同类型的嵌入

先决条件

使用嵌入

创建嵌入

指定嵌入维度

创建不同类型的嵌入

先决条件

使用嵌入

创建嵌入

指定嵌入维度

创建不同类型的嵌入

先决条件

使用嵌入

创建嵌入

指定嵌入维度

创建不同类型的嵌入

相关内容

反馈

其他资源