Watson Developer Cloud Swift SDK

概述

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

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

查看特色项目
浏览文档

服务

此 SDK 为使用以下 Watson 服务提供类和方法。

助手
比较 & 合规 *已弃用，改为 Discovery
发现
语言翻译 V3
自然语言分类器
自然语言理解
个性洞察 *已弃用，改为自然语言理解
语音转文本
文本转语音
语调分析器
视觉识别 *已弃用，改为 Maximo Visual Inspection

公告

自然语言分类器弃用

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™ Natural Language Understanding，这是一个IBM Cloud®服务，使用深度学习从文本中提取数据和分析，例如关键词、类别、情感、情绪和语法，以为您的业务或行业提供洞察。更多信息，请参阅《关于自然语言理解》。

视觉识别弃用

IBM Watson™ 视觉识别服务已弃用。现有实例将支持到2021年12月1日，但从2021年1月7日开始，无法创建新的实例。2021年12月1日创建的任何实例将被删除。

Compare and Comply 弃用

IBM Watson™ Compare and Comply 服务已弃用。现有实例将支持到2021年11月30日，但从2020年12月1日开始，无法创建新的实例。2021年11月30日存在的任何实例将被删除。请考虑将 Compare and Comply 用例迁移至 IBM Cloud 上的 Watson Discovery Premium。要开始迁移过程，请访问 https://ibm.biz/contact-wdc-premium。

准备工作

您需要 IBM Cloud 账户。

要求

Xcode 10.2+
Swift 5.0+
iOS 10.0+

安装

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

Swift包管理器

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

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

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

CocoaPods

您可以使用 RubyGems 安装CocoaPods

$ sudo gem install cocoapods

如果您的项目还没有Podfile，在项目的根目录中使用pod init命令。要将Swift SDK通过CocoaPods安装，将您将使用的服务添加到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

请按照以下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找到框架文件。
需要将以下框架添加到您的应用程序中：IBMSwiftSDKCore.framework

您应用程序将需要使用的服务（例如：AssistantV1.framework，DiscoveryV1.framework等）

（仅限Speech to Text） Starscream.framework。请确保将此框架添加到您的input.xcfilelist和output.xcfilelist中，下面会详细说明
仅针对XCode 12：在Embed列中，确保每个框架都设置为Do Not Embed
在您的应用程序目标的Build Phases设置标签页中，点击+图标并选择New Run Script Phase。创建一个Run Script，在下面的shell区域指定您的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服务实例。

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

转到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云上，这可以通过使用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云，则可以使用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云上服务实例的管理标签，并单击下载凭证的按钮。文件将命名为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的部分。

自定义服务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()

注意：当前不支持在 Linux 上使用 disableSSLVerification()。

获取事务标识符

在调试 IBM 支持的问题时，您可能需要提供 事务标识符 (transaction ID) 以帮助 IBM 识别需要调试的 API 调用。

每个 SDK 调用都会返回一个响应，其中包含在 X-Global-Transaction-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 由于某种原因没有返回响应，则无法获取事务标识符。在这种情况下，您可以在请求中设置自己的事务标识符。例如，在下例中将 <my-unique-transaction-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项目时，您可能需要将PNG图像添加到XCode的资源包中。默认情况下，XCode将PNG文件转换为Apple的CgBI文件格式作为优化步骤。

接受PNG图像作为输入文件的Watson服务（视觉识别、比较和遵守）无法处理CgBI文件。在某些情况下，传递已经是CgBI编码的PNG将导致HTTP错误，在其他情况下（视觉识别）将返回200成功但没有结果。

如何绕过资源文件的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 Package Manager指南操作。请注意，由于它们依赖于Linux上不可用的框架，语音到文本和文本到语音功能不受支持。

贡献

我们欢迎任何形式的帮助！如果您想贡献力量，请阅读有关开始贡献的CONTRIBUTING文档。

许可协议

本库遵循Apache 2.0许可协议。完整的许可文本在LICENSE文件中提供。

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

IBM Watson Visual Recognition V3 4.3.0

IBM Watson Visual Recognition V3 4.3.0

IBM Watson Visual Recognition V3 4.3.0

Watson Developer Cloud Swift SDK

概述

服务

公告

自然语言分类器弃用

从watsonplatform.net更新端点URL

个性洞察弃用

视觉识别弃用

Compare and Comply 弃用

准备工作

要求

安装

Swift包管理器

CocoaPods

Carthage

认证

第1步：获取凭证

第2步：在代码中认证

WatsonIAMAuthenticator（最常见）

WatsonBearerTokenAuthenticator

WatsonCloudPakForDataAuthenticator

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

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

自定义服务URL

禁用 SSL 证书验证

获取事务标识符

自定义头部

问题

特色项目

同步执行

在XCode中处理PNG和CgBI文件

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

处理CGBI的未来计划

Objective-C兼容性

Linux兼容性

贡献

许可协议