XTuner 微调模型命令行对话实战：`xtuner chat` 全面指南-平芜编程栈

XTuner 微调模型命令行对话实战：`xtuner chat`全面指南

【免费下载链接】xtunerA Next-Generation Training Engine Built for Ultra-Large MoE Models项目地址: https://gitcode.com/GitHub_Trending/xt/xtuner

导读

微调完成后，如何快速验证模型效果、与模型进行交互式对话？本文围绕 XTuner 官方中文文档《与微调后的大语言模型 LLMs 对话》展开，系统讲解xtuner chat命令的完整用法。你将掌握：如何加载基座模型 + LoRA/QLoRA 适配器进行对话、如何按微调数据集类型选用正确的提示词模板（Prompt Template）与系统模板（System Template）、如何开启流式输出、以及如何让模型具备调用计算器、方程求解器、网页搜索等插件能力，甚至以 Lagent ReAct 智能体模式与模型对话。文中所有命令参数均结合仓库源码（chat.py）逐一剖析，确保每条命令可复制、可运行。

一、`xtuner chat`命令概述

xtuner chat是 XTuner 提供的命令行交互式对话工具，用于直接加载 Hugging Face 上的基座模型（base model）与微调产出的 LoRA/QLoRA 适配器（adapter），在终端中与微调后的模型进行多轮对话。它对应的入口注册在 entry_point.py，实际实现位于 chat.py。

其核心工作流程（从 chat.py 的main()函数可见）如下：

通过AutoModelForCausalLM.from_pretrained加载基座模型，并通过PeftModel.from_pretrained加载微调适配器（来自peft库）；
根据--prompt-template/--system-template将用户输入包装成与训练阶段一致的对话格式（模板定义见 templates.py）；
借助transformers的GenerationConfig配置采样参数，配合TextStreamer实现流式输出；
通过StopWordStoppingCriteria（见 stop_criteria.py）识别模板中定义的特殊结束词，及时终止生成；
支持两轮生成式的插件调用（Plugin）与基于 Lagent 的 ReAct 智能体对话两种增强模式。

xtuner chat既支持纯文本大模型，也支持视觉语言模型（通过--llava参数加载视觉编码器与投影层），本指南以文档主线的文本模型对话为主。

命令基本形态

xtuner chat $LLM --adapter $ADAPTER --prompt-template $PROMPT_TEMPLATE --system-template $SYSTEM_TEMPLATE

其中：

$LLM：基座模型名或本地路径，例如internlm/internlm-7b、meta-llama/Llama-2-7b-hf；
$ADAPTER：微调得到的适配器名或路径，例如xtuner/internlm-7b-qlora-oasst1（XTuner 发布在 Hugging Face 上的官方适配器仓库）；
$PROMPT_TEMPLATE与$SYSTEM_TEMPLATE：分别对应训练时使用的对话格式与系统提示词，取值需与微调数据集匹配（详见下文）。

提示：--adapter与--llava是互斥参数；--system与--system-template也是互斥参数，二者只能二选一（见 chat.py 的参数定义）。

二、完整参数参考：从源码理解每个选项

下面依据 chat.py 中parse_args()的参数定义，汇总xtuner chat的全部常用参数：

