Watson Developer Cloud Swift SDK

弃用构建

概述

Watson Developer Cloud Swift SDK 使移动开发者能够轻松构建并由 Watson 驱动的应用程序。使用 Swift SDK，您可以利用 Watson 先进的 artificial intelligence、machine learning 和 deep learning 技术来理解非结构化数据并以新的方式与移动用户互动。

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

查看精选项目
查看文档

服务

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

从本次主要版本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上的自然语言理解服务。通过自然语言理解，语调分析通过预构建的分类模型完成，这提供了一个简单的方式来检测文本中的语言语调。更多信息，请参阅从Watson Tone Analyzer Customer Engagement端点到自然语言理解的迁移。

从本次主要版本5.0.0开始，为准备弃用，已移除NLC API。如果您希望在最后一次弃用前继续使用此SDK调用NLC，您需要使用旧版本。

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

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

在开始之前

您需要 IBM Cloud 帐户。

要求

Xcode 10.2+
Swift 5.0+
iOS 10.0+

安装

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

Swift Package Manager

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

在屏幕顶部的 XCode 菜单栏中点击 文件 -> Swift 包 -> 添加包依赖项，根据提示粘贴 https://github.com/watson-developer-cloud/swift-sdk 的 git url，如有必要，请使用最新的大版本。请确保只选择您计划使用的服务，否则您可能会遇到较长的构建时间

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

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 菜单栏中点击 产品 -> 清理构建文件夹，最后重新安装包。
现在你可以出发了！

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 在新的苹果硅 MacBook 上运行。再次建议使用 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：在“嵌入”列中，请确保每个框架都被设置为 不嵌入
在您的应用程序目标的构建阶段设置标签页中，单击加号图标并选择新建 Run Script 阶段。在 shell 下方创建一个 Run Script，并指定您的 shell（例如：/bin/sh），在以下脚本区域添加以下内容
```
/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 访问服务实例的凭证。

第二步：代码验证

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

您可能需要提供一个bearer token以进行服务验证。在IBM Cloud中，这可以通过IAM服务生成基于您的服务凭证的token来完成。在Cloud Pak for Data中，这可以在某个服务实例内完成。

要使用访问token在Swift应用中进行验证，您可以使用WatsonBearerTokenAuthenticator，并传入token。

示例

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

...

WatsonCloudPakForDataAuthenticator

如果您是使用IBM Cloud Pak for Data（CP4D）而非公共IBM Cloud，则可以使用WatsonCloudPakForDataAuthenticator对您的CP4D集群进行验证。与接受bearer token的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文件的 contents 合并到单个文件中。可以添加、删除或重新排列文件中的行，但不能更改每行的内容。

关于认证方法的其他信息

要查看更多信息及较少使用的其他认证形式，请参阅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的酷炫开源项目！如果您希望将项目添加到列表中，请随意创建一个链接到它的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项目时，您可能需要将PNG图像添加到XCode资源包中。默认情况下，XCode将作为一个优化步骤将PNG文件转换为苹果的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开发工具一起使用。

IBM Watson Discovery V2 5.0.0

IBM Watson Discovery V2 5.0.0

IBM Watson Discovery V2 5.0.0

Watson Developer Cloud Swift SDK

弃用构建

概述

服务

在开始之前

要求

安装

Swift Package Manager

Cocoapods

Carthage

身份验证

步骤 1：获取凭证

第二步：代码验证

WatsonIAMAuthenticator（最常用）

WatsonBearerTokenAuthenticator

WatsonCloudPakForDataAuthenticator

通过环境变量检测验证

关于认证方法的其他信息

自定义服务URL

禁用SSL证书验证

获取事务ID

自定义头信息

问题

特色项目

同步执行

在XCode中处理PNG和CgBI文件

如何绕过资源文件CgBI编码

处理CgBI的未来的计划

Objective-C兼容性

Linux兼容性

贡献

许可