IBM Watson SDK for Unity

停用通知

本仓库及其相关发布的二进制文件已被弃用。虽然IBM团队将不再对此仓库提供主动支持，但我们仍然欢迎社区通过PR提交贡献，并会对这些贡献进行评审。请注意，后续更新将不再发布到正式的二进制版本中，因此在此更新之后所做的更改需要由用户自行编译。

使用此SDK在Unity中构建基于Watson的应用程序。

公告

音调分析器弃用

自本次主要版本6.0.0起，音调分析器API已被移除，以准备正式弃用。如果您希望继续使用此SDK调用音调分析器服务直至其最终停用，您需要使用之前的版本。

2022年2月24日，IBM宣布音调分析器服务将被弃用。该服务将于2023年2月24日起停止提供。自2022年2月24日起，您将无法再创建新的实例。现有实例将继续得到支持，直到2023年2月24日为止。

作为替代方案，我们建议您考虑迁移到IBM Cloud上的自然语言理解服务。通过自然语言理解服务，您可以使用预构建的分类模型来进行语调分析，从而轻松检测书面文本中的语言语调。更多信息请参阅从Watson音调分析器客户互动端点迁移到自然语言理解。

自然语言分类器弃用

自本次主要版本6.0.0起，NLC API已被移除，以准备正式弃用。如果您希望继续使用此SDK调用NLC服务直至其最终停用，您需要使用之前的版本。

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

作为替代方案，我们鼓励您考虑迁移到IBM Cloud上的自然语言理解服务。该服务利用深度学习技术，可以从文本中提取关键词、类别、情感、情绪和语法等数据及洞察，并具备先进的多标签文本分类功能，从而为您的业务或行业提供更丰富的见解。更多信息请参阅迁移到自然语言理解。

更新watsonplatform.net的API端点URL

watsonplatform.net上的Watson API端点URL正在发生变化，自2021年5月26日起将不再有效。请更新您的调用以使用新的端点URL。更多信息请参阅https://cloud.ibm.com/docs/watson?topic=watson-endpoint-change。

开始之前

请确保您已满足以下先决条件：

• 您需要一个IBM Cloud账户。
• Unity。您可以使用免费的Personal版本。

配置Unity

• 在Unity中更改构建设置（“文件 > 构建设置”），选择除Web Player/WebGL之外的任何平台。IBM Watson SDK for Unity不支持Unity Web Player。
• 如果您使用的是Unity 2018.2或更高版本，则需要在构建设置中将“脚本运行时版本”和“API兼容性级别”设置为“.NET 4.x等效”。我们需要访问安全选项来启用TLS 1.2。

将MacOS升级到Mojave可能会导致Unity无法使用麦克风。如果您遇到此问题，请参阅这些指南，以配置Mojave下的麦克风。

获取Watson SDK并将其添加到Unity

您可以通过点击这里获取最新版本的SDK。同时，您还需要点击这里下载最新的IBM Unity SDK Core版本。

将SDK源代码安装到您的Unity项目中

将**unity-sdk和unity-sdk-core目录移动到您的Unity项目的Assets**目录下。可选：将SDK目录重命名为Watson，将Core目录重命名为IBMSdkCore。

配置您的服务凭据

要创建Watson服务实例及其凭据，请按照以下步骤操作。

注意： 服务凭据不同于您的IBM Cloud账户用户名和密码。

1. 确定需要配置哪些服务。
2. 如果您已经配置过这些服务，请完成以下步骤。否则，请跳至第3步。
   1. 登录到IBM Cloud网站：https://cloud.ibm.com。
   2. 单击您想要使用的服务。
   3. 单击“服务凭据”。
   4. 单击“查看凭据”以访问您的凭据。
3. 如果您需要配置想要使用的服务，请完成以下步骤。
   1. 登录到IBM Cloud网站：https://cloud.ibm.com。
   2. 单击“创建服务”按钮。
   3. 在“Watson”类别下，选择您想要创建实例的服务并单击该服务。
   4. 为服务和凭据命名，选择计划，然后单击底部的“创建”按钮。
   5. 单击“服务凭据”。
   6. 单击“查看凭据”以访问您的凭据。
4. 您的服务凭据可用于在应用程序中实例化Watson服务。大多数服务还支持令牌，您也可以使用令牌来实例化服务。

