azure-ai-language-questionanswering-authoring 1.0.0b1

Microsoft Corporation Azure Ai Language Questionanswering Authoring Client Library for Python

Azure AI Language Question Answering Authoring client library for Python

The azure-ai-language-questionanswering-authoring package provides authoring / management capabilities for Azure AI Language Question Answering: create and configure projects, add knowledge sources, manage QnA pairs and synonyms, and deploy versions. Runtime (query) operations live in the separate azure-ai-language-questionanswering package.

NOTE: This is a preview (1.0.0b1) targeting a preview service API version (2025-05-15-preview). APIs, models, and LRO result payloads may change before GA.

Product documentation

Getting started

Prerequisites

• Python 3.9+ (preview requires 3.9 or later)
• An Azure subscription
• An Azure AI Language resource with Question Answering enabled (custom subdomain endpoint recommended for AAD)

Install the package

pip install --pre azure-ai-language-questionanswering-authoring

Optional (for Azure Active Directory auth):

pip install azure-identity

Authenticate the client

You can authenticate with:

1. Azure Active Directory via DefaultAzureCredential (recommended)
2. A resource key via AzureKeyCredential (quick start / local experimentation)

AAD example:

from azure.identity import DefaultAzureCredential
from azure.ai.language.questionanswering.authoring import QuestionAnsweringAuthoringClient

endpoint = "https://<resource-name>.cognitiveservices.azure.com"
credential = DefaultAzureCredential()
client = QuestionAnsweringAuthoringClient(endpoint, credential)

Key credential example:

from azure.core.credentials import AzureKeyCredential
from azure.ai.language.questionanswering.authoring import QuestionAnsweringAuthoringClient

client = QuestionAnsweringAuthoringClient(
    endpoint="https://<resource-name>.cognitiveservices.azure.com",
    credential=AzureKeyCredential("<api-key>")
)

Key concepts

• Project: A logical container for your knowledge sources, QnA pairs, synonyms, and deployments.
• Knowledge Source: A URL/file describing content from which QnA pairs can be extracted.
• QnA Record: A question and its answer plus metadata/alternative questions.
• Synonyms: Word alteration groups to normalize variations in user questions.
• Deployment: A named (e.g., production) deployed snapshot of your project used by runtime clients.
• Long‑running operation (LRO): Certain operations (update sources/QnAs, import, export, deploy) return an LROPoller. In the current preview these resolve to None—treat .result() strictly as a completion signal.

Examples

Below are minimal synchronous examples. More complete samples (including async equivalents) are in the samples directory. Environment variables used by samples: AZURE_QUESTIONANSWERING_ENDPOINT, AZURE_QUESTIONANSWERING_KEY.

Create a project

metadata = {
    "language": "en",
    "description": "FAQ project",
    "settings": {"defaultAnswer": "no answer"},
    "multilingualResource": True,
}
client.create_project(project_name="FAQ", body=metadata)

List projects

for proj in client.list_projects():
    print(proj.get("projectName"), proj.get("lastModifiedDateTime"))

Add / update a knowledge source

from azure.ai.language.questionanswering.authoring.models import UpdateSourceRecord,UpdateQnaSourceRecord 

poller = client.begin_update_sources(
    project_name="FAQ",
    body=[
        UpdateSourceRecord(
            op="add",
            value=UpdateQnaSourceRecord(
                display_name="ContosoFAQ",
                source="https://contoso.com/faq",
                source_uri="https://contoso.com/faq",
                source_kind="url",
                content_structure_kind="unstructured",
                refresh=False,
            ),
        )
    ],
)
poller.result()

Add a QnA pair

from azure.ai.language.questionanswering.authoring.models import UpdateQnaRecord,QnaRecord

poller = client.begin_update_qnas(
    project_name="FAQ",
    body=[
        UpdateQnaRecord(
            op="add",
            value=QnaRecord(
                id=1,
                answer="Use the Azure SDKs.",
                source="manual",
                questions=["How do I use Azure services in .NET?"],
            ),
        )
    ],
)
poller.result()

Set synonyms

from azure.ai.language.questionanswering.authoring.models import SynonymAssets,WordAlterations

client.update_synonyms(
    project_name="FAQ",
    body=SynonymAssets(
        value=[
            WordAlterations(alterations=["qnamaker", "qna maker"]),
            WordAlterations(alterations=["qna", "question and answer"]),
        ]
    ),
)

Deploy

client.begin_deploy_project(project_name="FAQ", deployment_name="production").result()

Export / Import

export_poller = client.begin_export(project_name="FAQ", format="json")
export_poller.result()  # current preview returns None

from azure.ai.language.questionanswering.authoring.models import ImportJobOptions,Assets,ImportQnaRecord
assets = ImportJobOptions(
    assets=Assets(
        qnas=[
            ImportQnaRecord(
                id=1,
                answer="Example answer",
                source="https://contoso.com/faq",
                questions=["Example question?"],
            )
        ]
    )
)
client.begin_import_assets(project_name="FAQ", body=assets, format="json").result()

Troubleshooting

Errors

Service errors raise HttpResponseError (or subclasses) from azure-core. Check the .status_code / .message for details.

from azure.core.exceptions import HttpResponseError

try:
    client.list_projects()
except HttpResponseError as e:
    print("Request failed:", e.message)

Logging

Enable basic logging:

import logging
logging.basicConfig(level=logging.INFO)

For request/response details set environment variable AZURE_LOG_LEVEL=info or pass logging_enable=True per operation.

Next steps

• Explore the full samples
• Learn about Question Answering concepts in product documentation

Contributing

See CONTRIBUTING.md for instructions on building, testing, and contributing.

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 https://cla.microsoft.com.

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. For more information see the Code of Conduct FAQ or contact mailto:[e-mail] with any additional questions or comments.

Release History

1.0.0b1 (2025-11-16)

Features Added

• Initial preview release of azure-ai-language-questionanswering-authoring separated from the combined azure-ai-language-questionanswering package.
• Supports project listing, creation, update, deletion, import/export, deployments, synonym/source/QnA management operations aligned with the TypeSpec service definition (includes preview API version 2025-05-15-preview where applicable).

Other Changes

• Generated from TypeSpec definitions in specification\cognitiveservices\data-plane\LanguageQuestionAnsweringAuthoring.