Unity AI对话系统源码剖析：从状态机到语音交互的工程化实践

简介：一份面向Unity开发者的AI机器人对话系统源码包，适合在Unity3D中实现NPC对话、虚拟角色交互或模拟现实对话场景的开发者参考学习。源码围绕行为树、状态机、C#脚本与对话管理器组织AI逻辑，覆盖从用户输入处理、对话文本解析到回应生成的关键流程，并可能包含自然语言处理接口与Unity UI交互示例，整体呈现一套可运行、可拆解的人机对话实现方案。压缩包大小约60.17MB，内容以C#脚本和Unity工程源码为主，便于读者直接对照场景理解AI对话的模块划分和调用关系。目前已有1647人次浏览学习，对于希望提升游戏交互性和沉浸感的中高级Unity开发者具有较高的实践参考价值，可借助源码快速掌握对话系统的架构设计，了解行为树与状态机在对话管理中的应用，并尝试接入第三方NLP服务以丰富机器人应答能力。

1. UnityAI与机器人对话源码的实质：把对话编排进Unity主循环

拿到一套“UnityAI与机器人对话功能源码”时，很多人的第一反应是翻代码找大模型接口在哪里调用，但真正读完会发现问题不在模型层，而在对话状态管理、消息历史和Unity生命周期之间的编排。纯WebAI应用里一个fetch就能解决的请求，在Unity里要面对协程中断、场景切换、音频设备占用这几个绕不开的约束。文本对话至少牵扯UI层和网络层两层，加上语音还要再叠一层音频采集与播放。一套有价值的源码骨架，核心就是把这些异步过程收敛到几个清晰的抽象上，让业务层不直接编写HTTP细节。接下来沿着分层设计、请求封装、语音闭环、上下文维护和调试技巧五条线，把可复现的代码和参数铺开讲。

2. UnityAI对话系统的分层框架与消息模型

2.1 为什么对话管理器应该脱离MonoBehaviour

Unity初学者最容易犯的一个错，是把对话逻辑直接写进挂在场景物体上的MonoBehaviour里。原型阶段响应很快，但一旦需要切换场景、恢复历史会话、或者对接UI和语音模块，问题就会暴露：MonoBehaviour的销毁时机受场景加载控制，异步请求返回时对象可能已经被销毁，回调里访问任何成员都会抛MissingReferenceException。

合理的做法是让对话管理器独立为纯C#类，由场景里的一个瘦组件负责创建和释放。ChatManager不直接持有任何UI引用，而是通过C#事件广播状态变化。

public class ChatManager { private IAIProvider _provider; private DialogueStateMachine _stateMachine; private List<ChatMessage> _messageHistory; private CancellationTokenSource _cts; public event Action<string> OnPartialResponse; public event Action<ChatMessage> OnMessageCompleted; public event Action<DialogueState> OnStateChanged; public void Initialize(IAIProvider provider) { _provider = provider; _stateMachine = new DialogueStateMachine(); _messageHistory = new List<ChatMessage>(); } public void Shutdown() { _cts?.Cancel(); _cts?.Dispose(); _provider = null; } }

代码逻辑说明：事件字段用Action<T>而不是UnityEvent，因为Action不依赖Inspector序列化，可以用+=和-=随时注册注销，且不绑定UnityEngine.Object生命周期。CancellationTokenSource用于在场景切换或用户打断时取消进行中的请求。Shutdown里把_provider置为null，让底层对象在切场景后能被GC及时回收，避免请求回调访问到半释放的Provider。

IAIProvider是连接对话逻辑与具体AI服务的唯一接口。这个设计保证上层不感知后端实现，本地Llama.cpp、云端HTTP服务、甚至硬编码Mock都可以无缝替换。接口方法必须异步返回IEnumerator或Task，不能同步返回字符串——同步网络调用会阻塞Unity主线程，导致UnityWebRequest的回调线程拿不到主线程调度，最终整个对话流程卡死。

阅读别人源码时，重点看ChatManager在哪个场景对象里被new出来、Shutdown挂在哪个生命周期函数上。如果只在OnApplicationQuit里调用，说明作者没考虑切场景时对话状态的释放问题，这是判断代码质量的快速标尺。

2.2 消息模型字段设计与角色标记规范

对话历史必须和后端协议字段对齐。主流大模型服务的messages数组里，每条消息至少包含role和content，role取值通常是system、user、assistant，分别表示系统提示、用户输入、AI回复。

一套能复用的对话源码，消息模型还应该补充以下字段：

[Serializable] public class ChatMessage { public string role; public string content; public long timestamp; public string userId; [NonSerialized] public bool isStreamed; }

