IBMWatsonToneAnalyzerV3 4.3.0

IBMWatsonToneAnalyzerV3 4.3.0

×

由 watdevex, Jeff Arn 维护。

IBMWatsonToneAnalyzerV3 4.3.0

  • 由
  • Jeff Arn 和 Mike Kistler

Watson 开发者云 Swift SDK

Build Status Carthage Compatible Documentation CLA assistant wdc-community.slack.com

概览

Watson 开发者云 Swift SDK 使得移动开发者能够轻松地构建 Watson 驱动的应用程序。通过 Swift SDK，您可以利用 Watson 先进的人工智能、机器学习和深度学习技术，以新的方式理解非结构化数据并与移动用户互动。

有许多资源可以帮助您使用 Swift SDK 构建您的第一个认知应用程序

服务

此 SDK 提供了访问以下 Watson 服务的类和方法。

公告

自然语言分类器弃用

2021年8月9日，IBM宣布弃用自然语言分类器服务。该服务将从2022年8月8日起不再可用。自2021年9月9日起，您将无法创建新实例。现有实例将得到支持，直至2022年8月8日。到那天为止仍存在的任何实例将被删除。

作为替代选项，我们鼓励您考虑迁移到IBM Cloud上的自然语言理解服务，该服务使用深度学习从文本中提取数据和分析，如关键词、类别、情感、情绪和语法，并具有高级多标签文本分类功能，为您的业务或行业提供更丰富的洞察。有关更多信息，请参阅自然语言理解迁移。

从watsonplatform.net更新端点URL

位于watsonplatform.net的Watson API端点URL将发生更改，并在2021年5月26日之后不再适用。请更新调用以使用最新的端点URL。有关更多信息，请参阅Watson端点更改。

个性化洞察弃用

IBM Watson™ 个性化洞察服务已停用。自2020年12月1日起的一年期间，您仍然可以使用Watson 个性化洞察服务。但是，从2021年12月1日起，该服务将不再可用。

作为替代选项，我们鼓励您考虑迁移到IBM Watson™ 自然语言理解服务，这是一种在IBM Cloud®上使用深度学习从文本中提取数据和分析的服务，如关键词、类别、情感、情绪和语法，以为您提供业务或行业的洞察。有关更多信息，请参阅关于自然语言理解。

视觉识别弃用

IBM Watson™视觉识别服务已停用。现有实例将支持至2021年12月1日，但自2021年1月7日起，无法创建实例。2021年12月1日创建的任何实例将被删除。

比较和合规弃用

IBM Watson™比较和合规服务已停用。现有实例将支持至2021年11月30日，但自2020年12月1日起，无法创建实例。2021年11月30日存在的任何实例将被删除。请考虑将您的比较和合规用例迁移到IBM Cloud上的Watson Discovery Premium。要开始迁移过程，请访问https://ibm.biz/contact-wdc-premium。

开始前

要求

  • Xcode 10.2+
  • Swift 5.0+
  • iOS 10.0+

安装

可以使用Swift Package Manager，Cocoapods或Carthage安装IBM Watson Swift SDK。

Swift 包管理器

4.0.2 版本新增功能，Watson 开发者云 Swift SDK 现已通过 Swift 包管理器支持所有服务。

在您的屏幕顶部的 XCode 菜单栏中点击 文件 -> Swift Packages -> 添加包依赖，按照提示粘贴 github url https://github.com/watson-developer-cloud/swift-sdk，并在适用的情况下使用最新的主要版本。请确保只单击您计划使用的服务，否则您可能面临漫长的构建时间。

要将服务导入到您的项目中

import AssistantV2
import DiscoveryV2
.
.
.

