Клиентская библиотека ответов на вопросы службы Cognitive Language Service для Python версии 1.1.0

Статья
04/05/2023

Ответы на вопросы — это облачная служба API, которая позволяет создавать уровень вопросов и ответов в беседах на основе существующих данных. Используйте его для создания база знаний путем извлечения вопросов и ответов из частично структурированного содержимого, включая часто задаваемые вопросы, руководства и документы. Автоматически отвечайте на вопросы пользователей, используя лучшие ответы на вопросы из вопросов и ответов в база знаний. Ваш база знаний также становится умнее, так как он постоянно учится на поведении пользователей.

Исходный код | Пакет (PyPI) | Справочная документация по | API Документация по продукту | Образцы

Заявление об отказе

Поддержка пакетов Python пакета Azure SDK для Python 2.7 завершилась 1 января 2022 г. Дополнительные сведения и вопросы см. на https://github.com/Azure/azure-sdk-for-python/issues/20691

Начало работы

Предварительные требования

Для использования этого пакета требуется Python 3.7 или более поздней версии.
Подписка Azure
Ресурс языковой службы

Установка пакета

Установите клиентую библиотеку ответов на вопросы Azure для Python с помощью pip:

pip install azure-ai-language-questionanswering

Примечание. Эта версия клиентской библиотеки по умолчанию использует версию 2021-10-01API службы .

Аутентификация клиента

Чтобы взаимодействовать со службой ответов на вопросы, необходимо создать экземпляр класса QuestionAnsweringClient или экземпляр AuthoringClient для управления проектами в ресурсе. Для создания экземпляра клиентского объекта потребуется конечная точка и ключ API . Дополнительные сведения о проверке подлинности с помощью Cognitive Services см. в статье Проверка подлинности запросов к Azure Cognitive Services.

Получение ключа API

Вы можете получить конечную точку и ключ API из ресурса Language на портале Azure.

Кроме того, используйте приведенную ниже команду Azure CLI , чтобы получить ключ API из ресурса Language.

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

Создание QuestionAnsweringClient

Определив конечную точку и ключ API , вы можете создать экземпляр 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)

Создание объекта AuthoringClient

С помощью конечной точки и ключа API можно создать экземпляр 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)

Создание клиента с учетными данными Azure Active Directory

Чтобы использовать учетные данные маркера Azure Active Directory (AAD), укажите экземпляр нужного типа учетных данных, полученных из библиотеки azure-identity . Обратите внимание, что региональные конечные точки не поддерживают проверку подлинности AAD. Создайте пользовательское имя поддомена для ресурса, чтобы использовать этот тип проверки подлинности.

Для проверки подлинности с помощью AAD требуется некоторая начальная настройка:

Установка azure-identity
Регистрация нового приложения AAD
Предоставьте доступ к языковой службе, назначив субъекту-службе роль "Читатель языка Cognitive Services".

После настройки можно выбрать тип учетных данных из azure.identity для использования. Например, для проверки подлинности клиента можно использовать DefaultAzureCredential :

Задайте значения идентификатора клиента, идентификатора клиента и секрета клиента приложения AAD в качестве переменных среды: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET

Используйте возвращенные учетные данные маркера для проверки подлинности клиента:

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)

Основные понятия

QuestionAnsweringClient

QuestionAnsweringClient — это основной интерфейс для вопросов с помощью база знаний с вашей собственной информацией или текстового ввода с помощью предварительно обученных моделей. Для асинхронных операций асинхронный QuestionAnsweringClientazure.ai.language.questionanswering.aio объект находится в пространстве имен .

AuthoringClient

AuthoringClient предоставляет интерфейс для управления проектами ответов на вопросы. Примеры доступных операций включают создание и развертывание проектов, обновление источников знаний и обновление пар вопросов и ответов. Он предоставляет синхронные и асинхронные API.

Примеры

QuestionAnsweringClient

Клиентская azure-ai-language-questionanswering библиотека предоставляет синхронные и асинхронные API.