参数	类型/取值	默认值	作用说明
`model_name_or_path`	位置参数	必填	Hugging Face 模型名或本地路径（基座模型）
`--adapter`	字符串	`None`	LoRA/QLoRA 适配器名或路径，与`--llava`互斥
`--llava`	字符串	`None`	LLaVA 视觉模型名或路径，与`--adapter`互斥
`--visual-encoder`	字符串	`None`	视觉编码器路径（`--llava`目录中无`visual_encoder`子目录时必填）
`--visual-select-layer`	整数	`-2`	选择视觉编码器第几层 hidden states 作为视觉特征
`--image`	字符串	`None`	多模态对话时输入的图片路径
`--torch-dtype`	`fp16/bf16/fp32/auto`	`fp16`	模型加载时的 torch dtype
`--prompt-template`	见 templates.py 的`PROMPT_TEMPLATE`键	`None`	指定对话提示词模板
`--system`	字符串	`None`	直接指定系统提示词文本，与`--system-template`互斥
`--system-template`	见`SYSTEM_TEMPLATE`键	`None`	指定系统提示词模板名
`--bits`	`4/8/None`	`None`	LLM 量化位数；`4`使用 BitsAndBytes NF4 量化，`8`使用 8bit 加载
`--bot-name`	字符串	`BOT`	机器人名称，会代入模板中的`{bot_name}`占位符
`--with-plugins`	`calculate/solve/search`可多选	`None`	启用插件（计算器、方程求解器、网页搜索）
`--no-streamer`	开关	`False`	关闭流式输出，改为整段打印
`--lagent`	开关	`False`	以 Lagent ReAct 智能体模式对话
`--stop-words`	字符串列表	`[]`	自定义停止词，会与模板自带的`STOP_WORDS`合并
`--offload-folder`	字符串	`None`	权重卸载目录，用于显存不足时
`--max-new-tokens`	整数	`2048`	生成的最大新 token 数
`--temperature`	浮点数	`0.1`	采样温度；为 0 时`do_sample=False`，走贪心解码
`--top-k`	整数	`40`	top-k 过滤保留的最高概率 token 数
`--top-p`	浮点数	`0.75`	核采样概率阈值
`--repetition-penalty`	浮点数	`1.0`	重复惩罚系数，1.0 表示不惩罚
`--seed`	整数	`0`	随机种子，保证生成可复现

关键参数源码级解读

--bits的量化配置：当指定--bits 4时，chat.py 会构造BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_compute_dtype=torch.float16, bnb_4bit_use_double_quant=True, bnb_4bit_quant_type='nf4')；指定--bits 8时则设置load_in_8bit=True。这便于在单卡显存有限的情况下加载大模型。
生成参数与温度的关系：GenerationConfig中do_sample = args.temperature > 0，即默认temperature=0.1时走采样生成；若想完全确定性输出，可显式传--temperature 0。
停止词机制：每个模板可定义STOP_WORDS（如 InternLM 的['<eoa>']、MOSS 的['<eoc>', '<eom>']），配合用户--stop-words一起构造StoppingCriteriaList；StopWordStoppingCriteria在解码文本末尾匹配到停止词时终止生成，避免模型吐出多余的模板后缀。
多轮对话状态：对话历史会累积在inputs中并持续拼接到下一次输入，输入EXIT退出、输入RESET清空历史（对应 chat.py 的get_input与主循环）；当累积长度超过--max-new-tokens时，程序会自动清空历史并给出提示。

三、与微调后的 InternLM 对话

InternLM-7B（qlora 适配器）

以下命令均在 xtuner/configs/internlm/internlm_7b 目录中对应配置文件训练所得适配器的基础上演示。不同数据集微调出的模型，需要搭配不同的系统模板（--system-template）才能复现训练时的任务设定。

InternLM-7B，oasst1（通用对话）

xtuner chat internlm/internlm-7b --adapter xtuner/internlm-7b-qlora-oasst1 --prompt-template internlm_chat

InternLM-7B，Arxiv Gentitle（论文标题生成）

xtuner chat internlm/internlm-7b --adapter xtuner/internlm-7b-qlora-arxiv-gentitle --prompt-template internlm_chat --system-template arxiv_gentile

InternLM-7B，Colorist（配色方案生成）

xtuner chat internlm/internlm-7b --adapter xtuner/internlm-7b-qlora-colorist --prompt-template internlm_chat --system-template colorist

InternLM-7B，Alpaca-enzh（指令跟随）

xtuner chat internlm/internlm-7b --adapter xtuner/internlm-7b-qlora-alpaca-enzh --prompt-template internlm_chat --system-template alpaca

InternLM-7B，MSAgent（支持 Lagent ReAct 智能体）
```
export SERPER_API_KEY="xxx" # 请从 https://serper.dev 获得 API_KEY，以此支持谷歌搜索！ xtuner chat internlm/internlm-7b --adapter xtuner/internlm-7b-qlora-msagent-react --lagent
```
该适配器对应的训练配置为 internlm2_7b_qlora_msagent_react_e3_gpu8.py，基于damo/MSAgent-Bench数据集、采用 ReAct 格式（Thought / Action / Action Input / Response / Final Answer）微调。加载后可通过--lagent进入智能体模式，模型可调用GoogleSearch工具获取实时信息。注意：--lagent模式要求先设置环境变量SERPER_API_KEY（源码中缺失该变量会直接报错退出），并且该模式下不加载trust_remote_code与插件模板逻辑。

