本地部署CodeLlama+Ollama：打造离线智能代码补全环境

1. 为什么要在本地跑代码大模型

1.1 从一次断网经历说起

上个月我在一个客户现场做技术支援，那边办公区的外网访问策略特别严格，连代码补全插件的云端接口都调不通。当时我正在改一个C++的嵌入式项目，几百个文件来回跳转，没有智能补全简直像回到十年前用记事本写代码的年代。那次经历让我下定决心，必须把代码大模型搬到本地来跑，彻底摆脱对网络和外部服务的依赖。

回来之后我花了一个周末做调研和实测，最终锁定了一套组合方案：CodeLlama + Ollama。CodeLlama是Meta开源的代码专用大模型，有7B、13B、34B几个参数版本，专门针对代码生成和理解做了优化。Ollama则是一个轻量级的本地模型运行框架，把模型下载、量化、推理服务这些脏活累活全包了，你只需要一行命令就能把模型跑起来。两者搭配，从零到能用，我实测下来最快11分钟就能搞定。

这套方案适合什么人？如果你是后端开发、嵌入式工程师、算法同学，或者任何日常写代码但不想把公司代码传到云端的人，这篇文章就是写给你的。哪怕你之前没接触过本地大模型部署，只要会用命令行、装过软件，跟着走就能跑通。

1.2 本地跑代码模型的三个核心价值

第一个价值是数据不出本机。你写的每一行代码、每一个变量名、每一段注释，都不会离开你的硬盘。对于涉及核心业务逻辑或者有合规要求的项目，这一点是云端服务永远给不了的。

第二个价值是响应速度稳定。云端API受网络波动影响，有时候补全一个函数要等两三秒，思路都断了。本地推理虽然首次加载模型慢一点，但一旦跑起来，token生成速度基本在每秒20到40个之间，补全体验非常跟手。

第三个价值是可定制。Ollama支持自定义Modelfile，你可以把项目常用的代码规范、框架版本、甚至内部库的用法写进系统提示词里。再进一步，用LoRA做轻量微调，让模型学会你们团队的代码风格，这些都是云端通用模型做不到的。

注意：本地跑模型对硬件有基本要求。7B参数的模型量化后大约需要4到6GB显存，13B需要8到10GB，34B建议16GB以上。如果没有独立显卡，用CPU跑7B模型也能用，只是速度会慢一些，大概每秒5到10个token。

2. 环境准备与Ollama安装

2.1 硬件与系统的最低门槛

先说你手头的机器能不能跑。我整理了一个简单的对照表，你可以根据自己的配置对号入座：

操作系统方面，Windows 10/11、macOS 12以上、主流Linux发行版都支持。macOS用户如果用的是M系列芯片，统一内存架构跑起来效率很高，M1 16GB跑7B模型完全没问题。

2.2 Ollama的下载与安装

Ollama的安装过程非常简单，但国内网络环境下下载安装包和模型可能会比较慢，这里我给出两个方案。

方案一：官网直接下载

访问Ollama官网，根据你的操作系统选择对应的安装包。Windows用户下载.exe文件，macOS用户下载.dmg文件，Linux用户直接用一条命令：

curl -fsSL https://ollama.com/install.sh | sh

下载完成后双击安装，Windows和macOS都会自动把Ollama注册为后台服务，开机自启。安装完成后打开终端，输入：

ollama --version

如果能看到版本号输出，说明安装成功。

方案二：国内镜像源加速

如果你访问官网速度很慢，可以试试国内的一些开源镜像站。比如有些高校和云服务商提供了Ollama安装包的镜像下载。具体做法是找到对应你系统的安装包镜像地址，用下载工具拉下来再手动安装。模型下载同样可以配置镜像源，在终端里设置环境变量：

export OLLAMA_HOST=0.0.0.0 export OLLAMA_MODELS=/your/custom/path

把模型存储路径改到你空间比较大的盘符，避免默认路径把系统盘撑爆。

实操心得：Windows用户如果遇到安装后ollama命令不识别的情况，大概率是环境变量没刷新。关掉终端重新开一个，或者手动把Ollama的安装目录加到PATH里。我第一次装的时候就卡在这个问题上，折腾了十分钟才发现是终端缓存的问题。

