Question Answering - Get Answers

Service:

Cognitive Services

API Version:

2021-10-01

기술 자료 사용하여 지정된 질문에 답변합니다.

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

URI 매개 변수

Name	In(다음 안에)	필수	형식	Description
Endpoint	path	True	string	지원되는 Cognitive Services 엔드포인트(예: https://.api.cognitiveservices.azure.com).
api-version	query	True	string	클라이언트 API 버전입니다.
deploymentName	query	True	string	사용할 프로젝트의 특정 배포 이름입니다.
projectName	query	True	string	사용할 프로젝트의 이름입니다.

요청 헤더

Name	필수	형식	Description
Ocp-Apim-Subscription-Key	True	string

요청 본문

Name	형식	Description
answerSpanRequest	ShortAnswerOptions	응답 범위 예측 기능을 구성하려면
confidenceScoreThreshold	number	답변에 대한 최소 임계값 점수이며 값 범위는 0에서 1까지입니다.
context	KnowledgeBaseAnswerContext	이전 QnA 정보가 있는 컨텍스트 개체입니다.
filters	QueryFilters	지정된 메타데이터 목록 및 기술 자료 원본에 따라 QnA를 필터링합니다.
includeUnstructuredSources	boolean	(선택 사항) 구조화되지 않은 원본을 통해 쿼리를 사용하도록 설정하는 플래그입니다.
qnaId	integer	기술 자료 가져올 정확한 QnA ID입니다. 이 필드는 질문보다 우선합니다.
question	string	기술 자료 대해 쿼리할 사용자 질문입니다.
rankerType	RankerKind	사용할 순위의 유형입니다.
top	integer	질문에 대해 반환할 최대 답변 수입니다.
userId	string	사용자의 고유 식별자입니다.

응답

Name	형식	Description
200 OK	AnswersResult	기술 자료 답변을 얻기 위한 성공적인 응답입니다.
Other Status Codes	ErrorResponse	오류 응답입니다.

보안

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

예제

Successful query

Sample Request

HTTP

POST {Endpoint}/language/:query-knowledgebases?projectName=proj1&deploymentName=production&api-version=2021-10-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"
    }
  ]
}

정의

Name	Description
AnswersOptions	기술 자료 쿼리할 매개 변수입니다.
AnswerSpan	QnA의 응답 범위 개체입니다.
AnswersResult	질문 답변 목록을 나타냅니다.
enable	응답 범위 예측을 사용하거나 사용하지 않도록 설정합니다.
Error	Error 개체.
ErrorCode	사람이 읽을 수 있는 오류 코드입니다.
ErrorResponse	오류 응답입니다.
InnerErrorCode	사람이 읽을 수 있는 오류 코드입니다.
InnerErrorModel	오류에 대한 보다 구체적인 정보를 포함하는 개체입니다. Microsoft One API 지침에 따라 - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
KnowledgeBaseAnswer	기술 자료 답변을 나타냅니다.
KnowledgeBaseAnswerContext	이전 QnA 정보가 있는 컨텍스트 개체입니다.
KnowledgeBaseAnswerDialog	Answer와 연결된 대화 상자입니다.
KnowledgeBaseAnswerPrompt	답변을 묻는 메시지를 표시합니다.
LogicalOperationKind	해당 논리 작업을 사용하기 위해 'OR' 또는 'AND'로 설정합니다.
MetadataFilter	지정된 메타데이터 목록과 연결된 QnA를 찾습니다.
MetadataRecord	각 메타데이터에 대한 키 값 쌍을 제공하는 개체입니다.
QueryFilters	기술 자료 통해 필터링합니다.
RankerKind	사용할 순위의 유형입니다.
ShortAnswerOptions	응답 범위 예측 기능을 구성하려면

AnswersOptions

기술 자료 쿼리할 매개 변수입니다.

Name	형식	Description
answerSpanRequest	ShortAnswerOptions	응답 범위 예측 기능을 구성하려면
confidenceScoreThreshold	number	답변에 대한 최소 임계값 점수이며 값 범위는 0에서 1까지입니다.
context	KnowledgeBaseAnswerContext	이전 QnA 정보가 있는 컨텍스트 개체입니다.
filters	QueryFilters	지정된 메타데이터 목록 및 기술 자료 원본에 따라 QnA를 필터링합니다.
includeUnstructuredSources	boolean	(선택 사항) 구조화되지 않은 원본을 통해 쿼리를 사용하도록 설정하는 플래그입니다.
qnaId	integer	기술 자료 가져올 정확한 QnA ID입니다. 이 필드는 질문보다 우선합니다.
question	string	기술 자료 대해 쿼리할 사용자 질문입니다.
rankerType	RankerKind	사용할 순위의 유형입니다.
top	integer	질문에 대해 반환할 최대 답변 수입니다.
userId	string	사용자의 고유 식별자입니다.

AnswerSpan

QnA의 응답 범위 개체입니다.

Name	형식	Description
confidenceScore	number	예측된 응답 범위 점수, 값 범위는 0에서 1까지입니다.
length	integer	응답 범위의 길이입니다.
offset	integer	답변 시작부터의 응답 범위 오프셋입니다.
text	string	응답 범위의 예측 텍스트입니다.

AnswersResult

질문 답변 목록을 나타냅니다.

Name	형식	Description
answers	KnowledgeBaseAnswer[]	응답 결과 목록을 나타냅니다.

enable

응답 범위 예측을 사용하거나 사용하지 않도록 설정합니다.

Name	형식	Description
True	Boolean

Error

Error 개체.

