Condividi tramite

Riferimento API Dati Azure OpenAI sui dati

  • Articolo

Questo articolo fornisce la documentazione di riferimento per Python e REST per la nuova istanza di Azure OpenAI nell'API dati. La versione più recente dell'API è 2024-05-01-preview specifica Swagger.

Nota

Dalla versione dell'API 2024-02-15-preview sono state introdotte le seguenti modifiche di rilievo rispetto alle versioni precedenti dell'API:

  • Il percorso dell'API viene modificato da /extensions/chat/completions a /chat/completions.
  • La convenzione di denominazione delle chiavi di proprietà e dei valori di enumerazione viene modificata camel casing a snake casing. Esempio: deploymentName viene modificato in deployment_name.
  • Il tipo di origine dati AzureCognitiveSearch viene modificato in azure_search.
  • Le citazioni e le finalità vengono spostati dai messaggi di contesto del messaggio dell'assistente al livello radice del contesto del messaggio dell'assistente con uno schema esplicito definito.
POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Versioni supportate

Nota

Gli indici di Azure Machine Learning, Pineconee Elasticsearch sono supportati come anteprima.

Parametri URI

Nome Tra Type Obbligatorio Descrizione
deployment-id path string True Specifica il nome della distribuzione del modello di completamento della chat da usare per questa richiesta.
endpoint path string True Endpoint OpenAI di Azure. Ad esempio: https://{YOUR_RESOURCE_NAME}.openai.azure.com
api-version query string True Versione dell'API da usare per questa operazione.

Testo della richiesta

Il corpo della richiesta eredita lo stesso schema della richiesta API di completamento della chat. Questa tabella mostra i parametri univoci per Azure OpenAI sui dati.

Nome Digita Obbligatorio Descrizione
data_sources DataSource[] Vero Voci di configurazione per Azure OpenAI nei dati. Nella matrice deve essere presente esattamente un elemento. Se data_sources non viene fornito, il servizio usa direttamente il modello di completamento della chat e non usa Azure OpenAI nei dati. Quando si specifica il parametro data_sources, non sarà possibile usare i parametri logprobs o top_logprobs.

Corpo della risposta

Il corpo della risposta eredita lo stesso schema della risposta API di completamento della chat. Il messaggio di chat di risposta ha una proprietà context, aggiunta per Azure OpenAI nei dati.

Messaggio della chat

Lo schema del messaggio di risposta dell'assistente eredita dall'assistente del completamento del messaggio di chat e viene esteso con la proprietà context.

Nome Digita Obbligatorio Descrizione
context Contesto Falso Rappresenta i passaggi incrementali eseguiti da Azure OpenAI sui dati durante l'elaborazione della richiesta, inclusi i documenti recuperati.

Contesto

Nome Digita Obbligatorio Descrizione
citations Citazione[] Falso Risultato del recupero dell'origine dati, utilizzato per generare il messaggio di assistenza nella risposta. I client possono eseguire il rendering dei riferimenti dalle citazioni.
intent string Falso Finalità rilevata dalla cronologia delle chat. Il passaggio della finalità precedente non è più necessario. Ignorare questa proprietà.
all_retrieved_documents Documenti recuperati[] Falso Tutti i documenti recuperati.

Citazione

Nome Digita Obbligatorio Descrizione
content stringa True Contenuto della citazione.
title string Falso Titolo della citazione.
url string Falso URL della citazione.
filepath string Falso Percorso del file della citazione.
chunk_id string Falso ID di blocco della citazione.

Documenti recuperati

Nome Digita Obbligatorio Descrizione
search_queries string[] Vero Query di ricerca utilizzate per recuperare il documento.
data_source_index integer Vero Indice dell'origine dati.
original_search_score double Vero Punteggio di ricerca originale del documento recuperato.
rerank_score double Falso Punteggio di rerank del documento recuperato.
filter_reason string Falso Rappresenta la logica per filtrare il documento. Se il documento non viene filtrato, questo campo rimarrà non impostato. Verrà score se il documento viene filtrato in base alla soglia del punteggio di ricerca originale definita da strictness. Verrà rerank se il documento non viene filtrato in base alla soglia del punteggio di ricerca originale, ma viene filtrato in base al punteggio di rerank e top_n_documents.

Origine dati

Questo elenco mostra le origini dati supportate.

Esempi

Questo esempio illustrato come passare la cronologia delle conversazioni per ottenere risultati migliori.

Prerequisiti:

  • Configurare le assegnazioni di ruolo dall'identità gestita assegnata dal sistema OpenAI di Azure al servizio di ricerca di Azure. Ruoli richiesti: Search Index Data Reader, Search Service Contributor.
  • Configurare le assegnazioni di ruolo dall'utente alla risorsa OpenAI di Azure. Ruolo richiesto: Cognitive Services OpenAI User.
  • Installare l’interfaccia della riga di comando di Az ed eseguire az login.
  • Definire le variabili di ambiente seguenti: 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

Installare i pacchetti pip più recenti 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)