每个服务的凭据包含“用户名”、“密码”和端点“URL”，或者“API密钥”和端点“URL”。

警告： 您有责任妥善保管自己的凭据。任何拥有您服务凭据的人都可以访问您的服务实例！

Watson 服务

要在 Unity 中开始使用 Watson 服务，请按照链接查看代码。

• Assistant V1
• Assistant V2
• Compare Comply V1
• Conversation（已弃用 - 请使用 Assistant V1 或 Assistant V2）
• Discovery
• Language Translator V3
• Natural Language Classifier
• Natural Language Understanding
• Personality Insights
• Speech to Text
• Text to Speech
• Tone Analyzer
• Visual Recognition

身份验证

Watson 服务正在迁移到基于令牌的身份和访问管理 (IAM) 身份验证。

• 对于某些服务实例，您可以通过 IAM 对 API 进行身份验证。
• 在其他实例中，您需要提供该服务实例的 用户名和密码 来进行身份验证。

获取凭据

要确定使用哪种身份验证方式，请查看服务凭据。对于所有 Watson 服务，获取用于身份验证的服务凭据的方式相同：

1. 前往 IBM Cloud 的 仪表板 页面。
2. 单击现有的 Watson 服务实例，或单击 创建。
3. 单击 显示 查看您的服务凭据。
4. 复制 url 以及 apikey 或 username 和 password。

在您的代码中，您可以将这些值用于服务构造函数，或者在实例化服务后通过方法调用来使用它们。

IAM

部分服务使用基于令牌的身份和访问管理 (IAM) 身份验证。IAM 身份验证使用服务 API 密钥获取访问令牌，并在每次调用时传递该令牌。访问令牌的有效期约为一小时，必须重新生成。

您可以提供 IAM 服务的 API 密钥 或 访问令牌：

• 使用 API 密钥时，SDK 将管理访问令牌的生命周期。SDK 会请求访问令牌、确保其有效，并在必要时刷新它。
• 如果您希望自行管理访问令牌的生命周期，则可以使用访问令牌。有关详细信息，请参阅 使用 IAM 令牌进行身份验证。如果您想切换到 API 密钥，可以在协程中用 IAM API 密钥覆盖存储的 IAM 凭据，并等待直到凭据对象 HasIamTokenData() 返回 true。

提供 IAM API 密钥

Authenticator authenticator;
AssistantService assistant;
string versionDate = "<service-version-date>";

IEnumerator TokenExample()
{
    // 使用 IAM 令牌选项创建身份验证器
    authenticator = new IamAuthenticator(apikey: "<iam-api-key>");
    while (!authenticator.CanAuthenticate())
        yield return null;

    assistant = new AssistantService(versionDate, authenticator);
    assistant.SetServiceUrl("<service-url>");
    assistant.ListWorkspaces(callback: OnListWorkspaces);
}

private void OnListWorkspaces(DetailedResponse<WorkspaceCollection> response, IBMError error)
{
    Log.Debug("OnListWorkspaces()", "响应：{0}", response.Response);
}

提供访问令牌

Authenticator authenticator;
AssistantService assistant;
string versionDate = "<service-version-date>";

void TokenExample()
{
    // 使用 Bearer 令牌创建身份验证器
    authenticator = new BearerTokenAuthenticator("<bearer-token>");

    assistant = new AssistantService(versionDate, authenticator);
    assistant.SetServiceUrl("<service-url>");
    assistant.ListWorkspaces(callback: OnListWorkspaces);
}

private void OnListWorkspaces(DetailedResponse<WorkspaceCollection> response, IBMError error)
{
    Log.Debug("OnListWorkspaces()", "响应：{0}", response.Response);
}

用户名和密码

Authenticator authenticator;
AssistantService assistant;
string versionDate = "<service-version-date>";

void UsernamePasswordExample()
{
    Authenticator authenticator = new BasicAuthenticator("<username>", "<password>", "<url>");
    assistant = new AssistantService(versionDate, authenticator);
    assistant.SetServiceUrl("<service-url>");
}

提供身份验证器

有两种方法可以将上述找到的身份验证器提供给 SDK 以进行身份验证。

凭据文件（更简单！）

