标签和常规字段

本页介绍如何解释从 Communications Mining 平台下载的标签和常规字段，以在应用程序中使用。 本页介绍了标签和常规字段本身 - 要了解在下载的数据中可以找到它们，请务必查看所选下载方法的文档。

标签

注释可以有零个、一个或多个预测标签。 下面的示例显示了两个预测标签（ “顺序”和“顺序” >“缺失” ）及其置信度分数。 大多数 API 路由都使用此格式。 “数据集导出”路径是一个例外，它将标签名称的格式设置为字符串而不是列表（以与浏览器中的 CSV 导出保持一致）。

某些路由（当前为预测路由）将有选择地返回标签置信度分数符合的阈值名称（“高召回率”、“平衡”和“高精度”）。 这是手动选取阈值的有用替代方法，尤其是对于非常大的分类法。 在应用程序中，您决定是否对“高召回率”、“平衡”或“高精度”结果感兴趣，然后丢弃所有缺少所选自动阈值的标签，并像以前一样处理其余标签。

• 除“数据集导出”以外的所有路由

  {
    "labels": [
      {
        "name": ["Order"],
        "probability": 0.6598735451698303
      },
      {
        "name": ["Order", "Missing"],
        "probability": 0.6598735451698303
      }
    ]
  }

• 导出数据集

  {
    "labels": [
      {
        "name": "Order",
        "probability": 0.6598735451698303
      },
      {
        "name": "Order > Missing",
        "probability": 0.6598735451698303
      }
    ]
  }

• 预测 (自动阈值化)

  {
    "labels": [
      {
        "name": ["Order"],
        "probability": 0.6598735451698303,
        "auto_thresholds": ["high_recall", "balanced", "sampled_2"]
      },
      {
        "name": ["Order", "Missing"],
        "probability": 0.6598735451698303,
        "auto_thresholds": ["high_recall", "sampled_2"]
      }
    ]
  }

标签对象具有以下格式：

名称	类型	说明
name	数组<string> 或 字符串	除“数据集导出”以外的所有 API 路由：预测标签的名称，格式为层次结构标签列表。 例如，标签“父标签” > “子标签”的格式为["Parent Label", "Child Label"] 。 “数据集导出 API 路径”: 预测标签的名称，其格式为字符串，使用" > "分隔层次结构标签。
probability	数字	置信度分数。 0.0 到 1.0 之间的数字。
sentiment	数字	情感分数。 介于 -1.0 和 1.0 之间的数字。 仅在数据集中启用了情感时返回。
auto_thresholds	array<string>	标签置信度分数符合的自动计算阈值列表。 阈值以描述性名称（而不是 0.0 到 1 之间的值）返回，可用于轻松筛选出不符合所需置信度的标签。 阈值名称“高召回率”、“平衡”和“高精度”对应于三个递增的置信度级别。 附加的“sampled_0”…“sampled_5”阈值提供了一种为数据科学应用程序执行聚合的更高级方法，如果要逐一处理注释，则可以将其忽略。

标签常见问题解答

问：如何从 Communications Mining 平台下载标签？

答：以下下载方法提供标签：Communications Mining API 、 CSV 下载和 Communications Mining命令行工具。 请查看 “下载数据”页面，概述可用的下载方法，并查看下面的常见问题解答项目，以进行详细比较。

问：是否所有下载方法都提供相同的信息？

答：下表说明了下载方法之间的区别。 提供 Communications Mining 网页用户界面“探索”页面中的标签说明以进行比较。

非确定性方法

“探索”页面、CSV 下载、Communications Mining 命令行工具和导出 API 端点提供最新的可用预测。 请注意，在训练新的模型版本之后，在重新计算所有预测之前，您会混合看到来自最新和先前模型版本的预测。 这些方法可以识别已分配的标签，并将其显示为已分配或置信度分数为 1。

方法	已分配的标签	预测的标签
“探索”页面	“探索”页面可在视觉上区分分配的标签和预测的标签。 它不会报告已分配标签的置信度分数。	“探索”页面旨在支持模型训练工作流，因此会显示用户可能想要固定的选定预测标签。 它将优先显示满足平衡阈值的标签（从该标签的 F 分数派生），但如果用户可能想要固定标签，则也可能将概率较低的标签显示为建议。
导出 API	返回已分配的标签。	返回所有预测标签（不应用阈值）。
CSV 下载	为分配的标签返回 1 的置信度分数。 请注意，如果模型非常有把握，则预测标签的分数也可能为 1。	返回所有预测标签（不应用阈值）。
Communications Mining CLI	如果注释已分配标签，将同时返回该注释的已分配标签和预测标签。	返回所有预测标签（不应用阈值）。

确定性方法

与上述非确定性方法相反，流 API 和预测 API 路由将从特定模型版本返回预测。 因此，这些 API 路由的行为就像您从平台下载了注释，然后发送该注释以根据特定模型版本进行预测，并且不知道已分配的标签。

方法	已分配的标签	预测的标签
流 API 和预测 API	不知道已分配的标签。	返回置信度分数高于提供的标签阈值（如果未提供阈值，则高于默认值 0.25）的预测标签。

在自动化中使用标签

在设计基于每条消息做出决策的应用程序时，您需要将每个标签的置信度分数转换为“是”或“否”的答案。 为此，您可以确定将预测视为“是，标签适用”的最低置信度分数。 我们将此数字称为置信度分数阈值。

重要提示：

如何选择置信度分数阈值

一个常见的错误概念是选择与希望获得的精度相等的阈值（“我希望标签在至少 70％ 的情况下正确，因此我会选择置信度分数高于 0.70 的标签”）。 要了解阈值以及如何选择阈值，请查看集成指南的“置信度阈值”部分。

