AzureAISearchRetriever

Azure AI 搜索（以前称为Azure Cognitive Search）是一项 Microsoft 云搜索服务，可为开发人员提供基础结构、API 和工具，用于大规模检索向量、关键字和混合查询的信息。

AzureAISearchRetriever是一个集成模块，用于从非结构化查询返回文档。它基于 BaseRetriever 类，面向 Azure AI 搜索的 2023-11-01 稳定 REST API 版本，这意味着它支持矢量索引和查询。

本指南将帮助您开始使用 Azure AI 搜索检索器。有关所有AzureAISearchRetriever功能和配置可参考 API 参考。

AzureAISearchRetriever取代AzureCognitiveSearchRetriever，该版本即将被弃用。我们建议切换到基于搜索 API 的最新稳定版本的较新版本。

集成详细信息

Retriever	自托管	云产品	包
AzureAISearchRetriever	❌	✅	langchain_community

设置

要使用该模块，您需要：

Azure AI 搜索服务。如果您注册 Azure 试用版，则可以免费创建一个。免费服务的配额较低，但足以在此笔记本中运行代码。
具有向量字段的现有索引。有几种方法可以创建一个，包括使用 vector store 模块。或者，尝试 Azure AI 搜索 REST API。
API 密钥或 Azure AD 令牌。
- API 密钥是在创建搜索服务时生成的。如果您只是查询索引，则可以使用查询 API 密钥，否则请使用管理员 API 密钥。有关详细信息，请参阅查找 API 密钥。
- Azure AD 令牌可与 Azure 托管标识一起使用。有关详细信息，请参阅使用标识将应用连接到 Azure AI 搜索。

然后，我们可以将搜索服务名称、索引名称和 API 密钥设置为环境变量（或者，您可以将它们作为参数传递给AzureAISearchRetriever).搜索索引提供可搜索的内容。

使用 API 密钥

import os

os.environ["AZURE_AI_SEARCH_SERVICE_NAME"] = "<YOUR_SEARCH_SERVICE_NAME>"
os.environ["AZURE_AI_SEARCH_INDEX_NAME"] = "<YOUR_SEARCH_INDEX_NAME>"
os.environ["AZURE_AI_SEARCH_API_KEY"] = "<YOUR_API_KEY>"

使用 Azure AD 令牌

import os

os.environ["AZURE_AI_SEARCH_SERVICE_NAME"] = "<YOUR_SEARCH_SERVICE_NAME>"
os.environ["AZURE_AI_SEARCH_INDEX_NAME"] = "<YOUR_SEARCH_INDEX_NAME>"
os.environ["AZURE_AI_SEARCH_AD_TOKEN"] = "<YOUR_AZURE_AD_TOKEN>"

如果您想从单个查询中获得自动跟踪，您还可以通过取消下面的注释来设置您的 LangSmith API 密钥：

# os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")
# os.environ["LANGSMITH_TRACING"] = "true"

安装

这只Retriever生活在langchain-community包。我们还需要一些额外的依赖项：

%pip install --upgrade --quiet langchain-community
%pip install --upgrade --quiet langchain-openai
%pip install --upgrade --quiet  azure-search-documents>=11.4
%pip install --upgrade --quiet  azure-identity

实例

为AzureAISearchRetriever，请提供index_name,content_key和top_k设置为要检索的结果数。设置top_k为零（默认值）返回所有结果。

from langchain_community.retrievers import AzureAISearchRetriever

retriever = AzureAISearchRetriever(
    content_key="content", top_k=1, index_name="langchain-vector-demo"
)

API 参考：AzureAISearchRetriever

用法

现在，您可以使用它从 Azure AI 搜索中检索文档。这是您为此而调用的方法。它将返回与查询相关的所有文档。

retriever.invoke("here is my unstructured query string")

例

本节演示如何对内置示例数据使用检索器。如果您的搜索服务上已有向量索引，则可以跳过此步骤。

