다음을 통해 공유

데이터 원본 - Azure AI 검색

  • 아티클

Azure OpenAI On Your Data를 사용하는 경우 Azure AI 검색의 구성 가능한 옵션입니다. 이 데이터 원본은 API 버전 2024-02-01에서 지원됩니다.

속성 Type 필수 설명
parameters 매개 변수 True Azure Search를 구성할 때 사용할 매개 변수입니다.
type string True azure_search이어야 합니다.

매개 변수

이름 Type 필수 설명
endpoint string True 사용할 Azure Search 리소스의 절대 엔드포인트 경로입니다.
index_name string True 참조된 Azure Search 리소스에 사용할 인덱스의 이름입니다.
authentication ApiKeyAuthenticationOptions, SystemAssignedManagedIdentityAuthenticationOptions, UserAssignedManagedIdentityAuthenticationOptions, onYourDataAccessTokenAuthenticationOptions 중 하나 True 정의된 데이터 원본에 액세스할 때 사용할 인증 방법입니다.
embedding_dependency DeploymentNameVectorizationSource, EndpointVectorizationSource 중 하나 False 벡터 검색에 포함되는 종속성입니다. query_type이 vector, vector_simple_hybrid 또는 vector_semantic_hybrid인 경우 필요합니다.
fields_mapping FieldsMappingOptions False 검색 인덱스와 상호 작용할 때 사용할 사용자 지정된 필드 매핑 동작입니다.
filter string False 검색 필터입니다.
in_scope 부울 값 False 쿼리를 인덱싱된 데이터 사용으로 제한해야 하는지 여부입니다. 기본값은 True입니다.
query_type QueryType False Azure Search와 함께 사용할 쿼리 유형입니다. 기본값은 simple
role_information string False 응답을 생성할 때 참조해야 하는 컨텍스트와 작동 방식에 대한 지침을 모델에 제공합니다. 도우미의 성격을 설명하고 응답 형식을 지정하는 방법을 알려줄 수 있습니다.
semantic_configuration string False 쿼리에 대한 의미 체계 구성입니다. query_type이 semantic 또는 vector_semantic_hybrid인 경우 필요합니다.
strictness 정수 False 검색 관련성 필터링의 구성된 엄격성입니다. 엄격성이 높을수록 정밀도가 높지만 대답의 재현율이 낮습니다. 기본값은 3입니다.
top_n_documents 정수 False 구성된 쿼리에 대해 기능할 구성된 상위 문서 수입니다. 기본값은 5입니다.
max_search_queries 정수 False 다시 작성된 쿼리의 최대 수는 검색 공급자에게 하나의 사용자 메시지를 보내야 합니다. 지정하지 않으면 시스템에서 보낼 쿼리 수를 결정합니다.
allow_partial_result 정수 False true로 지정하면 시스템에서 부분 검색 결과를 사용할 수 있으며 모든 쿼리가 실패하면 요청이 실패합니다. 지정하지 않거나 false로 지정하면 검색 쿼리가 실패하면 요청이 실패합니다.
include_contexts 배열 False 출력 컨텍스트의 포함된 속성입니다. 지정하지 않은 경우 기본값은 citations 및 intent입니다. 값은 citations, intent, all_retrieved_documents일 수 있습니다.

API 키 인증 옵션

API 키를 사용하는 경우 Azure OpenAI On Your Data에 대한 인증 옵션입니다.

속성 Type 필수 설명
key string True 인증에 사용할 API 키입니다.
type string True api_key이어야 합니다.

시스템 할당 관리 ID 인증 옵션

시스템 할당 관리 ID를 사용하는 경우 Azure OpenAI On Your Data에 대한 인증 옵션입니다.

속성 Type 필수 설명
type string True system_assigned_managed_identity이어야 합니다.

사용자 할당 관리 ID 인증 옵션

사용자 할당 관리 ID를 사용하는 경우 Azure OpenAI On Your Data에 대한 인증 옵션입니다.

속성 Type 필수 설명
managed_identity_resource_id string True 인증 시 이용할 사용자가 할당한 관리 ID의 리소스 ID입니다.
type string True user_assigned_managed_identity이어야 합니다.

액세스 토큰 인증 옵션

액세스 토큰을 사용하는 경우 Azure OpenAI On Your Data에 대한 인증 옵션입니다.

속성 Type 필수 설명
access_token string True 인증에 사용할 액세스 토큰입니다.
type string True access_token이어야 합니다.

배포 이름 벡터화 원본