2.3 验证Ollama服务状态

安装完成后，Ollama默认会在11434端口启动一个本地服务。你可以用浏览器访问http://localhost:11434，如果看到Ollama is running的提示，说明服务正常。

也可以在终端里用curl验证：

curl http://localhost:11434/api/tags

这个接口会返回你本地已经下载的模型列表。刚装好的时候是空的，接下来我们就去拉模型。

3. 拉取CodeLlama模型与配置

3.1 模型版本选择：7B、13B还是34B

CodeLlama有三个主要版本，每个版本又有不同的量化等级。我的建议是：

• 7B版本：适合快速验证和轻量使用，代码补全够用，复杂逻辑推理稍弱。如果你只是想要一个本地的代码补全工具，7B完全足够。
• 13B版本：平衡之选，代码理解和生成质量明显好于7B，对硬件要求也不算离谱。我个人最推荐这个版本。
• 34B版本：质量最好，但需要高端显卡。如果你有RTX 3090或4090，直接上34B，体验接近云端大模型。

量化等级方面，Ollama默认使用Q4_0量化，在质量和体积之间取得了很好的平衡。如果你显存特别紧张，可以用Q3或Q2，但代码生成质量会下降。显存充裕的话，Q5或Q8能进一步提升效果。

3.2 一条命令拉取模型

确定好版本后，拉取模型就是一条命令的事。以13B版本为例：

ollama pull codellama:13b

如果你想要特定量化版本：

ollama pull codellama:13b-code-q4_0

拉取过程中会显示下载进度。模型文件大概7到8GB，国内网络环境下可能需要一些时间。如果下载速度慢，可以尝试在非高峰时段拉取，或者配置镜像源。

注意：Ollama的模型仓库里，codellama:13b默认指向的是指令微调版本，适合对话式交互。如果你主要用来做代码补全，可以试试codellama:13b-code，这个版本在代码填充任务上表现更好。

3.3 运行模型并测试效果

模型拉取完成后，直接运行：

ollama run codellama:13b

第一次运行会加载模型到显存，大概需要10到30秒。加载完成后你会看到一个交互式提示符，可以直接输入问题。比如：

>>> 用Python写一个快速排序函数

模型会流式输出代码。我实测下来，13B版本生成一个标准快排大概需要3到5秒，代码质量相当不错，边界条件处理得也合理。

如果你想测试代码补全能力，可以输入一个函数签名，让模型补全函数体：

>>> def binary_search(arr, target):

模型会自动补全整个二分查找的实现。

3.4 自定义Modelfile让模型更懂你的项目

Ollama支持通过Modelfile自定义模型行为。你可以创建一个文件，比如叫Modelfile：

FROM codellama:13b PARAMETER temperature 0.2 PARAMETER top_p 0.9 PARAMETER num_ctx 4096 SYSTEM """ 你是一个资深C++和Python开发工程师。回答代码问题时，优先给出可编译运行的完整代码，并附带简要注释。 项目使用C++17标准，Python版本为3.10。避免使用已废弃的API。 """

然后基于这个Modelfile创建新模型：

ollama create my-codellama -f Modelfile

之后用ollama run my-codellama启动，模型就会按照你设定的角色和参数来回答。temperature调到0.2是为了让代码生成更确定、更少随机性，num_ctx设为4096是上下文窗口大小，可以根据你的显存情况调整。

4. 接入VS Code实现智能补全

4.1 插件选型：Continue vs Copilot

VS Code上接入本地模型的插件有好几个，我试过Continue和CodeGPT，最后长期用的是Continue。原因很简单：Continue对Ollama的支持最原生，配置最简单，而且补全和对话功能都有。

Copilot虽然体验好，但它是云端服务，不符合我们本地化的初衷。Continue的架构是插件本身只做UI和编辑器集成，推理全部交给本地Ollama服务，数据完全不外流。

4.2 Continue插件的安装与配置

在VS Code的扩展市场搜索Continue，安装后侧边栏会出现Continue的图标。点击图标，然后点击设置按钮，会打开一个config.json文件。把里面的内容替换成：

