Dela via

Azure OpenAI på din data-API-referens

  • Artikel

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-preview Swagger spec.

Kommentar

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

Kommentar

Azure Machine Learning-index, Pinecone och Elasticsearch stöds som förhandsversion.

URI-parametrar

Name I Typ Obligatoriskt Beskrivning
deployment-id path sträng Sant Anger namnet på chattens slutförandemodell som ska användas för den här begäran.
endpoint path sträng Sant Azure OpenAI-slutpunkter. Till exempel: https://{YOUR_RESOURCE_NAME}.openai.azure.com
api-version query sträng Sant Den API-version som ska användas för den här åtgärden.

Begärandetext

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 Obligatoriskt Beskrivning
data_sources DataSource[] Sant 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 .

Själva svaret

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 Obligatoriskt 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 Obligatoriskt 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 sträng 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.

Hänvisning

Namn Typ Obligatoriskt Beskrivning
content sträng Sant Innehållet i källhänvisning.
title sträng Falsk Rubriken på citatet.
url sträng Falsk URL:en för källhänvisning.
filepath sträng Falsk Filsökvägen för källhänvisning.
chunk_id sträng Falsk Citatets segment-ID.

Hämtade dokument

Namn Typ Obligatoriskt Beskrivning
search_queries string[] Sant Sökfrågorna som används för att hämta dokumentet.
data_source_index integer Sant Datakällans index.
original_search_score dubbel Sant 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 sträng 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.

Data source

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)