(仅限语音转文本和文本转语音) 使用这些服务的 libogg 和 opus 库需要在进行包安装之前采取额外的步骤。

  1. 您需要安装 Homebrew

  2. 安装 libogg 和 opus

    $ brew install libogg opus

  3. 必须根据当前库版本移除打包的动态库。

    libogg 版本：1.3.4。

    opus 版本：1.3.1

    $ rm -f /usr/local/Cellar/libogg/1.3.4/lib/*.dylib
    $ rm -f /usr/local/Cellar/opus/1.3.1/lib/*.dylib

  4. 必须将安装的静态库替换为适用于多个架构编译的库。您可以从以下 github 仓库下载 libogg：此处和 opus：此处

  5. 替换当前安装的 libogg 和 libopus 库

    rm -f /usr/local/Cellar/libogg/1.3.4/lib/libogg.a && cp ~/Downloads/libogg.a /usr/local/Cellar/libogg/1.3.4/lib
    rm -f /usr/local/Cellar/opus/1.3.1/lib/libopus.a && cp ~/Downloads/libopus.a /usr/local/Cellar/opus/1.3.1/lib

  6. 如果您在执行上述步骤之前导入包或在构建时遇到任何错误，则可能需要重新索引项目。从您的 XCode 项目文件中的 Swift Packages 下删除 WatsonDeveloperCloud 包；然后，从屏幕顶部的 XCode 菜单栏单击 产品 -> 清空构建文件夹，最后重新安装包。

  7. 您就可以开始了！

CocoaPods

您可以使用 RubyGems 安装 Cocoapods

$ sudo gem install cocoapods

如果您的项目还没有 Podfile，请在您的项目根目录中使用 pod init 命令。要使用 Cocoapods 安装 Swift SDK，将要在您应用中使用的服务添加到您的 Podfile 中，如下所示（将 MyApp 替换为您应用的名称）。以下示例显示了所有当前可用的服务；您的 Podfile 应仅包括您的应用将使用的服务。

use_frameworks!

target 'MyApp' do
    pod 'IBMWatsonAssistantV1', '~> 4.3.0'
    pod 'IBMWatsonAssistantV2', '~> 4.3.0'
    pod 'IBMWatsonCompareComplyV1', '~> 4.3.0'
    pod 'IBMWatsonDiscoveryV1', '~> 4.3.0'
    pod 'IBMWatsonLanguageTranslatorV3', '~> 4.3.0'
    pod 'IBMWatsonNaturalLanguageClassifierV1', '~> 4.3.0'
    pod 'IBMWatsonNaturalLanguageUnderstandingV1', '~> 4.3.0'
    pod 'IBMWatsonPersonalityInsightsV3', '~> 4.3.0'
    pod 'IBMWatsonSpeechToTextV1', '~> 4.3.0'
    pod 'IBMWatsonTextToSpeechV1', '~> 4.3.0'
    pod 'IBMWatsonToneAnalyzerV3', '~> 4.3.0'
    pod 'IBMWatsonVisualRecognitionV3', '~> 4.3.0'
end

运行 pod install 命令，并打开生成的 .xcworkspace 文件。要更新到最新版本，使用 pod update。

在源文件中导入框架时，请排除 IBMWatson 前缀和版本后缀。例如，在安装 IBMWatsonAssistantV1 之后，在源文件中导入它为 import Assistant。

有关使用 Cocoapods 的更多信息，请参阅Cocoapods 指南。

Carthage

注意：苹果公司发布的新M1芯片导致Carthage遇到了XCode 11+版本的问题。在未来可预见的时期内，我们无法通过Carthage支持XCode 11。我们推荐您通过Swift Package Manager（首选方案）安装，或者升级到XCode 12（有解决方法）。

注意：我们的框架目前无法通过Carthage在新苹果硅芯片的Mac上运行。我们再次建议您使用Swift Package Manager。

您可以使用Homebrew安装Carthage。

$ brew update
$ brew install carthage

如果您的项目还没有Cartfile，请在项目的根目录下运行touch Cartfile命令。要使用Carthage安装IBM Watson Swift SDK，请将以下内容添加到您的Cartfile中。

github "watson-developer-cloud/swift-sdk" ~> 4.3.0

请遵循以下XCode 12的解决方法安装步骤这里。然后运行以下命令来构建依赖项和框架

$ carthage.sh bootstrap --platform iOS

请注意，上述命令会下载和构建IBM Watson Swift SDK的全部服务，这可能需要一些时间。

请遵循以下步骤将框架链接到您的XCode项目

  1. 请确保将构建的框架（仅限于您的应用所需的框架）拖放到您的应用目标下的General -> Frameworks, Libraries, and Embedded Content (XCode <= 10.x: General -> Linked Frameworks and Libraries) 中，并在需要它们的源文件中导入它们。您可以在您的源目录下的./Carthage/Build/iOS 中找到.framework文件。

  2. 需要添加到您的应用中的框架有：IBMSwiftSDKCore.framework

    您的应用将使用的服务（例如：AssistantV1.framework，DiscoveryV1.framework等）

    (仅限语音识别) Starscream.framework。请确保将其添加到您的input.xcfilelist和output.xcfilelist文件中，具体内容将在下文详细介绍

  3. 仅限XCode 12：在Embed列中确保每个框架都设置为Do Not Embed

  4. 在您的应用程序目标的构建阶段设置标签页中，点击+图标并选择新建Run Script阶段。创建一个Run Script，在其中指定您的shell（例如：/bin/sh），在shell下面的脚本区域中添加以下内容

    /usr/local/bin/carthage copy-frameworks

  5. 创建一个名为input.xcfilelist的文件和一个名为output.xcfilelist的文件

  6. 将您要使用的框架的路径添加到您的input.xcfilelist中。例如

    $(SRCROOT)/Carthage/Build/iOS/IBMSwiftSDKCore.framework
$(SRCROOT)/Carthage/Build/iOS/DiscoveryV1.framework

  7. 将复制的框架的路径添加到output.xcfilelist中。例如

    $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/IBMSwiftSDKCore.framework
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/DiscoveryV1.framework

    与输入文件一起指定输出文件后，只有在输入文件已更改或输出文件缺失时，XCode才需要运行脚本。这意味着，在没有使用Carthage重新构建框架的情况下，脏构建将更快。

  8. 将input.xcfilelist的路径添加到Carthage运行脚本阶段的“Input File Lists”部分。这通常是$(SRCROOT)/input.xcfilelist

  9. 将output.xcfilelist的路径添加到Carthage运行脚本阶段的“Output File Lists”部分。这通常是$(SRCROOT)/output.xcfilelist

如果您的应用程序由于使用了与下载的 SDK 不同版本的 Swift 而无法构建，那么带上 --no-use-binaries 标志重新运行 carthage.sh bootstrap 命令。

认证

为了在 Swift 应用程序中使用 IBM Watson 服务，您需要进行身份验证。以下说明了您需要遵循的典型路径。

步骤 1：获取凭据

使用 IBM Watson 服务的凭据是通过 IBM Cloud 获取的。在您的 Swift 应用中进行身份验证之前，您需要一个活跃的账户和一个要使用的服务的服务实例。

您可以通过以下步骤访问您的实例的服务凭据：

  1. 转到 IBM Cloud 的 仪表板 页面。
  2. 要么点击您的 资源列表 中的一个现有的 Watson 服务实例，要么点击 创建资源 > AI 创建一个服务实例。
  3. 点击您的服务实例左侧导航栏中的 管理 项。

在此页面上，您将看到用于 SDK 访问您的服务实例的凭据。

步骤 2：在代码中进行认证

Watson Swift SDK 使用 Authenticator 类来管理身份验证。根据您首选的方法，有多种身份验证器类型。

WatsonIAMAuthenticator（最常见）

WatsonIAMAuthenticator 允许您使用 IAM API 密钥进行身份验证。这是 IBM Cloud 中最常用的身份验证形式。《WatsonIAMAuthenticator》初始化方法需要一个 `apikey` 字符串。

示例

let authenticator = WatsonIAMAuthenticator(apiKey: "{apikey}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)

...

WatsonBearerTokenAuthenticator

您可能需要提供一个访问令牌来与一个服务进行身份验证。在IBM Cloud上，这可以通过IAM服务使用服务凭据生成令牌来完成。在Cloud Pak for Data上，这将在单个服务实例中可用。

要使用访问令牌在Swift应用中进行身份验证，您可以使用WatsonBearerTokenAuthenticator并提供令牌。

示例

let authenticator = WatsonBearerTokenAuthenticator(bearerToken: "{token}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)

...

WatsonCloudPakForDataAuthenticator

如果您使用的是IBM Cloud Pak for Data (CP4D) 而不是公共IBM Cloud，可以使用 WatsonCloudPakForDataAuthenticator 来对CP4D集群进行身份验证。与接受访问令牌的WatsonBearerTokenAuthenticator相比，WatsonCloudPakForDataAuthenticator 接受CP4D集群自身的用户名和密码。

示例

let authenticator = WatsonCloudPakForDataAuthenticator(username: "{username}", password: "{password}", url: "https://{cpd_cluster_host}{:port}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)

...

从环境变量检测身份验证

SDK可以从环境变量中提取服务凭据，例如VCAP_SERVICES环境变量或本地凭据文件。

要使用本地文件中存储的凭据，请转到IBM Cloud上您的服务实例的管理标签，然后单击按钮下载凭据。该文件将命名为ibm-credentials.env。将此文件添加到可以从您的项目访问的位置。对于iOS应用，请确保将其添加到应用程序目标。

let assistant = Assistant(version: "your-version") // by calling the init method without an authenticator, the SDK will search for environment variables

...

如果您的项目使用多个Watson服务，可以将ibm-credentials.env文件的内容合并到一个文件中。文件中的行可以添加、删除或重新排序，但每行的内容不得更改。

有关身份验证方法的更多信息

要查看更多详细信息和其他不常见的身份验证形式，请参阅IBM Swift SDK Core的Authenticator代码。

自定义服务URL

您可以通过修改 serviceURL 属性来自定义服务URL。在某些特定区域运行实例或通过代理进行连接时可能需要自定义服务URL。

例如，以下是连接到托管在德国的 Watson Assistant 实例的方法

let authenticator = WatsonIAMAuthenticator(apiKey: "{apikey}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)

assistant.serviceURL = "https://api.eu-de.assistant.watson.cloud.ibm.com"

禁用SSL证书验证

对于 Watson Cloud Pak for Data (CP4D)，如果您使用的是自签名证书，可能需要禁用 SSL 主机验证。每个服务类都有一个 disableSSLVerification 方法允许您这样做。

let authenticator = WatsonCloudPakForDataAuthenticator(username: "{username}", password: "{password}", url: "https://{cpd_cluster_host}{:port}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)

assistant.disableSSLVerification()

注意：disableSSLVerification() 目前在 Linux 上不受支持。

获取事务ID

在调试与 IBM 支持的问题时，您可能需要提供 事务ID 以帮助 IBM 识别需要调试的 API 调用。

每个 SDK 调用都会返回一个响应，该响应在 X-Global-Transaction-Id 标头中包含一个事务ID。该服务实例区域和此ID一起帮助支持团队从相关日志中调试问题。

您可以按照以下模式访问标头

import AssistantV1

let authenticator = WatsonIAMAuthenticator(apiKey: "{apikey}")
let assistant = Assistant(version: "2020-04-01", authenticator: authenticator)
assistant.serviceURL = "{url}"

let input = MessageInput(text: "Hello")

// let's say this request isn't working and you need the transaction ID
assistant.message(workspaceID: "{workspace_id}", input: input) {
  response, error in

  print(response?.headers["X-Global-Transaction-Id"]!)

  ...
}

然而，当 API 由于某种原因没有返回响应时，事务ID不可用。在这种情况下，您可以在请求中设置自己的事务ID。例如，以下示例中将 <my-unique-transaction-id> 替换为唯一的事务ID。

let authenticator = WatsonIAMAuthenticator(apiKey: "{apikey}")
let assistant = Assistant(version: "2020-04-01", authenticator: authenticator)
assistant.serviceURL = "{url}"

let input = MessageInput(text: "Hello")

assistant.message(workspaceID: "{workspace_id}", input: input, headers: ["X-Global-Transaction-Id": "<my-unique-transaction-id>"]) {
  response, error in

  print(response?.headers["X-Global-Transaction-Id"]!)

  ...
}

自定义标头

可以将不同类型的标头发送到 Watson 服务。例如，Watson 服务会记录请求及其结果以提高服务质量，但您可以通过包含 X-Watson-Learning-Opt-Out 标头来退出此功能。

我们已在每个类中公开了一个名为 defaultHeaders 的公共属性，使用户能够轻松自定义其标头。

let authenticator = WatsonIAMAuthenticator(apiKey: "{apikey}")
let assistant = Assistant(version: "{version}", authenticator: authenticator)

assistant.defaultHeaders = ["X-Watson-Learning-Opt-Out": "true"]

每个服务方法也接受一个可选的 headers 参数，该参数是要与请求一起发送的请求头部的字典。

问题

如果您在使用API或关于Watson服务的相关疑问，请访问Stack Overflow。

精选项目

我们喜欢推荐酷炫的开源项目，如果希望自己的项目被加入列表，可以自由创建问题，并提供链接。

同步执行

默认情况下，SDK以异步方式执行所有网络操作。如果您的应用程序需要同步执行，可以使用DispatchGroup。例如

let dispatchGroup = DispatchGroup()
dispatchGroup.enter()
assistant.message(workspaceID: workspaceID) { response, error in
	if let error = error {
        print(error)
    }
    if let message = response?.result else {
        print(message.output.text)
    }
    dispatchGroup.leave()
}
dispatchGroup.wait(timeout: .distantFuture)

在XCode中处理PNG和CgBI文件

当处理iOS项目时，您可能需要将PNG图像添加到XCode资源包中。默认情况下，XCode将PNG文件转换为Apple的CgBI文件格式作为优化步骤。

接受PNG图像作为输入文件的Watson服务（视觉识别、对比和遵守）无法处理CgBI文件。在某些情况下，通过传递已经编码为CgBI的PNG可能会导致HTTP错误，在其他情况下（视觉识别）将导致返回200 成功但没有结果。

如何绕过资源文件中的CgBI编码

为了绕过CgBI编码并保持PNG文件以适应Watson服务的格式，在XCode中选择PNG文件，并在文件检查器中将类型属性修改为数据。

例：
File inspector example

处理 CgBI 的未来计划

在未来，我们将探索在 Swift SDK 中处理 CgBI 与 PNG 转换的选项，但目前这一功能尚不可用。

Objective-C 兼容性

有关在 Objective-C 应用程序中消耗 Watson 开发者云 Swift SDK 的更多信息，请参阅此教程。

Linux 兼容性

要在 Linux 项目中使用 Watson SDK，请遵循Swift Package Manager 指令。请注意，语音转文本和文本转语音不支持，因为它们依赖于 Linux 上不可用的工作框架。

贡献

我们非常欢迎任何形式的支持和帮助！如果您想贡献力量，请阅读我们的贡献文档，了解如何开始。

授权

本库采用 Apache 2.0 授权。完整的授权文本可在授权文件中找到。

本 SDK 旨在与 Apple iOS 产品配合使用，并计划与官方授权的 Apple 开发工具一起使用。