Biblioteka klienta odpowiedzi na pytania dotyczące usługi Azure Cognitive Language Service dla języka Python — wersja 1.1.0

Odpowiadanie na pytania to oparta na chmurze usługa interfejsu API, która umożliwia tworzenie warstwy pytań i odpowiedzi konwersacji na istniejących danych. Służy do tworzenia baza wiedzy przez wyodrębnianie pytań i odpowiedzi z częściowo ustrukturyzowanej zawartości, w tym często zadawanych pytań, podręczników i dokumentów. Odpowiedz na pytania użytkowników, udzielając najlepszych odpowiedzi z pytań i odpowiedzi w baza wiedzy — automatycznie. Twój baza wiedzy staje się inteligentniejszy, ponieważ nieustannie uczy się na podstawie zachowania użytkowników.

Kod | źródłowy Pakiet (PyPI) | Dokumentacja referencyjna interfejsu | API Dokumentacja | produktu Próbki

Zrzeczenie odpowiedzialności

Obsługa pakietów języka Python zestawu Azure SDK dla języka Python w wersji 2.7 zakończyła się 1 stycznia 2022 r. Aby uzyskać więcej informacji i pytań, zapoznaj się z artykułem https://github.com/Azure/azure-sdk-for-python/issues/20691

Wprowadzenie

Wymagania wstępne

• Do korzystania z tego pakietu jest wymagany język Python w wersji 3.7 lub nowszej.
• Subskrypcja platformy Azure
• Zasób usługi językowej

Instalowanie pakietu

Zainstaluj bibliotekę klienta odpowiedzi na pytania platformy Azure dla języka Python za pomocą narzędzia pip:

pip install azure-ai-language-questionanswering

Uwaga: ta wersja biblioteki klienta jest domyślnie ustawiona na wersję 2021-10-01interfejsu API usługi .

Uwierzytelnianie klienta

Aby wchodzić w interakcje z usługą odpowiadania na pytania, należy utworzyć wystąpienie klasy QuestionAnsweringClient lub wystąpienie klasy AuthoringClient do zarządzania projektami w ramach zasobu. Będziesz potrzebować punktu końcowego i klucza interfejsu API do utworzenia wystąpienia obiektu klienta. Aby uzyskać więcej informacji na temat uwierzytelniania za pomocą usług Cognitive Services, zobacz Uwierzytelnianie żądań w usługach Azure Cognitive Services.

Uzyskiwanie klucza interfejsu API

Punkt końcowy i klucz interfejsu API można uzyskać z zasobu Language w witrynie Azure Portal.

Możesz też użyć poniższego polecenia interfejsu wiersza polecenia platformy Azure , aby pobrać klucz interfejsu API z zasobu Language.

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

Tworzenie elementu QuestionAnsweringClient

Po określeniu punktu końcowego i klucza interfejsu API można utworzyć wystąpienie elementu 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)

Tworzenie elementu AuthoringClient

Za pomocą punktu końcowego i klucza interfejsu API można utworzyć wystąpienie elementu 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)

Tworzenie klienta przy użyciu poświadczeń usługi Azure Active Directory

Aby użyć poświadczeń tokenu usługi Azure Active Directory (AAD), podaj wystąpienie żądanego typu poświadczeń uzyskanego z biblioteki azure-identity . Należy pamiętać, że regionalne punkty końcowe nie obsługują uwierzytelniania usługi AAD. Utwórz niestandardową nazwę poddomeny dla zasobu, aby użyć tego typu uwierzytelniania.

Uwierzytelnianie za pomocą usługi AAD wymaga konfiguracji początkowej:

• Instalowanie tożsamości platformy Azure
• Rejestrowanie nowej aplikacji usługi AAD
• Udziel dostępu do usługi językowej, przypisując rolę "Czytelnik języka usług Cognitive Services" do jednostki usługi.

Po skonfigurowaniu możesz wybrać typ poświadczeń z pliku azure.identity do użycia. Na przykład wartość DefaultAzureCredential może służyć do uwierzytelniania klienta:

