Hugging Face's logo

NewOrigin
/
GameSoul-AI-NPC-4B-v0.1

Text Generation
PEFT
Safetensors
Transformers
English
Chinese
lora
sft
trl
unsloth
game
npc
gamesoul
ai
RAG
MCP
游戏
Unreal
Unity
Cocos
conversational
Model card Files
xet
Community
GameSoul-AI-NPC-4B-v0.1 / README_ZH_CN.md
NewOrigin's picture
NewOrigin
Update README_ZH_CN.md
9c26933 verified
preview code
|
raw
history blame contribute delete
10.1 kB
metadata
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

English | [中文]

🤖 GameSoul-AI-NPC 遊戲 NPC 行為決策模型，透過多來源資訊融合，生成符合角色設定的動態行為。支援即時環境回應、事件回應、記憶回溯與角色一致性維持。可呼叫推理 (Reasoning)、RAG (檢索增強生成) 及 MCP (多角色協同規劃)。

模型細節 🔍

核心能力

模組 功能描述
環境感知 解析場景狀態、玩家互動、時間/天氣等即時訊號
記憶系統 支援長期行為記憶（使用資料庫儲存）
角色一致性 根據預設背景（性格/目標/身分/能力/記憶等）生成符合角色設定的行為
動態決策 基於綜合狀態生成動作序列（移動/對話/互動）

技術架構 🏗️ 

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 取得資料庫資訊

// 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

模型來源 🌐

使用場景 🚀

本模型為 unsloth/qwen3-4b 的微調版本，專為遊戲中非玩家角色 (NPC) 賦能智能行為。模型可根據角色背景、記憶上下文與環境狀態生成動態回應，支援推理 (Reasoning)、RAG (檢索增強生成) 及 MCP (多角色協同規劃) 呼叫。

預期使用者：

  • 遊戲開發者、遊戲設計師
  • 研究遊戲 NPC 行為 AI 的專業人員
  • 遊戲工作室、獨立遊戲開發者
  • 其他有興趣的使用者

潛在影響對象：

  • 與 NPC 互動的最終玩家

直接使用 🖥️

本模型可直接用於遊戲環境中生成 AI 行為，無需額外微調。它能根據上下文、記憶資訊、玩家行為及環境狀態生成符合預期的 NPC 回應。開發者可透過推理介面直接呼叫，或整合至遊戲系統、決策邏輯或 RAG 流程中使用。

典型應用場景包括：

  • 自動化 NPC 生態，形成遊戲世界即時推演
  • 基於劇情與記憶的 NPC 互動
  • 根據環境狀態的行為規劃
  • 多智能體協作推理與回應

下游整合 📦

該模型適合嵌入遊戲系統等下游場景，可作為 AI 驅動 NPC 的核心推理與對話引擎，融入：

  • 遊戲引擎中，實現即時對話生成與行為邏輯控制
  • 多智能體模擬平台，提供長期記憶及上下文推理能力的互動行為
  • 基於 RAG 的推理系統，透過知識檢索增強 NPC 的決策過程
  • 支援 MCP 協議的資料庫，用於儲存 NPC 資訊，並於需要時呼叫

依據遊戲調性、設定或任務需求，亦可進行進一步微調以符合風格。

不建議使用範圍 ⚠️

本模型不適用於涉及高風險或安全敏感的應用情境，以下為不建議使用方式：

  • 涉及法律、醫療、金融或安全等決策類任務
  • 需要高度事實準確度或倫理推理的應用場景

偏見、風險與限制 🚧

本模型可能繼承基礎預訓練資料或微調語料中的偏見，例如文化刻板印象、色情內容、性別偏見、角色行為模式等。

技術限制包括：

  • 無法驗證生成內容的真實性或邏輯正確性

在任何包含生成內容的系統中，尤其面向未成年玩家時，建議對輸出結果進行必要過濾。

建議事項 💡

  • 部署前請充分測試模型於多種遊戲情境下的表現，釐清其邊界與潛在失效風險。
  • 在遊戲引擎中，先建立能執行動作的框架，再整合該模型。

快速上手 🚩

以下範例示範如何快速載入並呼叫微調後模型：

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)

範例輸入與輸出 📥📤

  • 輸入📥
{
    "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",
            "動作": "發現新草藥",
            "影響": "增加魔法知識，提升魅力"
        }
    ]
},
{
    "當前事件": "遇到了好色的勇者"
}
  • 輸出📤
{"事件反應": "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:

@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

Model Card Authors ✍️

  • Author by : NewOrigin

聯絡方式 📧

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

電子郵件：[email protected]

Framework versions

  • PEFT 0.16.0