Azure Text Analytics Python客户端库

Azure认知服务语言是一个基于云的服务，它提供自然语言处理（NLP）功能，以理解和分析文本，包括以下主要功能

• 情感分析
• 命名实体识别
• 语言检测
• 关键短语提取
• 实体链接
• 多重分析
• 个人信息（PII）检测
• 健康文本分析
• 自定义命名实体识别
• 自定义文本分类
• 提取性文本摘要
• 抽象性文本摘要

源代码 | 包（PyPI） | 包（Conda） | API参考文档 | 产品文档 | 示例

入门指南

先决条件

• 使用此包需要Python 3.7或更高版本。
• 您必须拥有一个Azure订阅以及一个认知服务或语言服务资源才能使用此包。

创建认知服务或语言服务资源

语言服务支持多服务和单服务访问。如果您计划通过单个端点/密钥访问多个认知服务，请创建认知服务资源。如果您只访问语言服务，请创建语言服务资源。您可以使用Azure门户或Azure CLI，按照此文档中的步骤创建资源。

使用客户端库与服务交互开始于一个客户端。要创建客户端对象，您将需要资源的认知服务或语言服务端点以及一个允许您访问的凭据

from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import TextAnalyticsClient

credential = AzureKeyCredential("<api_key>")
text_analytics_client = TextAnalyticsClient(endpoint="https://<resource-name>.cognitiveservices.azure.com/", credential=credential)

请注意，对于某些认知服务资源，端点可能与上述代码片段不同。例如，https://<region>.api.cognitive.microsoft.com/。

安装包

使用pip安装Azure Text Analytics客户端库

pip install azure-ai-textanalytics

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import TextAnalyticsClient
endpoint = os.environ["AZURE_LANGUAGE_ENDPOINT"]
key = os.environ["AZURE_LANGUAGE_KEY"]

text_analytics_client = TextAnalyticsClient(endpoint, AzureKeyCredential(key))

请注意，5.2.X及更高版本针对的是Azure认知服务语言API。这些API包括文本分析和自然语言处理功能，这些功能在Text Analytics客户端库的前几个版本中已有提供。此外，服务API已从语义版本更新为基于日期的版本。此客户端库默认为最新支持的API版本，目前为2023-04-01。

下表显示了SDK版本与服务支持的API版本之间的关系

可以通过将api_version关键字参数传递给客户端来选择API版本。对于最新的语言服务功能，请考虑选择最新的beta API版本。对于生产场景，建议选择最新稳定版本。设置为较旧版本可能会导致功能兼容性降低。

验证客户端

获取端点

您可以使用Azure门户或Azure CLI找到语言服务资源端点。

# Get the endpoint for the Language service resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "properties.endpoint"

获取API密钥

您可以从认知服务或语言服务资源中在Azure门户获取API密钥。或者，您可以使用以下Azure CLI片段获取资源的API密钥。

az cognitiveservices account keys list --name "resource-name" --resource-group "resource-group-name"

使用API密钥凭据创建TextAnalyticsClient

一旦获得API密钥的值，您就可以将其作为字符串传递给一个AzureKeyCredential实例。使用密钥作为凭证参数来验证客户端

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import TextAnalyticsClient
endpoint = os.environ["AZURE_LANGUAGE_ENDPOINT"]
key = os.environ["AZURE_LANGUAGE_KEY"]

text_analytics_client = TextAnalyticsClient(endpoint, AzureKeyCredential(key))

使用Azure活动目录凭证创建TextAnalyticsClient

要使用Azure Active Directory (AAD)令牌凭证，提供从azure-identity库中获取的期望凭证类型的实例。请注意，区域端点不支持AAD身份验证。为了使用此类型身份验证，为您的资源创建一个自定义子域名称。

AAD身份验证需要一些初始设置

• 安装azure-identity
• 注册一个新的AAD应用程序
• 授权访问语言服务，通过将“Cognitive Services Language Reader”角色分配给您的服务主体。

设置完成后，您可以选择使用azure.identity中哪种类型的凭证。例如，可以使用DefaultAzureCredential来验证客户端

将AAD应用程序的客户端ID、租户ID和客户端密钥的值设置为环境变量：AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET

使用返回的令牌凭证来验证客户端

import os
from azure.ai.textanalytics import TextAnalyticsClient
from azure.identity import DefaultAzureCredential

endpoint = os.environ["AZURE_LANGUAGE_ENDPOINT"]
credential = DefaultAzureCredential()

text_analytics_client = TextAnalyticsClient(endpoint, credential=credential)

关键概念

TextAnalyticsClient

文本分析客户端库提供TextAnalyticsClient，用于对文档批进行分析。它提供同步和异步操作来访问特定的文本分析用途，如语言检测或关键词提取。

输入

一个文档是语言服务中预测模型要分析的单个单元。每个操作的输入以文档列表的形式传递。

列表中可以传递字符串，例如。

documents = ["I hated the movie. It was so slow!", "The movie made it into my top ten favorites. What a great movie!"]

或者，如果您希望传递每个项目的文档id或language/country_hint，它们可以传递为DetectLanguageInput或TextDocumentInput或类似字典的对象表示形式

documents = [
    {"id": "1", "language": "en", "text": "I hated the movie. It was so slow!"},
    {"id": "2", "language": "en", "text": "The movie made it into my top ten favorites. What a great movie!"},
]

有关输入（包括文档长度限制、最大批次大小和支持的文本编码）的服务限制，请参阅。

返回值

单个文档的返回值可以是结果或错误对象。每个操作返回包含一系列结果和错误对象的不均匀列表。这些结果/错误与提供的文档顺序索引匹配。

结果，如AnalyzeSentimentResult，是文本分析操作的结果，包含关于文档输入的预测或预测。

错误对象，DocumentError，表明服务在处理文档时遇到问题，并包含它失败的原因。

文档错误处理

您可以通过使用is_error属性在列表中过滤结果或错误对象。对于结果对象，这始终是False，而对于DocumentError，这是True。

例如，要过滤掉所有DocumentErrors，可以使用列表推导

response = text_analytics_client.analyze_sentiment(documents)
successful_responses = [doc for doc in response if not doc.is_error]

您还可以使用kind属性来过滤结果类型

poller = text_analytics_client.begin_analyze_actions(documents, actions)
response = poller.result()
for result in response:
    if result.kind == "SentimentAnalysis":
        print(f"Sentiment is {result.sentiment}")
    elif result.kind == "KeyPhraseExtraction":
        print(f"Key phrases: {result.key_phrases}")
    elif result.is_error is True:
        print(f"Document error: {result.code}, {result.message}")

长时间运行的操作

长时间运行的操作是指包括向服务发送初始请求以启动操作，然后以一定的时间间隔轮询服务以确定操作是否完成或失败，如果操作成功，则获取结果的操作。

支持医疗分析、自定义文本分析或多个分析的方法被建模为长时间运行的操作。客户端暴露一个返回轮询对象的begin_<方法名>方法。调用者应在轮询对象上调用result()以等待操作完成。以下提供了使用长时间运行操作的示例代码片段。

示例

以下部分提供了一些代码片段，涵盖了语言服务中的一些常见任务，包括