벡터 검색을 적용하는 경우 Azure OpenAI On Your Data에서 사용하는 벡터화 원본의 세부 정보입니다. 이 벡터화 원본은 동일한 Azure OpenAI 리소스의 내부 포함 모델 배포 이름을 기반으로 합니다. 이 벡터화 원본을 사용하면 Azure OpenAI api-key 없이 Azure OpenAI 공용 네트워크에 액세스하지 않고도 벡터 검색을 사용할 수 있습니다.

속성 Type 필수 설명
deployment_name string True 동일한 Azure OpenAI 리소스 내의 포함 모델의 배포 이름입니다.
type string True deployment_name이어야 합니다.
dimensions 정수 False 포함에 포함해야 하는 차원의 수입니다. text-embedding-3 이상 모델에서만 지원됩니다.

엔드포인트 벡터화 원본

벡터 검색을 적용하는 경우 Azure OpenAI On Your Data에서 사용하는 벡터화 원본의 세부 정보입니다. 이 벡터화 원본은 Azure OpenAI 포함 API 엔드포인트를 기반으로 합니다.

속성 Type 필수 설명
endpoint string True 포함을 검색할 리소스 엔드포인트 URL을 지정합니다. https://{YOUR_RESOURCE_NAME}.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings 형식이어야 합니다. api-version 쿼리 매개 변수는 허용되지 않습니다.
authentication ApiKeyAuthenticationOptions True 지정된 엔드포인트에서 포함을 검색할 때 사용할 인증 옵션을 지정합니다.
type string True endpoint이어야 합니다.
dimensions 정수 False 포함에 포함해야 하는 차원의 수입니다. text-embedding-3 이상 모델에서만 지원됩니다.

필드 매핑 옵션

구성된 Azure Search 리소스를 사용할 때 필드가 처리되는 방식을 제어하는 선택적 설정입니다.

속성 Type 필수 설명
content_fields string[] False 콘텐츠로 처리해야 하는 인덱스 필드의 이름입니다.
vector_fields string[] False 벡터 데이터를 나타내는 필드의 이름입니다.
content_fields_separator string False 콘텐츠 필드에서 사용해야 하는 구분 기호 패턴입니다. 기본값은 \n입니다.
filepath_field string False 파일 경로로 사용할 인덱스 필드의 이름입니다.
title_field string False 제목으로 사용할 인덱스 필드의 이름입니다.
url_field string False URL로 사용할 인덱스 필드의 이름입니다.

쿼리 유형

Azure OpenAI On Your Data로 사용할 때 실행해야 하는 Azure Search 검색 쿼리의 유형입니다.

열거형 값 설명
simple 기본 단순 쿼리 파서를 나타냅니다.
semantic 고급 의미 체계 모델링을 위한 의미 체계 쿼리 파서를 나타냅니다.
vector 계산된 데이터에 대한 벡터 검색을 나타냅니다.
vector_simple_hybrid 벡터 데이터와 간단한 쿼리 전략의 조합을 나타냅니다.
vector_semantic_hybrid 의미 체계 검색 및 벡터 데이터 쿼리의 조합을 나타냅니다.

예제

필수 조건:

  • Azure OpenAI 시스템이 할당한 관리 ID에서 Azure Search 서비스로 역할 할당을 구성합니다. 필요한 역할: Search Index Data Reader, Search Service Contributor.
  • 사용자에서 Azure OpenAI 리소스로 역할 할당을 구성합니다. 필요한 역할: Cognitive Services OpenAI User.
  • Az CLI를 설치하고 az login을 실행합니다.
  • 환경 변수 AzureOpenAIEndpoint, ChatCompletionsDeploymentName, SearchEndpoint, SearchIndex를 정의합니다.
export AzureOpenAIEndpoint=https://example.openai.azure.com/
export ChatCompletionsDeploymentName=turbo
export SearchEndpoint=https://example.search.windows.net
export SearchIndex=example-index

최신 pip 패키지 openai, azure-identity를 설치합니다.

import os
from openai import AzureOpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

endpoint = os.environ.get("AzureOpenAIEndpoint")
deployment = os.environ.get("ChatCompletionsDeploymentName")
search_endpoint = os.environ.get("SearchEndpoint")
search_index = os.environ.get("SearchIndex")

token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default")

client = AzureOpenAI(
    azure_endpoint=endpoint,
    azure_ad_token_provider=token_provider,
    api_version="2024-02-01",
)

completion = client.chat.completions.create(
    model=deployment,
    messages=[
        {
            "role": "user",
            "content": "Who is DRI?",
        },
    ],
    extra_body={
        "data_sources": [
            {
                "type": "azure_search",
                "parameters": {
                    "endpoint": search_endpoint,
                    "index_name": search_index,
                    "authentication": {
                        "type": "system_assigned_managed_identity"
                    }
                }
            }
        ]
    }
)

print(completion.model_dump_json(indent=2))