字段逐个说明：timestamp用Unix毫秒，统一单位方便在上下文裁剪时做时间差比较。userId在多NPC场景里标识对话归属，防止不同角色的对话历史互相污染。isStreamed标记消息是否为流式中间片段，UI层拿到这个标志后决定打字机动画是否继续显示，在最终消息拼接完成后要把对应的中间片段合并成完整消息。

一个值得注意的坑是JsonUtility对List<T>序列化的限制。虽然ChatMessage标了[Serializable]，但如果你把List<ChatMessage>作为普通字段放进另一个类，JsonUtility.ToJson会输出空数组。绕过办法是在外层再包一层：

[Serializable] public class ChatHistoryWrapper { public List<ChatMessage> messages = new List<ChatMessage>(); }

如果工程里已经引入Newtonsoft.Json，直接使用JsonConvert.SerializeObject(chatHistory)处理即可，不需要包装类。后者在字段名大小写、空值处理、枚举序列化这些方面都灵活得多，Unity官方维护的com.unity.nuget.newtonsoft-json包解决了License问题，可以放心使用。

2.3 对话状态机的核心状态与转移规则

对话机器人在真实交互里最常出现的问题是：用户连点两次按钮后产生两条并发请求。解决这个问题不能只靠UI置灰按钮——置灰只防住了鼠标，代码里被其他系统触发SendMessage依然会绕过。状态机的价值在于把“当前是否能发送新请求”固化成不可绕过的逻辑判断。

最小可用的状态机包含四个状态：

转移表可以用一个Dictionary实现，键是（当前状态, 触发事件）的组合，值是目标状态。这样状态多起来后不会出现switch case无限膨胀：

public class DialogueStateMachine { private Dictionary<(DialogueState, DialogueEvent), DialogueState> _transitions; public DialogueStateMachine() { _transitions = new Dictionary<(DialogueState, DialogueEvent), DialogueState> { [(DialogueState.Idle, DialogueEvent.StartListening)] = DialogueState.Listening, [(DialogueState.Listening, DialogueEvent.StopAndSend)] = DialogueState.WaitingResponse, [(DialogueState.WaitingResponse, DialogueEvent.ResponseReceived)] = DialogueState.Speaking, [(DialogueState.WaitingResponse, DialogueEvent.UserCancel)] = DialogueState.Idle, [(DialogueState.Speaking, DialogueEvent.PlaybackFinished)] = DialogueState.Idle }; } public bool TryTransition(DialogueState current, DialogueEvent trigger, out DialogueState next) { return _transitions.TryGetValue((current, trigger), out next); } }

参数说明：(DialogueState, DialogueEvent)是C# ValueTuple语法，Unity 2020.3及以上版本都支持。TryTransition返回false时说明当前状态下这个触发事件不合法——比如在Idle状态下点停止录音，请求被静默忽略，符合预期。调用方拿到false后建议打一条调试日志，方便排查是UI误触发还是状态机漏了某个转移。

提示：不要在状态机类里直接用Debug.Log写日志。状态机是纯C#类，如果引用了UnityEngine名字空间，后续做编辑器单元测试会引入额外依赖。构造时注入一个Action<string>日志回调更干净。

3. 用UnityWebRequest封装UnityAI对话请求与流式响应

3.1 最小可运行的对话请求发送

Unity从2018.4开始官方推荐用UnityWebRequest替代老的WWW类。发起一次对话POST请求，最小实现需要构造请求体、设置请求头和协程等待，缺一不可。

using UnityEngine; using UnityEngine.Networking; using System.Collections; using System.Collections.Generic; public class ChatApiClient : MonoBehaviour { private string apiUrl = "http://localhost:8000/v1/chat/completions"; public IEnumerator SendChatRequest(string userMessage, System.Action<string> onResult) { var requestBody = new Dictionary<string, object> { ["model"] = "qwen2.5-7b-instruct", ["temperature"] = 0.7f, ["max_tokens"] = 512, ["messages"] = new List<object> { new Dictionary<string, object> { ["role"] = "system", ["content"] = "你是游戏NPC助手" }, new Dictionary<string, object> { ["role"] = "user", ["content"] = userMessage } } }; string json = Newtonsoft.Json.JsonConvert.SerializeObject(requestBody); using (UnityWebRequest req = new UnityWebRequest(apiUrl, "POST")) { req.uploadHandler = new UploadHandlerRaw(Encoding.UTF8.GetBytes(json)); req.downloadHandler = new DownloadHandlerBuffer(); req.SetRequestHeader("Content-Type", "application/json"); req.timeout = 15; yield return req.SendWebRequest(); if (req.result == UnityWebRequest.Result.Success) { onResult?.Invoke(req.downloadHandler.text); } else { Debug.LogError($"对话请求失败: {req.result} {req.error}"); } } } }

