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.

Importante

Azure OpenAI On Your Data desativada em 14 de outubro de 2026 e não tem mais suporte do Microsoft.

Para um aplicativo com Pesquisa de IA do Azure , siga Migrar Azure OpenAI em seus dados para o IQ do Foundry. Este exemplo reutiliza o índice existente e demonstra as alterações de aplicativo para recuperação, respostas e citações. A migração não é automática. Consulte também a origem do bloco de anotações no GitHub.

A recuperação e a síntese de resposta do auto exemplo (answerSynthesis) usam 2026-08-01-preview. Examine seus pré-requisitos e requisitos de controle de acesso e os termos de visualização Pesquisa de IA do Azure . Recursos de visualização não são recomendados para produção. Para alternativas geralmente disponíveis, use a recuperação mínima e extrativa da base de dados de conhecimento com 2026-04-01 ou rag clássico, com geração de resposta gerenciada pelo aplicativo. Esses caminhos não são substituições equivalentes a recursos.

Antes da desativação, Azure OpenAI Em Seus Dados tinha suporte para 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)

Para corpus Q&A, chame diretamente uma base de dados de conhecimento do Foundry IQ . Adicione o Serviço do Foundry Agent para ferramentas, ações ou fluxos de trabalho adicionais. Consulte Escolher o caminho de migração. Para obter o caminho baseado em agente, consulte Conectar agentes às bases 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 mudanças de impacto 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 nomeação de chaves de propriedade e valores de enum mudou de carcaça camela para carcaça serpente. 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}

Versões com suporte

Note

Pinecone e Elasticsearch são suportados como prévia.

Parâmetros de URI

Name Em Tipo Obrigatório Descrição
deployment-id caminho cadeia Verdade Especifica o nome de implementação do modelo de conclusão de chat a ser usado para esta solicitação.
endpoint caminho cadeia Verdade Azure pontos de extremidade openai. Por exemplo: https://{YOUR_RESOURCE_NAME}.openai.azure.com
api-version consulta cadeia Verdade A versão da API a ser usada para esta operação.

Corpo da solicitação

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

Name Tipo Obrigatório Descrição
data_sources datasource[] Verdade As entradas de configuração para Azure OpenAI On Your Data. Deve haver exatamente um elemento no array. 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. Quando você especifica o data_sources parâmetro, não poderá usar os logprobs parâmetros ou.top_logprobs

Corpo da resposta

O corpo de resposta herda o mesmo esquema de resposta API de completação de chat. A mensagem response chat possui uma propriedade context, que é adicionada para 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 do chat, e é estendido com a propriedade context.

Name Tipo Obrigatório Descrição
context Contexto Falso Representa as etapas incrementais realizadas pelo OpenAI On Your Data do Azure durante o processamento da solicitação, incluindo os documentos recuperados.

Contexto

Name Tipo Obrigatório Descrição
citations Citação[] Falso O resultado da recuperação da fonte de dados, usado para gerar a mensagem assistente na resposta. Os clientes podem fornecer referências a partir das citações.
intent cadeia Falso A intenção detectada pelo histórico do chat. Transmitir a intenção anterior não é mais necessário. Ignore essa propriedade.
all_retrieved_documents Documentos recuperados[] Falso Todos os documentos recuperados.

Citação

Name Tipo Obrigatório Descrição
content cadeia Verdade O conteúdo da citação.
title cadeia Falso O título da citação.
url cadeia Falso A URL da citação.
filepath cadeia Falso O caminho do arquivo da citação.
chunk_id cadeia Falso O ID do bloco da multa.

Documentos recuperados

Name Tipo Obrigatório Descrição
search_queries string[] Verdade As consultas de busca usadas para recuperar o documento.
data_source_index inteiro Verdade O índice da fonte de dados.
original_search_score duplo Verdade A pontuação original da busca do documento recuperado.
rerank_score duplo Falso A pontuação de reclassificação do documento recuperado.
filter_reason cadeia Falso Representa a justificativa para filtrar o documento. Se o documento não passar por filtragem, esse campo permanecerá sem definição. Será score se o documento for filtrado pelo limiar original de pontuação de busca definido por strictness. Será rerank se o documento não for filtrado pelo limiar original de pontuação de busca, mas for filtrado por pontuação de reclassificação e top_n_documents.

Fonte de dados

Esta lista mostra as fontes de dados suportadas.

Exemplos

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

Pré-requisitos:

  • Configure as atribuições de funções do sistema Azure OpenAI atribuída identidade gerenciada ao serviço de busca do Azure. Funções obrigató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 obrigatória: Cognitive Services OpenAI User.
  • Instale o CLI do Arizona e execute 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)
  • Última atualização em