Skip to main content
Azure AI Search（前身为 Azure Cognitive Search）是 Microsoft 的云搜索服务，为开发者提供基础设施、API 和工具，用于大规模进行向量、关键词和混合查询的信息检索。 AzureAISearchRetriever 是一个集成模块，可从非结构化查询中返回文档。它基于 BaseRetriever 类构建，面向 Azure AI Search 的 2023-11-01 稳定版 REST API，这意味着它支持向量索引和查询。 本指南将帮助你开始使用 Azure AI Search 检索器。有关所有 AzureAISearchRetriever 功能和配置的详细文档，请参阅 API 参考。 AzureAISearchRetriever 取代了 AzureCognitiveSearchRetriever，后者即将被弃用。我们建议切换到基于最新稳定版搜索 API 的新版本。

​
集成详情

​
设置

要使用此模块，你需要： 然后，你可以将搜索服务名称、索引名称和 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"

​
安装

此检索器位于 langchain-community 包中。我们还需要一些额外的依赖： 
pip install -qU langchain-community
pip install -qU langchain-openai
pip install -qU  azure-search-documents>=11.4
pip install -qU  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"
)

​
使用方法

现在你可以使用它从 Azure AI Search 中检索文档。这是你调用的方法。它将返回与查询相关的所有文档。 
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 Search 向量存储中的嵌入向量。我们还将索引名称设置为 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",
)
接下来，我们将数据加载到新创建的向量存储中。在本示例中，我们加载 state_of_the_union.txt 文件。我们将文本分割为 400 个 token 的块，无重叠。最后，文档作为嵌入向量添加到我们的向量存储中。 
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)
接下来，我们将创建一个检索器。当前的 index_name 变量来自上一步的 langchain-vector-demo。如果你跳过了向量存储创建，请在参数中提供你的索引名称。在此查询中，返回排名第一的结果。 
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-4.1-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()
)

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

​
API 参考

有关所有 AzureAISearchRetriever 功能和配置的详细文档，请参阅 API 参考。
在 GitHub 上编辑此页面或提交问题。
通过 MCP 将这些文档连接到 Claude、VSCode 等以获取实时答案。