API prédéfinie

Article
12/19/2023

L’API prédéfinie de réponses aux questions personnalisées vous permet de répondre aux questions basées sur un passage de texte sans devoir créer de projets, conserver les paires questions-réponse ou engendrer des coûts pour une infrastructure sous-exploitée. Cette fonctionnalité fournie en tant qu’API peut être utilisée pour répondre aux besoins de questions et de réponses sans avoir à apprendre les détails des réponses aux questions personnalisées.

À partir d’une requête utilisateur et d’un bloc ou passage de texte, l’API retourne une réponse précise (si disponible).

Exemple d’utilisation de l’API

Imaginez que vous disposez d’un ou plusieurs blocs de texte dans lesquels vous souhaitez trouver des réponses à une question donnée. Normalement, vous auriez dû créer autant de sources qu’il y a de blocs de texte. En revanche, désormais, l’API prédéfinie vous permet d’interroger les blocs de texte sans avoir à définir des sources de contenu dans un projet.

Voici d’autres scénarios dans lesquels cette API peut être utilisée :

Application de lecteur de livre électronique permettant aux utilisateurs de mettre du texte en surbrillance, d’entrer une question et d’obtenir des réponses en relation avec un passage de texte sélectionné.
Extension de navigateur permettant aux utilisateurs de poser une question sur le contenu de la page affichée dans le navigateur.
Robot dédié à la santé qui accepte des requêtes d’utilisateurs et fournit des réponses basées sur le contenu médical que le bot identifie comme le plus pertinent.

Voici un exemple de demande :

Exemple de requête

POST https://{Unique-to-your-endpoint}.api.cognitive.microsoft.com/language/:query-text

Exemple de requête sur un seul bloc de texte

Corps de la demande

{
  "parameters": {
    "Endpoint": "{Endpoint}",
    "Ocp-Apim-Subscription-Key": "{API key}",
    "Content-Type": "application/json",
    "api-version": "2021-10-01",
    "stringIndexType": "TextElements_v8",
    "textQueryOptions": {
      "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"
    }
  }
}

Exemple de réponse

Dans le corps de la demande ci-dessus, nous effectuons une requête sur un bloc de texte. Un exemple de réponse reçue à cette requête figure ci-dessous.

{
"responses": {
    "200": {
      "headers": {},
      "body": {
        "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
          }
        ]
      }
    }
  }

Nous voyons que l’API propose plusieurs réponses. Chaque réponse est associée à un score de confiance spécifique qui permet d’en comprendre la pertinence. L’étendue de la réponse indique si une réponse rapide potentielle a été détectée. Les utilisateurs peuvent utiliser ce score de confiance pour déterminer les réponses à fournir en réponse à la requête.

Limites de l’API prédéfinie

Limites des appels d’API

Si vous devez utiliser des documents plus volumineux que la limite autorisée, vous pouvez scinder le texte en blocs de texte plus petits avant de les envoyer à l’API. Dans ce contexte, un document est une chaîne de caractères de texte unique définie.

Ces chiffres représentent les limites de chaque appel d’API :

Nombre de documents : 5.
Taille maximale d’un seul document : 5 120 caractères.
Trois réponses maximum par document.

Codes de langue pris en charge

Les codes de langue suivants sont pris en charge par l’API Prebuilt. Ces codes linguistiques sont conformes à la norme de codes ISO 639-1.

Code langue	Langage
af	Afrikaans
am	Amharique
ar	Arabe
as	Assamais
az	Azéri
ba	Bashkir
be	Biélorusse
bg	Bulgare
bn	Bengali
ca	Catalan, valencien
ckb	Kurde central
cs	Tchèque
cy	Gallois
da	Danois
de	Allemand
el	Grec, Moderne (1453–)
en	Anglais
Eo	Espéranto
es	Espagnol, castillan
et	Estonien
eu	Basque
fa	Persan
fi	Finnois
fr	Français
ga	Irlandais
gl	Galicien
gu	Goudjrati
he	Hébreu
hi	Hindi
heure(s)	Croate
hu	Hongrois
hy	Arménien
id	Indonésien
is	Islandais
it	Italien
ja	Japonais
ka	Géorgien
kk	Kazakh
km	Khmer central
kn	Kannada
ko	Coréen
ky	Kirghiz, Kirghiz
la	Latin
lo	Lao
lt	Lituanien
lv	Letton
mk	Macédonien
ml	Malayalam
mn	Mongol
mr	Marathi
ms	Malais
mt	Maltais
my	Birman
ne	Népalais
nl	Néerlandais, flamand
nn	Norvégien (Nynorsk)
non	Norvégien
or	Odia
pa	Pendjabi, penjabi
pl	Polonais
ps	Pachto, pachtou
pt	Portugais
ro	Roumain
ru	Russe
SA	Sanskrit
sd	Sindhi
si	Singhalais, cingalais
sk	Slovaque
sl	Slovène
sq	Albanais
sr	Serbe
sv	Suédois
sw	Swahili
ta	Tamoul
te	Télougou
tg	Tadjik
th	Thaï
tl	Tagalog
tr	Turc
tt	Tatar
ug	Uighur, Uyghur
uk	Ukrainien
ur	Ourdou
uz	Ouzbek
vi	Vietnamien
yi	Yiddish
zh	Chinois

Référence de l’API prédéfinie

Pour comprendre les paramètres d’entrée et de sortie requis pour appeler l’API, consultez la documentation regroupant les exemples de l’API prédéfinie.

Partage via