llama.vscode

本地LLM辅助文本补全、与AI聊天以及面向VS Code的代理式编程扩展

功能特性

• 输入时自动提示
• 使用 Tab 键接受建议
• 使用 Shift + Tab 键接受建议的第一行
• 使用 Ctrl/Cmd + 右箭头 键接受下一个单词
• 按 Ctrl + L 手动切换提示
• 控制最大文本生成时间
• 配置光标周围上下文的范围
• 将打开和编辑过的文件以及剪贴板内容以块的形式纳入上下文
• 通过智能上下文复用，即使在低端硬件上也能支持超大上下文
• 显示性能统计信息
• 用于代理式编程的Llama Agent
• 添加/删除/导出/导入模型——包括补全、聊天、嵌入和工具模型
• 模型选择——适用于补全、聊天、嵌入和工具
• 引入了环境（模型组）的概念。选择或取消选择某个环境会同时选择或取消选择其中的所有模型。
• 添加/删除/导出/导入环境
• 预定义模型（包括作为本地模型添加的OpenAI gpt-oss 20B）
• 针对不同使用场景的预定义环境——仅补全、聊天+补全、聊天+代理、本地完整包（含gpt-oss 20B）等
• 为代理选择MCP工具（来自VS Code中已安装的MCP服务器）
• 直接从llama-vscode中搜索并下载Huggingface上的模型

安装

VS Code扩展设置

从VS Code扩展市场安装llama-vscode扩展：

注意：也可在Open VSX上找到。

llama.cpp 设置

点击状态栏中的llama-vscode图标或按 Ctrl+Shift+M 打开llama-vscode菜单，然后选择“安装/升级llama.cpp”。这将自动为Mac和Windows安装llama.cpp。对于Linux系统，请获取最新二进制文件，并将bin目录添加到PATH中。

一旦安装好llama.cpp，您就可以从llama-vscode菜单的“选择/启动环境…”中根据需求选择合适的环境。

以下是手动安装llama.cpp的一些详细步骤（如果您更倾向于这种方式）。

Mac OS

brew install llama.cpp

Windows

winget install llama.cpp

其他操作系统

您可以使用最新二进制文件，也可以从源代码构建llama.cpp。有关如何运行llama.cpp服务器的更多信息，请参阅Wiki。

llama.cpp 设置

以下是根据您的显存容量推荐的设置：

• 显存大于64GB：

  llama-server --fim-qwen-30b-default
  

• 显存大于16GB：

  llama-server --fim-qwen-7b-default
  

• 显存小于16GB：

  llama-server --fim-qwen-3b-default
  

• 显存小于8GB：

  llama-server --fim-qwen-1.5b-default
  

llama-server \
    -hf ggml-org/Qwen2.5-Coder-1.5B-Q8_0-GGUF \
    --port 8012 -ub 512 -b 512 --ctx-size 0 --cache-reuse 256

llama-server \
    -hf ggml-org/Qwen2.5-Coder-0.5B-Q8_0-GGUF \
    --port 8012 -ub 1024 -b 1024 --ctx-size 0 --cache-reuse 256

您可以使用任何其他FIM兼容且您的系统能够运行的模型。默认情况下，使用 -hf 标志下载的模型会存储在以下路径：

• Mac OS: ~/Library/Caches/llama.cpp/
• Linux: ~/.cache/llama.cpp
• Windows: LOCALAPPDATA

推荐的LLM模型

该插件需要FIM兼容的模型：HF集合

Llama Agent

该扩展包含Llama Agent。

功能特性

• 在资源管理器视图中显示Llama Agent界面
• 支持本地模型——目前最佳选择是gpt-oss 20B
• 也可与外部模型配合使用（例如来自OpenRouter）
• 支持MCP——可以使用安装并运行在VS Code中的MCP服务器提供的工具
• 提供9种内置工具可供使用
• custom_tool——返回文件或网页的内容
• custom_eval_tool——用JavaScript编写您自己的工具（接受输入并返回字符串的函数）
• 可将选区附加到上下文中
• 可配置Llama Agent的最大循环次数

使用方法

1. 使用 Ctrl+Shift+A 或从llama-vscode菜单中的“显示Llama Agent”选项打开Llama Agent。
2. 如果您尚未选择环境，请选择一个包含代理的环境。
3. 输入查询，并在需要时使用 @ 按钮附加文件。

