Python용 Azure Cognitive Search 클라이언트 라이브러리 - 버전 11.4.0

  • 아티클

Azure Cognitive Search는 개발자에게 웹, 모바일 및 엔터프라이즈 애플리케이션의 프라이빗, 이기종 콘텐츠에 대한 풍부한 검색 환경을 추가하기 위한 API 및 도구를 제공하는 SaaS(Search-as-a-Service) 클라우드 솔루션입니다.

Azure Cognitive Search 서비스는 다음 애플리케이션 시나리오에 적합합니다.

  • 다양한 콘텐츠 형식을 검색 가능한 단일 인덱스로 통합합니다. 인덱스 채우기를 위해 콘텐츠가 포함된 JSON 문서를 푸시하거나 데이터가 이미 Azure에 있는 경우 데이터를 자동으로 끌어올 인덱서를 만들 수 있습니다.
  • 인덱서에 기술 세트를 연결하여 이미지 및 큰 텍스트 문서에서 검색 가능한 콘텐츠를 만듭니다. 기술 세트는 기본 제공 OCR, 엔터티 인식, 핵심 구 추출, 언어 감지, 텍스트 번역 및 감정 분석을 위해 Cognitive Services의 AI를 활용합니다. 사용자 지정 기술을 추가하여 데이터 수집 중에 콘텐츠의 외부 처리를 통합할 수도 있습니다.
  • 검색 클라이언트 애플리케이션에서 상용 웹 검색 엔진과 유사한 쿼리 논리 및 사용자 환경을 구현합니다.

Azure.Search.Documents 클라이언트 라이브러리를 사용하여 다음을 수행합니다.

  • 유사 항목 검색, 와일드카드 검색, 정규식을 포함하는 단순하고 고급 쿼리 양식에 대한 쿼리를 제출합니다.
  • 패싯 탐색, 지리 공간적 검색 또는 필터 조건에 따라 결과의 범위를 좁히기 위해 필터링된 쿼리를 구현합니다.
  • 검색 인덱스를 만들고 관리합니다.
  • 검색 인덱스에서 문서를 업로드하고 업데이트합니다.
  • Azure에서 인덱스로 데이터를 끌어오는 인덱서를 만들고 관리합니다.
  • 데이터 수집에 AI 보강을 추가하는 기술 세트를 만들고 관리합니다.
  • 고급 텍스트 분석 또는 다국어 콘텐츠를 위한 분석기를 만들고 관리합니다.
  • 점수 매기기 프로필을 통해 결과를 최적화하여 비즈니스 논리 또는 새로 고침을 고려합니다.

소스 코드 | 패키지(PyPI) | 패키지(Conda) | API 참조 설명서 | 제품 설명서 | 샘플

시작

패키지 설치

pip를 사용하여 Python용 Azure Cognitive Search 클라이언트 라이브러리를 설치합니다.

pip install azure-search-documents

사전 요구 사항

새 검색 서비스를 만들려면 Azure Portal, Azure PowerShell 또는 Azure CLI를 사용할 수 있습니다.

az search service create --name <mysearch> --resource-group <mysearch-rg> --sku free --location westus

사용 가능한 옵션에 대한 자세한 내용은 가격 책정 계층 선택을 참조하세요.

클라이언트 인증

Search Service 상호 작용하려면 적절한 클라이언트 클래스 SearchClient 의 instance 만들어야 합니다. 즉, 인덱싱된 문서 검색, SearchIndexClient 인덱스 관리 또는 SearchIndexerClient 데이터 원본 크롤링 및 검색 문서를 인덱스에 로드하기 위한 것입니다. 클라이언트 개체를 인스턴스화하려면 엔드포인트 와 API 키가 필요합니다. Search Service 지원되는 인증 방법에 대한 자세한 내용은 설명서를 참조하세요.

API 키 가져오기

Azure Portal의 Search Service 엔드포인트 및 API 키를 가져올 수 있습니다. API 키를 가져오는 방법에 대한 지침은 설명서를 참조하세요.

또는 다음 Azure CLI 명령을 사용하여 Search Service API 키를 검색할 수 있습니다.

az search admin-key show --service-name <mysearch> --resource-group <mysearch-rg>