使用凭据文件时，您只需将文件放置在正确的位置，SDK 就会自动解析并完成身份验证。您可以通过在服务实例的 管理 选项卡中点击凭据的 下载 按钮来获取此文件。

下载的文件名为 ibm-credentials.env。这是 SDK 会查找的文件名，必须 保留此名称，除非您想配置文件路径（稍后会详细介绍）。SDK 会在以下位置按顺序查找您的 ibm-credentials.env 文件：

• 您系统的主目录
• 您正在使用 SDK 的项目的顶级目录

只要正确设置了这些位置，您就不需要在代码中设置任何身份验证选项。例如，如果您为 Discovery 实例创建并下载了凭据文件，只需执行以下操作：

public IEnumerator ExampleAutoService()
{
    Assistant assistantService = new Assistant("2019-04-03");

    // 等待授权令牌
    while (!assistantService.Authenticator.CanAuthenticate())
        yield return null;

    var listWorkspacesResult = assistantService.ListWorkspaces();
}

就这么简单！

如果您在代码中同时使用多个服务，并获得了两个不同的 ibm-credentials.env 文件，只需将内容合并到一个 ibm-credentials.env 文件中，SDK 就会自动为相应的服务分配身份验证器。

如果您想配置凭据文件的位置或名称，可以设置名为 IBM_CREDENTIALS_FILE 的环境变量。这将优先于上述指定的位置。 设置方法如下：

export IBM_CREDENTIALS_FILE="<path>"

其中 <path> 类似于 /home/user/Downloads/<file_name>.env。

手动方式

如果您更倾向于在代码中手动设置身份验证值，SDK 同样支持这种方式。具体操作方式取决于您的服务实例提供的身份验证器类型。

回调函数

必须提供成功回调。您可以在回调中指定返回类型。

AssistantService assistant;
string assistantVersionDate = "<assistant-version-date>";
Authenticator assistantAuthenticator;
string workspaceId = "<workspaceId>";

DiscoveryService discovery;
string discoveryVersionDate = "<discovery-version-date>";
Authenticator discoveryAuthenticator;

private void Example()
{
    assistant = new AssistantService(assistantVersionDate, assistantAuthenticator);
    assistant.SetServiceUrl("<service-url>");

    discovery = new DiscoveryService(discoveryVersionDate, discoveryAuthenticator);
    discovery.SetServiceUrl("<service-url>");

    // 使用特定的回调进行调用
    assistant.Message(
        callback: OnMessage,
        workspaceId: workspaceId
    );

    discovery.ListEnvironments(
        callback: OnGetEnvironments
    );
}

private void OnMessage(DetailedResponse<MessageResponse> response, IBMError error)
{
    Log.Debug("ExampleCallback.OnMessage()", "收到响应：{0}", response.Response);
}

private void OnGetEnvironments(DetailedResponse<ListEnvironmentsResponse> response, IBMError error)
{
    Log.Debug("ExampleCallback.OnGetEnvironments()", "收到响应：{0}", response.Response);
}

由于成功回调的签名是泛型的，而失败回调的签名始终相同，因此可以使用一组回调来处理多个调用。

AssistantService assistant;
string assistantVersionDate = "<assistant-version-date>";
Authenticator assistantAuthenticator;
string workspaceId = "<workspaceId>";

DiscoveryService discovery;
string discoveryVersionDate = "<discovery-version-date>";
Authenticator discoveryAuthenticator;

private void Example()
{
    assistant = new AssistantService(assistantVersionDate, assistantAuthenticator);
    assistant.SetServiceUrl("<service-url>");

    // 使用通用回调进行调用
    JObject input = new JObject();
    input.Add("text", "");
    assistant.Message(
        callback: OnSuccess,
        workspaceId: workspaceId,
        input: input
    );

    discovery = new DiscoveryService(discoveryVersionDate, discoveryAuthenticator);
    discovery.SetServiceUrl("<service-url>");

    discovery.ListEnvironments(
        callback: OnSuccess
    );
}

// 通用的成功回调
private void OnSuccess<T>(DetailedResponse<T> resp, IBMError error)
{
    Log.Debug("ExampleCallback.OnSuccess()", "收到响应：{0}", resp.Response);
}

您还可以使用匿名回调：

