MonkeyCode 本地模型部署：完全离线的 AI 编程助手方案
引言
在数据安全要求日益严格的今天，"代码不出内网"已成为许多企业和政府项目的硬性需求。MonkeyCode 作为开源 AI 编程助手，不仅支持云端 API 调用，更提供了完整的本地模型部署方案——让你的 AI 编程能力完全运行在自己的服务器上，实现真正的零数据外泄。
本文将手把手教你从零搭建一套完全离线的 MonkeyCode 本地模型环境，涵盖硬件选型、模型选择、性能优化和生产部署的全流程。
🎯 核心信息
- GitHub 仓库: https://github.com/monkeycode-ai/monkeycode
- 开源协议: Apache License 2.0
- 欢迎提交 Issue: 部署问题请标记
deployment标签
一、为什么需要本地模型部署？
1.1 云端 vs 本地模型对比
┌─────────────────────────────────────────────────────────────────┐
│ 部署模式对比决策矩阵 │
├──────────────┬──────────────┬──────────────────┬────────────────┤
│ 维度 │ 云端 API │ 混合模式 │ 完全本地 │
├──────────────┼──────────────┼──────────────────┼────────────────┤
│ 数据安全性 │ ❌ │ ⚠️ │ ✅ │
│ 响应延迟 │ 200-800ms │ 100-500ms │ 50-200ms │
│ 成本（月） │ 按量付费 │ 中等 │ 一次性硬件投入 │
│ 模型能力 │ 最强(GPT-4) │ 灵活切换 │ 持续提升中 │
│ 定制化能力 │ ❌ │ ⚠️ │ ✅ │
│ 离线可用性 │ ❌ │ ⚠️ │ ✅ │
│ 合规友好度 │ ❌ │ ⚠️ │ ✅ │
│ 运维复杂度 │ 低 │ 中 │ 高 │
└──────────────┴──────────────┴──────────────────┴────────────────┘
1.2 必须使用本地模型的场景
| 场景 | 典型用户 | 核心诉求 |
|---|---|---|
| 🔒 金融/银行 | 核心系统开发团队 | 数据绝对不能出内网 |
| 🏛️ 政府/军工 | 信创项目组 | 自主可控 + 国密合规 |
| 🏥 医疗健康 | HIS/EMR 开发 | 患者数据保护 |
| 💰 企业核心 | 内部平台团队 | IP 保护 |
| 🎓 学术研究 | 高校实验室 | 无预算 + 数据隐私 |
| 🌍 出海受限 | 无法访问 OpenAI 的地区 | 网络隔离 |
二、硬件选型指南
2.1 推荐配置矩阵
# ===== 推荐硬件配置 =====
# 入门级（适合个人开发者 / 小团队）
entry_level:
gpu: "NVIDIA RTX 3060 12GB / RTX 4060 16GB"
cpu: "Intel i7-13700 / AMD Ryzen 7 7800X3D"
ram: "32GB DDR5"
storage: "1TB NVMe SSD"
suitable_models:
- "Qwen2.5-Coder-7B-Instruct"
- "DeepSeek-Coder-6.7B-Instruct"
- "CodeLlama-7B-Instruct"
estimated_performance:
tokens_per_second: "15-25 t/s"
concurrent_users: "1-3"
# 推荐级（适合中型团队 / 企业部门）
recommended:
gpu: "NVIDIA RTX 4090 24GB / A5000 24GB"
cpu: "Intel i9-14900K / AMD Ryzen 9 7950X"
ram: "64GB DDR5"
storage: "2TB NVMe SSD (PCIe 4.0)"
suitable_models:
- "Qwen2.5-Coder-14B-Instruct"
- "DeepSeek-Coder-33B-Instruct (GQAQ)"
- "Codestral-22B"
estimated_performance:
tokens_per_second: "30-50 t/s"
concurrent_users: "3-8"
# 企业级（适合大型团队 / 生产环境）
enterprise:
gpu: "NVIDIA A100 80GB / H100 80GB / L40S 48GB"
cpu: "Dual Xeon Gold 6454B / EPYC 9654"
ram: "256GB DDR5 ECC"
storage: "4TB NVMe RAID + 10TB HDD"
suitable_models:
- "Qwen2.5-Coder-72B-Instruct"
- "DeepSeek-Coder-V2-Lite (16B×2 MoE)"
- "自定义微调模型"
estimated_performance:
tokens_per_second: "60-120 t/s"
concurrent_users: "20-50+"
2.2 GPU 选型速查表
| GPU 型号 | 显存 | 推荐最大模型 | 参考价格 | 性价比评级 |
|---|---|---|---|---|
| RTX 3060 12GB | 12GB | 7B (Q4) | ¥2,000 | ⭐⭐⭐⭐⭐ |
| RTX 4060 Ti 16GB | 16GB | 13B (Q4) | ¥3,200 | ⭐⭐⭐⭐ |
| RTX 4090 24GB | 24GB | 32B (Q4) / 70B (Q2) | ¥12,000 | ⭐⭐⭐⭐ |
| A5000 24GB | 24GB | 32B (Q4) | ¥18,000 | ⭐⭐⭐ |
| L40S 48GB | 48GB | 70B (Q4) | ¥55,000 | ⭐⭐⭐ |
| A100 80GB | 80GB | 70B (Q4) + 大上下文 | ¥100,000+ | ⭐⭐ |
2.3 无 GPU 方案（CPU 推理）
# 对于没有 GPU 的环境，MonkeyCode 也支持 CPU 推理
# 但需要注意：速度会慢 10-20 倍
# CPU 推荐配置：
# - CPU: 至少 8 核 16 线程（推荐 Apple M 系列 / AMD 7950X）
# - 内存: 模型参数量的 2 倍以上（7B 模型需要 ≥16GB RAM）
# - 使用 GGUF 格式 + llama.cpp 后端
# 7B 模型在高端 CPU 上的预期速度：2-8 t/s
# 适合低频使用场景
三、模型选择与下载
3.1 MonkeyCode 官方支持的本地模型
| 模型名称 | 参数量 | 上下文长度 | 代码能力 | 中文能力 | 推荐显存 |
|---|---|---|---|---|---|
| Qwen2.5-Coder-7B | 7B | 32K | ★★★★☆ | ★★★★★ | 8GB+ |
| Qwen2.5-Coder-14B | 14B | 32K | ★★★★★ | ★★★★★ | 16GB+ |
| Qwen2.5-Coder-32B | 32B | 32K | ★★★★★ | ★★★★★ | 24GB+ |
| Qwen2.5-Coder-72B | 72B | 128K | ★★★★★ | ★★★★★ | 48GB+ |
| DeepSeek-Coder-6.7B | 6.7B | 16K | ★★★★☆ | ★★★☆☆ | 8GB+ |
| DeepSeek-Coder-33B | 33B | 16K | ★★★★★ | ★★★☆☆ | 24GB+ |
| Codestral-22B | 22B | 32K | ★★★★★ | ★★★☆☆ | 16GB+ |
| StarCoder2-15B | 15B | 16K | ★★★★☆ | ★★☆☆☆ | 16GB+ |
3.2 模型量化说明
量化等级对照表：
┌──────────┬──────────┬─────────────┬────────────┬─────────────┐
│ 量化格式 │ 显存占用 │ 模型质量损失 │ 推理速度 │ 适用场景 │
├──────────┼──────────┼─────────────┼────────────┼─────────────┤
│ FP16 │ 2×参数量 │ 无损失 │ 基准线 │ 最佳质量 │
│ INT8 │ 1×参数量 │ <1% 损失 │ ~1.5x快 │ 平衡之选 │
│ Q4_K_M │ ~0.5× │ 2-4% 损失 │ ~2.5x快 │ 显存受限 │
│ Q3_K_M │ ~0.4× │ 4-6% 损失 │ ~3x快 │ 极限压缩 │
│ Q2_K │ ~0.3× │ >8% 损失 │ ~3.5x快 │ 不推荐 │
└──────────┴──────────┴─────────────┴────────────┴─────────────┘
示例：Qwen2.5-Coder-7B 的显存需求
- FP16: ~14 GB VRAM
- Q4_K_M: ~5 GB VRAM ← 推荐！RTX 3060 即可流畅运行
- Q3_K_M: ~4 GB VRAM
3.3 模型下载脚本
#!/bin/bash
# ===== MonkeyCode 本地模型一键下载脚本 =====
set -e
MODEL_DIR="/opt/monkeycode/models"
mkdir -p "$MODEL_DIR"
echo "=========================================="
echo " MonkeyCode 本地模型下载工具"
echo "=========================================="
# 选择要下载的模型
echo "可选模型:"
echo " 1) Qwen2.5-Coder-7B-Instruct-Q4_K_M (推荐入门, ~5GB)"
echo " 2) Qwen2.5-Coder-14B-Instruct-Q4_K_M (推荐进阶, ~9GB)"
echo " 3) DeepSeek-Coder-6.7B-Instruct-Q4_K_M (~4GB)"
echo " 4) Codestral-22B-Q4_K_M (~14GB)"
read -p "请选择 [1-4]: " CHOICE
case $CHOICE in
1)
MODEL_NAME="Qwen/Qwen2.5-Coder-7B-Instruct-GGUF"
FILE="qwen2.5-coder-7b-instruct-q4_k_m.gguf"
;;
2)
MODEL_NAME="Qwen/Qwen2.5-Coder-14B-Instruct-GGUF"
FILE="qwen2.5-coder-14b-instruct-q4_k_m.gguf"
;;
3)
MODEL_NAME="deepseek-ai/DeepSeek-Coder-6.7B-Instruct-GGUF"
FILE="deepseek-coder-6.7b-instruct-q4_k_m.gguf"
;;
4)
MODEL_NAME="mistral/Codestral-22B-v0.1-GGUF"
FILE="codestral-22b-v0.1-q4_k_m.gguf"
;;
*)
echo "无效选择"
exit 1
esac
echo "正在下载 $FILE ..."
echo "来源: HuggingFace Hub"
# 方法一：使用 huggingface-cli（推荐）
if command -v huggingface-cli &>/dev/null; then
huggingface-cli download "$MODEL_NAME" "$FILE" \
--local-dir "$MODEL_DIR/$(basename $MODEL_NAME)" \
--local-dir-use-symlinks False
else
# 方法二：使用 wget 直接下载
URL="https://huggingface.co/$MODEL_NAME/resolve/main/$FILE"
wget -c "$URL" -O "$MODEL_DIR/$FILE"
fi
echo ""
echo "✅ 下载完成！"
echo "模型路径: $MODEL_DIR/$FILE"
echo ""
echo "下一步：运行 monkeycode --model-path $MODEL_DIR/$FILE 启动服务"
四、部署实战：从零到上线
4.1 Docker 一键部署（推荐）
# ===== 方案一：Docker Compose 一键部署 =====
# 创建工作目录
mkdir -p monkeycode-local && cd monkeycode-local
# 创建 docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
monkeycode-server:
image: monkeycode/ai-server:latest
container_name: monkeycode-local
restart: unless-stopped
ports:
- "8443:8443"
volumes:
- ./models:/app/models:ro # 模型文件（只读挂载）
- ./config:/app/config:rw # 配置文件
- ./data:/app/data:rw # 持久化数据
- ./logs:/app/logs:rw # 日志目录
environment:
- MONKEYCODE_MODEL_PATH=/app/models/qwen2.5-coder-7b-instruct-q4_k_m.gguf
- MONKEYCODE_N_GPU_LAYERS=35 # GPU 层数（根据显存调整）
- MONKEYCODE_CTX_SIZE=16384 # 上下文长度
- MONKEYCODE_MAX_TOKENS=4096 # 最大生成长度
- MONKEYCODE_HOST=0.0.0.0
- MONKEYCODE_PORT=8443
- MONKEYCODE_LOG_LEVEL=info
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8443/health"]
interval: 30s
timeout: 10s
retries: 3
networks:
- monkeycode-net
networks:
monkeycode-net:
driver: bridge
EOF
# 启动服务
docker compose up -d
# 查看日志
docker logs -f monkeycode-local
# 验证服务状态
curl -k https://localhost:8443/health
4.2 手动部署（适合深度定制）
#!/bin/bash
# ===== 手动部署完整流程 =====
set -e
echo "=== MonkeyCode 本地模型手动部署 ==="
# ===== 第一步：安装依赖 =====
echo "[1/6] 安装系统依赖..."
if [[ "$(uname -s)" == "Linux" ]]; then
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y \
build-essential \
git \
curl \
wget \
python3 \
python3-pip \
python3-venv \
libssl-dev \
pkg-config
# NVIDIA 驱动和 CUDA（如果尚未安装）
if ! command -v nvidia-smi &>/dev/null; then
echo "⚠️ 未检测到 NVIDIA 驱动，请先安装"
echo "参考: https://docs.nvidia.com/cuda/cuda-installation-guide-linux/"
fi
elif [[ "$(uname -s)" == "Darwin" ]]; then
# macOS (Apple Silicon)
brew install python@3.11 cmake openssl
fi
# ===== 第二步：创建虚拟环境 =====
echo "[2/6] 创建 Python 虚拟环境..."
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip setuptools wheel
# ===== 第三步：安装 MonkeyCode =====
echo "[3/6] 安装 MonkeyCode..."
pip install monkeycode[local]
# 如果需要 GPU 加速
pip install monkeycode[cuda] # NVIDIA CUDA
# 或
pip install monkeycode[metal] # macOS Metal
# ===== 第四步：下载模型 =====
echo "[4/6] 下载本地模型..."
python -m monkeycode download-model qwen2.5-coder-7b --quantize q4_k_m
# ===== 第五步：初始化配置 =====
echo "[5/6] 初始化配置..."
monkeycode init --mode local
# ===== 第六步：启动服务 =====
echo "[6/6] 启动 MonkeyCode 服务..."
monkeycode serve \
--host 0.0.0.0 \
--port 8443 \
--workers 4 \
--log-level info
echo ""
echo "✅ MonkeyCode 本地服务已启动！"
echo "访问地址: https://localhost:8443"
echo "API 文档: https://localhost:8443/docs"
echo ""
echo "按 Ctrl+C 停止服务"
4.3 配置文件详解
# config/local.yaml — MonkeyCode 本地部署配置模板
server:
host: "0.0.0.0"
port: 8443
tls:
enabled: true
cert_path: "/app/config/tls/cert.pem"
key_path: "/app/config/tls/key.pem"
workers: 4 # Worker 进程数
timeout: 300 # 请求超时(秒)
model:
# 模型路径
path: "/app/models/qwen2.5-coder-7b-instruct-q4_k_m.gguf"
# 推理后端: llama.cpp / vllm / sglang
backend: "llama.cpp"
# GPU 配置
n_gpu_layers: 35 # 卸载到 GPU 的层数（-1 = 全部）
main_gpu: 0 # 主 GPU 编号
# 生成参数
ctx_size: 16384 # 上下文窗口大小
max_tokens: 4096 # 最大输出 token 数
temperature: 0.2 # 温度（越低越确定）
top_p: 0.95 # Top-p 采样
top_k: 40 # Top-k 采样
repeat_penalty: 1.1 # 重复惩罚
# 性能优化
cache_enable: true # KV Cache 启用
batch_size: 8 # 批处理大小
parallel_prompt: true # 并行 prompt 处理
security:
# API 认证
auth_enabled: true
api_key_env: "MONKEYCODE_API_KEY"
# 速率限制
rate_limit:
requests_per_minute: 60
requests_per_hour: 1000
# CORS
cors_origins:
- "https://your-domain.com"
- "http://localhost:*"
logging:
level: "info" # debug / info / warn / error
format: "json" # json / text
file: "/app/logs/monkeycode.log"
max_size_mb: 100
backup_count: 5
features:
code_completion: true
chat: true
explanation: true
refactoring: true
test_generation: true
doc_generation: true
五、性能优化指南
5.1 推理加速技巧
optimization_techniques:
# 1. 量化优化
quantization:
tip: "使用 Q4_K_M 量化，质量和速度的最佳平衡点"
expected_speedup: "2-3x"
memory_reduction: "~75%"
# 2. 连续批处理 (Continuous Batching)
batching:
tip: "启用动态批处理，多个请求同时处理"
config: "batch_size: 8-16 (根据并发调整)"
expected_throughput: "+50-100%"
# 3. Flash Attention
flash_attention:
tip: "减少注意力计算的内存访问"
compatible: "Ampere+ GPU (RTX 30/40 series, A100+)"
speedup: "20-40% for long contexts"
# 4. PagedAttention
paged_attention:
tip: "解决 KV Cache 内存碎片问题"
benefit: "更稳定的内存使用，支持更长上下文"
# 5. 模型预加载
model_warmup:
tip: "启动时预热模型，避免首次请求冷启动"
method: "发送 dummy request on startup"
# 6. Tensor Parallelism (多卡)
tensor_parallel:
tip: "将模型分布到多张 GPU 上"
requirement: "2+ GPUs with NVLink preferred"
example: "tp_size=2 on 2×RTX 4090 → near 2x throughput"
5.2 不同场景的调优建议
| 场景 | 关键调优参数 | 推荐值 | 说明 |
|---|---|---|---|
| 极速补全 | max_tokens, temperature |
256-512, 0.1 | 减少输出长度，降低随机性 |
| 高质量生成 | ctx_size, top_p |
8192+, 0.9 | 更大上下文，更多探索 |
| 多用户并发 | batch_size, workers |
16, 8 | 提高吞吐量 |
| 长文件分析 | ctx_size, n_gpu_layers |
32768, max | 充分利用显存 |
| 资源受限 | n_gpu_layers, ctx_size |
28, 4096 | 部分 offload 到 CPU |
六、IDE 插件连接本地服务
6.1 VSCode 配置
// .vscode/settings.json
{
"monkeycode.serverUrl": "https://localhost:8443",
"monkeycode.apiKey": "${env:MONKEYCODE_API_KEY}",
"monkeycode.tlsVerify": false,
"monkeycode.model": "local",
"monkeycode.completion.triggerMode": "auto",
"monkeycode.completion.maxSuggestions": 5,
"monkeycode.chat.contextLines": 50,
"monkeycode.enableInlineChat": true,
"monkeycode.enableTerminalIntegration": true
}
6.2 JetBrains 配置
# Settings → Tools → MonkeyCode
# Server Configuration
monkeycode.server.url=https://localhost:8443
monkeycode.server.api.key=${MONKEYCODE_API_KEY}
monkeycode.server.tls.verify=false
# Completion Settings
monkeycode.completion.auto.trigger=true
monkeycode.completion.delay.ms=300
monkeycode.completion.max.results=5
# Chat Settings
monkeycode.chat.context.window.size=50
monkeycode.chat.stream.response=true
6.3 验证连接
# 健康检查
curl -k https://localhost:8443/health
# 预期返回: {"status":"ok","model":"qwen2.5-coder-7b","backend":"llama.cpp"}
# 测试补全 API
curl -k -X POST https://localhost:8443/v1/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"prompt": "def fibonacci(n):",
"max_tokens": 128,
"temperature": 0.2
}'
# 测试聊天 API
curl -k -X POST https://localhost:8443/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"model": "local",
"messages": [
{"role": "user", "content": "用Python写一个快速排序"}
],
"max_tokens": 512
}'
七、监控与运维
7.1 关键监控指标
monitoring_metrics:
# 性能指标
performance:
- name: "tokens_per_second"
unit: "t/s"
warning_threshold: "< 10"
critical_threshold: "< 5"
- name: "request_latency_p99"
unit: "ms"
warning_threshold: "> 5000"
critical_threshold: "> 10000"
- name: "queue_length"
unit: "requests"
warning_threshold: "> 10"
critical_threshold: "> 20"
# 资源指标
resources:
- name: "gpu_utilization"
unit: "%"
optimal_range: "70-90%"
- name: "gpu_memory_used"
unit: "GB"
warning_threshold: "> 90% of total"
- name: "cpu_usage"
unit: "%"
warning_threshold: "> 80%"
- name: "memory_usage"
unit: "GB"
warning_threshold: "> 85% of total"
7.2 Prometheus + Grafana 监控栈
# docker-compose.monitoring.yml
version: '3.8'
services:
prometheus:
image: prom/prometheus:latest
container_name: mc-prometheus
ports:
- "9090:9090"
volumes:
- ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
- prometheus_data:/prometheus
grafana:
image: grafana/grafana:latest
container_name: mc-grafana
ports:
- "3000:3000"
environment:
GF_SECURITY_ADMIN_PASSWORD: admin123
volumes:
- ./monitoring/grafana/dashboards:/var/lib/grafana/dashboards
- grafana_data:/var/lib/grafana
node_exporter:
image: quay.io/prometheus/node-exporter:latest
container_name: mc-node-exporter
ports:
- "9100:9100"
gpu_exporter:
image: nedbs/gpu-exporter:latest
container_name: mc-gpu-exporter
ports:
- "9445:9445"
runtime: nvidia
volumes:
prometheus_data:
grafana_data:
八、常见问题 FAQ
Q1: 我的显卡只有 8GB 显存，能跑什么模型？
✅ 可以运行 Qwen2.5-Coder-7B Q4_K_M（约需 5-6GB 显存），这是目前性价比最高的选择。
Q2: 本地模型的代码质量比 GPT-4 差多少？
📊 在标准基准测试（HumanEval+, MBPP+）上：
- Qwen2.5-Coder-7B ≈ GPT-3.5 水平
- Qwen2.5-Coder-32B ≈ GPT-4 水平（部分场景）
- 对于日常编码辅助任务，7B/14B 模型已经非常实用
Q3: 如何更新到新版本模型？
# 1. 下载新模型
monkeycode download-model qwen2.5-coder-7b --version latest
# 2. 更新配置文件中的 model.path
# 3. 重启服务
docker compose restart
# 或
monkeycode serve --restart
Q4: 多人可以同时使用吗？
✅ 可以。MonkeyCode 本地服务天然支持多用户并发，通过批处理机制高效调度。一台 RTX 4090 可支持 3-8 人同时使用。
Q5: 如何在没有互联网的环境部署？
- 在有网的机器上下载模型文件和 Docker 镜像
- 通过移动硬盘/U盘传输到目标机器
- 使用
docker load加载镜像 - 启动服务即可，无需任何网络连接
九、参与本地模型优化
我们需要的帮助
| 方向 | 难度 | 说明 |
|---|---|---|
| 🧪 新模型适配 | ⭐⭐⭐ | 将新发布的代码模型集成到 MonkeyCode |
| ⚡ 推理优化 | ⭐⭐⭐⭐ | 提升 llama.cpp/vLLM 后端的推理效率 |
| 📦 量化测试 | ⭐⭐ | 测试不同量化策略对代码生成质量的影响 |
| 🐛 Bug 修复 | ⭐⭐ | 本地部署相关的 Issue 修复 |
| 📝 文档完善 | ⭐ | 补充更多硬件/场景的部署教程 |
欢迎在 GitHub 提交 Issue 和 PR！
👉 GitHub Issues: https://github.com/monkeycode-ai/monkeycode/issues
结语
"真正的技术自由，是拥有选择的权利。"
MonkeyCode 的本地模型部署方案让你不再被绑定于任何云服务商。无论是出于数据安全的硬性需求，还是对技术自主的追求，我们都能为你提供完整的解决方案。
从一张 RTX 3060 到一整个 GPU 集群，从个人开发者到企业级部署——MonkeyCode 开源社区与你同行。
现在就克隆仓库，开始你的本地 AI 编程之旅吧！ 🚀
本文由 MonkeyCode 团队原创，采用 Apache 2.0 许可证发布。
关键词: MonkeyCode 本地部署 离线AI 大语言模型 LLM 私有化 GPU 开源 GitHub
浙公网安备 33010602011771号