Question Answering - Get Answers

Referência

Service:: Cognitive Services - Language

API Version:: 2023-04-01

Responde à pergunta especificada com a sua base de dados de conhecimento.

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

Parâmetros do URI

Name	Em	Necessário	Tipo	Description
Endpoint	path	True	string	Ponto final dos Serviços Cognitivos suportado (por exemplo, https://.api.cognitiveservices.azure.com).
api-version	query	True	string	Versão da API de Cliente.
deploymentName	query	True	string	O nome da implementação específica do projeto a utilizar.
projectName	query	True	string	O nome do projeto a utilizar.

Corpo do Pedido

Name	Tipo	Description
answerSpanRequest	ShortAnswerOptions	Para configurar a funcionalidade de predição do Answer span.
confidenceScoreThreshold	number	Classificação mínima de limiar para respostas, intervalos de valores de 0 a 1.
context	KnowledgeBaseAnswerContext	Objeto de contexto com informações de FAQ anteriores.
filters	QueryFilters	Filtre QnAs com base em determinadas origens de metadados e base de dados de conhecimento.
includeUnstructuredSources	boolean	(Opcional) Sinalizador para ativar a Consulta através de Origens Não Estruturadas.
qnaId	integer	ID de FAQ exato para obter a partir do base de dados de conhecimento, este campo tem prioridade sobre a pergunta.
question	string	Pergunta do utilizador para consultar o base de dados de conhecimento.
rankerType	RankerKind	Tipo de classificador a utilizar.
top	integer	Número máximo de respostas a devolver para a pergunta.
userId	string	Identificador exclusivo para o utilizador.

Respostas

Name	Tipo	Description
200 OK	AnswersResult	Uma resposta bem-sucedida para obter respostas de base de dados de conhecimento.
Other Status Codes	ErrorResponse	Resposta de erro.

Segurança

AADToken

Estes são os Fluxos OAuth2 do Azure Active Directory . Quando emparelhado com o controlo de acesso baseado em funções do Azure, pode ser utilizado para controlar o acesso às APIs REST Azure Maps. Os controlos de acesso baseados em funções do Azure são utilizados para designar o acesso a uma ou mais Azure Maps conta de recursos ou sub-recursos. Qualquer utilizador, grupo ou principal de serviço pode ter acesso através de uma função incorporada ou de uma função personalizada composta por uma ou mais permissões para Azure Maps APIs REST.

Para implementar cenários, recomendamos que veja os conceitos de autenticação. Em resumo, esta definição de segurança fornece uma solução para modelar aplicações através de objetos com capacidade de controlo de acesso em APIs e âmbitos específicos.

Notas

Esta definição de segurança requer a utilização do x-ms-client-id cabeçalho para indicar a que Azure Maps recurso a que a aplicação está a pedir acesso. Isto pode ser adquirido na API de gestão de Mapas.

O Authorization URL é específico da instância da cloud pública do Azure. As clouds soberanas têm URLs de Autorização exclusivos e configurações do Azure Active Directory. * O controlo de acesso baseado em funções do Azure está configurado a partir do plano de gestão do Azure através de portal do Azure, PowerShell, CLI, SDKs do Azure ou APIs REST. * A utilização do SDK Web Azure Maps permite a configuração baseada na configuração de uma aplicação para vários casos de utilização.

Atualmente, o Azure Active Directory v1.0 ou v2.0 suporta Trabalho, Escola e Convidados, mas não suporta contas pessoais.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

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

Ocp-Apim-Subscription-Key

Uma chave de subscrição para um recurso do Serviço de idiomas.

Type: apiKey
In: header

Exemplos

Successful query

Sample Request

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
}

Sample Response

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"
    }
  ]
}

Definições

Name	Description
AnswersOptions	Parâmetros para consultar uma base de dados de conhecimento.
AnswerSpan	Objeto de intervalo de respostas de FAQ.
AnswersResult	Representa a Lista de Respostas a Perguntas.
enable	Ativar ou desativar a predição do Answer Span.
Error	O objeto de erro.
ErrorCode	Código de erro legível por humanos.
ErrorResponse	Resposta de erro.
InnerErrorCode	Código de erro legível por humanos.
InnerErrorModel	Um objeto que contém informações mais específicas sobre o erro. De acordo com as diretrizes da Microsoft One API – https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
KnowledgeBaseAnswer	Representa base de dados de conhecimento resposta.
KnowledgeBaseAnswerContext	Objeto de contexto com informações de FAQ anteriores.
KnowledgeBaseAnswerDialog	Caixa de diálogo associada à Resposta.
KnowledgeBaseAnswerPrompt	Pedir uma resposta.
LogicalOperationKind	Defina como "OR" ou "AND" para utilizar a operação lógica correspondente.
MetadataFilter	Localize as FAQ associadas à lista de metadados especificada.
MetadataRecord	Objeto para fornecer o par de valores chave para cada metadados.
QueryFilters	filtra por base de dados de conhecimento.
RankerKind	Tipo de classificador a utilizar.
ShortAnswerOptions	Para configurar a funcionalidade de predição do Answer span.

AnswersOptions

Parâmetros para consultar uma base de dados de conhecimento.

Name	Tipo	Description
answerSpanRequest	ShortAnswerOptions	Para configurar a funcionalidade de predição do Answer span.
confidenceScoreThreshold	number	Classificação mínima de limiar para respostas, intervalos de valores de 0 a 1.
context	KnowledgeBaseAnswerContext	Objeto de contexto com informações de FAQ anteriores.
filters	QueryFilters	Filtre QnAs com base em determinadas origens de metadados e base de dados de conhecimento.
includeUnstructuredSources	boolean	(Opcional) Sinalizador para ativar a Consulta através de Origens Não Estruturadas.
qnaId	integer	ID de FAQ exato para obter a partir do base de dados de conhecimento, este campo tem prioridade sobre a pergunta.
question	string	Pergunta do utilizador para consultar o base de dados de conhecimento.
rankerType	RankerKind	Tipo de classificador a utilizar.
top	integer	Número máximo de respostas a devolver para a pergunta.
userId	string	Identificador exclusivo para o utilizador.

