--- 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 ![Image Alt Text](DocsAsset/GAMESOUL_top_pic.png) [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("") 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** ## 聯絡方式 📧 如有任何問題、建議或合作意向，歡迎聯繫： **電子郵件：**[**s1xvtt9tw@mozmail.com**](mailto\:s1xvtt9tw@mozmail.com) ### Framework versions - PEFT 0.16.0