MiniCPM5-1B Agentic Tooluse QLoRA v2

Current PEFT/LoRA adapter for openbmb/MiniCPM5-1B, specialized for MiniCPM5 XML tool calling and repaired with targeted Nemotron SFT followed by DPO.

This is an adapter-only repository. Load it on top of the exact base model named in adapter_config.json, or use the standalone merged repository.

Base model architecture

MiniCPM5-1B uses a standard LlamaForCausalLM architecture:

Thinking mode

MiniCPM5-1B has a built-in <think>...</think> chat template. The same checkpoint can act as a fast assistant or a deliberate chain-of-thought reasoner — controlled by a single flag:

# Fast mode — recommended for tool calling (thinking OFF)
prompt = tokenizer.apply_chat_template(
    messages, tools=tools, add_generation_prompt=True,
    enable_thinking=False,
    tokenize=False,
)

# Reasoning mode (thinking ON — NOT recommended for tool calling)
prompt = tokenizer.apply_chat_template(
    messages, tools=tools, add_generation_prompt=True,
    enable_thinking=True,
    tokenize=False,
)

Important: always use enable_thinking=False for tool/function calling. With thinking ON the model spends its token budget inside <think>...</think> and may not reach a completed function call. All benchmark numbers in this card use thinking OFF.

Citation

If you use this model, please cite the base model paper:

@article{minicpm4,
  title   = {MiniCPM4: Ultra-Efficient LLMs on End Devices},
  author  = {MiniCPM Team},
  journal = {arXiv preprint arXiv:2506.07900},
  year    = {2025}
}

And the ToolACE dataset used for fine-tuning:

@article{toolace,
  title   = {ToolACE: Winning the Points of LLM Function Calling},
  author  = {Liu, Ying and others},
  journal = {arXiv preprint arXiv:2409.00920},
  year    = {2024}
}

ModelScope

The base model is also available on ModelScope (for users in China and East Asia):

• OpenBMB/MiniCPM5-1B on ModelScope

(The fine-tuned adapter/GGUF builds are currently HuggingFace-only.)

Related repos

Latest v3 release

v2 family (this release)

Adapter Configuration

• Base: openbmb/MiniCPM5-1B
• PEFT type: LoRA for causal language modeling
• Rank: 32
• Alpha: 64
• Dropout: 0.05
• Bias: none
• Target modules: q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj
• Adapter parameters: approximately 22.4 million

Current primary artifacts:

• adapter_model.safetensors
• adapter_config.json
• matching tokenizer and chat_template.jinja
• inference_example.py
• EVAL_RESULTS.md
• external_toolace_base_vs_nemotron_dpo_eval.json

Tool-Calling Behavior

MiniCPM5-1B already has native XML-style tool calling:

<function name="tool_name"><param name="parameter">value</param></function>

This adapter specializes first-call tool selection, valid function names, argument selection, schema-copy avoidance and repeated-call suppression. It does not create tool calling from scratch.

Load with PEFT

import torch
from peft import PeftModel
from transformers import AutoModelForCausalLM, AutoTokenizer

base_id = "openbmb/MiniCPM5-1B"
adapter_id = "ewinregirgojr/MiniCPM5-1B-Agentic-Tooluse-QLoRA-v2"

# The adapter repository carries the matching final tokenizer/template.
tokenizer = AutoTokenizer.from_pretrained(adapter_id)
base = AutoModelForCausalLM.from_pretrained(
    base_id,
    dtype=torch.float16,
    device_map="auto",
)
model = PeftModel.from_pretrained(base, adapter_id)
model.eval()

Use tokenizer.apply_chat_template(messages, tools=tools, add_generation_prompt=True) rather than constructing a raw prompt. For deterministic tool selection, use do_sample=False.

See inference_example.py for a complete first-call example with bounded generation.

Recommended Serving

PEFT adapters are most convenient in Transformers. For a standalone server, use the merged FP16 repository.

OpenBMB recommends SGLang and its MiniCPM5 parser for tool calling:

python -m sglang.launch_server \
  --model-path ewinregirgojr/MiniCPM5-1B-Agentic-Tooluse-Merged-FP16 \
  --tool-call-parser minicpm5

The parser converts a completed <function ...>...</function> block into an OpenAI-compatible tool_calls response.

External Evaluation

Evaluation used 300 examples derived from the external Team-ACE/ToolACE dataset, deterministic decoding, and identical cases for the base and adapter. This is a custom first-call evaluation, not an official ToolACE or BFCL leaderboard submission.

Full metrics and bad-row records are published in EVAL_RESULTS.md and external_toolace_base_vs_nemotron_dpo_eval.json.

Understanding Natural Termination

stopped_cleanly_rate=0.15 measures whether generation naturally ended immediately after the completed function call without runtime intervention. It is not the usable-call rate.

The same run achieved 99.33% parseability, 97% available-tool names and 92.67% expected-tool selection. Production should use the official minicpm5 parser where supported and treat the first completed </function> as the action boundary.

Training Lineage

The current release continues from the earlier xLAM/Glaive adapter and preference-repair stages, then applies:

1. A targeted SFT continuation using cleaned Nemotron agentic tool data.
2. DPO preference optimization using valid calls versus corrupted or wrong-tool calls.

Nemotron sources:

• nvidia/Nemotron-SFT-Agentic-v2
• nvidia/Nemotron-RL-Agentic-Function-Calling-Pivot-v1
• nvidia/Nemotron-RL-Agentic-Conversational-Tool-Use-Pivot-v1

The final pipeline inspected physical data files, skipped one malformed SFT JSONL row, removed oversized policy text where needed, preserved tool schemas and recent context, and rejected unknown arguments, schema-copy placeholders and invalid expected tools.

Runtime Responsibilities

The application must:

1. Render only the available tools.
2. Extract the first complete function block.
3. Validate the exact function name and argument schema.
4. Enforce permissions and request confirmation for sensitive actions.
5. Execute the tool outside the model.
6. Return the tool result in a new turn.

Measured Improvements and Scope

This adapter improved every task-quality metric reported against the base model:

• Parseable calls: 1.33% -> 99.33%
• Valid available-tool names: 1.33% -> 97.00%
• Expected-tool selection: 1.33% -> 92.67%
• Exact arguments: 15.00% -> 65.33%
• Argument-key overlap: 0.33% -> 75.17%
• No repetition: 99.67% -> 100.00%
• Natural clean termination: 0.00% -> 15.00%

The remaining gap to 100% is residual error after a large improvement, not a regression caused by fine-tuning.

Deployment Notes

• This is intentionally an adapter package; load it with openbmb/MiniCPM5-1B, or use the merged repository for standalone inference.
• Schema validation, permission checks and confirmation for sensitive actions are standard requirements for every tool-calling model, including the base model.
• Exact-argument accuracy improved by 50.33 percentage points. Applications should still validate required fields, types and ranges before execution.
• Valid-name accuracy improved by 95.67 percentage points. Rare near misses can still occur on unseen or unusually named tools.
• Natural termination improved from 0% to 15%; MiniCPM5's official parser-based serving path extracts the completed call rather than relying solely on natural EOS.
• The external evaluation is custom rather than an official ToolACE/BFCL leaderboard submission.

Version History

The current branch contains the July 2026 Nemotron SFT+DPO adapter and current external evaluation artifacts. Older adapter and evaluation states remain recoverable from Hugging Face commit history.

Limitations