• 分析情感
• 识别实体
• 识别链接实体
• 识别PII实体
• 提取关键短语
• 检测语言
• 医疗实体分析
• 多重分析
• 自定义实体识别
• 自定义单标签分类
• 自定义多标签分类
• 提取式摘要
• 抽象式摘要

分析情感

analyze_sentiment通过查看输入文本，确定其情感是正面、负面、中性还是混合。其响应包括每句情感分析和置信度分数。

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import TextAnalyticsClient

endpoint = os.environ["AZURE_LANGUAGE_ENDPOINT"]
key = os.environ["AZURE_LANGUAGE_KEY"]

text_analytics_client = TextAnalyticsClient(endpoint=endpoint, credential=AzureKeyCredential(key))

documents = [
    """I had the best day of my life. I decided to go sky-diving and it made me appreciate my whole life so much more.
    I developed a deep-connection with my instructor as well, and I feel as if I've made a life-long friend in her.""",
    """This was a waste of my time. All of the views on this drop are extremely boring, all I saw was grass. 0/10 would
    not recommend to any divers, even first timers.""",
    """This was pretty good! The sights were ok, and I had fun with my instructors! Can't complain too much about my experience""",
    """I only have one word for my experience: WOW!!! I can't believe I have had such a wonderful skydiving company right
    in my backyard this whole time! I will definitely be a repeat customer, and I want to take my grandmother skydiving too,
    I know she'll love it!"""
]


result = text_analytics_client.analyze_sentiment(documents, show_opinion_mining=True)
docs = [doc for doc in result if not doc.is_error]

print("Let's visualize the sentiment of each of these documents")
for idx, doc in enumerate(docs):
    print(f"Document text: {documents[idx]}")
    print(f"Overall sentiment: {doc.sentiment}")

返回的响应是异构的列表，包括结果和错误对象：list[AnalyzeSentimentResult, DocumentError]

请参阅服务文档，了解情感分析的概念性讨论。要了解如何对文本中与个体方面（如产品或服务的属性）相关的观点进行更细致的分析，请参阅此处。

识别实体

recognize_entities识别并对其输入文本中的实体进行分类，如人物、地点、组织、日期/时间、数量、百分比、货币等。

import os
import typing
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import TextAnalyticsClient

endpoint = os.environ["AZURE_LANGUAGE_ENDPOINT"]
key = os.environ["AZURE_LANGUAGE_KEY"]

text_analytics_client = TextAnalyticsClient(endpoint=endpoint, credential=AzureKeyCredential(key))
reviews = [
    """I work for Foo Company, and we hired Contoso for our annual founding ceremony. The food
    was amazing and we all can't say enough good words about the quality and the level of service.""",
    """We at the Foo Company re-hired Contoso after all of our past successes with the company.
    Though the food was still great, I feel there has been a quality drop since their last time
    catering for us. Is anyone else running into the same problem?""",
    """Bar Company is over the moon about the service we received from Contoso, the best sliders ever!!!!"""
]

result = text_analytics_client.recognize_entities(reviews)
result = [review for review in result if not review.is_error]
organization_to_reviews: typing.Dict[str, typing.List[str]] = {}

for idx, review in enumerate(result):
    for entity in review.entities:
        print(f"Entity '{entity.text}' has category '{entity.category}'")
        if entity.category == 'Organization':
            organization_to_reviews.setdefault(entity.text, [])
            organization_to_reviews[entity.text].append(reviews[idx])

for organization, reviews in organization_to_reviews.items():
    print(
        "\n\nOrganization '{}' has left us the following review(s): {}".format(
            organization, "\n\n".join(reviews)
        )
    )

返回的响应是异构的列表，包括结果和错误对象：list[RecognizeEntitiesResult, DocumentError]

请参阅服务文档，了解命名实体识别和支持的类型的概念性讨论。

识别链接实体

recognize_linked_entities识别并消除其输入文本中每个实体的身份（例如，确定单词火星是指出星系，还是指罗马战神）。识别的实体与知名知识库（如维基百科）的URL相关联。

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import TextAnalyticsClient

endpoint = os.environ["AZURE_LANGUAGE_ENDPOINT"]
key = os.environ["AZURE_LANGUAGE_KEY"]

text_analytics_client = TextAnalyticsClient(endpoint=endpoint, credential=AzureKeyCredential(key))
documents = [
    """
    Microsoft was founded by Bill Gates with some friends he met at Harvard. One of his friends,
    Steve Ballmer, eventually became CEO after Bill Gates as well. Steve Ballmer eventually stepped
    down as CEO of Microsoft, and was succeeded by Satya Nadella.
    Microsoft originally moved its headquarters to Bellevue, Washington in January 1979, but is now
    headquartered in Redmond.
    """
]

result = text_analytics_client.recognize_linked_entities(documents)
docs = [doc for doc in result if not doc.is_error]

print(
    "Let's map each entity to it's Wikipedia article. I also want to see how many times each "
    "entity is mentioned in a document\n\n"
)
entity_to_url = {}
for doc in docs:
    for entity in doc.entities:
        print("Entity '{}' has been mentioned '{}' time(s)".format(
            entity.name, len(entity.matches)
        ))
        if entity.data_source == "Wikipedia":
            entity_to_url[entity.name] = entity.url

返回的响应是异构的列表，包括结果和错误对象：list[RecognizeLinkedEntitiesResult, DocumentError]

请参阅服务文档，了解实体链接和支持的类型的概念性讨论。

识别PII实体

recognize_pii_entities识别并对其输入文本中的个人信息（PII）实体进行分类，例如社会保障号码、银行账户信息、信用卡号码等。

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import TextAnalyticsClient

endpoint = os.environ["AZURE_LANGUAGE_ENDPOINT"]
key = os.environ["AZURE_LANGUAGE_KEY"]

text_analytics_client = TextAnalyticsClient(
    endpoint=endpoint, credential=AzureKeyCredential(key)
)
documents = [
    """Parker Doe has repaid all of their loans as of 2020-04-25.
    Their SSN is 859-98-0987. To contact them, use their phone number
    555-555-5555. They are originally from Brazil and have Brazilian CPF number 998.214.865-68"""
]

result = text_analytics_client.recognize_pii_entities(documents)
docs = [doc for doc in result if not doc.is_error]

print(
    "Let's compare the original document with the documents after redaction. "
    "I also want to comb through all of the entities that got redacted"
)
for idx, doc in enumerate(docs):
    print(f"Document text: {documents[idx]}")
    print(f"Redacted document text: {doc.redacted_text}")
    for entity in doc.entities:
        print("...Entity '{}' with category '{}' got redacted".format(
            entity.text, entity.category
        ))

返回的响应是一个异构的结果和错误对象列表：list[RecognizePiiEntitiesResult, DocumentError]

请参考服务文档了解支持的PII实体类型。

注意：识别PII实体服务在API版本v3.1及更高版本中可用。

提取关键短语

extract_key_phrases确定其输入文本中的主要论点。例如，对于输入文本"The food was delicious and there were wonderful staff"，API返回："food"和"wonderful staff"。

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import TextAnalyticsClient

