English 中文说明

PHYSICAL ATLAS

Winyunq Industrial Core / API Layer Documentation

Concept 01 / ABI Firewall

物理隔离：ABI 防火墙机制

Unreal Engine 5 (User Space) UObject, Blueprints, Game Thread LITERT_LM_WRAPPER.DLL Google SDK (Engine Core) Abseil, Protobuf, Minja, WebGPU void* handle
物理契约： 虚幻侧仅持有 void* 句柄。底层所有 C++ 对象的生命周期、符号 链接、内存布局均被 DLL 彻底遮蔽。
工程优势： 即使底层 Google SDK 版本升级，虚幻项目的二进制文件也无需重新编译。彻底解决了“符号冲突”这一大项目顽疾。
Concept 02 / KV Cache persistence

持久化：多会话 KV Cache 映射

GPU VRAM ADDRESS SPACE Model Weights (Frozen) Conv_A (NPC 1) KV Cache Slot 0 Conv_B (NPC 2) Conv_C (NPC 3)
物理映射： 每一个 Conversation 句柄在显存中独占一个 max_num_tokens 大小的物理分片。
瞬时响应： 切换对话对象只需在 SendChatRequest 时传入不同的句柄。首字延迟 < 100ms。
Concept 03 / Functional API Reference

功能 API 参考 (LiteRtLmUnrealApi)

LoadModel(const FLiteRtLmConfig& Config) STATIC

加载指定路径 of the .tflite 模型并初始化底层运行时。这是 所有推理操作的前置条件。

Side Effect: GPU VRAM Allocation Return: bool
SendChatRequest(void* SessionKey, const TArray<...>& Messages, ...) STATIC

发送聊天请求。系统会自动比较 SessionKey 对应的历史记录，仅同步新增的消息片段（增量同步），从而极大提高推理速度。

  • 支持 Tool Call 自动注入与解析。
  • 回调函数 OnChunk 会在 Game Thread 中触发，确保 UI 安全。
ReleaseSession(void* SessionKey) STATIC

手动释放特定会话在显存中的 KV Cache 槽位。当一个 NPC 彻底销毁时应调用此方法。

GetAutoConfig() STATIC

通过 DXGI 实时探测硬件显存，自动生成推荐的并行线程数与 KV 槽位大小配置。

Concept 04 / Hardware Mapping

物理映射与副作用 (Physical Logic)

物理映射 (Mapping)

Weights -> Memory

模型权重通过 mmap (内存映射文件) 直 接挂载，避免了冷启动时的冗余内存拷贝。

Handle -> VRAM

每一个 void* SessionKey 内部映射到一个 LlamaIndex，对应显存中固定的步长偏移地址。

系统副作用 (Side Effects)

Thread Blocking

底层 WaitUntilDone 是阻塞式的。我们 通过虚幻的 AsyncTask 隔离执行，防止游戏主线程卡死。

VRAM Pressure

模型一旦加载，将独占数 GB 显存。必须确保在 Level 切换或内存压力大时调用 UnloadModel。