更多详情(https://github.com/ggml-org/llama.vscode/wiki)

示例

在M2 Studio上本地运行的推测性FIMs：

https://github.com/user-attachments/assets/cab99b93-4712-40b4-9c8d-cf86e98d4482

实现细节

该扩展旨在保持极简轻量，同时提供高质量且高效的本地FIM补全功能，即便是在消费级硬件上也能实现。

• 最初的实现由Ivaylo Gardev @igardev完成，参考了llama.vim插件。
• 技术说明：https://github.com/ggerganov/llama.cpp/pull/9787

其他IDE

• Vim/Neovim：https://github.com/ggml-org/llama.vim

llama.vscode 快速上手指南

llama.vscode 是一款专为 VS Code 设计的本地大语言模型（LLM）辅助插件，支持代码自动补全、AI 对话以及智能体（Agent）编程。它基于 llama.cpp，能在消费级硬件上高效运行。

环境准备

系统要求

• 操作系统：macOS, Windows, Linux
• 硬件建议：
  • 显存 > 64GB：可运行大型模型（如 Qwen-30B）
  • 显存 > 16GB：推荐中型模型（如 Qwen-7B）
  • 显存 < 16GB：推荐小型模型（如 Qwen-3B 或 1.5B）
  • 仅 CPU：可运行量化小模型（如 Qwen-1.5B-Q8_0），但生成速度较慢
• 软件依赖：Visual Studio Code

前置依赖

插件核心依赖 llama.cpp 服务端。安装插件后通常可自动配置，也可手动安装。

安装步骤

1. 安装 VS Code 插件

在 VS Code 扩展商店中搜索并安装 llama-vscode，或使用命令面板安装：

# 在 VS Code 命令面板 (Ctrl+Shift+P) 中输入：
Extensions: Install Extensions
# 搜索 "llama-vscode" (发布者：ggml-org) 并点击安装

注：也可通过 Open VSX 安装。

2. 配置 llama.cpp 后端

安装插件后，点击 VS Code 底部状态栏的 llama-vscode 图标（或使用快捷键 Ctrl+Shift+M），选择 "Install/Upgrade llama.cpp"。

• macOS / Windows：插件将自动下载并安装对应版本的 llama.cpp。
• Linux：需手动下载 最新二进制文件 并将 bin 目录添加到系统 PATH，或使用包管理器安装。

手动安装命令参考：

# macOS
brew install llama.cpp

# Windows (需安装 winget)
winget install llama.cpp

3. 启动环境与选择模型

1. 再次点击状态栏图标或按 Ctrl+Shift+M。
2. 选择 "Select/start env..."。
3. 根据你的硬件配置选择合适的预设环境（Env）：
   • 高性能显卡：选择包含 gpt-oss 20B 或 Qwen-7B 的环境。
   • 低配设备/仅 CPU：选择 Qwen-1.5B 或 Qwen-0.5B 相关环境。

提示：插件支持直接从 Hugging Face 搜索和下载模型，首次选择环境时会自动拉取所需模型。

4. 推荐服务端参数（可选高级配置）

若需手动启动 llama-server，请根据显存大小使用以下推荐参数：

# 显存 > 64GB
llama-server --fim-qwen-30b-default

# 显存 > 16GB
llama-server --fim-qwen-7b-default

# 显存 < 16GB
llama-server --fim-qwen-3b-default

# 显存 < 8GB
llama-server --fim-qwen-1.5b-default

基本使用

代码自动补全 (FIM)

插件默认开启自动建议功能，无需额外配置即可在编码时获得提示。

• 触发建议：输入代码时自动弹出。
• 接受整段建议：按 Tab 键。
• 接受首行建议：按 Shift + Tab 键。
• 逐词接受：按 Ctrl/Cmd + Right (向右箭头)。
• 手动切换建议：按 Ctrl + L。

AI 对话与智能体 (Llama Agent)

利用内置的 Llama Agent 进行复杂任务处理或文件分析。

1. 打开界面：按 Ctrl+Shift+A 或通过菜单选择 "Show Llama Agent"。
2. 选择环境：确保已选择包含 Agent 功能的 Env（推荐使用 gpt-oss 20B）。
3. 发起请求：
   • 在输入框编写自然语言指令。
   • 如需引用当前选中的代码或文件，点击输入框旁的 @ 按钮附加上下文。
   • 支持调用 MCP 工具（需在 VS Code 中安装并启动相应的 MCP Server）。

管理模型与环境

• 切换模型：通过 Ctrl+Shift+M 菜单快速切换不同用途的模型（补全、对话、嵌入等）。
• 导入/导出：支持自定义模型的添加、移除及环境配置的导入导出。