Watson Developer Cloud Swift SDK

概述

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

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

• 查看特色项目
• 浏览文档

服务

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

• 助手
• 比较 & 遵守 *已被Discovery取代
• 发现
• 语言翻译V3
• 自然语言分类器
• 自然语言理解
• 个性洞察 *已被自然语言理解取代
• 语音转文本
• 文本转语音
• 语调分析器
• 视觉识别 *已被Maximo视觉检验取代

公告

自然语言分类器弃用

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。有关更多信息，请参阅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+

安装

可以通过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 Packages -> 添加包依赖，按照提示粘贴 GitHub 网址 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. 必须用为多架构编译的库替换已安装的静态库。这些库可以从中下载 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

请在此（在此）遵循Carthage安装的剩余步骤和XCode 12解决方案。然后运行以下命令来构建依赖项和框架

$ carthage.sh bootstrap --platform iOS

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

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

1. 确保将构建的框架（只适用于您的应用需要的部分服务）拖放到应用的“通用 -> 框架、库和嵌入内容”目标下（XCode <= 10.x: “通用 -> 链接框架和库”）。并在需要它们的源文件中导入它们。您可以从源目录下的 ./Carthage/Build/iOS 找到 .framework 文件。

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

   您的应用将要使用的服务（如 AssistantV1.framework、DiscoveryV1.framework 等）

   (仅限“语音转文本”)Starscream.framework。务必将其添加到您的 input.xcfilelist 和 output.xcfilelist 中（以下将详细说明）

3. 仅限XCode 12：在“嵌入”列确保每个框架都设置为“不嵌入”

4. 在您的应用目标的“构建步骤”设置选项卡中，单击加号图标并选择“新运行脚本阶段”。创建一个运行脚本，在下面脚本区域中指定您的shell（例如：/bin/sh），添加以下内容

   /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运行脚本阶段”的“输入文件列表”部分。这通常为 $(SRCROOT)/input.xcfilelist

9. 将 output.xcfilelist 的路径添加到“Carthage运行脚本阶段”的“输出文件列表”部分。这通常为 $(SRCROOT)/output.xcfilelist

如果您的应用因为构建与下载SDK不同的Swift版本而无法构建，请在添加 标志后重新运行 carthage.sh bootstrap 命令。

身份验证

为了在Swift应用程序中使用IBM Watson服务，您需要进行身份验证。以下介绍了您通常需要执行的步骤。

步骤 1：获取凭据

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

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

1. 访问IBM Cloud 仪表板页面。
2. 在您的资源列表中单击现有的Watson服务实例，或者单击创建资源 > 人工智能创建服务实例。
3. 点击服务实例左侧导航栏中的管理项。

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

步骤 2：在代码中验证

Watson Swift SDK使用Authenticator类来管理身份验证。根据您选择的验证方法，有各种类型的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代码中的认证器。

自定义服务URLs

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

注意：目前在 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的酷炫开源项目！如果您希望将您的项目添加到列表中，请随时创建一个链接到它的issue。

• 简单聊天（Swift）
• 语音转文本
• 文本转语音

同步执行

默认情况下，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文件，并在文件检查器中将