다음을 통해 공유

데이터 API 참조의 Azure OpenAI

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

비고

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}

지원되는 버전

비고

Pinecone 및 Elasticsearch 는 미리 보기로 지원됩니다.

URI 매개 변수

이름 안으로 유형 필수 설명
deployment-id 길 문자열 진실 이 요청에 사용할 채팅 완료 모델 배포 이름을 지정합니다.
endpoint 길 문자열 진실 Azure OpenAI 엔드포인트. 예: https://{YOUR_RESOURCE_NAME}.openai.azure.com
api-version 문의 문자열 진실 이 작업에 사용할 API 버전입니다.

요청 메시지 본문

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

이름 유형 필수 설명
data_sources 데이터 소스[] 진실 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로 확장됩니다.

이름 유형 필수 설명
context 컨텍스트 거짓 검색된 문서를 포함하여 요청을 처리하는 동안 Azure OpenAI On Your Data에서 수행하는 증분 단계를 나타냅니다.

컨텍스트

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

인용

이름 유형 필수 설명
content 문자열 진실 인용의 콘텐츠입니다.
title 문자열 거짓 인용의 제목입니다.
url 문자열 거짓 인용의 URL입니다.
filepath 문자열 거짓 인용의 파일 경로입니다.
chunk_id 문자열 거짓 인용의 청크 ID입니다.

검색된 문서

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

데이터 원본

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

예시

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

필수 조건:

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