简介这份PDF文档面向具备一定Unity开发经验与C#编程基础的技术人员系统讲解如何在Unity引擎中集成DeepSeek API实现跨平台的智能交互功能。内容从DeepSeek API的注册、密钥获取与RESTful调用原理讲起逐步深入到C#调用类的封装、请求构建、异步发送与响应解析并覆盖不同操作系统的兼容性处理、网络与性能优化、错误捕获与重试机制、Unity Profiler性能测试等实战环节最后通过智能对话游戏、智能教学辅助等案例展示落地场景。资源共1个PDF文件压缩包约1.83MB文档共25页目录与图表显示完整条理清晰便于按章节查阅。目前已有56人学习适合希望为Unity项目添加大模型能力、或对跨平台调用与AI集成感兴趣的开发者参考。1. 跨平台调用方案在Unity中集成DeepSeekAPI的C#实现详解很多团队在 Unity 里做 AI 对话功能时第一反应是找个现成的插件结果发现要么只支持某一家模型要么在 Android 上直接翻车。跨平台调用方案的核心诉求其实很朴素同一套 C# 代码在 Windows 编辑器里能跑打包到 Android、iOS、WebGL 之后还能跑而且不用为每个平台维护一份网络层。DeepSeekAPI 提供的是标准 HTTP 接口这意味着 Unity 里真正要解决的问题不是“怎么调模型”而是“怎么用 UnityWebRequest 或 HttpClient 把请求发出去、把流式响应接回来、把平台差异吃掉”。这篇内容面向的是已经在 Unity 里写过 C# 脚本、准备把大模型能力接进游戏或工具的中级开发者也适合做 C# 上位机、想复用同一套网络层逻辑的工程师。下面从接口形态讲到最小可跑实现再到流式输出和平台坑位每一步都给出可抄的代码和参数说明。2. DeepSeekAPI 的接口形态与 Unity 侧选型为什么不是随便发个 POST2.1 接口本质OpenAI 兼容的 Chat CompletionsDeepSeekAPI 对外暴露的是 OpenAI 兼容的/chat/completions接口请求体是 JSON鉴权走Authorization: Bearer API_KEY请求头。这意味着你在 Unity 里不需要引入任何厂商专属 SDK只要会发 HTTP POST 就能调通。请求体里最关键的几个字段是model、messages、stream、temperature、max_tokens。messages是一个数组每个元素包含role和contentrole取system、user、assistant三种。stream设为true时服务端会以 SSEServer-Sent Events形式逐块返回这对游戏里的打字机效果是刚需。常见做法是把请求体封装成一个 C# 类用JsonUtility或Newtonsoft.Json序列化。这里有个容易忽略的点JsonUtility不支持字典和顶层数组而messages是数组所以要么用Newtonsoft.Json要么手写一个可序列化的包装类。我一般会直接上Newtonsoft.Json因为流式解析时它处理不完整 JSON 片段更稳。2.2 Unity 侧网络层选型UnityWebRequest 还是 HttpClientUnity 里发 HTTP 请求有两条路。UnityWebRequest是 Unity 官方封装跨平台兼容性最好WebGL 平台只能用这个因为 WebGL 不允许直接开 Socket。HttpClient是 .NET 原生API 更顺手支持HttpCompletionOption.ResponseHeadersRead做流式读取但在 WebGL 上不可用iOS 上还要注意 AOT 裁剪问题。选型建议按目标平台分如果项目要出 WebGL网络层必须走UnityWebRequest流式响应得用DownloadHandlerScript自己攒缓冲区如果只出 PC 和移动端HttpClient更省心流式读取用ReadAsStreamAsync配合StreamReader.ReadLineAsync就能逐行拿 SSE 数据。我一般会写一个IDeepSeekClient接口底下两个实现运行时按Application.platform切换。这样编辑器里用HttpClient调试方便打包 WebGL 时自动切到UnityWebRequest。2.3 最小可跑请求先别碰流式把非流式调通在写流式之前先用非流式请求确认 API Key、网络、JSON 序列化三件事都对。下面这段代码用UnityWebRequest发一个最简单的请求返回完整 JSON 后解析出choices[0].message.content。using System.Collections; using System.Text; using Newtonsoft.Json; using Newtonsoft.Json.Linq; using UnityEngine; using UnityEngine.Networking; public class DeepSeekMinimal : MonoBehaviour { // 注意API Key 不要硬编码进正式包这里仅为演示 private const string ApiUrl https://api.deepseek.com/chat/completions; private const string ApiKey sk-你的Key; [System.Serializable] public class Message { public string role; public string content; } [System.Serializable] public class RequestBody { public string model deepseek-chat; public Message[] messages; public bool stream false; public float temperature 0.7f; public int max_tokens 512; } void Start() { StartCoroutine(SendOnce(用一句话解释什么是协程)); } IEnumerator SendOnce(string userInput) { var body new RequestBody { messages new[] { new Message { role system, content 你是一个简洁的助手 }, new Message { role user, content userInput } } }; string json JsonConvert.SerializeObject(body); byte[] raw Encoding.UTF8.GetBytes(json); using var req new UnityWebRequest(ApiUrl, POST); req.uploadHandler new UploadHandlerRaw(raw); req.downloadHandler new DownloadHandlerBuffer(); req.SetRequestHeader(Content-Type, application/json); req.SetRequestHeader(Authorization, Bearer ApiKey); yield return req.SendWebRequest(); if (req.result ! UnityWebRequest.Result.Success) { Debug.LogError($请求失败: {req.responseCode} {req.error}\n{req.downloadHandler.text}); yield break; } var parsed JObject.Parse(req.downloadHandler.text); string reply parsed[choices]?[0]?[message]?[content]?.ToString(); Debug.Log(回复: reply); } }这段代码里RequestBody的字段名必须和接口文档一致model写deepseek-chat走通用对话模型。temperature控制随机性0 到 2 之间写代码场景建议 0.2 到 0.5创意场景可以到 1.0 以上。max_tokens限制回复长度设太小会被截断设太大在移动端会拉长等待时间。UploadHandlerRaw负责把 UTF-8 字节流塞进请求体DownloadHandlerBuffer把响应完整缓存在内存里。失败时一定要把req.downloadHandler.text打出来401 是 Key 错429 是限流400 多半是 JSON 字段拼错。3. 流式输出与打字机效果把 SSE 数据一块块喂给 UI3.1 SSE 的数据格式与解析边界流式模式下服务端返回的每一行形如data: {choices:[{delta:{content:你}}]}最后以data: [DONE]结束。关键点是一个 TCP 包不等于一行 SSE一行 SSE 也不等于一个完整 JSON。你必须自己维护一个字符串缓冲区按\n切分对每个以data:开头的片段单独解析遇到[DONE]就停止。如果直接对每个网络回调做JObject.Parse迟早会遇到“JSON 不完整”的异常这是流式解析最常见的翻车点。3.2 用 HttpClient 做流式读取的完整实现PC 和移动端推荐用HttpClient因为ReadAsStreamAsync能真正逐行读不用等整个响应体下载完。下面这段代码把 SSE 行解析成delta.content并通过回调吐给 UI。using System; using System.IO; using System.Net.Http; using System.Text; using System.Threading; using System.Threading.Tasks; using Newtonsoft.Json.Linq; public class DeepSeekStreamClient { private static readonly HttpClient Http new HttpClient(); // onDelta: 每收到一小段文本就回调一次用于打字机效果 // onDone: 流结束回调 public static async Task StreamChatAsync( string apiKey, string userInput, Actionstring onDelta, Action onDone, CancellationToken token default) { var payload new { model deepseek-chat, stream true, temperature 0.7, messages new object[] { new { role system, content 你是一个简洁的助手 }, new { role user, content userInput } } }; string json Newtonsoft.Json.JsonConvert.SerializeObject(payload); using var req new HttpRequestMessage(HttpMethod.Post, https://api.deepseek.com/chat/completions); req.Headers.Add(Authorization, Bearer apiKey); req.Content new StringContent(json, Encoding.UTF8, application/json); using var resp await Http.SendAsync(req, HttpCompletionOption.ResponseHeadersRead, token); resp.EnsureSuccessStatusCode(); using var stream await resp.Content.ReadAsStreamAsync(); using var reader new StreamReader(stream, Encoding.UTF8); var buffer new StringBuilder(); while (!reader.EndOfStream !token.IsCancellationRequested) { string line await reader.ReadLineAsync(); if (string.IsNullOrEmpty(line)) continue; // SSE 行以 data: 开头 if (!line.StartsWith(data: )) continue; string data line.Substring(6).Trim(); if (data [DONE]) { onDone?.Invoke(); yield break; // 注意此处为示意实际用 return } // 单行可能不是完整 JSON用 try 兜住 try { var obj JObject.Parse(data); string delta obj[choices]?[0]?[delta]?[content]?.ToString(); if (!string.IsNullOrEmpty(delta)) { buffer.Append(delta); onDelta?.Invoke(delta); } } catch (Newtonsoft.Json.JsonException) { // 不完整片段跳过等下一行 } } onDone?.Invoke(); } }上面代码里HttpCompletionOption.ResponseHeadersRead是关键参数它让SendAsync在收到响应头后就返回而不是等整个 body 下载完这是流式的前提。ReadLineAsync按行读SSE 协议保证每行以\n结尾。data:前缀长度是 6截取后Trim掉首尾空白。[DONE]是结束标记收到后必须停止读取否则会一直阻塞。try-catch包住JObject.Parse是因为极少数情况下服务端会把一个 JSON 拆到两行虽然不常见但线上跑久了总会遇到这就是血泪经验。3.3 在 Unity 主线程里安全更新 UIHttpClient的回调在线程池线程上执行而 Unity 的 UI 组件只能在主线程操作。直接onDelta里改Text.text会抛UnityException。常见做法是用一个线程安全队列把 delta 存起来在Update里出队并刷新 UI。using System.Collections.Concurrent; using UnityEngine; using UnityEngine.UI; public class ChatUI : MonoBehaviour { public Text outputText; private readonly ConcurrentQueuestring _pending new ConcurrentQueuestring(); private System.Text.StringBuilder _full new System.Text.StringBuilder(); void Update() { bool dirty false; while (_pending.TryDequeue(out string piece)) { _full.Append(piece); dirty true; } if (dirty) outputText.text _full.ToString(); } public void OnDelta(string piece) _pending.Enqueue(piece); }ConcurrentQueue是 .NET 标准库里的线程安全队列入队和出队不需要额外加锁。Update每帧最多把队列清空一次避免频繁触发 UI 重建。如果文本很长建议用TMP_Text的SetText并配合maxVisibleCharacters做逐字显示而不是每帧拼字符串否则 GC 压力会很明显。4. 跨平台避坑与常见问题排查4.1 Android 上请求直接失败报“Cleartext HTTP traffic not permitted”现象编辑器里跑得好好的打包到 Android 真机后请求全部失败日志里出现 cleartext 相关提示。原因Android 9 以后默认禁止明文 HTTP虽然 DeepSeekAPI 是 HTTPS但如果你的项目里还有别的 HTTP 请求或者 Unity 某些版本对 TLS 处理有差异就会触发。解决确认请求地址是https://并在AndroidManifest.xml里显式声明android:usesCleartextTrafficfalse同时检查 Player Settings 里Internet Access设为Require。如果还是失败把req.error和req.responseCode都打出来区分是网络层还是应用层。4.2 iOS 上 AOT 裁剪导致 Newtonsoft.Json 反射失败现象iOS 包运行到解析 JSON 时抛ExecutionEngineException或字段全为 null。原因IL2CPP 的 AOT 裁剪会把没有被静态引用的类型和属性裁掉而Newtonsoft.Json依赖反射。解决在link.xml里保留Newtonsoft.Json相关程序集或者改用UnityWebRequest配合JsonUtility做非流式解析。如果必须用Newtonsoft.Json把link.xml放到Assets根目录内容如下。linker assembly fullnameNewtonsoft.Json type fullname* preserveall/ /assembly /linker4.3 WebGL 平台无法使用 HttpClient 和线程现象WebGL 打包后编译报错提示System.Net.Http不可用或者运行时卡死。原因WebGL 是单线程模型不支持多线程和 SocketHttpClient底层依赖的SocketsHttpHandler在 WebGL 上不可用。解决网络层切到UnityWebRequest流式响应用DownloadHandlerScript继承类在ReceiveData回调里攒缓冲区解析 SSE。注意 WebGL 下UnityWebRequest也是异步的但回调在主线程不需要额外做线程调度。4.4 API Key 泄露与请求被限流现象打包后的包被反编译API Key 明文可见或者短时间内大量请求返回 429。原因把 Key 硬编码进客户端是常见错误客户端代码对用户完全透明。解决正式项目里 Key 必须放在自建后端客户端只调自己的后端由后端转发到 DeepSeekAPI 并做鉴权和限流。如果只是内部工具至少把 Key 存在StreamingAssets之外的地方并做简单混淆但这不是安全方案只是提高门槛。429 限流则需要在客户端做指数退避重试第一次等 1 秒第二次 2 秒第三次 4 秒最多重试三次。4.5 流式响应中文乱码或截断现象打字机效果里中文显示成问号或者一段话中间少几个字。原因StreamReader的编码没指定 UTF-8或者缓冲区按字节切分时把一个多字节字符切断了。解决StreamReader构造时显式传Encoding.UTF8并且按行读取而不是按字节读取。如果自己用DownloadHandlerScript攒字节必须用一个Decoder对象处理跨包的多字节字符不能直接Encoding.UTF8.GetString每个包。5. 进阶把对话历史、超时和重试做成可复用的客户端5.1 维护多轮对话的 messages 数组单轮请求只是演示真实场景需要把历史对话带上。做法是维护一个ListMessage每次用户输入后追加user消息收到完整回复后追加assistant消息。注意messages数组会随着轮次增长token 消耗也线性增长所以要么限制保留最近 N 轮要么在超过阈值时做摘要压缩。我一般会保留最近 10 轮超过后把最早的两轮合并成一条system摘要这样既保留上下文又控制成本。5.2 超时与取消别让请求卡死整个游戏HttpClient默认超时是 100 秒游戏里等 100 秒是不可接受的。建议把Timeout设为 30 秒并且用CancellationTokenSource在用户关闭面板或切换场景时主动取消。UnityWebRequest则用req.timeout设秒数并在OnDestroy里调用req.Abort()。取消后要捕获TaskCanceledException或检查req.result UnityWebRequest.Result.ConnectionError避免把取消当成错误弹窗。5.3 一个可复用的客户端接口设计把前面所有逻辑收进一个DeepSeekClient类对外暴露ChatAsync和ChatStreamAsync两个方法内部按平台选择HttpClient或UnityWebRequest实现。配置项包括apiKey、model、temperature、maxTokens、timeoutSeconds、maxRetry。重试逻辑只对 429 和 5xx 生效4xx 直接抛出不重试。下面是一个配置表方便对照调整。参数建议值说明modeldeepseek-chat通用对话代码场景可换 deepseek-codertemperature0.2 ~ 0.7越低越稳定越高越有创意max_tokens512 ~ 2048移动端建议不超过 1024timeoutSeconds30流式可放宽到 60maxRetry3仅对 429 和 5xx 重试historyRounds10超过后做摘要压缩5.4 验证方法用日志和抓包确认每一层调通之后别急着接 UI先用Debug.Log把请求体、响应码、首字节时间、每段 delta 长度打出来。首字节时间能反映网络质量delta 长度能看出流式是否真的在逐块返回。如果首字节时间超过 5 秒检查 DNS 和 TLS 握手如果 delta 一次性全到说明ResponseHeadersRead没生效或者中间有代理缓冲。抓包工具在 PC 上可以用 Fiddler移动端可以用 Charles但注意 HTTPS 需要装证书这一步在 Android 7 以后对用户证书有限制调试时用network_security_config放行即可。我自己的习惯是每接一个新 API先写一个纯 C# 控制台程序把请求跑通确认 JSON 结构和流式格式再往 Unity 里搬。这样能把网络问题和 Unity 问题分开省掉大量来回打包的时间。希望帮到你。本文还有配套的精品资源点击获取