-
Notifications
You must be signed in to change notification settings - Fork 2.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[QnA] Initial SDK #19544
Merged
annatisch
merged 31 commits into
Azure:main
from
annatisch:feature/cognitiveservices/language
Jul 8, 2021
Merged
[QnA] Initial SDK #19544
Changes from all commits
Commits
Show all changes
31 commits
Select commit
Hold shift + click to select a range
b3f19aa
Template + first code gen
annatisch acc2108
Basic client
annatisch 792610e
First tests
annatisch 21848b5
Added async client + tests
annatisch a445347
Added answerspan test
annatisch cf4d00d
Added authoring APIs
annatisch 459481e
Some updates
annatisch d0e4a6a
Pure generated clients
annatisch 5cee5e6
Test updates
annatisch b9ed3bb
Update test imports
annatisch 455bd3f
Clean working recordings
annatisch dae79b7
Renamed directory
annatisch df656d9
Removed authoring for now
annatisch 52a306f
Use unreleased core
annatisch f91a856
Remove conversation + ci yaml
annatisch 94cf599
Merge remote-tracking branch 'upstream/main' into feature/cognitivese…
annatisch 19c99c7
Some CI updates
annatisch 6eafbf6
update language __init__.py to not have a space in the name
scbedd d3d0322
Setup.py
annatisch 78f3631
Updated core dependency
annatisch 8e70771
CI fixes
annatisch 8b22e87
Added language nspkg
annatisch 55d270f
Merge remote-tracking branch 'upstream/main' into feature/cognitivese…
annatisch a510171
Fix Python 2.7
annatisch 485ab2f
Added some more tests
annatisch 2651fd5
Test fixes
annatisch c14a5e7
Added live configuration
annatisch 9dc5346
Bumped msrest
annatisch f335cf3
readme + samples
annatisch c27d1d3
No pypi or refdocs yet
annatisch da8e057
Review feedback
annatisch File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
6 changes: 6 additions & 0 deletions
6
sdk/cognitivelanguage/azure-ai-language-questionanswering/CHANGELOG.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,6 @@ | ||
# Release History | ||
|
||
## 1.0.0b1 (unreleased) | ||
|
||
### Features Added | ||
* Initial release. |
8 changes: 8 additions & 0 deletions
8
sdk/cognitivelanguage/azure-ai-language-questionanswering/MANIFEST.in
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
include _meta.json | ||
include *.md | ||
include azure/__init__.py | ||
include azure/ai/__init__.py | ||
include azure/ai/language/__init__.py | ||
recursive-include tests *.py | ||
recursive-include samples *.py *.md | ||
include azure/ai/language/questionanswering/py.typed |
212 changes: 212 additions & 0 deletions
212
sdk/cognitivelanguage/azure-ai-language-questionanswering/README.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,212 @@ | ||
[![Build Status](https://dev.azure.com/azure-sdk/public/_apis/build/status/azure-sdk-for-python.client?branchName=main)](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=46?branchName=main) | ||
|
||
# Azure Cognitive Language Services Question Answering client library for Python | ||
|
||
Question Answering is a cloud-based API service that lets you create a conversational question-and-answer layer over your existing data. Use it to build a knowledge base by extracting questions and answers from your semi-structured content, including FAQ, manuals, and documents. Answer users’ questions with the best answers from the QnAs in your knowledge base—automatically. Your knowledge base gets smarter, too, as it continually learns from users' behavior. | ||
|
||
[Source code][questionanswering_client_src] | [Package (PyPI)][questionanswering_pypi_package] | [API reference documentation][questionanswering_refdocs] | [Product documentation][questionanswering_docs] | [Samples][questionanswering_samples] | ||
|
||
## Getting started | ||
|
||
### Prerequisites | ||
|
||
* Python 2.7, or 3.6 or later is required to use this package. | ||
* An [Azure subscription][azure_subscription] | ||
* An existing Question Answering resource | ||
|
||
> Note: the new unified Cognitive Language Services are not currently available for deployment. | ||
### Install the package | ||
|
||
Install the Azure QuestionAnswering client library for Python with [pip][pip_link]: | ||
|
||
```bash | ||
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. You will need an **endpoint**, and an **API key** 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 | ||
|
||
You can get the **endpoint** and an **API key** from the Cognitive Services resource or Question Answering resource in the [Azure Portal][azure_portal]. | ||
|
||
Alternatively, use the [Azure CLI][azure_cli] command shown below to get the API key from the Question Answering resource. | ||
|
||
```powershell | ||
az cognitiveservices account keys list --resource-group <resource-group-name> --name <resource-name> | ||
``` | ||
|
||
#### Create QuestionAnsweringClient | ||
|
||
Once you've determined your **endpoint** and **API key** you can instantiate a `QuestionAnsweringClient`: | ||
|
||
```python | ||
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) | ||
``` | ||
|
||
## Key concepts | ||
|
||
### QuestionAnsweringClient | ||
|
||
The [`QuestionAnsweringClient`][questionanswering_client_class] is the primary interface for asking questions using a knowledge base with your own information, or text input using pre-trained models. | ||
For asynchronous operations, an async `QuestionAnsweringClient` is in the `azure.ai.language.questionanswering.aio` namespace. | ||
|
||
## Examples | ||
|
||
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) | ||
|
||
annatisch marked this conversation as resolved.
Show resolved
Hide resolved
|
||
### Ask a question | ||
|
||
The only input required to ask a question using a knowledgebase is just the question itself: | ||
|
||
```python | ||
from azure.ai.language.questionanswering import models as qna | ||
|
||
params = qna.KnowledgebaseQueryParameters( | ||
question="How long should my Surface battery last?" | ||
) | ||
|
||
output = client.query_knowledgebase( | ||
project_name="FAQ", | ||
knowledgebase_query_parameters=params | ||
) | ||
for candidate in output.answers: | ||
print("({}) {}".format(candidate.confidence_score, candidate.answer)) | ||
print("Source: {}".format(candidate.source)) | ||
|
||
``` | ||
|
||
You can set additional properties on `KnowledgebaseQueryParameters` to limit the number of answers, specify a minimum confidence score, and more. | ||
|
||
### Ask a follow-up question | ||
|
||
If your knowledgebase is configured for [chit-chat][questionanswering_docs_chat], you can ask a follow-up question provided the previous question-answering ID and, optionally, the exact question the user asked: | ||
|
||
```python | ||
params = qna.models.KnowledgebaseQueryParameters( | ||
question="How long should charging take?" | ||
context=qna.models.KnowledgebaseAnswerRequestContext( | ||
previous_user_query="How long should my Surface battery last?", | ||
previous_qna_id=previous_answer.id | ||
) | ||
) | ||
|
||
output = client.query_knowledgebase( | ||
project_name="FAQ", | ||
knowledgebase_query_parameters=params | ||
) | ||
for candidate in output.answers: | ||
print("({}) {}".format(candidate.confidence_score, 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 | ||
from azure.ai.language.questionanswering import models as qna | ||
|
||
client = QuestionAnsweringClient(endpoint, credential) | ||
|
||
params = qna.KnowledgebaseQueryParameters( | ||
question="How long should my Surface battery last?" | ||
) | ||
|
||
output = await client.query_knowledgebase( | ||
project_name="FAQ", | ||
knowledgebase_query_parameters=params | ||
) | ||
``` | ||
|
||
## Optional Configuration | ||
Optional keyword arguments can be passed in at the client and per-operation level. The azure-core [reference documentation][azure_core_ref_docs] describes available configurations for retries, logging, transport protocols, and more. | ||
|
||
## Troubleshooting | ||
|
||
### General | ||
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". | ||
|
||
```python | ||
from azure.core.exceptions import HttpResponseError | ||
|
||
try: | ||
client.query_knowledgebase( | ||
project_name="invalid-knowledgebase", | ||
knowledgebase_query_parameters=params | ||
) | ||
except HttpResponseError as error: | ||
print("Query failed: {}".format(error.message)) | ||
``` | ||
|
||
### Logging | ||
This library uses the standard | ||
annatisch marked this conversation as resolved.
Show resolved
Hide resolved
|
||
[logging][python_logging] library for logging. | ||
Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO | ||
level. | ||
|
||
Detailed DEBUG level logging, including request/response bodies and unredacted | ||
headers, can be enabled on a client with the `logging_enable` argument. | ||
|
||
See full SDK logging documentation with examples [here][sdk_logging_docs]. | ||
|
||
## Next steps | ||
|
||
* View our [samples][questionanswering_samples]. | ||
* Read about the different [features][questionanswering_docs_features] of the Question Answering service. | ||
* Try our service [demos][questionanswering_docs_demos]. | ||
|
||
## Contributing | ||
|
||
See the [CONTRIBUTING.md][contributing] for details on building, testing, and contributing to this library. | ||
|
||
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [cla.microsoft.com][cla]. | ||
|
||
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA. | ||
|
||
This project has adopted the [Microsoft Open Source Code of Conduct][code_of_conduct]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments. | ||
|
||
<!-- LINKS --> | ||
[azure_cli]: https://docs.microsoft.com/cli/azure/ | ||
[azure_portal]: https://portal.azure.com/ | ||
[azure_subscription]: https://azure.microsoft.com/free/ | ||
[cla]: https://cla.microsoft.com | ||
[coc_contact]: mailto:opencode@microsoft.com | ||
[coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ | ||
[code_of_conduct]: https://opensource.microsoft.com/codeofconduct/ | ||
[cognitive_auth]: https://docs.microsoft.com/azure/cognitive-services/authentication/ | ||
[contributing]: https://github.com/Azure/azure-sdk-for-python/blob/main/CONTRIBUTING.md | ||
[python_logging]: https://docs.python.org/3/library/logging.html | ||
[sdk_logging_docs]: https://docs.microsoft.com/azure/developer/python/azure-sdk-logging | ||
[azure_core_ref_docs]: https://azuresdkdocs.blob.core.windows.net/$web/python/azure-core/latest/azure.core.html | ||
[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://github.com/Azure/azure-sdk-for-python/blob/main/sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/_question_answering_client.py#L27 | ||
[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/ | ||
[questionanswering_docs_chat]: https://docs.microsoft.com/azure/cognitive-services/qnamaker/how-to/chit-chat-knowledge-base | ||
[questionanswering_docs_demos]: https://azure.microsoft.com/services/cognitive-services/qna-maker/#demo | ||
[questionanswering_docs_features]: https://azure.microsoft.com/services/cognitive-services/qna-maker/#features | ||
[questionanswering_pypi_package]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-language-questionanswering/ | ||
[questionanswering_refdocs]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-language-questionanswering/ | ||
[questionanswering_rest_docs]: https://docs.microsoft.com/rest/api/cognitiveservices-qnamaker/ | ||
[questionanswering_samples]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/cognitivelanguage/azure-ai-language-questionanswering/samples/README.md | ||
|
||
![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-python%2Fsdk%2Ftemplate%2Fazure-template%2FREADME.png) |
1 change: 1 addition & 0 deletions
1
sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/__init__.py
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
__path__ = __import__('pkgutil').extend_path(__path__, __name__) |
1 change: 1 addition & 0 deletions
1
sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/__init__.py
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
__path__ = __import__('pkgutil').extend_path(__path__, __name__) |
1 change: 1 addition & 0 deletions
1
sdk/cognitivelanguage/azure-ai-language-questionanswering/azure/ai/language/__init__.py
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
__path__ = __import__('pkgutil').extend_path(__path__, __name__) |
19 changes: 19 additions & 0 deletions
19
...guage/azure-ai-language-questionanswering/azure/ai/language/questionanswering/__init__.py
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
# coding=utf-8 | ||
# -------------------------------------------------------------------------- | ||
# Copyright (c) Microsoft Corporation. All rights reserved. | ||
# Licensed under the MIT License. See License.txt in the project root for license information. | ||
# Code generated by Microsoft (R) AutoRest Code Generator. | ||
# Changes may cause incorrect behavior and will be lost if the code is regenerated. | ||
# -------------------------------------------------------------------------- | ||
|
||
from ._question_answering_client import QuestionAnsweringClient | ||
from ._version import VERSION | ||
|
||
__version__ = VERSION | ||
__all__ = ['QuestionAnsweringClient'] | ||
|
||
try: | ||
from ._patch import patch_sdk # type: ignore | ||
patch_sdk() | ||
except ImportError: | ||
pass |
70 changes: 70 additions & 0 deletions
70
...azure-ai-language-questionanswering/azure/ai/language/questionanswering/_configuration.py
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,70 @@ | ||
# coding=utf-8 | ||
# -------------------------------------------------------------------------- | ||
# Copyright (c) Microsoft Corporation. All rights reserved. | ||
# Licensed under the MIT License. See License.txt in the project root for license information. | ||
# Code generated by Microsoft (R) AutoRest Code Generator. | ||
# Changes may cause incorrect behavior and will be lost if the code is regenerated. | ||
# -------------------------------------------------------------------------- | ||
|
||
from typing import TYPE_CHECKING | ||
|
||
from azure.core.configuration import Configuration | ||
from azure.core.pipeline import policies | ||
|
||
from ._version import VERSION | ||
|
||
if TYPE_CHECKING: | ||
# pylint: disable=unused-import,ungrouped-imports | ||
from typing import Any | ||
|
||
from azure.core.credentials import AzureKeyCredential | ||
|
||
|
||
class QuestionAnsweringClientConfiguration(Configuration): | ||
"""Configuration for QuestionAnsweringClient. | ||
Note that all parameters used to create this instance are saved as instance | ||
attributes. | ||
:param credential: Credential needed for the client to connect to Azure. | ||
:type credential: ~azure.core.credentials.AzureKeyCredential | ||
:param endpoint: Supported Cognitive Services endpoint (e.g., https://:code:`<resource-name>`.api.cognitiveservices.azure.com). | ||
:type endpoint: str | ||
""" | ||
|
||
def __init__( | ||
self, | ||
credential, # type: AzureKeyCredential | ||
endpoint, # type: str | ||
**kwargs # type: Any | ||
): | ||
# type: (...) -> None | ||
if credential is None: | ||
raise ValueError("Parameter 'credential' must not be None.") | ||
if endpoint is None: | ||
raise ValueError("Parameter 'endpoint' must not be None.") | ||
super(QuestionAnsweringClientConfiguration, self).__init__(**kwargs) | ||
|
||
self.credential = credential | ||
self.endpoint = endpoint | ||
self.api_version = "2021-05-01-preview" | ||
kwargs.setdefault("sdk_moniker", "ai-language-questionanswering/{}".format(VERSION)) | ||
self._configure(**kwargs) | ||
|
||
def _configure( | ||
self, **kwargs # type: Any | ||
): | ||
# type: (...) -> None | ||
self.user_agent_policy = kwargs.get("user_agent_policy") or policies.UserAgentPolicy(**kwargs) | ||
self.headers_policy = kwargs.get("headers_policy") or policies.HeadersPolicy(**kwargs) | ||
self.proxy_policy = kwargs.get("proxy_policy") or policies.ProxyPolicy(**kwargs) | ||
self.logging_policy = kwargs.get("logging_policy") or policies.NetworkTraceLoggingPolicy(**kwargs) | ||
self.http_logging_policy = kwargs.get("http_logging_policy") or policies.HttpLoggingPolicy(**kwargs) | ||
self.retry_policy = kwargs.get("retry_policy") or policies.RetryPolicy(**kwargs) | ||
self.custom_hook_policy = kwargs.get("custom_hook_policy") or policies.CustomHookPolicy(**kwargs) | ||
self.redirect_policy = kwargs.get("redirect_policy") or policies.RedirectPolicy(**kwargs) | ||
self.authentication_policy = kwargs.get("authentication_policy") | ||
if self.credential and not self.authentication_policy: | ||
self.authentication_policy = policies.AzureKeyCredentialPolicy( | ||
self.credential, "Ocp-Apim-Subscription-Key", **kwargs | ||
) |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Does QNA support multi-service / Cognitive Services resource? Wondering about it since above it says we need an existing Questioning Answering resource
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
hmm I'm not sure - I will look into this!