Twinny 发布 FIM 模型选择指南：标签决定提示词格式

在 AI 辅助编程工具 Twinny 中，选择正确的代码补全模型（Completion Model）并非简单的“选最强”逻辑，而是一场关于提示词工程（Prompt Engineering）与模型架构的精密匹配游戏。官方最新指南指出：模型标签上的名称直接决定了 Twinny 使用的 Prompt 模板。

核心原则：Base 而非 Instruct

代码补全依赖于 Fill-in-the-Middle (FIM) 机制，即模型需要在前缀（Prefix）和后缀（Suffix）之间填充缺失的文本（Middle）。

• Base/Code 变体：仅此类模型支持真正的代码补全。例如 qwen2.5-coder:1.5b-base 或 codellama:7b-code。
• Instruct 变体：通常用于对话或解释，若强行用于 FIM 补全，模型往往会生成解释性文字而非代码，导致功能失效。

关键发现：Qwen3-Coder 的特殊性

本次指南特别强调了 Qwen3-Coder 的异常行为，这是许多开发者容易踩坑的地方：

1. 架构矛盾：Qwen3-Coder 仅以 Instruct 模型发布，缺乏原生 FIM 能力。
2. 特殊处理机制：自 Twinny 4.2.3 版本起，系统检测到 qwen3-coder 标签时，会自动切换至 ChatML 格式。
   • 系统会在 Prompt 中注入系统指令：You are a code completion assistant.
   • 对于 Ollama，设置 raw: true 以防止模型二次应用模板。
   • 对于 LiteLLM，将请求以消息列表形式传递。
3. 输出规范：Qwen3-Coder 会强制在 Markdown 代码块中输出代码，且 Twinny 会自动剥离首尾的 Markdown 标记。此外，模型会将未完成的单词视为拼写错误，因此 Twinny 会将其作为上下文传递，而非直接填入。

模板细节与避坑指南

Twinny 通过硬编码的 MODEL_NAME_HINTS 列表自动匹配模型模板，顺序至关重要（先匹配 codellama 再匹配 llama）。

1. 空格的重要性

• CodeLlama 特例：官方文档指出，CodeLlama 对 FIM 模板中的空格非常敏感。Twinny 在 <SUF> 和 {suffix} 之间保留了空格（<SUF> {suffix}），而某些参考格式可能缺失。缺少这个空格会导致模型忽略中间区域，甚至重新输出整个文件。

2. 停止符（Stop Tokens）的匹配

• 不同的模型家族拥有不同的停止符标记（如 CodeLlama 的 <EOT> 及三个标记，Qwen 的十个标记）。
• 错误后果：若模板匹配错误（例如将非 CodeLlama 变体误判为 CodeLlama 格式），模型不仅无法理解 Prompt 结构，其真实的结束标记也不在 Twinny 的停止列表中，导致补全过程无限循环或截断。

3. 空后缀处理

• 当光标位于文件末尾（无后缀）时，Twinny 仅发送前缀。这是因为 Base 模型在纯文本前缀上表现稳定，而带有空后缀的标记会让某些模型（特别是 CodeLlama）立即停止。

4. 文件上下文（File Context）

• 部分模型（Qwen2.5-Coder, StarCoder2, Granite 等）支持通过 Token 识别文件名，将相邻文件作为独立块传入。
• 其他模型则需将文件作为注释块处理。
• 注意：此功能默认关闭以节省延迟，需手动开启 twinny.fileContextEnabled。

总结与建议

• 首选模型：建议从 qwen2.5-coder:1.5b-base 开始，平衡速度与效果；硬件允许可升级至 7B 版本。
• 避坑：34B 的 CodeLlama 在 FIM 任务中表现不佳，切勿盲目追求大参数。
• 调试：若补全失败，请检查 Twinny 输出通道是否开启 Debug，并手动验证模型名称是否触发了正确的模板逻辑。

“模型的选择不仅仅是关于模型本身，更是关于提示词格式。Twinny 从模型名称中自动完成这一决策，但理解其背后的机制对于解决疑难杂症至关重要。” —— Twinny 官方技术团队