Pustaka klien Jawaban atas Pertanyaan Azure Cognitive Language Service untuk Python - versi 1.1.0

Artikel
04/05/2023

Jawaban Atas Pertanyaan adalah layanan API berbasis cloud yang memungkinkan Anda membuat lapisan tanya jawab percakapan di atas data yang ada. Gunakan untuk membangun Pangkalan Pengetahuan dengan mengekstrak pertanyaan dan jawaban dari konten semi terstruktur Anda, termasuk FAQ, manual, dan dokumen. Jawab pertanyaan pengguna dengan jawaban terbaik dari QnA di Pangkalan Pengetahuan Anda—secara otomatis. Pangkalan Pengetahuan Anda juga semakin cerdas, karena terus belajar dari perilaku pengguna.

Kode sumber | Paket (PyPI) | Dokumentasi | referensi API Dokumentasi | produk Sampel

Pengelakan

Dukungan paket Azure SDK Python untuk Python 2.7 berakhir 01 Januari 2022. Untuk informasi lebih lanjut dan pertanyaan, silakan merujuk ke https://github.com/Azure/azure-sdk-for-python/issues/20691

Memulai

Prasyarat

Python 3.7 atau yang lebih baru diharuskan untuk menggunakan paket ini.
Langganan Azure
Sumber daya Layanan Bahasa

Instal paketnya

Instal pustaka klien Azure Question Answering untuk Python dengan pip:

pip install azure-ai-language-questionanswering

Catatan: versi pustaka klien ini default ke versi 2021-10-01API layanan .

Mengautentikasi klien

Untuk berinteraksi dengan layanan Jawaban Atas Pertanyaan, Anda harus membuat instans kelas QuestionAnsweringClient atau instans AuthoringClient untuk mengelola proyek dalam sumber daya Anda. Anda akan memerlukan titik akhir, dan kunci API untuk membuat instans objek klien. Untuk informasi selengkapnya mengenai autentikasi dengan Cognitive Services, lihat Mengautentikasi permintaan ke Azure Cognitive Services.

Mendapatkan kunci API

Anda bisa mendapatkan titik akhir dan kunci API dari sumber daya Bahasa di Portal Microsoft Azure.

Atau, gunakan perintah Azure CLI yang ditunjukkan di bawah ini untuk mendapatkan kunci API dari sumber daya Bahasa.

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

Buat QuestionAnsweringClient

Setelah menentukan titik akhir dan kunci API , Anda dapat membuat instans 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)

Membuat AuthoringClient

Dengan titik akhir dan kunci API, Anda dapat membuat instans 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)

Membuat klien dengan Kredensial Azure Active Directory

Untuk menggunakan kredensial token Azure Active Directory (AAD), berikan instans jenis kredensial yang diinginkan yang diperoleh dari pustaka identitas azure . Perhatikan bahwa titik akhir regional tidak mendukung autentikasi AAD. Buat nama subdomain kustom untuk sumber daya Anda untuk menggunakan jenis autentikasi ini.

Autentikasi dengan AAD memerlukan beberapa penyiapan awal:

Menginstal azure-identity
Mendaftarkan aplikasi AAD baru
Berikan akses ke layanan Bahasa dengan menetapkan peran "Pembaca Bahasa Cognitive Services" ke perwakilan layanan Anda.

Setelah penyiapan, Anda dapat memilih jenis kredensial mana dari azure.identity yang akan digunakan. Sebagai contoh, DefaultAzureCredential dapat digunakan untuk mengautentikasi klien:

Atur nilai ID klien, ID penyewa, dan rahasia klien aplikasi AAD sebagai variabel lingkungan: AZURE_CLIENT_ID, , AZURE_TENANT_IDAZURE_CLIENT_SECRET

Gunakan kredensial token yang dikembalikan untuk mengautentikasi klien:

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)

Konsep utama

QuestionAnsweringClient

QuestionAnsweringClient adalah antarmuka utama untuk mengajukan pertanyaan menggunakan Pangkalan Pengetahuan dengan informasi Anda sendiri, atau input teks menggunakan model yang telah dilatih sebelumnya. Untuk operasi asinkron, asinkron QuestionAnsweringClient ada di azure.ai.language.questionanswering.aio namespace.

