|
|
--- |
|
|
base_model: unsloth/qwen3-4b-unsloth-bnb-4bit |
|
|
library_name: peft |
|
|
pipeline_tag: text-generation |
|
|
tags: |
|
|
- base_model:adapter:unsloth/qwen3-4b-unsloth-bnb-4bit |
|
|
- lora |
|
|
- sft |
|
|
- transformers |
|
|
- trl |
|
|
- unsloth |
|
|
- game |
|
|
- npc |
|
|
- gamesoul |
|
|
- ai |
|
|
- RAG |
|
|
- MCP |
|
|
- 游戏 |
|
|
- Unreal |
|
|
- Unity |
|
|
- Cocos |
|
|
--- |
|
|
|
|
|
# Model Card for GameSoul-AI-NPC |
|
|
|
|
|
 |
|
|
|
|
|
[English](README.md) | [中文] |
|
|
|
|
|
🤖 GameSoul-AI-NPC 遊戲 NPC 行為決策模型，透過多來源資訊融合，生成符合角色設定的動態行為。支援即時環境回應、事件回應、記憶回溯與角色一致性維持。可呼叫推理 (Reasoning)、RAG (檢索增強生成) 及 MCP (多角色協同規劃)。 |
|
|
|
|
|
## 模型細節 🔍 |
|
|
|
|
|
### 核心能力 |
|
|
|
|
|
| 模組 | 功能描述 | |
|
|
| --------- | ---------------------------------- | |
|
|
| **環境感知** | 解析場景狀態、玩家互動、時間/天氣等即時訊號 | |
|
|
| **記憶系統** | 支援長期行為記憶（使用資料庫儲存） | |
|
|
| **角色一致性** | 根據預設背景（性格/目標/身分/能力/記憶等）生成符合角色設定的行為 | |
|
|
| **動態決策** | 基於綜合狀態生成動作序列（移動/對話/互動） | |
|
|
|
|
|
### 技術架構 🏗️ |
|
|
|
|
|
```mermaid |
|
|
graph TD |
|
|
A[🌏環境狀態] --> C(🧠LLM決策引擎) |
|
|
B[🧙♂️角色記憶] --> C |
|
|
D[💭當前事件] --> C |
|
|
C --> E{行為裁決} |
|
|
E --> F[👊動作指令] |
|
|
E --> G[💬自然語言回饋] |
|
|
E --> H[📌儲存記憶] |
|
|
``` |
|
|
|
|
|
### 擴展介面 |
|
|
|
|
|
🔌MCP 協議 (reference only)：透過 npc\_memory\_api (example) 呼叫 MCP 取得資料庫資訊 |
|
|
|
|
|
```json |
|
|
// example |
|
|
{ |
|
|
"jsonrpc": "2.0", |
|
|
"id": 123456789, |
|
|
"method": "get_npc_memory", |
|
|
"params": { |
|
|
"player_action": "steal_item", |
|
|
"npc_id": "npc_123456" |
|
|
} |
|
|
} |
|
|
``` |
|
|
|
|
|
### 模型描述 📝 |
|
|
|
|
|
- **Developed by : NewOrigin** |
|
|
- **Funded by : NewOrigin** |
|
|
- **Shared by : NewOrigin** |
|
|
- **Model type : Decoder&MoE Transformer** |
|
|
- **Language(s) (NLP) : English & Chinese & 110+ languages** |
|
|
- **License : apache-2.0** |
|
|
- **Finetuned from model : unsloth/qwen3-4b** |
|
|
|
|
|
### 模型來源 🌐 |
|
|
|
|
|
- **Repository :** [https://huggingface.co/unsloth/Qwen3-4B](https://huggingface.co/unsloth/Qwen3-4B) |
|
|
|
|
|
## 使用場景 🚀 |
|
|
|
|
|
本模型為 unsloth/qwen3-4b 的微調版本，專為遊戲中非玩家角色 (NPC) 賦能智能行為。模型可根據角色背景、記憶上下文與環境狀態生成動態回應，支援推理 (Reasoning)、RAG (檢索增強生成) 及 MCP (多角色協同規劃) 呼叫。 |
|
|
|
|
|
預期使用者： |
|
|
|
|
|
- 遊戲開發者、遊戲設計師 |
|
|
- 研究遊戲 NPC 行為 AI 的專業人員 |
|
|
- 遊戲工作室、獨立遊戲開發者 |
|
|
- 其他有興趣的使用者 |
|
|
|
|
|
潛在影響對象： |
|
|
|
|
|
- 與 NPC 互動的最終玩家 |
|
|
|
|
|
### 直接使用 🖥️ |
|
|
|
|
|
本模型可直接用於遊戲環境中生成 AI 行為，無需額外微調。它能根據上下文、記憶資訊、玩家行為及環境狀態生成符合預期的 NPC 回應。開發者可透過推理介面直接呼叫，或整合至遊戲系統、決策邏輯或 RAG 流程中使用。 |
|
|
|
|
|
典型應用場景包括： |
|
|
|
|
|
- 自動化 NPC 生態，形成遊戲世界即時推演 |
|
|
- 基於劇情與記憶的 NPC 互動 |
|
|
- 根據環境狀態的行為規劃 |
|
|
- 多智能體協作推理與回應 |
|
|
|
|
|
### 下游整合 📦 |
|
|
|
|
|
該模型適合嵌入遊戲系統等下游場景，可作為 AI 驅動 NPC 的核心推理與對話引擎，融入： |
|
|
|
|
|
- 遊戲引擎中，實現即時對話生成與行為邏輯控制 |
|
|
- 多智能體模擬平台，提供長期記憶及上下文推理能力的互動行為 |
|
|
- 基於 RAG 的推理系統，透過知識檢索增強 NPC 的決策過程 |
|
|
- 支援 MCP 協議的資料庫，用於儲存 NPC 資訊，並於需要時呼叫 |
|
|
|
|
|
依據遊戲調性、設定或任務需求，亦可進行進一步微調以符合風格。 |
|
|
|
|
|
### 不建議使用範圍 ⚠️ |
|
|
|
|
|
本模型不適用於涉及高風險或安全敏感的應用情境，以下為不建議使用方式： |
|
|
|
|
|
- 涉及法律、醫療、金融或安全等決策類任務 |
|
|
- 需要高度事實準確度或倫理推理的應用場景 |
|
|
|
|
|
## 偏見、風險與限制 🚧 |
|
|
|
|
|
本模型可能繼承基礎預訓練資料或微調語料中的偏見，例如文化刻板印象、色情內容、性別偏見、角色行為模式等。 |
|
|
|
|
|
技術限制包括： |
|
|
|
|
|
- 無法驗證生成內容的真實性或邏輯正確性 |
|
|
|
|
|
在任何包含生成內容的系統中，尤其面向未成年玩家時，建議對輸出結果進行必要過濾。 |
|
|
|
|
|
### 建議事項 💡 |
|
|
|
|
|
- 部署前請充分測試模型於多種遊戲情境下的表現，釐清其邊界與潛在失效風險。 |
|
|
- 在遊戲引擎中，先建立能執行動作的框架，再整合該模型。 |
|
|
|
|
|
## 快速上手 🚩 |
|
|
|
|
|
以下範例示範如何快速載入並呼叫微調後模型： |
|
|
|
|
|
```python |
|
|
from transformers import AutoModelForCausalLM, AutoTokenizer |
|
|
import torch |
|
|
|
|
|
model_name = "NewOrigin/GameSoul-AI-NPC-4B-v0.1" |
|
|
|
|
|
tokenizer = AutoTokenizer.from_pretrained(model_name) |
|
|
model = AutoModelForCausalLM.from_pretrained( |
|
|
model_name, |
|
|
torch_dtype=torch.auto, |
|
|
device_map="auto" |
|
|
) |
|
|
|
|
|
prompt = "input your content" |
|
|
messages = [ |
|
|
{"role": "user", "content": prompt} |
|
|
] |
|
|
|
|
|
text = tokenizer.apply_chat_template( |
|
|
messages, |
|
|
tokenize=False, |
|
|
add_generation_prompt=False, |
|
|
enable_thinking=False |
|
|
) |
|
|
|
|
|
model_inputs = tokenizer([text], return_tensors="pt").to(model.device) |
|
|
|
|
|
generated_ids = model.generate( |
|
|
**model_inputs, |
|
|
max_new_tokens=1024, |
|
|
do_sample=True, |
|
|
top_p=0.9, |
|
|
) |
|
|
|
|
|
output_ids = generated_ids[0].tolist() |
|
|
think_token_id = tokenizer.convert_tokens_to_ids("</think>") |
|
|
if think_token_id in output_ids: |
|
|
idx = output_ids.index(think_token_id) |
|
|
thinking = tokenizer.decode(output_ids[:idx], skip_special_tokens=True).strip() |
|
|
response = tokenizer.decode(output_ids[idx+1:], skip_special_tokens=True).strip() |
|
|
else: |
|
|
thinking, response = "", tokenizer.decode(output_ids, skip_special_tokens=True).strip() |
|
|
|
|
|
print("🧠 think", thinking) |
|
|
print("💬 answer", response) |
|
|
``` |
|
|
|
|
|
### 範例輸入與輸出 📥📤 |
|
|
|
|
|
- 輸入📥 |
|
|
|
|
|
```json |
|
|
{ |
|
|
"NPCID": "npc_585919", |
|
|
"角色背景": "一位來自神秘森林的魅魔藥劑師，二十歲，從小在森林中學習草藥和魔法知識。因森林遭遇邪惡魔法侵襲，親人離世，她決心尋找破解魔法的方法。擅長調配藥劑、魅惑與魔法感知。", |
|
|
"特徵": { |
|
|
"核心性格": [ |
|
|
"誘惑", |
|
|
"狡猾", |
|
|
"好奇" |
|
|
], |
|
|
"特長": [ |
|
|
"藥劑調配", |
|
|
"魅惑術", |
|
|
"魔法感知" |
|
|
] |
|
|
}, |
|
|
"動態狀態": { |
|
|
"當前情緒": "憤怒（因最近魔法污染在森林中加劇，影響了她的力量）" |
|
|
}, |
|
|
"記憶事件": [ |
|
|
{ |
|
|
"eventid": "evt_20240805_001", |
|
|
"timestamp": "2024-08-05", |
|
|
"事件類型": "幫助", |
|
|
"發起者": "player_004", |
|
|
"接受者": "npc_585919", |
|
|
"動作": "提供魔法書籍", |
|
|
"影響": "對player_004產生好感，獲得更多魔法能量" |
|
|
}, |
|
|
{ |
|
|
"eventid": "evt_20240720_002", |
|
|
"timestamp": "2024-07-20", |
|
|
"事件類型": "衝突", |
|
|
"發起者": "npc_006", |
|
|
"接受者": "npc_585919", |
|
|
"動作": "搶奪草藥", |
|
|
"影響": "npc_585919對npc_006產生敵意，警惕性上升" |
|
|
}, |
|
|
{ |
|
|
"eventid": "evt_20240712_003", |
|
|
"timestamp": "2024-07-12", |
|
|
"事件類型": "交易", |
|
|
"發起者": "player_005", |
|
|
"接受者": "npc_585919", |
|
|
"動作": "購買藥劑", |
|
|
"影響": "獲得金幣，心情愉悅，利用魅力加強交易" |
|
|
}, |
|
|
{ |
|
|
"eventid": "evt_20240630_004", |
|
|
"timestamp": "2024-06-30", |
|
|
"事件類型": "幫助", |
|
|
"發起者": "npc_585919", |
|
|
"接受者": "player_006", |
|
|
"動作": "治療傷口", |
|
|
"影響": "透過魔法治療，產生好感與依賴" |
|
|
}, |
|
|
{ |
|
|
"eventid": "evt_20240615_005", |
|
|
"timestamp": "2024-06-15", |
|
|
"事件類型": "探索", |
|
|
"發起者": "npc_585919", |
|
|
"接受者": "npc_585919", |
|
|
"動作": "發現新草藥", |
|
|
"影響": "增加魔法知識，提升魅力" |
|
|
} |
|
|
] |
|
|
}, |
|
|
{ |
|
|
"當前事件": "遇到了好色的勇者" |
|
|
} |
|
|
``` |
|
|
|
|
|
- 輸出📤 |
|
|
|
|
|
```json |
|
|
{"事件反應": "npc_585919察覺到勇者對她的騷擾後，釋放魅惑術使其陷入幻覺，同時用魔法感知追蹤其行動軌跡，並在森林深處設下陷阱"} |
|
|
``` |
|
|
|
|
|
## 訓練細節 🏋️♀️ |
|
|
|
|
|
### 訓練流程 |
|
|
|
|
|
本模型基於 unsloth/qwen3-4b-unsloth-bnb-4bit 進行微調，採用 Unsloth 工具庫中的 LoRA (Low-Rank Adaptation) 方法，實現高效低資源微調。 |
|
|
|
|
|
- 微調方式： LoRA |
|
|
- 訓練器： 使用 Unsloth 的 SFTTrainer |
|
|
- 模型格式： 僅保存 adapter 權重，格式為 safetensors |
|
|
- 訓練設備： Nvidia A10 GPU |
|
|
|
|
|
## 環境影響 🌱 |
|
|
|
|
|
- **Hardware Type : cloud server** |
|
|
- **Cloud Provider : Google Cloud Platform & Alibaba Cloud** |
|
|
- **Compute Region : NorthAmerica & Asia** |
|
|
- **Carbon Emitted : <1Kg** |
|
|
|
|
|
**BibTeX:** |
|
|
|
|
|
```bibtex |
|
|
@misc{NewOrigin2025GameSoul-AI-NPC, |
|
|
title = {GameSoul-AI-NPC: A LoRA fine-tuned Qwen3-4B model for game NPC reasoning and interaction}, |
|
|
author = {NewOrigin}, |
|
|
year = {2025}, |
|
|
publisher = {Hugging Face}, |
|
|
howpublished = {https://huggingface.co/NewOrigin/GameSoul-AI-NPC-4B-v0.1} |
|
|
} |
|
|
``` |
|
|
|
|
|
**APA:** |
|
|
|
|
|
NewOrigin. (2025). *GameSoul-AI-NPC: A LoRA fine-tuned Qwen3-4B model for game NPC reasoning and interaction*. Hugging Face. [https://huggingface.co/NewOrigin/GameSoul-AI-NPC-4B-v0.1](https://huggingface.co/NewOrigin/GameSoul-AI-NPC-4B-v0.1) |
|
|
|
|
|
## Model Card Authors ✍️ |
|
|
|
|
|
- **Author by : NewOrigin** |
|
|
|
|
|
## 聯絡方式 📧 |
|
|
|
|
|
如有任何問題、建議或合作意向，歡迎聯繫： |
|
|
|
|
|
**電子郵件：**[**[email protected]**](mailto\:[email protected]) |
|
|
|
|
|
### Framework versions |
|
|
|
|
|
- PEFT 0.16.0 |
|
|
|
|
|
|
