Biblioteca de clientes de Respostas às Perguntas do Serviço de Linguagem Cognitiva do Azure para Python – versão 1.1.0

Artigo
04/05/2023

Respostas a perguntas é um serviço de API baseado em nuvem que permite criar uma camada de perguntas e respostas conversacionais sobre os dados existentes. Use-o para criar uma base de dados de conhecimento extraindo perguntas e respostas de seu conteúdo semiestruturado, incluindo perguntas frequentes, manuais e documentos. Responda às perguntas dos usuários com as melhores respostas dos QnAs em seu base de dados de conhecimento automaticamente. Sua base de dados de conhecimento também fica mais inteligente, pois aprende continuamente com o comportamento dos usuários.

Código-fonte | Pacote (PyPI) | Documentação | de referência da API Documentação do produto | Amostras

Aviso de isenção de responsabilidade

O suporte a pacotes python do SDK do Azure para Python 2.7 terminou em 01 de janeiro de 2022. Para obter mais informações e tirar dúvidas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691

Introdução

Pré-requisitos

É necessário ter o Python 3.7 ou posterior para usar esse pacote.
Uma assinatura do Azure
Um recurso do Serviço de Linguagem

Instalar o pacote

Instale a biblioteca de clientes de Respostas a Perguntas do Azure para Python com pip:

pip install azure-ai-language-questionanswering

Observação: essa versão da biblioteca de clientes usa como padrão a versão 2021-10-01da API de serviço .

Autenticar o cliente

Para interagir com o serviço de Respostas a Perguntas, você precisará criar uma instância da classe QuestionAnsweringClient ou uma instância do AuthoringClient para gerenciar projetos em seu recurso. Você precisará de um ponto de extremidade e uma chave de API para instanciar um objeto cliente. Para obter mais informações sobre como autenticar com os Serviços Cognitivos, consulte Autenticar solicitações nos Serviços Cognitivos do Azure.

Obter uma chave de API

Você pode obter o ponto de extremidade e uma chave de API do recurso Idioma no Portal do Azure.

Como alternativa, use o comando da CLI do Azure mostrado abaixo para obter a chave de API do recurso De linguagem.

az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name>

Criar QuestionAnsweringClient

Depois de determinar o ponto de extremidade e a chave de API , você poderá instanciar um QuestionAnsweringClient:

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering import QuestionAnsweringClient

endpoint = "https://{myaccount}.api.cognitive.microsoft.com"
credential = AzureKeyCredential("{api-key}")

client = QuestionAnsweringClient(endpoint, credential)

Criar AuthoringClient

Com o ponto de extremidade e a chave de API, você pode criar uma instância de AuthoringClient:

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

endpoint = "https://{myaccount}.api.cognitive.microsoft.com"
credential = AzureKeyCredential("{api-key}")

client = AuthoringClient(endpoint, credential)

Criar um cliente com uma Credencial do Azure Active Directory

Para usar uma credencial de token do AAD (Azure Active Directory), forneça uma instância do tipo de credencial desejado obtido da biblioteca azure-identity . Observe que os pontos de extremidade regionais não dão suporte à autenticação do AAD. Crie um nome de subdomínio personalizado para o recurso para usar esse tipo de autenticação.

A autenticação com o AAD requer alguma configuração inicial:

Instalar azure-identity
Registrar um novo aplicativo do AAD
Conceda acesso ao serviço de Linguagem atribuindo a função "Leitor de Linguagem dos Serviços Cognitivos" à sua entidade de serviço.

Após a instalação, você pode escolher qual tipo de credencial do azure.identity usar. Por exemplo, DefaultAzureCredential pode ser usado para autenticar o cliente:

Defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Use a credencial de token retornada para autenticar o cliente:

