Watson Developer Cloud Swift SDK

已弃用的构建版本

概述

Watson Developer Cloud Swift SDK让移动开发者轻松构建基于Watson的应用程序。利用Swift SDK，您可以利用Watson强大的高级人工智能、机器学习和深度学习技术来理解非结构化数据，并以新方式与移动用户互动。

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

查看特色项目
查看文档

服务

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

公告

语调分析器的弃用

从此次主要版本5.0.0开始，为了准备弃用，已经删除了 Tone Analyzer 接口。如果您希望在最终弃用前继续使用此 SDK 调用 Tone Analyzer，您必须使用之前的版本。

2022 年 2 月 24 日，IBM 宣布了 Tone Analyzer 服务的弃用。该服务将于 2023 年 2 月 24 日不再可用。自 2022 年 2 月 24 日起，您将无法创建新实例。现有实例将被支持至 2023 年 2 月 24 日。

作为替代方案，我们鼓励您考虑迁移到 IBM 云上的自然语言理解服务。使用自然语言理解，通过预建的分类模型进行语调分析，可以轻松检测文本中的语言语调。有关更多信息，请参阅从 Watson Tone Analyzer Customer Engagement 端口迁移到自然语言理解。

自然语言分类器的弃用

从此次主要版本5.0.0开始，为了准备弃用，已经删除了 NLC 接口。如果您希望在最终弃用前继续使用此 SDK 调用 NLC，您必须使用之前的版本。

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

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

开始之前

您需要一个 IBM Cloud 账户。

要求

Xcode 10.2+
Swift 5.0+
iOS 10.0+

安装

IBM Watson Swift SDK 可以使用 Swift Package Manager、CocoaPods 或 Carthage 进行安装。

Swift Package Manager

从版本 4.0.2 开始，Watson 开发者云 Swift SDK 现在支持通过 Swift Package Manager 使用所有服务。

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

将服务导入到您的项目中

import AssistantV2
import DiscoveryV2
.
.
.

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

