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

转录历史与查询

从代码读取当前对话轮次时间线,实时响应轮次变化,并将会话历史导出为文本、Markdown 或 JSON。

ConvaiManager.ActiveManager.Transcripts 让你的代码能够以结构化方式访问当前房间会话中的每一次对话轮次。通过 GetTurns 读取当前状态, CurrentTimeline 和 GetTurns,通过 Subscribe 对实时变化作出响应, Subscribe 和 SubscribeCommitted,并通过 Export 导出已完成的轮次。 Export。此外观层不会控制屏幕上显示的内容——有关这方面请参见 转录 UI 。如需完整 API 参考,请参见 转录 API.

读取当前转录状态

ConvaiManager.ActiveManager.Transcripts.CurrentTimeline 返回一个不可变的 TranscriptTimeline ——在你读取它的那一刻,对房间中每个轮次的一致视图。反复读取它的成本很低:在运行时发布变更之前,它会返回同一个实例;只有时间线实际发生变化时才会返回新实例。

ConvaiManager.ActiveManager.Transcripts 会抛出 InvalidOperationException 如果 SDK 尚未完成初始化。对于较早运行的代码(OnEnable, Awake),请使用 ConvaiManager.ActiveManager.TryGetTranscripts(out ConvaiTranscripts transcripts) 代替,它返回 false 而不是抛出。

成员
类型
说明

游标

long

单调递增计数器。每当运行时发布更新时都会变化

ActiveTurns

IReadOnlyList<TranscriptTurn>

仍在进行中的轮次——尚未提交或中断

CommittedTurns

IReadOnlyList<TranscriptTurn>

已完成的轮次(Committed 或 被打断 状态)

TurnsById

IReadOnlyDictionary<string, TranscriptTurn>

按以下内容快速查找: TranscriptTurn.Id,涵盖活动和已提交轮次

Turns

IReadOnlyList<TranscriptTurn>

按以下顺序排列的每个轮次(活动和已提交) RoomSequence

每个 TranscriptTurn 公开 DisplayText (已提交文本加上任何进行中的临时文本), 说话者 (一个 TranscriptSpeaker 使用 类型, Id, DisplayName, ParticipantId), StartedAtUtc, WasInterrupted,以及 Revision ——一个整数,每当该轮次的存储数据发生变化时就递增一次。请使用 turn.IsCommitted 来检查轮次是否已结束,而不是直接比较 State 。

using Convai.Domain.Models;
using Convai.Runtime.Components;
using System.Text;
using UnityEngine;

public class SessionReporter : MonoBehaviour
{
    public string BuildSessionReport()
    {
        TranscriptTimeline timeline = ConvaiManager.ActiveManager.Transcripts.CurrentTimeline;
        var sb = new StringBuilder();

        foreach (TranscriptTurn turn in timeline.CommittedTurns)
            sb.AppendLine($"[{turn.StartedAtUtc:HH:mm:ss}] {turn.Speaker.DisplayName}: {turn.DisplayText}");

        return sb.ToString();
    }
}

查找单个轮次

使用 GetTurn(string turnId) 用于按 ID 进行 O(1) 查找,或 GetLatestTurn(TranscriptParticipantRef) 用于获取某个特定玩家或角色的最新轮次。

这两个方法都会返回 null 当不存在匹配的轮次时。

使用以下方式筛选轮次: TranscriptQuery

将一个 TranscriptQuery 为 GetTurns(query) 以检索时间线的一个子集。省略查询,或将某个字段留空,将禁用对应筛选。结果按 RoomSequence.

字段
类型
默认
说明

ParticipantKind

TranscriptParticipantKind?

null (任意)

仅限制为 Player 或 Character 轮次

PlayerOrCharacterId

string

null (任意)

按 ID 限制为某个特定玩家或角色

ParticipantId

string

null (任意)

按房间作用域的参与者 ID 限制(多用户房间)

IncludeActiveTurns

bool

true

在结果中包含进行中的轮次

IncludeCommittedTurns

bool

true

在结果中包含已完成的轮次

TranscriptQuery.ParticipantKind 使用 TranscriptParticipantKind (Player 或 Character)。这是一个独立于 TranscriptSpeakerType (Player, Character,或 System)的枚举,它出现在 TranscriptSpeaker 和 TranscriptSubscriptionOptions 本页下方。

响应实时转录变化

调用 Subscribe(callback, options) 以接收一个 TranscriptChange 每当匹配的轮次发生变化时。 Subscribe 返回一个 IDisposable ——释放它即可取消订阅,通常在 OnDisable.

