Partager via

Informations de référence sur l’API Azure OpenAI sur vos données

  • Article

Cet article fournit une documentation de référence pour Python et REST pour la nouvelle API Azure OpenAI sur vos données. La dernière version de l’API est 2024-05-01-preview Spécification Swagger.

Remarque

Depuis la version 2024-02-15-preview de l’API, nous avons introduit les changements cassants suivants par rapport aux versions antérieures de l’API :

  • Le chemin d’accès de l’API n’est plus/extensions/chat/completions, mais /chat/completions.
  • La convention d’affectation de noms des clés de propriété et des valeurs d’énumération est passée du « camel case » (casse mixte) au « snake case ». Exemple : deploymentName est remplacé par deployment_name.
  • Le type de source de données AzureCognitiveSearch est remplacé par azure_search.
  • Les citations et l’intention sont déplacées des messages de l’outil de contexte du message assistant vers le niveau racine de contexte du message assistant avec un schéma explicite défini.
POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Versions prises en charge

Remarque

Les index Azure Machine Learning, Pinecone et Elasticsearch sont pris en charge en tant que préversion.

Paramètres d’URI

Nom Dans Type Requise Description
deployment-id path string True Spécifie le nom du déploiement de modèle d’achèvement de conversation à utiliser pour cette requête.
endpoint path string True Points de terminaison Azure OpenAI. Par exemple : https://{YOUR_RESOURCE_NAME}.openai.azure.com
api-version query string True Version de l’API à utiliser pour cette opération.

Corps de la demande

Le corps de la requête hérite du même schéma de requête d’API d’achèvements de conversation. Ce tableau montre les paramètres uniques pour Azure OpenAI sur vos données.

Nom Type Requise Description
data_sources DataSource[] True Entrées de configuration pour Azure OpenAI sur vos données. Il doit y avoir exactement un élément dans le tableau. Si data_sources n’est pas fourni, le service utilise directement le modèle d’achèvements de conversation et n’utilise pas Azure OpenAI sur vos données. Lorsque vous spécifiez le paramètre data_sources, vous ne pourrez pas utiliser les paramètres logprobs ou top_logprobs.

Corps de réponse

Le corps de la réponse hérite du même schéma de réponse d’API d’achèvements de conversation. Le message de conversation de réponse a une propriété context, qui est ajoutée pour Azure OpenAI sur vos données.

Message de conversation

Le schéma des messages d’assistant de réponse hérite du message de conversation d’assistant de complétions de conversation et est étendu avec la propriété context.

Nom Type Requise Description
context Context False Représente les étapes incrémentielles effectuées par Azure OpenAI sur vos données lors du traitement de la requête, y compris les documents récupérés.

Context

Nom Type Requise Description
citations Citation[] False Résultat de récupération de la source de données, utilisé pour générer le message assistant dans la réponse. Les clients peuvent afficher les références des citations.
intent string False Intention détectée de l’historique des conversations. L’action de repasser l’intention précédente n’est plus nécessaire. Ignorez cette propriété.
all_retrieved_documents Documents récupérés[] False Tous les documents récupérés.

Citation

Nom Type Requise Description
content string True Contenu de la citation.
title string False Titre de la citation.
url string False URL de la citation.
filepath string False Chemin d’accès au fichier de la citation.
chunk_id string False ID de bloc de la citation.

Documents récupérés

Nom Type Requise Description
search_queries string[] True Ls requêtes de recherche utilisées pour récupérer le document.
data_source_index entier True L’index de la source de données.
original_search_score double True Le score de recherche d’origine du document récupéré.
rerank_score double False Le score de reclassement du document récupéré.
filter_reason string False Représente la justification du filtrage du document. Si le document ne subit pas de filtrage, ce champ reste non défini. Sera score si le document est filtré par le seuil de score de recherche d’origine défini par strictness. Sera rerank si le document n’est pas filtré par le seuil du score de recherche original, mais est filtré par le score de reclassement et top_n_documents.

Source de données

Cette liste montre les sources de données prises en charge.

Exemples

Cet exemple montre comment passer l’historique des conversations pour obtenir de meilleurs résultats.

Configuration requise :

  • Configurez les attributions de rôles à partir de l’identité managée affectée par le système Azure OpenAI vers le service Recherche Azure. Rôles nécessaires : Search Index Data Reader, Search Service Contributor.
  • Configurez les attributions de rôles de l’utilisateur vers la ressource Azure OpenAI. Rôle nécessaire : Cognitive Services OpenAI User.
  • Installez Az CLI et exécutez az login.
  • Définissez les variables d’environnement suivantes : 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

Installez le dernier package pip 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)