Question Answering - Get Answers

Referencia

Servicio:: Cognitive Services - Language

Versión de la API:: 2023-04-01

Responde a la pregunta especificada mediante el knowledge base.

POST {Endpoint}/language/:query-knowledgebases?projectName={projectName}&deploymentName={deploymentName}&api-version=2023-04-01

Parámetros de identificador URI

Nombre	En	Requerido	Tipo	Description
Endpoint	path	True	string	Punto de conexión de Cognitive Services compatible (por ejemplo, https://.api.cognitiveservices.azure.com).
api-version	query	True	string	Versión de API del cliente.
deploymentName	query	True	string	Nombre de la implementación específica del proyecto que se va a usar.
projectName	query	True	string	Nombre del proyecto que se va a usar.

Cuerpo de la solicitud

Nombre	Tipo	Description
answerSpanRequest	ShortAnswerOptions	Para configurar la característica de predicción de intervalo de respuestas.
confidenceScoreThreshold	number	Puntuación de umbral mínima para las respuestas, el valor oscila entre 0 y 1.
context	KnowledgeBaseAnswerContext	Objeto de contexto con la información de QnA anterior.
filters	QueryFilters	Filtre las QnAs en función de la lista de metadatos y los orígenes de knowledge base especificados.
includeUnstructuredSources	boolean	(Opcional) Marca para habilitar la consulta sobre orígenes no estructurados.
qnaId	integer	Identificador exacto de QnA para capturar del knowledge base, este campo tiene prioridad sobre la pregunta.
question	string	Pregunta del usuario para consultar en el knowledge base.
rankerType	RankerKind	Tipo de clasificador que se va a usar.
top	integer	Número máximo de respuestas que se devolverán para la pregunta.
userId	string	Identificador único para el usuario.

Respuestas

Nombre	Tipo	Description
200 OK	AnswersResult	Respuesta correcta para obtener respuestas de knowledge base.
Other Status Codes	ErrorResponse	Respuesta de error.

Seguridad

AADToken

Estos son los flujos de OAuth2 de Azure Active Directory . Cuando se empareja con el control de acceso basado en rol de Azure, se puede usar para controlar el acceso a Azure Maps API REST. Los controles de acceso basados en roles de Azure se usan para designar el acceso a una o varias Azure Maps cuenta de recursos o subrecursos. Se puede conceder acceso a cualquier usuario, grupo o entidad de servicio a través de un rol integrado o un rol personalizado compuesto por uno o varios permisos para Azure Maps API REST.

Para implementar escenarios, se recomienda ver los conceptos de autenticación. En resumen, esta definición de seguridad proporciona una solución para modelar aplicaciones a través de objetos capaces de controlar el acceso en determinadas API y ámbitos.

Notas

Esta definición de seguridad requiere el uso del x-ms-client-id encabezado para indicar a qué recurso Azure Maps la aplicación solicita acceso. Esto se puede adquirir desde la API de administración de Maps.

Authorization URL es específico de la instancia de nube pública de Azure. Las nubes soberanas tienen direcciones URL de autorización únicas y configuraciones de Azure Active Directory. * El control de acceso basado en rol de Azure se configura desde el plano de administración de Azure a través de Azure Portal, PowerShell, CLI, SDK de Azure o API REST. * El uso del SDK web de Azure Maps permite la configuración basada en la configuración de una aplicación para varios casos de uso.

Actualmente, Azure Active Directory v1.0 o v2.0 admite Cuentas profesionales, educativas e invitados, pero no admite cuentas personales.

Tipo: oauth2
Flujo: implicit
Dirección URL de autorización: https://login.microsoftonline.com/common/oauth2/authorize

Ámbitos

Nombre	Description
https://cognitiveservices.azure.com/.default	https://cognitiveservices.azure.com/.default

Ocp-Apim-Subscription-Key

Una clave de suscripción para un recurso de servicio de lenguaje.

Tipo: apiKey
En: header

Ejemplos

Successful query

Solicitud de ejemplo

HTTP

POST {Endpoint}/language/:query-knowledgebases?projectName=proj1&deploymentName=production&api-version=2023-04-01

{
  "question": "how long it takes to charge surface?",
  "top": 3,
  "userId": "sd53lsY=",
  "confidenceScoreThreshold": 0.2,
  "context": {
    "previousQnaId": 9,
    "previousUserQuery": "Where are QnA Maker quickstarts?"
  },
  "rankerType": "Default",
  "filters": {
    "metadataFilter": {
      "metadata": [
        {
          "key": "category",
          "value": "api"
        },
        {
          "key": "editorial",
          "value": "chitchat"
        }
      ],
      "logicalOperation": "AND"
    },
    "sourceFilter": [
      "filename1.pdf",
      "https://www.wikipedia.org/microsoft"
    ],
    "logicalOperation": "AND"
  },
  "answerSpanRequest": {
    "enable": true,
    "confidenceScoreThreshold": 0.2,
    "topAnswersWithSpan": 1
  },
  "includeUnstructuredSources": true
}

Respuesta de muestra

status code:: 200

{
  "answers": [
    {
      "questions": [
        "Power and charging"
      ],
      "answer": "Power and charging**\n\nIt takes two to four hours to charge the Surface Pro 4 battery fully from an empty state. It can take longer if you’re using your Surface for power-intensive activities like gaming or video streaming while you’re charging it.\n\nYou can use the USB port on your Surface Pro 4 power supply to charge other devices, like a phone, while your Surface charges. The USB port on the power supply is only for charging, not for data transfer. If you want to use a USB device, plug it into the USB port on your Surface.",
      "confidenceScore": 0.65,
      "id": 20,
      "source": "surface-pro-4-user-guide-EN.pdf",
      "metadata": {
        "category": "api",
        "editorial": "chitchat"
      },
      "dialog": {
        "isContextOnly": false,
        "prompts": [
          {
            "displayOrder": 1,
            "qnaId": 23,
            "displayText": "prompt1"
          },
          {
            "displayOrder": 2,
            "qnaId": 36,
            "displayText": "prompt2"
          }
        ]
      },
      "answerSpan": {
        "text": "two to four hours",
        "confidenceScore": 0.3,
        "offset": 33,
        "length": 50
      }
    },
    {
      "questions": [
        "Charge your Surface Pro 4"
      ],
      "answer": "**Charge your Surface Pro 4**\n\n1.  Connect the two parts of the power cord.\n\n2.  Connect the power cord securely to the charging port.\n\n3.  Plug the power supply into an electrical outlet.",
      "confidenceScore": 0.32,
      "id": 13,
      "source": "surface-pro-4-user-guide-EN.pdf"
    }
  ]
}

Definiciones

Nombre	Description
AnswersOptions	Parámetros para consultar un knowledge base.
AnswerSpan	Objeto de intervalo de respuesta de QnA.
AnswersResult	Representa la lista de respuestas a preguntas.
enable	Habilite o deshabilite la predicción de intervalo de respuestas.
Error	Objeto de error.
ErrorCode	Código de error legible.
ErrorResponse	Respuesta de error.
InnerErrorCode	Código de error legible.
InnerErrorModel	Objeto que contiene información más específica sobre el error. Según las directrices de la API de Microsoft One: https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
KnowledgeBaseAnswer	Representa knowledge base respuesta.
KnowledgeBaseAnswerContext	Objeto de contexto con la información de QnA anterior.
KnowledgeBaseAnswerDialog	Cuadro de diálogo asociado a Answer.
KnowledgeBaseAnswerPrompt	Pida una respuesta.
LogicalOperationKind	Establezca en "OR" o "AND" para usar la operación lógica correspondiente.
MetadataFilter	Busque QnAs asociadas a la lista de metadatos especificada.
MetadataRecord	Objeto para proporcionar el par de valores de clave para cada metadato.
QueryFilters	filtra por knowledge base.
RankerKind	Tipo de clasificador que se va a usar.
ShortAnswerOptions	Para configurar la característica de predicción de intervalo de respuestas.

AnswersOptions

Parámetros para consultar un knowledge base.

Nombre	Tipo	Description
answerSpanRequest	ShortAnswerOptions	Para configurar la característica de predicción de intervalo de respuestas.
confidenceScoreThreshold	number	Puntuación de umbral mínima para las respuestas, el valor oscila entre 0 y 1.
context	KnowledgeBaseAnswerContext	Objeto de contexto con la información de QnA anterior.
filters	QueryFilters	Filtre las QnAs en función de la lista de metadatos y los orígenes de knowledge base especificados.
includeUnstructuredSources	boolean	(Opcional) Marca para habilitar la consulta sobre orígenes no estructurados.
qnaId	integer	Identificador exacto de QnA para capturar del knowledge base, este campo tiene prioridad sobre la pregunta.
question	string	Pregunta del usuario para consultar en el knowledge base.
rankerType	RankerKind	Tipo de clasificador que se va a usar.
top	integer	Número máximo de respuestas que se devolverán para la pregunta.
userId	string	Identificador único para el usuario.

AnswerSpan

Objeto de intervalo de respuesta de QnA.

Nombre	Tipo	Description
confidenceScore	number	Puntuación prevista del intervalo de respuestas, intervalos de valor de 0 a 1.
length	integer	Longitud del intervalo de respuesta.
offset	integer	Desplazamiento del intervalo de respuesta desde el inicio de la respuesta.
text	string	Texto previsto del intervalo de respuestas.

AnswersResult

Representa la lista de respuestas a preguntas.

Nombre	Tipo	Description
answers	KnowledgeBaseAnswer[]	Representa la lista de resultados de respuesta.

enable

Habilite o deshabilite la predicción de intervalo de respuestas.

Nombre	Tipo	Description
True	Boolean

Error

Objeto de error.

Nombre	Tipo	Description
code	ErrorCode	Uno de un conjunto definido por el servidor de códigos de error.
details	Error[]	Matriz de detalles sobre errores específicos que llevaron a este error notificado.
innererror	InnerErrorModel	Objeto que contiene información más específica que el objeto actual sobre el error.
message	string	Representación legible del error.
target	string	Destino del error.

ErrorCode

Código de error legible.

Nombre	Tipo	Description
AzureCognitiveSearchIndexLimitReached	string
AzureCognitiveSearchIndexNotFound	string
AzureCognitiveSearchNotFound	string
AzureCognitiveSearchThrottling	string
Conflict	string
Forbidden	string
InternalServerError	string
InvalidArgument	string
InvalidRequest	string
NotFound	string
OperationNotFound	string
ProjectNotFound	string
QuotaExceeded	string
ServiceUnavailable	string
Timeout	string
TooManyRequests	string
Unauthorized	string
Warning	string

ErrorResponse

Respuesta de error.

Nombre	Tipo	Description
error	Error	Objeto de error.

InnerErrorCode

Código de error legible.

Nombre	Tipo	Description
AzureCognitiveSearchNotFound	string
AzureCognitiveSearchThrottling	string
EmptyRequest	string
ExtractionFailure	string
InvalidCountryHint	string
InvalidDocument	string
InvalidDocumentBatch	string
InvalidParameterValue	string
InvalidRequest	string
InvalidRequestBodyFormat	string
KnowledgeBaseNotFound	string
MissingInputDocuments	string
ModelVersionIncorrect	string
UnsupportedLanguageCode	string

InnerErrorModel

Objeto que contiene información más específica sobre el error. Según las directrices de la API de Microsoft One: https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Nombre	Tipo	Description
code	InnerErrorCode	Uno de un conjunto definido por el servidor de códigos de error.
details	object	Detalles del error.
innererror	InnerErrorModel	Objeto que contiene información más específica que el objeto actual sobre el error.
message	string	Mensaje de error.
target	string	Destino de error.

KnowledgeBaseAnswer

Representa knowledge base respuesta.

Nombre	Tipo	Description
answer	string	Texto de respuesta.
answerSpan	AnswerSpan	Objeto de intervalo de respuesta de QnA con respecto a la pregunta del usuario.
confidenceScore	number	Respuesta a la puntuación de confianza, el valor oscila entre 0 y 1.
dialog	KnowledgeBaseAnswerDialog	Cuadro de diálogo asociado a Answer.
id	integer	Identificador del resultado de QnA.
metadata	object	Metadatos asociados a la respuesta, útiles para clasificar o filtrar respuestas de preguntas.
questions	string[]	Lista de preguntas asociadas a la respuesta.
source	string	Origen del resultado de QnA.

KnowledgeBaseAnswerContext

Objeto de contexto con la información de QnA anterior.

Nombre	Tipo	Description
previousQnaId	integer	Id. de QnA del resultado de respuesta superior anterior.
previousUserQuery	string	Consulta de usuario anterior.

KnowledgeBaseAnswerDialog

Cuadro de diálogo asociado a Answer.

Nombre	Tipo	Description
isContextOnly	boolean	Para marcar si una solicitud solo es relevante con una pregunta anterior o no. Si es true, no incluya esta QnA como resultado de búsqueda para las consultas sin contexto; de lo contrario, si es false, omite el contexto e incluye este QnA en el resultado de la búsqueda.
prompts	KnowledgeBaseAnswerPrompt[]	Lista de mensajes asociados a la respuesta.

KnowledgeBaseAnswerPrompt

Pida una respuesta.

Nombre	Tipo	Description
displayOrder	integer	Índice del símbolo del sistema: se usa para ordenar las indicaciones.
displayText	string	Texto que se muestra para representar un mensaje de pregunta de seguimiento.
qnaId	integer	Id. de QnA correspondiente al símbolo del sistema.

LogicalOperationKind

Establezca en "OR" o "AND" para usar la operación lógica correspondiente.

Nombre	Tipo	Description
AND	string
OR	string

MetadataFilter

Busque QnAs asociadas a la lista de metadatos especificada.

Nombre	Tipo	Valor predeterminado	Description
logicalOperation	LogicalOperationKind	AND	Operación usada para combinar filtros de metadatos.
metadata	MetadataRecord[]		Objeto para proporcionar el par de valores de clave para cada metadato.

MetadataRecord

Objeto para proporcionar el par de valores de clave para cada metadato.

Nombre	Tipo	Description
key	string	Clave de metadatos del diccionario de metadatos usado en QnA.
value	string	Valor de metadatos del diccionario de metadatos usado en QnA.

QueryFilters

filtra por knowledge base.

Nombre	Tipo	Valor predeterminado	Description
logicalOperation	LogicalOperationKind	AND	Operación lógica usada para combinar el filtro de metadatos con el filtro de origen.
metadataFilter	MetadataFilter		Busque QnAs asociadas a la lista de metadatos especificada.
sourceFilter	string[]		Busque QnAs asociadas a cualquiera de las listas de orígenes especificadas en knowledge base.

RankerKind

Tipo de clasificador que se va a usar.

Nombre	Tipo	Description
Default	string	Clasificador predeterminado.
QuestionOnly	string	Pregunta solo clasificador.

ShortAnswerOptions

Para configurar la característica de predicción de intervalo de respuestas.

Nombre	Tipo	Description
confidenceScoreThreshold	number	Puntuación de umbral mínima necesaria para incluir un intervalo de respuesta, intervalos de valor comprendidos entre 0 y 1.
enable	enable	Habilite o deshabilite la predicción de intervalo de respuestas.
topAnswersWithSpan	integer	Número de respuestas principales que se deben tener en cuenta para la predicción del intervalo de 1 a 10.

Compartir a través de