endpoint = os.environ["AZURE_LANGUAGE_ENDPOINT"]
key = os.environ["AZURE_LANGUAGE_KEY"]

text_analytics_client = TextAnalyticsClient(endpoint=endpoint, credential=AzureKeyCredential(key))
articles = [
    """
    Washington, D.C. Autumn in DC is a uniquely beautiful season. The leaves fall from the trees
    in a city chock-full of forests, leaving yellow leaves on the ground and a clearer view of the
    blue sky above...
    """,
    """
    Redmond, WA. In the past few days, Microsoft has decided to further postpone the start date of
    its United States workers, due to the pandemic that rages with no end in sight...
    """,
    """
    Redmond, WA. Employees at Microsoft can be excited about the new coffee shop that will open on campus
    once workers no longer have to work remotely...
    """
]

result = text_analytics_client.extract_key_phrases(articles)
for idx, doc in enumerate(result):
    if not doc.is_error:
        print("Key phrases in article #{}: {}".format(
            idx + 1,
            ", ".join(doc.key_phrases)
        ))

返回的响应是一个异构的结果和错误对象列表：list[ExtractKeyPhrasesResult, DocumentError]

请参考服务文档，了解关键短语提取的概念性讨论。

检测语言

detect_language确定其输入文本的语言，包括预测语言的置信度分数。

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import TextAnalyticsClient

endpoint = os.environ["AZURE_LANGUAGE_ENDPOINT"]
key = os.environ["AZURE_LANGUAGE_KEY"]

text_analytics_client = TextAnalyticsClient(endpoint=endpoint, credential=AzureKeyCredential(key))
documents = [
    """
    The concierge Paulette was extremely helpful. Sadly when we arrived the elevator was broken, but with Paulette's help we barely noticed this inconvenience.
    She arranged for our baggage to be brought up to our room with no extra charge and gave us a free meal to refurbish all of the calories we lost from
    walking up the stairs :). Can't say enough good things about my experience!
    """,
    """
    最近由于工作压力太大，我们决定去富酒店度假。那儿的温泉实在太舒服了，我跟我丈夫都完全恢复了工作前的青春精神！加油！
    """
]

result = text_analytics_client.detect_language(documents)
reviewed_docs = [doc for doc in result if not doc.is_error]

print("Let's see what language each review is in!")

for idx, doc in enumerate(reviewed_docs):
    print("Review #{} is in '{}', which has ISO639-1 name '{}'\n".format(
        idx, doc.primary_language.name, doc.primary_language.iso6391_name
    ))

返回的响应是一个异构的结果和错误对象列表：list[DetectLanguageResult, DocumentError]

请参考服务文档，了解语言检测和语言和区域支持的概念性讨论。

医疗实体分析

长运行操作 begin_analyze_healthcare_entities从医疗保健领域提取识别到的实体，并在输入文档中的实体之间识别关系，并将链接到各种知名数据库中的已知信息源，如UMLS、CHV、MSH等。

import os
import typing
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import TextAnalyticsClient, HealthcareEntityRelation

endpoint = os.environ["AZURE_LANGUAGE_ENDPOINT"]
key = os.environ["AZURE_LANGUAGE_KEY"]

text_analytics_client = TextAnalyticsClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(key),
)

documents = [
    """
    Patient needs to take 100 mg of ibuprofen, and 3 mg of potassium. Also needs to take
    10 mg of Zocor.
    """,
    """
    Patient needs to take 50 mg of ibuprofen, and 2 mg of Coumadin.
    """
]

poller = text_analytics_client.begin_analyze_healthcare_entities(documents)
result = poller.result()

docs = [doc for doc in result if not doc.is_error]

print("Let's first visualize the outputted healthcare result:")
for doc in docs:
    for entity in doc.entities:
        print(f"Entity: {entity.text}")
        print(f"...Normalized Text: {entity.normalized_text}")
        print(f"...Category: {entity.category}")
        print(f"...Subcategory: {entity.subcategory}")
        print(f"...Offset: {entity.offset}")
        print(f"...Confidence score: {entity.confidence_score}")
        if entity.data_sources is not None:
            print("...Data Sources:")
            for data_source in entity.data_sources:
                print(f"......Entity ID: {data_source.entity_id}")
                print(f"......Name: {data_source.name}")
        if entity.assertion is not None:
            print("...Assertion:")
            print(f"......Conditionality: {entity.assertion.conditionality}")
            print(f"......Certainty: {entity.assertion.certainty}")
            print(f"......Association: {entity.assertion.association}")
    for relation in doc.entity_relations:
        print(f"Relation of type: {relation.relation_type} has the following roles")
        for role in relation.roles:
            print(f"...Role '{role.name}' with entity '{role.entity.text}'")
    print("------------------------------------------")

print("Now, let's get all of medication dosage relations from the documents")
dosage_of_medication_relations = [
    entity_relation
    for doc in docs
    for entity_relation in doc.entity_relations if entity_relation.relation_type == HealthcareEntityRelation.DOSAGE_OF_MEDICATION
]

注意：医疗保健实体分析仅在API版本v3.1及更高版本中可用。

多重分析

长运行操作 begin_analyze_actions在一个请求中对一组文档执行多个分析。目前它支持使用以下语言API的任何组合在一个请求中进行

• 实体识别
• PII实体识别
• 链接实体识别
• 关键短语提取
• 情感分析
• 自定义实体识别（API版本2022-05-01及更高版本）
• 自定义单标签分类（API版本2022-05-01及更高版本）
• 自定义多标签分类（API版本2022-05-01及更高版本）
• 医疗保健实体分析（API版本2022-05-01及更高版本）
• 提取式摘要（API版本2023-04-01及更高版本）
• 抽象式摘要（API版本2023-04-01及更高版本）

import os
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import (
    TextAnalyticsClient,
    RecognizeEntitiesAction,
    RecognizeLinkedEntitiesAction,
    RecognizePiiEntitiesAction,
    ExtractKeyPhrasesAction,
    AnalyzeSentimentAction,
)

endpoint = os.environ["AZURE_LANGUAGE_ENDPOINT"]
key = os.environ["AZURE_LANGUAGE_KEY"]

text_analytics_client = TextAnalyticsClient(
    endpoint=endpoint,
    credential=AzureKeyCredential(key),
)

documents = [
    'We went to Contoso Steakhouse located at midtown NYC last week for a dinner party, and we adore the spot! '
    'They provide marvelous food and they have a great menu. The chief cook happens to be the owner (I think his name is John Doe) '
    'and he is super nice, coming out of the kitchen and greeted us all.'
    ,

    'We enjoyed very much dining in the place! '
    'The Sirloin steak I ordered was tender and juicy, and the place was impeccably clean. You can even pre-order from their '
    'online menu at www.contososteakhouse.com, call 312-555-0176 or send email to order@contososteakhouse.com! '
    'The only complaint I have is the food didn\'t come fast enough. Overall I highly recommend it!'
]

poller = text_analytics_client.begin_analyze_actions(
    documents,
    display_name="Sample Text Analysis",
    actions=[
        RecognizeEntitiesAction(),
        RecognizePiiEntitiesAction(),
        ExtractKeyPhrasesAction(),
        RecognizeLinkedEntitiesAction(),
        AnalyzeSentimentAction(),
    ],
)

