解决Qwen3.5-4B模型在LlamaIndex中输出思维链的问题

1. 问题背景与现象分析

最近在使用LlamaIndex框架加载本地Qwen3.5-4B模型时，遇到了一个有趣的现象：模型在回答问题时总是先输出完整的思维推理过程（"Here's a thinking process..."），而不是直接给出答案。这个问题在Qwen3.5-2B版本上却不存在。作为一名长期从事大模型应用开发的工程师，我决定深入探究这个问题并找到解决方案。

1.1 问题复现

首先让我们看看问题的具体表现。使用以下基础代码加载Qwen3.5-4B模型：

python复制from llama_index.core.llms import ChatMessage
from llama_index.llms.huggingface import HuggingFaceLLM

llm = HuggingFaceLLM(
    model_name="/path/to/Qwen3.5-4B",
    tokenizer_name="/path/to/Qwen3.5-4B",
    model_kwargs={"trust_remote_code": True},
    tokenizer_kwargs={"trust_remote_code": True}
)
rsp = llm.chat(messages=[ChatMessage(content="猪八戒是什么？")])

执行后，模型输出会包含类似这样的内容：

code复制<think>猪八戒是中国古典名著《西游记》中的角色...</think>
猪八戒是《西游记》中唐僧的二徒弟...

1.2 问题根源

经过分析，发现这是Qwen3系列模型从4B版本开始引入的一个特性——内置"思维链"能力。模型默认会在回答前输出<think>...</think>推理块。而2B模型由于参数量较小，没有这个功能，所以表现正常。

注意：思维链(Chain-of-Thought)是大模型中常见的技术，通过展示推理过程来提高答案的可解释性。但在实际应用中，我们往往只需要最终答案。

2. 解决方案探索

2.1 第一次尝试：禁用thinking模式

查阅Qwen的文档发现，其tokenizer的apply_chat_template方法有一个enable_thinking参数。于是尝试这样修改：

python复制_tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)

def messages_to_prompt(messages):
    msg_list = [{"role": m.role.value, "content": m.content} for m in messages]
    return _tokenizer.apply_chat_template(
        msg_list, tokenize=False, add_generation_prompt=True,
        enable_thinking=False
    )

llm = HuggingFaceLLM(
    ...,
    messages_to_prompt=messages_to_prompt,
    generate_kwargs={"max_new_tokens": 512, "temperature": 0.7},
)

结果：输出变成了乱码，中英文混杂的混乱文本。

原因：LlamaIndex内部在messages_to_prompt的结果上又套了一层completion_to_prompt，导致prompt被双重包装，模型接收到的输入格式错乱。

2.2 第二次尝试：修复prompt处理流程

为了解决双重包装问题，我们添加了completion_to_prompt函数，并尝试去除残留的<think>标签：

python复制def messages_to_prompt(messages):
    msg_list = [{"role": m.role.value, "content": m.content} for m in messages]
    prompt = _tokenizer.apply_chat_template(
        msg_list, tokenize=False, add_generation_prompt=True,
        enable_thinking=False
    )
    # 去除think标签
    prompt = re.sub(r'<think>.*?</think>\s*', '', prompt, flags=re.DOTALL)  
    return prompt

def completion_to_prompt(completion):
    return completion  # 透传，不再包装

llm = HuggingFaceLLM(
    ...,
    messages_to_prompt=messages_to_prompt,
    completion_to_prompt=completion_to_prompt,
    max_new_tokens=512,
    generate_kwargs={"temperature": 0.7, "do_sample": True},
)

结果：prompt格式正确了，但模型仍然输出<think>内容。

原因：问题不在输入端，而在输出端。模型在生成阶段自主产生了<think>token。

2.3 第三次尝试：token级别控制

最终的解决方案是在生成阶段直接屏蔽<think>token：

python复制# 获取<think>的token id
think_token_ids = _tokenizer.encode("<think>", add_special_tokens=False)

llm = HuggingFaceLLM(
    ...,
    generate_kwargs={
        "temperature": 0.7,
        "do_sample": True,
        "suppress_tokens": think_token_ids,  # 关键：屏蔽<think> token
    },
)

结果：问题完美解决，模型直接输出答案。

3. 完整解决方案

3.1 最终代码实现

以下是经过多次调试后的完整代码：

python复制import re
from transformers import AutoTokenizer
from llama_index.core.llms import ChatMessage
from llama_index.llms.huggingface import HuggingFaceLLM

model_path = "/path/to/Qwen3.5-4B"
_tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)

# 获取<think>的token id
think_token_ids = _tokenizer.encode("<think>", add_special_tokens=False)

def messages_to_prompt(messages):
    msg_list = []
    for m in messages:
        role = m.role.value if hasattr(m.role, 'value') else str(m.role)
        msg_list.append({"role": role, "content": m.content})
    return _tokenizer.apply_chat_template(
        msg_list,
        tokenize=False,
        add_generation_prompt=True,
        enable_thinking=False
    )

def completion_to_prompt(completion):
    return completion

llm = HuggingFaceLLM(
    model_name=model_path,
    tokenizer_name=model_path,
    model_kwargs={"trust_remote_code": True},
    tokenizer_kwargs={"trust_remote_code": True},
    messages_to_prompt=messages_to_prompt,
    completion_to_prompt=completion_to_prompt,
    max_new_tokens=512,
    generate_kwargs={
        "temperature": 0.7,
        "do_sample": True,
        "suppress_tokens": think_token_ids,
    },
)

rsp = llm.chat(messages=[ChatMessage(role="user", content="猪八戒是什么？")])
print(rsp)

3.2 关键点解析

1. tokenizer预加载：提前加载tokenizer以获取<think>的token ID
2. 消息格式处理：正确处理ChatMessage的role字段，兼容不同版本
3. prompt双重保险：
   • enable_thinking=False禁用thinking模式
   • suppress_tokens阻止<think>token生成
4. 参数优化：
   • max_new_tokens=512控制生成长度
   • temperature=0.7平衡创造性和准确性

4. 经验总结与扩展

4.1 问题排查心得

1. 分层调试法：先确认是输入问题还是生成问题

   • 检查实际发送给模型的prompt内容
   • 单独测试模型生成行为

2. 版本兼容性：

   • Qwen3.5-4B和2B行为不同
   • 不同版本的LlamaIndex处理prompt方式可能不同

3. 备选方案：

   • 如果suppress_tokens不被支持，可以尝试bad_words_ids
   • 也可以考虑后处理过滤<think>内容

4.2 性能优化建议

1. 缓存tokenizer：避免重复加载
2. 批量处理：对于多个消息，可以批量处理提高效率
3. 参数调优：
   • 根据任务调整temperature
   • 合理设置max_new_tokens避免过长响应

4.3 适用性说明

1. 模型范围：适用于Qwen3系列所有带thinking功能的模型（4B及以上）
2. 框架版本：
   • 测试于LlamaIndex 0.10.x
   • 不同版本可能需要调整
3. 替代方案：如果不想修改代码，也可以考虑使用模型微调来改变默认行为

在实际项目中，这种精细控制模型行为的能力非常重要。通过这次调试，我不仅解决了具体问题，还深入理解了LlamaIndex和Qwen模型的交互机制。这种经验对于处理其他类似的大模型集成问题也很有参考价值。