Question Answering - Get Answers From Text

Riferimento

Servizio:: Cognitive Services - Language

Versione API:: 2023-04-01

Risponde alla domanda specificata usando il testo specificato nel corpo.

POST {Endpoint}/language/:query-text?api-version=2023-04-01

Parametri dell'URI

Nome	In	Necessario	Tipo	Descrizione
Endpoint	path	True	string	Endpoint servizi cognitivi supportati (ad esempio, https://.api.cognitiveservices.azure.com).
api-version	query	True	string	Versione API client.

Corpo della richiesta

Nome	Necessario	Tipo	Descrizione
question	True	string	Domanda dell'utente per eseguire query sui record di testo specificati.
records	True	TextDocument[]	Record di testo da cercare per una determinata domanda.
language		string	Lingua dei record di testo. Si tratta della rappresentazione BCP-47 di una lingua. Ad esempio, usare "en" per l'inglese; "es" per spagnolo e così via. Se non è impostato, usare "en" per l'inglese come impostazione predefinita.
stringIndexType		StringIndexType	Specifica il metodo usato per interpretare gli offset di stringa. Il valore predefinito viene impostato su Elementi di testo (Graphemes) in base a Unicode v8.0.0. Per ulteriori informazioni, vedere https://aka.ms/text-analytics-offsets.

Risposte

Nome	Tipo	Descrizione
200 OK	AnswersFromTextResult	Risposta riuscita per ottenere risposte dal testo di input.
Other Status Codes	ErrorResponse	Risposta di errore.

Sicurezza

AADToken

Si tratta dei flussi OAuth2 di Azure Active Directory . Quando è associato al controllo degli accessi in base al ruolo di Azure, può essere usato per controllare l'accesso alle API REST Mappe di Azure. I controlli di accesso basati sul ruolo di Azure vengono usati per designare l'accesso a uno o più Mappe di Azure account delle risorse o alle sotto-risorse. Qualsiasi utente, gruppo o entità servizio può essere concesso l'accesso tramite un ruolo predefinito o un ruolo personalizzato composto da una o più autorizzazioni per Mappe di Azure API REST.

Per implementare scenari, è consigliabile visualizzare i concetti di autenticazione. In riepilogo, questa definizione di sicurezza offre una soluzione per la modellazione di applicazioni tramite oggetti in grado di controllare l'accesso in API e ambiti specifici.

Note

Questa definizione di sicurezza richiede l'uso dell'intestazione x-ms-client-id per indicare quale Mappe di Azure risorsa a cui l'applicazione richiede l'accesso. Questa operazione può essere acquisita dall'API di gestione mappe.

L'oggetto Authorization URL è specifico dell'istanza del cloud pubblico di Azure. I cloud sovrani dispongono di URL di autorizzazione univoci e configurazioni di Azure Active Directory. * Il controllo degli accessi in base al ruolo di Azure viene configurato dal piano di gestione di Azure tramite portale di Azure, PowerShell, interfaccia della riga di comando, SDK di Azure o API REST. * L'utilizzo dell'SDK Web Mappe di Azure consente la configurazione basata sulla configurazione di un'applicazione per più casi d'uso.

Attualmente, Azure Active Directory v1.0 o v2.0 supporta Work, School e Guest, ma non supporta gli account Personali.

Tipo: oauth2
Flow: implicit
URL di autorizzazione: https://login.microsoftonline.com/common/oauth2/authorize

Ambiti

Nome	Descrizione
https://cognitiveservices.azure.com/.default	https://cognitiveservices.azure.com/.default

Ocp-Apim-Subscription-Key

Chiave di sottoscrizione per una risorsa del servizio lingua.

Tipo: apiKey
In: header

Esempio

Successful query

Esempio di richiesta

HTTP

POST {Endpoint}/language/:query-text?api-version=2023-04-01

{
  "question": "how long it takes to charge surface?",
  "records": [
    {
      "id": "1",
      "text": "Power and charging. It 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."
    },
    {
      "id": "2",
      "text": "You 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."
    }
  ],
  "language": "en"
}

Risposta di esempio

Codice di stato:: 200

{
  "answers": [
    {
      "answer": "Power and charging. It 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.",
      "confidenceScore": 0.93,
      "id": "1",
      "answerSpan": {
        "text": "two to four hours",
        "confidenceScore": 0,
        "offset": 28,
        "length": 45
      },
      "offset": 0,
      "length": 224
    },
    {
      "answer": "It 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.",
      "confidenceScore": 0.92,
      "id": "1",
      "answerSpan": {
        "text": "two to four hours",
        "confidenceScore": 0,
        "offset": 8,
        "length": 25
      },
      "offset": 20,
      "length": 224
    },
    {
      "answer": "It can take longer if you’re using your Surface for power-intensive activities like gaming or video streaming while you’re charging it.",
      "confidenceScore": 0.05,
      "id": "1",
      "answerSpan": null,
      "offset": 110,
      "length": 244
    }
  ]
}

Definizioni

Nome	Descrizione
AnswersFromTextOptions	Parametri di record di testo e domanda da rispondere.
AnswersFromTextResult	Rappresenta i risultati della risposta.
AnswerSpan	Oggetto di intervallo di risposte di QnA.
Error	Oggetto error.
ErrorCode	Codice di errore leggibile dall'utente.
ErrorResponse	Risposta di errore.
InnerErrorCode	Codice di errore leggibile dall'utente.
InnerErrorModel	Oggetto contenente informazioni più specifiche sull'errore. In base alle linee guida per l'API Microsoft One - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
StringIndexType	Specifica il metodo usato per interpretare gli offset di stringa. Il valore predefinito viene impostato su Elementi di testo (Graphemes) in base a Unicode v8.0.0. Per ulteriori informazioni, vedere https://aka.ms/text-analytics-offsets.
TextAnswer	Rappresenta il risultato della risposta.
TextDocument	Rappresentare il record di testo di input da eseguire una query.

AnswersFromTextOptions

Parametri di record di testo e domanda da rispondere.

Nome	Tipo	Valore predefinito	Descrizione
language	string		Lingua dei record di testo. Si tratta della rappresentazione BCP-47 di una lingua. Ad esempio, usare "en" per l'inglese; "es" per spagnolo e così via. Se non è impostato, usare "en" per l'inglese come impostazione predefinita.
question	string		Domanda dell'utente per eseguire query sui record di testo specificati.
records	TextDocument[]		Record di testo da cercare per una determinata domanda.
stringIndexType	StringIndexType	TextElements_v8	Specifica il metodo usato per interpretare gli offset di stringa. Il valore predefinito viene impostato su Elementi di testo (Graphemes) in base a Unicode v8.0.0. Per ulteriori informazioni, vedere https://aka.ms/text-analytics-offsets.

AnswersFromTextResult

Rappresenta i risultati della risposta.

Nome	Tipo	Descrizione
answers	TextAnswer[]	Rappresenta i risultati della risposta.

AnswerSpan

Oggetto di intervallo di risposte di QnA.

Nome	Tipo	Descrizione
confidenceScore	number	Punteggio stimato dell'intervallo di risposte, il valore è compreso tra 0 e 1.
length	integer	Lunghezza dell'intervallo di risposta.
offset	integer	Offset della risposta dall'inizio della risposta.
text	string	Testo stimato dell'intervallo di risposte.

Error

Oggetto error.

Nome	Tipo	Descrizione
code	ErrorCode	Uno di un set definito dal server di codici di errore.
details	Error[]	Matrice di dettagli sugli errori specifici che hanno causato l'errore segnalato.
innererror	InnerErrorModel	Oggetto contenente informazioni più specifiche dell'oggetto corrente sull'errore.
message	string	Rappresentazione leggibile dell'errore.
target	string	Destinazione dell'errore.

ErrorCode

Codice di errore leggibile dall'utente.

Nome	Tipo	Descrizione
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

Risposta di errore.

Nome	Tipo	Descrizione
error	Error	Oggetto error.

InnerErrorCode

Codice di errore leggibile dall'utente.

Nome	Tipo	Descrizione
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

Oggetto contenente informazioni più specifiche sull'errore. In base alle linee guida per l'API Microsoft One - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.

Nome	Tipo	Descrizione
code	InnerErrorCode	Uno di un set definito dal server di codici di errore.
details	object	Dettagli degli errori.
innererror	InnerErrorModel	Oggetto contenente informazioni più specifiche dell'oggetto corrente sull'errore.
message	string	Messaggio di errore.
target	string	Destinazione errore.

StringIndexType

Specifica il metodo usato per interpretare gli offset di stringa. Il valore predefinito viene impostato su Elementi di testo (Graphemes) in base a Unicode v8.0.0. Per ulteriori informazioni, vedere https://aka.ms/text-analytics-offsets.

Nome	Tipo	Descrizione
TextElements_v8	string	I valori di offset e lunghezza restituiti corrispondono ai cluster TextElements (Graphemes e Grapheme) confermando lo standard Unicode 8.0.0. Usare questa opzione se l'applicazione è scritta in .Net Framework o .NET Core e si userà StringInfo.
UnicodeCodePoint	string	I valori di offset e lunghezza restituiti corrispondono ai punti di codice Unicode. Usare questa opzione se l'applicazione è scritta in un linguaggio che supporta Unicode, ad esempio Python.
Utf16CodeUnit	string	I valori di offset e lunghezza restituiti corrispondono alle unità di codice UTF-16. Usare questa opzione se l'applicazione è scritta in un linguaggio che supporta Unicode, ad esempio JavaScript.

TextAnswer

Rappresenta il risultato della risposta.

Nome	Tipo	Descrizione
answer	string	Risposta.
answerSpan	AnswerSpan	Oggetto span di risposte rispetto alla domanda dell'utente.
confidenceScore	number	punteggio di attendibilità della risposta, il valore è compreso tra 0 e 1.
id	string	ID record.
length	integer	Lunghezza della frase.
offset	integer	Offset della frase dall'inizio del documento.

TextDocument

Rappresentare il record di testo di input da eseguire una query.

Nome	Tipo	Descrizione
id	string	Identificatore univoco per il record di testo.
text	string	Contenuto del testo del record.

Condividi tramite

Question Answering - Get Answers From Text

Parametri dell'URI

Corpo della richiesta

Risposte

Sicurezza

AADToken

Note

Ambiti

Ocp-Apim-Subscription-Key

Esempio

Successful query

Esempio di richiesta

Risposta di esempio

Definizioni

AnswersFromTextOptions

AnswersFromTextResult

AnswerSpan

Error

ErrorCode

ErrorResponse

InnerErrorCode

InnerErrorModel

StringIndexType

TextAnswer

TextDocument

Risorse aggiuntive