Azure OpenAI On Your Data API Reference (classic)

Gilt nur für:Foundry (klassisches) Portal. Dieser Artikel ist für das neue Foundry-Portal nicht verfügbar. Erfahren Sie mehr über das neue Portal.

Note

Links in diesem Artikel können Inhalte in der neuen Microsoft Foundry-Dokumentation anstelle der jetzt angezeigten Foundry-Dokumentation (klassisch) öffnen.

Important

Azure OpenAI On Your Data ist veraltet und steht kurz vor dem Ruhestand.

Microsoft hat die Einführung neuer Modelle für Azure OpenAI On Your Data eingestellt. Dieses Feature unterstützt nur die folgenden Modelle:

  • GPT-4o (Versionen 2024-05-13, 2024-08-06 und 2024-11-20)
  • GPT-4o-mini (Version 2024-07-18)
  • GPT-4.1, GPT-4.1-mini und GPT-4.1-nano (Version 2025-04-14)

Sobald die GPT-4.1-Modelle eingestellt werden funktionieren alle Azure OpenAI On Your Data API-Endpunkte und unterstützte Datenquellen-Connectoren nicht mehr.

Wir empfehlen, Azure OpenAI On Your Data Workloads zu Foundry Agent Service mit Foundry IQ zu migrieren, um Inhalte abzurufen und fundierte Antworten aus Ihren Daten zu generieren. Informationen zu den ersten Schritten finden Sie unter Connect a Foundry IQ Knowledge Base.

Dieser Artikel bietet eine Referenzdokumentation für Python und REST für die neue Azure OpenAI On Your Data API. Die neueste API-Version ist 2024-05-01-previewSwagger spec.

Note

Seit der API-Version 2024-02-15-preview haben wir die folgenden wichtigen Änderungen im Vergleich zu früheren API-Versionen eingeführt:

  • Der API-Pfad wird von /extensions/chat/completions zu /chat/completions.
  • Die Benennungskonvention von Eigenschaftsschlüsseln und Enumerationswerten wird von Kamel casing in Schlangenhülle geändert. Beispiel: deploymentName wird in deployment_name.
  • Der Datenquellentyp AzureCognitiveSearch wird in azure_search.
  • Die Zitate und Absichten werden aus den Kontexttoolnachrichten der Assistenten in die Kontextstammebene der Assistentennachricht verschoben, wobei explizites Schema definiert ist.
POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Supported versions

Note

Pinecone und Elasticsearch werden als Vorschau unterstützt.

URI parameters

Name In Type Required Description
deployment-id path string True Gibt den Bereitstellungsnamen des Chatabschlussmodells an, das für diese Anforderung verwendet werden soll.
endpoint path string True Azure OpenAI endpoints. Zum Beispiel: https://{YOUR_RESOURCE_NAME}.openai.azure.com
api-version query string True Die API-Version, die für diesen Vorgang verwendet werden soll.

Request body

Der Anforderungstext erbt dasselbe Schema von Chatabschluss-API-Anforderung. Diese Tabelle zeigt die für Azure OpenAI einzigartigen Parameter auf Ihren Daten.

Name Type Required Description
data_sources DataSource[] True Die Konfigurationseinträge für Azure OpenAI On Your Data. Es muss genau ein Element im Array vorhanden sein. Wenn data_sources nicht bereitgestellt wird, verwendet der Dienst das Chat-Abschlussmodell direkt und Azure OpenAI On Your Data nicht. Wenn Sie den Parameter angeben, können Sie die data_sourceslogprobs Parameter nicht top_logprobs verwenden.

Response body

Der Antworttext erbt dasselbe Schema der API-Antwort für Chatabschlusse. Die Response-Chatnachricht besitzt eine Eigenschaft context, die für Azure OpenAI On Your Data hinzugefügt wird.

Chat message

Das Nachrichtenschema des Antwort-Assistenten erbt von der Chat-Assistent-Chatnachricht und wird mit der Eigenschaft contexterweitert.

Name Type Required Description
context Context False Repräsentiert die inkrementellen Schritte, die Azure OpenAI On Your Data während der Verarbeitung der Anfrage ausführt, einschließlich der abgerufenen Dokumente.

Context

Name Type Required Description
citations Citation[] False Das Abrufergebnis der Datenquelle, das zum Generieren der Assistentennachricht in der Antwort verwendet wird. Clients können Verweise aus den Zitaten rendern.
intent string False Die erkannte Absicht aus dem Chatverlauf. Das Übergeben der vorherigen Absicht ist nicht mehr erforderlich. Diese Eigenschaft ignorieren.
all_retrieved_documents Retrieved documents[] False Alle abgerufenen Dokumente.

Citation

Name Type Required Description
content string True Der Inhalt des Zitats.
title string False Der Titel des Zitats.
url string False Die URL des Zitats.
filepath string False Der Dateipfad des Zitats.
chunk_id string False Die Block-ID des Zitats.

Retrieved documents

Name Type Required Description
search_queries string[] True Die Suchabfragen, die zum Abrufen des Dokuments verwendet werden.
data_source_index integer True Der Index der Datenquelle.
original_search_score double True Die ursprüngliche Suchbewertung des abgerufenen Dokuments.
rerank_score double False Die Rerankbewertung des abgerufenen Dokuments.
filter_reason string False Stellt die Rationale zum Filtern des Dokuments dar. Wenn das Dokument nicht gefiltert wird, bleibt dieses Feld nicht festgelegt. Wird sein score , wenn das Dokument nach dem ursprünglichen Suchergebnisschwellenwert gefiltert wird, der von strictness. Wird sein rerank , wenn das Dokument nicht nach dem ursprünglichen Schwellenwert für die Suchbewertung gefiltert wird, aber nach rerank score und top_n_documentsgefiltert wird.

Data source

Diese Liste zeigt die unterstützten Datenquellen an.

Examples

In diesem Beispiel wird gezeigt, wie Sie den Unterhaltungsverlauf für bessere Ergebnisse übergeben.

Prerequisites:

  • Konfigurieren Sie die Rollenzuweisungen aus dem Azure OpenAI-System-zugewiesenen verwalteten Identitätsdienst an den Azure-Suchdienst. Erforderliche Rollen: Search Index Data Reader, Search Service Contributor.
  • Konfigurieren Sie die Rollenzuweisungen vom Benutzer auf die Azure OpenAI-Ressource. Erforderliche Rolle: Cognitive Services OpenAI User.
  • Installieren Sie Az CLI, und führen Sie aus az login.
  • Definieren Sie die folgenden Umgebungsvariablen: 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

Installieren Sie die neuesten Pip-Pakete 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://ai.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)