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

本文介绍如何将嵌入 API 与 Azure AI Foundry 模型中部署的模型配合使用。

先决条件

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

• Azure 订阅。 如果你正在使用 GitHub 模型，则可以升级体验并在此过程中创建 Azure 订阅。 如果是这种情况，请阅读 从 GitHub 模型升级到 Azure AI Foundry 模型 。

• Azure AI Foundry 资源（以前称为 Azure AI 服务）。 有关详细信息，请参阅 创建 Azure AI Foundry 资源。

• 终结点 URL 和密钥。

  

• 请使用以下命令安装适用于 Python 的 Azure AI 推理包：

  pip install -U azure-ai-inference
  

• 嵌入模型部署。 如果您没有，请阅读 添加和配置 Foundry 模型 来将嵌入模型添加到您的资源中。

使用嵌入

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

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

model = EmbeddingsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    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.identity import DefaultAzureCredential

model = EmbeddingsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    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 维度的嵌入内容。 请注意，并非所有嵌入模型都支持在请求中指示维度数，在这些情况下会返回 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 的嵌入。

本文介绍如何将嵌入 API 与 Azure AI Foundry 模型中部署的模型配合使用。

先决条件

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

• Azure 订阅。 如果你正在使用 GitHub 模型，则可以升级体验并在此过程中创建 Azure 订阅。 如果是这种情况，请阅读 从 GitHub 模型升级到 Azure AI Foundry 模型 。

• Azure AI Foundry 资源（以前称为 Azure AI 服务）。 有关详细信息，请参阅 创建 Azure AI Foundry 资源。

• 终结点 URL 和密钥。

  

• 使用以下命令安装适用于 JavaScript 的 Azure 推理库：

  npm install @azure-rest/ai-inference
  npm install @azure/core-auth
  npm install @azure/identity
  

  如果使用 Node.js，则可以在 package.json中配置依赖项：

  package.json

  {
    "name": "main_app",
    "version": "1.0.0",
    "description": "",
    "main": "app.js",
    "type": "module",
    "dependencies": {
      "@azure-rest/ai-inference": "1.0.0-beta.6",
      "@azure/core-auth": "1.9.0",
      "@azure/core-sse": "2.2.0",
      "@azure/identity": "4.8.0"
    }
  }
  

• 导入以下内容：

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

• 嵌入模型部署。 如果您没有，请阅读 添加和配置 Foundry 模型 来将嵌入模型添加到您的资源中。

使用嵌入

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

const client = ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new AzureKeyCredential(process.env.AZURE_INFERENCE_CREDENTIAL)
);

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

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential()
    clientOptions,
);

创建嵌入

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

var response = await client.path("/embeddings").post({
    body: {
        model: "text-embedding-3-small",
        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: {
        model: "text-embedding-3-small",
        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 维度的嵌入内容。 请注意，并非所有嵌入模型都支持在请求中指示维度数，在这些情况下会返回 422 错误。

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

创建不同类型的嵌入

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

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

var response = await client.path("/embeddings").post({
    body: {
        model: "text-embedding-3-small",
        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: {
        model: "text-embedding-3-small",
        input: ["What's the ultimate meaning of life?"],
        input_type: "query",
    }
});

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

本文介绍如何将嵌入 API 与 Azure AI Foundry 模型中部署的模型配合使用。

先决条件

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

• Azure 订阅。 如果你正在使用 GitHub 模型，则可以升级体验并在此过程中创建 Azure 订阅。 如果是这种情况，请阅读 从 GitHub 模型升级到 Azure AI Foundry 模型 。

• Azure AI Foundry 资源（以前称为 Azure AI 服务）。 有关详细信息，请参阅 创建 Azure AI Foundry 资源。

• 终结点 URL 和密钥。

  

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

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

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

  <dependency>
      <groupId>com.azure</groupId>
      <artifactId>azure-identity</artifactId>
      <version>1.15.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.ChatCompletionsClient;
  import com.azure.ai.inference.ChatCompletionsClientBuilder;
  import com.azure.ai.inference.models.EmbeddingsResult;
  import com.azure.ai.inference.models.EmbeddingItem;
  import com.azure.ai.inference.models.ChatCompletions;
  import com.azure.core.credential.AzureKeyCredential;
  import com.azure.core.util.Configuration;
  
  import java.util.ArrayList;
  import java.util.List;
  

• 导入下列命名空间：

  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;
  

• 嵌入模型部署。 如果您没有，请阅读 添加和配置 Foundry 模型 来将嵌入模型添加到您的资源中。

使用嵌入

首先，创建客户端以使用模型。 以下代码使用存储在环境变量中的终结点 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 维度的嵌入内容。 请注意，并非所有嵌入模型都支持在请求中指示维度数，在这些情况下会返回 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 的嵌入。

本文介绍如何将嵌入 API 与 Azure AI Foundry 模型中部署的模型配合使用。

先决条件

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

• Azure 订阅。 如果你正在使用 GitHub 模型，则可以升级体验并在此过程中创建 Azure 订阅。 如果是这种情况，请阅读 从 GitHub 模型升级到 Azure AI Foundry 模型 。

• Azure AI Foundry 资源（以前称为 Azure AI 服务）。 有关详细信息，请参阅 创建 Azure AI Foundry 资源。

• 终结点 URL 和密钥。

  

• 请使用以下命令安装 Azure AI 推理包：

  dotnet add package Azure.AI.Inference --prerelease
  

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

  dotnet add package Azure.Identity
  

• 嵌入模型部署。 如果您没有，请阅读 添加和配置 Foundry 模型 来将嵌入模型添加到您的资源中。

使用嵌入

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

EmbeddingsClient client = new EmbeddingsClient(
    new Uri(Environment.GetEnvironmentVariable("AZURE_INFERENCE_ENDPOINT")),
    new AzureKeyCredential(Environment.GetEnvironmentVariable("AZURE_INFERENCE_CREDENTIAL"))
);

如果将资源配置为具有 Microsoft Entra ID 支持，则可以使用以下代码片段创建客户端。 请注意，此处 includeInteractiveCredentials 的设置为 true 仅出于演示用途，因此可以通过网页浏览器进行身份认证。 在生产工作负荷上，应删除此类参数。

TokenCredential credential = new DefaultAzureCredential(includeInteractiveCredentials: true);
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });

clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

client = new EmbeddingsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    clientOptions,
);

创建嵌入

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

EmbeddingsOptions requestOptions = new EmbeddingsOptions()
{
    Input = {
        "The ultimate answer to the question of life"
    },
    Model = "text-embedding-3-small"
};

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"
    },
    Model = "text-embedding-3-small"
};

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

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