InternLM-Chat-7B

InternLM-Chat-7B，oasst1

xtuner chat internlm/internlm-chat-7b --adapter xtuner/internlm-chat-7b-qlora-oasst1 --prompt-template internlm_chat

InternLM-Chat-7B，Alpaca-enzh

xtuner chat internlm/internlm-chat-7b --adapter xtuner/internlm-chat-7b-qlora-alpaca-enzh --prompt-template internlm_chat --system-template alpaca

InternLM-20B

InternLM-20B，oasst1

xtuner chat internlm/internlm-20b --adapter xtuner/internlm-20b-qlora-oasst1 --prompt-template internlm_chat

InternLM-20B，Arxiv Gentitle

xtuner chat internlm/internlm-20b --adapter xtuner/internlm-20b-qlora-arxiv-gentitle --prompt-template internlm_chat --system-template arxiv_gentile

InternLM-20B，Colorist

xtuner chat internlm/internlm-20b --adapter xtuner/internlm-20b-qlora-colorist --prompt-template internlm_chat --system-template colorist

InternLM-20B，Alpaca-enzh

xtuner chat internlm/internlm-20b --adapter xtuner/internlm-20b-qlora-alpaca-enzh --prompt-template internlm_chat --system-template alpaca

InternLM-20B，MSAgent（支持 Lagent ReAct）

export SERPER_API_KEY="xxx" # 请从 https://serper.dev 获得 API_KEY，以此支持谷歌搜索！ xtuner chat internlm/internlm-20b --adapter xtuner/internlm-20b-qlora-msagent-react --lagent

InternLM-Chat-20B

InternLM-Chat-20B，oasst1

xtuner chat internlm/internlm-chat-20b --adapter xtuner/internlm-chat-20b-qlora-oasst1 --prompt-template internlm_chat

InternLM-Chat-20B，Alpaca-enzh

xtuner chat internlm/internlm-chat-20b --adapter xtuner/internlm-chat-20b-qlora-alpaca-enzh --prompt-template internlm_chat --system-template alpaca

从源码 templates.py 可见，internlm_chat模板格式为：<|System|>:{system}\n<|User|>:{input}<eoh>\n<|Bot|>:，并以<eoa>作为停止词。因此使用 InternLM 系列时务必指定--prompt-template internlm_chat，保证输入格式与训练时一致。

四、与微调后的 Llama-2 对话

前置条件：Llama-2 系列为 gated 模型，使用前必须先执行huggingface-cli login输入你的 Hugging Face 访问令牌（access token）；如何获取令牌可参考 Hugging Face 官方文档。

Llama-2-7B，MOSS-003-SFT（支持调用插件）

export SERPER_API_KEY="xxx" # 请从 https://serper.dev 获得 API_KEY，以此支持谷歌搜索！ xtuner chat meta-llama/Llama-2-7b-hf --adapter xtuner/Llama-2-7b-qlora-moss-003-sft --bot-name Llama2 --prompt-template moss_sft --system-template moss_sft --with-plugins calculate solve search --no-streamer

这条命令是文档中最完整的一条，涉及三类机制：

提示词与系统模板均使用moss_sft：在 chat.py 中，一旦使用--with-plugins，会断言args.prompt_template == args.system_template == 'moss_sft'，因此插件模式只支持 MOSS-SFT 模板。moss_sft模板格式为<|Human|>: {input}<eoh>\n，系统提示词由SYSTEM_TEMPLATE['moss_sft']生成，其中会按启用情况动态声明- Inner thoughts: enabled.、- Web search: enabled. API: Search(query)、- Calculator: enabled. API: Calculate(expression)、- Equation solver: enabled. API: Solve(equation)等能力项（未启用的能力会替换为 disabled）。
--with-plugins calculate solve search：启用计算、方程求解、网页搜索三个插件。生成过程中模型输出<|Commands|>:...<eoc>格式的调用指令后，由 api.py 正则解析并调用对应插件执行，再将<|Results|>:结果拼接回上下文进行第二次生成，最终输出带工具结果的完整回答。
--no-streamer：关闭流式输出。因为插件模式下需要两段式生成，关闭流式可避免中间过程被逐字打印，最终整段展示结果。

