Azure OpenAI em sua referência de API de dados

Artigo
10/16/2024

Este artigo fornece documentação de referência para Python e REST para a nova API do Azure OpenAI On Your Data. A versão mais recente da API é 2024-05-01-preview a especificação Swagger.

Nota

Desde a versão 2024-02-15-preview da API, introduzimos as seguintes alterações em comparação com as versões anteriores da API:

O caminho da API é alterado de /extensions/chat/completions para /chat/completions.
A convenção de nomenclatura de chaves de propriedade e valores de enum é alterada de invólucro de camelo para invólucro de cobra. Exemplo: deploymentName é alterado para deployment_name.
O tipo AzureCognitiveSearch de fonte de dados é alterado para azure_search.
As citações e a intenção são movidas das mensagens da ferramenta de contexto da mensagem assistente para o nível raiz de contexto da mensagem assistente com esquema explícito definido.

POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Versões suportadas

2024-02-15-previewEspecificação Swagger.
2024-02-01Especificação Swagger.
2024-05-01-previewEspecificações Swagger

Nota

Os índices do Azure Machine Learning, o Pinecone e o Elasticsearch são suportados como uma visualização.

Parâmetros de URI

Nome	Em	Type	Obrigatório	Description
`deployment-id`	path	string	True	Especifica o nome de implantação do modelo de conclusão de chat a ser usado para essa solicitação.
`endpoint`	path	string	True	Pontos de extremidade do Azure OpenAI. Por exemplo: `https://{YOUR_RESOURCE_NAME}.openai.azure.com`
`api-version`	query	string	True	A versão da API a utilizar para esta operação.

Corpo do pedido

O corpo da solicitação herda o mesmo esquema de solicitação de API de conclusão de chat. Esta tabela mostra os parâmetros exclusivos para o Azure OpenAI On Your Data.

Nome	Type	Obrigatório	Description
`data_sources`	Fonte de dados[]	True	As entradas de configuração para o Azure OpenAI On Your Data. Deve haver exatamente um elemento na matriz. Se `data_sources` não for fornecido, o serviço usa o modelo de conclusão de chat diretamente e não usa o Azure OpenAI On Your Data. Ao especificar o `data_sources` parâmetro, você não poderá usar os `logprobs` parâmetros or `top_logprobs` .

Corpo da resposta

O corpo da resposta herda o mesmo esquema de resposta da API de conclusão de chat. A mensagem de chat de resposta tem uma context propriedade, que é adicionada para o Azure OpenAI On Your Data.

Mensagem de chat

O esquema de mensagem do assistente de resposta herda da mensagem de chat do assistente de conclusão de chat e é estendido com a propriedade context.

Nome	Type	Obrigatório	Description
`context`	Contexto	False	Representa as etapas incrementais executadas pelo Azure OpenAI On Your Data durante o processamento da solicitação, incluindo os documentos recuperados.

Contexto

Nome	Type	Obrigatório	Description
`citations`	Citação[]	False	O resultado da recuperação da fonte de dados, usado para gerar a mensagem do assistente na resposta. Os clientes podem renderizar referências a partir das citações.
`intent`	string	False	A intenção detetada do histórico de bate-papo. Devolver a intenção anterior não é mais necessário. Ignore esta propriedade.
`all_retrieved_documents`	Documentos recuperados[]	False	Todos os documentos recuperados.

Citação

Nome	Type	Obrigatório	Description
`content`	string	True	O conteúdo da citação.
`title`	string	False	O título da citação.
`url`	string	False	O URL da citação.
`filepath`	string	False	O caminho do arquivo da citação.
`chunk_id`	string	False	O ID do bloco da citação.

Documentos recuperados

Nome	Type	Obrigatório	Description
`search_queries`	string[]	True	As consultas de pesquisa usadas para recuperar o documento.
`data_source_index`	integer	True	O índice da fonte de dados.
`original_search_score`	duplo	True	A pontuação de pesquisa original do documento recuperado.
`rerank_score`	duplo	False	A pontuação de reclassificação do documento recuperado.
`filter_reason`	string	False	Representa a lógica para filtrar o documento. Se o documento não for submetido a filtragem, este campo permanecerá desdefinido. Será `score` se o documento for filtrado pelo limite de pontuação de pesquisa original definido por `strictness`. Será `rerank` se o documento não for filtrado pelo limite de pontuação de pesquisa original, mas for filtrado por pontuação de reclassificação e `top_n_documents`.

Data source

Esta lista mostra as fontes de dados suportadas.

Exemplos

Este exemplo mostra como passar o histórico de conversas para obter melhores resultados.

Pré-requisitos:

Configure as atribuições de função do sistema Azure OpenAI atribuído identidade gerenciada ao serviço de pesquisa do Azure. Funções obrigatórias: Search Index Data Reader, Search Service Contributor.
Configure as atribuições de função do usuário para o recurso do Azure OpenAI. Função requerida: Cognitive Services OpenAI User.
Instale Az CLI e execute az login.
Defina as seguintes variáveis de ambiente: 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

Instale os pacotes openaipip mais recentes, 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)

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"
        }
    ]
}
'

Partilhar via