Watson 开发者云 Swift SDK

已弃用构建

概述

Watson 开发者云 Swift SDK 可让移动开发者轻松构建 Watson 增强的应用程序。使用 Swift SDK，您可以利用 Watson 高级人工智能、机器学习、深度学习技术的力量来理解非结构化数据，以前所未有的方式与移动用户互动。

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

查看特色项目
浏览文档

服务

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

公告

声调分析弃用

自本重要版本5.0.0起，为弃用做准备，已删除Tone Analyzer API。如果您希望在弃用之前继续使用此sdk调用Tone Analyzer，您必须使用先前版本。

2022年2月24日，IBM宣布弃用Tone Analyzer服务。该服务将从2023年2月24日起不再可用。截至2022年2月24日，无法创建新实例。现有实例将得到支持，直至2023年2月24日。

作为替代，我们鼓励您考虑迁移到IBM Cloud上的自然语言理解服务。使用自然语言理解，通过预构建的分类模型进行声调分析，为检测书面文本语言声调提供一个简单的方法。更多信息，请参阅从Watson Tone Analyzer服务端点迁移到自然语言理解。

自然语言分类器弃用

自本重要版本5.0.0起，为弃用做准备，已删除NLC API。如果您希望在弃用之前继续使用此sdk调用NLC，您必须使用先前版本。

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

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

在开始之前

您需要一个 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 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 repo 下载：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菜单栏上点击Product -> Clean Build Folder，最后重新安装该包。
您已准备就绪！

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.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等）

（仅语音转文本）Starscream.framework。请确保将此框架添加到下面的 input.xcfilelist 和 output.xcfilelist 中
仅适用于XCode 12：在 Embed 列中，确保每个框架设置为 Do Not Embed
在您的应用程序目标的“构建阶段”设置标签页中，点击加号图标并选择“New Run Script Phase”。创建一个运行脚本来指定您的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

如果您的应用由于构建了不同版本的Swift而失败，则在带有 --no-use-binaries 标志的情况下重新运行 carthage.sh bootstrap 命令。

认证

为了在Swift应用中使用IBM Watson服务，您需要进行认证。以下描述了您通常需要采取的认证步骤。

步骤1：获取凭证

使用IBM Watson服务的凭证是通过IBM Cloud获得的。在Swift应用程序中进行认证之前，您需要一个 действующий аккаунт иinstance of the service you wish to use on IBM Cloud。

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

转到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 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代码中的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的酷炫开源项目！如果您想要将项目添加到列表中，请随时创建一个链接到该项目的issue。

同步执行

默认情况下，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文件格式，作为一个优化步骤。

如何跳过资源文件的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上不可用的框架，因此不支持语音到文本和文本到语音。

贡献

我们期待您的任何帮助！如果您想贡献，请阅读我们的贡献文档，了解如何开始。

许可证

本库采用Apache 2.0许可证。完整许可证文本可在LICENSE中查看。

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

IBM Watson Text To Speech V1 5.0.0

IBM Watson Text To Speech V1 5.0.0

IBM Watson Text To Speech V1 5.0.0

Watson 开发者云 Swift SDK

已弃用构建

概述

服务

公告

声调分析弃用

自然语言分类器弃用

在开始之前

需求

安装

Swift 包管理器

Cocoapods

Carthage

认证

步骤1：获取凭证

步骤 2：代码认证

WatsonIAMAuthenticator（最常见）

WatsonBearerTokenAuthenticator

WatsonCloudPakForDataAuthenticator

从环境变量检测认证

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

自定义服务URL

禁用SSL证书验证

获取交易ID

自定义头信息

问题提出

特色项目

同步执行

在XCode中处理PNG和CgBI文件

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

处理CgBI的未来计划

Objective-C兼容性

Linux兼容性

贡献

许可证