Watson Developer Cloud Swift SDK

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

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

• 查看一个 精选项目
• 浏览 文档

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

• Assistant (助手)
• Discovery (发现)
• Language Translator V3 (语言翻译器 V3)
• Natural Language Understanding (自然语言理解)
• Speech to Text (语音转文本)
• Text to Speech (文本转语音)

从这个主版本 5.0.0 开始，Tone Analyzer API 已经移除，为弃用做准备。如果您希望继续使用此 SDK 调用 Tone Analyzer 直到其最终弃用，您将必须使用以前的版本。

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

作为替代方案，我们鼓励您考虑迁移到 IBM Cloud 上的 Natural Language Understanding 服务。使用 Natural Language Understanding，情感分析是通过使用预构建的分类模型来完成的，该模型提供了一种简单的方法来检测书面文本中的语言情感。有关更多信息，请参阅从 Watson Tone Analyzer 客户互动端点迁移到 Natural Language Understanding。

从这个主版本 5.0.0 开始，NLC API 已经移除，为弃用做准备。如果您希望继续使用此 SDK 调用 NLC 直到其最终弃用，您将必须使用以前的版本。

2021 年 8 月 9 日，IBM 宣布弃用 Natural Language Classifier 服务。该服务将于 2022 年 8 月 8 日起不再可用。从 2021 年 9 月 9 日起，您将无法创建新实例。现有实例将支持到 2022 年 8 月 8 日。在该日期仍然存在的任何实例将被删除。

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

• 您需要一个 IBM Cloud 帐户。

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

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

在 4.0.2 版本中新增，Watson Developer Cloud Swift SDK 现在通过 Swift Package Manager 支持所有服务。

在屏幕顶部的 XCode 菜单栏上，单击File -> Swift Packages -> Add Package Dependencies，按照提示粘贴 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 repo 下载，用于 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 菜单栏上，单击 Product -> Clean Build Folder，最后重新安装该包。

7. 您准备好了！

您可以使用 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 指南。

注意：Apple 新的 M1 芯片的发布导致 Carthage 在 XCode 11+ 版本中出现问题。在可预见的未来，我们无法通过 Carthage 支持 XCode 11。我们建议通过 Swift Package Manager 安装（首选）或升级到 XCode 12（其中有解决方法）。

注意：我们的框架目前无法通过 Carthage 在新的 Apple Silicon 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

按照其余的 Carthage 安装说明获取 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. 在应用程序目标的“Build Phases”设置选项卡上，单击 + 图标并选择“New Run Script Phase”。 创建一个运行脚本，您可以在其中指定您的 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 服务，您需要进行身份验证。 以下描述了您需要采取的典型路径。

使用 IBM Watson 服务的凭证通过 IBM Cloud 获得。 在您的 Swift 应用程序中进行身份验证之前，您需要一个有效的帐户和一个要使用的服务的服务实例。

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

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

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

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

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

示例

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

...

您可能希望提供一个持有者令牌来与服务进行身份验证。 在 IBM Cloud 上，这将通过使用 IAM 服务基于您的服务凭证生成令牌来完成。 在 Cloud Pak for Data 上，这将可以在单个服务实例中使用。

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

示例

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

...

如果您使用的是 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 代码。

您可以通过修改 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"

对于 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()

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

在调试 IBM 支持的问题时，可能会要求您提供 transaction 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 的酷炫开源项目！ 如果您想将您的项目添加到列表中，请随时创建一个问题并链接到它。

• 简单聊天 (Swift)
• Speech to Text (语音转文本)
• Text to Speech (文本转语音)

默认情况下，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)

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

为了绕过 CgBI 编码并保持 PNG 文件的格式与 Watson 服务兼容，请在 XCode 中选择 PNG 文件，然后在 File Inspector 中将 Type 属性修改为 Data。

例如

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

请参阅 本教程，以获取有关在 Objective-C 应用程序中使用 Watson Developer Cloud Swift SDK 的更多信息。

要在您的 Linux 项目中使用 Watson SDK，请按照 Swift Package Manager 说明进行操作。 请注意，语音转文本和文本转语音不受支持，因为它们依赖于 Linux 上不可用的框架。

我们欢迎任何和所有的帮助！ 如果您想贡献力量，请阅读我们的 CONTRIBUTING 文档，其中包含有关入门的信息。

此库在 Apache 2.0 下获得许可。 完整的许可证文本可在 LICENSE 中找到。

此 SDK 旨在与 Apple iOS 产品一起使用，并且旨在与官方授权的 Apple 开发工具结合使用。