Клиентская библиотека ответов на вопросы службы Cognitive Language Service для Python версии 1.1.0
Ответы на вопросы — это облачная служба 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-01
API службы .
Аутентификация клиента
Чтобы взаимодействовать со службой ответов на вопросы, необходимо создать экземпляр класса 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 — это основной интерфейс для вопросов с помощью база знаний с вашей собственной информацией или текстового ввода с помощью предварительно обученных моделей.
Для асинхронных операций асинхронный QuestionAnsweringClient
azure.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 с любыми дополнительными вопросами или комментариями.
Azure SDK for Python