Watson Developer Cloud Swift SDK

已过时构建

概述

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

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

查看特色项目
浏览文档

服务

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

公告

语调分析器弃用

自5.0.0版本（本重大发布）起，为了准备弃用，已经删除了语调分析api。如果您希望继续使用此sdk调用语调分析器直到其最终弃用，您必须使用之前的版本。

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

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

自然语言分类器弃用

自5.0.0版本（本重大发布）起，为了准备弃用，已经删除了NLC api。如果您希望继续使用此sdk调用NLC直到其最终弃用，您必须使用之前的版本。

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

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

开始之前

您需要一个 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 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

如果在执行上述步骤之前遇到任何构建错误或之前已导入包，则可能需要重新索引项目。将 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', '~> 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 芯片的发布导致了 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" ~> 5.0.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），并添加以下内容到 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 Cloud 获取用于使用 IBM Watson 服务的凭证。在您的 Swift 应用中进行身份验证之前，您需要有一个有效的账户以及您想要使用的服务的服务实例。

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

访问 IBM Cloud 的仪表板页面。
要么单击您的资源列表中的现有 Watson 服务实例，要么单击 创建资源 > AI 创建一个服务实例。
在您的服务实例左导航条中点击管理项。

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

第2步：在代码中认证

Watson Swift SDK 使用 Authenticator 类来管理认证。根据您选择的方法，有多种类型的 Authenticator。

WatsonIAMAuthenticator（最常用）

WatsonIAMAuthenticator 允许您使用 IAM API 密钥进行认证。这是在 IBM Cloud 中最常用的认证方式。初始化方法中需要提供一个 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 clouds上服务实例的管理标签，然后单击下载凭据的按钮。该文件将被命名为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()

注意：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文件转换为苹果的 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 开发工具一起使用。

IBMWatsonLanguageTranslatorV3 5.0.0

IBMWatsonLanguageTranslatorV3 5.0.0

IBMWatsonLanguageTranslatorV3 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 兼容性

贡献

许可协议