AuthoringClient

AuthoringClient menyediakan antarmuka untuk mengelola proyek Jawaban Atas Pertanyaan. Contoh operasi yang tersedia termasuk membuat dan menyebarkan proyek, memperbarui sumber pengetahuan Anda, dan memperbarui pasangan pertanyaan dan jawaban. Ini menyediakan API sinkron dan asinkron.

Contoh

QuestionAnsweringClient

azure-ai-language-questionanswering Pustaka klien menyediakan API sinkron dan asinkron.

Ajukan pertanyaan
Ajukan pertanyaan tindak lanjut
Membuat proyek baru
Menambahkan sumber pengetahuan
Menyebarkan proyek Anda
Operasi asinkron

Ajukan pertanyaan

Satu-satunya input yang diperlukan untuk mengajukan pertanyaan menggunakan Pangkalan Pengetahuan hanyalah pertanyaan itu sendiri:

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

Anda dapat mengatur opsi kata kunci tambahan untuk membatasi jumlah jawaban, menentukan skor keyakinan minimum, dan banyak lagi.

Ajukan pertanyaan tindak lanjut

Jika Pangkalan Pengetahuan Anda dikonfigurasi untuk obrolan, jawaban dari Pangkalan Pengetahuan dapat mencakup permintaan yang disarankan untuk pertanyaan tindak lanjut untuk memulai percakapan. Anda dapat mengajukan pertanyaan tindak lanjut dengan memberikan ID jawaban yang Anda pilih sebagai konteks untuk percakapan berkelanjutan:

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

Membuat proyek baru

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

Menambahkan sumber pengetahuan

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

Menyebarkan proyek Anda

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)

Operasi Asinkron

Contoh di atas juga dapat dijalankan secara asinkron menggunakan klien di aio namespace layanan:

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

Konfigurasi Opsional

Argumen kata kunci opsional dapat diteruskan di tingkat klien dan per operasi. Dokumentasi referensi azure-core menjelaskan konfigurasi yang tersedia untuk percobaan ulang, pengelogan, protokol transportasi, dan banyak lagi.

Pemecahan Masalah

Umum

Klien Azure Question Answering memunculkan pengecualian yang ditentukan di Azure Core. Saat Anda berinteraksi dengan pustaka klien Jawaban Atas Pertanyaan Cognitive Language Service menggunakan Python SDK, kesalahan yang dikembalikan oleh layanan sesuai dengan kode status HTTP yang sama yang dikembalikan untuk permintaan REST API .

Misalnya, jika Anda mengirimkan pertanyaan ke Pangkalan Pengetahuan yang tidak ada, kesalahan 400 dikembalikan yang menunjukkan "Permintaan Buruk".

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

Pembuatan Log

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat di tingkat INFO.

Pengelogan tingkat DEBUG terperinci, termasuk isi permintaan/respons dan header yang tidak diredaksikan, dapat diaktifkan pada klien dengan logging_enable argumen .

Lihat dokumentasi pengelogan SDK lengkap dengan contoh di sini.

Langkah berikutnya

Lihat sampel kami.
Baca tentang berbagai fitur layanan Jawaban atas Pertanyaan.
Coba demo layanan kami.

Berkontribusi

Lihat CONTRIBUTING.md untuk detail tentang membangun, menguji, dan berkontribusi pada pustaka ini.

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.

Tayangan

Bagikan melalui

Pustaka klien Jawaban atas Pertanyaan Azure Cognitive Language Service untuk Python - versi 1.1.0

Pengelakan

Memulai

Prasyarat

Instal paketnya

Mengautentikasi klien

Mendapatkan kunci API

Buat QuestionAnsweringClient

Membuat AuthoringClient

Membuat klien dengan Kredensial Azure Active Directory

Konsep utama

QuestionAnsweringClient

AuthoringClient

Contoh

QuestionAnsweringClient

Ajukan pertanyaan

Ajukan pertanyaan tindak lanjut

Membuat proyek baru

Menambahkan sumber pengetahuan

Menyebarkan proyek Anda

Operasi Asinkron

Konfigurasi Opsional

Pemecahan Masalah

Umum

Pembuatan Log

Langkah berikutnya

Berkontribusi

Saran dan Komentar

Sumber Daya Tambahan: