AzureOpenAIEmbeddings 集成 - Docs by LangChain中文

Azure OpenAI 是一项云服务，旨在帮助你利用来自 OpenAI、Meta 等供应商的多样化预构建和精选模型，快速开发生成式 AI 体验。 LangChain.js 支持通过 OpenAI SDK 中新的 Azure 集成，与 Azure OpenAI 进行集成。你可以在此页面了解有关 Azure OpenAI 及其与 OpenAI API 区别的更多信息。如果你没有 Azure 账户，可以创建一个免费账户来开始使用。这将帮助你使用 LangChain 开始使用 AzureOpenAIEmbeddings 嵌入模型。有关 AzureOpenAIEmbeddings 功能和配置选项的详细文档，请参阅 API 参考。

此前，LangChain.js 使用专用的 Azure OpenAI SDK 来支持与 Azure OpenAI 的集成。该 SDK 现已弃用，取而代之的是 OpenAI SDK 中新的 Azure 集成，它允许你在最新 OpenAI 模型和功能发布的同一天就进行访问，并支持在 OpenAI API 和 Azure OpenAI 之间无缝切换。如果你正在使用已弃用的 SDK 与 Azure OpenAI 集成，请参阅迁移指南以更新到新的 API。

概述

集成详情

类	包	本地	Py 支持	下载量	版本
`AzureOpenAIEmbeddings`	`@langchain/openai`	❌	✅

设置

要访问 Azure OpenAI 嵌入模型，你需要创建一个 Azure 账户，获取 API 密钥，并安装 @langchain/openai 集成包。

凭证

你需要部署一个 Azure OpenAI 实例。你可以按照本指南在 Azure Portal 上部署一个版本。一旦你的实例运行起来，请确保你拥有实例名称和密钥。你可以在 Azure Portal 中实例的“Keys and Endpoint”部分找到密钥。如果你使用的是 Node.js，可以定义以下环境变量来使用该服务：

AZURE_OPENAI_API_INSTANCE_NAME=<你的实例名称>
AZURE_OPENAI_API_EMBEDDINGS_DEPLOYMENT_NAME=<你的嵌入部署名称>
AZURE_OPENAI_API_KEY=<你的密钥>
AZURE_OPENAI_API_VERSION="2024-02-01"

如果你希望自动追踪你的模型调用，也可以取消下面注释来设置你的 LangSmith API 密钥：

# export LANGSMITH_TRACING="true"
# export LANGSMITH_API_KEY="your-api-key"

安装

LangChain 的 AzureOpenAIEmbeddings 集成位于 @langchain/openai 包中：

npm install @langchain/openai @langchain/core

你可以在 Azure OpenAI 文档中找到支持的 API 版本列表。

如果未定义 AZURE_OPENAI_API_EMBEDDINGS_DEPLOYMENT_NAME，部署名称将回退到 AZURE_OPENAI_API_DEPLOYMENT_NAME 的值。AzureOpenAIEmbeddings 构造函数中的 azureOpenAIApiEmbeddingsDeploymentName 参数也是如此，如果未定义，它将回退到 azureOpenAIApiDeploymentName 的值。

实例化

现在我们可以实例化我们的模型对象并嵌入文本：

import { AzureOpenAIEmbeddings } from "@langchain/openai";

const embeddings = new AzureOpenAIEmbeddings({
  azureOpenAIApiKey: "<your_key>", // 在 Node.js 中，默认为 process.env.AZURE_OPENAI_API_KEY
  azureOpenAIApiInstanceName: "<your_instance_name>", // 在 Node.js 中，默认为 process.env.AZURE_OPENAI_API_INSTANCE_NAME
  azureOpenAIApiEmbeddingsDeploymentName: "<your_embeddings_deployment_name>", // 在 Node.js 中，默认为 process.env.AZURE_OPENAI_API_EMBEDDINGS_DEPLOYMENT_NAME
  azureOpenAIApiVersion: "<api_version>", // 在 Node.js 中，默认为 process.env.AZURE_OPENAI_API_VERSION
  maxRetries: 1,
});

索引和检索

嵌入模型通常用于检索增强生成 (RAG) 流程，既作为索引数据的一部分，也用于后续检索。有关更详细的说明，请参阅我们位于学习标签页下的 RAG 教程。下面，了解如何使用我们上面初始化的 embeddings 对象来索引和检索数据。在此示例中，我们将使用演示版 MemoryVectorStore 索引和检索一个样本文档。

