README_ZH_CN.md

---
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("</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**

## 聯絡方式 📧

如有任何問題、建議或合作意向，歡迎聯繫：

**電子郵件：**[**s1xvtt9tw@mozmail.com**](mailto\:s1xvtt9tw@mozmail.com)

### Framework versions

- PEFT 0.16.0