用 Twinny 在 VS Code 中搭建本地 AI 补全与对话环境

Twinny 是一款 VS Code 扩展，作用是把本地或远程的模型服务器接到编辑器里，让代码补全、内联编辑、侧边栏对话、Agent 模式这些能力都跑在你选定的模型上。它本身不训练模型，也不绑定某一家服务商，而是负责「发现服务器、分配任务、发起请求、把结果送回编辑器」这一层。适合两类人：一是希望代码不出本机、用本地显卡跑模型的开发者；二是已经有自建推理服务、想把它接进 VS Code 工作流的团队。如果你只是想先看看它长什么样、跑通一次最小链路，可以配合 Twinny 的说明页对照阅读。

下面这条路径以 Ollama 作为本地服务器，因为它是最常见的本地推理入口。换成别的服务器，只要服务已经在跑，后续步骤基本一致，区别只在端口和模型命名。

准备工作

开始之前需要确认三件事：编辑器、模型服务器、以及至少两个模型。

• VS Code：Twinny 以扩展形式安装，可以从 Marketplace 或 Open VSX 获取。两个渠道的版本节奏可能不同，具体以扩展页面当前显示的信息为准。
• Ollama：从 Ollama 官网安装，安装完成后它作为后台服务常驻运行，默认监听 11434 端口。这个端口号是后面自动发现能否成功的关键。
• 模型：需要区分「对话模型」和「补全模型」，两者不是同一个东西，下面会解释。

为什么需要两个模型

这是初次配置最容易踩空的地方。对话场景需要的是 instruct 模型，也就是经过指令微调、能听懂「帮我加错误处理」这类要求的模型；而代码补全场景需要的是经过 fill-in-the-middle 训练的模型，在多数模型家族里对应 base 变体或专门的 code 变体。用 instruct 模型去做补全，它倾向于「说话」而不是「续写」，补出来的内容往往是一段解释而不是代码。

补全模型还要优先考虑小尺寸。补全是在你敲字的间隙触发的，速度比深度重要得多，1.5B 级别的模型在多数笔记本上能在很短时间内给出结果。对话模型则可以选大一些的，因为对话允许等待。

拉取模型

在终端里执行下面两条命令，分别拉取对话模型和补全模型：

ollama pull qwen2.5-coder:7b-instruct
ollama pull qwen2.5-coder:1.5b-base

如果还希望对话能对整个工作区做语义检索，再额外拉一个嵌入模型：

ollama pull nomic-embed-text

嵌入模型不是必需的。没有它，对话仍然可用，只是 @workspace 这类跨项目搜索能力会缺失。

如果机器内存不足 8 GB，或者没有独立 GPU，不要硬上 7B 模型，应改用更小的模型组合。模型尺寸与显存、内存的匹配关系需要自己按硬件情况判断，具体可选型号以模型库当前提供的信息为准。

操作步骤

第一步：安装 twinny 扩展

在 VS Code 的扩展视图里搜索 twinny 并安装，或者从 Open VSX 安装。安装完成后不需要立刻配置任何东西，先让扩展自己去探测环境。

第二步：让 twinny 自动发现服务器

首次运行时，twinny 会扫描本地常用端口。Ollama 在 11434 上应答，于是 twinny 读取它的模型列表，自动创建三类 Provider，并通过通知告知结果：

• 一个对话 Provider，指向 instruct 模型；
• 一个自动补全 Provider，指向 base 模型；
• 如果检测到嵌入模型，再创建一个嵌入 Provider。

这里有一个设计取舍值得注意：如果某个任务找不到合适类型的模型，twinny 会把它留空，而不是随便指一个不匹配的模型上去。所以「某一栏是空的」通常不是故障，而是它判断没有合适的候选。

但自动匹配是靠模型名字判断的，这就带来一个已知的偏差：自动补全取的是模型列表里第一个名字中含 code 或 coder 的模型，而这个模型完全可能是 qwen2.5-coder:7b-instruct。也就是说，补全栏有可能被错配成 instruct 模型。安装完成后务必去确认补全栏实际拿到的是哪个模型，如果是 instruct 变体，手动改成 base 模型。

如果探测时没有任何服务应答——比如 Ollama 还没启动，或者跑在非默认端口上——twinny 会提示一次，并给出一个「Choose a provider」按钮。此时 Providers 标签页会显示一个欢迎界面，上面有三个入口：重新搜索、手动选择 Provider、导入 Provider 配置。你可以先把服务器启动起来再点重新搜索，也可以直接选 Ollama 预设然后手动填端口号。

第三步：验证配置是否生效

从活动栏打开 twinny 侧边栏，进入 Providers 标签页（机器人图标）。页面按对话、自动补全、嵌入分成几个区块，每个区块显示当前生效的 Provider。空区块意味着该任务没有配置任何模型。

每个 Provider 卡片上都有一个「Test provider」按钮。点它会向服务器发一个小请求，返回成功，或者原样显示服务器给出的错误信息。这一步比看配置项更可靠，因为错误信息来自服务端本身，能直接指出是端口不通、模型不存在还是别的问题。