// 使用示例文本创建一个向量存储
import { MemoryVectorStore } from "@langchain/classic/vectorstores/memory";

const text = "LangChain 是用于构建上下文感知推理应用程序的框架";

const vectorstore = await MemoryVectorStore.fromDocuments(
  [{ pageContent: text, metadata: {} }],
  embeddings,
);

// 将向量存储用作检索器，返回单个文档
const retriever = vectorstore.asRetriever(1);

// 检索最相似的文本
const retrievedDocuments = await retriever.invoke("What is LangChain?");

retrievedDocuments[0].pageContent;

LangChain 是用于构建上下文感知推理应用程序的框架

直接使用

在底层，向量存储和检索器的实现会分别调用 embeddings.embedDocument(...) 和 embeddings.embedQuery(...)，为 fromDocuments 和检索器的 invoke 操作中使用的文本创建嵌入。你可以直接调用这些方法，为你自己的用例获取嵌入。

嵌入单个文本

你可以使用 embedQuery 嵌入查询以进行搜索。这会生成特定于查询的向量表示：

const singleVector = await embeddings.embedQuery(text);

console.log(singleVector.slice(0, 100));

[
   -0.024253517, -0.0054218727,   0.048715446,   0.020580322,    0.03180832,
   0.0028770117,  -0.012367731,   0.037383243,  -0.054915592,   0.032225136,
     0.00825818,  -0.023888804,   -0.01184671,   0.012257014,   0.016294925,
    0.009254632,  0.0051353113,  -0.008889917,   0.016855022,    0.04207243,
  0.00082589936,  -0.011664353,    0.00818654,   0.029020859,  -0.012335167,
   -0.019603407,  0.0013945447,    0.05538451,  -0.011625277,  -0.008153976,
    0.038607642,   -0.03811267, -0.0074440846,   0.047647353,   -0.00927417,
    0.024201415, -0.0069230637,  -0.008538228,   0.003910912,   0.052805457,
   -0.023159374,  0.0014352495,  -0.038659744,   0.017141584,   0.005587948,
    0.007971618,  -0.016920151,    0.06658646, -0.0016916894,   0.045667473,
   -0.042202685,   -0.03983204,   -0.04160351,  -0.011729481,  -0.055905532,
    0.012543576,  0.0038848612,   0.007919516,   0.010915386,  0.0033117384,
   -0.007548289,  -0.030427614,  -0.041890074,   0.036002535,  -0.023771575,
   -0.008792226,  -0.049444873,   0.016490309, -0.0060568666,   0.040196754,
    0.014106638,  -0.014575557, -0.0017356506,  -0.011234511,  -0.012517525,
    0.008362384,    0.01253055,   0.036158845,   0.008297256, -0.0010908874,
   -0.014888169,  -0.020489143,   0.018965157,  -0.057937514, -0.0037122732,
    0.004402626,   -0.00840146,   0.042984217,   -0.04936672,   -0.03714878,
    0.004969236,    0.03707063,   0.015396165,   -0.02055427,    0.01988997,
    0.030219207,  -0.021257648,    0.01340326,   0.003692735,   0.012595678
]

嵌入多个文本

你可以使用 embedDocuments 嵌入多个文本以进行索引。此方法内部使用的逻辑可能（但不必）与嵌入查询不同：

const text2 = "LangGraph 是一个用于构建有状态、多角色 LLM 应用程序的库";

const vectors = await embeddings.embedDocuments([text, text2]);

console.log(vectors[0].slice(0, 100));
console.log(vectors[1].slice(0, 100));

