Referencia de API sobre sus datos de Azure OpenAI

Artículo
27/02/2025

En este artículo se proporciona documentación de referencia para Python y REST para la nueva instancia de Azure OpenAI en la API de datos. La última versión de la API es 2024-05-01-previewEspecificación de Swagger.

Nota

Desde 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 camel casing a snake casing. Ejemplo: deploymentName se cambia a deployment_name.
El tipo de origen de datos AzureCognitiveSearch 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.

HTTP

POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Versiones compatibles

2024-02-15-preview Especificación de Swagger.
2024-02-01 Especificación de Swagger
2024-05-01-preview Especificación de Swagger

Nota

Pineconey Elasticsearch se admiten como versión preliminar.

Parámetros del identificador URI

Nombre	En	Tipo	Obligatorio	Descripción
`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	Puntos de conexión de Azure OpenAI. Por ejemplo: `https://{YOUR_RESOURCE_NAME}.openai.azure.com`
`api-version`	consulta	string	True	Versión de API que se usará para la operación.

Cuerpo de la solicitud

El cuerpo de la solicitud hereda el mismo esquema de solicitudes de API de finalizaciones de chat. En esta tabla se muestran los parámetros únicos de Azure OpenAI en los datos.

Nombre	Type	Obligatorio	Descripción
`data_sources`	DataSource[]	True	Las entradas de configuración de Azure OpenAI en los datos. Debe haber exactamente un elemento en la matriz. Si no se proporciona `data_sources`, el servicio usa directamente el modelo de finalizaciones de chat y no usa Azure OpenAI en los datos. Al especificar el parámetro `data_sources`, no podrá usar los parámetros `logprobs` ni `top_logprobs`.

Cuerpo de la respuesta

El cuerpo de la respuesta hereda el mismo esquema de respuesta de la API de finalizaciones de chat. El mensaje de chat de respuesta tiene una propiedad context, que se agrega para Azure OpenAI en los datos.

Mensaje de chat

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

Nombre	Type	Obligatorio	Descripción
`context`	Context	False	Representa los pasos incrementales que realiza Azure OpenAI en los datos al procesar la solicitud, incluidos los documentos recuperados.

Context

Nombre	Type	Obligatorio	Descripción
`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. Puedes omitir esta propiedad.
`all_retrieved_documents`	Documentos recuperados[]	False	Todos los documentos recuperados.

Referencia bibliográfica

Nombre	Type	Obligatorio	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.

Documentos recuperados

Nombre	Type	Obligatorio	Descripción
`search_queries`	string[]	True	Las consultas de búsqueda usadas para recuperar el documento.
`data_source_index`	integer	True	El índice del origen de datos.
`original_search_score`	doble	True	La puntuación de búsqueda original del documento recuperado.
`rerank_score`	doble	False	La puntuación de reclasificación 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. Será `score` si el documento se filtra por el umbral de puntuación de la búsqueda original definido por `strictness`. Será `rerank` si el documento no se filtra por el umbral de puntuación de la búsqueda original, sino que se filtra por la puntuación de reclasificación y `top_n_documents`.

Origen de datos

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

Ejemplos

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

Requisitos previos:

Configure las asignaciones de roles desde la identidad administrada asignada por el sistema OpenAI de Azure al Servicio Azure Search. Roles necesarios: Search Index Data Reader, Search Service Contributor.
Configure las asignaciones de roles del usuario al recurso de Azure OpenAI. Rol necesario: Cognitive Services OpenAI User.
Instale CLI de Az y ejecute az login.
Defina las siguientes variables de entorno: AzureOpenAIEndpoint, ChatCompletionsDeploymentName,SearchEndpoint, SearchIndex.

Bash

export AzureOpenAIEndpoint=https://example.openai.azure.com/
export ChatCompletionsDeploymentName=turbo
export SearchEndpoint=https://example.search.windows.net
export SearchIndex=example-index

Python 1.x
REST

Instale los paquetes de pip más recientes openai, azure-identity.

Python

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)