Azure OpenAI On Your Data API Reference (clássico)

Aplica-se somente a:Portal de fundimento (clássico). Este artigo não está disponível para o novo portal do Foundry. Saiba mais sobre o novo portal.

Note

Links neste artigo podem abrir conteúdo na nova documentação do Microsoft Foundry em vez da documentação da Foundry (clássica) que você está exibindo agora.

Important

Azure OpenAI Em Seus Dados está preterido e se aproximando da desativação.

Microsoft parou de integrar novos modelos para Azure OpenAI em seus dados. Esse recurso só dá suporte aos seguintes modelos:

  • GPT-4o (versões 2024-05-13, 2024-08-06 e 2024-11-20)
  • GPT-4o-mini (versão 2024-07-18)
  • GPT-4.1, GPT-4.1-mini e GPT-4.1-nano (versão 2025-04-14)

Once, os modelos GPT-4.1 se desativam, todos os Azure Os pontos de extremidade da API de Dados e os conectores de fonte de dados compatíveis param de funcionar.

Recomendamos que você migre Azure cargas de trabalho openai em seus dados para Foundry Agent Service com Foundry IQ para recuperar conteúdo e gerar respostas a base de seus dados. Para começar, consulte Conectar uma base de dados de conhecimento do IQ do Foundry.

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

Note

Desde a versão 2024-02-15-preview da API, introduzimos as seguintes alterações significativas 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 enumeração é alterada de casing de camelo para casing 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 de ferramenta de contexto da mensagem de assistente para o nível raiz de contexto da mensagem de assistente com o esquema explícito definido.
POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Supported versions

Note

Há suporte para Pinecone e Elasticsearch como uma versão prévia.

URI parameters

Name In Tipo Required Description
deployment-id caminho cadeia True Especifica o nome de implantação do modelo de conclusões de chat a ser usado para essa solicitação.
endpoint caminho cadeia True Azure OpenAI endpoints. Por exemplo: https://{YOUR_RESOURCE_NAME}.openai.azure.com
api-version consulta cadeia True A versão da API a ser usada para esta operação.

Request body

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

Name Tipo Required Description
data_sources DataSource[] True As entradas de configuração para 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 utiliza Azure OpenAI On Your Data. Ao especificar o data_sources parâmetro, você não poderá usar os parâmetros ou top_logprobs os logprobs parâmetros.

Response body

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

Chat message

O esquema de mensagens do assistente de resposta herda da mensagem de chat do assistente de conclusões de chat e é estendido com a propriedade context.

Name Tipo Required Description
context Context False Representa as etapas incrementais realizadas pelo OpenAI On Your Data do Azure durante o processamento da solicitação, incluindo os documentos recuperados.

Context

Name Tipo Required Description
citations Citation[] 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 das citações.
intent cadeia False A intenção detectada do histórico de chat. A passagem de volta da intenção anterior não é mais necessária. Ignore essa propriedade.
all_retrieved_documents Retrieved documents[] False Todos os documentos recuperados.

Citation

Name Tipo Required Description
content cadeia True O conteúdo da citação.
title cadeia False O título da citação.
url cadeia False A URL da citação.
filepath cadeia False O caminho do arquivo da citação.
chunk_id cadeia False A ID da parte da citação.

Retrieved documents

Name Tipo Required Description
search_queries string[] True As consultas de pesquisa usadas para recuperar o documento.
data_source_index inteiro True O índice da fonte de dados.
original_search_score double True A pontuação de pesquisa original do documento recuperado.
rerank_score double False A pontuação de reclassificado do documento recuperado.
filter_reason cadeia False Representa a lógica para filtrar o documento. Se o documento não passar por filtragem, esse campo permanecerá indefinido. score Será se o documento for filtrado pelo limite de pontuação de pesquisa original definido por strictness. rerank Será se o documento não for filtrado pelo limite de pontuação de pesquisa original, mas for filtrado por pontuação de reclassificado e top_n_documents.

Data source

Esta lista mostra as fontes de dados com suporte.

Examples

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

Prerequisites:

  • Configure as atribuições de funções do sistema Azure OpenAI atribuída identidade gerenciada ao serviço de busca do Azure. Funções necessárias: Search Index Data Reader, Search Service Contributor.
  • Configure as atribuições de funções do usuário para o recurso Azure OpenAI. Função necessária: Cognitive Services OpenAI User.
  • Instale a CLI do Az e execute az login.
  • Defina as seguintes variáveis de ambiente: AzureOpenAIEndpoint, ,ChatCompletionsDeploymentNameSearchEndpoint, 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 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://ai.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)