Name	형식	Description
code	ErrorCode	서버 정의 오류 코드 집합 중 하나입니다.
details	Error[]	이 보고된 오류로 이어진 특정 오류에 대한 세부 정보 배열입니다.
innererror	InnerErrorModel	오류에 대한 현재 개체보다 더 구체적인 정보를 포함하는 개체입니다.
message	string	사람이 읽을 수 있는 오류 표현입니다.
target	string	오류의 대상입니다.

ErrorCode

사람이 읽을 수 있는 오류 코드입니다.

Name	형식	Description
AzureCognitiveSearchIndexLimitReached	string
AzureCognitiveSearchIndexNotFound	string
AzureCognitiveSearchNotFound	string
AzureCognitiveSearchThrottling	string
Forbidden	string
InternalServerError	string
InvalidArgument	string
InvalidRequest	string
NotFound	string
OperationNotFound	string
ProjectNotFound	string
ServiceUnavailable	string
TooManyRequests	string
Unauthorized	string

ErrorResponse

오류 응답입니다.

Name	형식	Description
error	Error	Error 개체.

InnerErrorCode

사람이 읽을 수 있는 오류 코드입니다.

Name	형식	Description
AzureCognitiveSearchNotFound	string
AzureCognitiveSearchThrottling	string
ExtractionFailure	string
InvalidParameterValue	string
InvalidRequest	string
KnowledgeBaseNotFound	string

InnerErrorModel

오류에 대한 보다 구체적인 정보를 포함하는 개체입니다. Microsoft One API 지침에 따라 - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Name	형식	Description
code	InnerErrorCode	서버 정의 오류 코드 집합 중 하나입니다.
details	object	오류 세부 정보입니다.
innererror	InnerErrorModel	오류에 대한 현재 개체보다 더 구체적인 정보를 포함하는 개체입니다.
message	string	오류 메시지입니다.
target	string	오류 대상입니다.

KnowledgeBaseAnswer

기술 자료 답변을 나타냅니다.

Name	형식	Description
answer	string	텍스트에 응답합니다.
answerSpan	AnswerSpan	사용자의 질문에 대한 QnA의 응답 범위 개체입니다.
confidenceScore	number	답변 신뢰도 점수, 값 범위는 0에서 1까지입니다.
dialog	KnowledgeBaseAnswerDialog	Answer와 연결된 대화 상자입니다.
id	integer	QnA 결과의 ID입니다.
metadata	object	답변과 연결된 메타데이터로, 질문 답변을 분류하거나 필터링하는 데 유용합니다.
questions	string[]	답변과 관련된 질문 목록입니다.
source	string	QnA 결과의 원본입니다.

KnowledgeBaseAnswerContext

이전 QnA 정보가 있는 컨텍스트 개체입니다.

Name	형식	Description
previousQnaId	integer	이전 턴 상위 응답 결과 QnA ID입니다.
previousUserQuery	string	이전 사용자 쿼리.

KnowledgeBaseAnswerDialog

Answer와 연결된 대화 상자입니다.

Name	형식	Description
isContextOnly	boolean	프롬프트가 이전 질문과만 관련이 있는지 여부를 표시합니다. true이면 컨텍스트가 없는 쿼리에 대한 검색 결과로 이 QnA를 포함하지 마세요. 그렇지 않으면 false이면 컨텍스트를 무시하고 검색 결과에 이 QnA를 포함합니다.
prompts	KnowledgeBaseAnswerPrompt[]	답변과 연결된 프롬프트 목록입니다.

KnowledgeBaseAnswerPrompt

답변을 묻는 메시지를 표시합니다.

Name	형식	Description
displayOrder	integer	프롬프트의 인덱스 - 프롬프트 순서에 사용됩니다.
displayText	string	후속 질문 프롬프트를 나타내기 위해 표시되는 텍스트입니다.
qnaId	integer	프롬프트에 해당하는 QnA ID입니다.

LogicalOperationKind

해당 논리 작업을 사용하기 위해 'OR' 또는 'AND'로 설정합니다.

Name	형식	Description
AND	string
OR	string

MetadataFilter

지정된 메타데이터 목록과 연결된 QnA를 찾습니다.

Name	형식	기본값	Description
logicalOperation	LogicalOperationKind	AND	메타데이터 필터를 조인하는 데 사용되는 작업입니다.
metadata	MetadataRecord[]		각 메타데이터에 대한 키 값 쌍을 제공하는 개체입니다.

MetadataRecord

각 메타데이터에 대한 키 값 쌍을 제공하는 개체입니다.

Name	형식	Description
key	string	QnA에 사용되는 메타데이터 사전의 메타데이터 키입니다.
value	string	QnA에 사용되는 메타데이터 사전의 메타데이터 값입니다.

QueryFilters

기술 자료 통해 필터링합니다.

Name	형식	기본값	Description
logicalOperation	LogicalOperationKind	AND	메타데이터 필터를 원본 필터와 조인하는 데 사용되는 논리적 작업입니다.
metadataFilter	MetadataFilter		지정된 메타데이터 목록과 연결된 QnA를 찾습니다.
sourceFilter	string[]		기술 자료 지정된 원본 목록과 연결된 QnA를 찾습니다.

RankerKind

사용할 순위의 유형입니다.

Name	형식	Description
Default	string	기본 순위입니다.
QuestionOnly	string	질문 전용 순위입니다.

ShortAnswerOptions

응답 범위 예측 기능을 구성하려면

Name	형식	Description
confidenceScoreThreshold	number	응답 범위를 포함하는 데 필요한 최소 임계값 점수이며 값 범위는 0에서 1까지입니다.
enable	enable	응답 범위 예측을 사용하거나 사용하지 않도록 설정합니다.
topAnswersWithSpan	integer	범위 예측에 대해 고려할 상위 답변 수(1에서 10까지)입니다.