Share via

Azure Cognitive Language Service–fråga Besvara klientbibliotek för Python – version 1.1.0

  • Artikel

Frågesvar är en molnbaserad API-tjänst som gör att du kan skapa ett konversationslager med frågor och svar över dina befintliga data. Använd den för att skapa en kunskapsbas genom att extrahera frågor och svar från ditt halvstrukturerade innehåll, inklusive vanliga frågor och svar, handböcker och dokument. Besvara användarnas frågor med de bästa svaren från QnA:erna i din kunskapsbas – automatiskt. Din kunskapsbas blir också smartare eftersom den kontinuerligt lär sig av användarnas beteende.

Källkod | Paket (PyPI) | API-referensdokumentation | Produktdokumentation | Prover

Friskrivning

Stöd för Azure SDK Python-paket för Python 2.7 slutade den 1 januari 2022. Mer information och frågor finns i https://github.com/Azure/azure-sdk-for-python/issues/20691

Komma igång

Förutsättningar

Installera paketet

Installera Azure Question Answering-klientbiblioteket för Python med pip:

pip install azure-ai-language-questionanswering

Obs! Den här versionen av klientbiblioteket är standard för tjänstens API-version 2021-10-01.

Autentisera klienten

För att kunna interagera med tjänsten Frågesvar måste du skapa en instans av klassen QuestionAnsweringClient eller en instans av AuthoringClient för att hantera projekt i resursen. Du behöver en slutpunkt och en API-nyckel för att instansiera ett klientobjekt. Mer information om autentisering med Cognitive Services finns i Autentisera begäranden till Azure Cognitive Services.

Hämta en API-nyckel

Du kan hämta slutpunkten och en API-nyckel från språkresursen i Azure Portal.

Du kan också använda Azure CLI-kommandot som visas nedan för att hämta API-nyckeln från språkresursen.

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

Skapa questionAnsweringClient

När du har fastställt slutpunkten och API-nyckeln kan du instansiera en 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)

Skapa authoringClient

Med din slutpunkt och API-nyckel kan du instansiera en 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)

Skapa en klient med en Azure Active Directory-autentiseringsuppgift

Om du vill använda en AAD-tokenautentisering (Azure Active Directory) anger du en instans av önskad typ av autentiseringsuppgifter som hämtats från azure-identity-biblioteket . Observera att regionala slutpunkter inte stöder AAD-autentisering. Skapa ett anpassat underdomännamn för resursen för att använda den här typen av autentisering.

Autentisering med AAD kräver viss inledande konfiguration:

Efter installationen kan du välja vilken typ av autentiseringsuppgifter från azure.identity som ska användas. Till exempel kan DefaultAzureCredential användas för att autentisera klienten:

Ange värdena för klient-ID, klient-ID och klienthemlighet för AAD-programmet som miljövariabler: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Använd den returnerade tokenautentiseringsuppgiften för att autentisera klienten:

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)

Viktiga begrepp

QuestionAnsweringClient

QuestionAnsweringClient är det primära gränssnittet för att ställa frågor med hjälp av en kunskapsbas med din egen information eller textinmatning med hjälp av förtränade modeller. För asynkrona åtgärder finns en asynkron azure.ai.language.questionanswering.aio i QuestionAnsweringClient namnområdet.

AuthoringClient

AuthoringClient tillhandahåller ett gränssnitt för att hantera frågesvarsprojekt. Exempel på tillgängliga åtgärder är att skapa och distribuera projekt, uppdatera dina kunskapskällor och uppdatera fråge- och svarspar. Den innehåller både synkrona och asynkrona API:er.

Exempel

QuestionAnsweringClient

Klientbiblioteket azure-ai-language-questionanswering innehåller både synkrona och asynkrona API:er.

Ställ en fråga

De enda indata som krävs för att ställa en fråga med hjälp av en kunskapsbas är bara själva frågan:

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

Du kan ange ytterligare nyckelordsalternativ för att begränsa antalet svar, ange en minsta konfidenspoäng med mera.

Ställ en uppföljningsfråga

Om din kunskapsbas har konfigurerats för chit-chat kan svaren från kunskapsbas innehålla föreslagna uppmaningar om uppföljningsfrågor för att initiera en konversation. Du kan ställa en uppföljningsfråga genom att ange ID:t för ditt valda svar som kontext för den fortsatta konversationen:

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

Skapa ett nytt projekt

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

Lägga till en kunskapskälla

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

Distribuera projektet

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)

Asynkrona åtgärder

Exemplen ovan kan också köras asynkront med klienterna aio i namnområdet:

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

Valfri konfiguration

Valfria nyckelordsargument kan skickas på klient- och åtgärdsnivå. Referensdokumentationen för azure-core beskriver tillgängliga konfigurationer för återförsök, loggning, transportprotokoll med mera.

Felsökning

Allmänt

Azure Question Answering-klienter skapar undantag som definierats i Azure Core. När du interagerar med klientbiblioteket för cognitive language service answering med hjälp av Python SDK motsvarar fel som returneras av tjänsten samma HTTP-statuskoder som returneras för REST API-begäranden .

Om du till exempel skickar en fråga till en obefintlig kunskapsbas returneras ett 400 fel som anger "Felaktig begäran".

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

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning. Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO-nivå.

Detaljerad loggning på FELSÖKNINGsnivå, inklusive begärande-/svarskroppar och oredigerade huvuden, kan aktiveras på en klient med logging_enable argumentet .

Se fullständig dokumentation om SDK-loggning med exempel här.

Nästa steg

Bidra

Mer information om hur du skapar, testar och bidrar till det här biblioteket finns i CONTRIBUTING.md .

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns i cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekod eller kontakt opencode@microsoft.com med ytterligare frågor eller kommentarer.

Visningar