Azure OpenAI On Your Data API Reference (classic)

Solo se aplica a:Portal de foundry (clásico). Este artículo no está disponible para el nuevo portal de Foundry. Obtenga más información sobre el nuevo portal.

Note

Los vínculos de este artículo pueden abrir contenido en la nueva documentación de Microsoft Foundry en lugar de la documentación de Foundry (clásico) que está viendo ahora.

Important

Azure OpenAI en sus datos está en desuso y se acerca a la retirada.

Microsoft ha dejado de incorporar nuevos modelos para Azure OpenAI en los datos. Esta característica solo admite los siguientes modelos:

  • GPT-4o (versiones 2024-05-13, 2024-08-06 y 2024-11-20)
  • GPT-4o-mini (versión 2024-07-18)
  • GPT-4.1, GPT-4.1-mini y GPT-4.1-nano (versión 2025-04-14)

Once los modelos GPT-4.1 se retiran, todos los Azure OpenAI en los puntos de conexión de Data API y los conectores de origen de datos admitidos dejan de funcionar.

Se recomienda migrar Azure OpenAI en las cargas de trabajo de datos a Foundry Agent Service con Foundry IQ para recuperar contenido y generar respuestas fundamentadas de los datos. Para empezar, consulte Conexión de una base de conocimiento de Foundry IQ.

Este artículo ofrece documentación de referencia para Python y REST para la nueva API de OpenAI sobre tus datos de Azure. La última versión de la API es 2024-05-01-previewSwagger spec.

Note

Dado que la versión 2024-02-15-preview de la API introdujimos los siguientes cambios importantes en comparación con versiones anteriores de la API:

  • La ruta de acceso de LA API se cambia de /extensions/chat/completions a /chat/completions.
  • La convención de nomenclatura de las claves de propiedad y los valores de enumeración se cambia de mayúsculas y minúsculas a mayúsculas y minúsculas de serpiente. Ejemplo: deploymentName se cambia a deployment_name.
  • El tipo AzureCognitiveSearch de origen de datos se cambia a azure_search.
  • Las citas y la intención se mueven de los mensajes de la herramienta de contexto del mensaje del asistente al nivel raíz del contexto del mensaje del asistente con esquema explícito definido.
POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Supported versions

Note

Pinecone y Elasticsearch se admiten como versión preliminar.

URI parameters

Name In Type Required Description
deployment-id path string True Especifica el nombre de implementación del modelo de finalizaciones de chat que se usará para esta solicitud.
endpoint path string True Azure OpenAI endpoints. Por ejemplo: https://{YOUR_RESOURCE_NAME}.openai.azure.com
api-version query string True Versión de la API que se va a usar para esta operación.

Request body

El cuerpo de la solicitud hereda el mismo esquema de solicitudes de API de finalizaciones de chat. Esta tabla muestra los parámetros únicos para Azure OpenAI On Your Data.

Name Type Required Description
data_sources DataSource[] True Las entradas de configuración para Azure OpenAI On Your Data. Debe haber exactamente un elemento en la matriz. Si no se proporciona data_sources, el servicio utiliza directamente el modelo de completación de chats y no utiliza Azure OpenAI On Your Data. Al especificar el data_sources parámetro , no podrá usar los logprobs parámetros o top_logprobs .

Response body

El cuerpo de la respuesta hereda el mismo esquema de respuesta de la API de finalizaciones de chat. El mensaje de chat respuesta tiene una propiedad context, que se añade para Azure OpenAI On Your Data.

Chat message

El esquema de mensajes del asistente de respuesta hereda del mensaje del asistente de finalizaciones de chat y se extiende con la propiedad context.

Name Type Required Description
context Context False Representa los pasos incrementales realizados por Azure OpenAI On Your Data al procesar la solicitud, incluidos los documentos recuperados.

Context

Name Type Required Description
citations Citation[] False Resultado de la recuperación del origen de datos, que se usa para generar el mensaje del asistente en la respuesta. Los clientes pueden representar referencias de las citas.
intent string False La intención detectada del historial de chat. Ya no se necesita pasar la intención anterior. Omita esta propiedad.
all_retrieved_documents Retrieved documents[] False Todos los documentos recuperados.

Citation

Name Type Required Description
content string True Contenido de la cita.
title string False Título de la cita.
url string False Dirección URL de la cita.
filepath string False Ruta de acceso del archivo de la cita.
chunk_id string False Identificador del fragmento de la cita.

Retrieved documents

Name Type Required Description
search_queries string[] True Las consultas de búsqueda usadas para recuperar el documento.
data_source_index integer True Índice del origen de datos.
original_search_score double True Puntuación de búsqueda original del documento recuperado.
rerank_score double False Puntuación de rerank del documento recuperado.
filter_reason string False Representa la justificación para filtrar el documento. Si el documento no se somete a un filtrado, este campo permanecerá sin establecer. score Será si el documento se filtra por el umbral de puntuación de búsqueda original definido por strictness. rerank Será si el documento no se filtra por el umbral de puntuación de búsqueda original, pero se filtra por puntuación de rerank y top_n_documents.

Data source

En esta lista se muestran los orígenes de datos admitidos.

Examples

En este ejemplo se muestra cómo pasar el historial de conversaciones para obtener mejores resultados.

Prerequisites:

  • Configura la asignación de roles desde el sistema OpenAI asignado a la identidad gestionada de Azure al servicio de búsqueda de Azure. Roles necesarios: Search Index Data Reader, Search Service Contributor.
  • Configura la asignación de roles del usuario al recurso de Azure OpenAI. Rol necesario: Cognitive Services OpenAI User.
  • Instale la CLI de Az y ejecute az login.
  • Defina las siguientes variables de entorno: 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 los paquetes openaipip más recientes , 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)