人人都会AI编程

2.2.2 本地开源模型部署与接入

更新时间：2026-06-30

如果代码绝对不能离网，或团队希望零调用成本长期使用，可以选择在本地工作站或服务器部署开源模型，再通过 OpenCode 插件接入。该方案对硬件有一定要求，但数据完全留在本地，适合金融、政务、军工等高保密场景。

1. 硬件与环境要求

本地模型的运行效果直接取决于显存和内存，以下为流畅运行的最低参考：

| 模型规模 | 建议显存 | 推荐框架 | 备注 |
|---|---|---|---|
| 7B 级（如 Qwen2.5-Coder-7B、DeepSeek-Coder-V2-Lite） | 8 GB+ | Ollama、llama.cpp | 单卡 3060/4060 可流畅推理 |
| 14B 级（如 Qwen2.5-14B、CodeLlama-13B） | 16 GB+ | Ollama、vLLM | 单卡 3090/4090 或 A4000 |
| 32B 级（如 Qwen2.5-32B、DeepSeek-Coder-33B） | 24 GB+ | vLLM、TGI | 需 3090/4090/A10 或双卡 |
| 纯 CPU 运行 | 内存 32 GB+ | llama.cpp、Ollama CPU 模式 | 速度较慢，仅适合 7B 以下模型 |

提示：代码补全对延迟极其敏感，建议本地部署时优先使用 7B–14B 级别的专用代码模型（如 Qwen2.5-Coder、DeepSeek-Coder），而非通用的超大对话模型。

2. 模型部署（三种常用方式）

方式 A：Ollama（最简单，推荐个人及小团队）

  1. 访问 ollama.com 下载对应系统的安装包并安装。
  2. 命令行拉取模型（以 Qwen2.5-Coder 为例）：
   ollama pull qwen2.5-coder:14b
  1. 启动服务（默认监听 http://localhost:11434）：
   ollama serve
  1. 验证：
   curl http://localhost:11434/api/generate -d '{"model":"qwen2.5-coder:14b","prompt":"def hello():"}'

方式 B：vLLM（适合高并发、生产环境）

适合团队共享服务器，支持多卡并行与 OpenAI 兼容 API。

# 需 Python 3.8+ 及 CUDA 环境
pip install vllm

# 启动服务（单卡示例）
python -m vllm.entrypoints.openai.api_server \
  --model deepseek-ai/deepseek-coder-6.7b-instruct \
  --port 8000 \
  --tensor-parallel-size 1

启动后，API 地址为 http://<服务器IP>:8000/v1/chat/completions，与 OpenAI 接口格式一致。

方式 C：llama.cpp（适合 CPU 或无 NVIDIA 显卡环境）

适合旧设备或苹果 Mac（利用 Metal GPU）。

  1. 下载或编译 llama-server。
  2. 下载 GGUF 格式量化模型（如 Q4_K_M 量化版）。
  3. 启动服务器：
   ./llama-server -m qwen2.5-coder-7b-q4_k_m.gguf \
     --host 0.0.0.0 --port 8080 \
     -c 4096  # 上下文长度

3. 接入 OpenCode

  1. 在 OpenCode 设置中，将模型来源切换为本地模型（或自定义 / 私有化部署）。
  2. Base URL / API Endpoint：
  • Ollama 需填入：http://localhost:11434/v1（Ollama 0.1.24+ 自带兼容层）。
  • vLLM / llama.cpp / TGI 填入对应的 OpenAI 兼容地址，如 http://localhost:8000/v1。
  1. API Key：本地模型通常无鉴权，随意填一个占位符（如 sk-local）即可；若配置了反向代理密钥，则如实填写。
  2. 模型名称：填写实际部署的模型 ID（如 qwen2.5-coder:14b、deepseek-coder-6.7b-instruct），务必与部署时的模型名一致。
  3. 点击连接测试，若返回成功，保存后立即生效。

4. 本地部署的调优建议

  • 上下文长度：本地显存有限，建议在 OpenCode 插件中将 Max Tokens 和上下文窗口调小（如 2048–4096），避免一次性请求过长代码导致显存溢出（OOM）。
  • Temperature：本地模型容易出现重复生成，建议将 Temperature 设为 0.2 左右，提高确定性。
  • 并发控制：若多人共用一台本地服务器，请在 vLLM/Ollama 侧限制并发数，避免排队导致补全延迟超过 5 秒，影响编码体验。
  • 只开启必要功能：若硬件紧张，可在 OpenCode 设置中关闭「实时对话」或「代码解释」，仅保留「代码补全」，降低 GPU 占用。

5. 常见问题

  • 补全速度慢、卡顿：7B 模型在 4060 上一般能做到 30–50 tokens/s；若速度过慢，检查是否误用 CPU 推理，或尝试更低级别的量化（如 Q4 代替 Q8）。
  • 显存不足（CUDA out of memory）：减小模型尺寸、降低上下文长度、关闭其他占用显存的程序，或在 vLLM 中启用 --enforce-eager 和 --max-model-len 4096。
  • 生成代码质量差：开源 7B 模型的能力弱于云端 GPT-4o / Claude，建议用它处理单文件、短函数补全；复杂跨文件重构仍建议切回云端大模型。
  • Ollama 连接测试失败：确认 Ollama 版本 ≥ 0.1.24，旧版本无 /v1 兼容接口；或尝试在 Base URL 末尾显式加上 /v1。