검색 서비스에 액세스하는 데 사용되는 키에는 admin(읽기-쓰기) 및 쿼리(읽기 전용) 키의 두 가지 유형이 있습니다. 클라이언트 앱에서 액세스 및 작업을 제한하는 것은 서비스에서 검색 자산을 보호하는 데 있어 필수적입니다. 클라이언트 앱에서 시작하는 모든 쿼리에 대해 항상 관리자 키 대신 쿼리 키를 사용하세요.

참고: 위의 예제 Azure CLI 코드 조각은 API 탐색을 더 쉽게 시작할 수 있도록 관리 키를 검색하지만 신중하게 관리해야 합니다.

SearchClient 만들기

를 인스턴스화 SearchClient하려면 엔드포인트, API 키 및 인덱스 이름이 필요합니다.

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

service_endpoint = os.environ["AZURE_SEARCH_SERVICE_ENDPOINT"]
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
key = os.environ["AZURE_SEARCH_API_KEY"]

search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

Azure Active Directory 인증을 사용하여 클라이언트 만들기

, SearchIndexClient또는 SearchIndexerClient AAD(Azure Active Directory) 인증을 사용하여 만들 SearchClient수도 있습니다. 사용자 또는 서비스 주체에 "인덱스 데이터 판독기 검색" 역할이 할당되어야 합니다. DefaultAzureCredential을 사용하면 코드를 변경하지 않고도 관리 ID 또는 서비스 주체를 사용하여 서비스를 인증하고, 애플리케이션에서 작업하는 개발자로 인증할 수 있습니다. Azure RBAC(Azure 역할 기반 액세스 제어)를 사용하여 Azure Cognitive Search 연결하는 방법에 대한 지침은 설명서를 참조하세요.

Azure.Identity에서 DefaultAzureCredential또는 자격 증명 형식을 사용하려면 먼저 Azure.Identity 패키지를 설치해야 합니다.

클라이언트 ID 및 비밀과 함께 사용 DefaultAzureCredential 하려면 , AZURE_CLIENT_ID및 AZURE_CLIENT_SECRET 환경 변수를 설정AZURE_TENANT_ID해야 합니다. 또는 Azure.Identity에서도 해당 값을 ClientSecretCredential 에 전달할 수 있습니다.

원본 파일의 맨 위에 있는 에 DefaultAzureCredential 적합한 네임스페이스를 사용해야 합니다.

from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient

service_endpoint = os.getenv("AZURE_SEARCH_SERVICE_ENDPOINT")
index_name = os.getenv("AZURE_SEARCH_INDEX_NAME")
credential = DefaultAzureCredential()

search_client = SearchClient(service_endpoint, index_name, credential)

주요 개념

Azure Cognitive Search 서비스에는 JSON 문서 형식으로 검색 가능한 데이터의 영구 스토리지를 제공하는 하나 이상의 인덱스가 포함되어 있습니다. 검색을 처음 접하는 경우 인덱스와 데이터베이스 테이블 간에 매우 대략적인 비유를 만들 수 있습니다. Azure.Search.Documents 클라이언트 라이브러리는 두 가지 기본 클라이언트 유형을 통해 이러한 리소스에 대한 작업을 노출합니다.

Azure Cognitive Search 의미 체계 검색과 벡터 검색이라는 두 가지 강력한 기능을 제공합니다.

의미 체계 검색 은 텍스트 기반 쿼리에 대한 검색 결과의 품질을 향상시킵니다. 검색 서비스에서 의미 체계 검색을 사용하도록 설정하면 다음 두 가지 방법으로 검색 결과의 관련성을 향상시킬 수 있습니다.

  • 초기 결과 집합에 보조 순위를 적용하여 가장 의미상 관련성이 높은 결과를 맨 위로 승격합니다.
  • 응답에서 캡션과 답변을 추출하고 반환하며, 이는 사용자의 검색 환경을 향상시키기 위해 검색 페이지에 표시될 수 있습니다.

의미 체계 검색에 대한 자세한 내용은 설명서를 참조하세요.

