简介面向Unity开发者的AI对话机器人源码包围绕行为树、状态机、C#脚本、对话管理器与UI交互等模块展开适合希望为游戏或虚拟体验引入智能对话系统的中高级开发者。压缩包约60.17MB文件数量与具体类型暂未标注但此类源码包通常包含可直接运行的Unity工程、核心C#脚本及演示场景。目前已有1647人学习下载常用于NPC互动、任务引导与模拟场景对答等开发场景。通过阅读源码可掌握从用户输入采集、对话状态流转到回应生成的整体流程包括行为树节点如何映射为对话选项、状态机如何管理等待/回应/思考状态、对话管理器如何组织话术库与当前上下文以及UI层如何绑定输入输出还可借鉴第三方NLP服务接入方式提升机器人对自然语言的理解能力。对于希望以低成本起步的开发者或团队这套源码提供了从零搭建对话功能的可参考范本便于快速迁移至自己的Unity项目。1. UnityAI与机器人对话功能源码跑起来之前先搞懂它要干什么拿到一个UnityAI与机器人对话功能源码.rar很多人的第一反应是解压后拖进 Unity结果要么报一堆命名空间错误要么找不到哪个场景是入口。其实这类源码包解决的问题非常集中在 Unity 里给机器人加一个能聊天的窗口把用户输入的文字发给 AI 服务再把返回内容显示出来。适合数字孪生、产品演示、游戏 NPC 互动这类场景也适合想接大模型的 Unity 开发者拿来当参考。这里不评论某个打包者的代码好坏而是讲清楚一个能用的对话功能要有哪几个模块、每层改哪里、参数怎么配以及最常见的失败点在哪里。2. 机器人对话功能在 Unity 里的架构拆开 UI、控制器与 AI 客户端2.1 三层结构为什么对话功能不能让 UI 直接请求网络很多 Unity 新手会直接把聊天逻辑写进 Button 的 onClick方法里创建 UnityWebRequest拿到结果再赋值给 Text。这在单次问答的测试场景里没问题但一接真实业务就崩用户连点发送会产生并发请求后返回的旧数据会覆盖新数据UI 状态没法回滚更没法做重试。所以我在自己项目里包括在帮人改这类源码包时都会先按三层结构重排一遍。第一层是 UI 层只负责显示。常见是一个 ScrollRect 作为消息列表底下挂 InputField 和发送按钮。第二层是对话控制器ChatManager持有会话历史、当前状态和 UI 引用。第三层是 AI 客户端它从控制器拿到消息数组做网络请求并返回文本。控制器不关心请求是发给 OpenAI 还是自己部署的模型只关心 AI 客户端是否成功返回一个字符串。using System; using System.Threading.Tasks; namespace RobotChat { [Serializable] public class ChatMessage { public string role; // 消息角色user / assistant / system public string content; // 消息文本内容 } public interface IAIClient { Taskstring GetReplyAsync(ChatMessage[] history, float temperature 0.7f); } }IAIClient接口定义在这里有实际意义你可以写一个OpenAIClient用 HTTPS 请求也可以写一个MockClient在开发阶段返回固定文本。ChatMessage 保持和主流大模型messages参数一致后续不用做字段映射。接口方法用了Taskstring而不是协程是为了让控制器能用await写顺序逻辑比如“先锁 UI再发请求成功解锁失败重试”。2.2 Unity 主线程与 AI 网络异步协程和 Async/Await 怎么选Unity 的引擎循环是单线程的网络回调不保证发生在主线程任何直接操作 UI 的代码都可能因为线程问题抛异常。老项目里最常见的是StartCoroutine包UnityWebRequest因为 unity 的协程机制会自动回到主线程继续执行写起来也短。但协程最大的问题是没有返回值你要把结果传给调用方就得塞回调委托代码一复杂就是回调地狱。方案返回值异常处理主线程切换适用场景StartCoroutine UnityWebRequest无try-catch 包整个迭代器自动回到主线程简单请求、快速验证async/await UnityWebRequest 扩展Task标准 try-catch需要确保上下文复杂业务、可测试性要求高HttpClient DllImport 等Task标准必须手动派发非 Unity 环境或服务端从 Unity 2020 开始官方在UnityWebRequest上提供了SendWebRequest()的ConfigureAwait扩展配合async/await完全可用。我一般会保留协程写法用于编辑器测试正式网络层用 async。下面是一个最小客户端实现很多源码包里的 AIClient 就是这个结构的变体using System.Threading.Tasks; using UnityEngine; using UnityEngine.Networking; public class OpenAIClient : IAIClient { private string apiUrl http://localhost:8000/v1/chat/completions; private string apiKey dev-key; public async Taskstring GetReplyAsync(ChatMessage[] history, float temperature) { string jsonBody {\model\:\gpt-4o-mini\,\messages\:[; // 构造 messages 数组 for (int i 0; i history.Length; i) { if (i 0) jsonBody ,; jsonBody {\role\:\ history[i].role \,\content\:\ history[i].content.Replace(\, \\\) \}; } jsonBody ],\temperature\: temperature.ToString(F1) }; using (UnityWebRequest req new UnityWebRequest(apiUrl, POST)) { byte[] bodyRaw System.Text.Encoding.UTF8.GetBytes(jsonBody); req.uploadHandler new UploadHandlerRaw(bodyRaw); req.downloadHandler new DownloadHandlerBuffer(); req.SetRequestHeader(Content-Type, application/json; charsetutf-8); if (!string.IsNullOrEmpty(apiKey)) req.SetRequestHeader(Authorization, Bearer apiKey); req.timeout 30; await req.SendWebRequest(); if (req.result ! UnityWebRequest.Result.Success) throw new System.Exception(AI 请求失败: req.error); return ParseResponse(req.downloadHandler.text); } } }这里有一个容易踩的坑new UnityWebRequest之后不能直接给downloadHandler赋值空对象必须用DownloadHandlerBuffer否则取不到任何数据。jsonBody用了最原始的字符串拼接是为了在源码里不引入额外依赖但如果消息里带换行这样的实现会崩。等到第 4.3 节我们再换成 JsonUtility 或 Newtonsoft.Json。有一点要记住temperature在请求体里要用英文句点比如0.7如果系统区域设置把逗号作为小数点C# 的ToString(F1)受当前 Culture 影响可能生成0,7后端会直接 400。所以更稳妥的写法是CultureInfo.InvariantCulture。2.3 会话状态机等待回复时用户又发了一句怎么办对话功能最常见的 bug 是用户连点发送。解决要靠状态机而不是靠把按钮的 Interactable 设为 false 那么简单因为程序化调用也会绕过按钮。用枚举做状态public enum ChatState { Ready, // 可以发送 WaitingReply,// 正在等待模型回复 Error // 上次请求失败 }控制器持有state字段在Send()方法开头查状态如果是 WaitingReply直接忽略如果是 Error重置会话中的最后一条占位消息再继续。等待期间除了按钮置灰还要在消息列表底部显示一个“对方正在输入…”的占位气泡。这个占位气泡本质是一行普通消息等结果回来后替换掉比单独 edit 一个 Text 更平滑。为了不让控制器持有太多 UI 引用建议把 UI 操作收口在一个ChatView类里。控制器只管业务比如“追加一条用户消息”“追加一条机器人消息”“清空错误状态”ChatView 负责具体改 ScrollRect 哪一个子节点。源码包里如果已经拆了这层你会看到 ChatManager 里的代码很干净如果没拆维护一会儿你就想自己动手了。3. 从 .rar 到 Unity 场景源码包的最小跑通链路3.1 解压与导入先看工程结构再动手拿到.rar文件后最忌讳直接右键解压到 Assets 目录。先把整个包解压到独立文件夹看它到底是完整 Unity 工程还是一个 Asset 包或者只是脚本集合。判断方法很简单看到Assets、ProjectSettings、Packages三个文件夹就是完整工程只有一个.unitypackage就需要通过Assets Import Package Custom Package导入如果只有Assets/Scripts和server.py就直接复制脚本和服务端代码。包结构导入方式坑完整工程目录用 Unity Hub 打开该目录你的 Unity 版本会重新构建 Library耗时几分钟.unitypackageImport Package 导入当前项目同名类会覆盖导入前用 git 提交一下纯 Assets 脚本按目录复制到 Assets 下文件名和类名必须一致否则 Mono 不识别源码 服务端分别处理服务端 Python 依赖需要 pip install 一遍如果是完整工程打开前先看ProjectSettings/ProjectVersion.txt。如果写的是2022.3.10f1你本机是2021.3可能会有一堆包管理器解析失败。遇到这种情况我会用 Unity Hub 多装一个 LTS 版本比折腾代码性价比高。要是版本差距太大脚本直接报#if编译错误那不是你的问题是包自带的宏没生效。导入完成后的第一步不是点 Play而是查依赖打开Window Package Manager看Newtonsoft Json是否在列表。很多对话源码包用JObject.Parse但不把com.unity.nuget.newtonsoft-json写在 manifest.json 里。如果你没有安装可以自己在 Package Manager 左上角加com.unity.nuget.newtonsoft-json。如果找不到说明你的 Unity 版本太老改用 Unity 自带的JsonUtility但要写更多的解析类。3.2 改哪个文件的哪个参数URL、密钥与模型名源码包里最核心的参数通常散落在AIClient.cs、ChatManager.cs、GameConfig文件里。我习惯先全局搜索https://或api.把所有网络地址揪出来。下面用一个ScriptableObject配置类把参数集中管理改造后你只需要在 Inspector 里改不用重新编译using UnityEngine; [CreateAssetMenu(fileName ChatConfig, menuName RobotChat/ChatConfig)] public class ChatConfig : ScriptableObject { [Header(AI 服务地址)] [Tooltip(部署到手机后不要用 localhost要填电脑的局域网 IP)] public string apiUrl http://localhost:8000/v1/chat/completions; [Tooltip(临时 token不要放正式 key)] public string apiKey ; [Tooltip(模型名需要后端支持透传)] public string modelName gpt-4o-mini; [Range(0f, 2f)] public float temperature 0.7f; public int timeout 30; }apiUrl是你自己的服务端地址不是大模型厂商地址。如果你不想搭服务端也可以直接填厂商的https://api.example.com/v1/chat/completions但这样密钥只能放客户端运行时会被人用抓包工具拿走。modelName写错不会报编译错误但后端会返回model_not_found而且信息很隐晦通常会让你以为是网络问题。temperature参数控制随机性0 到 2 之间对话客服场景我喜欢设 0.3闲聊 0.8太高容易跑题。参数改完后还要检查ChatManager有没有在Awake/Start里把自己和这个 config 绑定。常见源码包会在 Inspector 上留一个ChatConfig的槽位忘了拖引用运行就会NullReferenceException。看到这种空引用报错第一反应不是看堆栈而是去场景里找到 ChatManager把配置资产拖上去。3.3 一个最小后端用 Flask 转发大模型请求本地没有后端Unity 就不知道聊什么。最直接的方式是写一个 Flask 转发服务把客户端的请求转发给真实模型提供商。这样做的好处是密钥只在服务端出现Unity 端始终只连你的localhost。这段代码我不抄现成源码给出一个能直接跑的最小版本from flask import Flask, request, jsonify import requests import os app Flask(__name__) # 从环境变量读 key别写死在代码里 OPENAI_API_KEY os.getenv(OPENAI_API_KEY, sk-demo) OPENAI_URL os.getenv(OPENAI_URL, https://api.example.com/v1/chat/completions) app.route(/v1/chat/completions, methods[POST]) def proxy(): body request.get_json(forceTrue) payload { model: body.get(model, gpt-4o-mini), messages: body.get(messages, []), temperature: body.get(temperature, 0.7) } headers {Authorization: Bearer OPENAI_API_KEY} try: resp requests.post(OPENAI_URL, jsonpayload, headersheaders, timeout35) resp.raise_for_status() except requests.exceptions.RequestException as e: return jsonify({error: str(e)}), 502 return jsonify(resp.json()) if __name__ __main__: app.run(host0.0.0.0, port8000, debugFalse)需要说明的是requests库不是 Python 标准库要先执行pip install flask requests。forceTrue表示即使请求头不是标准 content-type 也尝试解析这样 Unity 端如果忘了设application/json也能收到 body排查时反而方便。timeout35比 Unity 端的 30 秒多 5 秒这样网络层超时是由 Unity 先触发不会出现服务端还挂着、客户端已经放弃导致连接池堆积的问题。最后确认连通性先在浏览器访问http://localhost:8000/v1/chat/completions看到 405 就说明服务端起来了。再用一个 Postman 或者 curl 构造请求确认返回结构是{choices:[{message:{content:...}}]}。这一步做通Unity 端的问题范围就缩小了。4. Unity 多轮对话与 UI 实战消息列表、等待状态与上下文管理4.1 动态生成消息行并滚动到底部大部分源码包会提供一个预制体ChatBubble.prefab但我发现直接拿来用时经常出现新消息不在视野内、ScrollRect 卡在顶部的情况。原因出在 Content 锚点上如果你把 Content 的 anchor 在 Y 轴设在 0底部Vertical Layout Group 会按从下往上的顺序排列当内容变多时所有子项会从 Content 的底部往下溢出而 ScrollRect 的视口固定在顶部于是你看到的列表一直是空白。正确做法是把Content的anchorMin/anchorMax都设为(0,1)pivot也设为(0,1)让子节点从顶部开始往下排。动态追加消息时还需要在 LayoutRebuilder 强制刷新后把 ScrollRect 滚到底部不然用户看不到新回复using UnityEngine; using UnityEngine.UI; public class ChatView : MonoBehaviour { public ScrollRect scrollRect; public RectTransform content; public void AddMessage(string message, bool isUser) { // 实例化消息行预制体并设置文本 GameObject row Instantiate(messageRowPrefab, content); row.GetComponentMessageRow().SetMessage(message, isUser); // 强制让 Content 重新计算高度 LayoutRebuilder.ForceRebuildLayoutImmediate(content); // 滚动到底部normalizedPosition 的 y 最小值对应底部 scrollRect.verticalNormalizedPosition 0f; } }ForceRebuildLayoutImmediate很贵不要在 Update 里刷只在消息进出、窗口大小变化时调用。如果消息气泡的宽度根据文字自适应还要确保消息行上的LayoutElement勾选了preferredWidth否则长文本会撑满整个 Content看起来像两个人在一边说话。生产环境里我一般会把滚动逻辑包一层协程延迟一帧再执行。因为ForceRebuildLayoutImmediate虽然立刻刷新了布局但 ScrollRect 在下一帧的 LateUpdate 里还会做一次位置修正直接设verticalNormalizedPosition会被覆盖。延迟一帧后设置反而稳定。4.2 多轮对话的上下文管理截断窗口和 token 配额对话功能如果只能一句一问那不叫机器人叫查询接口。多轮对话的关键是把历史消息随请求一起传递。但历史越大延迟越大费用越高。常见的做法是保留最近 8 轮再按 token 预算兜底。public ListChatMessage BuildContext(ListChatMessage history, int maxRounds 8, int maxChars 4000) { var ctx new ListChatMessage(); int total 0; for (int i history.Count - 1; i 0; i--) { // 预留系统提示词的空间 if (total history[i].content.Length maxChars) break; ctx.Insert(0, history[i]); total history[i].content.Length; if (ctx.Count maxRounds) break; } return ctx; }这个函数的逻辑是倒着遍历历史把消息一条条插入到列表头部直到达到轮数限制或者字符预算。ctx.Insert(0, ...)会有一点性能开销但消息量不大可读性好。需要注意maxChars和实际 token 不完全等价中文一个字符通常对应 0.6~0.7 个 token4~5 个汉字约等于 3 个 token。如果你用的是 OpenAI 的 gpt-4o-mini可以按 1000 汉字约 650 token 粗算。策略优点缺点推荐场景永远全量发上下文最全token 会爆延迟高短对话测试保留最近 N 轮简单稳定长单条消息仍可能超限多数 AI 客服、NPC字符预算 轮数双限更精确实现稍复杂生产环境、收费 API除了截断还要在每次成功响应后把 assistant 消息写入 history请求失败时用户那条已追加的消息其实也应该保留但要在 UI 上标记失败。等到用户下次输入时那条失败掉的 user 消息还留在上下文里AI 可能会误以为那是用户最新指令。常见的处理是失败后从历史中移除最后一次 user 输入UI 上也把最后那条消息气泡改回输入框的内容。4.3 中文乱码与 JSON 解析Unity 里的常见反例中文显示为乱码或者信息到客户端变成???根源几乎都出在编码。UnityWebRequest 的downloadHandler.text默认会用 UTF-8 解码但如果后端返回的响应头写的是ISO-8859-1Unity 会遵循头部导致中文乱码。解决方式是不看text直接读字节数组再手动 UTF-8 解码private string GetUtf8Text(DownloadHandler dh) { byte[] bytes dh.data; if (bytes null) return string.Empty; return System.Text.Encoding.UTF8.GetString(bytes); }关于 JSON 解析使用 Unity 内置的JsonUtility解析大模型返回会有很多限制。你可以定义一个 DTO[System.Serializable] public class ChatResponse { public Choice[] choices; } [System.Serializable] public class Choice { public Message message; }然后JsonUtility.FromJsonChatResponse(json)。但问题是很多 AI 服务返回的 JSON 字段名带下划线或首字母大写比如model没问题created_time就映射不上。遇到这种情况我建议直接用Newtonsoft.Json.Linq.JObject少写很多 DTO 类。解析大模型响应的核心目标是拿到choices[0].message.contentusing Newtonsoft.Json.Linq; public static string ExtractContent(string responseJson) { var root JObject.Parse(responseJson); JToken content root[choices]?[0]?[message]?[content]; return content?.ToString() ?? string.Empty; }这里每一层都用了?.空值传播任何一层缺失都不会抛空引用返回空字符串由业务层决定要不要提示重试。很多线上的对话 UI 崩溃就崩溃在choices节点缺失时暴力索引抛了异常。另外如果你的文本里带换行显示时尽量把 UGUI Text 的RichText关掉否则\n会被当成富文本标签的一部分处理。提示如果服务端返回的 JSON 是数组结构JsonUtility 需要包一层{ data: [...] }才能反序列化换成 Newtonsoft.Json 后没有这个问题。5. Unity AI 对话功能上线前必调的 5 个参数和 3 个深坑5.1 热参数速查表根据前面第 3、4 章的讨论上线前的参数基本集中在这几个位置参数推荐值说明request.timeout30~60低于 15 秒时大模型长回复容易被误杀temperature客服 0.3 / 闲聊 0.8值为 0 时模型容易反复说同一句话maxRounds6~10每轮按 2 条消息算通常不会超过上下文长度maxChars4000 左右超过这个值可以提前截断避免 token 超限请求重试次数2~3 次指数退避重试多了会让 UI 卡在 waiting 状态改这四个参数时建议在 ChatConfig 里面加一条自定义日志字段把每次请求的 model、temperature、消息轮数打出来。用Debug.Log打印序列化后的 JSON能省掉一半后端联调时间。5.2 三个深坑WebGL 跨域、安卓明文 HTTP 和密钥泄漏第一WebGL 发布时Unity 使用浏览器里的 HTTP 请求会受同源策略限制。你的 Flask 服务必须开启 CORS。在 Flask 里加一行简单配置from flask_cors import CORS CORS(app, resources{r/v1/*: {origins: *}})第二Android 9 开始默认禁止明文流量。如果你只是本地联调在 AndroidManifest.xml 的application节点加android:usesCleartextTraffictrue。注意这么做有安全风险正式包建议用 HTTPS。第三也是最后一点不要把apiKey放在Config.cs的常量里并勾选Debug.Log打印。APK 用反编译工具一拉就能看到。常见做法是把 key 放到你自己的服务端Unity 端只拿短期 token。如果你只是个人项目至少把 key 放到一个不被跟踪的文件里。如果遇到“Unity 请求成功但返回空字符串”先检查是不是后端返回的 content 字段叫text而不是message.content用一个临时 JSON Viewer 确认字段名。如果遇到“偶发超时”先看 Flask 日志里的响应耗时大厂接口首字延迟高超过 30 秒属于正常现象不是你的代码问题。本文还有配套的精品资源点击获取
Unity AI机器人对话功能源码解析：架构、异步与多轮对话实战
简介面向Unity开发者的AI对话机器人源码包围绕行为树、状态机、C#脚本、对话管理器与UI交互等模块展开适合希望为游戏或虚拟体验引入智能对话系统的中高级开发者。压缩包约60.17MB文件数量与具体类型暂未标注但此类源码包通常包含可直接运行的Unity工程、核心C#脚本及演示场景。目前已有1647人学习下载常用于NPC互动、任务引导与模拟场景对答等开发场景。通过阅读源码可掌握从用户输入采集、对话状态流转到回应生成的整体流程包括行为树节点如何映射为对话选项、状态机如何管理等待/回应/思考状态、对话管理器如何组织话术库与当前上下文以及UI层如何绑定输入输出还可借鉴第三方NLP服务接入方式提升机器人对自然语言的理解能力。对于希望以低成本起步的开发者或团队这套源码提供了从零搭建对话功能的可参考范本便于快速迁移至自己的Unity项目。1. UnityAI与机器人对话功能源码跑起来之前先搞懂它要干什么拿到一个UnityAI与机器人对话功能源码.rar很多人的第一反应是解压后拖进 Unity结果要么报一堆命名空间错误要么找不到哪个场景是入口。其实这类源码包解决的问题非常集中在 Unity 里给机器人加一个能聊天的窗口把用户输入的文字发给 AI 服务再把返回内容显示出来。适合数字孪生、产品演示、游戏 NPC 互动这类场景也适合想接大模型的 Unity 开发者拿来当参考。这里不评论某个打包者的代码好坏而是讲清楚一个能用的对话功能要有哪几个模块、每层改哪里、参数怎么配以及最常见的失败点在哪里。2. 机器人对话功能在 Unity 里的架构拆开 UI、控制器与 AI 客户端2.1 三层结构为什么对话功能不能让 UI 直接请求网络很多 Unity 新手会直接把聊天逻辑写进 Button 的 onClick方法里创建 UnityWebRequest拿到结果再赋值给 Text。这在单次问答的测试场景里没问题但一接真实业务就崩用户连点发送会产生并发请求后返回的旧数据会覆盖新数据UI 状态没法回滚更没法做重试。所以我在自己项目里包括在帮人改这类源码包时都会先按三层结构重排一遍。第一层是 UI 层只负责显示。常见是一个 ScrollRect 作为消息列表底下挂 InputField 和发送按钮。第二层是对话控制器ChatManager持有会话历史、当前状态和 UI 引用。第三层是 AI 客户端它从控制器拿到消息数组做网络请求并返回文本。控制器不关心请求是发给 OpenAI 还是自己部署的模型只关心 AI 客户端是否成功返回一个字符串。using System; using System.Threading.Tasks; namespace RobotChat { [Serializable] public class ChatMessage { public string role; // 消息角色user / assistant / system public string content; // 消息文本内容 } public interface IAIClient { Taskstring GetReplyAsync(ChatMessage[] history, float temperature 0.7f); } }IAIClient接口定义在这里有实际意义你可以写一个OpenAIClient用 HTTPS 请求也可以写一个MockClient在开发阶段返回固定文本。ChatMessage 保持和主流大模型messages参数一致后续不用做字段映射。接口方法用了Taskstring而不是协程是为了让控制器能用await写顺序逻辑比如“先锁 UI再发请求成功解锁失败重试”。2.2 Unity 主线程与 AI 网络异步协程和 Async/Await 怎么选Unity 的引擎循环是单线程的网络回调不保证发生在主线程任何直接操作 UI 的代码都可能因为线程问题抛异常。老项目里最常见的是StartCoroutine包UnityWebRequest因为 unity 的协程机制会自动回到主线程继续执行写起来也短。但协程最大的问题是没有返回值你要把结果传给调用方就得塞回调委托代码一复杂就是回调地狱。方案返回值异常处理主线程切换适用场景StartCoroutine UnityWebRequest无try-catch 包整个迭代器自动回到主线程简单请求、快速验证async/await UnityWebRequest 扩展Task标准 try-catch需要确保上下文复杂业务、可测试性要求高HttpClient DllImport 等Task标准必须手动派发非 Unity 环境或服务端从 Unity 2020 开始官方在UnityWebRequest上提供了SendWebRequest()的ConfigureAwait扩展配合async/await完全可用。我一般会保留协程写法用于编辑器测试正式网络层用 async。下面是一个最小客户端实现很多源码包里的 AIClient 就是这个结构的变体using System.Threading.Tasks; using UnityEngine; using UnityEngine.Networking; public class OpenAIClient : IAIClient { private string apiUrl http://localhost:8000/v1/chat/completions; private string apiKey dev-key; public async Taskstring GetReplyAsync(ChatMessage[] history, float temperature) { string jsonBody {\model\:\gpt-4o-mini\,\messages\:[; // 构造 messages 数组 for (int i 0; i history.Length; i) { if (i 0) jsonBody ,; jsonBody {\role\:\ history[i].role \,\content\:\ history[i].content.Replace(\, \\\) \}; } jsonBody ],\temperature\: temperature.ToString(F1) }; using (UnityWebRequest req new UnityWebRequest(apiUrl, POST)) { byte[] bodyRaw System.Text.Encoding.UTF8.GetBytes(jsonBody); req.uploadHandler new UploadHandlerRaw(bodyRaw); req.downloadHandler new DownloadHandlerBuffer(); req.SetRequestHeader(Content-Type, application/json; charsetutf-8); if (!string.IsNullOrEmpty(apiKey)) req.SetRequestHeader(Authorization, Bearer apiKey); req.timeout 30; await req.SendWebRequest(); if (req.result ! UnityWebRequest.Result.Success) throw new System.Exception(AI 请求失败: req.error); return ParseResponse(req.downloadHandler.text); } } }这里有一个容易踩的坑new UnityWebRequest之后不能直接给downloadHandler赋值空对象必须用DownloadHandlerBuffer否则取不到任何数据。jsonBody用了最原始的字符串拼接是为了在源码里不引入额外依赖但如果消息里带换行这样的实现会崩。等到第 4.3 节我们再换成 JsonUtility 或 Newtonsoft.Json。有一点要记住temperature在请求体里要用英文句点比如0.7如果系统区域设置把逗号作为小数点C# 的ToString(F1)受当前 Culture 影响可能生成0,7后端会直接 400。所以更稳妥的写法是CultureInfo.InvariantCulture。2.3 会话状态机等待回复时用户又发了一句怎么办对话功能最常见的 bug 是用户连点发送。解决要靠状态机而不是靠把按钮的 Interactable 设为 false 那么简单因为程序化调用也会绕过按钮。用枚举做状态public enum ChatState { Ready, // 可以发送 WaitingReply,// 正在等待模型回复 Error // 上次请求失败 }控制器持有state字段在Send()方法开头查状态如果是 WaitingReply直接忽略如果是 Error重置会话中的最后一条占位消息再继续。等待期间除了按钮置灰还要在消息列表底部显示一个“对方正在输入…”的占位气泡。这个占位气泡本质是一行普通消息等结果回来后替换掉比单独 edit 一个 Text 更平滑。为了不让控制器持有太多 UI 引用建议把 UI 操作收口在一个ChatView类里。控制器只管业务比如“追加一条用户消息”“追加一条机器人消息”“清空错误状态”ChatView 负责具体改 ScrollRect 哪一个子节点。源码包里如果已经拆了这层你会看到 ChatManager 里的代码很干净如果没拆维护一会儿你就想自己动手了。3. 从 .rar 到 Unity 场景源码包的最小跑通链路3.1 解压与导入先看工程结构再动手拿到.rar文件后最忌讳直接右键解压到 Assets 目录。先把整个包解压到独立文件夹看它到底是完整 Unity 工程还是一个 Asset 包或者只是脚本集合。判断方法很简单看到Assets、ProjectSettings、Packages三个文件夹就是完整工程只有一个.unitypackage就需要通过Assets Import Package Custom Package导入如果只有Assets/Scripts和server.py就直接复制脚本和服务端代码。包结构导入方式坑完整工程目录用 Unity Hub 打开该目录你的 Unity 版本会重新构建 Library耗时几分钟.unitypackageImport Package 导入当前项目同名类会覆盖导入前用 git 提交一下纯 Assets 脚本按目录复制到 Assets 下文件名和类名必须一致否则 Mono 不识别源码 服务端分别处理服务端 Python 依赖需要 pip install 一遍如果是完整工程打开前先看ProjectSettings/ProjectVersion.txt。如果写的是2022.3.10f1你本机是2021.3可能会有一堆包管理器解析失败。遇到这种情况我会用 Unity Hub 多装一个 LTS 版本比折腾代码性价比高。要是版本差距太大脚本直接报#if编译错误那不是你的问题是包自带的宏没生效。导入完成后的第一步不是点 Play而是查依赖打开Window Package Manager看Newtonsoft Json是否在列表。很多对话源码包用JObject.Parse但不把com.unity.nuget.newtonsoft-json写在 manifest.json 里。如果你没有安装可以自己在 Package Manager 左上角加com.unity.nuget.newtonsoft-json。如果找不到说明你的 Unity 版本太老改用 Unity 自带的JsonUtility但要写更多的解析类。3.2 改哪个文件的哪个参数URL、密钥与模型名源码包里最核心的参数通常散落在AIClient.cs、ChatManager.cs、GameConfig文件里。我习惯先全局搜索https://或api.把所有网络地址揪出来。下面用一个ScriptableObject配置类把参数集中管理改造后你只需要在 Inspector 里改不用重新编译using UnityEngine; [CreateAssetMenu(fileName ChatConfig, menuName RobotChat/ChatConfig)] public class ChatConfig : ScriptableObject { [Header(AI 服务地址)] [Tooltip(部署到手机后不要用 localhost要填电脑的局域网 IP)] public string apiUrl http://localhost:8000/v1/chat/completions; [Tooltip(临时 token不要放正式 key)] public string apiKey ; [Tooltip(模型名需要后端支持透传)] public string modelName gpt-4o-mini; [Range(0f, 2f)] public float temperature 0.7f; public int timeout 30; }apiUrl是你自己的服务端地址不是大模型厂商地址。如果你不想搭服务端也可以直接填厂商的https://api.example.com/v1/chat/completions但这样密钥只能放客户端运行时会被人用抓包工具拿走。modelName写错不会报编译错误但后端会返回model_not_found而且信息很隐晦通常会让你以为是网络问题。temperature参数控制随机性0 到 2 之间对话客服场景我喜欢设 0.3闲聊 0.8太高容易跑题。参数改完后还要检查ChatManager有没有在Awake/Start里把自己和这个 config 绑定。常见源码包会在 Inspector 上留一个ChatConfig的槽位忘了拖引用运行就会NullReferenceException。看到这种空引用报错第一反应不是看堆栈而是去场景里找到 ChatManager把配置资产拖上去。3.3 一个最小后端用 Flask 转发大模型请求本地没有后端Unity 就不知道聊什么。最直接的方式是写一个 Flask 转发服务把客户端的请求转发给真实模型提供商。这样做的好处是密钥只在服务端出现Unity 端始终只连你的localhost。这段代码我不抄现成源码给出一个能直接跑的最小版本from flask import Flask, request, jsonify import requests import os app Flask(__name__) # 从环境变量读 key别写死在代码里 OPENAI_API_KEY os.getenv(OPENAI_API_KEY, sk-demo) OPENAI_URL os.getenv(OPENAI_URL, https://api.example.com/v1/chat/completions) app.route(/v1/chat/completions, methods[POST]) def proxy(): body request.get_json(forceTrue) payload { model: body.get(model, gpt-4o-mini), messages: body.get(messages, []), temperature: body.get(temperature, 0.7) } headers {Authorization: Bearer OPENAI_API_KEY} try: resp requests.post(OPENAI_URL, jsonpayload, headersheaders, timeout35) resp.raise_for_status() except requests.exceptions.RequestException as e: return jsonify({error: str(e)}), 502 return jsonify(resp.json()) if __name__ __main__: app.run(host0.0.0.0, port8000, debugFalse)需要说明的是requests库不是 Python 标准库要先执行pip install flask requests。forceTrue表示即使请求头不是标准 content-type 也尝试解析这样 Unity 端如果忘了设application/json也能收到 body排查时反而方便。timeout35比 Unity 端的 30 秒多 5 秒这样网络层超时是由 Unity 先触发不会出现服务端还挂着、客户端已经放弃导致连接池堆积的问题。最后确认连通性先在浏览器访问http://localhost:8000/v1/chat/completions看到 405 就说明服务端起来了。再用一个 Postman 或者 curl 构造请求确认返回结构是{choices:[{message:{content:...}}]}。这一步做通Unity 端的问题范围就缩小了。4. Unity 多轮对话与 UI 实战消息列表、等待状态与上下文管理4.1 动态生成消息行并滚动到底部大部分源码包会提供一个预制体ChatBubble.prefab但我发现直接拿来用时经常出现新消息不在视野内、ScrollRect 卡在顶部的情况。原因出在 Content 锚点上如果你把 Content 的 anchor 在 Y 轴设在 0底部Vertical Layout Group 会按从下往上的顺序排列当内容变多时所有子项会从 Content 的底部往下溢出而 ScrollRect 的视口固定在顶部于是你看到的列表一直是空白。正确做法是把Content的anchorMin/anchorMax都设为(0,1)pivot也设为(0,1)让子节点从顶部开始往下排。动态追加消息时还需要在 LayoutRebuilder 强制刷新后把 ScrollRect 滚到底部不然用户看不到新回复using UnityEngine; using UnityEngine.UI; public class ChatView : MonoBehaviour { public ScrollRect scrollRect; public RectTransform content; public void AddMessage(string message, bool isUser) { // 实例化消息行预制体并设置文本 GameObject row Instantiate(messageRowPrefab, content); row.GetComponentMessageRow().SetMessage(message, isUser); // 强制让 Content 重新计算高度 LayoutRebuilder.ForceRebuildLayoutImmediate(content); // 滚动到底部normalizedPosition 的 y 最小值对应底部 scrollRect.verticalNormalizedPosition 0f; } }ForceRebuildLayoutImmediate很贵不要在 Update 里刷只在消息进出、窗口大小变化时调用。如果消息气泡的宽度根据文字自适应还要确保消息行上的LayoutElement勾选了preferredWidth否则长文本会撑满整个 Content看起来像两个人在一边说话。生产环境里我一般会把滚动逻辑包一层协程延迟一帧再执行。因为ForceRebuildLayoutImmediate虽然立刻刷新了布局但 ScrollRect 在下一帧的 LateUpdate 里还会做一次位置修正直接设verticalNormalizedPosition会被覆盖。延迟一帧后设置反而稳定。4.2 多轮对话的上下文管理截断窗口和 token 配额对话功能如果只能一句一问那不叫机器人叫查询接口。多轮对话的关键是把历史消息随请求一起传递。但历史越大延迟越大费用越高。常见的做法是保留最近 8 轮再按 token 预算兜底。public ListChatMessage BuildContext(ListChatMessage history, int maxRounds 8, int maxChars 4000) { var ctx new ListChatMessage(); int total 0; for (int i history.Count - 1; i 0; i--) { // 预留系统提示词的空间 if (total history[i].content.Length maxChars) break; ctx.Insert(0, history[i]); total history[i].content.Length; if (ctx.Count maxRounds) break; } return ctx; }这个函数的逻辑是倒着遍历历史把消息一条条插入到列表头部直到达到轮数限制或者字符预算。ctx.Insert(0, ...)会有一点性能开销但消息量不大可读性好。需要注意maxChars和实际 token 不完全等价中文一个字符通常对应 0.6~0.7 个 token4~5 个汉字约等于 3 个 token。如果你用的是 OpenAI 的 gpt-4o-mini可以按 1000 汉字约 650 token 粗算。策略优点缺点推荐场景永远全量发上下文最全token 会爆延迟高短对话测试保留最近 N 轮简单稳定长单条消息仍可能超限多数 AI 客服、NPC字符预算 轮数双限更精确实现稍复杂生产环境、收费 API除了截断还要在每次成功响应后把 assistant 消息写入 history请求失败时用户那条已追加的消息其实也应该保留但要在 UI 上标记失败。等到用户下次输入时那条失败掉的 user 消息还留在上下文里AI 可能会误以为那是用户最新指令。常见的处理是失败后从历史中移除最后一次 user 输入UI 上也把最后那条消息气泡改回输入框的内容。4.3 中文乱码与 JSON 解析Unity 里的常见反例中文显示为乱码或者信息到客户端变成???根源几乎都出在编码。UnityWebRequest 的downloadHandler.text默认会用 UTF-8 解码但如果后端返回的响应头写的是ISO-8859-1Unity 会遵循头部导致中文乱码。解决方式是不看text直接读字节数组再手动 UTF-8 解码private string GetUtf8Text(DownloadHandler dh) { byte[] bytes dh.data; if (bytes null) return string.Empty; return System.Text.Encoding.UTF8.GetString(bytes); }关于 JSON 解析使用 Unity 内置的JsonUtility解析大模型返回会有很多限制。你可以定义一个 DTO[System.Serializable] public class ChatResponse { public Choice[] choices; } [System.Serializable] public class Choice { public Message message; }然后JsonUtility.FromJsonChatResponse(json)。但问题是很多 AI 服务返回的 JSON 字段名带下划线或首字母大写比如model没问题created_time就映射不上。遇到这种情况我建议直接用Newtonsoft.Json.Linq.JObject少写很多 DTO 类。解析大模型响应的核心目标是拿到choices[0].message.contentusing Newtonsoft.Json.Linq; public static string ExtractContent(string responseJson) { var root JObject.Parse(responseJson); JToken content root[choices]?[0]?[message]?[content]; return content?.ToString() ?? string.Empty; }这里每一层都用了?.空值传播任何一层缺失都不会抛空引用返回空字符串由业务层决定要不要提示重试。很多线上的对话 UI 崩溃就崩溃在choices节点缺失时暴力索引抛了异常。另外如果你的文本里带换行显示时尽量把 UGUI Text 的RichText关掉否则\n会被当成富文本标签的一部分处理。提示如果服务端返回的 JSON 是数组结构JsonUtility 需要包一层{ data: [...] }才能反序列化换成 Newtonsoft.Json 后没有这个问题。5. Unity AI 对话功能上线前必调的 5 个参数和 3 个深坑5.1 热参数速查表根据前面第 3、4 章的讨论上线前的参数基本集中在这几个位置参数推荐值说明request.timeout30~60低于 15 秒时大模型长回复容易被误杀temperature客服 0.3 / 闲聊 0.8值为 0 时模型容易反复说同一句话maxRounds6~10每轮按 2 条消息算通常不会超过上下文长度maxChars4000 左右超过这个值可以提前截断避免 token 超限请求重试次数2~3 次指数退避重试多了会让 UI 卡在 waiting 状态改这四个参数时建议在 ChatConfig 里面加一条自定义日志字段把每次请求的 model、temperature、消息轮数打出来。用Debug.Log打印序列化后的 JSON能省掉一半后端联调时间。5.2 三个深坑WebGL 跨域、安卓明文 HTTP 和密钥泄漏第一WebGL 发布时Unity 使用浏览器里的 HTTP 请求会受同源策略限制。你的 Flask 服务必须开启 CORS。在 Flask 里加一行简单配置from flask_cors import CORS CORS(app, resources{r/v1/*: {origins: *}})第二Android 9 开始默认禁止明文流量。如果你只是本地联调在 AndroidManifest.xml 的application节点加android:usesCleartextTraffictrue。注意这么做有安全风险正式包建议用 HTTPS。第三也是最后一点不要把apiKey放在Config.cs的常量里并勾选Debug.Log打印。APK 用反编译工具一拉就能看到。常见做法是把 key 放到你自己的服务端Unity 端只拿短期 token。如果你只是个人项目至少把 key 放到一个不被跟踪的文件里。如果遇到“Unity 请求成功但返回空字符串”先检查是不是后端返回的 content 字段叫text而不是message.content用一个临时 JSON Viewer 确认字段名。如果遇到“偶发超时”先看 Flask 日志里的响应耗时大厂接口首字延迟高超过 30 秒属于正常现象不是你的代码问题。本文还有配套的精品资源点击获取
