Teilen über

Azure OpenAI in Ihrer Daten-API-Referenz

  • Artikel

Dieser Artikel enthält eine Referenzdokumentation zu Python und REST für die neue API für Azure OpenAI für Ihre Daten. Die neueste API-Version ist 2024-05-01-preview Swagger-Spezifikation.

Hinweis

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

  • Der API-Pfad wird von /extensions/chat/completions in /chat/completions geändert.
  • Bei der Namenskonvention von Eigenschaftsschlüsseln und Enumerationswerten werden nun Unterstriche und keine Binnenmajuskeln mehr verwendet. Beispiel: deploymentName wird in deployment_name geändert.
  • Der Datenquellentyp AzureCognitiveSearch wird in azure_search geändert.
  • Die Zitate und Absichten werden aus den Kontexttoolnachrichten der Assistentennachricht in die Kontextstammebene der Assistentennachricht verschoben. Dabei wird ein explizites Schema definiert.
POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Unterstützte Versionen

Hinweis

Azure Machine Learning-Indizes, Pinecone und Elasticsearch werden als Vorschauversion unterstützt.

URI-Parameter

Name Geben Sie in Type Erforderlich Beschreibung
deployment-id path Zeichenfolge True Gibt den Namen der Modellimplementierung für Chatvervollständigungen an, der für diese Anforderung verwendet werden soll.
endpoint path Zeichenfolge True Azure OpenAI-Endpunkte. Beispiel: https://{YOUR_RESOURCE_NAME}.openai.azure.com
api-version query Zeichenfolge True Hierbei handelt es sich um die für diesen Vorgang zu verwendende API-Version.

Anforderungstext

Der Anforderungstext erbt dasselbe Schema von der Anforderung der Chatvervollständigungs-API. Die folgende Tabelle enthält die für „Azure OpenAI für Ihre Daten“ eindeutigen Parameter.

Name Type Erforderlich Beschreibung
data_sources DataSource[] True Die Konfigurationseinträge für „Azure OpenAI für Ihre Daten“. Es muss genau ein Element im Array vorhanden sein. Wenn data_sources nicht angegeben wird, verwendet der Dienst das Chatvervollständigungsmodell direkt und verwendet nicht „Azure OpenAI für Ihre Daten“. Wenn Sie den Parameter data_sources angeben, können Sie die Parameter logprobs oder top_logprobs nicht verwenden.

Antworttext

Der Antworttext erbt dasselbe Schema von der Antwort der Chatvervollständigungs-API. Die Antwortchatnachricht verfügt über eine context-Eigenschaft, die für „Azure OpenAI für Ihre Daten“ hinzugefügt wird.

Chatnachricht

Das Nachrichtenschema des Antwort-Assistenten erbt von der Chat-Nachricht des Assistenten für Chat-Abschlüsse und wird um die Eigenschaft context erweitert.

Name Type Erforderlich Beschreibung
context Kontext False Stellt die inkrementellen Schritte dar, die Azure OpenAI On Your Data während der Verarbeitung der Anfrage durchführt, einschließlich der abgerufenen Dokumente.

Kontext

Name Type Erforderlich Beschreibung
citations Citation[] False Das Ergebnis des Datenquellenabrufs, das zum Generieren der Assistentennachricht in der Antwort verwendet wird. Kunden können Referenzen aus den Zitaten wiedergeben.
intent Zeichenfolge False Die erkannte Absicht aus dem Chatverlauf. Die Rückgabe der vorherigen Absicht ist nicht mehr erforderlich. Ignorieren Sie diese Eigenschaft.
all_retrieved_documents Abgerufene Dokumente[] False Alle abgerufenen Dokumente.

Quellenangaben

Name Type Erforderlich Beschreibung
content Zeichenfolge True Der Inhalt des Zitats.
title Zeichenfolge False Der Titel des Zitats.
url Zeichenfolge False Die URL des Zitats.
filepath Zeichenfolge False Der Dateipfad des Zitats.
chunk_id Zeichenfolge False Die Segment-ID des Zitats.

Abgerufene Dokumente

Name Type Erforderlich Beschreibung
search_queries string[] True Die zum Abrufen des Dokuments verwendeten Suchabfragen.
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 neue Rangpunktzahl des abgerufenen Dokuments.
filter_reason Zeichenfolge False Stellt die Begründung für die Filterung des Dokuments dar. Wenn das Dokument nicht gefiltert wird, bleibt dieses Feld leer. Wenn das Dokument nach dem durch strictness definierten Schwellenwert der ursprünglichen Suchbewertung gefiltert wird, hat das Feld den Wert score. Wenn das Dokument nicht nach dem Schwellenwert der ursprünglichen Suchbewertung, sondern nach neuer Rangpunktzahl und top_n_documents gefiltert wird, hat das Feld den Wert rerank.

Datenquelle

In der folgenden Liste sind die unterstützten Datenquellen aufgeführt:

Beispiele

Dieses Beispiel zeigt, wie Sie den Gesprächsverlauf für bessere Ergebnisse weitergeben können.

Voraussetzungen:

  • Konfigurieren Sie die Rollenzuweisungen aus dem Azure OpenAI-System, dem der Azure-Suchdienst verwaltete Identität zugewiesen wurde. Erforderliche Rollen: Search Index Data Reader, Search Service Contributor.
  • Konfigurieren Sie die Rollenzuweisungen vom Benutzer zur Azure OpenAI-Ressource. Erforderliche Rolle: Cognitive Services OpenAI User.
  • Installieren Sie Az CLI und führen Sie az login aus.
  • 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://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)