日志、指标与重试策略

按子系统配置 SDK 日志详细级别，将日志路由到自定义输出端，读取 RTVI 管道延迟指标，并调整连接重试策略。

Convai Unity SDK 附带默认配置，可适用于训练模拟、交互式体验和游戏。当你需要诊断延迟、减少生产环境中的日志噪声、了解 AI 管线的时序，或调整重连行为时——本页涵盖可用的控制项。

跳转到你需要的主题：

• 日志级别配置 — 减少生产构建中的控制台噪声
• 自定义日志接收器 — 将日志路由到文件或远程服务
• RTVI 服务器端调试指标 — 按轮次测量 AI 管线延迟
• 重试策略 — 为不稳定网络调整重连行为

---

日志级别配置

日志级别

级别	枚举值	适用场景
关闭	0	禁用所有 SDK 日志。
错误	1	生产构建——仅错误。
警告	2	预发布——警告和错误。
信息	3	默认。 正常运行消息。
调试	4	主动开发——详细的生命周期事件。
跟踪	5	深度调试——高频内部状态。

这些值对应于 Convai.Domain.Logging.LogLevel 枚举。

跟踪 是位于 调试 级别会产生大量输出。SDK 调试日志在 Unity 编辑器和开发构建中处于激活状态。在发布构建中，除非 CONVAI_DEBUG_LOGGING 被添加到 Scripting Define Symbols 中，否则会被编译器剥离。请不要在 跟踪 启用的情况下发布。

在 Inspector 中配置

打开 项目设置 → Convai （或选择 ConvaiSettings 资源资产 Assets/Resources/ConvaiSettings.asset）。在 Logging 部分下：

字段	说明
全局日志级别	所有 SDK 子系统的最低级别。
包含堆栈跟踪	为 Warning 和 Error 消息附加堆栈跟踪。
彩色输出	在 Unity 控制台中对日志消息进行颜色编码。
类别覆盖	按子系统覆盖级别——添加条目，为特定类别设置更细粒度的级别。

日志类别

类别	子系统
SDK	通用操作
角色	按角色会话生命周期
音频	麦克风采集、播放、音频设备
Transport	WebRTC / WebSocket 连接层
事件	内部事件总线
转录	转录处理和路由
叙事	叙事设计系统
LipSync	唇形同步处理和 blendshape 播放
视觉	摄像头捕获和视频发布
引导	SDK 启动和初始化
UI	UI 组件生命周期
REST	REST API 通信
玩家	玩家身份和输入
编辑器	仅编辑器操作

这些值对应于 Convai.Domain.Logging.LogCategory 枚举。

在运行时配置

using Convai.Runtime;
using Convai.Domain.Logging;

// 设置全局级别——会立即应用于后续所有日志调用。
ConvaiSettings.Instance.SetGlobalLogLevel(LogLevel.Debug);

// 覆盖特定子系统，而不改变全局级别。
ConvaiSettings.Instance.SetCategoryOverrides(new[]
{
    new LogLevelOverride(LogCategory.Audio,     LogLevel.Debug),
    new LogLevelOverride(LogCategory.Transport, LogLevel.Warning)
});

LogLevelOverride 是一个包含两个字段的结构体： LogCategory Category 是位于 LogLevel Level.

CONVAI_DEBUG_LOGGING 脚本定义

ConvaiLogger.Debug(...) 调用受三个 [Conditional] 属性保护： UNITY_EDITOR, DEVELOPMENT_BUILD，以及 CONVAI_DEBUG_LOGGING。如果这些符号都未定义，编译器会将其从任何构建中剥离——在生产发布构建中零开销。

要在发布构建中启用调试日志：添加 CONVAI_DEBUG_LOGGING 到 项目设置 → Player → Scripting Define Symbols。开发构建会自动启用它们，无需此定义。

---

自定义日志接收器

通过实现以下接口，将 SDK 日志输出路由到文件、远程日志服务或任何目标： ILogSink 并将其注册到 ConvaiLogger.

// FileSink.cs
using System;
using System.IO;
using Convai.Domain.Logging;

public class FileSink : ILogSink
{
    private readonly StreamWriter _writer;

