Azure AI Search (이전 명칭 Azure Cognitive Search)는 Microsoft 클라우드 검색 서비스로, 개발자에게 대규모 벡터, 키워드 및 하이브리드 쿼리의 정보 검색을 위한 인프라, API 및 도구를 제공합니다. AzureAISearchRetriever는 비구조화된 쿼리에서 문서를 반환하는 통합 모듈입니다. BaseRetriever 클래스를 기반으로 하며 Azure AI Search의 2023-11-01 안정 REST API 버전을 대상으로 하므로 벡터 인덱싱 및 쿼리를 지원합니다. 이 가이드는 Azure AI Search retriever를 시작하는 데 도움을 드립니다. 모든 AzureAISearchRetriever 기능 및 구성에 대한 자세한 문서는 API reference를 참조하세요. AzureAISearchRetriever는 곧 deprecated될 AzureCognitiveSearchRetriever를 대체합니다. 최신 안정 버전의 검색 API를 기반으로 하는 새 버전으로 전환하는 것을 권장합니다.

​
Integration details

​
Setup

이 모듈을 사용하려면 다음이 필요합니다:
  • Azure AI Search 서비스. Azure 평가판에 가입하면 무료로 생성할 수 있습니다. 무료 서비스는 할당량이 낮지만 이 노트북의 코드를 실행하기에는 충분합니다.
  • vector 필드가 있는 기존 인덱스. vector store 모듈을 사용하는 것을 포함하여 여러 가지 생성 방법이 있습니다. 또는 Azure AI Search REST API를 사용해보세요.
  • API key 또는 Azure AD Token.
    • API key는 검색 서비스를 생성할 때 생성됩니다. 인덱스만 쿼리하는 경우 query API key를 사용할 수 있으며, 그렇지 않으면 admin API key를 사용하세요. 자세한 내용은 Find your API keys를 참조하세요.
    • Azure AD Token은 Azure Managed Identity와 함께 사용할 수 있습니다. 자세한 내용은 Connect your app to Azure AI Search using identities를 참조하세요.
그런 다음 검색 서비스 이름, 인덱스 이름 및 API key를 환경 변수로 설정할 수 있습니다(또는 AzureAISearchRetriever에 인수로 전달할 수 있습니다). 검색 인덱스는 검색 가능한 콘텐츠를 제공합니다. API Key 사용 
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 Token 사용 
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 key를 설정할 수도 있습니다: 
os.environ["LANGSMITH_API_KEY"] = getpass.getpass("Enter your LangSmith API key: ")
os.environ["LANGSMITH_TRACING"] = "true"

​
Installation

이 retriever는 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

​
Instantiation

AzureAISearchRetriever의 경우 index_name, content_key 및 검색하려는 결과 수로 설정된 top_k를 제공하세요. top_k를 0(기본값)으로 설정하면 모든 결과가 반환됩니다. 
from langchain_community.retrievers import AzureAISearchRetriever

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

​
Usage

이제 Azure AI Search에서 문서를 검색하는 데 사용할 수 있습니다. 이것이 그렇게 하기 위해 호출할 메서드입니다. 쿼리와 관련된 모든 문서를 반환합니다. 
retriever.invoke("here is my unstructured query string")

​
Example

이 섹션에서는 내장된 샘플 데이터에 대해 retriever를 사용하는 방법을 보여줍니다. 검색 서비스에 이미 vector 인덱스가 있는 경우 이 단계를 건너뛸 수 있습니다. 먼저 endpoint와 key를 제공합니다. 이 단계에서 vector 인덱스를 생성하므로 텍스트의 벡터 표현을 얻기 위해 text embedding 모델을 지정하세요. 이 예제는 text-embedding-ada-002 배포가 있는 Azure OpenAI를 가정합니다. 이 단계에서는 인덱스를 생성하므로 검색 서비스에 대한 admin API key를 사용해야 합니다. 
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의 embedding 모델을 사용하여 문서를 Azure AI Search vector store에 저장된 embedding으로 변환합니다. 또한 인덱스 이름을 langchain-vector-demo로 설정합니다. 이렇게 하면 해당 인덱스 이름과 연결된 새 vector store가 생성됩니다. 
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개의 토큰 청크로 분할합니다. 마지막으로 문서가 embedding으로 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)
다음으로 retriever를 생성합니다. 현재 index_name 변수는 마지막 단계의 langchain-vector-demo입니다. vector store 생성을 건너뛴 경우 매개변수에 인덱스 이름을 제공하세요. 이 쿼리에서는 상위 결과가 반환됩니다. 
retriever = AzureAISearchRetriever(
    content_key="content", top_k=1, index_name="langchain-vector-demo"
)
이제 업로드한 문서에서 쿼리와 관련된 데이터를 검색할 수 있습니다. 
retriever.invoke("does the president have a plan for covid-19?")

​
Use within a chain

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()
)

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

​
API reference

모든 AzureAISearchRetriever 기능 및 구성에 대한 자세한 문서는 API reference를 참조하세요.
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.
⌘I