Ustaw wartości identyfikatora klienta, identyfikatora dzierżawy i klucza tajnego klienta aplikacji usługi AAD jako zmienne środowiskowe: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET

Użyj zwróconego poświadczenia tokenu, aby uwierzytelnić klienta:

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)

Kluczowe pojęcia

QuestionAnsweringClient

Element QuestionAnsweringClient jest podstawowym interfejsem do zadawania pytań przy użyciu baza wiedzy z własnymi informacjami lub wprowadzaniem tekstu przy użyciu wstępnie wytrenowanych modeli. W przypadku operacji asynchronicznych asynchroniczna QuestionAnsweringClient jest w azure.ai.language.questionanswering.aio przestrzeni nazw.

AuthoringClient

Element AuthoringClient udostępnia interfejs do zarządzania projektami odpowiedzi na pytania. Przykłady dostępnych operacji obejmują tworzenie i wdrażanie projektów, aktualizowanie źródeł wiedzy oraz aktualizowanie par pytań i odpowiedzi. Zapewnia zarówno synchroniczne, jak i asynchroniczne interfejsy API.

Przykłady

QuestionAnsweringClient

Biblioteka azure-ai-language-questionanswering klienta udostępnia zarówno synchroniczne, jak i asynchroniczne interfejsy API.

• Zadaj pytanie
• Zadaj pytanie z monitem
• Tworzenie nowego projektu
• Dodawanie źródła wiedzy
• Wdrażanie projektu
• Operacje asynchroniczne

Zadaj pytanie

Jedynymi danymi wejściowymi wymaganymi do zadawania pytania przy użyciu baza wiedzy jest tylko samo pytanie:

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

Możesz ustawić dodatkowe opcje słowa kluczowego, aby ograniczyć liczbę odpowiedzi, określić minimalny współczynnik ufności i nie tylko.

Zadaj pytanie z monitem

Jeśli baza wiedzy jest skonfigurowany do konwersacji, odpowiedzi z baza wiedzy mogą zawierać sugerowane monity o pytania monitowe o zainicjowanie konwersacji. Możesz zadać kolejne pytanie, podając identyfikator wybranej odpowiedzi jako kontekst dalszej konwersacji:

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

Tworzenie nowego projektu

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

Dodawanie źródła wiedzy

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

Wdrażanie projektu

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)

Operacje asynchroniczne

Powyższe przykłady można również uruchamiać asynchronicznie przy użyciu klientów w aio przestrzeni nazw:

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

Konfiguracja opcjonalna

Opcjonalne argumenty słów kluczowych można przekazać na poziomie klienta i na poziomie operacji. W dokumentacji referencyjnej platformy Azure opisano dostępne konfiguracje dotyczące ponownych prób, rejestrowania, protokołów transportowych i nie tylko.

Rozwiązywanie problemów

Ogólne

Klienci odpowiedzi na pytania platformy Azure zgłaszają wyjątki zdefiniowane w usłudze Azure Core. W przypadku interakcji z biblioteką klienta odpowiedzi na pytania usługi Cognitive Language Service przy użyciu zestawu SDK języka Python błędy zwracane przez usługę odpowiadają tym samym kodom stanu HTTP zwracanym dla żądań interfejsu API REST .

Jeśli na przykład prześlesz pytanie do nieistniejącego baza wiedzy, 400 zostanie zwrócony błąd wskazujący na "Nieprawidłowe żądanie".

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

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na poziomie INFORMACJI.

Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie z argumentem logging_enable .

Zobacz pełną dokumentację rejestrowania zestawu SDK z przykładami tutaj.

Następne kroki

• Zapoznaj się z naszymi przykładami.
• Przeczytaj o różnych funkcjach usługi odpowiadania na pytania.
• Wypróbuj nasze pokazy usług.

Współtworzenie

Zobacz CONTRIBUTING.md , aby uzyskać szczegółowe informacje na temat kompilowania, testowania i współtworzenia tej biblioteki.

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.