document_results = poller.result()
for doc, action_results in zip(documents, document_results):
    print(f"\nDocument text: {doc}")
    for result in action_results:
        if result.kind == "EntityRecognition":
            print("...Results of Recognize Entities Action:")
            for entity in result.entities:
                print(f"......Entity: {entity.text}")
                print(f".........Category: {entity.category}")
                print(f".........Confidence Score: {entity.confidence_score}")
                print(f".........Offset: {entity.offset}")

        elif result.kind == "PiiEntityRecognition":
            print("...Results of Recognize PII Entities action:")
            for pii_entity in result.entities:
                print(f"......Entity: {pii_entity.text}")
                print(f".........Category: {pii_entity.category}")
                print(f".........Confidence Score: {pii_entity.confidence_score}")

        elif result.kind == "KeyPhraseExtraction":
            print("...Results of Extract Key Phrases action:")
            print(f"......Key Phrases: {result.key_phrases}")

        elif result.kind == "EntityLinking":
            print("...Results of Recognize Linked Entities action:")
            for linked_entity in result.entities:
                print(f"......Entity name: {linked_entity.name}")
                print(f".........Data source: {linked_entity.data_source}")
                print(f".........Data source language: {linked_entity.language}")
                print(
                    f".........Data source entity ID: {linked_entity.data_source_entity_id}"
                )
                print(f".........Data source URL: {linked_entity.url}")
                print(".........Document matches:")
                for match in linked_entity.matches:
                    print(f"............Match text: {match.text}")
                    print(f"............Confidence Score: {match.confidence_score}")
                    print(f"............Offset: {match.offset}")
                    print(f"............Length: {match.length}")

        elif result.kind == "SentimentAnalysis":
            print("...Results of Analyze Sentiment action:")
            print(f"......Overall sentiment: {result.sentiment}")
            print(
                f"......Scores: positive={result.confidence_scores.positive}; \
                neutral={result.confidence_scores.neutral}; \
                negative={result.confidence_scores.negative} \n"
            )

        elif result.is_error is True:
            print(
                f"...Is an error with code '{result.error.code}' and message '{result.error.message}'"
            )

    print("------------------------------------------")

返回的响应是一个封装多个可迭代对象的对象，每个对象代表单独分析的结果。

注意：多个分析在API版本v3.1及更高版本中可用。

可选配置

可以在客户端和操作级别传递可选关键字参数。azure-core 参考文档描述了重试、日志记录、传输协议等可用的配置。

故障排除

一般

Text Analytics客户端将抛出在Azure Core中定义的异常。

日志记录

此库使用标准的logging库进行日志记录。HTTP会话的基本信息（URL、标头等）在INFO级别进行日志记录。

可以通过在客户端使用logging_enable关键字参数启用详细的DEBUG级别日志记录，包括请求/响应体和未脱敏的标头。

import sys
import logging
from azure.identity import DefaultAzureCredential
from azure.ai.textanalytics import TextAnalyticsClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

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

# This client will log detailed information about its HTTP sessions, at DEBUG level
text_analytics_client = TextAnalyticsClient(endpoint, credential, logging_enable=True)
result = text_analytics_client.analyze_sentiment(["I did not like the restaurant. The food was too spicy."])

同样，logging_enable可以为一个操作启用详细的日志记录，即使它没有为客户端启用

result = text_analytics_client.analyze_sentiment(documents, logging_enable=True)

下一步

更多示例代码

以下代码示例展示了使用Azure Text Analytics客户端库的常见场景操作。

使用认知服务/语言服务API密钥或azure-identity的令牌凭据对客户端进行身份验证

• sample_authentication.py (异步版本)

常见场景

• 分析情感：sample_analyze_sentiment.py (异步版本)
• 识别实体：sample_recognize_entities.py (异步版本)
• 识别个人身份信息：sample_recognize_pii_entities.py (异步版本)
• 识别链接实体：sample_recognize_linked_entities.py (异步版本)
• 提取关键短语：sample_extract_key_phrases.py (异步版本)
• 检测语言：sample_detect_language.py (异步版本)
• 医疗实体分析：sample_analyze_healthcare_entities.py (异步版本)
• 多分析：sample_analyze_actions.py (异步版本)
• 自定义实体识别：sample_recognize_custom_entities.py (异步版本)
• 自定义单标签分类：sample_single_label_classify.py (异步版本)
• 自定义多标签分类：sample_multi_label_classify.py (异步版本)
• 提取性文本摘要：sample_extract_summary.py (异步版本)
• 抽象文本摘要：sample_abstract_summary.py (异步版本)

高级场景

• 情感挖掘：请参考sample_analyze_sentiment_with_opinion_mining.py（异步版本）

附加文档

有关Azure认知服务语言的更多详细信息，请参阅docs.microsoft.com上的语言服务文档。

贡献

此项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），声明您有权并且实际上确实授予我们使用您的贡献的权利。有关详细信息，请访问cla.microsoft.com。

当您提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA，并适当地装饰PR（例如，标签、注释）。只需遵循机器人提供的说明即可。您只需在整个使用我们的CLA的存储库中这样做一次。

本项目已采用微软开源行为准则。有关更多信息，请参阅行为准则常见问题解答或通过opencode@microsoft.com联系以提出任何额外的问题或评论。

发布历史

5.3.0 (2023-06-15)

此客户端库版本默认使用服务API版本2023-04-01。

重大变更

注意：以下更改仅从上一个beta版开始破坏。它们不会破坏以前的稳定版本。

• 已将模型ExtractSummaryAction重命名为ExtractiveSummaryAction。
• 已将模型ExtractSummaryResult重命名为ExtractiveSummaryResult。
• 已将客户端方法begin_abstractive_summary重命名为begin_abstract_summary。
• 已删除客户端方法dynamic_classification和相关类型：DynamicClassificationResult和ClassificationType。
• 从begin_analyze_healthcare_entities和AnalyzeHealthcareEntitiesAction中删除了关键字参数fhir_version和document_type。
• 从AnalyzeHealthcareEntitiesResult中删除了属性fhir_bundle。
• 已删除枚举HealthcareDocumentType。
• 从CategorizedEntity中删除了属性resolutions。
• 删除了与解析相关的模型和枚举：ResolutionKind、AgeResolution、AreaResolution、CurrencyResolution、DateTimeResolution、InformationResolution、LengthResolution、NumberResolution、NumericRangeResolution、OrdinalResolution、SpeedResolution、TemperatureResolution、TemporalSpanResolution、VolumeResolution、WeightResolution、AgeUnit、AreaUnit、TemporalModifier、InformationUnit、LengthUnit、NumberKind、RangeKind、RelativeTo、SpeedUnit、TemperatureUnit、VolumeUnit、DateTimeSubKind和WeightUnit。
• 从RecognizeEntitiesResult、RecognizePiiEntitiesResult、AnalyzeHealthcareEntitiesResult、ExtractKeyPhrasesResult、RecognizeLinkedEntitiesResult、AnalyzeSentimentResult、RecognizeCustomEntitiesResult、ClassifyDocumentResult、ExtractSummaryResult和AbstractSummaryResult中删除了属性detected_language。
• 从DetectedLanguage中删除了属性script。