您需要安装 Homebrew
安装 libogg 和 opus
```
$ brew install libogg opus
```
必须根据当前库版本移除打包的动态库。

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
```
必须用为多架构编译的库替换已安装的静态库。这些库可以从以下 github 仓库下载：libogg 在此和 opus 在此

替换当前安装的 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

如果在执行上述步骤之前遇到了构建错误或预先导入了包，这时可能需要重新索引项目。从您的XCode项目文件中“Swift Packages”下移除WatsonDeveloperCloud包；然后，在屏幕顶部的XCode菜单栏中点击Product -> 清除构建文件夹，最后重新安装该包。
一切准备就绪！

Cocoapods

您可以使用 RubyGems 安装Cocoapods

$ sudo gem install cocoapods

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

use_frameworks!

target 'MyApp' do
    pod 'IBMWatsonAssistantV1', '~> 5.0.0'
    pod 'IBMWatsonAssistantV2', '~> 5.0.0'
    pod 'IBMWatsonDiscoveryV1', '~> 5.0.0'
    pod 'IBMWatsonLanguageTranslatorV3', '~> 5.0.0'
    pod 'IBMWatsonNaturalLanguageUnderstandingV1', '~> 5.0.0'
    pod 'IBMWatsonSpeechToTextV1', '~> 5.0.0'
    pod 'IBMWatsonTextToSpeechV1', '~> 5.0.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" ~> 5.0.0

按照以下步骤进行XCode 12解决方案的Carthage安装说明在此处。然后运行以下命令以构建依赖项和框架

$ carthage.sh bootstrap --platform iOS

注意，上述命令将下载并构建IBM Watson Swift SDK中的所有服务，这需要一段时间。

按照以下步骤将框架链接到您的XCode项目

请确保将构建好的框架（仅限于您应用程序需要的服务）拖放到您的应用程序目标下 通用 -> 框架、库和嵌入内容（XCode <= 10.x: 通用 -> 链接框架和库），并在需要它们的源文件中导入它们。您可以从源目录下 ./Carthage/Build/iOS 找到 .framework 文件。
以下框架需要添加到您应用程序中: IBMSwiftSDKCore.framework

应用程序将使用哪些服务（AssistantV1.framework，DiscoveryV1.framework 等）

（仅限语音到文本） Starscream.framework。务必将此框架添加到您的 input.xcfilelist 和 output.xcfilelist，以下将详细介绍
仅限 XCode 12：在 嵌入 列下，确保每个框架设置为 不嵌入
在您应用程序目标的“构建阶段”设置选项卡中，点击 "+ " 图标，选择“新建运行脚本阶段”。创建一个运行脚本，在其中指定您的 shell（例如：/bin/sh），并在 shell 下的脚本区域添加以下内容
```
/usr/local/bin/carthage copy-frameworks
```
创建一个名为 input.xcfilelist 的文件和一个名为 output.xcfilelist 的文件

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

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

将复制的框架的路径添加到 output.xcfilelist 中。例如
```
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/IBMSwiftSDKCore.framework
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/DiscoveryV1.framework
```
与输入文件一同指定输出文件，XCode 只需要在输入文件已更改或输出文件缺失时运行脚本。这意味着在没有使用 Carthage 重新构建框架的情况下，脏构建将更快。
将 input.xcfilelist 的路径添加到 Carthage 运行脚本阶段的“输入文件列表”部分。这通常会是 $(SRCROOT)/input.xcfilelist
将 output.xcfilelist 的路径添加到 Carthage 运行脚本阶段的“输出文件列表”部分。这通常会是 $(SRCROOT)/output.xcfilelist

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

认证

为了在 Swift 应用程序中使用 IBM Watson 服务，您需要进行认证。以下描述了您需要采取的典型路径。

第 1 步：获取凭证

为了使用 IBM Watson 服务，您需要通过 IBM Cloud 获取凭证。您需要在您的 Swift 应用程序中进行认证之前，拥有一个活动的账户和使用您希望使用的服务的服务实例。

您可以按照以下步骤访问您的实例的服务凭证：

访问 IBM Cloud 仪表板页面。
要么在您的资源列表中点击现有的 Watson 服务实例，要么点击 创建资源 > AI 创建一个服务实例。
单击您的服务实例左侧导航栏中的管理项目。

在这个页面上，您将看到用于在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云中服务实例的管理标签页，并单击下载凭证的按钮。文件将被称为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调用都返回一个包含交易ID的响应，该ID位于X-Global-Transaction-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的酷炫开源项目！如果您想将自己的项目加入列表，欢迎创建一个issue并提供链接。

同步执行

默认情况下，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项目时，您可能需要在XCode资源包中添加PNG图像。默认情况下，XCode将PNG文件转换为Apple的CgBI文件格式作为优化步骤。

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

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

例：

CgBI处理的未来计划

将来，我们将探索在Swift SDK中处理CgBI和PNG之间转换的选项，但目前这尚不可用。

Objective-C兼容性

有关在Objective-C应用程序中消费Watson Developer Cloud Swift SDK的更多信息，请参阅这篇教程。

Linux 兼容性

要在您的 Linux 项目中使用 Watson SDK，请遵循 Swift 包管理器说明。注意，由于语音到文本和文本到语音功能依赖于 Linux 上不可用的框架，因此它们不支持。

贡献

我们非常欢迎任何帮助！如果您想贡献力量，请阅读我们的贡献指南，了解如何开始。

许可

此库受 Apache 2.0 许可。完整许可证文本可在 LICENSE 中找到。

此 SDK 旨在与 Apple iOS 产品一起使用，并旨在与官方许可 Apple 开发工具一起使用。

IBMWatsonNaturalLanguageUnderstandingV1 5.0.0

IBMWatsonNaturalLanguageUnderstandingV1 5.0.0

IBMWatsonNaturalLanguageUnderstandingV1 5.0.0

Watson Developer Cloud Swift SDK

已弃用的构建版本

概述

服务

公告

语调分析器的弃用

自然语言分类器的弃用

开始之前

要求

安装

Swift Package Manager

Cocoapods

Carthage

认证

第 1 步：获取凭证

步骤 2：代码中认证

WatsonIAMAuthenticator（最常用）

WatsonBearerTokenAuthenticator

WatsonCloudPakForDataAuthenticator

从环境变量中检测认证

关于认证方法的其他信息

自定义服务URL

禁用SSL证书验证

获取交易ID

自定义头信息

问答

特色项目

同步执行

在XCode中处理PNG和CgBI文件

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

CgBI处理的未来计划

Objective-C兼容性

Linux 兼容性

贡献

许可