Watson Developer Cloud Swift SDK

已停用构建

概述

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

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

查看特色项目
浏览文档

服务

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

公告

语调分析器弃用

从这次重要版本5.0.0开始，为了准备弃用，已经删除了语调分析API。如果您希望继续使用此SDK调用语调分析器直到其最终弃用，您需要使用之前的版本。

IBM于2022年2月24日宣布弃用语调分析器服务。该服务将从2023年2月24日起不再提供。从2022年2月24日起，您将无法创建新实例。现有实例将得到支持，直到2023年2月24日。

作为替代方案，我们鼓励您考虑迁移到IBM云上的自然语言理解服务。使用自然语言理解服务，通过预建的分类模型进行语调分析，这是一种轻松检测书面文本中语言语调的方法。有关更多信息，请参阅从沃森语调分析器客户互动端点迁移到自然语言理解。

自然语言分类器弃用

从这次重要版本5.0.0开始，为了准备弃用，已经删除了NLC API。如果您希望继续使用此SDK调用NLC直到其最终弃用，您需要使用之前的版本。

IBM于2021年8月9日宣布弃用自然语言分类器服务。该服务将从2022年8月8日起不再提供。从2021年9月9日起，您将无法创建新实例。现有实例将得到支持，直到2022年8月8日。任何到那天仍在使用的实例都将被删除。

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

开始之前

您需要一个IBM Cloud账户。

要求

Xcode 10.2+
Swift 5.0+
iOS 10.0+

安装

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

Swift 包管理器

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

在屏幕顶部的 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菜单栏点击产品 -> 清理构建文件夹，最后重新安装包。
一切准备就绪！

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芯片的发布导致了对于XCode 11+的Carthage工具的问题。在可预见的未来，我们无法通过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

按照Carthage在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 类管理身份验证。根据您选择的方法，有多种类型的 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的认证器代码。

自定义服务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主机名验证时可能需要禁用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的酷炫开源项目！如果您希望将您的项目添加到列表中，请自由联系我们将链接发给我们。

同步执行

默认情况下，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上不可用的框架。

贡献

我们欢迎任何形式的帮助！如果您想贡献，请阅读我们的CONTRIBUTING文档，以获取有关如何开始的更多信息。

许可

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

此SDK专为与Apple iOS产品一起使用而设计，并旨在与官方许可的Apple开发工具结合使用。

IBM Watson Assistant V1 5.0.0

IBM Watson Assistant V1 5.0.0

IBM Watson Assistant V1 5.0.0

Watson Developer Cloud Swift SDK

已停用构建

概述

服务

公告

语调分析器弃用

自然语言分类器弃用

开始之前

要求

安装

Swift 包管理器

Cocoapods

Carthage

身份验证

步骤1：获取凭证

步骤 2：在代码中验证

WatsonIAMAuthenticator（最常用）

WatsonBearerTokenAuthenticator

WatsonCloudPakForDataAuthenticator

从环境变量中检测认证

关于认证方法的更多信息

自定义服务URL

禁用SSL证书验证

获取交易ID

自定义头部

问题

特色项目

同步执行

在 XCode 中处理 PNG 和 CgBI 文件

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

处理 CgBI 的未来计划

Objective-C 兼容性

Linux兼容性

贡献

许可