新增功能

• 为HealthcareEntityCategory和HealthcareEntityRelation添加了新的枚举值。

5.3.0b2 (2023-03-07)

此客户端库版本默认使用服务API版本2022-10-01-preview。

新增功能

• 添加了begin_extract_summary客户端方法，用于对文档进行提取式摘要。
• 添加了begin_abstractive_summary客户端方法，用于对文档进行抽象式摘要。

重大变更

• 删除了模型BaseResolution和BooleanResolution。
• 从ResolutionKind中删除了枚举值BooleanResolution。
• 已将模型AbstractSummaryAction重命名为AbstractiveSummaryAction。
• 已将模型AbstractSummaryResult重命名为AbstractiveSummaryResult。
• 从长时间运行的操作API中删除了关键字参数autodetect_default_language。

其他更改

• 改进了客户端库中的静态类型。

5.3.0b1 (2022-11-17)

此客户端库版本默认使用服务API版本2022-10-01-preview。

新增功能

• 添加了提取摘要功能和相关模型：ExtractSummaryAction、ExtractSummaryResult和SummarySentence。通过begin_analyze_actions API访问此功能。
• 向begin_analyze_healthcare_entities和AnalyzeHealthcareEntitiesAction添加了关键字参数fhir_version和document_type。
• 向AnalyzeHealthcareEntitiesResult添加了属性fhir_bundle。
• 向HealthcareRelation添加了属性confidence_score。
• 添加了枚举HealthcareDocumentType。
• 向CategorizedEntity添加了属性resolutions。
• 添加了与解析相关的模型和枚举：BaseResolution、ResolutionKind、AgeResolution、AreaResolution、BooleanResolution、CurrencyResolution、DateTimeResolution、InformationResolution、LengthResolution、NumberResolution、NumericRangeResolution、OrdinalResolution、SpeedResolution、TemperatureResolution、TemporalSpanResolution、VolumeResolution、WeightResolution、AgeUnit、AreaUnit、TemporalModifier、InformationUnit、LengthUnit、NumberKind、RangeKind、RelativeTo、SpeedUnit、TemperatureUnit、VolumeUnit、DateTimeSubKind和WeightUnit。
• 添加了抽象摘要功能和相关模型：AbstractSummaryAction、AbstractSummaryResult、AbstractiveSummary和SummaryContext。通过begin_analyze_actions API访问此功能。
• 向长时间运行的操作API添加了自动语言检测。将auto传递到文档language提示以使用此功能。
• 向长时间运行的操作API添加了autodetect_default_language。将其作为自动语言检测的默认/后备语言。
• 向以下结果对象添加了属性detected_language，以指示自动语言检测检测到的语言：RecognizeEntitiesResult、RecognizePiiEntitiesResult、AnalyzeHealthcareEntitiesResult、ExtractKeyPhrasesResult、RecognizeLinkedEntitiesResult、AnalyzeSentimentResult、RecognizeCustomEntitiesResult、ClassifyDocumentResult、ExtractSummaryResult和AbstractSummaryResult。
• 向DetectedLanguage添加了属性script，以指示输入文档的脚本。
• 添加了dynamic_classification客户端方法，用于在不需要训练模型的情况下对文档进行动态分类。

其他更改

• 删除了对msrest的依赖。

5.2.1 (2022-10-26)

错误修复

• 在begin_analyze_actions API中的操作失败时，在文档错误中返回更有帮助的消息。

5.2.0 (2022-09-08)

其他更改

客户端库的这个版本标志着稳定发布，默认为服务API版本2022-05-01。包括从5.2.0b1到5.2.0b5的所有更改。

5.2.0b5 (2022-08-11)

此客户端库的版本默认为API版本2022-05-01。

新增功能

• 添加了begin_recognize_custom_entities客户端方法，用于在文档中识别自定义命名实体。
• 添加了begin_single_label_classify客户端方法，用于在文档上执行自定义单标签分类。
• 添加了begin_multi_label_classify客户端方法，用于在文档上执行自定义多标签分类。
• 在包含长时间运行操作元数据的返回轮询对象上添加了属性details。
• 添加了TextAnalysisLROPoller和AsyncTextAnalysisLROPoller协议，以描述长时间运行操作的返回类型。
• 在轮询对象上添加了cancel方法。调用它以取消正在进行的长时间运行操作。
• 向以下结果对象添加了属性kind：RecognizeEntitiesResult、RecognizePiiEntitiesResult、AnalyzeHealthcareEntitiesResult、DetectLanguageResult、ExtractKeyPhrasesResult、RecognizeLinkedEntitiesResult、AnalyzeSentimentResult、RecognizeCustomEntitiesResult、ClassifyDocumentResult和DocumentError。
• 添加了枚举TextAnalysisKind。

重大变更

• 已移除文本提取摘要功能及相关模型： ExtractSummaryAction、ExtractSummaryResult 和 SummarySentence。要访问此测试版功能，请安装客户端库的 5.2.0b4 版本。
• 已移除 FHIR 功能及相关关键字参数和属性：fhir_version 和 fhir_bundle。要访问此测试版功能，请安装客户端库的 5.2.0b4 版本。
• 将 SingleCategoryClassifyResult 和 MultiCategoryClassifyResult 模型合并为一个模型： ClassifyDocumentResult。
• 将 SingleCategoryClassifyAction 重命名为 SingleLabelClassifyAction
• 将 MultiCategoryClassifyAction 重命名为 MultiLabelClassifyAction。

错误修复

• 当 F0 级语言资源超出调用配额时，将立即引发 HttpResponseError。

其他更改

• 不再支持 Python 3.6。请使用 Python 版本 3.7 或更高版本。有关更多详细信息，请参阅Azure SDK for Python 版本支持策略。

5.2.0b4 (2022-05-18)

请注意，这是第一个针对 Azure 认知服务语言 API 的客户端库版本，它包括 Text Analytics 客户端库中现有的文本分析和自然语言处理功能。此外，服务 API 已从语义版本更改为基于日期的版本。此版本的客户端库默认使用最新支持的 API 版本，目前为 2022-04-01-preview。已移除对 v3.2-preview.2 的支持，但所有功能均包含在最新版本中。

新增功能

• 通过 begin_analyze_actions API 和 AnalyzeHealthcareEntitiesAction 类型添加了对 Healthcare Entities Analysis 的支持。
• 向 begin_analyze_healthcare_entities 和 AnalyzeHealthcareEntitiesAction 添加了关键字参数 fhir_version。使用此关键字来指示 AnalyzeHealthcareEntitiesResult 中包含的 fhir_bundle 的版本。
• 向AnalyzeHealthcareEntitiesResult添加了属性fhir_bundle。
• 向 begin_analyze_healthcare_entities 添加了关键字参数 display_name。

5.2.0b3 (2022-03-08)

错误修复