代码逻辑说明：请求体用Dictionary<string, object>和List<object>构造，再经Newtonsoft.Json序列化。这个组合比JsonUtility处理嵌套集合靠谱得多。using关键字确保请求结束后UnityWebRequest对象被正确释放，避免连接句柄泄漏。req.timeout设15秒，不设置则默认为0，0在Unity里表示无限等待——本地开发时感受不到，发布到公网后一旦服务端丢包或响应慢，协程会永远挂着，UI一直停在“输入中”。

temperature是采样随机性，NPC闲聊设0.7到0.9比较自然，客服问答或知识库查询建议0.2左右。max_tokens限制单次回复长度，512个token大约对应500到800个汉字，够普通对话气泡使用。

注意：new UploadHandlerRaw(Encoding.UTF8.GetBytes(json))在传入空字符串时会抛异常。请求体序列化前检查一下string.IsNullOrEmpty(json)更稳妥，尤其当用户消息为空时后端大概率返回400。

3.2 SSE流式响应的协程拆包处理

对话功能要做到打字机效果，依赖服务端SSE流式返回。Unity没有浏览器原生的EventSource类，得通过DownloadHandlerScript手动解析增量数据。

核心处理逻辑写在ReceiveData方法里：

public class SseDownloadHandler : DownloadHandlerScript { private StringBuilder _buffer = new StringBuilder(); public event System.Action<string> OnDataChunk; protected override bool ReceiveData(byte[] data, int dataLength) { string chunk = Encoding.UTF8.GetString(data, 0, dataLength); _buffer.Append(chunk); while (true) { string current = _buffer.ToString(); int splitIndex = current.IndexOf("\n\n"); if (splitIndex < 0) break; string eventBlock = current.Substring(0, splitIndex); _buffer.Remove(0, splitIndex + 2); if (eventBlock.StartsWith("data:")) { string payload = eventBlock.Substring(5).Trim(); if (payload.Length > 0) OnDataChunk?.Invoke(payload); } } return true; } }

代码逻辑说明：ReceiveData在每次底层数据到达时被调用，数据块被追加到StringBuilder。while循环里按\n\n边界切出完整的SSE事件，只取以data:开头的行。返回true表示继续接收新数据，返回false会中止下载流程。

使用这个Handler时，要把DownloadHandlerBuffer替换成它：