{ "models": [ { "title": "CodeLlama 13B", "provider": "ollama", "model": "codellama:13b", "apiBase": "http://localhost:11434" } ], "tabAutocompleteModel": { "title": "CodeLlama 13B", "provider": "ollama", "model": "codellama:13b", "apiBase": "http://localhost:11434" }, "allowAnonymousTelemetry": false }

保存后Continue会自动连接到Ollama服务。你可以在侧边栏的对话框里直接提问，也可以在编辑器里选中代码后右键选择Continue进行解释或重构。

4.3 代码补全的触发与调优

Continue的代码补全默认是自动触发的，你打字停顿一下它就会给出建议。按Tab接受补全，按Esc取消。

如果觉得补全太频繁或者不够频繁，可以在VS Code设置里搜索continue，调整Continue: Tab Autocomplete Debounce参数。默认是300毫秒，我一般调到500毫秒，避免打字过程中频繁弹出建议干扰思路。

还有一个关键参数是maxTokens，控制单次补全的最大长度。默认是256，对于大多数场景够用。如果你经常写长函数，可以调到512，但会增加显存占用和响应时间。

实操心得：Continue的补全质量跟上下文关系很大。打开相关文件、保持编辑器里能看到足够的上下文代码，补全准确率会明显提升。我习惯在写新函数之前，先把相关的头文件或者接口定义打开在旁边，这样模型能更好地理解我要做什么。

4.4 实测补全效果与性能数据

我在一个真实的C++项目里做了对比测试。项目大概有200多个源文件，主要涉及网络通信和数据处理。测试场景是写一个新的数据解析函数。

用CodeLlama 13B补全，从输入函数签名到接受补全，平均耗时1.8秒，生成的代码一次通过编译的概率大概在70%左右。剩下的30%主要是边界条件或者类型不匹配的问题，稍微改改就能用。

对比之前用云端服务的体验，本地补全的延迟略高一点点，但胜在稳定，不会因为网络抖动突然卡住。而且因为模型跑在本地，我可以放心地把完整的函数上下文给它看，补全质量反而更好。

5. LoRA微调入门：让模型学会你的代码风格

5.1 什么情况下需要微调

CodeLlama的通用能力已经不错了，但每个团队都有自己的代码风格和内部库。比如你们可能有一套自研的日志框架、一套特定的错误处理模式，或者命名规范跟主流不太一样。这些信息很难通过提示词完整传达，这时候LoRA微调就派上用场了。

LoRA的全称是Low-Rank Adaptation，中文叫低秩适配。它的核心思想是不改动原始模型参数，而是在模型旁边挂一小块可训练的参数。训练完成后，这块小参数跟原模型合并，就能让模型学会新风格。好处是训练成本极低，7B模型用一张消费级显卡几个小时就能跑完。

5.2 数据准备：从代码库到训练集

微调的第一步是准备数据。你需要把项目里的代码整理成模型能吃的格式。最简单的方式是准备一个JSONL文件，每行一个样本：

{"instruction": "实现一个线程安全的队列", "output": "template<typename T>\nclass ThreadSafeQueue {\npublic:\n void push(T value) {\n std::lock_guard<std::mutex> lock(mutex_);\n queue_.push(std::move(value));\n }\n ...\n};"}

数据来源可以是你们项目里的优秀代码片段、代码审查记录、或者内部技术文档。关键是质量要高，宁缺毋滥。我建议至少准备500到1000个样本，少了效果不明显。

5.3 LoRA训练的关键参数配置

训练脚本可以用Hugging Face的peft库配合transformers来写。核心参数配置如下：

from peft import LoraConfig, get_peft_model lora_config = LoraConfig( r=8, lora_alpha=32, target_modules=["q_proj", "v_proj"], lora_dropout=0.05, bias="none", task_type="CAUSAL_LM" )

几个关键参数解释一下：

• r=8：秩的大小，控制可训练参数的数量。8是个常用起点，数据量大可以调到16或32。
• lora_alpha=32：缩放因子，一般设为r的两倍。
• target_modules：指定在哪些层上挂LoRA。q_proj和v_proj是注意力层的查询和值投影，这是最常用的选择。
• lora_dropout=0.05：防止过拟合。

训练时的批次大小和学习率也很关键。7B模型在24GB显存的卡上，batch_size可以设到4，gradient_accumulation_steps设8，等效批次32。学习率用2e-4，配合余弦退火调度。