• 现在，对于 AnalyzeSentimentAction 和 RecognizeCustomEntitiesAction，string_index_type 正确默认为 Python 默认的 UnicodeCodePoint。
• 修复了在客户端库测试版中对旧 API 版本 v3.1 目标时在 begin_analyze_actions 中发送不正确动作类型的问题。
• 将 string_index_type 选项 Utf16CodePoint 修正为 Utf16CodeUnit。

其他更改

• 不再支持 Python 2.7。请使用 Python 版本 3.6 或更高版本。

5.2.0b2 (2021-11-02)

此版本的 SDK 默认使用最新支持的 API 版本，目前为 v3.2-preview.2。

新增功能

• 通过 begin_analyze_actions API 和 RecognizeCustomEntitiesAction、RecognizeCustomEntitiesResult 类型添加了对自定义实体识别的支持。
• 通过 begin_analyze_actions API 和 SingleCategoryClassifyAction、SingleCategoryClassifyActionResult 类型添加了对自定义单分类的支持。
• 通过 begin_analyze_actions API 和 MultiCategoryClassifyAction、MultiCategoryClassifyActionResult 类型添加了对自定义多分类的支持。
• 现在支持 begin_analyze_actions 中的相同动作类型的多个实例。

错误修复

• 现在支持从保存的状态重启长运行操作，适用于 begin_analyze_actions 和 begin_recognize_healthcare_entities 方法。
• 在动作级别出现错误的情况下，现在在 begin_analyze_actions 中返回任何成功动作的可用部分结果。

其他更改

• 此软件包需要 azure-core 版本 1.19.1 或更高版本

5.2.0b1 (2021-08-09)

此版本的 SDK 默认使用最新支持的 API 版本，目前为 v3.2-preview.1。

新增功能

• 通过ExtractSummaryAction类型添加了对提取摘要操作的支持。

错误修复

• RecognizePiiEntitiesAction选项的disable_service_logs现在默认为True。

其他更改

• 不再支持Python 3.5。

5.1.0 (2021-07-07)

本版本的SDK默认使用最新的支持API版本，目前为v3.1。包括从5.1.0b1到5.1.0b7的所有更改。

注意：本版本将是最后一个官方支持Python 3.5的版本，未来的版本将需要Python 2.7或Python 3.6+。

新增功能

• 向RecognizePiiEntitiesAction添加了catagories_filter。
• 添加了HealthcareEntityCategory。
• 为begin_analyze_healthcare_entities方法添加了AAD支持。

重大变更

• 变更：现在being_analyze_actions的响应结构返回一个结果列表，其中每个结果都是文档操作结果的列表，顺序与文档和操作传递的顺序相同。
• 变更：begin_analyze_actions现在接受每类型一个操作。如果传递了重复的操作，将引发ValueError。
• 移除：AnalyzeActionsType。
• 移除：AnalyzeActionsResult。
• 移除：AnalyzeActionsError。
• 移除：HealthcareEntityRelationRoleType。
• 变更：将HealthcareEntityRelationType重命名为HealthcareEntityRelation。
• 变更：将PiiEntityCategoryType重命名为PiiEntityCategory。
• 变更：将PiiEntityDomainType重命名为PiiEntityDomain。

5.1.0b7 (2021-05-18)

重大变更

• 将begin_analyze_batch_actions重命名为begin_analyze_actions。
• 将AnalyzeBatchActionsType重命名为AnalyzeActionsType。
• 将AnalyzeBatchActionsResult重命名为AnalyzeActionsResult。
• 将AnalyzeBatchActionsError重命名为AnalyzeActionsError。
• 将AnalyzeHealthcareEntitiesResultItem重命名为AnalyzeHealthcareEntitiesResult。
• 修复了AnalyzeHealthcareEntitiesResult的statistics以正确类型，即TextDocumentStatistics。
• 移除RequestStatistics，改用TextDocumentBatchStatistics。

新功能

• 添加了枚举EntityConditionality、EntityCertainty和EntityAssociation。
• 将AnalyzeSentimentAction添加为begin_analyze_batch_actions支持的操作类型。
• 添加了kwarg disable_service_logs。如果设置为true，您将选择不在服务端记录文本输入以进行故障排除。

5.1.0b6 (2021-03-09)

重大变更

• 现在，我们通过枚举值TextAnalyticsApiVersion.V3_1_PREVIEW默认针对服务的v3.1-preview.4端点。
• 从HealthcareEntity移除了属性related_entities，并为医疗保健在文档响应级别上添加了entity_relations。
• 在MinedOpinion类中将属性aspect和opinions分别重命名为target和assessments。
• 将类AspectSentiment和OpinionSentiment分别重命名为TargetSentiment和AssessmentSentiment。

新功能

• 将RecognizeLinkedEntitiesAction添加为begin_analyze_batch_actions支持的操作类型。
• 将categories_filter参数添加到recognize_pii_entities客户端方法。
• 添加了枚举PiiEntityCategoryType。
• 向HealthcareEntity添加属性normalized_text。此属性是已存在于HealthcareEntity上的text属性的归一化版本。
• 向HealthcareEntity添加属性assertion。这包含有关实体的断言，即如果实体代表一个诊断，这个诊断是否取决于一个症状？

已知问题

• begin_analyze_healthcare_entities目前处于限定的预览版，不能与AAD凭据一起使用。有关更多信息，请参阅文本分析医疗保健文档。
• 在发布此SDK时，服务不尊重通过model_version传递给begin_analyze_healthcare_entities的值，它只使用最新模型。

5.1.0b5 (2021-02-10)

重大变更

• 将begin_analyze重命名为begin_analyze_batch_actions。
• 现在，您不再需要为要传递给 begin_analyze_batch_actions 的所有不同类型的操作单独传递参数，我们可以接受一个参数 actions，它是一个包含您希望执行的操作列表。操作的结果以输入的相同顺序返回。
• begin_analyze_batch_actions 返回的响应对象也已更改。现在，在您的长时间运行的操作完成后，我们返回一个按输入顺序分页的迭代器，其中包含操作结果。每个操作的实际文档结果包含在每个操作结果中的 document_results 属性下。

新功能

• begin_analyze_healthcare 已重命名为 begin_analyze_healthcare_entities。
• AnalyzeHealthcareResult 已重命名为 AnalyzeHealthcareEntitiesResult，而 AnalyzeHealthcareResultItem 已重命名为 AnalyzeHealthcareEntitiesResultItem。
• HealthcareEntityLink 已重命名为 HealthcareEntityDataSource，并已将其属性 id 重命名为 entity_id，将 data_source 重命名为 name。
• 从 AnalyzeHealthcareEntitiesResultItem 中删除了 relations，并在 HealthcareEntity 中添加了 related_entities。
• 将 Analyze Healthcare Entities 服务的取消逻辑从服务客户端移动到从 begin_analyze_healthcare_entities 返回的轮询对象。
• 在从 begin_analyze_healthcare_entities 返回的轮询对象上公开了 Analyze Healthcare Entities 操作元数据。
• 在调用 begin_analyze 和 begin_analyze_healthcare_entities 时，不再需要指定 api_version=TextAnalyticsApiVersion.V3_1_PREVIEW_3。尽管如此，begin_analyze_healthcare_entities 仍然处于受控预览中。
• 向服务客户端方法 begin_analyze_healthcare_entities、analyze_sentiment、recognize_entities、recognize_pii_entities 和 recognize_linked_entities 添加了新的参数 string_index_type，该参数告诉服务如何解释字符串偏移量。
• 向 CategorizedEntity、SentenceSentiment、LinkedEntityMatch、AspectSentiment、OpinionSentiment、PiiEntity 和 HealthcareEntity 添加了属性 length。

