初始化项目，由ModelHub XC社区提供模型
Model: AndriLawrence/Qwen-3B-Intent-Microplan-v1 Source: Original Platform
This commit is contained in:
ModelHub XC
253
README.md
Normal file
253
README.md
Normal file
@@ -0,0 +1,253 @@
|
||||
---
|
||||
language: en
|
||||
license: other
|
||||
library_name: transformers
|
||||
pipeline_tag: text-generation
|
||||
base_model: bunnycore/Qwen2.5-3B-RP-Mix
|
||||
tags:
|
||||
- qwen
|
||||
- sft
|
||||
- 3b
|
||||
- gguf
|
||||
- transformers
|
||||
- lora
|
||||
- gamedev
|
||||
- npc
|
||||
- game-npc
|
||||
- json
|
||||
- json-only
|
||||
- intent-microplan
|
||||
- companion-ai
|
||||
- roleplay
|
||||
- comfort
|
||||
- local-llm
|
||||
- action-generation
|
||||
---
|
||||
|
||||
# Qwen-3B-Intent-Microplan-v1
|
||||
|
||||
> ⚠️ **Deprecated / Archived Model**
|
||||
|
||||
👉 Looking for the maintained version?
|
||||
Use **Qwen-3B-Intent-Microplan-v2** instead:
|
||||
➡️ https://huggingface.co/AndriLawrence/Qwen-3B-Intent-Microplan-v2
|
||||
|
||||
---
|
||||
|
||||
This is a supervised fine-tune (SFT) of `bunnycore/Qwen2.5-3B-RP-Mix` (3B) designed to serve as a **local-first, real-time game NPC brain**.
|
||||
|
||||
This v1 model is the first release built on the **"Intent-Microplan Framework"**: a structured-output approach that separates an NPC's high-level social/strategic goals (`intent`) from their low-level physical execution steps (`microplan`).
|
||||
|
||||
The model is designed for **companion, dating-sim, or comfort-aware** NPC use cases, outputting strict, engine-parsable JSON for dialogue and action.
|
||||
|
||||
## ⚠️ V1 Status: Deprecated (Failure Analysis)
|
||||
|
||||
**This V1 model is considered a failure and is deprecated. Do not use this for production.**
|
||||
|
||||
The primary issue stems from the choice of the base model, `bunnycore/Qwen2.5-3B-RP-Mix`. This "Roleplay (RP) merge" proved highly resistant to strict JSON schema enforcement. It consistently attempts to break out of the JSON format to produce creative, non-structured text, which defeats the purpose of the Intent-Microplan framework.
|
||||
|
||||
**This model is superseded by V2**, which uses a non-RP, foundational base model that is better suited for structured data output:
|
||||
|
||||
➡️ https://huggingface.co/AndriLawrence/Qwen-3B-Intent-Microplan-v2
|
||||
|
||||
*The original documentation below is preserved for archival purposes of the V1 attempt.*
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 🎯 The Intent-Microplan Framework
|
||||
|
||||
This model's purpose is to act as a *dynamic behavior tree generator*. Instead of just talking, it creates a plan.
|
||||
|
||||
1. **`intent` (The "What"):** The strategic goal or social understanding. This is the "why" behind the action (e.g., `comfort_intimate`, `acknowledge_compliment`).
|
||||
2. **`microplan` (The "How"):** The list of physical, engine-agnostic steps to achieve the intent. Your game engine's C\# (or C++) script is responsible for parsing this array and executing the functions (e.g., triggering animations, moving the NavMeshAgent).
|
||||
|
||||
This architecture allows for:
|
||||
|
||||
* **Emergent Behavior:** NPCs can dynamically generate plans based on context.
|
||||
* **Low Latency:** Only one small, local LLM call is needed per interaction.
|
||||
|
||||
## 📦 Model Artifacts
|
||||
|
||||
* **`merged/`**: FP16 Transformers weights (LoRA merged) for direct use.
|
||||
* **`adapter/`**: The LoRA adapter (PEFT) for continued SFT or experimentation.
|
||||
* **`gguf/`**: Quantized GGUF files (e.g., Q4\_K\_M) for `llama.cpp`, ideal for local in-game deployment (Unity, Unreal).
|
||||
|
||||
## 💬 Prompting & JSON Schema
|
||||
|
||||
The model is trained to respond to a context block and output **ONLY** a raw JSON object.
|
||||
|
||||
### JSON Schema
|
||||
|
||||
| Key | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `dialog` | `array` | A list of 1-2 dialogue objects (`{"speaker": "npc", "text": "..."}`). |
|
||||
| `intent` | `string` | The single, precise strategic goal selected by the model. |
|
||||
| `microplan` | `array` | An array of 0-5 string commands for the game engine. |
|
||||
|
||||
**Supported Intents (v1):**
|
||||
`social_greeting`, `acknowledge_touch`, `acknowledge_compliment`, `comfort_intimate`, `invite_sleep`, `inspect_object`, `open_or_trigger_object`, `give_item`, `receive_item`, `small_talk`, `react_to_player_action`, `idle_initiative`, `respect_distance`
|
||||
|
||||
### ⚡ Recommended Prompt
|
||||
|
||||
This "hardened" prompt includes rules that mirror the dataset's logic, ensuring high stability and intent accuracy.
|
||||
|
||||
```
|
||||
|
||||
You are LLM-1 (creative social responder).
|
||||
Return ONE object of STRICT JSON ONLY with keys:
|
||||
|
||||
- "dialog": [{ "speaker": "npc", "text": string }] (1–2 items, concise, warm, natural)
|
||||
- "intent": string (choose a precise label, e.g., social_greeting, acknowledge_touch, acknowledge_compliment, comfort_intimate, invite_sleep, inspect_object, open_or_trigger_object, give_item, receive_item, small_talk, react_to_player_action, idle_initiative, respect_distance)
|
||||
- "microplan": array of 0–5 short steps (body/face/locomotion cues, e.g., "Approach front (1.0m)", "Offer hand (0.7)", "Smile (0.6)")
|
||||
|
||||
Hard rules:
|
||||
|
||||
- If event == "Player_Touches" → intent MUST be "acknowledge_touch".
|
||||
- If event == "Player_Action" → intent MUST be "react_to_player_action" (or a more specific action intent if obvious).
|
||||
- If player's text contains (nice|great|love|beautiful|cool) → intent MUST be "acknowledge_compliment".
|
||||
- English only. No markdown/code fences. No extra text. JSON only.
|
||||
- ≤ 2 sentences in each dialog text. Do NOT start with "I'm" or "I am". No helper clichés.
|
||||
|
||||
NOW RESPOND TO THIS CONTEXT:
|
||||
{CONTEXT_JSON}
|
||||
OUTPUT:
|
||||
|
||||
```
|
||||
|
||||
Replace `{CONTEXT_JSON}` with your game's state payload.
|
||||
|
||||
## 🚀 How to Use
|
||||
|
||||
### Transformers (Python)
|
||||
|
||||
```python
|
||||
from transformers import AutoTokenizer, AutoModelForCausalLM, pipeline
|
||||
import json
|
||||
|
||||
MODEL_ID = "AndriLawrence/Qwen-3B-Intent-Microplan-v1"
|
||||
|
||||
tok = AutoTokenizer.from_pretrained(MODEL_ID, use_fast=True)
|
||||
mdl = AutoModelForCausalLM.from_pretrained(
|
||||
MODEL_ID,
|
||||
device_map="auto",
|
||||
torch_dtype="auto",
|
||||
trust_remote_code=True
|
||||
)
|
||||
|
||||
# This system prompt is CRITICAL for schema adherence
|
||||
system_prompt = (
|
||||
'You are LLM-1 (creative social responder).\n'
|
||||
'Return ONE object of STRICT JSON ONLY with keys:\n'
|
||||
'- "dialog": [{ "speaker": "npc", "text": string }] (1–2 items, concise, warm, natural)\n'
|
||||
'- "intent": string (choose a precise label, e.g., social_greeting, acknowledge_touch, acknowledge_compliment, comfort_intimate, invite_sleep, inspect_object, open_or_trigger_object, give_item, receive_item, small_talk, react_to_player_action, idle_initiative, respect_distance)\n'
|
||||
'- "microplan": array of 0–5 short steps (body/face/locomotion cues, e.g., "Approach front (1.0m)", "Offer hand (0.7)", "Smile (0.6)")\n\n'
|
||||
'Hard rules:\n'
|
||||
'- If event == "Player_Touches" → intent MUST be "acknowledge_touch".\n'
|
||||
'- If event == "Player_Action" → intent MUST be "react_to_player_action" (or a more specific action intent if obvious).\n'
|
||||
'- If player\'s text contains (nice|great|love|beautiful|cool) → intent MUST be "acknowledge_compliment".\n'
|
||||
'- English only. No markdown/code fences. No extra text. JSON only.\n'
|
||||
'- ≤ 2 sentences in each dialog text. Do NOT start with "I\'m" or "I am". No helper clichés.'
|
||||
)
|
||||
|
||||
# Example: Player holds out their hand
|
||||
game_context = {
|
||||
"event": "Player_Action",
|
||||
"action": "offer_hand",
|
||||
"environment": {"location": "Living Room", "distance": "1.5m"}
|
||||
}
|
||||
|
||||
msgs = [
|
||||
{"role": "system", "content": system_prompt},
|
||||
{"role": "user", "content": f"NOW RESPOND TO THIS CONTEXT:\n{json.dumps(game_context)}\nOUTPUT:"}
|
||||
]
|
||||
prompt = tok.apply_chat_template(msgs, tokenize=False, add_generation_prompt=False) # We add the 'OUTPUT:' manually
|
||||
|
||||
pipe = pipeline("text-generation", model=mdl, tokenizer=tok)
|
||||
gen_out = pipe(
|
||||
prompt,
|
||||
do_sample=True,
|
||||
temperature=0.35, # BALANCED preset
|
||||
top_p=0.85,
|
||||
repetition_penalty=1.1,
|
||||
max_new_tokens=256,
|
||||
pad_token_id=tok.eos_token_id
|
||||
)[0]["generated_text"]
|
||||
|
||||
# Clean the output and parse
|
||||
try:
|
||||
output_text = gen_out.split("OUTPUT:")[-1].strip()
|
||||
parsed_json = json.loads(output_text)
|
||||
print(json.dumps(parsed_json, indent=2))
|
||||
|
||||
except json.JSONDecodeError:
|
||||
print(f"FAILED TO PARSE JSON. Raw output:\n{output_text}")
|
||||
```
|
||||
|
||||
### GGUF / Ollama
|
||||
|
||||
Use the GGUF files for `llama.cpp`. This model is ideal for a "hidden terminal server" bundled with your game.
|
||||
|
||||
Example `Modelfile` for Ollama:
|
||||
|
||||
```
|
||||
FROM ./model-Q4_K_M.gguf
|
||||
|
||||
TEMPLATE """<|system|>
|
||||
{{ .System }}
|
||||
<|end|>
|
||||
<|user|>
|
||||
{{ .Prompt }}
|
||||
<|end|>
|
||||
<|assistant|>
|
||||
"""
|
||||
|
||||
SYSTEM """You are LLM-1 (creative social responder).
|
||||
Return ONE object of STRICT JSON ONLY with keys:
|
||||
- "dialog": [{ "speaker": "npc", "text": string }] (1–2 items, concise, warm, natural)
|
||||
- "intent": string (choose a precise label, e.g., social_greeting, acknowledge_touch, acknowledge_compliment, comfort_intimate, invite_sleep, inspect_object, open_or_trigger_object, give_item, receive_item, small_talk, react_to_player_action, idle_initiative, respect_distance)
|
||||
- "microplan": array of 0–5 short steps (body/face/locomotion cues, e.g., "Approach front (1.0m)", "Offer hand (0.7)", "Smile (0.6)")
|
||||
|
||||
Hard rules:
|
||||
- If event == "Player_Touches" → intent MUST be "acknowledge_touch".
|
||||
- If event == "Player_Action" → intent MUST be "react_to_player_action" (or a more specific action intent if obvious).
|
||||
- If player's text contains (nice|great|love|beautiful|cool) → intent MUST be "acknowledge_compliment".
|
||||
- English only. No markdown/code fences. No extra text. JSON only.
|
||||
- ≤ 2 sentences in each dialog text. Do NOT start with "I'm" or "I am". No helper clichés.
|
||||
"""
|
||||
|
||||
PARAMETER temperature 0.35
|
||||
PARAMETER top_p 0.85
|
||||
PARAMETER repeat_penalty 1.1
|
||||
```
|
||||
|
||||
## 🛠️ Training Details (v1)
|
||||
|
||||
This model was trained using PEFT LoRA on a custom, curated English-only dataset focused on comfort and companion interactions.
|
||||
|
||||
* **Base Model:** `bunnycore/Qwen2.5-3B-RP-Mix`
|
||||
* **Model Type:** `qwen2`
|
||||
|
||||
### Hyperparameters
|
||||
|
||||
| Parameter | Value |
|
||||
| --- | --- |
|
||||
| `learning_rate` | 2e-4 (0.0002) |
|
||||
| `num_train_epochs` | 2 |
|
||||
| `per_device_train_batch_size` | 1 |
|
||||
| `gradient_accumulation_steps` | 8 |
|
||||
| **Effective Batch Size** | **8** |
|
||||
| `lr_scheduler_type` | `cosine` |
|
||||
| `loss_type` | `nll` |
|
||||
| `optimizer` | `adamw_torch_fused` |
|
||||
| `max_length` | 1024 |
|
||||
|
||||
### LoRA Configuration (PEFT)
|
||||
|
||||
| Parameter | Value |
|
||||
| --- | --- |
|
||||
| `peft_type` | `LORA` |
|
||||
| `r` (rank) | 16 |
|
||||
| `lora_alpha` | 32 |
|
||||
| `lora_dropout` | 0.05 |
|
||||
| `target_modules` | `["v_proj", "o_proj", "q_proj", "up_proj", "gate_proj", "k_proj", "down_proj"]` |
|
||||
Reference in New Issue
Block a user