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

Aplica-se apenas a:Portal da fundição (clássico). Este artigo não está disponível para o novo portal da Foundry. Saiba mais sobre o novo portal.

Note

Os links neste artigo podem abrir conteúdo na nova documentação do Microsoft Foundry em vez da documentação do Foundry (clássico) que está a ver agora.

Important

O Azure OpenAI On Your Data está obsoleto e está a aproximar-se da reforma.

A Microsoft deixou de integrar novos modelos no Azure OpenAI On Your Data. Esta funcionalidade suporta apenas os seguintes modelos:

  • GPT-4o (versões 2024-05-13, 2024-08-06 e 20-11-2024)
  • 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)

Assim que os modelos GPT-4.1 se retiram, todos os endpoints e conectores de fonte de dados suportados Azure OpenAI On Your Data API deixam de funcionar.

Recomendamos que migre Azure cargas de trabalho OpenAI On Your Data para Foundry Agent Service com Foundry IQ para recuperar conteúdo e gerar respostas fundamentadas a partir dos seus dados. Para começar, consulte a base de conhecimento Connect a Foundry IQ.

Este artigo fornece documentação de referência para Python e REST para a nova API Azure OpenAI On Your Data. 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 marcantes em comparação com 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 propriedades e valores de enum é alterada de camel casing para snake casing. 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 do contexto da mensagem assistente, com esquema explícito definido.
POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Supported versions

Note

Pinecone e Elasticsearch são suportados como pré-visualização.

URI parameters

Name In Tipo Required Description
deployment-id caminho cadeia (de caracteres) True Especifica o nome de implementação do modelo de conclusão de chat a usar para este pedido.
endpoint caminho cadeia (de caracteres) True Azure OpenAI endpoints. Por exemplo: https://{YOUR_RESOURCE_NAME}.openai.azure.com
api-version consulta cadeia (de caracteres) True A versão da API a usar para esta operação.

Request body

O corpo do pedido herda o mesmo esquema de pedidos API de conclusão 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. Tem de haver exatamente um elemento no array. Se não for fornecido data_sources, o serviço utiliza diretamente o modelo de conclusão de chat e não utiliza Azure OpenAI On Your Data. Quando especificas o data_sources parâmetro, não poderás usar os logprobs parâmetros ou top_logprobs .

Response body

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

Chat message

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

Name Tipo Required Description
context Context False Representa os passos incrementais realizados pelo OpenAI On Your Data do Azure durante o processamento do pedido, 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 fornecer referências a partir das citações.
intent cadeia (de caracteres) False A intenção detetada no histórico da conversa. Já não é necessário transmitir a intenção anterior. Ignora esta propriedade.
all_retrieved_documents Retrieved documents[] False Todos os documentos recuperados.

Citation

Name Tipo Required Description
content cadeia (de caracteres) True O conteúdo da citação.
title cadeia (de caracteres) False O título da citação.
url cadeia (de caracteres) False O URL da citação.
filepath cadeia (de caracteres) False O caminho do ficheiro da citação.
chunk_id cadeia (de caracteres) False A identificação do bloco 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 número inteiro True O índice da fonte de dados.
original_search_score double True A pontuação original da pesquisa do documento recuperado.
rerank_score double False A pontuação de reclassificação do documento recuperado.
filter_reason cadeia (de caracteres) False Representa a razão para filtrar o documento. Se o documento não for sujeito a filtragem, este campo permanecerá sem definir. Será score se o documento for filtrado pelo limiar original de pontuação de pesquisa definido por strictness. Será rerank se o documento não for filtrado pelo limiar original da pontuação de pesquisa, mas for filtrado pela pontuação de reclassificação e top_n_documents.

Data source

Esta lista mostra as fontes de dados suportadas.

Examples

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

Prerequisites:

  • Configure as atribuições de funções do sistema Azure OpenAI atribuída identidade gerida ao serviço de pesquisa Azure. Papéis obrigatórios: Search Index Data Reader, Search Service Contributor.
  • Configure as atribuições de funções do utilizador para o recurso Azure OpenAI. Função obrigatória: Cognitive Services OpenAI User.
  • Instala o Az CLI e executa az logino arquivo .
  • 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 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)