5.1.0b4 (2021-01-12)

错误修复

• 该包需要 1.8.2 或更高版本的 azure-core

5.1.0b3 (2020-11-19)

新功能

• 我们添加了 begin_analyze 方法，它支持命名实体识别、个人身份信息和关键词提取的长时间运行的批处理。要使用，您必须在创建客户端时指定 api_version=TextAnalyticsApiVersion.V3_1_PREVIEW_3。
• 我们添加了 begin_analyze_healthcare 方法，它支持服务的 Health API。由于 Health API 目前仅处于受控预览中，因此您必须将订阅添加到服务的允许列表中，并且在创建客户端时必须指定 api_version=TextAnalyticsApiVersion.V3_1_PREVIEW_3。请注意，由于这是一个受控预览，因此不支持 AAD。更多信息请参阅 此处。

5.1.0b2 (2020-10-06)

破坏性更改

• 从 CategorizedEntity、SentenceSentiment、LinkedEntityMatch、AspectSentiment、OpinionSentiment 和 PiiEntity 中删除了属性 length。要获取这些模型中文本的长度，只需在 text 属性上调用 len()。
• 当参数或端点与您指定的 API 版本不兼容时，我们现在将返回一个 ValueError，而不是 NotImplementedError。
• 客户端输入验证现在默认禁用。这意味着客户端 SDK 在输入格式不正确的情况下不会抛出 ValidationError。错误现在将通过 HttpResponseError 由服务抛出。

5.1.0b1 (2020-09-17)

新功能

• 我们现在将服务的 v3.1-preview API 作为默认值。如果您仍然想使用服务的 v3.0 版本，则在创建 TextAnalyticsClient 时将 v3.0 传递给 api_version 关键字参数。
• 我们添加了一个 API recognize_pii_entities，它返回包含批量文档中个人身份信息的实体。仅适用于 API 版本 v3.1-preview 及更高版本。
• 为CategorizedEntity、SentenceSentiment和LinkedEntityMatch添加了offset和length属性。这些属性仅在API版本3.1-preview及以上版本中可用。
  • length是这些模型文本中的字符数
  • offset是文本相对于文档开始的偏移量
• 现在已添加了对情感挖掘的支持。要使用此功能，请确保您正在使用服务的v3.1-preview API。要获取此支持，在调用analyze_sentiment端点时将show_opinion_mining传递为True。
• 将属性bing_entity_search_api_id添加到LinkedEntity类中。该属性仅在v3.1-preview及以上版本中可用，并与Bing实体搜索API一起使用，以检索有关返回实体的附加相关信息。

5.0.0 (2020-07-27)

• 重新发布GA版本1.0.0的新版本

1.0.0 (2020-06-09)

• azure-ai-textanalytics包的第一个稳定版本。针对服务的v3.0 API。

1.0.0b6（2020-05-27）

新功能

• 现在在每个文档级响应对象上都有warnings属性，它是一个TextAnalyticsWarning列表。
• 为SentenceSentiment添加了text属性

破坏性更改

• 现在仅针对服务的v3.0 API，而不是v3.0-preview.1 API
• DetectedLanguage的score属性已被重命名为confidence_score
• 从CategorizedEntity、SentenceSentiment和LinkedEntityMatch中删除了grapheme_offset和grapheme_length
• TextDocumentStatistics的grapheme_count属性已被重命名为character_count

1.0.0b5

• 这是一个有问题的发布

1.0.0b4（2020-04-07）

破坏性更改

• 已从库中删除recognize_pii_entities端点和所有相关模型（RecognizePiiEntitiesResult和PiiEntity）。
• 已删除TextAnalyticsApiKeyCredential，现在使用AzureKeyCredential（来自azure.core.credentials）作为密钥凭证
• 已将score属性重命名为confidence_score，适用于CategorizedEntity、LinkedEntityMatch和PiiEntity模型
• 所有输入参数inputs已重命名为documents

1.0.0b3（2020-03-10）

破坏性更改

• SentimentScorePerLabel已重命名为SentimentConfidenceScores
• AnalyzeSentimentResult和SentenceSentiment属性sentiment_scores已重命名为confidence_scores
• TextDocumentStatistics属性character_count已重命名为grapheme_count
• LinkedEntity属性id已重命名为data_source_entity_id
• 参数country_hint和language现在作为关键字参数传递
• 关键字参数response_hook已重命名为raw_response_hook
• length和offset属性已重命名为grapheme_length和grapheme_offset，用于SentenceSentiment、CategorizedEntity、PiiEntity和LinkedEntityMatch模型

新功能

• 传递country_hint="none"以不使用默认的国家提示"US"。

依赖关系更新

• 采用azure-core版本1.3.0或更高版本

1.0.0b2（2020-02-11）

破坏性更改

• 已从客户端库中删除单个文本、模块级操作single_detect_language()、single_recognize_entities()、single_extract_key_phrases()、single_analyze_sentiment()、single_recognize_pii_entities()和single_recognize_linked_entities()。在生产环境中使用批处理方法以获得最佳性能。
• 要使用API密钥作为客户端的身份验证凭据，必须为credential参数传递新的凭证类TextAnalyticsApiKeyCredential("<api_key>")。不再支持将API密钥作为字符串传递。
• detect_languages() 已重命名为 detect_language()。
• TextAnalyticsError 模型已被简化为仅具有属性 code、message 和 target 的对象。
• NamedEntity 已重命名为 CategorizedEntity，其属性 type 已重命名为 category，subtype 已重命名为 subcategory。
• RecognizePiiEntitiesResult 现在包含一个对象列表的 PiiEntity 而不是 NamedEntity。
• AnalyzeSentimentResult 属性 document_scores 已重命名为 sentiment_scores。
• SentenceSentiment 属性 sentence_scores 已重命名为 sentiment_scores。
• SentimentConfidenceScorePerLabel 已重命名为 SentimentScorePerLabel。
• DetectLanguageResult 不再具有属性 detected_languages。请使用 primary_language 访问文本中检测到的语言。

新功能

• 凭据类 TextAnalyticsApiKeyCredential 提供了一个 update_key() 方法，允许您为长生命周期客户端更新 API 密钥。

修复和改进

• 已为所有响应对象添加了 __repr__。
• 如果您尝试访问 DocumentError 对象上的结果属性，将引发具有自定义错误消息的 AttributeError，该错误消息提供文档 ID 和无效文档的错误。

1.0.0b1 (2020-01-09)

版本 (1.0.0b1) 是我们创建用户友好且 Pythonic 的 Azure Text Analytics 客户端库努力的第一个预览版。有关更多信息以及其他 Azure SDK 库的预览版本，请访问 https://azure.github.io/azure-sdk/releases/latest/python.html。

