Skip to content

Commit

Permalink
Removed qna samples
Browse files Browse the repository at this point in the history
  • Loading branch information
annatisch committed Sep 10, 2021
1 parent e25bc35 commit 0806f7f
Show file tree
Hide file tree
Showing 12 changed files with 15 additions and 621 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@ 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
include azure/ai/language/conversations/py.typed
135 changes: 6 additions & 129 deletions sdk/cognitivelanguage/azure-ai-language-conversations/README.md
Original file line number Diff line number Diff line change
@@ -1,160 +1,51 @@
[![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
# Azure Cognitive Language Services Conversations 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]:
Install the Azure Conversations client library for Python with [pip][pip_link]:

```bash
pip install azure-ai-language-questionanswering
pip install azure-ai-language-conversations
```

### 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** 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

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
#### Create ConversationAnalysisClient

endpoint = "https://{myaccount}.api.cognitive.microsoft.com"
credential = AzureKeyCredential("{api-key}")

client = QuestionAnsweringClient(endpoint, credential)
```

## Key concepts

### QuestionAnsweringClient
### ConversationAnalysisClient

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)

### Ask a question

The only input required to ask a question using a knowledge base is just the question itself:

```python
from azure.ai.language.questionanswering import models as qna

params = qna.KnowledgeBaseQueryOptions(
question="How long should my Surface battery last?"
)

output = client.query_knowledge_base(
params,
project_name="FAQ",
)
for candidate in output.answers:
print("({}) {}".format(candidate.confidence_score, candidate.answer))
print("Source: {}".format(candidate.source))

```

You can set additional properties on `KnowledgeBaseQueryOptions` to limit the number of answers, specify a minimum confidence score, and more.

### Ask a follow-up question

If your knowledge base 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.KnowledgeBaseQueryOptions(
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_knowledge_base(
params,
project_name="FAQ"
)
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.KnowledgeBaseQueryOptions(
question="How long should my Surface battery last?"
)

output = await client.query_knowledge_base(
params,
project_name="FAQ"
)
```

## 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_knowledge_base(
params,
project_name="invalid-knowledge-base"
)
except HttpResponseError as error:
print("Query failed: {}".format(error.message))
```

### Logging
This library uses the standard
Expand All @@ -169,10 +60,6 @@ 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.
Expand All @@ -198,15 +85,5 @@ This project has adopted the [Microsoft Open Source Code of Conduct][code_of_con
[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)

This file was deleted.

This file was deleted.

Loading

0 comments on commit 0806f7f

Please sign in to comment.