状态栏也有反馈：twinny 空闲时显示 </>，生成过程中显示转圈动画。点击状态栏图标可以调出快捷操作。

第四步：逐个试用功能

代码补全。打开一个源码文件，开始写一个函数。短暂停顿后，光标后会浮出一段灰色建议，按 Tab 接受。也可以先写一行注释描述接下来几行要做什么，然后在下一行停住，观察是否给出多行建议。补全的触发依赖停顿，敲得太快不会触发。

内联编辑。选中若干行，按 Ctrl+I（macOS 上是 Cmd+I），输入指令，例如「add error handling」，回车。改动会以 diff 形式流式呈现。按 Ctrl+Shift+Enter 接受，按 Ctrl+Shift+Backspace 拒绝。这个功能适合对已有代码做局部改写，比在对话里贴代码再复制回来更顺手。

对话。在侧边栏输入 @ 会弹出可附加的上下文类型，包括：某个文件、某个符号、当前问题列表、git diff、终端最后一次输出，以及 @workspace（对工作区索引做检索）。附加好上下文再提问，回答里的代码块带有 apply、insert、copy、new file、terminal 几个操作按钮，可以直接把结果落回编辑器或终端。

修复报错。把光标放在有红色波浪线的位置，打开灯泡菜单，选择「Fix with Twinny」。这条路径把诊断信息和修复请求串在一起，省去手动复制错误文本的步骤。

一个完整示例

下面把上面的步骤串成一条从零到可用的最短路径，假设是一台全新环境、Ollama 尚未安装。

1. 安装并启动 Ollama。从 Ollama 官网下载安装包，安装后服务自动在后台运行，监听 11434。

2. 拉取两个模型。

ollama pull qwen2.5-coder:7b-instruct
ollama pull qwen2.5-coder:1.5b-base

3. 安装 twinny 扩展，安装完成后重新加载窗口。

4. 等待自动发现。首次运行会弹出通知，说明已创建对话 Provider 和自动补全 Provider。如果没有弹出，打开 Providers 标签页，点「Search again」。

5. 检查补全栏的模型。在 Providers 标签页找到自动补全区块，确认它指向的是 qwen2.5-coder:1.5b-base。如果显示的是 7b-instruct，手动切换成 base 模型。

6. 点 Test provider。对话和补全两个卡片各点一次，确认都返回成功。若失败，先看错误文本，再检查 Ollama 是否在跑、端口是否为 11434。

7. 验证补全。新建一个源文件，输入：

// 读取配置文件并返回解析后的对象

在下一行停住，等待灰色建议出现，按 Tab 接受。

8. 验证内联编辑。选中刚生成的几行，按 Ctrl+I，输入「add error handling」，回车，查看 diff，按 Ctrl+Shift+Enter 接受。

9. 验证对话。在侧边栏输入 @，选择当前文件作为上下文，提问「这段代码有什么边界情况没处理」。回答中的代码块可以直接点 apply 写回文件。

走完这九步，补全、内联编辑、对话三条主链路就都通了。嵌入模型和 @workspace 属于可选增强，可以之后再补。

注意事项

自动匹配靠模型名，可能错配

前面已经强调过一次，这里再单独列出：自动补全取的是模型列表中第一个名字含 code 或 coder 的模型，这个规则不区分 instruct 与 base。装完扩展后检查补全栏是必要动作，不是可选项。

留空是正常状态

某个任务栏为空，说明 twinny 判断没有类型匹配的模型可用，它宁可留空也不指向错误类型的模型。遇到空栏，正确做法是补拉对应类型的模型，而不是强行把别的模型塞进去。

非默认端口需要手动指定

自动发现只扫常用端口。如果 Ollama 跑在别的端口上，探测会失败，需要走「Choose a provider」手动选 Ollama 预设并填写端口。

硬件门槛

内存低于 8 GB 或没有 GPU 的机器不适合跑 7B 级别的模型，应改用更小的模型。补全场景本身就更适合小模型，这一点在选型时可以直接利用。

配置与数据的存放位置

了解这些位置有助于备份、迁移和排查问题：

内容	位置
Provider 配置	VS Code 全局状态；若 twinny.providerStorageLocation 设为 file，则存放在扩展的全局存储目录中的文件里
对话记录	VS Code 全局状态
提示词模板	~/.twinny/templates/*.hbs
工作区索引	~/.twinny/embeddings/，每个工作区一个文件夹
P2P 身份与已配对设备（命令行节点）	~/.twinny/node/
P2P 身份（扩展）	VS Code 密钥存储
日志	Twinny 输出通道

排查问题时优先看输出通道里的日志，它比界面上的提示更详细。Provider 配置默认存在 VS Code 全局状态里，这意味着换工作区不会丢配置，但也意味着它不随项目仓库走；如果团队需要共享配置，可以改用 file 存储方式再自行分发。

版本、价格与配额

扩展版本、可用模型、托管 API 的计费方式与调用配额都会随时间变化，本文不给出具体数字。安装前请以扩展页面和所选用服务商的官网当前信息为准。