벡터 검색은 기존의 키워드(keyword) 기반 검색의 한계를 극복하는 정보 검색 기술입니다. Vector Search는 어휘 분석과 개별 쿼리 용어 일치에만 의존하는 대신 기계 학습 모델을 활용하여 단어와 구의 상황별 의미를 캡처합니다. 문서 및 쿼리를 포함이라고 하는 고차원 공간에서 벡터로 나타냅니다. 쿼리의 의도를 이해하면 벡터 검색은 문서에 정확한 용어가 없더라도 사용자의 요구 사항에 맞는 보다 관련성이 큰 결과를 제공할 수 있습니다. 또한 벡터 검색은 텍스트뿐만 아니라 이미지 및 비디오를 비롯한 다양한 유형의 콘텐츠에 적용할 수 있습니다.

벡터 필드를 인덱싱하고 벡터 검색을 수행하는 방법을 알아보려면 샘플을 참조하세요. 이 샘플에서는 인덱싱 벡터 필드에 대한 자세한 지침을 제공하고 벡터 검색을 수행하는 방법을 보여 줍니다.

또한 개념 및 사용을 포함하여 벡터 검색에 대한 보다 포괄적인 정보는 설명서를 참조하세요. 이 설명서에서는 Azure Cognitive Search 벡터 검색의 기능을 활용하는 방법에 대한 자세한 설명과 지침을 제공합니다.

Azure.Search.Documents 클라이언트 라이브러리(v1)는 애플리케이션에서 검색 기술을 사용하려는 Python 개발자를 위한 새로운 제품입니다. 유사한 API가 많이 있는 이전의 완전한 기능을 갖춘 Microsoft.Azure.Search 클라이언트 라이브러리(v10)가 있으므로 온라인 리소스를 탐색할 때 혼동을 피해야 합니다.

예제

다음 예제에서는 모두 Azure Portal 사용자 고유의 인덱스로 가져올 수 있는 간단한 Hotel 데이터 집합을 사용합니다. 다음은 몇 가지 기본 사항일 뿐입니다. 샘플을 검사 더 자세히 설명해 주세요.

쿼리

먼저 네임스페이스를 가져와 보겠습니다.

import os
from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

그런 다음 호텔 검색 인덱스 액세스에 대한 을 SearchClient 만듭니다.

index_name = "hotels"
# Get the service endpoint and API key from the environment
endpoint = os.environ["SEARCH_ENDPOINT"]
key = os.environ["SEARCH_API_KEY"]

# Create a client
credential = AzureKeyCredential(key)
client = SearchClient(endpoint=endpoint,
                      index_name=index_name,
                      credential=credential)

"럭셔리" 호텔을 검색해 보겠습니다.

results = client.search(search_text="luxury")

for result in results:
    print("{}: {})".format(result["hotelId"], result["hotelName"]))

인덱스 만들기

를 사용하여 SearchIndexClient 검색 인덱스 만들기를 수행할 수 있습니다. 필드는 편리한 SimpleField, SearchableField또는 ComplexField 모델을 사용하여 정의할 수 있습니다. 인덱스는 제안기, 어휘 분석기 등을 정의할 수도 있습니다.

client = SearchIndexClient(service_endpoint, AzureKeyCredential(key))
name = "hotels"
fields = [
    SimpleField(name="hotelId", type=SearchFieldDataType.String, key=True),
    SimpleField(name="baseRate", type=SearchFieldDataType.Double),
    SearchableField(name="description", type=SearchFieldDataType.String, collection=True),
    ComplexField(
        name="address",
        fields=[
            SimpleField(name="streetAddress", type=SearchFieldDataType.String),
            SimpleField(name="city", type=SearchFieldDataType.String),
        ],
        collection=True,
    ),
]
cors_options = CorsOptions(allowed_origins=["*"], max_age_in_seconds=60)
scoring_profiles: List[ScoringProfile] = []
index = SearchIndex(name=name, fields=fields, scoring_profiles=scoring_profiles, cors_options=cors_options)

result = client.create_index(index)

인덱스로 문서 추가

단일 일괄 처리 요청에서 인덱스에서 , Merge, MergeOrUpload및 Delete 여러 문서를 사용할 수 있습니다Upload. 병합에 대해 알아야 할 몇 가지 특별한 규칙이 있습니다.