    public string Name      => "FileSink";
    public bool   IsEnabled { get; private set; } = true;

    public FileSink(string path)
        => _writer = new StreamWriter(path, append: true);

    public void Write(LogEntry entry)
        => _writer.WriteLine($"[{entry.Timestamp:HH:mm:ss.fff}] [{entry.Level}] [{entry.Category}] {entry.Message}");

    public void Flush()             => _writer.Flush();
    public void SetEnabled(bool en) => IsEnabled = en;
    public void Dispose()           => _writer?.Dispose();
}

在以下之后注册 ConvaiLogger 初始化：

using Convai.Runtime.Logging;

// 当 ConvaiLogger 就绪时会触发 OnInitializationCompleted——务必在这里注册 sink，
// 切勿更早，以避免错过初始化窗口。
ConvaiLogger.OnInitializationCompleted += _ =>
{
    string logPath = Path.Combine(Application.persistentDataPath, "convai_session.log");
    ConvaiLogger.RegisterSink(new FileSink(logPath));
};

Sink 生命周期：

• ILogSink 扩展 IDisposable — 实现类必须提供一个 Dispose() 方法。
• 调用 ConvaiLogger.UnregisterSink(sink) 在释放 sink 之前调用。
• 调用 ConvaiLogger.FlushAllSinks() 应在应用退出时调用，以确保缓冲的条目被写入。

---

RTVI 服务器端调试指标

RTVI（Real-Time Voice Interaction，实时语音交互）是 Convai 的会话协议。当 ConvaiRoomManager.Debug 为 true启用时，服务器会在每次 AI 回合后将管线指标流式传输到客户端，显示每个阶段（语音转文本、LLM、文本转语音等）花费的时间。当你需要定位管线中的瓶颈阶段时使用此项——例如，AI 响应慢是因为转录延迟还是 LLM 生成时间？

启用调试指标

ConvaiRoomManager.Debug 是一个只读运行时属性。通过勾选 调试 复选框 ConvaiRoomManager 组件上的

在进入播放模式之前于 Inspector 中。调试指标会给每回合增加少量开销。仅在性能分析会话中勾选此选项——不要在启用状态下发布。

读取指标

// MetricsLogger.cs
using Convai.Runtime.Adapters.Networking;
using Convai.Infrastructure.Protocol.Messages;
using UnityEngine;

public class MetricsLogger : MonoBehaviour
{
    [SerializeField] private ConvaiRoomManager _roomManager;

    private void OnEnable()
        => _roomManager.OnRtvMetricsReceived += OnMetricsReceived;

    private void OnDisable()
        => _roomManager.OnRtvMetricsReceived -= OnMetricsReceived;

    private void OnMetricsReceived(RTVIMetricsPayload payload)
    {
        if (payload.Ttfb       != null) Debug.Log($"[指标] TTFB: {payload.Ttfb}");
        if (payload.Processing != null) Debug.Log($"[指标] Processing: {payload.Processing}");
        if (payload.Custom     != null) Debug.Log($"[指标] Custom: {payload.Custom}");
    }
}

指标字段

字段	类型	说明
Ttfb	JToken?	每个处理器的首字节时间（秒）。包含 {processor, value} 条目的数组。
Processing	JToken?	本次回合每个处理器的总处理时长（秒）。
自定义	JToken?	特定提供方的指标——格式因处理器而异（例如， output_fps, blendshapes_received 来自 NeuroSync）。

Ttfb 是位于 Processing 是原始 JToken 值（来自 Newtonsoft.Json.Linq，通过以下方式包含在 Unity 中： com.unity.nuget.newtonsoft-json 包）。将它们反序列化为 payload.Ttfb.ToObject<List<MetricEntry>>() 其中 MetricEntry 是一个与该 {processor, value} 形状匹配的结构体。并非每一轮都会包含所有指标类型——访问前务必进行空值检查。

---

重试策略

SDK 使用 ExponentialBackoffPolicy 来处理瞬时连接失败。默认行为：

尝试	重试前的延迟
1（初始）	0 秒
2	1 秒
3	2 秒
4	4 秒

