Azure OpenAI em sua referência de API de dados
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 paradeployment_name
. - O tipo
AzureCognitiveSearch
de fonte de dados é alterado paraazure_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-preview
Especificação Swagger.2024-02-01
Especificação Swagger.2024-05-01-preview
Especificaçõ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.
- Azure AI Search
- Azure Cosmos DB para MongoDB vCore
- Índice do Azure Machine Learning (visualização)
- Elasticsearch (visualização)
- Pinha (pré-visualização)
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
Instale os pacotes openai
pip 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)