Compartir vía

Referencia de API sobre sus datos de Azure OpenAI

  • Artículo

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-preview Especificació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.
POST {endpoint}/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Versiones compatibles

Nota:

Los índices de Azure Machine Learning, Pinecone y 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.
export AzureOpenAIEndpoint=https://example.openai.azure.com/
export ChatCompletionsDeploymentName=turbo
export SearchEndpoint=https://example.search.windows.net
export SearchIndex=example-index

Instale los paquetes de pip más recientes openai, 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://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)