1. 项目概述为什么要在Unity里做流式对话最近在做一个Unity项目需要集成一个智能对话功能。用户输入文字问题后台的AI模型不是一次性吐出全部答案而是一个字一个字、或者一个词一个词地“流”回来在UI上实时显示出来。这种体验就像你在和一个人打字聊天对方正在“输入中…”然后逐字呈现回复感觉非常自然和即时。我评估了几个方案最终选择了火山引擎的机器翻译与自然语言处理相关服务具体是其中的大模型服务来实现这个“文字提问流式回复”的功能。选择火山引擎主要是看中它提供了相对稳定、低延迟的API并且支持SSEServer-Sent Events这种非常适合流式传输的协议对于Unity这种游戏引擎来说集成起来比自己去搭建WebSocket服务或者处理长轮询要省心得多。这个功能可以用在很多地方比如游戏内的智能NPC对话、虚拟主播的实时问答、教育类应用的知识点交互甚至是工具软件里的AI助手。2. 核心思路与方案选型2.1 流式回复的技术本质流式回复的核心是改变传统“请求-等待-完整响应”的同步模式变为“请求-持续接收-实时渲染”的异步流模式。对于AI大模型生成文本这种耗时操作尤其有用。技术实现上主要有几种方式WebSocket双向全双工通信能力最强但服务器和客户端都需要额外维护连接状态对于单纯的服务器向客户端推送文本流的场景有点“杀鸡用牛刀”且Unity的WebSocket实现需要引入第三方库。长轮询Long Polling客户端发起请求服务器持有请求直到有新数据或超时。实现简单但效率较低频繁建立连接开销大。Server-Sent Events (SSE)基于HTTP的单向服务器推送技术。客户端发起一个HTTP请求服务器可以持续通过这个连接发送多个事件流。它完美契合了“服务器向客户端持续推送文本片段”这个需求协议简单天然支持断线重连并且是纯HTTP兼容性极好。火山引擎的大模型服务API通常就支持SSE方式的流式输出。这意味着我们只需要在Unity里发起一个携带问题和流式参数的HTTP请求然后像读取一个持续打开的流一样不断地从网络响应中读取新的文本数据块即可。2.2 Unity网络通信方案选择Unity中进行HTTP通信传统上有UnityWebRequest它是Unity官方提供的网络工具。对于流式SSE我们需要持续读取响应体UnityWebRequest的DownloadHandler虽然可以处理数据但要实现真正的流式读取需要用到DownloadHandler的子类DownloadHandlerScript并重写其ReceiveContent方法这需要一些额外的编码工作。另一种更现代、更灵活的选择是使用System.Net.Http.HttpClient需要.NET 4.x或.NET Standard 2.1兼容的运行时版本。HttpClient提供了更强大的异步流支持HttpCompletionOption.ResponseHeadersRead配合ReadAsStreamAsync可以让我们以Stream的方式精细控制响应数据的读取非常适合处理SSE流。考虑到代码的清晰度和对异步流的原生支持本项目选择了HttpClient方案。注意使用HttpClient需要确保你的Unity项目脚本运行时版本支持推荐使用.NET Standard 2.1或.NET 4.x及以上并且在Android/iOS等平台需要检查其网络后端实现是否完全兼容。实测在主流平台表现良好。2.3 火山引擎API对接要点在对接前你需要前往火山引擎控制台开通相应的自然语言处理或大模型服务创建一个应用并获取API Key和Secret Key用于鉴权。火山引擎的API鉴权通常使用HMAC-SHA256签名算法我们需要在Unity中构造签名。流式请求的关键在于API的请求参数。以常见的文本生成接口为例你需要关注两个参数stream: 必须设置为true告诉服务器开启流式输出。temperature、top_p等控制生成文本随机性的参数根据你的需求调整。流式和非流式调用这些参数的意义是一致的。服务器返回的将不是一个完整的JSON而是一个遵循SSE格式的文本流。每一段数据以data:开头后面跟着一个JSON对象包含当前生成的文本片段或结束标志并以两个换行符\n\n结尾。我们的客户端代码需要持续解析这个流。3. 核心模块实现与代码拆解3.1 网络请求与流式读取核心类我们创建一个核心管理类VolcanoStreamingClient。这个类负责封装所有与火山引擎API交互的细节。using System; using System.Collections.Generic; using System.IO; using System.Net.Http; using System.Security.Cryptography; using System.Text; using System.Threading; using System.Threading.Tasks; using UnityEngine; public class VolcanoStreamingClient : MonoBehaviour { // 配置参数建议从ScriptableObject或配置文件中读取 public string apiHost ark.cn-beijing.volces.com; // 示例host以控制台为准 public string apiPath /api/v3/chat/completions; // 示例路径以控制台为准 public string accessKey; // 你的AK public string secretKey; // 你的SK private HttpClient _httpClient; private CancellationTokenSource _cancellationTokenSource; void Awake() { // 创建HttpClient实例建议单例管理 _httpClient new HttpClient(); _httpClient.Timeout TimeSpan.FromSeconds(60); // 设置较长超时因为连接会保持 } void OnDestroy() { _httpClient?.Dispose(); CancelCurrentRequest(); // 清理可能的正在进行的请求 } // 取消当前正在进行的流式请求 public void CancelCurrentRequest() { _cancellationTokenSource?.Cancel(); _cancellationTokenSource?.Dispose(); _cancellationTokenSource null; } }接下来是核心的请求和签名方法。火山引擎的签名通常需要UTC时间戳、随机数等信息。private string GenerateSignature(string timestamp, string nonce, string bodyJson) { // 构建签名字符串格式可能为{path}\n{method}\n{query}\n{host}\n{content-type}\n{timestamp}\n{nonce}\n{body} // !!! 重要务必严格按照火山引擎API文档的签名方法示例来构建 !!! string signString ${apiPath}\nPOST\n\n{apiHost}\napplication/json\n{timestamp}\n{nonce}\n{bodyJson}; using (var hmac new HMACSHA256(Encoding.UTF8.GetBytes(secretKey))) { byte[] hashBytes hmac.ComputeHash(Encoding.UTF8.GetBytes(signString)); return BitConverter.ToString(hashBytes).Replace(-, ).ToLower(); } }3.2 发起流式请求与解析SSE这是最关键的AskStreamingAsync方法。它接收用户问题和一个回调委托用于实时推送收到的文本片段。public async Task AskStreamingAsync(string userMessage, Actionstring onChunkReceived, Actionstring onCompleted null, ActionException onError null) { CancelCurrentRequest(); // 确保之前的请求被取消 _cancellationTokenSource new CancellationTokenSource(); var cancellationToken _cancellationTokenSource.Token; try { // 1. 准备请求Body var requestBody new { model your_model_name, // 替换为你的模型名称如“deepseek-llm” messages new[] { new { role user, content userMessage } }, stream true, // 关键参数开启流式 temperature 0.7 }; string bodyJson JsonUtility.ToJson(requestBody); // JsonUtility可能不适用复杂对象生产环境建议使用Newtonsoft.Json或Unity自带的JsonSerializer // 这里为演示假设requestBody是可序列化的简单对象。 // 2. 生成签名所需参数 string timestamp DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString(); string nonce Guid.NewGuid().ToString(N); string signature GenerateSignature(timestamp, nonce, bodyJson); // 3. 构建HTTP请求 var requestUrl $https://{apiHost}{apiPath}; var request new HttpRequestMessage(HttpMethod.Post, requestUrl); request.Content new StringContent(bodyJson, Encoding.UTF8, application/json); // 添加鉴权Header具体字段名参考API文档 request.Headers.Add(X-Date, timestamp); request.Headers.Add(X-Content-Sha256, CalculateSHA256(bodyJson)); // 可能需要 request.Headers.Add(Authorization, $HMAC-SHA256 Credential{accessKey}, SignedHeadershost;x-content-sha256;x-date, Signature{signature}); // 4. 发送请求并获取流式响应 // ResponseHeadersRead意味着接收到响应头后就立即返回而不是等待整个响应体 var response await _httpClient.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, cancellationToken); response.EnsureSuccessStatusCode(); // 5. 以流的方式读取响应内容 using (var responseStream await response.Content.ReadAsStreamAsync()) using (var streamReader new StreamReader(responseStream)) { // 用于累积不完整的行 StringBuilder buffer new StringBuilder(); char[] readBuffer new char[8192]; // 8KB缓冲区 while (!cancellationToken.IsCancellationRequested) { int bytesRead await streamReader.ReadAsync(readBuffer, 0, readBuffer.Length, cancellationToken); if (bytesRead 0) // 流结束 { Debug.Log(Stream ended.); break; } // 将读取到的字符添加到缓冲区 buffer.Append(readBuffer, 0, bytesRead); string currentData buffer.ToString(); // 6. 解析SSE格式按“\n\n”分割事件 int lastNewLineDoubleIndex; while ((lastNewLineDoubleIndex currentData.IndexOf(\n\n)) ! -1) { string eventBlock currentData.Substring(0, lastNewLineDoubleIndex); currentData currentData.Substring(lastNewLineDoubleIndex 2); // 移除已处理的部分 buffer.Clear(); buffer.Append(currentData); // 剩余部分放回缓冲区 ProcessEventBlock(eventBlock, onChunkReceived); } } // 处理缓冲区可能残留的最后一条不完整数据理论上SSE应以\n\n结尾但安全起见 if (buffer.Length 0) { ProcessEventBlock(buffer.ToString(), onChunkReceived); } } onCompleted?.Invoke(Stream finished.); } catch (TaskCanceledException) { Debug.Log(Request was canceled by user.); } catch (Exception e) { Debug.LogError($Streaming request failed: {e}); onError?.Invoke(e); } finally { _cancellationTokenSource?.Dispose(); _cancellationTokenSource null; } } // 处理单个SSE事件块 private void ProcessEventBlock(string block, Actionstring onChunkReceived) { if (string.IsNullOrWhiteSpace(block) || !block.StartsWith(data: )) return; string jsonStr block.Substring(5).Trim(); // 去掉data: if (jsonStr [DONE]) // 流结束标志 { Debug.Log(Received [DONE] signal.); return; } // 解析JSON这里需要根据火山引擎返回的实际JSON结构来定义类 try { // 示例解析假设返回格式为 {“choices”:[{“delta”:{“content”:”text chunk”}}]} var jsonNode JsonUtility.FromJsonVolcanoStreamResponse(jsonStr); if (jsonNode?.choices?.Length 0) { string chunk jsonNode.choices[0]?.delta?.content; if (!string.IsNullOrEmpty(chunk)) { // 在主线程调用回调因为UI操作必须在主线程 MainThreadDispatcher.RunOnMainThread(() onChunkReceived?.Invoke(chunk)); } } } catch (Exception e) { Debug.LogWarning($Failed to parse SSE data block: {e.Message}\nBlock: {block}); } } // 辅助方法计算SHA256 private string CalculateSHA256(string input) { using (var sha256 SHA256.Create()) { byte[] bytes sha256.ComputeHash(Encoding.UTF8.GetBytes(input)); return BitConverter.ToString(bytes).Replace(-, ).ToLower(); } } // 定义响应数据结构类需根据实际API响应调整 [System.Serializable] public class VolcanoStreamResponse { public Choice[] choices; } [System.Serializable] public class Choice { public Delta delta; } [System.Serializable] public class Delta { public string content; }3.3 UI交互与主线程调度Unity中所有对GameObject和UI组件如Text、TextMeshProUGUI的修改都必须在主线程进行。而我们的网络请求是在后台异步线程中运行的。因此我们需要一个机制将收到的文本块“调度”回主线程进行渲染。我们可以创建一个简单的MainThreadDispatcher单例类using System; using System.Collections.Concurrent; using System.Collections.Generic; using UnityEngine; public class MainThreadDispatcher : MonoBehaviour { private static MainThreadDispatcher _instance; private readonly ConcurrentQueueAction _executionQueue new ConcurrentQueueAction(); public static MainThreadDispatcher Instance { get { if (_instance null) { GameObject go new GameObject(MainThreadDispatcher); _instance go.AddComponentMainThreadDispatcher(); DontDestroyOnLoad(go); } return _instance; } } public static void RunOnMainThread(Action action) { if (action null) return; Instance._executionQueue.Enqueue(action); } void Update() { // 每帧执行所有累积在主线程的任务 while (_executionQueue.TryDequeue(out Action action)) { action?.Invoke(); } } }在UI层我们有一个简单的对话界面脚本using TMPro; using UnityEngine; using UnityEngine.UI; public class ChatUI : MonoBehaviour { public TMP_InputField inputField; public TextMeshProUGUI outputText; public Button sendButton; public VolcanoStreamingClient streamingClient; // 拖拽赋值 private StringBuilder _currentResponse new StringBuilder(); void Start() { sendButton.onClick.AddListener(OnSendButtonClicked); // 也可以监听inputField的onSubmit事件 } async void OnSendButtonClicked() { string question inputField.text; if (string.IsNullOrEmpty(question)) return; inputField.interactable false; sendButton.interactable false; outputText.text 思考中...; _currentResponse.Clear(); try { await streamingClient.AskStreamingAsync( question, onChunkReceived: (chunk) { // 这个回调在子线程被触发通过Dispatcher跳转到主线程 MainThreadDispatcher.RunOnMainThread(() { _currentResponse.Append(chunk); outputText.text _currentResponse.ToString(); }); }, onCompleted: (msg) { MainThreadDispatcher.RunOnMainThread(() { Debug.Log($对话完成: {msg}); ResetUI(); }); }, onError: (error) { MainThreadDispatcher.RunOnMainThread(() { outputText.text $出错: {error.Message}; ResetUI(); }); } ); } catch (System.Exception e) { Debug.LogError(e); ResetUI(); } } void ResetUI() { inputField.interactable true; sendButton.interactable true; inputField.text ; inputField.Select(); inputField.ActivateInputField(); } }4. 实战部署与优化要点4.1 正确处理请求生命周期在Unity中场景切换或对象销毁时必须妥善处理未完成的网络请求否则可能导致内存泄漏或尝试更新已销毁的UI对象而报错。取消令牌CancellationToken如代码所示我们使用CancellationTokenSource来管理请求的取消。在OnDestroy或UI关闭时调用CancelCurrentRequest()方法。异步方法安全确保async方法被取消时能正确捕获TaskCanceledException并优雅退出而不是抛出其他异常。单例与依赖注入VolcanoStreamingClient最好作为单例或通过依赖注入框架管理避免重复创建HttpClient。HttpClient本身设计为可重用的频繁创建和销毁会导致套接字耗尽。4.2 性能与内存优化缓冲区大小流读取的缓冲区大小示例中为8192字符可以根据实际情况调整。太小会增加读取次数太大可能增加单次处理延迟。字符串操作频繁的字符串拼接如_currentResponse.Append(chunk)在回复很长时可能影响性能。可以考虑使用StringBuilder并在UI更新时进行节流比如累积几个字符或每0.1秒更新一次UI而不是每收到一个字符就更新但这会牺牲一定的实时性。UI更新频率对于极快的流每收到一个字符就更新一次Text组件可能会造成UI卡顿。可以使用协程或计时器来限制UI更新的频率例如每累积50毫秒的文本或每收到5个字符再更新一次。// 简单的节流示例在UI脚本中 private System.Collections.IEnumerator UpdateTextWithThrottle() { while (_isReceiving) { yield return new WaitForSeconds(0.05f); // 每50ms更新一次 if (_dirtyFlag) { outputText.text _currentResponse.ToString(); _dirtyFlag false; } } } // 在收到chunk时只设置_dirtyFlag为true不直接更新text。4.3 错误处理与重试机制网络请求充满不确定性健壮的错误处理必不可少。网络异常HttpRequestException、IOException、超时等。应捕获这些异常并给用户友好的提示如“网络连接不稳定请重试”。API错误火山引擎API返回的错误状态码如4xx5xx。需要解析响应的错误体如果是非流式错误响应并转换为可读信息。重试策略对于网络波动导致的失败可以实现简单的重试逻辑。但需要注意对于流式请求重试意味着重新发起整个对话请求可能会丢失上下文。更复杂的实现可以结合“断点续传”的思路但这需要服务器支持。心跳与超时长时间的流式连接可能因为防火墙或代理而中断。虽然SSE协议有内置的重连机制但客户端也可以定期发送心跳或检查连接状态。5. 常见问题与排查实录在实际集成过程中我遇到了不少坑这里记录下最典型的几个问题和解决方法。5.1 签名错误 (Signature mismatch)这是对接火山引擎API时最常见的问题。错误提示通常是403或SignatureNotMatch。排查步骤逐字核对文档签名算法的每一步都必须严格按照官方最新文档来。空格、换行符、字段顺序一个都不能错。我最初就因为在签名字符串里多了一个空格导致一直失败。时间同步确保生成签名用的时间戳X-Date是UTC时间并且你的服务器时间与网络时间同步。误差过大通常超过5分钟会被拒绝。Body编码确保计算签名时使用的bodyJson字符串和实际发送的HTTP请求体完全一致包括空格和换行。最好在生成签名后将签名字符串和实际发送的Body打印到日志里与官方提供的签名工具或示例进行比对。Secret Key确认确认使用的Secret Key是正确的且没有多余的空格或换行。5.2 流式响应解析失败或中断现象是能收到数据但ProcessEventBlock解析不出内容或者连接突然断开。排查步骤原始数据日志在ProcessEventBlock方法开始时将原始的block字符串打印出来。确认它是否符合data: {...}\n\n或data: [DONE]\n\n的格式。有时网络缓冲区可能导致事件块不完整我们的缓冲区分割逻辑IndexOf(\n\n)就是处理这个的。JSON结构验证将打印出的jsonStr复制到在线的JSON格式化工具中检查其结构是否与你定义的VolcanoStreamResponse类匹配。火山引擎不同模型的流式返回格式可能有细微差别务必以实际返回为准。连接稳定性在移动网络或弱网环境下TCP连接可能不稳定。可以尝试增加HttpClient的超时时间并考虑加入心跳保活机制如果API支持。对于Unity移动端确保应用有正确的网络权限Android Manifest中的INTERNET权限。5.3 Unity在Android/iOS平台上的网络权限与后端问题在编辑器里运行正常打包到真机后无法连接。Android确认权限在Assets/Plugins/Android/AndroidManifest.xml文件中确保有uses-permission android:nameandroid.permission.INTERNET /。Cleartext Traffic如果火山引擎的API地址是HTTP非HTTPS在Android 9以上需要允许明文传输。在AndroidManifest.xml的application标签内添加android:usesCleartextTraffictrue。强烈建议使用HTTPS。iOSATSiOS默认要求使用HTTPS。如果你的API是HTTPS且证书有效通常没问题。如果使用非常规证书或需要调试可能需要在Info.plist中配置ATS例外但这在提交App Store时可能会被审核关注。后台线程确保网络请求不在主线程阻塞。我们的async/await模式通常能处理好这一点但要避免在回调中做耗时操作。5.4 UI更新卡顿或延迟当流式回复速度极快时频繁的UI更新可能导致主线程卡顿。解决方案使用TextMeshProUnity原生的UI.Text在频繁更新大量文本时性能较差TextMeshProUGUI是更好的选择。更新节流如前文所述采用累积更新或基于时间的更新而非逐字更新。对象池如果对话气泡是动态生成的使用对象池来复用GameObject避免频繁的实例化和销毁。Profiler分析使用Unity Profiler查看性能瓶颈到底是在UI渲染、字符串操作还是GC垃圾回收上。StringBuilder的滥用也可能导致大量内存分配。5.5 内存泄漏排查长时间运行或频繁对话后内存持续增长。主要怀疑点事件订阅确保onChunkReceived等回调委托在请求完成后被正确释放。如果回调方法捕获了外部对象如UI组件而该对象的生命周期短于网络客户端可能导致内存泄漏。在我们的设计中回调是通过UI按钮触发的且UI和Client生命周期通常一起管理问题不大。但更严谨的做法是使用WeakReference或确保在取消请求时清空回调。HttpClient确保HttpClient实例是单例或静态的并在应用退出时正确Dispose。不要为每个请求创建新的HttpClient。字符串累积_currentResponse会累积整个对话历史。对于非常长的多轮对话需要考虑设置一个历史长度上限或者定期清理旧对话。
Unity集成火山引擎大模型实现流式对话：SSE与HttpClient实战
1. 项目概述为什么要在Unity里做流式对话最近在做一个Unity项目需要集成一个智能对话功能。用户输入文字问题后台的AI模型不是一次性吐出全部答案而是一个字一个字、或者一个词一个词地“流”回来在UI上实时显示出来。这种体验就像你在和一个人打字聊天对方正在“输入中…”然后逐字呈现回复感觉非常自然和即时。我评估了几个方案最终选择了火山引擎的机器翻译与自然语言处理相关服务具体是其中的大模型服务来实现这个“文字提问流式回复”的功能。选择火山引擎主要是看中它提供了相对稳定、低延迟的API并且支持SSEServer-Sent Events这种非常适合流式传输的协议对于Unity这种游戏引擎来说集成起来比自己去搭建WebSocket服务或者处理长轮询要省心得多。这个功能可以用在很多地方比如游戏内的智能NPC对话、虚拟主播的实时问答、教育类应用的知识点交互甚至是工具软件里的AI助手。2. 核心思路与方案选型2.1 流式回复的技术本质流式回复的核心是改变传统“请求-等待-完整响应”的同步模式变为“请求-持续接收-实时渲染”的异步流模式。对于AI大模型生成文本这种耗时操作尤其有用。技术实现上主要有几种方式WebSocket双向全双工通信能力最强但服务器和客户端都需要额外维护连接状态对于单纯的服务器向客户端推送文本流的场景有点“杀鸡用牛刀”且Unity的WebSocket实现需要引入第三方库。长轮询Long Polling客户端发起请求服务器持有请求直到有新数据或超时。实现简单但效率较低频繁建立连接开销大。Server-Sent Events (SSE)基于HTTP的单向服务器推送技术。客户端发起一个HTTP请求服务器可以持续通过这个连接发送多个事件流。它完美契合了“服务器向客户端持续推送文本片段”这个需求协议简单天然支持断线重连并且是纯HTTP兼容性极好。火山引擎的大模型服务API通常就支持SSE方式的流式输出。这意味着我们只需要在Unity里发起一个携带问题和流式参数的HTTP请求然后像读取一个持续打开的流一样不断地从网络响应中读取新的文本数据块即可。2.2 Unity网络通信方案选择Unity中进行HTTP通信传统上有UnityWebRequest它是Unity官方提供的网络工具。对于流式SSE我们需要持续读取响应体UnityWebRequest的DownloadHandler虽然可以处理数据但要实现真正的流式读取需要用到DownloadHandler的子类DownloadHandlerScript并重写其ReceiveContent方法这需要一些额外的编码工作。另一种更现代、更灵活的选择是使用System.Net.Http.HttpClient需要.NET 4.x或.NET Standard 2.1兼容的运行时版本。HttpClient提供了更强大的异步流支持HttpCompletionOption.ResponseHeadersRead配合ReadAsStreamAsync可以让我们以Stream的方式精细控制响应数据的读取非常适合处理SSE流。考虑到代码的清晰度和对异步流的原生支持本项目选择了HttpClient方案。注意使用HttpClient需要确保你的Unity项目脚本运行时版本支持推荐使用.NET Standard 2.1或.NET 4.x及以上并且在Android/iOS等平台需要检查其网络后端实现是否完全兼容。实测在主流平台表现良好。2.3 火山引擎API对接要点在对接前你需要前往火山引擎控制台开通相应的自然语言处理或大模型服务创建一个应用并获取API Key和Secret Key用于鉴权。火山引擎的API鉴权通常使用HMAC-SHA256签名算法我们需要在Unity中构造签名。流式请求的关键在于API的请求参数。以常见的文本生成接口为例你需要关注两个参数stream: 必须设置为true告诉服务器开启流式输出。temperature、top_p等控制生成文本随机性的参数根据你的需求调整。流式和非流式调用这些参数的意义是一致的。服务器返回的将不是一个完整的JSON而是一个遵循SSE格式的文本流。每一段数据以data:开头后面跟着一个JSON对象包含当前生成的文本片段或结束标志并以两个换行符\n\n结尾。我们的客户端代码需要持续解析这个流。3. 核心模块实现与代码拆解3.1 网络请求与流式读取核心类我们创建一个核心管理类VolcanoStreamingClient。这个类负责封装所有与火山引擎API交互的细节。using System; using System.Collections.Generic; using System.IO; using System.Net.Http; using System.Security.Cryptography; using System.Text; using System.Threading; using System.Threading.Tasks; using UnityEngine; public class VolcanoStreamingClient : MonoBehaviour { // 配置参数建议从ScriptableObject或配置文件中读取 public string apiHost ark.cn-beijing.volces.com; // 示例host以控制台为准 public string apiPath /api/v3/chat/completions; // 示例路径以控制台为准 public string accessKey; // 你的AK public string secretKey; // 你的SK private HttpClient _httpClient; private CancellationTokenSource _cancellationTokenSource; void Awake() { // 创建HttpClient实例建议单例管理 _httpClient new HttpClient(); _httpClient.Timeout TimeSpan.FromSeconds(60); // 设置较长超时因为连接会保持 } void OnDestroy() { _httpClient?.Dispose(); CancelCurrentRequest(); // 清理可能的正在进行的请求 } // 取消当前正在进行的流式请求 public void CancelCurrentRequest() { _cancellationTokenSource?.Cancel(); _cancellationTokenSource?.Dispose(); _cancellationTokenSource null; } }接下来是核心的请求和签名方法。火山引擎的签名通常需要UTC时间戳、随机数等信息。private string GenerateSignature(string timestamp, string nonce, string bodyJson) { // 构建签名字符串格式可能为{path}\n{method}\n{query}\n{host}\n{content-type}\n{timestamp}\n{nonce}\n{body} // !!! 重要务必严格按照火山引擎API文档的签名方法示例来构建 !!! string signString ${apiPath}\nPOST\n\n{apiHost}\napplication/json\n{timestamp}\n{nonce}\n{bodyJson}; using (var hmac new HMACSHA256(Encoding.UTF8.GetBytes(secretKey))) { byte[] hashBytes hmac.ComputeHash(Encoding.UTF8.GetBytes(signString)); return BitConverter.ToString(hashBytes).Replace(-, ).ToLower(); } }3.2 发起流式请求与解析SSE这是最关键的AskStreamingAsync方法。它接收用户问题和一个回调委托用于实时推送收到的文本片段。public async Task AskStreamingAsync(string userMessage, Actionstring onChunkReceived, Actionstring onCompleted null, ActionException onError null) { CancelCurrentRequest(); // 确保之前的请求被取消 _cancellationTokenSource new CancellationTokenSource(); var cancellationToken _cancellationTokenSource.Token; try { // 1. 准备请求Body var requestBody new { model your_model_name, // 替换为你的模型名称如“deepseek-llm” messages new[] { new { role user, content userMessage } }, stream true, // 关键参数开启流式 temperature 0.7 }; string bodyJson JsonUtility.ToJson(requestBody); // JsonUtility可能不适用复杂对象生产环境建议使用Newtonsoft.Json或Unity自带的JsonSerializer // 这里为演示假设requestBody是可序列化的简单对象。 // 2. 生成签名所需参数 string timestamp DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString(); string nonce Guid.NewGuid().ToString(N); string signature GenerateSignature(timestamp, nonce, bodyJson); // 3. 构建HTTP请求 var requestUrl $https://{apiHost}{apiPath}; var request new HttpRequestMessage(HttpMethod.Post, requestUrl); request.Content new StringContent(bodyJson, Encoding.UTF8, application/json); // 添加鉴权Header具体字段名参考API文档 request.Headers.Add(X-Date, timestamp); request.Headers.Add(X-Content-Sha256, CalculateSHA256(bodyJson)); // 可能需要 request.Headers.Add(Authorization, $HMAC-SHA256 Credential{accessKey}, SignedHeadershost;x-content-sha256;x-date, Signature{signature}); // 4. 发送请求并获取流式响应 // ResponseHeadersRead意味着接收到响应头后就立即返回而不是等待整个响应体 var response await _httpClient.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, cancellationToken); response.EnsureSuccessStatusCode(); // 5. 以流的方式读取响应内容 using (var responseStream await response.Content.ReadAsStreamAsync()) using (var streamReader new StreamReader(responseStream)) { // 用于累积不完整的行 StringBuilder buffer new StringBuilder(); char[] readBuffer new char[8192]; // 8KB缓冲区 while (!cancellationToken.IsCancellationRequested) { int bytesRead await streamReader.ReadAsync(readBuffer, 0, readBuffer.Length, cancellationToken); if (bytesRead 0) // 流结束 { Debug.Log(Stream ended.); break; } // 将读取到的字符添加到缓冲区 buffer.Append(readBuffer, 0, bytesRead); string currentData buffer.ToString(); // 6. 解析SSE格式按“\n\n”分割事件 int lastNewLineDoubleIndex; while ((lastNewLineDoubleIndex currentData.IndexOf(\n\n)) ! -1) { string eventBlock currentData.Substring(0, lastNewLineDoubleIndex); currentData currentData.Substring(lastNewLineDoubleIndex 2); // 移除已处理的部分 buffer.Clear(); buffer.Append(currentData); // 剩余部分放回缓冲区 ProcessEventBlock(eventBlock, onChunkReceived); } } // 处理缓冲区可能残留的最后一条不完整数据理论上SSE应以\n\n结尾但安全起见 if (buffer.Length 0) { ProcessEventBlock(buffer.ToString(), onChunkReceived); } } onCompleted?.Invoke(Stream finished.); } catch (TaskCanceledException) { Debug.Log(Request was canceled by user.); } catch (Exception e) { Debug.LogError($Streaming request failed: {e}); onError?.Invoke(e); } finally { _cancellationTokenSource?.Dispose(); _cancellationTokenSource null; } } // 处理单个SSE事件块 private void ProcessEventBlock(string block, Actionstring onChunkReceived) { if (string.IsNullOrWhiteSpace(block) || !block.StartsWith(data: )) return; string jsonStr block.Substring(5).Trim(); // 去掉data: if (jsonStr [DONE]) // 流结束标志 { Debug.Log(Received [DONE] signal.); return; } // 解析JSON这里需要根据火山引擎返回的实际JSON结构来定义类 try { // 示例解析假设返回格式为 {“choices”:[{“delta”:{“content”:”text chunk”}}]} var jsonNode JsonUtility.FromJsonVolcanoStreamResponse(jsonStr); if (jsonNode?.choices?.Length 0) { string chunk jsonNode.choices[0]?.delta?.content; if (!string.IsNullOrEmpty(chunk)) { // 在主线程调用回调因为UI操作必须在主线程 MainThreadDispatcher.RunOnMainThread(() onChunkReceived?.Invoke(chunk)); } } } catch (Exception e) { Debug.LogWarning($Failed to parse SSE data block: {e.Message}\nBlock: {block}); } } // 辅助方法计算SHA256 private string CalculateSHA256(string input) { using (var sha256 SHA256.Create()) { byte[] bytes sha256.ComputeHash(Encoding.UTF8.GetBytes(input)); return BitConverter.ToString(bytes).Replace(-, ).ToLower(); } } // 定义响应数据结构类需根据实际API响应调整 [System.Serializable] public class VolcanoStreamResponse { public Choice[] choices; } [System.Serializable] public class Choice { public Delta delta; } [System.Serializable] public class Delta { public string content; }3.3 UI交互与主线程调度Unity中所有对GameObject和UI组件如Text、TextMeshProUGUI的修改都必须在主线程进行。而我们的网络请求是在后台异步线程中运行的。因此我们需要一个机制将收到的文本块“调度”回主线程进行渲染。我们可以创建一个简单的MainThreadDispatcher单例类using System; using System.Collections.Concurrent; using System.Collections.Generic; using UnityEngine; public class MainThreadDispatcher : MonoBehaviour { private static MainThreadDispatcher _instance; private readonly ConcurrentQueueAction _executionQueue new ConcurrentQueueAction(); public static MainThreadDispatcher Instance { get { if (_instance null) { GameObject go new GameObject(MainThreadDispatcher); _instance go.AddComponentMainThreadDispatcher(); DontDestroyOnLoad(go); } return _instance; } } public static void RunOnMainThread(Action action) { if (action null) return; Instance._executionQueue.Enqueue(action); } void Update() { // 每帧执行所有累积在主线程的任务 while (_executionQueue.TryDequeue(out Action action)) { action?.Invoke(); } } }在UI层我们有一个简单的对话界面脚本using TMPro; using UnityEngine; using UnityEngine.UI; public class ChatUI : MonoBehaviour { public TMP_InputField inputField; public TextMeshProUGUI outputText; public Button sendButton; public VolcanoStreamingClient streamingClient; // 拖拽赋值 private StringBuilder _currentResponse new StringBuilder(); void Start() { sendButton.onClick.AddListener(OnSendButtonClicked); // 也可以监听inputField的onSubmit事件 } async void OnSendButtonClicked() { string question inputField.text; if (string.IsNullOrEmpty(question)) return; inputField.interactable false; sendButton.interactable false; outputText.text 思考中...; _currentResponse.Clear(); try { await streamingClient.AskStreamingAsync( question, onChunkReceived: (chunk) { // 这个回调在子线程被触发通过Dispatcher跳转到主线程 MainThreadDispatcher.RunOnMainThread(() { _currentResponse.Append(chunk); outputText.text _currentResponse.ToString(); }); }, onCompleted: (msg) { MainThreadDispatcher.RunOnMainThread(() { Debug.Log($对话完成: {msg}); ResetUI(); }); }, onError: (error) { MainThreadDispatcher.RunOnMainThread(() { outputText.text $出错: {error.Message}; ResetUI(); }); } ); } catch (System.Exception e) { Debug.LogError(e); ResetUI(); } } void ResetUI() { inputField.interactable true; sendButton.interactable true; inputField.text ; inputField.Select(); inputField.ActivateInputField(); } }4. 实战部署与优化要点4.1 正确处理请求生命周期在Unity中场景切换或对象销毁时必须妥善处理未完成的网络请求否则可能导致内存泄漏或尝试更新已销毁的UI对象而报错。取消令牌CancellationToken如代码所示我们使用CancellationTokenSource来管理请求的取消。在OnDestroy或UI关闭时调用CancelCurrentRequest()方法。异步方法安全确保async方法被取消时能正确捕获TaskCanceledException并优雅退出而不是抛出其他异常。单例与依赖注入VolcanoStreamingClient最好作为单例或通过依赖注入框架管理避免重复创建HttpClient。HttpClient本身设计为可重用的频繁创建和销毁会导致套接字耗尽。4.2 性能与内存优化缓冲区大小流读取的缓冲区大小示例中为8192字符可以根据实际情况调整。太小会增加读取次数太大可能增加单次处理延迟。字符串操作频繁的字符串拼接如_currentResponse.Append(chunk)在回复很长时可能影响性能。可以考虑使用StringBuilder并在UI更新时进行节流比如累积几个字符或每0.1秒更新一次UI而不是每收到一个字符就更新但这会牺牲一定的实时性。UI更新频率对于极快的流每收到一个字符就更新一次Text组件可能会造成UI卡顿。可以使用协程或计时器来限制UI更新的频率例如每累积50毫秒的文本或每收到5个字符再更新一次。// 简单的节流示例在UI脚本中 private System.Collections.IEnumerator UpdateTextWithThrottle() { while (_isReceiving) { yield return new WaitForSeconds(0.05f); // 每50ms更新一次 if (_dirtyFlag) { outputText.text _currentResponse.ToString(); _dirtyFlag false; } } } // 在收到chunk时只设置_dirtyFlag为true不直接更新text。4.3 错误处理与重试机制网络请求充满不确定性健壮的错误处理必不可少。网络异常HttpRequestException、IOException、超时等。应捕获这些异常并给用户友好的提示如“网络连接不稳定请重试”。API错误火山引擎API返回的错误状态码如4xx5xx。需要解析响应的错误体如果是非流式错误响应并转换为可读信息。重试策略对于网络波动导致的失败可以实现简单的重试逻辑。但需要注意对于流式请求重试意味着重新发起整个对话请求可能会丢失上下文。更复杂的实现可以结合“断点续传”的思路但这需要服务器支持。心跳与超时长时间的流式连接可能因为防火墙或代理而中断。虽然SSE协议有内置的重连机制但客户端也可以定期发送心跳或检查连接状态。5. 常见问题与排查实录在实际集成过程中我遇到了不少坑这里记录下最典型的几个问题和解决方法。5.1 签名错误 (Signature mismatch)这是对接火山引擎API时最常见的问题。错误提示通常是403或SignatureNotMatch。排查步骤逐字核对文档签名算法的每一步都必须严格按照官方最新文档来。空格、换行符、字段顺序一个都不能错。我最初就因为在签名字符串里多了一个空格导致一直失败。时间同步确保生成签名用的时间戳X-Date是UTC时间并且你的服务器时间与网络时间同步。误差过大通常超过5分钟会被拒绝。Body编码确保计算签名时使用的bodyJson字符串和实际发送的HTTP请求体完全一致包括空格和换行。最好在生成签名后将签名字符串和实际发送的Body打印到日志里与官方提供的签名工具或示例进行比对。Secret Key确认确认使用的Secret Key是正确的且没有多余的空格或换行。5.2 流式响应解析失败或中断现象是能收到数据但ProcessEventBlock解析不出内容或者连接突然断开。排查步骤原始数据日志在ProcessEventBlock方法开始时将原始的block字符串打印出来。确认它是否符合data: {...}\n\n或data: [DONE]\n\n的格式。有时网络缓冲区可能导致事件块不完整我们的缓冲区分割逻辑IndexOf(\n\n)就是处理这个的。JSON结构验证将打印出的jsonStr复制到在线的JSON格式化工具中检查其结构是否与你定义的VolcanoStreamResponse类匹配。火山引擎不同模型的流式返回格式可能有细微差别务必以实际返回为准。连接稳定性在移动网络或弱网环境下TCP连接可能不稳定。可以尝试增加HttpClient的超时时间并考虑加入心跳保活机制如果API支持。对于Unity移动端确保应用有正确的网络权限Android Manifest中的INTERNET权限。5.3 Unity在Android/iOS平台上的网络权限与后端问题在编辑器里运行正常打包到真机后无法连接。Android确认权限在Assets/Plugins/Android/AndroidManifest.xml文件中确保有uses-permission android:nameandroid.permission.INTERNET /。Cleartext Traffic如果火山引擎的API地址是HTTP非HTTPS在Android 9以上需要允许明文传输。在AndroidManifest.xml的application标签内添加android:usesCleartextTraffictrue。强烈建议使用HTTPS。iOSATSiOS默认要求使用HTTPS。如果你的API是HTTPS且证书有效通常没问题。如果使用非常规证书或需要调试可能需要在Info.plist中配置ATS例外但这在提交App Store时可能会被审核关注。后台线程确保网络请求不在主线程阻塞。我们的async/await模式通常能处理好这一点但要避免在回调中做耗时操作。5.4 UI更新卡顿或延迟当流式回复速度极快时频繁的UI更新可能导致主线程卡顿。解决方案使用TextMeshProUnity原生的UI.Text在频繁更新大量文本时性能较差TextMeshProUGUI是更好的选择。更新节流如前文所述采用累积更新或基于时间的更新而非逐字更新。对象池如果对话气泡是动态生成的使用对象池来复用GameObject避免频繁的实例化和销毁。Profiler分析使用Unity Profiler查看性能瓶颈到底是在UI渲染、字符串操作还是GC垃圾回收上。StringBuilder的滥用也可能导致大量内存分配。5.5 内存泄漏排查长时间运行或频繁对话后内存持续增长。主要怀疑点事件订阅确保onChunkReceived等回调委托在请求完成后被正确释放。如果回调方法捕获了外部对象如UI组件而该对象的生命周期短于网络客户端可能导致内存泄漏。在我们的设计中回调是通过UI按钮触发的且UI和Client生命周期通常一起管理问题不大。但更严谨的做法是使用WeakReference或确保在取消请求时清空回调。HttpClient确保HttpClient实例是单例或静态的并在应用退出时正确Dispose。不要为每个请求创建新的HttpClient。字符串累积_currentResponse会累积整个对话历史。对于非常长的多轮对话需要考虑设置一个历史长度上限或者定期清理旧对话。