AssistantService assistant;
string assistantVersionDate = "<assistant-version-date>";
Authenticator assistantAuthenticator;
string workspaceId = "<workspaceId>";

private void Example()
{
    assistant = new AssistantService(assistantVersionDate, assistantAuthenticator);

    assistant.ListWorkspaces(
        callback: (DetailedResponse<WorkspaceCollection> response, IBMError error) =>
        {
            Log.Debug("ExampleCallback.OnSuccess()", "ListWorkspaces 的结果：{0}", response.Response);
        },
        pageLimit: 1,
        includeCount: true,
        sort: "-name",
        includeAudit: true
    );
    assistant.SetServiceUrl("<service-url>");
}

您可以通过检查 error 响应来确定调用是否出现错误。

AssistantService assistant;
string assistantVersionDate = "<assistant-version-date>";
Authenticator assistantAuthenticator;
string workspaceId = "<workspaceId>";

private void Example()
{
    assistant = new AssistantService(versionDate, authenticator);

    assistant.Message(OnMessage, workspaceId);
}

private void OnMessage(DetailedResponse<MessageResponse> response, IBMError error)
{
    if (error == null)
    {
        Log.Debug("ExampleCallback.OnMessage()", "收到响应：{0}", response.Response);
    }
    else
    {
        Log.Debug("ExampleCallback.OnMessage()", "收到错误：{0}, {1}, {3}", error.StatusCode, error.ErrorMessage, error.Response);
    }
}

自定义请求头

您可以通过将自定义请求头添加到服务中来发送它们。

AssistantService assistant;
string assistantVersionDate = "<assistant-version-date>";
Authenticator assistantAuthenticator;
string workspaceId = "<workspaceId>";

void Example()
{
    assistant = new AssistantService(assistantVersionDate, assistantAuthenticator);

    // 向 REST 调用添加自定义头
    assistant.WithHeader("X-Watson-Metadata", "customer_id=some-assistant-customer-id");
    assistant.Message(OnSuccess, "<workspace-id>");
}

private void OnSuccess(DetailedResponse<MessageResponse> response, IBMError error)
{
    Log.Debug("ExampleCallback.OnMessage()", "收到响应：{0}", response.Response);
}

响应头

您可以在 DetailedResponse 中的 headers 对象中获取响应头。

AssistantService assistant;
string assistantVersionDate = "<assistant-version-date>";
Authenticator assistantAuthenticator;
string workspaceId = "<workspaceId>";

void Example()
{
    assistant = new AssistantService(assistantVersionDate, assistantAuthenticator);

    assistant.Message(OnMessage, "<workspace-id>");
}

private void OnMessage(DetailedResponse<MessageResponse> response, IBMError error)
{
    // 列出响应头对象中的所有头
    foreach (KeyValuePair<string, object> kvp in response.Headers)
    {
        Log.Debug("ExampleCustomHeader.OnMessage()", "{0}: {1}", kvp.Key, kvp.Value);
    }
}

事务ID

每个 SDK 调用都会返回一个响应，其中 X-Global-Transaction-Id 头部包含事务 ID。结合服务实例所在的区域，此 ID 可帮助支持团队从相关日志中排查问题。

public void ExampleGetTransactionId()
{
    AssistantService service = new AssistantService("{version-date}");
    service.ListWorkspaces(
        callback: (DetailedResponse<Workspace> response, IBMError error) =>
        {
            if(error != null)
            {
                Log.Debug("AssistantServiceV1", "事务 ID: {0}", error.ResponseHeaders["X-Global-Transaction-Id"]);
            }
            else
            {
                Log.Debug("AssistantServiceV1", "事务 ID: {0}", response.Headers["X-Global-Transaction-Id"]);
            }
        }
    );
}

然而，如果 API 因某种原因未返回响应，则事务 ID 将不可用。在这种情况下，您可以在请求中设置自己的事务 ID。例如，在下面的示例中，将 <my-unique-transaction-id> 替换为唯一的事务 ID。