5.4 微调后的模型合并与部署

训练完成后，LoRA权重是单独保存的。要把它跟原模型合并：

from peft import PeftModel from transformers import AutoModelForCausalLM base_model = AutoModelForCausalLM.from_pretrained("codellama/CodeLlama-7b-hf") model = PeftModel.from_pretrained(base_model, "./lora_output") merged_model = model.merge_and_unload() merged_model.save_pretrained("./merged_model")

合并后的模型可以用llama.cpp转换成GGUF格式，再导入Ollama：

ollama create my-finetuned-codellama -f Modelfile

Modelfile里指向你转换好的GGUF文件路径。之后就能像用普通模型一样使用微调后的版本了。

注意：LoRA微调虽然成本低，但也不是万能的。如果训练数据质量差或者样本太少，模型可能会过拟合，反而影响通用能力。我的经验是，先用提示词工程试试，确实解决不了再上微调。

6. 常见问题与排查技巧

6.1 模型下载慢或中断怎么办

国内网络环境下，ollama pull下载模型慢是常态。几个应对方法：

• 设置OLLAMA_MODELS环境变量，把模型存到大容量硬盘，避免下载中断后重复下载。
• 尝试在凌晨或非高峰时段拉取，速度会快很多。
• 如果实在拉不下来，可以找已经下载好的朋友，把~/.ollama/models目录整个拷贝过来，放到相同路径下即可。

6.2 显存不足的降级方案

跑13B模型时如果遇到显存不足报错，有几个降级方案：

num_ctx参数控制上下文窗口大小，默认可能是4096。如果显存紧张，可以降到2048甚至1024，能省不少显存。

6.3 VS Code插件连接失败的排查

Continue插件连不上Ollama服务时，按这个顺序排查：

1. 确认Ollama服务在运行：终端输入ollama list，能列出模型说明服务正常。
2. 检查端口：默认是11434，如果被占用可以在Ollama配置里改端口。
3. 检查config.json里的apiBase地址是否正确，注意不要有多余的斜杠。
4. 查看VS Code的输出面板，选择Continue，看有没有具体的错误信息。

我遇到过一次连接失败，最后发现是公司安全软件拦截了本地端口通信。把Ollama加入白名单就好了。

6.4 补全质量不理想的调优方向

如果补全出来的代码质量差，可以从这几个方向调：

• 提高上下文质量：打开相关文件，让编辑器里有足够的参考代码。
• 调整temperature：代码补全建议用0.1到0.3，太高会随机生成不相关的代码。
• 换更大的模型：7B换13B，质量提升很明显。
• 写更详细的注释：在函数上方用注释描述清楚功能，模型会参考注释来生成代码。

6.5 模型回答速度慢的优化

生成速度慢通常有几个原因：模型太大、量化等级太高、上下文太长。对应的优化手段就是换小模型、用更低量化、缩短num_ctx。另外，确保Ollama使用的是GPU而不是CPU，可以在启动日志里看到using GPU的提示。

如果用的是NVIDIA显卡，确认CUDA驱动版本跟Ollama要求匹配。驱动太旧会导致Ollama回退到CPU模式，速度直接掉一个数量级。

7. 我的实际使用体会与建议

这套方案我用了快两个月，日常开发已经离不开它了。写新功能的时候，Continue的补全能帮我省掉大量敲键盘的时间；遇到不熟悉的库或者API，直接在侧边栏问模型，比翻文档快得多。

有一点要提醒：本地模型再强，也比不上云端最大的那些模型。它的定位是"够用的日常助手"，不是"替代你思考的万能工具"。复杂架构设计、疑难bug排查，还是得靠自己的经验判断。

另外，LoRA微调虽然听起来很美好，但实际做下来，数据准备的工作量往往比训练本身大得多。如果你只是想提升补全体验，先把提示词和上下文管理做好，效果可能比微调来得更快。

最后分享一个小技巧：Ollama支持同时加载多个模型，你可以把7B和13B都拉下来。日常补全用7B，速度快；遇到复杂问题切换到13B，质量高。在Continue的配置里可以配多个模型，随时切换，非常灵活。