from azure.ai.language.questionanswering import QuestionAnsweringClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
client = QuestionAnsweringClient(endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/", credential=credential)

Principais conceitos

QuestionAnsweringClient

O QuestionAnsweringClient é a interface principal para fazer perguntas usando um base de dados de conhecimento com suas próprias informações ou entrada de texto usando modelos pré-treinados. Para operações assíncronas, um assíncrono QuestionAnsweringClient está no azure.ai.language.questionanswering.aio namespace.

AuthoringClient

O AuthoringClient fornece uma interface para gerenciar projetos de Resposta a Perguntas. Exemplos das operações disponíveis incluem criar e implantar projetos, atualizar suas fontes de conhecimento e atualizar pares de perguntas e respostas. Ele fornece APIs síncronas e assíncronas.

Exemplos

QuestionAnsweringClient

A azure-ai-language-questionanswering biblioteca de clientes fornece APIs síncronas e assíncronas.

Fazer uma pergunta
Fazer uma pergunta de acompanhamento
Criar um novo projeto
Adicionar uma fonte de conhecimento
Implantar seu projeto
Operações assíncronas

Faça uma pergunta

A única entrada necessária para fazer uma pergunta usando um base de dados de conhecimento é apenas a própria pergunta:

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering import QuestionAnsweringClient

endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

client = QuestionAnsweringClient(endpoint, AzureKeyCredential(key))

output = client.get_answers(
    question="How long should my Surface battery last?",
    project_name="FAQ",
    deployment_name="test"
)
for candidate in output.answers:
    print("({}) {}".format(candidate.confidence, candidate.answer))
    print("Source: {}".format(candidate.source))

Você pode definir opções de palavra-chave adicionais para limitar o número de respostas, especificar uma pontuação de confiança mínima e muito mais.

Fazer uma pergunta de acompanhamento

Se o base de dados de conhecimento estiver configurado para bate-papo, as respostas do base de dados de conhecimento poderão incluir prompts sugeridos para perguntas de acompanhamento para iniciar uma conversa. Você pode fazer uma pergunta de acompanhamento fornecendo a ID da resposta escolhida como o contexto para a conversa continuada:

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering import QuestionAnsweringClient
from azure.ai.language.questionanswering import models

endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

client = QuestionAnsweringClient(endpoint, AzureKeyCredential(key))

output = client.get_answers(
    question="How long should charging take?",
    answer_context=models.KnowledgeBaseAnswerContext(
        previous_qna_id=previous_answer.qna_id
    ),
    project_name="FAQ",
    deployment_name="live"
)
for candidate in output.answers:
    print("({}) {}".format(candidate.confidence, candidate.answer))
    print("Source: {}".format(candidate.source))

Criar um novo projeto

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

# get service secrets
endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

# create client
client = AuthoringClient(endpoint, AzureKeyCredential(key))
with client:

    # create project
    project_name = "IssacNewton"
    project = client.create_project(
        project_name=project_name,
        options={
            "description": "biography of Sir Issac Newton",
            "language": "en",
            "multilingualResource": True,
            "settings": {
                "defaultAnswer": "no answer"
            }
        })

    print("view created project info:")
    print("\tname: {}".format(project["projectName"]))
    print("\tlanguage: {}".format(project["language"]))
    print("\tdescription: {}".format(project["description"]))

Adicionar uma fonte de conhecimento

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

# get service secrets
endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

# create client
client = AuthoringClient(endpoint, AzureKeyCredential(key))

project_name = "IssacNewton"
update_sources_poller = client.begin_update_sources(
    project_name=project_name,
    sources=[
        {
            "op": "add",
            "value": {
                "displayName": "Issac Newton Bio",
                "sourceUri": "https://wikipedia.org/wiki/Isaac_Newton",
                "sourceKind": "url"
            }
        }
    ]
)
update_sources_poller.result()

# list sources
print("list project sources")
sources = client.list_sources(
    project_name=project_name
)
for source in sources:
    print("project: {}".format(source["displayName"]))
    print("\tsource: {}".format(source["source"]))
    print("\tsource Uri: {}".format(source["sourceUri"]))
    print("\tsource kind: {}".format(source["sourceKind"]))

Implantar o projeto

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import AuthoringClient

# get service secrets
endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

# create client
client = AuthoringClient(endpoint, AzureKeyCredential(key))

project_name = "IssacNewton"

# deploy project
deployment_poller = client.begin_deploy_project(
    project_name=project_name,
    deployment_name="production"
)
deployment_poller.result()

# list all deployments
deployments = client.list_deployments(
    project_name=project_name
)

print("view project deployments")
for d in deployments:
    print(d)

Operações assíncronas

Os exemplos acima também podem ser executados de forma assíncrona usando os clientes no aio namespace:

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.aio import QuestionAnsweringClient

endpoint = os.environ["AZURE_QUESTIONANSWERING_ENDPOINT"]
key = os.environ["AZURE_QUESTIONANSWERING_KEY"]

client = QuestionAnsweringClient(endpoint, AzureKeyCredential(key))

output = await client.get_answers(
    question="How long should my Surface battery last?",
    project_name="FAQ",
    deployment_name="production"
)

Configuração opcional

Argumentos opcionais de palavra-chave podem ser passados no nível do cliente e por operação. A documentação de referência do azure-core descreve as configurações disponíveis para repetições, registro em log, protocolos de transporte e muito mais.

Solução de problemas

Geral

Os clientes de Resposta a Perguntas do Azure geram exceções definidas no Azure Core. Quando você interage com a biblioteca de clientes de Respostas às Perguntas do Serviço de Linguagem Cognitiva usando o SDK do Python, os erros retornados pelo serviço correspondem aos mesmos códigos de status HTTP retornados para solicitações da API REST .

Por exemplo, se você enviar uma pergunta a um base de dados de conhecimento inexistente, um 400 erro será retornado indicando "Solicitação Incorreta".

from azure.core.exceptions import HttpResponseError

try:
    client.get_answers(
        question="Why?",
        project_name="invalid-knowledge-base",
        deployment_name="test"
    )
except HttpResponseError as error:
    print("Query failed: {}".format(error.message))

Log

Essa biblioteca usa a biblioteca de log padrão para registro em log. Informações básicas sobre sessões HTTP (URLs, cabeçalhos etc.) são registradas no nível INFO.

O log detalhado do nível de DEBUG, incluindo corpos de solicitação/resposta e cabeçalhos não redigidos, pode ser habilitado em um cliente com o logging_enable argumento .

Confira a documentação completa de registro em log do SDK com exemplos aqui.

Próximas etapas

Exiba nossos exemplos.
Leia sobre os diferentes recursos do serviço de Respostas a Perguntas.
Experimente nossas demonstrações de serviço.

Participante

Consulte o CONTRIBUTING.md para obter detalhes sobre como criar, testar e contribuir para essa biblioteca.

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões

Compartilhar via

Biblioteca de clientes de Respostas às Perguntas do Serviço de Linguagem Cognitiva do Azure para Python – versão 1.1.0

Aviso de isenção de responsabilidade

Introdução

Pré-requisitos

Instalar o pacote

Autenticar o cliente

Obter uma chave de API

Criar QuestionAnsweringClient

Criar AuthoringClient

Criar um cliente com uma Credencial do Azure Active Directory

Principais conceitos

QuestionAnsweringClient

AuthoringClient

Exemplos

QuestionAnsweringClient

Faça uma pergunta

Fazer uma pergunta de acompanhamento

Criar um novo projeto

Adicionar uma fonte de conhecimento

Implantar o projeto

Operações assíncronas

Configuração opcional

Solução de problemas

Geral

Log

Próximas etapas

Participante

Recursos adicionais