TranscriptChange.Kind 会告诉你发生了什么; TranscriptChange.Turn 是更新后的轮次,或者 null 当 Kind 是 Removed (读取 TurnId )在这种情况下。

TranscriptChangeKind

含义

Added

该轮次首次出现在时间线中

Updated

轮次仍处于活动状态时,其文本发生了变化(流式或稳定)

Committed

轮次正常完成

被打断

轮次因其他发言者打断而完成

Corrected

先前发送的该轮次文本被追溯更正

Removed

该轮次已从时间线中移除; 轮次 是 null

TranscriptSubscriptionOptions 控制哪些轮次和变更类型会到达你的回调:

字段
类型
默认
说明

ReplayExisting

bool

false

在实时更新开始前,立即为每个当前匹配的轮次调用回调

IncludeActive

bool

true

包含尚未完成的轮次变更

IncludeTerminal

bool

true

包含已提交、中断或更正的轮次变更

SpeakerType

TranscriptSpeakerType?

null (任意)

仅限制为 Player, Character,或 System 轮次

SpeakerId

string

null (任意)

按 ID 限制为某个特定玩家或角色

ParticipantId

string

null (任意)

按房间作用域的参与者 ID 限制(多用户房间)

SubscribeCommitted(callback, options) 是对以下内容的便捷封装: Subscribe 它强制设置 IncludeActive = false 和 IncludeTerminal = true,因此回调只会在轮次完成后触发——当你只关心已完成历史时使用,例如聊天记录或评分系统。

对于需要立即查看之前轮次的后加入观看者,请将 ReplayExisting = true 设置在传递给 Subscribe ——在实时更新开始前,匹配的轮次会先向你的回调传递一次。

导出并清空转录历史

Export(TranscriptExportFormat format) 将按以下顺序序列化每个已提交轮次: RoomSequence,并合并为一个字符串。它读取自 CurrentTimeline.CommittedTurns ——活动轮次绝不会包含在内。

TranscriptExportFormat

输出

PlainText

每个轮次一行: "{speaker}: {turn.DisplayText}"

Markdown

每个轮次一行: "**{speaker}:** {turn.DisplayText}",轮次之间留一个空行

Json

一个带缩进的 JSON 数组,由 TranscriptTurn 对象

该 {speaker} 的值是 turn.Speaker.DisplayName,或 turn.Speaker.Type 当 DisplayName 为空。

调用 Clear() 以从规范房间历史中移除每个轮次:

故障排除

症状
可能原因
修复方法
验证

ConvaiManager.ActiveManager.Transcripts 会抛出 InvalidOperationException

在以下操作之前访问: ConvaiManager 完成初始化

使用 ConvaiManager.ActiveManager.TryGetTranscripts(out var transcripts),或检查 ConvaiManager.IsBootstrapped 首先

TryGetTranscripts 返回 true 和 transcripts 非空

Subscribe 回调从不触发

在房间会话已经结束后才订阅,或者 TranscriptSubscriptionOptions 筛选条件排除了所有轮次

请在房间连接之前或刚连接后订阅;确认 SpeakerType, SpeakerId,以及 ParticipantId 与实际参与者匹配

订阅后,回调会在下一次轮次变化时触发

GetTurns() 在设置了查询时返回空列表

PlayerOrCharacterId 或 ParticipantId 不匹配任何参与者,或者两者都 IncludeActiveTurns 和 IncludeCommittedTurns 是 false

日志 turn.Speaker.Id 和 turn.Speaker.ParticipantId 来自未过滤的 Subscribe 回调以找到正确的值

GetTurns() 使用更正后的查询会返回非空列表

change.Turn 是 null 在一个 Subscribe 回调的协程

change.Kind 是 TranscriptChangeKind.Removed

读取 change.TurnId 而不是 change.Turn 当 Kind 是 Removed

在移除时,回调不再抛出空引用异常

Export(TranscriptExportFormat.PlainText) 返回空字符串

尚无轮次提交

Export 仅仅读取 CurrentTimeline.CommittedTurns;请等待轮次完成,或检查 CommittedTurns.Count 首先

CurrentTimeline.CommittedTurns.Count 在导出前是否大于零

下一步

你现在已拥有对房间转录时间线、实时变更通知以及导出支持的完整读取权限。有关本页背后的完整 API 表面,请参见 Transcript API 参考。若要在场景中显示这些数据,请参见 Transcript UI。若要配置运行时启用的可视模式,请参见 Settings Panel。

转录 API转录 UI设置面板

最后更新于

这有帮助吗?