Задать вопрос
Задать следующий вопрос
Создание нового проекта
Добавление источника знаний
Развертывание проекта
Асинхронные операции

Задать вопрос

Чтобы задать вопрос с помощью база знаний, требуется только сам вопрос:

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

Можно задать дополнительные параметры ключевых слов, чтобы ограничить количество ответов, указать минимальную оценку достоверности и многое другое.

Задать следующий вопрос

Если ваша база знаний настроена для беседы, ответы из база знаний могут включать предлагаемые запросы на дальнейшие вопросы для начала беседы. Вы можете задать следующий вопрос, указав идентификатор выбранного ответа в качестве контекста для продолжения беседы:

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

Создание проекта

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

Добавление источника знаний

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

Развертывание проекта

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)

Асинхронные операции

Приведенные выше примеры также можно выполнять асинхронно с помощью клиентов в aio пространстве имен:

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

Дополнительная настройка

Необязательные аргументы ключевых слов можно передавать на уровне клиента и для каждой операции. В справочной документации по azure-core описаны доступные конфигурации для повторных попыток, ведения журнала, транспортных протоколов и многого другого.

Устранение неполадок

Общие сведения

Клиенты ответов на вопросы Azure вызывают исключения, определенные в Azure Core. При взаимодействии с клиентской библиотекой ответов на вопросы Cognitive Language Service с помощью пакета SDK для Python ошибки, возвращаемые службой, соответствуют тем же кодам состояния HTTP, которые возвращаются для запросов REST API .

Например, если вы отправляете вопрос несуществующему база знаний, возвращается ошибка с сообщением 400 "Недопустимый запрос".

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

Ведение журнала

Эта библиотека использует стандартную библиотеку ведения журнала для ведения журнала. Основные сведения о сеансах HTTP (URL-адреса, заголовки и т. д.) регистрируются на уровне INFO.

Подробное ведение журнала на уровне DEBUG, включая тексты запросов и ответов и неотредактированные заголовки, можно включить на клиенте с помощью аргумента logging_enable .

См. полную документацию по ведению журнала пакета SDK с примерами здесь.

Дальнейшие действия

Просмотрите наши примеры.
Ознакомьтесь с различными функциями службы ответов на вопросы.
Попробуйте наши демонстрации служб.

Участие

Дополнительные сведения о создании, тестировании и участии в этой библиотеке см. в CONTRIBUTING.md .

На этом проекте приветствуются публикации и предложения. Для участия в большинстве процессов по разработке документации необходимо принять лицензионное соглашение участника (CLA), в котором указывается, что вы предоставляете нам права на использование ваших публикаций. Дополнительные сведения см. на странице cla.microsoft.com.

При отправке запроса на включение внесенных изменений CLA-бот автоматически определит необходимость предоставления соглашения CLA и соответствующего оформления запроса на включение внесенных изменений (например, добавление метки, комментария). Просто следуйте инструкциям бота. Будет достаточно выполнить их один раз для всех репозиториев, поддерживающих соглашение CLA.

В рамках этого проекта действуют правила поведения в отношении продуктов с открытым исходным кодом Майкрософт. Дополнительные сведения см. в разделе часто задаваемых вопросов о правилах поведения или обратитесь к opencode@microsoft.com с любыми дополнительными вопросами или комментариями.

Просмотры

Поделиться через

Клиентская библиотека ответов на вопросы службы Cognitive Language Service для Python версии 1.1.0

Заявление об отказе

Начало работы

Предварительные требования

Установка пакета

Аутентификация клиента

Получение ключа API

Создание QuestionAnsweringClient

Создание объекта AuthoringClient

Создание клиента с учетными данными Azure Active Directory

Основные понятия

QuestionAnsweringClient

AuthoringClient

Примеры

QuestionAnsweringClient

Задать вопрос

Задать следующий вопрос

Создание проекта

Добавление источника знаний

Развертывание проекта

Асинхронные операции

Дополнительная настройка

Устранение неполадок

Общие сведения

Ведение журнала

Дальнейшие действия

Участие

Обратная связь

Дополнительные ресурсы