Share via

Pergunta do Serviço de Linguagem Cognitiva Azure Respondendo biblioteca de clientes para Python - versão 1.1.0

  • Artigo

QuestionIng é um serviço de API baseado na nuvem que permite criar uma camada de perguntas e respostas de conversação sobre os seus dados existentes. Use-o para construir um base de dados de conhecimento extraindo perguntas e respostas do seu conteúdo semi-estruturado, incluindo FAQ, manuais e documentos. Responda às perguntas dos utilizadores com as melhores respostas dos QNAs na sua base de dados de conhecimento — automaticamente. O seu base de dados de conhecimento fica mais inteligente também, uma vez que aprende continuamente com o comportamento dos utilizadores.

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

Exclusão de Responsabilidade

O apoio aos pacotes Azure SDK Python para python 2.7 terminou em 01 de janeiro de 2022. Para mais informações e perguntas, consulte https://github.com/Azure/azure-sdk-for-python/issues/20691

Introdução

Pré-requisitos

Instale o pacote

Instale a biblioteca cliente de resposta a perguntas Azure para Python com pip:

pip install azure-ai-language-questionanswering

Nota: esta versão da biblioteca do cliente está por defeito na versão 2021-10-01API de serviço .

Autenticar o cliente

Para interagir com o serviço de resposta a perguntas, terá de criar uma instância da classe QuestionAnsweringClient ou uma instância do AuthoringClient para gerir projetos dentro do seu recurso. Você precisará de um ponto final, e uma chave API para instantaneaizar um objeto de cliente. Para obter mais informações sobre a autenticação com serviços cognitivos, consulte autenticar os pedidos aos Serviços Cognitivos da Azure.

Obter uma chave de API

Pode obter o ponto final e uma chave API a partir do recurso Idioma no Portal Azure.

Em alternativa, utilize o comando Azure CLI apresentado abaixo para obter a chave API do recurso Language.

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

Criar QuestionAnsweringClient

Uma vez determinado o seu ponto final e a chave API , pode instantaneamente 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 O Licenciamento

Com a sua chave endpoint e API, pode instantaneamente um 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 de Diretório Ativo Azure

Para utilizar uma credencial de token Azure Ative(AAD), forneça uma instância do tipo credencial pretendido obtido a partir da biblioteca de identidade azul . Note que os pontos finais regionais não suportam a autenticação da AAD. Crie um nome de subdomínio personalizado para o seu recurso para utilizar este tipo de autenticação.

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

Após a configuração, pode escolher que tipo de credencial a azul.identidade a usar. Como exemplo, o DefaultAzureCredential pode ser usado para autenticar o cliente:

Definir os valores do ID do cliente, iD do inquilino e segredo de cliente da aplicação AAD como variáveis ambientais: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET

Utilize a credencial simbólica devolvida 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)

Conceitos-chave

QuestionAnsweringClient

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

Autoria Desemaente

O AuthoringClient fornece uma interface para gerir projetos de resposta a perguntas. Exemplos das operações disponíveis incluem a criação e implementação de projetos, a atualização das suas fontes de conhecimento e a atualização de pares de perguntas e respostas. Fornece APIs sincronizados e assíncronos.

Exemplos

QuestionAnsweringClient

A azure-ai-language-questionanswering biblioteca do cliente fornece APIs sincronizados e assíncronos.

Fazer uma pergunta

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

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))

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

Faça uma pergunta de acompanhamento

Se o seu base de dados de conhecimento estiver configurado para o chit-chat, as respostas do base de dados de conhecimento podem incluir indicações sugeridas para perguntas de seguimento para iniciar uma conversação. Pode fazer uma pergunta de acompanhamento fornecendo a iD da sua resposta escolhida como o contexto para a conversação contínua:

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"]))

Implemente o seu 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 assíncronosamente usando os clientes no espaço de aio nome:

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

Os argumentos de palavras-chave opcionais podem ser transmitidos ao cliente e ao nível por operação. A documentação de referência do núcleo azul descreve as configurações disponíveis para recaídas, registos, protocolos de transporte e muito mais.

Resolução de problemas

Geral

Perguntas Azure Responder clientes levantam exceções definidas no Azure Core. Quando interage com a biblioteca de clientes do Serviço de Linguagem Cognitiva respondendo à biblioteca do cliente utilizando o Python SDK, os erros devolvidos pelo serviço correspondem aos mesmos códigos de estado HTTP devolvidos para pedidos de API REST .

Por exemplo, se submeter uma pergunta a um base de dados de conhecimento inexistente, é devolvido um 400 erro indicando "Mau Pedido".

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))

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registar registos. Informações básicas sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao nível info.

A registo detalhado do nível DEBUG, incluindo os órgãos de pedido/resposta e os cabeçalhos não redigidos, pode ser ativado num cliente com o logging_enable argumento.

Consulte a documentação completa do registo SDK com exemplos aqui.

Passos seguintes

Contribuir

Consulte o CONTRIBUTING.md para mais detalhes sobre a construção, teste e contribuição para esta biblioteca.

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para mais informações consulte o Código de Conduta FAQ ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Impressões