var sseHandler = new SseDownloadHandler(); sseHandler.OnDataChunk += OnChunkReceived; using (UnityWebRequest req = new UnityWebRequest(apiUrl, "POST")) { req.downloadHandler = sseHandler; // 其他设置保持不变 }

每次OnDataChunk回调拿到的都是完整的一行JSON，业务层用JsonConvert.DeserializeObject解析choices[0].delta.content字段即可。如果解析失败，多半是服务端返回了[DONE]结束标记，这个标记不是JSON，需要在解析前单独判断。

3.3 超时重试与错误码处理策略

请求失败时最忌讳的是无条件重试。服务端处理不过来时重试会加重压力，密钥过期时重试一万次也没用。推荐按错误类型区分处理：

等待重试时不要直接yield return new WaitForSeconds(seconds)。如果游戏里同时存在缩放时间的逻辑，协程的等时计时会被拖慢。用真实的墙钟时间更稳：

IEnumerator WaitRealTime(float seconds) { float end = Time.realtimeSinceStartup + seconds; while (Time.realtimeSinceStartup < end) yield return null; }

Time.realtimeSinceStartup不受Time.timeScale影响，就算游戏暂停了，这个计时器也按真实时间走。对话请求的超时判断也建议用这个API，而不是Time.time。

4. 机器人对话的语音闭环：麦克风录音、识别与TTS播报

4.1 运行时麦克风录音与静音裁剪

Unity的Microphone类屏蔽了Windows、macOS和Android的底层差异，一段代码跑全平台。但它的缓冲设计是循环式的，直接处理会出现“开头是上一轮的旧声音、结尾才是本轮新声音”的问题。

private AudioClip _clip; private string _device; void StartRecording() { _device = Microphone.devices.Length > 0 ? Microphone.devices[0] : null; if (_device == null) return; _clip = Microphone.Start(_device, true, 5, 16000); } AudioClip StopAndTrim() { int lastSample = Microphone.GetPosition(_device); Microphone.End(_device); if (lastSample <= 0) return null; float[] samples = new float[lastSample * _clip.channels]; _clip.GetData(samples, 0); AudioClip result = AudioClip.Create("trimmed", lastSample, _clip.channels, 16000, false); result.SetData(samples, 0); return result; }

参数说明：Microphone.Start的第三个参数lengthSec是循环缓冲的总秒数，这里设5秒。超过5秒的声音会被覆盖，所以长句朗读场景建议放宽到10秒。frequency设16000是语音识别服务通用的低采样率，语音识别不需要48kHz的高采样，加上传输更省流量，识别速度也更快。

Microphone.GetPosition返回的是缓冲中最新写入样本的下标，截取时从0取到lastSample，而不是从lastSample取到末尾。这个方向弄反是语音模块最常见的bug，原因在于新手会习惯性地以为GetPosition是“读到这里为止”，实际上它表示“写到了这里”。

4.2 AudioClip转PCM字节流上传识别

语音识别服务商通常要求16kHz、16bit、单声道PCM格式。AudioClip.GetData拿到的是float[]，范围-1到1，需要转换成short再转字节数组：

byte[] ConvertToPcm(AudioClip clip) { float[] samples = new float[clip.samples * clip.channels]; clip.GetData(samples, 0); byte[] pcm = new byte[samples.Length * 2]; for (int i = 0; i < samples.Length; i++) { short value = (short)(Mathf.Clamp(samples[i], -1f, 1f) * short.MaxValue); byte[] bytes = System.BitConverter.GetBytes(value); pcm[i * 2] = bytes[0]; pcm[i * 2 + 1] = bytes[1]; } return pcm; }

short.MaxValue即32767，把-1到1的浮点映射到-32768到32767的范围。BitConverter.GetBytes在绝大多数平台上返回小端字节序，符合语音识别服务的PCM格式约定。如果服务端要求WAV格式，就在PCM字节流前面加44字节的WAV头（RIFF + fmt + data块）再上传。

提示：语音识别接口对音频时长的容忍度不同。直接上传整段5秒录音，如果其中包含2秒静音，多数服务可以自动跳过，但按时长计费时浪费明显。本地做一个简单的能量VAD（计算滑动窗口的RMS均方根），静音超过1秒就提前截断，省时省钱。

4.3 TTS回放与AudioSource的时序衔接

TTS服务返回的音频格式决定了解码路径。优先让后端返回WAV，因为Unity运行时无法直接解析任意MP3字节流。Resources目录下的MP3是Unity编辑器预处理的，运行时的AudioClip创建接口不接受MP3压缩格式。

public IEnumerator PlayTtsResponse(byte[] wavData) { AudioClip clip = WavUtility.ToAudioClip(wavData); if (clip == null) yield break; _audioSource.clip = clip; _audioSource.Play(); float elapsed = 0f; while (_audioSource.isPlaying && elapsed < clip.length + 1f) { elapsed += Time.deltaTime; yield return null; } _audioSource.clip = null; _stateMachine.TransitionTo(DialogueState.Idle); }

代码逻辑说明：WavUtility.ToAudioClip是负责解析WAV文件的工具方法，核心是跳过44字节RIFF头，把data块内的PCM数据转成AudioClip。elapsed上限设为clip.length + 1f，防止音频设备异常时isPlaying永远为true，状态机卡死在Speaking。播放结束后显式置空clip，释放AudioClip占用的托管内存。_audioSource.loop必须为false，否则isPlaying永远不结束，对话永远不会返回Idle状态。

AudioSource.priority的取值范围是0到32，0是最高优先级。对话属于交互型音频，建议直接设0，避免游戏BGM音量较大时语音被引擎降权。如果机器人角色在3D场景里，spatialBlend设0.7以上，让玩家能根据声音定位角色方位，同时dopplerLevel保持0，避免移动摄像机时产生音调漂移。

5. UnityAI机器人对话的上下文维护与内容安全兜底

5.1 用System Prompt稳定NPC人设

对话机器人要表现得像“某个角色”，关键在System Prompt的构造。一个合格的系统提示词应包含四层信息：身份（你是谁）、场景（现在在做什么）、风格（怎么说话）、边界（什么不回应）。散乱的一段话不如结构化的Prompt稳定，原因是模型对指令的跟随能力直接受文本结构影响。

private string BuildSystemPrompt(string npcName, string persona) { return $@"你是游戏《星港》的NPC向导{npcName}。 人物设定：{persona}。 说话时保持口语化，每次不超过3句话或60个汉字。 涉及现实世界新闻或引战内容时，主动把话题拉回游戏任务。"; }

参数说明：3句话这个限制在大模型生成时比字数限制更有效，因为模型对句式的理解强于对字符计数的理解。60个汉字与Unity里的Text组件单行显示高度搭配，超过这个长度后对话气泡需要动态扩容，会打乱UI布局。如果你同时做语音播报，60字意味着TTS播放时长在15到20秒之间，配合到这个范围才不会让玩家等得不耐烦。

System Prompt同样消耗token预算。一段100到200字符的Prompt大约占60到120个token，在max_tokens=512配置下已经吃掉近四分之一的预算。所以人设Prompt控制在80字以内比较实际，别写成小作文。

5.2 滑动窗口裁剪与发送时机

大多数开源模型的上下文窗口在4k到8k token之间，多轮对话不做裁剪的话，12到15轮之后就会顶到上限，服务端报context_length_exceeded错误。

序列化前的计算顺序不能写反：

public List<ChatMessage> BuildRequestPayload(string userInput) { _messageHistory.Add(new ChatMessage { role = "user", content = userInput }); int overflow = _messageHistory.Count - maxKeepCount; if (overflow > 0) _messageHistory.RemoveRange(0, overflow); return _messageHistory; }

这段代码先加入新消息再裁剪，确保裁剪发生在最新一轮消息入列之后。如果反过来——先裁剪再加入——每次都会丢掉一条有效消息，导致对话记忆比预期少一轮。逻辑很简单，但顺序反了的现象在源码里很常见。

去掉历史里最旧的user或assistant消息会让对话上下文出现断裂。如果你在system消息里明确了“按最近的对话主题回答”，模型会优先遵循最近的内容，所以不用过度担心裁剪造成的语义割裂。

5.3 本地敏感内容过滤与降级响应

多轮对话中，开源模型的输出不完全可控，需要一层本地过滤兜底。过滤逻辑分为两段：发送前对用户输入做检查，接收后对模型输出做校验。发送前命中敏感词时，跳过模型调用直接返回降级文案。

public bool TryFilterInput(string userInput, out string fallback) { foreach (string keyword in _sensitiveKeywords) { if (userInput.Contains(keyword)) { fallback = "这个方向我不太懂，我们聊聊游戏吧。"; return true; } } fallback = null; return false; }

这段代码输出两条信息：是否命中过滤，以及命中后的降级文案。调用方拿到true后直接走UI显示，不触发任何网络请求。后置过滤模型输出时，除了检测敏感词，还要检查长度是否超限——有些模型在遇到恶意拼接提示词时会输出超长内容，设置一个200字符的上限能避免UI被撑爆。

过滤词表的维护原则是宁缺毋滥。词表维护成本是隐性的，误杀正常对话会降低体验，漏过又起不到保护作用。对需要正式上线的项目，更稳妥的做法是额外接入云端内容安全服务，让云端辅助过滤，本地词表只做必须拦截的高置信度词项。

6. 用MockProvider调试UnityAI对话状态机

6.1 一个30行的MockProvider实现

调试对话流转时，最怕网络波动把问题搞混：超时、限流、数据格式错误交织在一起，很难定位是代码问题还是环境问题。一个可取的做法是在IAIProvider上做一个Mock实现，让对话流程在没有网络的情况下完全确定性地执行。

public class MockProvider : IAIProvider { public IEnumerator RequestAsync(ChatMessage userMessage, Action<string> onPartial, Action<string> onCompleted) { string reply = "我是Mock回复，验证对话流程用"; foreach (char c in reply) { onPartial?.Invoke(c.ToString()); yield return new WaitForSeconds(0.05f); } onCompleted?.Invoke(reply); } }

代码逻辑说明：MockProvider逐字符调用onPartial，模拟真实流式返回的拆包节奏。onCompleted在最后调用，给出完整消息。这段代码不产生任何HTTP请求，自然也不会超时或报错，状态机、UI绑定、语音播放全部可以在这个环境里完整走通。

调用方式只在初始化处改一行：

_chatManager.Initialize(new MockProvider());

6.2 三个日志观察点与异常定位

配合Mock环境，在三个位置打日志能快速定位异常：ChatManager.SendMessage入口处打Debug.Log，DialogueStateMachine.TryTransition返回false时打Debug.LogError，TrimHistory执行裁剪时打Debug.LogWarning。

跑一轮Mock对话后看Console日志的先后顺序：正常路径应该是“信息日志 → 信息日志 → 若干流式chunk → 信息日志”。如果看到Error出现在某个状态转移时，说明状态机的字典里漏了对应的转移规则，补上即可。

MockProvider的价值在于过程可复现。把网络的随机性拿掉之后，所有问题都变成了确定性的逻辑问题，调试效率不在一个量级。

本文还有配套的精品资源，点击获取