Watson Developer Cloud Swift SDK

概述

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

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

查阅一个特色项目
浏览文档

服务

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

助手
比较与合规 *已弃用，改用 Discovery
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™自然语言理解（Natural Language Understanding），这是一个在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 Package Manager、Cocoapods或Carthage进行安装。

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 命令。要使用 Cocoapods 安装 Swift SDK，将以下示例（将 MyApp 替换为您的应用名称）中的服务添加到您的 Podfile 中。以下示例显示所有当前可用的服务；您的 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项目

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

您的应用程序将使用哪些服务（如AssistantV1.framework、DiscoveryV1.framework等。）

（仅限语音转文本）Starscream.framework。请确保将其添加到您的input.xcfilelist和output.xcfilelist中，以下将详细说明
仅在Xcode 12中：在“嵌入”列中，确保每个框架都被设置为“不要嵌入”
在应用程序目标的构建阶段设置选项卡中，单击+图标并选择“新运行脚本阶段”。创建一个运行脚本，在其中指定您的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访问服务实例的凭据。

步骤 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的认证器代码。

自定义服务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调用的响应都包含一个事务ID，位于X-Global-Transaction-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时遇到问题或者对IBM 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文件格式作为优化步骤。

接受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开发工具一起使用。

IBMWatsonVisualRecognitionV4 4.3.0

IBMWatsonVisualRecognitionV4 4.3.0

IBMWatsonVisualRecognitionV4 4.3.0

Watson Developer Cloud Swift SDK

概述

服务

公告

自然语言分类器弃用

从 watsonplatform.net 更新端点URL

个性洞察弃用

视觉识别弃用

比较与遵守弃用

开始之前

要求

安装

Swift 包管理器

Cocoapods

Carthage

身份验证

步骤 1：获取凭据

步骤 2：在代码中认证

WatsonIAMAuthenticator（最常用）

WatsonBearerTokenAuthenticator

WatsonCloudPakForDataAuthenticator

从环境变量检测认证

有关认证方法的更多信息

自定义服务URL

禁用SSL证书验证

获取事务ID

自定义标题

问题

精选项目

同步执行

处理XCode中的PNG和CgBI文件

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

处理CgBI的未来计划

Objective-C兼容性

Linux兼容性

贡献

许可