[
   -0.024253517, -0.0054218727,   0.048715446,   0.020580322,    0.03180832,
   0.0028770117,  -0.012367731,   0.037383243,  -0.054915592,   0.032225136,
     0.00825818,  -0.023888804,   -0.01184671,   0.012257014,   0.016294925,
    0.009254632,  0.0051353113,  -0.008889917,   0.016855022,    0.04207243,
  0.00082589936,  -0.011664353,    0.00818654,   0.029020859,  -0.012335167,
   -0.019603407,  0.0013945447,    0.05538451,  -0.011625277,  -0.008153976,
    0.038607642,   -0.03811267, -0.0074440846,   0.047647353,   -0.00927417,
    0.024201415, -0.0069230637,  -0.008538228,   0.003910912,   0.052805457,
   -0.023159374,  0.0014352495,  -0.038659744,   0.017141584,   0.005587948,
    0.007971618,  -0.016920151,    0.06658646, -0.0016916894,   0.045667473,
   -0.042202685,   -0.03983204,   -0.04160351,  -0.011729481,  -0.055905532,
    0.012543576,  0.0038848612,   0.007919516,   0.010915386,  0.0033117384,
   -0.007548289,  -0.030427614,  -0.041890074,   0.036002535,  -0.023771575,
   -0.008792226,  -0.049444873,   0.016490309, -0.0060568666,   0.040196754,
    0.014106638,  -0.014575557, -0.0017356506,  -0.011234511,  -0.012517525,
    0.008362384,    0.01253055,   0.036158845,   0.008297256, -0.0010908874,
   -0.014888169,  -0.020489143,   0.018965157,  -0.057937514, -0.0037122732,
    0.004402626,   -0.00840146,   0.042984217,   -0.04936672,   -0.03714878,
    0.004969236,    0.03707063,   0.015396165,   -0.02055427,    0.01988997,
    0.030219207,  -0.021257648,    0.01340326,   0.003692735,   0.012595678
]
[
   -0.033366997,   0.010419146,  0.0118083665,  -0.040441725, 0.0020355924,
   -0.015808804,  -0.023629595, -0.0066180876,  -0.040004376,  0.020053642,
  -0.0010797002,   -0.03900105,  -0.009956073,  0.0027896944,  0.003305828,
   -0.034010153,   0.009833873,  0.0061164247,   0.022536227,  0.029147884,
    0.017789727,    0.03182342,   0.010869357,   0.031849146, -0.028093107,
    0.008283865, -0.0145610785,    0.01645196,  -0.029430874,  -0.02508313,
    0.046178687,   -0.01722375,  -0.010046115,   0.013101112, 0.0044538635,
     0.02197025,    0.03985002,   0.007955855,  0.0008819293,  0.012657333,
    0.014368132,  -0.014007963,   -0.03722594,   0.031617608, -0.011570398,
    0.039052505,  0.0020018267,   0.023706773, -0.0046950476,  0.056083307,
    -0.08412496,  -0.043425974,  -0.015512952,   0.015950298,  -0.03624834,
  -0.0053317733,  -0.037251666,  0.0046339477,    0.04193385,  0.023475237,
   -0.021378545,   0.013699248,  -0.026009277,   0.050757967,   -0.0494202,
   0.0007874656,   -0.07208506,   0.015885983,  -0.003259199,  0.015127057,
   0.0068946453,  -0.035373647,  -0.005875241, -0.0032238255,  -0.04185667,
   -0.022047428,  0.0014326327, -0.0070940237, -0.0027864785, -0.016271876,
    0.005097021,   0.034473225,   0.012361481,  -0.026498076, 0.0067274245,
   -0.026330855,  -0.006132504,   0.008180959,  -0.049368747, -0.032337945,
    0.011049441,    0.00186194,  -0.012097787,    0.01930758,   0.07059293,
    0.029713862,    0.04337452, -0.0048461896,  -0.019976463,  0.011473924
]

使用 Azure 托管标识

如果你正在使用 Azure 托管标识，可以像这样配置凭据：

import {
  DefaultAzureCredential,
  getBearerTokenProvider,
} from "@azure/identity";
import { AzureOpenAIEmbeddings } from "@langchain/openai";

const credentials = new DefaultAzureCredential();
const azureADTokenProvider = getBearerTokenProvider(
  credentials,
  "https://cognitiveservices.azure.com/.default"
);

const modelWithManagedIdentity = new AzureOpenAIEmbeddings({
  azureADTokenProvider,
  azureOpenAIApiInstanceName: "<你的实例名称>",
  azureOpenAIApiEmbeddingsDeploymentName: "<你的嵌入部署名称>",
  azureOpenAIApiVersion: "<api_version>",
});

使用不同的域

