企业官网建设流程全解析

简介：这份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 侧选型：为什么不是随便发个 POST

2.1 接口本质：OpenAI 兼容的 Chat Completions

DeepSeekAPI 对外暴露的是 OpenAI 兼容的/chat/completions接口，请求体是 JSON，鉴权走Authorization: Bearer <API_KEY>请求头。这意味着你在 Unity 里不需要引入任何厂商专属 SDK，只要会发 HTTP POST 就能调通。请求体里最关键的几个字段是model、messages、stream、temperature、max_tokens。messages是一个数组，每个元素包含role和content，role取system、user、assistant三种。stream设为true时，服务端会以 SSE（Server-Sent Events）形式逐块返回，这对游戏里的打字机效果是刚需。

常见做法是把请求体封装成一个 C# 类，用JsonUtility或Newtonsoft.Json序列化。这里有个容易忽略的点：JsonUtility不支持字典和顶层数组，而messages是数组，所以要么用Newtonsoft.Json，要么手写一个可序列化的包装类。我一般会直接上Newtonsoft.Json，因为流式解析时它处理不完整 JSON 片段更稳。

2.2 Unity 侧网络层选型：UnityWebRequest 还是 HttpClient

Unity 里发 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 数据一块块喂给 UI

3.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, Action<string> 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 主线程里安全更新 UI

HttpClient的回调在线程池线程上执行，而 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 ConcurrentQueue<string> _pending = new ConcurrentQueue<string>(); 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:usesCleartextTraffic="false"，同时检查 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 fullname="Newtonsoft.Json"> <type fullname="*" preserve="all"/> </assembly> </linker>

4.3 WebGL 平台无法使用 HttpClient 和线程

现象：WebGL 打包后编译报错，提示System.Net.Http不可用，或者运行时卡死。原因：WebGL 是单线程模型，不支持多线程和 Socket，HttpClient底层依赖的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 数组

单轮请求只是演示，真实场景需要把历史对话带上。做法是维护一个List<Message>，每次用户输入后追加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 直接抛出不重试。下面是一个配置表，方便对照调整。

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 问题分开，省掉大量来回打包的时间。希望帮到你。

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