Referencia de API sobre sus datos de Azure OpenAI
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 adeployment_name
. - El tipo de origen de datos
AzureCognitiveSearch
se cambia aazure_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
2024-02-15-preview
Especificación de Swagger.2024-02-01
Especificación de Swagger2024-05-01-preview
Especificación de Swagger
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.
- Azure AI Search
- Núcleo virtual de Azure Cosmos DB for MongoDB
- Índice de Azure Machine Learning (versión preliminar)
- Elasticsearch (versión preliminar)
- Pinecone (versión preliminar)
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)