AnswerSpan

Objeto de intervalo de respostas de FAQ.

Name	Tipo	Description
confidenceScore	number	Classificação prevista do intervalo de respostas, intervalos de valores de 0 a 1.
length	integer	O comprimento do intervalo de respostas.
offset	integer	O desvio do intervalo de respostas desde o início da resposta.
text	string	Texto previsto do intervalo de respostas.

AnswersResult

Representa a Lista de Respostas a Perguntas.

Name	Tipo	Description
answers	KnowledgeBaseAnswer[]	Representa a lista Resultado da Resposta.

enable

Ativar ou desativar a predição do Answer Span.

Name	Tipo	Description
True	Boolean

Error

O objeto de erro.

Name	Tipo	Description
code	ErrorCode	Um dos conjuntos de códigos de erro definidos pelo servidor.
details	Error[]	Uma matriz de detalhes sobre erros específicos que levaram a este erro reportado.
innererror	InnerErrorModel	Um objeto que contém informações mais específicas do que o objeto atual sobre o erro.
message	string	Uma representação legível por humanos do erro.
target	string	O destino do erro.

ErrorCode

Código de erro legível por humanos.

Name	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

Resposta de erro.

Name	Tipo	Description
error	Error	O objeto de erro.

InnerErrorCode

Código de erro legível por humanos.

Name	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

Um objeto que contém informações mais específicas sobre o erro. De acordo com as diretrizes da Microsoft One API – https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Name	Tipo	Description
code	InnerErrorCode	Um dos conjuntos de códigos de erro definidos pelo servidor.
details	object	Detalhes do erro.
innererror	InnerErrorModel	Um objeto que contém informações mais específicas do que o objeto atual sobre o erro.
message	string	Mensagem de erro.
target	string	Destino do erro.

KnowledgeBaseAnswer

Representa base de dados de conhecimento resposta.

Name	Tipo	Description
answer	string	Responder ao texto.
answerSpan	AnswerSpan	Objeto de intervalo de respostas da FAQ relativamente à pergunta do utilizador.
confidenceScore	number	Responda à classificação de confiança, o valor varia entre 0 e 1.
dialog	KnowledgeBaseAnswerDialog	Caixa de diálogo associada à Resposta.
id	integer	ID do resultado do FAQ.
metadata	object	Metadados associados à resposta, úteis para categorizar ou filtrar respostas a perguntas.
questions	string[]	Lista de perguntas associadas à resposta.
source	string	Origem do resultado de FAQ.

KnowledgeBaseAnswerContext

Objeto de contexto com informações de FAQ anteriores.

Name	Tipo	Description
previousQnaId	integer	ID de QnA do resultado de resposta superior anterior.
previousUserQuery	string	Consulta de utilizador anterior.

KnowledgeBaseAnswerDialog

Caixa de diálogo associada à Resposta.

Name	Tipo	Description
isContextOnly	boolean	Para marcar se um pedido é relevante apenas com uma pergunta anterior ou não. Se for verdadeiro, não inclua este FAQ como resultado de pesquisa para consultas sem contexto; caso contrário, se for falso, ignora o contexto e inclui este FAQ no resultado da pesquisa.
prompts	KnowledgeBaseAnswerPrompt[]	Lista de pedidos associados à resposta.

KnowledgeBaseAnswerPrompt

Pedir uma resposta.

Name	Tipo	Description
displayOrder	integer	Índice da linha de comandos - utilizado na ordenação dos pedidos.
displayText	string	Texto apresentado para representar um pedido de perguntas de seguimento.
qnaId	integer	ID de FAQ correspondente ao pedido.

LogicalOperationKind

Defina como "OR" ou "AND" para utilizar a operação lógica correspondente.

Name	Tipo	Description
AND	string
OR	string

MetadataFilter

Localize as FAQ associadas à lista de metadados especificada.

Name	Tipo	Valor Predefinido	Description
logicalOperation	LogicalOperationKind	AND	Operação utilizada para associar filtros de metadados.
metadata	MetadataRecord[]		Objeto para fornecer o par de valores chave para cada metadados.

MetadataRecord

Objeto para fornecer o par de valores chave para cada metadados.

Name	Tipo	Description
key	string	Chave de Metadados do dicionário metadados utilizado no FAQ.
value	string	Valor de metadados do dicionário metadados utilizado no FAQ.

QueryFilters

filtra por base de dados de conhecimento.

Name	Tipo	Valor Predefinido	Description
logicalOperation	LogicalOperationKind	AND	Operação lógica utilizada para associar o filtro de metadados ao filtro de origem.
metadataFilter	MetadataFilter		Localize as FAQ associadas à lista de metadados especificada.
sourceFilter	string[]		Localize as FAQ associadas a qualquer uma das origens fornecidas no base de dados de conhecimento.

RankerKind

Tipo de classificador a utilizar.

Name	Tipo	Description
Default	string	Classificador predefinido.
QuestionOnly	string	Apenas classificador de perguntas.

ShortAnswerOptions

Para configurar a funcionalidade de predição do Answer span.

Name	Tipo	Description
confidenceScoreThreshold	number	Classificação mínima de limiar necessária para incluir um intervalo de respostas, os valores variam entre 0 e 1.
enable	enable	Ativar ou desativar a predição do Answer Span.
topAnswersWithSpan	integer	Número de respostas principais a considerar para a predição de span de 1 a 10.

Partilhar via