From 78f5553bcef3fde725ed0760ab339dc228081dc2 Mon Sep 17 00:00:00 2001 From: Krista Pratico Date: Thu, 13 Oct 2022 12:04:45 -0700 Subject: [PATCH] update changelog date and ref docs --- .../CHANGELOG.md | 2 +- .../README.md | 109 ++++++++++++------ .../questionanswering/_operations/_patch.py | 22 +++- .../ai/language/questionanswering/_patch.py | 4 +- .../aio/_operations/_patch.py | 22 +++- .../language/questionanswering/aio/_patch.py | 4 +- .../questionanswering/authoring/_patch.py | 7 +- .../questionanswering/authoring/aio/_patch.py | 7 +- .../samples/README.md | 3 +- 9 files changed, 129 insertions(+), 51 deletions(-) diff --git a/sdk/cognitivelanguage/azure-ai-language-questionanswering/CHANGELOG.md b/sdk/cognitivelanguage/azure-ai-language-questionanswering/CHANGELOG.md index 6c46d5c043c1..e09eb2c93113 100644 --- a/sdk/cognitivelanguage/azure-ai-language-questionanswering/CHANGELOG.md +++ b/sdk/cognitivelanguage/azure-ai-language-questionanswering/CHANGELOG.md @@ -1,6 +1,6 @@ # Release History -## 1.1.0 (Unreleased) +## 1.1.0 (2022-10-13) ### Breaking Changes * `QuestionAnsweringProjectsClient` was renamed to `AuthoringClient`. diff --git a/sdk/cognitivelanguage/azure-ai-language-questionanswering/README.md b/sdk/cognitivelanguage/azure-ai-language-questionanswering/README.md index 24f8a369143d..77e673831a94 100644 --- a/sdk/cognitivelanguage/azure-ai-language-questionanswering/README.md +++ b/sdk/cognitivelanguage/azure-ai-language-questionanswering/README.md @@ -14,7 +14,7 @@ _Azure SDK Python packages support for Python 2.7 ended 01 January 2022. For mor - Python 3.7 or later is required to use this package. - An [Azure subscription][azure_subscription] -- A Language Service resource +- A [Language Service][language_service] resource ### Install the package @@ -28,7 +28,7 @@ pip install azure-ai-language-questionanswering ### Authenticate the client -In order to interact with the Question Answering service, you'll need to create an instance of the [QuestionAnsweringClient][questionanswering_client_class] class or an instance of the [AuthoringClient][questionansweringauthoring_client_class] for managing projects within your resource. You will need an **endpoint**, and an **API key** to instantiate a client object. For more information regarding authenticating with Cognitive Services, see [Authenticate requests to Azure Cognitive Services][cognitive_auth]. +In order to interact with the Question Answering service, you'll need to create an instance of the [QuestionAnsweringClient][questionanswering_client_class] class or an instance of the [AuthoringClient][authoring_client_class] for managing projects within your resource. You will need an **endpoint**, and an **API key** to instantiate a client object. For more information regarding authenticating with Cognitive Services, see [Authenticate requests to Azure Cognitive Services][cognitive_auth]. #### Get an API key @@ -42,7 +42,7 @@ az cognitiveservices account keys list --resource-group -- #### Create QuestionAnsweringClient -Once you've determined your **endpoint** and **API key** you can instantiate a `QuestionAnsweringClient`: +Once you've determined your **endpoint** and **API key** you can instantiate a [QuestionAnsweringClient][questionanswering_client_class]: ```python from azure.core.credentials import AzureKeyCredential @@ -55,7 +55,7 @@ client = QuestionAnsweringClient(endpoint, credential) ``` #### Create AuthoringClient -With your endpoint and API key, you can instantiate a [AuthoringClient][questionansweringauthoring_client_class]: +With your endpoint and API key, you can instantiate a [AuthoringClient][authoring_client_class]: ```python from azure.core.credentials import AzureKeyCredential @@ -106,24 +106,34 @@ The [QuestionAnsweringClient][questionanswering_client_class] is the primary int For asynchronous operations, an async `QuestionAnsweringClient` is in the `azure.ai.language.questionanswering.aio` namespace. ### AuthoringClient -The [AuthoringClient][questionansweringauthoring_client_class] provides an interface for managing Question Answering projects. Examples of the available operations include creating and deploying projects, updating your knowledge sources, and updating question and answer pairs. It provides both synchronous and asynchronous APIs. +The [AuthoringClient][authoring_client_class] provides an interface for managing Question Answering projects. Examples of the available operations include creating and deploying projects, updating your knowledge sources, and updating question and answer pairs. It provides both synchronous and asynchronous APIs. ## Examples ### QuestionAnsweringClient The `azure-ai-language-questionanswering` client library provides both synchronous and asynchronous APIs. -The following examples show common scenarios using the `client` [created above](#create-questionansweringclient). - -- [Ask a question](#ask-a-question) -- [Ask a follow-up question](#ask-a-follow-up-question) -- [Asynchronous operations](#asynchronous-operations) +- [Ask a question](#ask-a-question "Ask a question") +- [Ask a follow-up question](#ask-a-follow-up-question "Ask a follow-up question") +- [Create a new project](#create-a-new-project "Create a new project") +- [Add a knowledge source](#add-a-knowledge-source "Add a knowledge source") +- [Deploy your project](#deploy-your-project "Deploy your project") +- [Asynchronous operations](#asynchronous-operations "Asynchronous operations") #### Ask a question The only input required to ask a question using a knowledge base is just the question itself: ```python +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", @@ -142,8 +152,16 @@ You can set additional keyword options to limit the number of answers, specify a If your knowledge base is configured for [chit-chat][questionanswering_docs_chat], the answers from the knowledge base may include suggested [prompts for follow-up questions][questionanswering_refdocs_prompts] to initiate a conversation. You can ask a follow-up question by providing the ID of your chosen answer as the context for the continued conversation: ```python +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( @@ -155,28 +173,8 @@ output = client.get_answers( for candidate in output.answers: print("({}) {}".format(candidate.confidence, candidate.answer)) print("Source: {}".format(candidate.source)) - ``` -#### Asynchronous operations - -The above examples can also be run asynchronously using the client in the `aio` namespace: - -```python -from azure.core.credentials import AzureKeyCredential -from azure.ai.language.questionanswering.aio import QuestionAnsweringClient - -client = QuestionAnsweringClient(endpoint, credential) - -output = await client.get_answers( - question="How long should my Surface battery last?", - project_name="FAQ", - deployment_name="production" -) -``` - -### AuthoringClient - #### Create a new project ```python @@ -214,6 +212,18 @@ with client: #### Add a knowledge source ```python +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=[ @@ -245,6 +255,19 @@ for source in sources: ```python +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, @@ -262,7 +285,26 @@ for d in deployments: print(d) ``` +#### Asynchronous operations + +The above examples can also be run asynchronously using the client in the `aio` namespace: + +```python +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" +) +``` ## Optional Configuration @@ -275,7 +317,7 @@ Optional keyword arguments can be passed in at the client and per-operation leve Azure QuestionAnswering clients raise exceptions defined in [Azure Core][azure_core_readme]. When you interact with the Cognitive Language Services Question Answering client library using the Python SDK, errors returned by the service correspond to the same HTTP status codes returned for [REST API][questionanswering_rest_docs] requests. -For example, if you submit a question to a non-existant knowledge base, a `400` error is returned indicating "Bad Request". +For example, if you submit a question to a non-existent knowledge base, a `400` error is returned indicating "Bad Request". ```python from azure.core.exceptions import HttpResponseError @@ -323,6 +365,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con [azure_cli]: https://docs.microsoft.com/cli/azure/ [azure_portal]: https://portal.azure.com/ [azure_subscription]: https://azure.microsoft.com/free/ +[language_service]: https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesTextAnalytics [cla]: https://cla.microsoft.com [coc_contact]: mailto:opencode@microsoft.com [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ @@ -335,7 +378,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con [azure_core_readme]: https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/core/azure-core/README.md [pip_link]: https://pypi.org/project/pip/ [questionanswering_client_class]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-ai-language-questionanswering/latest/azure.ai.language.questionanswering.html#azure.ai.language.questionanswering.QuestionAnsweringClient -[questionansweringauthoring_client_class]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/authoring/_client.py +[authoring_client_class]: https://aka.ms/azsdk/python/questionansweringauthoringclient [questionanswering_refdocs_prompts]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-ai-language-questionanswering/latest/azure.ai.language.questionanswering.models.html#azure.ai.language.questionanswering.models.KnowledgeBaseAnswerDialog [questionanswering_client_src]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-language-questionanswering/ [questionanswering_docs]: https://azure.microsoft.com/services/cognitive-services/qna-maker/ @@ -344,7 +387,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con [questionanswering_docs_features]: https://azure.microsoft.com/services/cognitive-services/qna-maker/#features [questionanswering_pypi_package]: https://pypi.org/project/azure-ai-language-questionanswering/ [questionanswering_refdocs]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-ai-language-questionanswering/latest/azure.ai.language.questionanswering.html -[questionanswering_rest_docs]: https://docs.microsoft.com/rest/api/cognitiveservices-qnamaker/ +[questionanswering_rest_docs]: https://learn.microsoft.com/rest/api/cognitiveservices/questionanswering/question-answering [questionanswering_samples]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-language-questionanswering/samples/README.md [cognitive_authentication_aad]: https://docs.microsoft.com/azure/cognitive-services/authentication#authenticate-with-azure-active-directory [azure_identity_credentials]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity#credentials diff --git a/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/_operations/_patch.py b/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/_operations/_patch.py index e38a445bbddd..cdc5bedf16c2 100644 --- a/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/_operations/_patch.py +++ b/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/_operations/_patch.py @@ -193,7 +193,16 @@ def get_answers(self, *args: AnswersOptions, **kwargs: Any) -> AnswersResult: :paramtype include_unstructured_sources: bool :return: AnswersResult :rtype: ~azure.ai.language.questionanswering.models.AnswersResult - :raises: ~azure.core.exceptions.HttpResponseError + :raises ~azure.core.exceptions.HttpResponseError: + + .. admonition:: Example: + + .. literalinclude:: ../samples/sample_query_knowledgebase.py + :start-after: [START query_knowledgebase] + :end-before: [END query_knowledgebase] + :language: python + :dedent: 4 + :caption: Answer the specified question using your knowledge base. """ options, kwargs = _get_answers_prepare_options(*args, **kwargs) return super().get_answers(options, **kwargs) @@ -230,7 +239,16 @@ def get_answers_from_text(self, *args: AnswersFromTextOptions, **kwargs: Any) -> :paramtype language: str :return: AnswersFromTextResult :rtype: ~azure.ai.language.questionanswering.models.AnswersFromTextResult - :raises: ~azure.core.exceptions.HttpResponseError + :raises ~azure.core.exceptions.HttpResponseError: + + .. admonition:: Example: + + .. literalinclude:: ../samples/sample_query_text.py + :start-after: [START query_text] + :end-before: [END query_text] + :language: python + :dedent: 4 + :caption: Answers the specified question using the provided text. """ options, kwargs = _get_answers_from_text_prepare_options( *args, language=kwargs.pop("language", self._default_language), **kwargs # type: ignore diff --git a/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/_patch.py b/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/_patch.py index fafa41665a97..feac2333488b 100644 --- a/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/_patch.py +++ b/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/_patch.py @@ -35,10 +35,10 @@ class QuestionAnsweringClient(QuestionAnsweringClientGenerated): The API can be used to analyze unstructured text for tasks such as sentiment analysis, key phrase extraction, language detection and question answering. - Further documentation can be found in https://docs.microsoft.com/azure/cognitive-services/text-analytics/overview + Further documentation can be found in https://learn.microsoft.com/azure/cognitive-services/language-service/overview :param endpoint: Supported Cognitive Services endpoint (e.g., - https://.api.cognitiveservices.azure.com). + https://:code:``.cognitiveservices.azure.com). :type endpoint: str :param credential: Credential needed for the client to connect to Azure. This can be the an instance of AzureKeyCredential if using a Language API key diff --git a/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/aio/_operations/_patch.py b/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/aio/_operations/_patch.py index 203144f5a463..331981363e25 100644 --- a/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/aio/_operations/_patch.py +++ b/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/aio/_operations/_patch.py @@ -86,7 +86,16 @@ async def get_answers(self, *args, **kwargs) -> AnswersResult: # type: ignore :paramtype include_unstructured_sources: bool :return: AnswersResult :rtype: ~azure.ai.language.questionanswering.models.AnswersResult - :raises: ~azure.core.exceptions.HttpResponseError + :raises ~azure.core.exceptions.HttpResponseError: + + .. admonition:: Example: + + .. literalinclude:: ../samples/async_samples/sample_query_knowledgebase_async.py + :start-after: [START query_knowledgebase_async] + :end-before: [END query_knowledgebase_async] + :language: python + :dedent: 4 + :caption: Answer the specified question using your knowledge base. """ options, kwargs = _get_answers_prepare_options(*args, **kwargs) return await super().get_answers(options, **kwargs) # type: ignore @@ -123,7 +132,16 @@ async def get_answers_from_text(self, *args, **kwargs) -> AnswersFromTextResult: :paramtype language: str :return: AnswersFromTextResult :rtype: ~azure.ai.language.questionanswering.models.AnswersFromTextResult - :raises: ~azure.core.exceptions.HttpResponseError + :raises ~azure.core.exceptions.HttpResponseError: + + .. admonition:: Example: + + .. literalinclude:: ../samples/async_samples/sample_query_text_async.py + :start-after: [START query_text_async] + :end-before: [END query_text_async] + :language: python + :dedent: 4 + :caption: Answers the specified question using the provided text. """ options, kwargs = _get_answers_from_text_prepare_options( *args, language=kwargs.pop("language", self._default_language), **kwargs # type: ignore diff --git a/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/aio/_patch.py b/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/aio/_patch.py index 79f5dc35bee7..b2b353d9b448 100644 --- a/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/aio/_patch.py +++ b/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/aio/_patch.py @@ -38,10 +38,10 @@ class QuestionAnsweringClient(QuestionAnsweringClientGenerated): The API can be used to analyze unstructured text for tasks such as sentiment analysis, key phrase extraction, language detection and question answering. - Further documentation can be found in https://docs.microsoft.com/azure/cognitive-services/text-analytics/overview + Further documentation can be found in https://learn.microsoft.com/azure/cognitive-services/language-service/overview :param endpoint: Supported Cognitive Services endpoint (e.g., - https://.api.cognitiveservices.azure.com). + https://:code:``.cognitiveservices.azure.com). :type endpoint: str :param credential: Credential needed for the client to connect to Azure. This can be the an instance of AzureKeyCredential if using a Language API key diff --git a/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/authoring/_patch.py b/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/authoring/_patch.py index bfb62f969375..3a8ce1eba86b 100644 --- a/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/authoring/_patch.py +++ b/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/authoring/_patch.py @@ -37,12 +37,11 @@ class AuthoringClient(AuthoringClientGenerated): """The language service API is a suite of natural language processing (NLP) skills built with best-in-class Microsoft machine learning algorithms. The API can be used to analyze unstructured text for tasks such as sentiment analysis, key phrase extraction, language - detection and question answering. Further documentation can be found in :code:` - https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview`. + detection and question answering. Further documentation can be found in + https://learn.microsoft.com/azure/cognitive-services/language-service/overview :param endpoint: Supported Cognitive Services endpoint (e.g., - https://:code:``.api.cognitiveservices.azure.com). + https://:code:``.cognitiveservices.azure.com). :type endpoint: str :param credential: Credential needed for the client to connect to Azure. This can be the an instance of AzureKeyCredential if using a Language API key diff --git a/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/authoring/aio/_patch.py b/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/authoring/aio/_patch.py index e584f2016cde..1ab098ccc60f 100644 --- a/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/authoring/aio/_patch.py +++ b/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/authoring/aio/_patch.py @@ -37,12 +37,11 @@ class AuthoringClient(AuthoringClientGenerated): """The language service API is a suite of natural language processing (NLP) skills built with best-in-class Microsoft machine learning algorithms. The API can be used to analyze unstructured text for tasks such as sentiment analysis, key phrase extraction, language - detection and question answering. Further documentation can be found in :code:` - https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview`. + detection and question answering. Further documentation can be found in + https://learn.microsoft.com/azure/cognitive-services/language-service/overview :param endpoint: Supported Cognitive Services endpoint (e.g., - https://:code:``.api.cognitiveservices.azure.com). + https://:code:``.cognitiveservices.azure.com). :type endpoint: str :param credential: Credential needed for the client to connect to Azure. This can be the an instance of AzureKeyCredential if using a Language API key diff --git a/sdk/cognitivelanguage/azure-ai-language-questionanswering/samples/README.md b/sdk/cognitivelanguage/azure-ai-language-questionanswering/samples/README.md index 5fe24bcac9f1..d5b9730dcab5 100644 --- a/sdk/cognitivelanguage/azure-ai-language-questionanswering/samples/README.md +++ b/sdk/cognitivelanguage/azure-ai-language-questionanswering/samples/README.md @@ -33,7 +33,7 @@ These sample programs show common scenarios for the QuestionAnswering client's o * Python 3.7 or later is required to use this package. * An [Azure subscription][azure_subscription] -* An existing Question Answering resource +* A [Language Service][language_service] resource ## Setup @@ -66,5 +66,6 @@ pip install azure-ai-language-questionanswering [add_knowledge_sources]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-language-questionanswering/samples/authoring/sample_update_knowledge_sources.py [add_knowledge_sources_async]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-language-questionanswering/samples/authoring/async_samples/sample_update_knowledge_sources_async.py +[language_service]: https://ms.portal.azure.com/#create/Microsoft.CognitiveServicesTextAnalytics [pip]: https://pypi.org/project/pip/ [azure_subscription]: https://azure.microsoft.com/free/