各插件的实现如下：

Calculate(expression)（见 calculate.py）：对表达式做eval求值，支持^转**，结果保留两位小数，失败返回No result.；
Solve(equation)（见 solve.py）：基于sympy求解方程组，自动提取变量、支持pi替换、支持多个解及表达式代入验证；
Search(query)（见 search.py）：通过 Serper API 调用谷歌搜索，取前 10 条 organic 结果的 snippet 作为上下文返回给模型。

Llama-2-7B，MSAgent（支持 Lagent ReAct）

export SERPER_API_KEY="xxx" # 请从 https://serper.dev 获得 API_KEY，以此支持谷歌搜索！ xtuner chat meta-llama/Llama-2-7b-hf --adapter xtuner/Llama-2-7b-qlora-msagent-react --lagent

五、与微调后的 Qwen 对话

Qwen-7B，MOSS-003-SFT（支持调用插件）

export SERPER_API_KEY="xxx" # 请从 https://serper.dev 获得 API_KEY，以此支持谷歌搜索！ xtuner chat Qwen/Qwen-7B --adapter xtuner/Qwen-7B-qlora-moss-003-sft --bot-name Qwen --prompt-template moss_sft --system-template moss_sft --with-plugins calculate solve search

与 Llama-2 的 MOSS 插件命令相比，这里没有加--no-streamer，即默认开启流式输出。由于 MOSS-SFT 适配器使用--bot-name指定机器人名（Llama2/Qwen），系统提示词中的{bot_name}占位符会被替换为对应名称。

六、提示词模板与系统模板速查

支持的提示词模板（`PROMPT_TEMPLATE`）

定义于 templates.py 的PROMPT_TEMPLATE中，每个模板包含SYSTEM、INSTRUCTION、SEP（轮次分隔符）、STOP_WORDS（停止词），部分模板还含SUFFIX/SUFFIX_AS_EOS。常用模板及关键格式如下：

模板名	指令格式（`INSTRUCTION`）	停止词	适用模型
`internlm_chat`	`<\\|User\\|>:{input}<eoh>\n<\\|Bot\\|>:`	`<eoa>`	InternLM-7B/20B 等
`internlm2_chat`	`<\\|im_start\\|>user\n{input}<\\|im_end\\|>\n<\\|im_start\\|>assistant\n`	`<\\|im_end\\|>`	InternLM2
`moss_sft`	`<\\|Human\\|>: {input}<eoh>\n`	`<eoc>`,`<eom>`	MOSS-003-SFT
`llama2_chat`	`[INST] {input} [/INST]`	—	Llama-2 Chat
`qwen_chat`	`<\\|im_start\\|>user\n{input}<\\|im_end\\|>\n<\\|im_start\\|>assistant\n`	`<\\|im_end\\|>`,`<\\|endoftext\\|>`	Qwen
`default`	`<\\|User\\|>:{input}\n<\\|Bot\\|>:`	—	通用
`chatglm2`/`chatglm3`	轮次化`问/答`或`<\\|user\\|>`格式	—	ChatGLM
`baichuan_chat`/`baichuan2_chat`	`<reserved_102>{input}<reserved_103>`等	—	Baichuan
`deepseek_v2`	`User: {input}\n\nAssistant:`	`<｜end▁of▁sentence｜>`	DeepSeek-V2
`llama3_chat`	`<\\|start_header_id\\|>user<\\|end_header_id\\|>\n\n{input}<\\|eot_id\\|>...`	`<\\|eot_id\\|>`	Llama-3
`phi3_chat`	`<\\|user\\|>\n{input}<\\|end\\|>\n<\\|assistant\\|>\n`	`<\\|end\\|>`	Phi-3
`gemma`	`<start_of_turn>user\n{input}<end_of_turn>\n<start_of_turn>model\n`	`<end_of_turn>`	Gemma

选错模板会导致输入格式与训练时不匹配，对话效果大打折扣。文档中的所有示例均显式指定了模板，请勿省略。