首先提供终端节点和密钥。由于我们在此步骤中创建向量索引，因此请指定文本嵌入模型以获取文本的向量表示形式。此示例假定 Azure OpenAI 具有 text-embedding-ada-002 部署。由于此步骤会创建索引，因此请务必为搜索服务使用管理员 API 密钥。

import os

from langchain_community.document_loaders import DirectoryLoader, TextLoader
from langchain_community.retrievers import AzureAISearchRetriever
from langchain_community.vectorstores import AzureSearch
from langchain_openai import AzureOpenAIEmbeddings, OpenAIEmbeddings
from langchain_text_splitters import TokenTextSplitter

os.environ["AZURE_AI_SEARCH_SERVICE_NAME"] = "<YOUR_SEARCH_SERVICE_NAME>"
os.environ["AZURE_AI_SEARCH_INDEX_NAME"] = "langchain-vector-demo"
os.environ["AZURE_AI_SEARCH_API_KEY"] = "<YOUR_SEARCH_SERVICE_ADMIN_API_KEY>"
azure_endpoint: str = "<YOUR_AZURE_OPENAI_ENDPOINT>"
azure_openai_api_key: str = "<YOUR_AZURE_OPENAI_API_KEY>"
azure_openai_api_version: str = "2023-05-15"
azure_deployment: str = "text-embedding-ada-002"

我们将使用 Azure OpenAI 中的嵌入模型将文档转换为存储在 Azure AI 搜索矢量存储中的嵌入。我们还会将索引名称设置为langchain-vector-demo.这将创建一个与该索引名称关联的新向量存储。

embeddings = AzureOpenAIEmbeddings(
    model=azure_deployment,
    azure_endpoint=azure_endpoint,
    openai_api_key=azure_openai_api_key,
)

vector_store: AzureSearch = AzureSearch(
    embedding_function=embeddings.embed_query,
    azure_search_endpoint=os.getenv("AZURE_AI_SEARCH_SERVICE_NAME"),
    azure_search_key=os.getenv("AZURE_AI_SEARCH_API_KEY"),
    index_name="langchain-vector-demo",
)

接下来，我们将数据加载到新创建的 vector store 中。在此示例中，我们加载state_of_the_union.txt文件。我们将文本拆分为 400 个没有重叠的标记块。最后，文档作为 emedding 添加到我们的 vector store 中。

from langchain_community.document_loaders import TextLoader
from langchain_text_splitters import CharacterTextSplitter

loader = TextLoader("../../how_to/state_of_the_union.txt", encoding="utf-8")

documents = loader.load()
text_splitter = CharacterTextSplitter(chunk_size=400, chunk_overlap=0)
docs = text_splitter.split_documents(documents)

vector_store.add_documents(documents=docs)

API 参考：TextLoader | CharacterTextSplitter（字符文本拆分器）

接下来，我们将创建一个 retriever。当前的index_namevariable 为langchain-vector-demo从最后一步开始。如果您跳过了矢量存储创建，请在参数中提供索引名称。在此查询中，将返回 top 结果。

retriever = AzureAISearchRetriever(
    content_key="content", top_k=1, index_name="langchain-vector-demo"
)

现在，我们可以从上传的文档中检索与我们的查询相关的数据。

retriever.invoke("does the president have a plan for covid-19?")

在链内使用

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain_openai import ChatOpenAI

prompt = ChatPromptTemplate.from_template(
    """Answer the question based only on the context provided.

Context: {context}

Question: {question}"""
)

llm = ChatOpenAI(model="gpt-4o-mini")


def format_docs(docs):
    return "\n\n".join(doc.page_content for doc in docs)


chain = (
    {"context": retriever | format_docs, "question": RunnablePassthrough()}
    | prompt
    | llm
    | StrOutputParser()
)

API 参考：StrOutputParser | ChatPromptTemplate 模板 | RunnablePassthrough | 聊天OpenAI

chain.invoke("does the president have a plan for covid-19?")

API 参考

有关所有AzureAISearchRetriever功能和配置可参考 API 参考。

Retriever概念指南
Retriever操作指南