指定嵌入维度

可以指定嵌入的维度数。 以下示例代码演示如何创建具有 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 = input,
    InputType = EmbeddingInputType.DOCUMENT, 
    Model = "text-embedding-3-small"
};

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

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

var input = new List<string> { 
    "What's the ultimate meaning of life?"
};
var requestOptions = new EmbeddingsOptions()
{
    Input = input,
    InputType = EmbeddingInputType.QUERY,
    Model = "text-embedding-3-small"
};

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

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

本文介绍如何将嵌入 API 与 Azure AI Foundry 模型中部署的模型配合使用。

先决条件

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

• Azure 订阅。 如果你正在使用 GitHub 模型，则可以升级体验并在此过程中创建 Azure 订阅。 如果是这种情况，请阅读 从 GitHub 模型升级到 Azure AI Foundry 模型 。

• Azure AI Foundry 资源（以前称为 Azure AI 服务）。 有关详细信息，请参阅 创建 Azure AI Foundry 资源。

• 终结点 URL 和密钥。

  

• 嵌入模型部署。 如果您没有，请阅读 添加和配置 Foundry 模型 来将嵌入模型添加到您的资源中。

使用嵌入

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

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 格式传递令牌。Bearer <token> 使用范围 https://cognitiveservices.azure.com/.default。

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

使用 Microsoft Entra ID 可能需要资源中的其他配置才能授予访问权限。 了解如何 使用 Microsoft Entra ID 配置无密钥身份验证。

创建嵌入

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

{
    "model": "text-embedding-3-small",
    "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 可以是字符串列表，其中每个字符串都是不同的输入。 反过来，响应是嵌入列表，其中每个嵌入对应于同一位置的输入。

{
    "model": "text-embedding-3-small",
    "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 维度的嵌入内容。 请注意，并非所有嵌入模型都支持在请求中指示维度数，在这些情况下会返回 422 错误。

{
    "model": "text-embedding-3-small",
    "input": [
        "The ultimate answer to the question of life"
    ],
    "dimensions": 1024
}

创建不同类型的嵌入

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

以下示例演示如何创建嵌入，这些嵌入用于为要存储在矢量数据库中的文档创建嵌入。 由于 text-embedding-3-small 不支持此功能，我们在以下示例中使用来自 Cohere 的嵌入模型：

{
    "model": "cohere-embed-v3-english",
    "input": [
        "The answer to the ultimate question of life, the universe, and everything is 42"
    ],
    "input_type": "document"
}

处理查询以检索此类文档时，可以使用以下代码片段为查询创建嵌入，并最大程度地提高检索性能。 由于 text-embedding-3-small 不支持此功能，我们在以下示例中使用来自 Cohere 的嵌入模型：

{
    "model": "cohere-embed-v3-english",
    "input": [
        "What's the ultimate meaning of life?"
    ],
    "input_type": "query"
}

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