支持的系统模板（`SYSTEM_TEMPLATE`）

SYSTEM_TEMPLATE中预置了与各微调数据集对应的任务提示词，--system-template的取值即其键名：

模板名	任务设定	对应数据集/适配器
`moss_sft`	AI 助手 + 工具能力声明（内省、搜索、计算、方程求解）	MOSS-003-SFT
`alpaca`	指令跟随（instruction following）	Alpaca-enzh
`arxiv_gentile`	论文标题生成专家	Arxiv Gentitle
`colorist`	专业配色设计师	Colorist
`coder`	专业程序员（生成代码）	代码类数据集
`lawyer`	中国律师（中文法律问答）	Lawyer
`medical`	医生（医学问答）	Medical
`sql`	SQL 专家（生成查询语句）	SQL

这些模板会通过--system-template传入，在首轮对话时作为SYSTEM段拼入 prompt（见 chat.py 中if 'SYSTEM' in template and n_turn == 0的分支逻辑）；--system参数则用于直接自定义一段系统文本，两者互斥。

七、交互方式与进阶技巧

终端交互命令

进入对话后：

输入内容：支持多行输入，连续两次回车结束当前输入；
输入EXIT：退出对话；
输入RESET：清空多轮历史，重新开始（对应 chat.py 中主循环对RESET的处理）。

显存不足时的处理

使用--bits 4或--bits 8对模型做量化加载，显著降低显存占用；
使用--offload-folder指定权重卸载目录，把暂时不用的权重卸载到磁盘。

复现性与停止词

指定--seed可复现同一输入的生成结果；
当模板自带的停止词不够用时，可用--stop-words追加自定义停止词，配合StopWordStoppingCriteria在生成到指定词时立即终止。

多模态对话（`--llava`）

若使用视觉语言模型，命令形态为：

xtuner chat $LLM --llava $LLAVA --visual-encoder $VISUAL_ENCODER --image $IMAGE --prompt-template $PROMPT_TEMPLATE --system-template $SYSTEM_TEMPLATE

--llava目录下可含visual_encoder、llm_adapter、visual_encoder_adapter、projector等子目录，源码会按子目录结构自动加载 CLIP 视觉编码器、LLM 适配器与投影层；若目录中没有visual_encoder子目录，则必须显式指定--visual-encoder。视觉 token 通过IMAGE_TOKEN_INDEX（即<image>占位符）嵌入输入序列，并由 utils.py 的prepare_inputs_labels_for_multimodal处理为多模态输入。

八、从微调配置到对话验证的完整链路

理解xtuner chat的模板参数从何而来，能帮助你为任意新微调模型正确配置对话命令。以 MSAgent-ReAct 为例，训练配置 internlm2_7b_qlora_msagent_react_e3_gpu8.py 中：

训练时使用PROMPT_TEMPLATE.default作为对话格式，并通过自定义SYSTEM提示词描述工具调用规范（Thought/Action/Action Input/Response/Final Answer）；
训练数据来自damo/MSAgent-Bench，映射函数为msagent_react_map_fn；
训练过程中还通过EvaluateChatHook（见 evaluate_chat_hook.py）定期用evaluation_inputs（如“上海明天天气怎么样？”）评估生成效果。

这也解释了为什么文档中所有命令都要显式携带--prompt-template与--system-template：它们正是微调阶段模板设定的“回放”，只有模板一致，微调成果才能被正确唤起。

结语

xtuner chat让“微调—验证”闭环变得轻量直接：一条命令即可将基座模型与 LoRA/QLoRA 适配器组合成可对话的模型，并通过模板、插件与智能体三种能力层次满足不同场景。无论是普通 SFT 模型的开箱即聊、MOSS-SFT 模型的工具调用，还是 MSAgent 模型的 Lagent ReAct 智能体交互，本文给出的命令与源码级参数说明都能帮助你快速上手、按需扩展。建议结合仓库中的 templates.py 与 chat.py 按图索骥，为自有微调产物定制专属对话命令。

【免费下载链接】xtunerA Next-Generation Training Engine Built for Ultra-Large MoE Models项目地址: https://gitcode.com/GitHub_Trending/xt/xtuner

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

XTuner 微调模型命令行对话实战：`xtuner chat` 全面指南