IBMWatsonSpeechToTextV1 5.0.0

IBMWatsonSpeechToTextV1 5.0.0

×

由watdevex，Jeff Arn维护。

 
依赖关系
IBMSwiftSDKCore~> 1.2.1
Starscream~> 4.0.0
 

IBMWatsonSpeechToTextV1 5.0.0

  • 由
  • Jeff Arn 和 Angelo Paparazzi

Watson 开发者云 Swift SDK

Build and Test Deploy and Publish Carthage Compatible Documentation CLA assistant wdc-community.slack.com

已弃用构建

Build Status

概览

Watson 开发者云 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 Cloud上的自然语言理解服务。借助自然语言理解，情感分析通过预构建的模型进行，提供检测书面文本中语言情感的便捷方式。更多信息，请参阅从Watson情感分析器客户参与端点迁移到自然语言理解。

自然语言分类器弃用

从此次重大版本发行，5.0.0版开始，NLC API已被移除，准备弃用。如果您希望继续使用此SDK调用NLC直到其最终弃用，您将必须使用旧版本。

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

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

开始之前

要求

  • Xcode 10.2+
  • Swift 5.0+
  • iOS 10.0+

安装

IBM Watson Swift SDK可以通过Swift Package Manager、Cocoapods或Carthage安装。

Swift Package Manager

从版本4.0.2开始，Watson Developer Cloud Swift SDK现在支持通过Swift Package Manager使用所有服务。

在屏幕顶部的XCode菜单栏上，点击文件 -> Swift Packages -> 添加包依赖项，通过粘贴github url https://github.com/watson-developer-cloud/swift-sdk并使用最近的较新版本（如果适用）来遵循提示。请确保只选择您计划使用的服务，否则可能会导致构建时间过长

要将服务导入到您的项目中

import AssistantV2
import DiscoveryV2
.
.
.

（仅限语音听写和语音转文本）这些服务使用libogg和opus库需要执行额外的步骤，在安装包之前。

  1. 您需要安装Homebrew

  2. 安装libogg和opus

    $ brew install libogg opus

  3. 必须根据当前库版本删除打包的动态库。

    截至写作时，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

  4. 安装的静态库必须替换为为多架构编译的库。这些库可以从本github库下载这里 libogg和这里 opus

  5. 替换已安装的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

  6. 如果您在执行以上步骤之前遇到了构建错误或导入了包，则可能需要重新索引项目。请从XCode项目的Swift Packages中移除WatsonDeveloperCloud包；然后，在屏幕顶部的XCode菜单栏中点击Product -> Clean Build Folder，最后重新安装该包。

  7. 您已准备就绪！

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在新苹果Silicon 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项目

  1. 请确保将构建好的框架（仅限您应用需要的框架）拖放到应用目标下的通用 -> 框架、库和嵌入式内容（XCode <= 10.x：通用 -> 链接框架和库）并导入它们到需要它们的源文件中。您将在源目录下的./Carthage/Build/iOS找到.framework文件。

  2. 需要添加到您的应用的框架如下：IBMSwiftSDKCore.framework

    您的应用将使用的任何服务（AssistantV1.framework、DiscoveryV1.framework等）

    （仅针对“语音识别到文本”）Starscream.framework。请确保将其添加到下面的input.xcfilelist和output.xcfilelist中（将在以下内容中详细介绍）

  3. 仅XCode 12：在嵌入列中，确保每个框架都设置为不嵌入

  4. 在您的应用目标“构建阶段”设置选项卡中，单击加号图标并选择“新运行脚本阶段”。创建一个运行脚本，在其中指定您的shell（例如：/bin/sh），在shell下面的脚本区域添加以下内容：

    /usr/local/bin/carthage copy-frameworks

  5. 创建一个名为input.xcfilelist的文件和一个名为output.xcfilelist的文件

  6. 将您要使用的框架的路径添加到您的input.xcfilelist中。例如：

    $(SRCROOT)/Carthage/Build/iOS/IBMSwiftSDKCore.framework
$(SRCROOT)/Carthage/Build/iOS/DiscoveryV1.framework

  7. 将复制的框架的路径添加到output.xcfilelist中。例如：

    $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/IBMSwiftSDKCore.framework
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/DiscoveryV1.framework

    在指定了输入和输出文件之后，XCode仅需要在输入文件已更改或输出文件缺失时运行脚本。这意味着在没有用Carthage重新构建框架时，带有脏构建的构建速度会更快。

  8. 将input.xcfilelist的路径添加到Carthage运行脚本阶段“输入文件列表”部分。这通常将是$(SRCROOT)/input.xcfilelist

  9. 将output.xcfilelist的路径添加到Carthage运行脚本阶段“输出文件列表”部分。这通常将是$(SRCROOT)/output.xcfilelist

如果您的应用由于使用了与下载的SDK不同的Swift版本而无法构建，则请添加--no-use-binaries标志重新运行carthage.sh bootstrap命令。

身份验证

为了在Swift应用中使用IBM Watson服务，您需要启用身份验证。以下描述了完成此操作的典型步骤。

步骤1：获取凭据

要使用IBM Watson服务，您需要通过IBM Cloud获取凭据。在您的Swift应用中进行身份验证之前，您需要一个活动账户以及要使用的服务实例。

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

  1. 转到IBM Cloud 仪表板页面。
  2. 要么在您的资源列表中单击现有的Watson服务实例，要么单击创建资源 > AI并创建服务实例。
  3. 在您的服务实例左侧导航栏中点击 管理 项目。

在此页面上，您将看到用于在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

您可能需要提供一个Bear令牌来对服务进行身份验证。在 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 集群进行身份验证。与接受 Bear 令牌的 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的酷炫开源项目！如果您想将您的项目添加到列表中，请随意提出一个与该链接相关的问题。

同步执行

默认情况下，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文件，并在文件检查器中修改类型属性为数据。

示例
File inspector example

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