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 的异常行为，这是许多开发者容易踩坑的地方：
- 架构矛盾：Qwen3-Coder 仅以 Instruct 模型发布，缺乏原生 FIM 能力。
- 特殊处理机制：自 Twinny 4.2.3 版本起，系统检测到
qwen3-coder标签时，会自动切换至 ChatML 格式。- 系统会在 Prompt 中注入系统指令：
You are a code completion assistant. - 对于 Ollama，设置
raw: true以防止模型二次应用模板。 - 对于 LiteLLM，将请求以消息列表形式传递。
- 系统会在 Prompt 中注入系统指令：
- 输出规范：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 官方技术团队