public void ExampleSetTransactionId()
{
    AssistantService service = new AssistantService("{version-date}");
    service.WithHeader("X-Global-Transaction-Id", "<my-unique-transaction-id>");
    service.ListWorkspaces(
        callback: (DetailedResponse<Workspace> response, IBMError error) =>
        {
            if(error != null)
            {
                Log.Debug("AssistantServiceV1", "事务 ID: {0}", error.ResponseHeaders["X-Global-Transaction-Id"]);
            }
            else
            {
                Log.Debug("AssistantServiceV1", "事务 ID: {0}", response.Headers["X-Global-Transaction-Id"]);
            }
        }
    );
}

TLS 1.0 支持

Watson 服务已将其主机升级到 TLS 1.2。达拉斯地区有一个适用于流媒体的 TLS 1.0 端点。要在其他地区进行流媒体传输，请使用 Unity 2018.2，并在构建设置中将 脚本运行时版本 设置为 .NET 4.x 等效。若要在较早版本的 Unity 中支持语音转文本功能，请在达拉斯地区创建实例。

禁用 SSL 验证

您可以在进行服务调用时禁用 SSL 验证。

AssistantService assistant;
string assistantVersionDate = "<assistant-version-date>";
Authenticator assistantAuthenticator;
string workspaceId = "<workspaceId>";

void Example()
{
    authenticator.DisableSslVerification = true;
    assistant = new AssistantService(assistantVersionDate, assistantAuthenticator);

    // 禁用 SSL 验证
    assistant.DisableSslVerification = true;
}

IBM Cloud Pak for Data(ICP4D)

如果您的服务实例属于 ICP4D，则以下是初始化助理服务的两种方法。

1) 提供 username、password、icp4d_url 和 authentication_type

SDK 将为用户管理令牌

    CloudPakForDataAuthenticator authenticator = new CloudPakForDataAuthenticator("<url>", "<username>", "<password>");
    while(!authenticator.CanAuthenticate())
    {
        yield return null;
    }
    service = new AssistantService(versionDate, authenticator);

2) 提供访问令牌

    BearerTokenAuthenticator = new BearerTokenAuthenticator("<accessToken>");
    while(!authenticator.CanAuthenticate())
    {
        yield return null;
    }
    service = new AssistantService(versionDate, authenticator);

IBM Cloud Private

Watson Unity SDK 不支持 IBM Cloud Private，因为 UnityWebRequest 不支持通过代理连接。

文档

文档可以在此处找到[文档]。您也可以通过选择 Watson 菜单中的 API 参考（Watson -> API 参考）来访问文档。

入门视频

您可以在 YouTube 上观看 IBM Watson SDK for Unity 的入门视频。

问题

如果您在使用 API 时遇到问题，或对 Watson 服务有任何疑问，请参阅 Stack Overflow。

IBM 开源项目

您可以在 IBM Github 页面上找到更多开源项目。

许可证

本库采用 Apache 2.0 许可证。完整的许可证文本可在 LICENSE 中找到。

贡献

请参阅 CONTRIBUTING.md。

特色项目

我们非常乐意展示使用本 SDK 的优秀开源项目！如果您希望将自己的项目加入列表，请随时提交一个链接到该项目的问题。

IBM Watson Unity SDK 快速上手指南

⚠️ 重要提示：弃用通知 本仓库及发布的二进制文件已被 IBM 官方标记为弃用（Deprecated）。IBM 团队将不再提供主动支持，也不再发布新的二进制更新。社区提交的 PR 仍会被审查，但后续变更需开发者自行编译。建议新项目评估迁移方案或仅用于维护现有应用。

1. 环境准备

在开始之前，请确保满足以下前置条件：

• IBM Cloud 账号：您需要拥有一个 IBM Cloud 账号以获取服务实例和凭证。
• Unity 编辑器：
  • 推荐使用 Unity 2018.2 或更高版本。
  • 可以使用免费的 Personal 版本。
• 构建设置配置（关键步骤）：
  1. 打开 Unity，进入 File > Build Settings。
  2. 选择任意平台，但不支持 Web Player 或 WebGL。
  3. 点击 Player Settings，在 Other Settings 中找到：
     • Scripting Runtime Version: 设置为 .NET 4.x Equivalent。
     • Api Compatibility Level: 设置为 .NET 4.x。
     • 原因：SDK 需要访问安全选项以启用 TLS 1.2。