在总共 4 次尝试后（1 次初始 + 3 次重试），操作失败。该策略只会重试瞬时错误：超时、网络中断，以及 OperationCanceledException。非瞬时错误（身份验证失败、配置无效）会立即失败。

何时自定义重试策略

默认策略（4 次尝试、指数退避，最长 4 秒）可覆盖大多数普通网络条件。在以下情况下考虑自定义策略：

• 部署在工业或嵌入式硬件上 且已知会间歇性连接——增加 MaxAttempts 和延迟步长。
• 自助终端或常开安装 ——更激进的重试（更多尝试、更长的最大延迟）可避免在短暂网络中断后需要用户干预。
• 低延迟训练环境 且网络可靠——减少 MaxAttempts 以快速失败，并将错误暴露到你自己的重连 UI，而不是静默重试。

如果你只需要更多尝试而不改变延迟曲线，请增加 maxRetryAttempts 在 ConvaiBootstrapConfigSnapshot 中——无需自定义策略。

自定义重试策略

实现 IRetryPolicy 并使用 RetryExecutor 来包装任何异步操作：

// AggressiveRetryPolicy.cs
using System;
using Convai.Runtime.Core.Policies;

public class AggressiveRetryPolicy : IRetryPolicy
{
    public int MaxAttempts => 6;

    public TimeSpan GetDelay(int attempt) => attempt switch
    {
        0 => TimeSpan.Zero,
        1 => TimeSpan.FromSeconds(2),
        2 => TimeSpan.FromSeconds(5),
        3 => TimeSpan.FromSeconds(10),
        4 => TimeSpan.FromSeconds(20),
        _ => TimeSpan.FromSeconds(30)
    };

    public bool ShouldRetry(Exception exception, int attempt)
    {
        if (attempt >= MaxAttempts) return false;
        return exception is TimeoutException
            || exception is System.Net.WebException
            || exception is OperationCanceledException;
    }
}

using Convai.Runtime.Core.Policies;

var executor = new RetryExecutor(new AggressiveRetryPolicy());

await executor.ExecuteAsync(async (attempt, ct) =>
{
    Debug.Log($"连接尝试 {attempt + 1}...");
    await someAsyncOperation(ct);
    return true;
}, cancellationToken);

---

生产检查清单

• 全局日志级别 设置为 警告 或 错误 在生产 ConvaiSettings 资源资产中。
• CONVAI_DEBUG_LOGGING 不是 存在于发布构建的 Scripting Define Symbols 中。
• ConvaiRoomManager.Debug 复选框 未勾选 在生产场景中。
• maxRetryAttempts 在 ConvaiBootstrapConfigSnapshot 适合你的目标网络（默认 3 适用于大多数普通消费者连接）。
• connectionTimeoutSeconds 考虑到了你部署中最慢的目标设备/网络（默认 30 秒）。
• 自定义 ILogSink 实例会在应用退出时注销并释放。
• ConvaiLogger.FlushAllSinks() 在以下情况下调用 Application.quitting 处理程序，如果任何 sink 会缓冲输出。

---

故障排查

症状	可能原因	修复
发布构建中控制台被 SDK 消息刷屏	CONVAI_DEBUG_LOGGING 定义已存在，或者 GlobalLogLevel 为 调试 或 跟踪	移除脚本定义，并将全局级别设置为 警告 或 错误.
OnRtvMetricsReceived 从不触发	ConvaiRoomManager.Debug 未勾选，或者角色尚未完成完整回合	启用 Debug 复选框，并验证完整 AI 回合已完成（用户发言、角色响应）。
Ttfb / Processing 字段为空	服务器没有为此回合包含这些指标类型	访问前先处理空值。并非每一轮都会包含所有指标类型。
连接在 4 次尝试后失败且不再重试	默认值 ExponentialBackoffPolicy 已达到 MaxAttempts = 4	增加 maxRetryAttempts 在 ConvaiBootstrapConfigSnapshot，或者实现自定义 IRetryPolicy.
自定义日志 sink 缺少早期启动消息	sink 在以下之后注册 ConvaiLogger.Initialize() 已经触发	通过 OnInitializationCompleted 回调注册——在初始化完成前切勿注册 sink。

---

下一步

故障排除运行时模块系统实现自定义模块