Udostępnij za pośrednictwem

Dokumentacja interfejsu API danych w usłudze Azure OpenAI

  • Artykuł

Ten artykuł zawiera dokumentację referencyjną dla języka Python i interfejsu REST dla nowego interfejsu API usługi Azure OpenAI on Your Data API. Najnowsza wersja interfejsu API to 2024-05-01-preview specyfikacja struktury Swagger.

Uwaga

Od wersji 2024-02-15-preview interfejsu API wprowadziliśmy następujące zmiany powodujące niezgodność w porównaniu z wcześniejszymi wersjami interfejsu API:

  • Ścieżka interfejsu API jest zmieniana z /extensions/chat/completions na /chat/completions.
  • Konwencja nazewnictwa kluczy właściwości i wartości wyliczenia jest zmieniana z wielkości liter wielbłąda na obudowę węża. Przykład: deploymentName jest zmieniany na deployment_name.
  • Typ AzureCognitiveSearch źródła danych został zmieniony na azure_search.
  • Cytaty i intencja są przenoszone z komunikatów narzędzia kontekstowego asystenta do poziomu głównego kontekstu komunikatu asystenta z zdefiniowanym jawnym schematem.
POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Obsługiwane wersje

Uwaga

Indeksy usługi Azure Machine Learning, Pinecone i Elasticsearch są obsługiwane jako wersja zapoznawcza .

Parametry identyfikatora URI

Nazwisko W Typ Wymagania opis
deployment-id path string Prawda Określa nazwę wdrożenia modelu uzupełniania czatu do użycia dla tego żądania.
endpoint path string Prawda Punkty końcowe usługi Azure OpenAI. Na przykład: https://{YOUR_RESOURCE_NAME}.openai.azure.com.
api-version zapytanie string Prawda Wersja interfejsu API do użycia dla tej operacji.

Treść żądania

Treść żądania dziedziczy ten sam schemat żądań interfejsu API uzupełniania czatu. W tej tabeli przedstawiono parametry unikatowe dla usługi Azure OpenAI On Your Data.

Nazwisko Type Wymagania opis
data_sources Źródło danych[] Prawda Wpisy konfiguracji dla usługi Azure OpenAI Na danych. W tablicy musi znajdować się dokładnie jeden element. Jeśli data_sources nie zostanie podana, usługa korzysta bezpośrednio z modelu uzupełniania czatów i nie korzysta z usługi Azure OpenAI On Your Data. Po określeniu parametru data_sources nie będzie można używać parametrów logprobs lub top_logprobs .

Treść odpowiedzi

Treść odpowiedzi dziedziczy ten sam schemat odpowiedzi interfejsu API uzupełniania czatu. Komunikat czatu odpowiedzi ma context właściwość dodaną dla usługi Azure OpenAI On Your Data.

Wiadomość czatu

Schemat komunikatów asystenta odpowiedzi dziedziczy z komunikatu czatu asystenta czatu i jest rozszerzony o właściwość context.

Nazwisko Type Wymagania opis
context Kontekst Fałsz Reprezentuje kroki przyrostowe wykonywane przez usługę Azure OpenAI On Your Data podczas przetwarzania żądania, w tym pobrane dokumenty.

Kontekst

Nazwisko Type Wymagania opis
citations Cytat[] Fałsz Wynik pobierania źródła danych używany do generowania komunikatu asystenta w odpowiedzi. Klienci mogą renderować odwołania z cytatów.
intent string Fałsz Wykryta intencja z historii czatów. Przekazanie poprzedniej intencji nie jest już potrzebne. Ignoruj tę właściwość.
all_retrieved_documents Pobrane dokumenty[] Fałsz Wszystkie pobrane dokumenty.

Odsyłacz bibliograficzny

Nazwisko Type Wymagania opis
content string Prawda Zawartość cytatu.
title string Fałsz Tytuł cytatu.
url string Fałsz Adres URL cytatu.
filepath string Fałsz Ścieżka pliku cytatu.
chunk_id string Fałsz Identyfikator fragmentu cytatu.

Pobrane dokumenty

Nazwisko Type Wymagania opis
search_queries string[] Prawda Zapytania wyszukiwania używane do pobierania dokumentu.
data_source_index integer Prawda Indeks źródła danych.
original_search_score double Prawda Oryginalny wynik wyszukiwania pobranego dokumentu.
rerank_score double Fałsz Wynik ponownego generowania pobranego dokumentu.
filter_reason string Fałsz Reprezentuje uzasadnienie filtrowania dokumentu. Jeśli dokument nie zostanie poddany filtrowaniu, to pole pozostanie niezastawione. score Jeśli dokument jest filtrowany według oryginalnego progu oceny wyszukiwania zdefiniowanego przez strictnesselement . rerank Jeśli dokument nie jest filtrowany według oryginalnego progu wyników wyszukiwania, ale jest filtrowany według wyników ponownego korbacji i top_n_documents.

Źródło danych

Ta lista zawiera obsługiwane źródła danych.

Przykłady

W tym przykładzie pokazano, jak przekazać historię konwersacji w celu uzyskania lepszych wyników.

Wymagania wstępne:

  • Skonfiguruj przypisania ról z przypisanej przez system tożsamości zarządzanej systemu Azure OpenAI do usługi Azure Search. Wymagane role: Search Index Data Reader, Search Service Contributor.
  • Skonfiguruj przypisania ról od użytkownika do zasobu usługi Azure OpenAI. Wymagana rola: Cognitive Services OpenAI User.
  • Zainstaluj interfejs wiersza polecenia Az i uruchom polecenie az login.
  • Zdefiniuj następujące zmienne środowiskowe: AzureOpenAIEndpoint, , ChatCompletionsDeploymentNameSearchEndpoint, SearchIndex.
export AzureOpenAIEndpoint=https://example.openai.azure.com/
export ChatCompletionsDeploymentName=turbo
export SearchEndpoint=https://example.search.windows.net
export SearchIndex=example-index

Zainstaluj najnowsze pakiety 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)