重大变更：新的 API 设计

• 新的命名空间/包名称

  • Azure Text Analytics 客户端库的命名空间/包名称已从 azure.cognitiveservices.language.textanalytics 更改为 azure.ai.textanalytics。

• 新的操作和命名

  • detect_language 已重命名为 detect_languages。
  • entities 已重命名为 recognize_entities。
  • key_phrases 已重命名为 extract_key_phrases。
  • sentiment 已重命名为 analyze_sentiment。
  • 新的操作 recognize_pii_entities 在文本中查找可识别的个人身份信息实体。
  • 新的操作 recognize_linked_entities 为每个识别的实体提供来自知名知识库的链接。
  • 添加了新的模块级操作 single_detect_language、single_recognize_entities、single_extract_key_phrases、single_analyze_sentiment、single_recognize_pii_entities 和 single_recognize_linked_entities，它们在单个字符串上执行功能而不是在文本文档批上，并可从 azure.ai.textanalytics 命名空间导入。
  • 已向子命名空间 azure.ai.textanalytics.aio 添加了新的客户端和模块级异步 API。
  • MultiLanguageInput 已重命名为 TextDocumentInput。
  • LanguageInput 已重命名为 DetectLanguageInput。
  • DocumentLanguage 已重命名为 DetectLanguageResult。
  • DocumentEntities 已重命名为 RecognizeEntitiesResult。
  • DocumentLinkedEntities 已重命名为 RecognizeLinkedEntitiesResult。
  • DocumentKeyPhrases 已重命名为 ExtractKeyPhrasesResult。
  • DocumentSentiment 已重命名为 AnalyzeSentimentResult。
  • DocumentStatistics 已重命名为 TextDocumentStatistics。
  • RequestStatistics 已重命名为 TextDocumentBatchStatistics。
  • Entity 已重命名为 NamedEntity。
  • Match 已重命名为 LinkedEntityMatch。
  • 批量方法的 documents 参数已重命名为 inputs。

• 新的输入类型

  • detect_languages 可以接受 list[DetectLanguageInput] 或 list[str] 作为输入。还可以接受与 DetectLanguageInput 形状相同的列表字典对象。
  • recognize_entities、recognize_pii_entities、recognize_linked_entities、extract_key_phrases、analyze_sentiment 方法可以接受输入为 list[TextDocumentInput] 或 list[str]。接受与 TextDocumentInput 形状相同的 dict-like 对象列表作为输入。

• 新的参数/关键字参数

  • 现在所有操作都接受一个关键字参数 model_version，允许用户指定用于分析的期望模型版本。如果没有指定字符串，则默认为最新的非预览版本。
  • detect_languages 现在接受一个参数 country_hint，允许您为整个批次指定国家提示。任何单个项目的国家提示将优先于整个批次的提示。
  • recognize_entities、recognize_pii_entities、recognize_linked_entities、extract_key_phrases、analyze_sentiment 现在接受一个参数 language，允许您为整个批次指定语言。任何单个项目指定的语言将优先于整个批次的提示。
  • 可以在客户端实例化时传递 default_country_hint 或 default_language 关键字参数来为所有操作设置默认值。
  • 可以传递一个 response_hook 关键字参数与回调一起使用，以使用服务的原始响应。此外，必须使用响应钩子检索返回的 TextDocumentBatchStatistics 和 model_version 的值。
  • show_stats 和 model_version 参数现在移动到关键字参数。

• 新的返回类型

  • 批量方法的返回类型（detect_languages、recognize_entities、recognize_pii_entities、recognize_linked_entities、extract_key_phrases、analyze_sentiment）现在返回一个异构列表，包含请求传入顺序的结果对象和文档错误。要迭代列表并筛选结果或错误，可以在每个对象上使用布尔属性 is_error 来确定返回的响应对象是否在索引处是结果还是错误。
  • detect_languages 现在返回一个 List[Union[DetectLanguageResult, DocumentError]]
  • recognize_entities 现在返回一个 List[Union[RecognizeEntitiesResult, DocumentError]]
  • recognize_pii_entities 现在返回一个 List[Union[RecognizePiiEntitiesResult, DocumentError]]
  • recognize_linked_entities 现在返回一个 List[Union[RecognizeLinkedEntitiesResult, DocumentError]]
  • extract_key_phrases 现在返回一个 List[Union[ExtractKeyPhrasesResult, DocumentError]]
  • analyze_sentiment 现在返回一个 List[Union[AnalyzeSentimentResult, DocumentError]]
  • 模块级别的单个文本操作将返回一个单一的结果对象或抛出在文档上发现的错误
  • single_detect_languages 返回一个 DetectLanguageResult
  • single_recognize_entities 返回一个 RecognizeEntitiesResult
  • single_recognize_pii_entities 返回一个 RecognizePiiEntitiesResult
  • single_recognize_linked_entities 返回一个 RecognizeLinkedEntitiesResult
  • single_extract_key_phrases 返回一个 ExtractKeyPhrasesResult
  • single_analyze_sentiment 返回一个 AnalyzeSentimentResult

• 新的底层 REST 管道实现，基于新的 azure-core 库。

• 客户端和管道配置现在可以通过客户端级别和每个操作的关键字参数获取。有关可选配置参数的完整列表，请参阅 README。

• 使用 azure-identity 凭据进行身份验证

  • 有关更多信息，请参阅Azure Identity 文档

• 新的错误层次结构

  • 现在所有服务错误都将使用基类型：azure.core.exceptions.HttpResponseError
  • 有一个派生自该基类型的异常类型用于身份验证错误
    • ClientAuthenticationError：身份验证失败。

0.2.0 (2019-03-12)

功能

• 客户端类可以用作上下文管理器以保持底层 HTTP 会话打开以提高性能
• 新的方法 "entities"
• 模型 KeyPhraseBatchResultItem 有一个新参数 statistics
• 模型 KeyPhraseBatchResult 有一个新参数 statistics
• 模型 LanguageBatchResult 有一个新参数 statistics
• 模型语言批次结果项（LanguageBatchResultItem）新增了统计参数。
• 模型情感批次结果（SentimentBatchResult）新增了统计参数。

破坏性更改

• 文本分析API的主客户端已重命名为TextAnalyticsClient。
• TextAnalyticsClient参数不再是区域，而是完整的端点。

通用重大更改

本版本使用新一代代码生成器，可能会引入重大更改。

• 模型签名现在仅使用关键字参数语法。所有位置参数必须重写为关键字参数。为了在大多数情况下保持自动完成，模型现在为Python 2和Python 3生成。Python 3使用"*"语法进行关键字参数。

• 枚举类型现在使用"str"混合（class AzureEnum(str, Enum)）来改进遇到未识别枚举值时的行为。虽然这不是一个重大更改，但区别很重要，在此处进行了记录：https://docs.pythonlang.cn/3/library/enum.html#others 简要说明

  • 不应使用"是"。
  • "格式"将返回字符串值，其中"%s"字符串格式将返回NameOfEnum.stringvalue。应优先使用格式语法。

错误修复

• 与wheel 0.31.0的sdist兼容性

0.1.0 (2018-01-12)

• 初始发布