Azure OpenAI på din data-API-referens

Artikel
05/30/2024

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.

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

2024-02-15-previewSwagger-specifikation.
2024-02-01Swagger-specifikation.
2024-05-01-previewSwagger-specifikation

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.

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

Python 1.x
REST

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))

az rest --method POST \
 --uri $AzureOpenAIEndpoint/openai/deployments/$ChatCompletionsDeploymentName/chat/completions?api-version=2024-05-01-preview \
 --resource https://cognitiveservices.azure.com/ \
 --body \
'
{
    "data_sources": [
        {
            "type": "azure_search",
            "parameters": {
                "endpoint": "'$SearchEndpoint'",
                "index_name": "'$SearchIndex'",
                "authentication": {
                    "type": "system_assigned_managed_identity"
                }
            }
        }
    ],
    "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"
        }
    ]
}
'

Dela via