For the complete documentation index, see llms.txt. This page is also available as Markdown.

异步模式

使用 async/await、协程、链式调用、进度跟踪、取消和流来消费 IConvaiOperation<T> 和 IConvaiStream<T>。

IConvaiOperation<T> 和 IConvaiStream<T> 支持多种消费模式,因此你可以使用最适合你代码库的风格——纯 async/await、Unity 协程,或两者混合使用。有关类型定义和成员引用,请参阅 操作与流类型.


异步/await

最直接的模式。适用于任何 async 方法。出错的操作会抛出 ConvaiOperationException.

using Convai.Runtime.Core.Async;
using Convai.Runtime.Facades;
using System.Threading;
using UnityEngine;

public class AsyncConnectExample : MonoBehaviour
{
    private async void Start()
    {
        var manager = ConvaiManager.ActiveManager;
        if (manager == null) return;

        try
        {
            var session = await manager.ConnectAsync(destroyCancellationToken);
            Debug.Log($"已连接。房间:{session.RoomId}");
        }
        catch (ConvaiOperationException ex)
        {
            Debug.LogError($"[{ex.Code}] 连接失败:{ex.Message}");
        }
        catch (OperationCanceledException)
        {
            Debug.Log("连接已取消——场景已卸载。");
        }
    }
}

await operation 与 await operation.AsTask()

两者结果相同。优先使用 await operation 直接使用——它会用到 GetAwaiter() ,并避免额外分配。仅在需要将操作传递给要求 AsTask() 的方法时才使用 Task<T>,例如 Task.WhenAll.


协程

当你的脚本不能使用 async (例如,在不支持 async 的 Unity 事件回调中),或者你更喜欢基于回调的流程时,请使用协程。

ToCoroutine 会一直挂起,直到操作完成。两者 onSuccess 和 onError 都是可选的——如果不需要回调,对任意一项都传 null 即可。


ContinueWith 链式调用

将一个操作的结果转换为另一个操作,而无需嵌套 await 调用。

ContinueWith 会传播错误:如果源操作出错,链式操作也会以相同错误出错,而不会调用选择器。


进度跟踪

轮询 operation.Progress 来驱动 UI 进度指示器。该值会从 0.0 为 1.0 随着操作完成而前进。并非所有操作都会报告细粒度进度——请检查 状态 以确定最终完成状态。


取消

使用 CancellationToken

将一个 CancellationToken 传递给任何 SDK 方法。当令牌被触发时,操作会转变为 已取消 状态。

使用 destroyCancellationToken

MonoBehaviour.destroyCancellationToken 是作用于组件生命周期内操作的最简单取消模式——当组件被销毁时,令牌会自动被触发。

使用 operation.Cancel()

调用 Cancel() 在操作句柄上直接调用,用于独立于 CancellationToken.

CancellationToken 与 operation.Cancel()

CancellationToken

operation.Cancel()

来源

外部(CancellationTokenSource)

操作句柄

使用场景

组件生命周期、超时、关联取消

通过按钮或事件取消单个操作

与协程兼容

在创建操作时传递

随时在句柄上调用


流

使用 IConvaiStream<T> 使用 await foreach 和 await using 用于资源清理。

ReadAllAsync 返回 IAsyncEnumerable<T>。当流到达 已完成, 或,或 已取消已故障 await using 时循环退出。务必包装在 DisposeAsync() 中,即使循环提前退出也会调用它。

始终释放流。未能 await using 释放流会导致底层资源泄漏。


错误处理决策表

场景
模式
原因

async void MonoBehaviour 方法

使用 try/catch 的 Async/await

自然契合;故障会以异常形式显现

UI 按钮回调(不支持 async)

带有 onError 回调的协程

按钮回调是同步的

带转换的顺序操作

ContinueWith 链式调用

避免嵌套 await;自动传播错误

进度条或加载遮罩层

协程轮询 进度

yield return null 每帧循环

组件生命周期作用域

destroyCancellationToken

零样板代码;自动清理

用户触发的取消(按钮)

operation.Cancel()

无需 CTS 的直接句柄控制

持续数据流

await foreach + await using

IAsyncEnumerable + 保证释放


使用示例

示例 1——带进度条和取消按钮的加载遮罩层

一个医学培训模拟在会话连接时显示加载遮罩层,并提供可视化进度条和取消按钮,供希望在会话开始前退出的学习者使用。

示例 2——将流式转写令牌输出到自定义日志控件

一个企业入职模拟从 Convai 流式传输单个转写令牌,并将它们一次一个地追加到自定义日志控件中,产生打字机式效果。


故障排除

症状
可能原因
修复方法

操作保持在 运行中 无限期

等待从未到来的响应的 SDK 方法(网络超时)

设置一个 CancellationToken ,并设定超时: new CancellationTokenSource(TimeSpan.FromSeconds(15)).Token

HasError 是 true 但 ConvaiOperationException 不会抛出

使用协程路径——错误会传递给 onError 回调,而不会抛出

添加一个 onError 回调到 ToCoroutine()

catch (ConvaiOperationException) 在取消时永远不会命中

取消会抛出 OperationCanceledException,而不是 ConvaiOperationException

添加一个单独的 catch (OperationCanceledException) 块

一旦 operation.Cancel()

在调用取消之前,操作已完成

检查 IsCompleted 在调用之前 Cancel()

场景卸载时流卡住

ReadAllAsync 未传递 CancellationToken

传递 destroyCancellationToken 为 ReadAllAsync

ContinueWith 选择器从不运行

源操作出错;错误已传播,选择器被跳过

检查链式操作的 HasError 或捕获 ConvaiOperationException 在 await 处


下一步

有关这些模式背后的完整类型参考,请参阅 操作与流类型。对于返回 IConvaiOperation<T>的 SDK 方法,请参阅 ConvaiManager API 和 角色与玩家 API.

最后更新于

这有帮助吗?