• macOS 用户注意：如果您升级到 macOS Mojave 或更高版本，可能需要在系统隐私设置中手动允许 Unity 访问麦克风（用于语音服务）。

2. 安装步骤

由于官方已停止二进制发布，推荐通过源码方式集成到项目中。

第一步：下载 SDK 源码

您需要下载两个核心组件：

1. Watson SDK: 从 unity-sdk 最新 Release 下载源码包。
2. Core SDK: 从 unity-sdk-core 最新 Release 下载源码包（必须）。

第二步：导入 Unity 项目

1. 解压下载的两个压缩包。
2. 将解压后的 unity-sdk 文件夹重命名为 Watson（可选，但推荐）。
3. 将解压后的 unity-sdk-core 文件夹重命名为 IBMSdkCore（可选，但推荐）。
4. 将这两个文件夹直接移动到您的 Unity 项目的 Assets 目录下。
5. 返回 Unity 编辑器，等待资源重新导入和编译完成。

3. 基本使用

3.1 获取服务凭证

在使用代码前，需在 IBM Cloud 控制台获取凭证：

1. 登录 IBM Cloud Dashboard。
2. 创建或选择一个 Watson 服务实例（如 Assistant, Speech to Text 等）。
3. 点击左侧菜单的 Service credentials -> View credentials。
4. 记录 apikey (或 username/password) 以及 url。

安全警告：请勿将凭证硬编码并提交到公共代码仓库。

3.2 认证方式

目前主要推荐使用 IAM API Key 方式进行认证。

方式 A：使用 IAM API Key（推荐）

SDK 会自动管理 Access Token 的生命周期（获取、验证和刷新）。

using IBM.Watson.Assistant.V1;
using IBM.Watson.Core;
using IBM.Watson.Core.Authentication;
using IBM.Watson.Core.DetailedResponse;
using System.Collections;

public class WatsonExample : MonoBehaviour
{
    private AssistantService assistantService;
    private string versionDate = "2021-06-14"; // 替换为对应服务的版本日期
    private string iamApiKey = "<YOUR_IAM_API_KEY>";
    private string serviceUrl = "<YOUR_SERVICE_URL>";

    IEnumerator Start()
    {
        // 1. 创建认证器
        IamAuthenticator authenticator = new IamAuthenticator(apikey: iamApiKey);
        
        // 2. 等待认证器准备就绪
        while (!authenticator.CanAuthenticate())
            yield return null;

        // 3. 初始化服务
        assistantService = new AssistantService(versionDate, authenticator);
        assistantService.SetServiceUrl(serviceUrl);

        // 4. 调用 API (示例：列出工作空间)
        assistantService.ListWorkspaces(OnListWorkspaces);
    }

    private void OnListWorkspaces(DetailedResponse<WorkspaceCollection> response, IBMError error)
    {
        if (error != null)
        {
            Log.Error("Watson Example", "Error: {0}", error.ToString());
            return;
        }
        Log.Debug("Watson Example", "Response: {0}", response.Response);
    }
}

方式 B：使用凭证文件（最简便）

如果您不想在代码中编写认证逻辑，可以使用配置文件：

1. 在 IBM Cloud 服务凭证页面点击 Download 下载 ibm-credentials.env 文件。
2. 将该文件放置在以下任一位置：
   • 您的系统用户主目录 (Home Directory)。
   • Unity 项目的根目录（与 Assets 文件夹同级）。
3. 代码中无需显式传递 authenticator，SDK 会自动读取该文件：

// 无需手动创建 Authenticator，SDK 会自动从 ibm-credentials.env 加载
assistantService = new AssistantService(versionDate); 
assistantService.SetServiceUrl("<YOUR_SERVICE_URL>"); // 如果文件中未包含 URL，仍需设置
assistantService.ListWorkspaces(OnListWorkspaces);

3.3 可用服务列表

集成成功后，您可以使用以下服务（部分旧服务已弃用，请参考官方文档迁移）：

• Assistant V1 / V2
• Discovery V1
• Language Translator V3
• Natural Language Understanding V1
• Speech to Text V1
• Text to Speech V1
• Visual Recognition V3

注：Tone Analyzer 和 Natural Language Classifier 已在 v6.0.0 中移除，如需使用请下载旧版本 SDK 并尽快迁移至 Natural Language Understanding。