DOCUMENT = {
    "category": "Hotel",
    "hotelId": "1000",
    "rating": 4.0,
    "rooms": [],
    "hotelName": "Azure Inn",
}

result = search_client.upload_documents(documents=[DOCUMENT])

print("Upload of new document succeeded: {}".format(result[0].succeeded))

국가별 클라우드에서 인증

National Cloud에서 인증하려면 클라이언트 구성에 다음을 추가해야 합니다.

  • AuthorityHost 자격 증명 옵션에서 또는 환경 변수를 통해 을 AZURE_AUTHORITY_HOST 설정합니다.
  • audience, 또는 에서 를 SearchIndexClient설정합니다.SearchClientSearchIndexerClient
# Create a SearchClient that will authenticate through AAD in the China national cloud.
import os
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts
from azure.search.documents import SearchClient

index_name = "hotels"
endpoint = os.environ["SEARCH_ENDPOINT"]
key = os.environ["SEARCH_API_KEY"]
credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_CHINA)

search_client = SearchClient(endpoint, index_name, credential=credential, audience="https://search.azure.cn")

인덱스에서 특정 문서 검색

키워드 및 선택적 필터를 사용하여 문서를 쿼리하는 것 외에도 키를 이미 알고 있는 경우 인덱스에서 특정 문서를 검색할 수 있습니다. 예를 들어 쿼리에서 키를 가져와서 해당 키에 대한 자세한 정보를 표시하거나 고객을 해당 문서로 이동하려고 할 수 있습니다.

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

result = search_client.get_document(key="23")

print("Details for hotel '23' are:")
print("        Name: {}".format(result["hotelName"]))
print("      Rating: {}".format(result["rating"]))
print("    Category: {}".format(result["category"]))

비동기 API

이 라이브러리에는 완전한 비동기 API가 포함되어 있습니다. 이를 사용하려면 먼저 aiohttp와 같은 비동기 전송을 설치해야 합니다. 자세한 내용은 azure-core 설명서를 참조하세요.

from azure.core.credentials import AzureKeyCredential
from azure.search.documents.aio import SearchClient

search_client = SearchClient(service_endpoint, index_name, AzureKeyCredential(key))

async with search_client:
    results = await search_client.search(search_text="spa")

    print("Hotels containing 'spa' in the name (or other fields):")
    async for result in results:
        print("    Name: {} (rating {})".format(result["hotelName"], result["rating"]))

문제 해결

일반

Azure Cognitive Search 클라이언트는 Azure Core에 정의된 예외를 발생합니다.

로깅

이 라이브러리는 로깅에 표준 로깅 라이브러리를 사용합니다. HTTP 세션(URL, 헤더 등)에 대한 기본 정보는 INFO 수준에서 기록됩니다.

logging_enable 키워드 인수를 통해 클라이언트에서 요청/응답 본문 및 미작성 헤더를 포함한 상세 디버그 수준 로깅을 사용할 수 있습니다.

import sys
import logging
from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = SearchClient("<service endpoint>", "<index_name>", AzureKeyCredential("<api key>"), logging_enable=True)

마찬가지로 logging_enable은 클라이언트에 대해 상세 로깅을 사용하지 않는 경우에도 한 작업에만 사용하게 설정할 수 있습니다.

result =  client.search(search_text="spa", logging_enable=True)

다음 단계

참여

이 라이브러리의 빌드, 테스트 및 기여에 대한 자세한 내용은 검색 CONTRIBUTING.md 참조하세요.

이 프로젝트에 대한 기여와 제안을 환영합니다. 대부분의 경우 기여하려면 권한을 부여하며 실제로 기여를 사용할 권한을 당사에 부여한다고 선언하는 CLA(기여자 라이선스 계약)에 동의해야 합니다. 자세한 내용은 cla.microsoft.com.

이 프로젝트에는 Microsoft Open Source Code of Conduct(Microsoft 오픈 소스 준수 사항)가 적용됩니다. 자세한 내용은 Code of Conduct FAQ(규정 FAQ)를 참조하세요. 또는 추가 질문이나 의견은 opencode@microsoft.com으로 문의하세요.

Impressions

Impressions