API predefinida
A API predefinida de respostas às perguntas personalizadas fornece a capacidade de responder a perguntas com base em uma passagem de texto sem precisar criar projetos, manter pares de perguntas e respostas ou incorrer em custos com infraestrutura subutilizada. Essa funcionalidade é fornecida como uma API e pode ser usada para atender às necessidades de perguntas e respostas sem precisar aprender os detalhes sobre as respostas às perguntas personalizadas.
Dada uma consulta de usuário e um bloco de texto/passagem, a API retornará uma resposta e uma resposta precisa (se disponível).
Exemplo de uso da API
Imagine que você tenha um ou mais blocos de texto dos quais você gostaria de obter respostas para uma determinada pergunta. Normalmente, você teria que criar tantas fontes quanto o número de blocos de texto. No entanto, agora com a API predefinida, você pode consultar os blocos de texto sem precisar definir fontes de conteúdo em um projeto.
Alguns outros cenários em que essa API pode ser usada são:
- Você está desenvolvendo um aplicativo de leitor de ebook para usuários finais que permite realçar textos, inserir pergunta e encontrar respostas em uma passagem realçada de texto.
- Uma extensão de navegador que permite aos usuários fazer uma pergunta sobre o conteúdo que está sendo exibido atualmente na página do navegador.
- Um bot de integridade que usa consultas de usuários e fornece respostas com base no conteúdo médico que o bot identifica como mais relevante para a consulta do usuário.
Abaixo está um exemplo de uma solicitação de exemplo:
Solicitação de exemplo
POST https://{Unique-to-your-endpoint}.api.cognitive.microsoft.com/language/:query-text
Exemplo de consulta em apenas um bloco de texto
Corpo da solicitação
{
"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"
}
}
}
Resposta de exemplo
No corpo da solicitação acima, consultamos um único bloco de texto. Uma resposta de exemplo recebida para a consulta acima é mostrada abaixo,
{
"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
}
]
}
}
}
Vemos que várias respostas são recebidas como parte da resposta da API. Cada resposta tem uma pontuação de confiança específica que ajuda a entender a relevância geral da resposta. O intervalo de respostas indica se uma resposta curta possível também foi detectada. Os usuários podem fazer uso dessa pontuação de confiança para determinar quais respostas fornecer em resposta à consulta.
Limites da API predefinida
Limites de chamadas à API
Se você precisa usar documentos maiores do que o limite permitido, é possível dividir o texto em partes menores antes de enviá-los para a API. Nesse contexto, um documento é apenas uma cadeia de caracteres de texto definida.
Esses números representam os limites por chamada à API individual:
- Número de documentos: 5.
- Tamanho máximo de um documento: 5.120 caracteres.
- Máximo de três respostas por documento.
Códigos de idioma com suporte
Os códigos de idioma a seguir têm suporte na API predefinida. Esses códigos de linguagem estão de acordo com o padrão de códigos ISO 639-1.
| Código de idioma | Linguagem |
|---|---|
| af | Africâner |
| am | Amárico |
| ar | Árabe |
| as | Assamês |
| az | Azerbaidjano |
| ba | Bashkir |
| be | Bielorrusso |
| bg | Búlgaro |
| bn | Bengali |
| ca | Catalão, valenciano |
| ckb | Curdo Central |
| cs | Tcheco |
| cy | Galês |
| da | Dinamarquês |
| de | Alemão |
| el | Grego, moderno (1453–) |
| en | Inglês |
| eo | Esperanto |
| es | Espanhol, castelhano |
| et | Estoniano |
| eu | Basco |
| fa | Persa |
| fi | Finlandês |
| fr | Francês |
| ga | Irlandês |
| gl | Galego |
| gu | Guzerate |
| he | Hebraico |
| hi | Híndi |
| h | Croata |
| hu | Húngaro |
| hy | Armênia |
| id | Indonésio |
| está | Islandês |
| it | Italiano |
| ja | Japonês |
| ka | Georgiano |
| kk | Cazaque |
| km | Khmer Central |
| kn | canarim |
| ko | Coreano |
| ky | Quirguistão, quirguiz |
| la | Latim |
| lo | Lao |
| lt | Lituano |
| lv | Letão |
| mk | Macedônio |
| ml | Malaiala |
| mn | Mongol |
| mr | Marati |
| ms | Malaio |
| mt | Maltês |
| my | Birmanês |
| ne | Nepali |
| nl | Holandês; Flamengo |
| nn | Norueguês Nynorsk |
| não | Norueguês |
| or | Oriá |
| pa | Punjabi, panjabi |
| pl | Polonês |
| ps | Pashto, pastó |
| pt | Português |
| ro | Romeno |
| ru | Russo |
| sa | Sânscrito |
| sd | Sindhi |
| si | Cingalês, cingalês |
| sk | Eslovaco |
| sl | Esloveno |
| sq | Albanês |
| sr | Sérvio |
| sv | Sueco |
| sw | Swahili |
| ta | Tâmil |
| te | Télugo |
| tg | Tajik |
| th | Tailandês |
| tl | Tagalo |
| tr | Turco |
| tt | Tártaro |
| ug | Uigur |
| uk | Ucraniano |
| ur | Urdu |
| uz | Uzbek |
| vi | Vietnamita |
| yi | Iídiche |
| zh | Chinês |
Referência de API Predefinida
Visite a documentação de exemplos da API predefinida completa para entender os parâmetros de entrada e saída necessários para chamar a API.