在分析中使用标签

如果要导出标签以在分析应用程序中使用，则决定是否向用户公开置信度分数非常重要。 对于业务分析应用程序的用户，您应使用自动化部分中描述的其中一种方法将置信度分数转换为是否存在标签。 另一方面，精通处理概率数据的数据科学应用程序用户将受益于原始置信度分数。

一个重要的注意事项是确保分析应用程序中的所有预测都来自同一模型版本。 如果您要升级集成以从新的模型版本中获取预测，则需要重新提取所有预测，以使数据保持一致。

标签属性

如果已将服务质量标签添加到数据集，则预测响应将包含每个注释的服务质量分数如果在数据集上启用了语气分数，则预测响应将包含每个注释的语气分数。 这两个分数都可以在响应的label_properties部分中找到。

{
  "label_properties": [
    {
      "property_id": "0000000000000001",
      "property_name": "tone",
      "value": -1.8130283355712891
    },
    {
      "id": "0000000000000002",
      "name": "quality_of_service",
      "value": -3.006324252113699913
    }
  ]
}

标签属性对象采用以下格式：

名称	类型	说明
name	字符串	标签属性的名称。
id	字符串	标签属性的内部 ID。
value	数字	标签属性的值。 介于 -10 和 10 之间的值。

通用字段

注释可以包含零个、一个或多个预测常规字段。 以下示例显示了一个预测的order_number实体。 请注意，与标签不同，常规字段没有关联的置信度分数。

"entities": [
    {
        "id": "0abe5b728ee17811",
        "name": "order_number",
        "span": {
            "content_part": "body",
            "message_index": 0,
            "utf16_byte_start": 58,
            "utf16_byte_end": 76,
            "char_start": 29,
            "char_end": 38
        },
        "name": "order_number",
        "kind": "order_number", # deprecated
        "formatted_value": "ABC-123456",
        "capture_ids": []
    }
]

API 以以下格式返回实体：

名称	类型	说明
id	字符串	实体 ID。
name	字符串	实体名称。
kind	字符串	（已弃用）实体种类。
formatted_value	字符串	实体值。
span	Span	一个对象，其中包含实体在注释中的位置。
capture_ids	array<int>	实体所属组的捕获 ID 。

Formatting

每个实体都有一个span和一个formatted_value 。 跨度表示相应注释中实体的边界。 formatted_value通常对应于该跨度涵盖的文本，但在下面描述的一些特定实例中除外。

货币量

Monetary Quantity实体将提取各种货币金额并应用通用格式。 例如，“100 万美元”、“1000000 美元”和“1,000,000 美元”都将提取为1,000,000.00 USD 。 由于提取值的格式一致，因此您可以通过空格拆分轻松获取币种和金额。

但是，如果币种不明确，则提取的值将保留不明确的币种。 例如，“$1M”和“$1,000,000”将提取为$1,000,000.00而不是1,000,000.00 USD ，因为 "$" 符号可以指加拿大元或澳大利亚元，也可以指美元。

日期

Date实体将提取注释中出现的任何日期，并使用标准ISO 8601 格式（后跟 UTC 时间）将其标准化。 例如，2020 年 1 月 25 日发送的电子邮件中的“2020 年 1 月 25 日”、“25/01/2020”和“now”都将提取为“2020-01-25 00:00 UTC”。

此格式将应用于具有与日期对应的类型的任何实体，例如取消日期、生效日期或用户训练过的任何类型的日期。

如果日期的某些部分缺失，则注释的时间戳将用作锚点； 2020 年 5 月 1 日发送的消息中的日期“五号下午 4 点”将提取为“2020-05-05 16:00 UTC”。 如果未提供时区，则使用注释的时区，但提取的日期将始终以 UTC 时区的形式返回。

国家/地区

国家/地区名称已标准化为通用值；例如，字符串“英国”和“英国”的格式化值均为“英国”。

捕获 ID

如果注释作为富文本处理，并且包含表格，并且在该表格中匹配了一个实体，则该实体的capture_ids属性将包含捕获 ID。 在表格同一行中匹配的实体将具有相同的捕获 ID，从而可以将它们分在一组。

例如， Order ID可以与Order Date相关联。 在引用多个订单的注释中，可以通过按捕获 ID 对实体进行分组来区分不同的订单详细信息。

目前，表格中匹配的实体仅属于一个组，即它们的capture_ids属性将仅包含一个 ID。 将来，该 API 可能会返回多个 ID。

在所有其他情况下， capture_id属性将为空列表。

注意：现在，通过 CSV 上传或 API 进行文本更新时，系统将保留实体。

常规字段常见问题解答

问：如何从 Communications Mining 平台下载常规字段？

答：以下下载方法提供常规字段：Communications Mining API和 Communications Mining命令行工具。 请查看下载数据概述，了解哪种方法适合您的用例。 请注意， CSV 下载内容不包含常规字段。

模型

临时标签和实时标签

为便于集成使用，可以在 Communications Mining 用户界面中将模型版本标记为staging或live 。 可以将此标签提供给预测 API 请求，以代替模型版本号。 这允许您的集成从临时或实时标签指向的任何模型版本中获取预测，平台用户可以从 Communications Mining 用户界面轻松管理这些预测。

模型版本详细信息

可以使用验证 API 端点获取有关特定模型版本的详细信息。

此外，对预测请求的响应包含有关用于进行预测的模型的信息。

"model": {
    "version": 2,
    "time": "2021-02-17T12:56:13.444000Z"
}

名称	类型	说明
time	时间戳	固定模型版本的时间。
version	数字	模型版本。