当数据安全合规成为硬性要求，当网络延迟让云端AI补全显得卡顿，当订阅成本随着团队规模线性增长时，把AI编程助手搬到自己的服务器上，就从"锦上添花"变成了"必选项"。CodeGeeX作为国产模型中少有的在代码任务上接近GPT-4水平的开源方案，本地部署的性价比正在快速提升。但我们在实际落地过程中踩过不少坑：模型下载慢到怀疑人生、显存爆掉、IDE插件连接超时，这些真实经历都写进了本文。
我们团队在2025年Q3开始试点AI编程助手，最初用云端API方案，但随着代码量增加，三个核心矛盾逐渐突出。第一是数据合规：金融级项目要求代码不得离开内网，云端API直接把代码发送到第三方服务器，这触碰了红线。第二是体验问题：办公室到云端API的RTT在80-120ms之间，连续补全时累积延迟非常明显，打断思路。第三是成本：按token计费对高频使用者极其不友好，一个中等规模团队每月API费用轻松过万。
CodeGeeX的优势在于它是国内少有的、在HumanEval和MBPP上得分超过80的开源模型，而且智谱AI提供了完整的商业授权通道。本地部署的本质是用一次性硬件成本+电费，换取无限制的调用能力和完全的数据主权。但这并不意味着没有代价：GPU资源占用、模型运维成本、以及从"开箱即用"到"生产可用"之间那道看不见的鸿沟。
CodeGeeX2基于Transformer-Decoder架构，支持标准的 causal LM 推理，同时针对代码任务优化了Fill-in-the-Middle（FIM）模式，允许光标位于代码中间时进行补全。本地部署的架构通常分为三层：推理引擎层（vLLM/TGI）、API适配层（OpenAI兼容封装）、客户端层（IDE插件或自定义脚本）。
选择vLLM而不是TGI或ollama，主要基于三个工程考量。首先是PagedAttention内存管理，vLLM把KV cache按页分配，显存利用率比TGI高15-20%，batch处理时吞吐量优势明显。其次是Continuous Batching，请求到达后立即插入当前批次，不用等最长序列处理完，这对交互式补全场景至关重要。第三是生态兼容性，vLLM原生暴露OpenAI兼容接口，Continue、Windsurf等主流插件无需改造即可接入。
如果团队没有专职算法工程师，建议直接用vLLM官方Docker镜像，不要自己编译CUDA内核。官方镜像已经把tensor parallelism、FlashAttention、AWQ量化打包好了，省去至少3天的环境调试时间。
我们最终在两张A10（24GB显存）上搭建了生产级CodeGeeX服务，以下是完整部署路径和踩坑记录。
硬件方面，单张A10可以流畅跑CodeGeeX2-6B的FP16，但要支撑团队20人并发，需要至少两张卡做Tensor Parallelism。如果是4-bit量化版本，单卡就能跑，batch size建议设16-32，延迟控制在50ms以内。CPU-only部署不推荐，我们在128核机器上测过，单请求延迟约2.3秒，完全无法满足IDE实时补全需求。
模型文件从HuggingFace下载，国内用户务必配置镜像源，否则下载速度可能只有几十KB/s。启动命令使用vLLM的OpenAI兼容模式，这样后续切换模型完全不用改客户端代码。
# 配置镜像源加速下载
export HF_ENDPOINT=https://hf-mirror.com
# 拉取CodeGeeX2-6B-Instruct（约12GB）
huggingface-cli download \
--resume-download \
THUDM/codegeex-2-6b-instruct \
--local-dir /models/codegeex-2-6b
# 启动vLLM服务（TP=2，两张A10）
python -m vllm.entrypoints.openai.api_server \
--model /models/codegeex-2-6b \
--tokenizer THUDM/codegeex-2-6b-instruct \
--tensor-parallel-size 2 \
--max-model-len 8192 \
--quantization awq \
--port 18789 \
--host 0.0.0.0
启动后验证接口是否正常，以下Python代码可以直接测试补全效果。我们把这段代码写成了独立脚本，部署后第一时间跑，确保服务可用。
import requests
import json
def test_completion(prompt):
url = "http://localhost:18789/v1/completions"
headers = {"Content-Type": "application/json"}
payload = {
"model": "codegeex-2-6b",
"prompt": prompt,
"max_tokens": 256,
"temperature": 0.2,
"stop": ["\n\n", "def ", "class "]
}
resp = requests.post(url, headers=headers, json=payload, timeout=30)
data = resp.json()
return data["choices"][0]["text"]
# 测试输入：Python快速排序
prompt = "def quicksort(arr):\n "
result = test_completion(prompt)
print("补全结果：")
print(result)
print("---")
# 预期输出：标准的递归快速排序实现，包含partition逻辑
在我们的测试环境中，两张A10、batch=32、max_model_len=8192、AWQ 4-bit量化，得到以下指标：首token延迟（TTFT）约35ms，每token生成速度约2.1ms，吞吐量约1800 req/min。如果是单张A10不量化，batch=16时TTFT约22ms，吞吐量约900 req/min。这些数据说明，对于20人规模团队，单张A10加4-bit量化完全够用，省下的卡可以跑其他模型。
| 方案 | 优势 | 代价 | 适用场景 |
|---|---|---|---|
| vLLM + A10 × 2 + AWQ | 吞吐量最高，延迟稳定，支持连续批处理 | 硬件成本约8万元，运维复杂度中等 | 20人以上团队，生产环境 |
| vLLM + 单卡4090 + AWQ | 成本最低约1.2万元，部署简单 | 并发超过5人时延迟明显上升 | 5人以下小团队，个人使用 |
| TGI + A10 | HuggingFace官方维护，更新及时 | 显存利用率低15%，吞吐量不如vLLM | 已有TGI技术栈的团队 |
| ollama + CPU | 零配置，适合快速验证 | 单请求延迟2秒以上，无法生产使用 | 原型验证、离线测试 |
坑一：模型下载。我们从HuggingFace直接拉取模型时，高峰期速度掉到20KB/s，12GB的模型文件下了整整三天。定位后发现是HuggingFace对非镜像用户的限速。解决方案是配置国内镜像源，或者提前在能访问的环境中下载好，再scp到服务器。代价是额外花了一上午调试镜像配置，但后续换模型时再也没卡过。
坑二：显存爆掉。第一次启动时没开量化，FP16的6B模型加上KV cache，单张A10（24GB）刚启动就OOM。现象是vLLM打印CUDA out of memory后直接崩溃。定位方法是nvidia-smi观察显存峰值，发现模型权重占14GB，KV cache按max_model_len=8192预分配时瞬间吃满。最终方案是加--quantization awq参数，显存占用降到7GB，余量充足。代价是首token延迟从22ms涨到35ms，但完全在可接受范围内。
Continue插件默认超时时间是10秒，而CodeGeeX首次请求时vLLM要做JIT编译和CUDA图优化，冷启动经常卡12秒。表现为IDE一直转圈，最后报连接失败。定位方法是curl直接打接口，发现首次请求确实要12秒，第二次就正常了。最终方案是在vLLM启动参数里加--disable-log-requests减少启动开销，同时在Continue配置里把超时调到30秒。代价是每次服务重启后需要手动触发一次预热请求，或者写个健康检查脚本自动预热。
如果你的团队只有5个人、预算有限，单张4090加4-bit量化是最佳起点，投入不到1.5万元就能获得接近云端API的体验。如果团队规模在20人以上、对延迟敏感，直接上两张A10走vLLM + AWQ方案，单卡故障时另一张卡可以撑住，SLA更有保障。如果追求极致性能且显存充足，可以去掉量化，FP16在复杂代码生成任务上确实有微弱优势，但成本翻倍。
从工程角度看，本地部署AI编程助手不是买卡就完事的生意。你需要考虑模型版本管理、服务监控（显存利用率、请求队列长度、TTFT P99）、以及故障转移。建议把vLLM跑在K8s里，配好HPA，根据GPU利用率自动扩缩容。毕竟AI编程助手已经从"玩具"变成了基础设施，稳定性比一次性性能更重要。
CodeGeeX2最大支持6B参数，主打轻量部署和低延迟；CodeGeeX4支持更大参数规模，代码理解能力更强但显存占用更高。日常IDE补全推荐CodeGeeX2-6B，复杂重构建议用CodeGeeX4。
CodeGeeX2-6B FP16需要约14GB显存，4-bit量化后仅需6-7GB。若开启Tensor Parallelism（TP=2），两块24GB卡可跑满batch=64。CPU部署需要32GB以上内存，但延迟会升高至秒级，仅适合离线验证场景。
CodeGeeX2原生支持32768 token上下文窗口，足以覆盖中小型项目的核心模块。通过RAG检索相关文件片段，可进一步扩展至整个仓库，但需要自行搭建向量索引层。
4-bit AWQ/GPTQ量化在HumanEval基准上仅下降2-3个百分点，但吞吐量提升约40%。对于编程任务，语法正确率基本无损，仅在复杂算法生成时偶有格式偏差。
CodeGeeX2和CodeGeeX4模型权重对学术研究免费，商业使用需联系智谱AI获取企业授权。部署后的推理服务本身无额外费用，但需自行承担服务器成本。