如果你的实例托管在默认 openai.azure.com 之外的域下，你需要使用备用的 AZURE_OPENAI_BASE_PATH 环境变量。例如，下面是如何连接到域 https://westeurope.api.microsoft.com/openai/deployments/{DEPLOYMENT_NAME} 的方法：

import { AzureOpenAIEmbeddings } from "@langchain/openai";

const embeddingsDifferentDomain = new AzureOpenAIEmbeddings({
  azureOpenAIApiKey: "<你的密钥>", // 在 Node.js 中，默认为 process.env.AZURE_OPENAI_API_KEY
  azureOpenAIApiEmbeddingsDeploymentName: "<你的嵌入部署名称>", // 在 Node.js 中，默认为 process.env.AZURE_OPENAI_API_EMBEDDINGS_DEPLOYMENT_NAME
  azureOpenAIApiVersion: "<api_version>", // 在 Node.js 中，默认为 process.env.AZURE_OPENAI_API_VERSION
  azureOpenAIBasePath:
    "https://westeurope.api.microsoft.com/openai/deployments", // 在 Node.js 中，默认为 process.env.AZURE_OPENAI_BASE_PATH
});

自定义标头

你可以通过传入一个 configuration 字段来指定自定义标头：

import { AzureOpenAIEmbeddings } from "@langchain/openai";

const embeddingsWithCustomHeaders = new AzureOpenAIEmbeddings({
  azureOpenAIApiKey: "<你的密钥>",
  azureOpenAIApiInstanceName: "<你的实例名称>",
  azureOpenAIApiEmbeddingsDeploymentName: "<你的嵌入部署名称>",
  azureOpenAIApiVersion: "<api_version>",
  configuration: {
    defaultHeaders: {
      "x-custom-header": `某个值`,
    },
  },
});

configuration 字段也接受官方 SDK 所接受的其他 ClientOptions 参数。 注意： 目前无法以这种方式覆盖特定的标头 api-key，它将从 azureOpenAIApiKey 获取值。

从 Azure OpenAI SDK 迁移

如果你正在使用已弃用的 Azure OpenAI SDK 配合 @langchain/azure-openai 包，你可以按照以下步骤更新代码以使用新的 Azure 集成：

安装新的 @langchain/openai 包并移除先前的 @langchain/azure-openai 包：
npm
```
npm install @langchain/openai
npm uninstall @langchain/azure-openai
```
更新你的导入，使用来自 @langchain/openai 包的新 AzureOpenAIEmbeddings 类：
```
import { AzureOpenAIEmbeddings } from "@langchain/openai";
```
更新你的代码以使用新的 AzureOpenAIEmbeddings 类并传入所需的参数：
```
const model = new AzureOpenAIEmbeddings({
  azureOpenAIApiKey: "<你的密钥>",
  azureOpenAIApiInstanceName: "<你的实例名称>",
  azureOpenAIApiEmbeddingsDeploymentName:
    "<你的嵌入部署名称>",
  azureOpenAIApiVersion: "<api_version>",
});
```
请注意，构造函数现在需要 azureOpenAIApiInstanceName 参数而不是 azureOpenAIEndpoint 参数，并添加了 azureOpenAIApiVersion 参数以指定 API 版本。
- 如果你之前使用的是 Azure 托管标识，现在你需要使用构造函数的 azureADTokenProvider 参数而不是 credentials，更多细节请参阅 Azure 托管标识部分。
- 如果你之前使用的是环境变量，现在需要设置 AZURE_OPENAI_API_INSTANCE_NAME 环境变量而不是 AZURE_OPENAI_API_ENDPOINT，并添加 AZURE_OPENAI_API_VERSION 环境变量以指定 API 版本。

API 参考

有关所有 AzureOpenAIEmbeddings 功能和配置的详细文档，请前往 API 参考。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​概述

​集成详情

​设置

​凭证

​安装

​实例化

​索引和检索

​直接使用

​嵌入单个文本

​嵌入多个文本

​使用 Azure 托管标识

​使用不同的域

​自定义标头

​从 Azure OpenAI SDK 迁移

​API 参考

概述

集成详情

设置

凭证

安装

实例化

索引和检索

直接使用

嵌入单个文本

嵌入多个文本

使用 Azure 托管标识

使用不同的域

自定义标头

从 Azure OpenAI SDK 迁移

API 参考