Dela via


Azure OpenAI på din data-API-referens

Den här artikeln innehåller referensdokumentation för Python och REST för det nya Azure OpenAI On Your Data-API:et. Den senaste API-versionen är 2024-05-01-previewSwagger spec.

Anmärkning

Sedan API-versionen 2024-02-15-preview introducerade vi följande icke-bakåtkompatibla ändringar jämfört med tidigare API-versioner:

  • API-sökvägen ändras från /extensions/chat/completions till /chat/completions.
  • Namngivningskonventionen för egenskapsnycklar och uppräkningsvärden ändras från kamelhölje till ormhölje. Exempel: deploymentName ändras till deployment_name.
  • Datakällans typ AzureCognitiveSearch ändras till azure_search.
  • Citaten och avsikten flyttas från assistentmeddelandets kontextverktygsmeddelanden till assistentmeddelandets kontextrotnivå med explicit schema definierat.
POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Versioner som stöds

Anmärkning

Pinecone och Elasticsearch stöds som en förhandsversion.

URI parametrar

Namn I Typ Krävs Beskrivning
deployment-id väg snöre Sann Anger namnet på chattens slutförandemodell som ska användas för den här begäran.
endpoint väg snöre Sann Azure OpenAI-slutpunkter. Till exempel: https://{YOUR_RESOURCE_NAME}.openai.azure.com
api-version förfrågan snöre Sann Den API-version som ska användas för den här åtgärden.

begäranens innehåll

Begärandetexten ärver samma schema för API-begäran om chattavslut. Den här tabellen visar parametrarna som är unika för Azure OpenAI på dina data.

Namn Typ Krävs Beskrivning
data_sources Datakälla[] Sann Konfigurationsposterna för Azure OpenAI på dina data. Det måste finnas exakt ett element i matrisen. Om data_sources inte tillhandahålls använder tjänsten modellen för chattavslut direkt och använder inte Azure OpenAI på dina data. När du anger parametern data_sources kan du inte använda parametrarna logprobs eller top_logprobs .

Svarsdel

Svarstexten ärver samma schema för API-svar för chattavslut. Svarschattmeddelandet har en context egenskap som läggs till för Azure OpenAI På dina data.

Chattmeddelande

Meddelandeschemat för svarsassistenten ärver från chattassistentens chattmeddelande och utökas med egenskapen context.

Namn Typ Krävs Beskrivning
context Kontext Falsk Representerar de inkrementella steg som utförs av Azure OpenAI på dina data när begäran bearbetas, inklusive de hämtade dokumenten.

Kontext

Namn Typ Krävs Beskrivning
citations Citat[] Falsk Datakällans hämtningsresultat, som används för att generera assistentmeddelandet i svaret. Klienter kan återge referenser från citaten.
intent snöre Falsk Den identifierade avsikten från chatthistoriken. Det behövs inte längre att du skickar tillbaka den tidigare avsikten. Ignorera den här egenskapen.
all_retrieved_documents Hämtade dokument[] Falsk Alla hämtade dokument.

Citat

Namn Typ Krävs Beskrivning
content snöre Sann Innehållet i källhänvisning.
title snöre Falsk Rubriken på citatet.
url snöre Falsk URL:en för källhänvisning.
filepath snöre Falsk Filsökvägen för källhänvisning.
chunk_id snöre Falsk Citatets segment-ID.

Hämtade dokument

Namn Typ Krävs Beskrivning
search_queries sträng[] Sann Sökfrågorna som används för att hämta dokumentet.
data_source_index integer Sann Datakällans index.
original_search_score dubbel Sann Den ursprungliga sökpoängen för det hämtade dokumentet.
rerank_score dubbel Falsk Omrankningspoängen för det hämtade dokumentet.
filter_reason snöre Falsk Representerar anledningen till att filtrera dokumentet. Om dokumentet inte genomgår filtrering förblir det här fältet oet. Kommer att vara score om dokumentet filtreras efter det ursprungliga tröskelvärdet för sökpoäng som definieras av strictness. Kommer att vara rerank om dokumentet inte filtreras efter det ursprungliga tröskelvärdet för sökpoäng, men filtreras efter omrankningspoäng och top_n_documents.

Datakälla

Den här listan visar de datakällor som stöds.

Exempel

Det här exemplet visar hur du skickar konversationshistorik för bättre resultat.

Förutsättningar:

  • Konfigurera rolltilldelningarna från Azure OpenAI-systemet som tilldelats hanterad identitet till Azure Search-tjänsten. Nödvändiga roller: Search Index Data Reader, Search Service Contributor.
  • Konfigurera rolltilldelningarna från användaren till Azure OpenAI-resursen. Obligatorisk roll: Cognitive Services OpenAI User.
  • Installera Az CLI och kör az login.
  • Definiera följande miljövariabler: 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

Installera de senaste pip-paketen 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)