다음을 통해 공유

데이터 API 참조의 Azure OpenAI

  • 아티클

이 문서에서는 새 Azure OpenAI On Your Data API에 대한 Python 및 REST에 대한 참조 문서를 제공합니다. 최신 API 버전은 2024-05-01-preview Swagger 사양입니다.

참고 항목

API 버전 2024-02-15-preview 이후로 이전 API 버전과 비교하여 다음과 같은 호환성이 손상되는 변경이 도입되었습니다.

  • API 경로가 /extensions/chat/completions에서 /chat/completions로 변경됩니다.
  • 속성 키 및 열거형 값의 명명 규칙은 카멜 표기법에서 스네이크 표기법으로 변경됩니다. 예: deploymentName은 deployment_name으로 변경됩니다.
  • 데이터 원본 형식 AzureCognitiveSearch는 azure_search로 변경됩니다.
  • 인용 및 의도는 정의된 명시적 스키마를 사용하여 도우미 메시지의 컨텍스트 도구 메시지에서 도우미 메시지의 컨텍스트 루트 수준으로 이동됩니다.
POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

지원되는 버전

참고 항목

Azure Machine Learning 인덱스, Pinecone 및 Elasticsearch는 미리 보기로 지원됩니다.

URI 매개 변수

이름 In Type 필수 설명
deployment-id 경로 string True 이 요청에 사용할 채팅 완료 모델 배포 이름을 지정합니다.
endpoint 경로 string True Azure OpenAI 엔드포인트. 예: https://{YOUR_RESOURCE_NAME}.openai.azure.com
api-version query string True 이 작업에 사용할 API 버전입니다.

요청 본문

요청 본문은 채팅 완료 API 요청과 동일한 스키마를 상속합니다. 이 표에서는 Azure OpenAI On Your Data에 고유한 매개 변수를 보여 줍니다.

속성 Type 필수 설명
data_sources DataSource[] True Azure OpenAI On Your Data에 대한 구성 항목입니다. 배열에는 정확히 하나의 요소가 있어야 합니다. data_sources가 제공되지 않으면 서비스는 채팅 완료 모델을 직접 사용하며 Azure OpenAI On Your Data를 사용하지 않습니다. data_sources 매개 변수를 지정하면 logprobs 또는 top_logprobs 매개 변수를 사용할 수 없습니다.

응답 본문

응답 본문은 채팅 완료 API 응답과 동일한 스키마를 상속합니다. 응답 채팅 메시지에는 Azure OpenAI On Your Data에 대해 추가되는 context 속성이 있습니다.

채팅 메시지

응답 도우미 메시지 스키마는 채팅 완료 도우미 채팅 메시지에서 상속되며 속성 context로 확장됩니다.

속성 Type 필수 설명
context Context False 검색된 문서를 포함하여 요청을 처리하는 동안 Azure OpenAI On Your Data에서 수행하는 증분 단계를 나타냅니다.

Context

속성 Type 필수 설명
citations 인용[] False 응답에서 도우미 메시지를 생성하는 데 사용되는 데이터 원본 검색 결과입니다. 클라이언트는 인용에서 참조를 렌더링할 수 있습니다.
intent string False 채팅 기록에서 검색된 의도입니다. 이전 의도를 다시 전달할 필요가 없습니다. 이 속성을 무시합니다.
all_retrieved_documents 검색된 문서[] False 검색된 모든 문서입니다.

인용

속성 Type 필수 설명
content string True 인용의 내용입니다.
title string False 인용의 제목입니다.
url string False 인용의 URL입니다.
filepath string False 인용의 파일 경로입니다.
chunk_id string False 인용의 청크 ID입니다.

검색된 문서

속성 Type 필수 설명
search_queries string[] True 문서를 검색하는 데 사용되는 검색 쿼리입니다.
data_source_index 정수 True 데이터 원본의 인덱스입니다.
original_search_score double True 검색된 문서의 원래 검색 점수입니다.
rerank_score double False 검색된 문서의 순위 다시 매김 점수입니다.
filter_reason string False 문서 필터링의 근거를 나타냅니다. 문서가 필터링되지 않으면 이 필드는 설정되지 않은 상태로 유지됩니다. 문서가 strictness에서 정의한 원래 검색 점수 임곗값으로 필터링되는 경우 score입니다. 문서가 원래 검색 점수 임곗값으로 필터링되지 않고 순위 다시 매김 점수 및 top_n_documents로 필터링되는 경우 rerank입니다.

데이터 원본

이 목록에는 지원되는 데이터 원본이 표시됩니다.

예제

이 예제에서는 더 나은 결과를 위해 대화 기록을 전달하는 방법을 보여 줍니다.

필수 조건:

  • 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-05-01-preview",
)

completion = client.chat.completions.create(
    model=deployment,
    messages=[
        {
            "role": "user",
            "content": "Who is DRI?",
        },
        {
            "role": "assistant",
            "content": "DRI stands for Directly Responsible Individual of a service. Which service are you asking about?"
        },
        {
            "role": "user",
            "content": "Opinion mining service"
        }
    ],
    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))

# render the citations

content = completion.choices[0].message.content
context = completion.choices[0].message.context
for citation_index, citation in enumerate(context["citations"]):
    citation_reference = f"[doc{citation_index + 1}]"
    url = "https://example.com/?redirect=" + citation["url"] # replace with actual host and encode the URL
    filepath = citation["filepath"]
    title = citation["title"]
    snippet = citation["content"]
    chunk_id = citation["chunk_id"]
    replaced_html = f"<a href='{url}' title='{title}\n{snippet}''>(See from file {filepath}, Part {chunk_id})</a>"
    content = content.replace(citation_reference, replaced_html)
print(content)