Question Answering - Get Answers

참조

서비스:: Azure AI Services

API 버전:: 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 (double) minimum: 0 maximum: 1	답변에 대한 최소 임계값 점수, 값 범위는 0에서 1까지입니다.
context	KnowledgeBaseAnswerContext	이전 QnA 정보가 있는 컨텍스트 개체입니다.
filters	QueryFilters	지정된 메타데이터 목록 및 기술 자료 원본에 따라 QnA를 필터링합니다.
includeUnstructuredSources	boolean	(선택 사항) 구조화되지 않은 원본을 통해 쿼리를 사용하도록 설정하는 플래그입니다.
qnaId	integer (int32)	기술 자료에서 가져올 정확한 QnA ID입니다. 이 필드는 질문보다 우선합니다.
question	string	기술 자료에 대해 쿼리할 사용자 질문입니다.
rankerType	RankerKind	사용할 순위의 유형입니다.
top	integer (int32)	질문에 대해 반환할 최대 답변 수입니다.
userId	string	사용자의 고유 식별자입니다.

응답

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

보안

Ocp-Apim-Subscription-Key

형식: apiKey
In(다음 안에): header

예제

Successful query

샘플 요청

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
}

샘플 응답

상태 코드:: 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	오류 개체입니다.
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	답변과 연결된 대화 상자입니다.
KnowledgeBaseAnswerPrompt	답변을 묻는 메시지를 표시합니다.
LogicalOperationKind	해당 논리 작업을 사용하려면 'OR' 또는 'AND'로 설정합니다.
MetadataFilter	지정된 메타데이터 목록과 연결된 QnA를 찾습니다.
MetadataRecord	각 메타데이터에 대한 키 값 쌍을 제공하는 개체입니다.
QueryFilters	는 기술 자료를 통해 필터링합니다.
RankerKind	사용할 순위의 유형입니다.
ShortAnswerOptions	응답 범위 예측 기능을 구성하려면

AnswersOptions

Object

기술 자료를 쿼리하는 매개 변수입니다.

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

AnswerSpan

Object

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

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

AnswersResult

Object

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

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

enable

열거형

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

값	Description
True

Error

Object

오류 개체입니다.

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

ErrorCode

열거형

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

값	Description
AzureCognitiveSearchIndexLimitReached
AzureCognitiveSearchIndexNotFound
AzureCognitiveSearchNotFound
AzureCognitiveSearchThrottling
Forbidden
InternalServerError
InvalidArgument
InvalidRequest
NotFound
OperationNotFound
ProjectNotFound
ServiceUnavailable
TooManyRequests
Unauthorized

ErrorResponse

Object

오류 응답입니다.

Name	형식	Description
error	Error	오류 개체입니다.

InnerErrorCode

열거형

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

값	Description
AzureCognitiveSearchNotFound
AzureCognitiveSearchThrottling
ExtractionFailure
InvalidParameterValue
InvalidRequest
KnowledgeBaseNotFound

InnerErrorModel

Object

오류에 대한 보다 구체적인 정보를 포함하는 개체입니다. 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

Object

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

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

KnowledgeBaseAnswerContext

Object

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

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

KnowledgeBaseAnswerDialog

Object

답변과 연결된 대화 상자입니다.

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

KnowledgeBaseAnswerPrompt

Object

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

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

LogicalOperationKind

열거형

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

값	Description
AND
OR

MetadataFilter

Object

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

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

MetadataRecord

Object

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

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

QueryFilters

Object

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

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

RankerKind

열거형

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

값	Description
Default	기본 순위입니다.
QuestionOnly	질문만 순위입니다.

ShortAnswerOptions

Object

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

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

다음을 통해 공유

Question Answering - Get Answers

URI 매개 변수

요청 헤더

요청 본문

응답

보안

Ocp-Apim-Subscription-Key

예제

Successful query

샘플 요청

샘플 응답

정의

AnswersOptions

AnswerSpan

AnswersResult

enable

Error

ErrorCode

ErrorResponse

InnerErrorCode

InnerErrorModel

KnowledgeBaseAnswer

KnowledgeBaseAnswerContext

KnowledgeBaseAnswerDialog

KnowledgeBaseAnswerPrompt

LogicalOperationKind

MetadataFilter

MetadataRecord

QueryFilters

RankerKind

ShortAnswerOptions

추가 리소스