Watson Developer Cloud Swift SDK

概述

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

有很多资源可以帮助您使用 Swift SDK 构建,《a>`构建您的第一个认知应用程序

查看特色项目
浏览文档

服务

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

助手
比较与合规 *已弃用，由 Discovery 取代
Discovery
语言翻译 V3
自然语言分类器
自然语言理解
个性洞察 *已弃用，由自然语言理解取代
语音转文字
文字转语音
语调分析
视觉识别 *已弃用，由 Maximo Visual Inspection 取代

公告

自然语言分类器弃用

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

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

从watsonplatform.net更新端点URL

位于watsonplatform.net上的Watson API端点URL将发生变化，并且在2021年5月26日之后将不再可用。更新您的调用以使用新的端点URL。有关更多信息，请参阅https://cloud.ibm.com/docs/watson?topic=watson-endpoint-change。

个性洞察弃用

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。

开始之前

您需要一个IBM Cloud账户。

要求

Xcode 10.2+
Swift 5.0+
iOS 10.0+

安装

IBM Watson Swift SDK可以使用Swift包管理器、Cocoapods或Carthage进行安装。

Swift包管理器

从版本4.0.2开始，Watson开发者云Swift SDK现在通过Swift包管理器支持所有服务。

在屏幕顶部的XCode菜单栏中点击文件 -> Swift Packages -> 添加包依赖项，然后根据提示粘贴github网址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

如果您在执行以上步骤之前导入包或遇到构建错误，可能需要重新索引项目。将WatsonDeveloperCloud包从您的XCode项目文件中的Swift Packages移除；然后，从屏幕顶部的XCode菜单栏点击产品 -> 清理构建文件夹，最后重新安装包。
您已经准备就绪了！

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在新的苹果硅M1 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安装说明在此处进行操作。然后运行以下命令来构建依赖项和框架：

$ carthage.sh bootstrap --platform iOS

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

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

请确保将生成的框架（仅针对您的应用程序需要的服务）拖放到您的应用程序目标下的General -> Frameworks, Libraries, and Embedded Content（XCode <= 10.x: General -> Linked Frameworks and Libraries）中，并在需要它们的源文件中导入它们。您可以在源目录下的./Carthage/Build/iOS中找到.framework文件。
需要添加到您的应用程序中的以下框架：IBMSwiftSDKCore.framework

您的应用程序将会使用的服务（AssistantV1.framework，DiscoveryV1.framework等。）

仅限（语音到文本） Starscream.framework。请确保将其添加到您的input.xcfilelist和output.xcfilelist中（以下将详细说明）。
仅限XCode 12：在Embed列中确保每个框架都设置为Do Not Embed
在您的应用程序目标的“构建阶段”设置选项卡中，单击+图标并选择“New Run Script Phase”。创建一个运行脚本，在其中指定您的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 服务实例，或者点击 创建资源 > 人工智能 创建一个服务实例。
点击您的服务实例左侧导航栏中的管理项。

在这个页面上，您将看到可用于 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对其进行身份验证。与接受载体令牌的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 属性来设置自定义服务网址。在特定区域运行实例或通过代理连接时可能需要自定义服务网址。

例如，以下是如何连接到位于德国的 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()

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

获取事务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 Success。

如何绕过资源文件中的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 Natural Language Classifier V1 4.3.0

IBM Watson Natural Language Classifier V1 4.3.0

IBM Watson Natural Language Classifier V1 4.3.0

Watson Developer Cloud Swift SDK

概述

服务

公告

自然语言分类器弃用

从watsonplatform.net更新端点URL

个性洞察弃用

视觉识别弃用

比较与合规弃用

开始之前

要求

安装

Swift包管理器

CocoaPods

Carthage

身份验证

步骤 1：获取凭证

步骤 2：在代码中身份验证

WatsonIAMAuthenticator（最常用）

WatsonBearerTokenAuthenticator

WatsonCloudPakForDataAuthenticator

从环境变量中检测身份验证

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

自定义服务网址

禁用SSL证书验证

获取事务ID

自定义头

问题

推荐项目

同步执行

在XCode中处理PNG和CgBI文件

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

处理 CgBI 的未来计划

Objective-C 兼容性

Linux 兼容性

贡献力量

许可