CodeGeeX是智谱AI与清华大学联合推出的代码生成模型，能够根据自然语言描述生成代码、补全函数、解释代码逻辑，也支持多种编程语言。对于需要在公司内网处理代码、不想把核心业务代码发送到外部API，或者想针对自有代码库做微调的技术团队来说，本地部署是更可控的选择。
一、部署前准备：模型版本与硬件要求
先看模型版本。目前比较适合本地部署的是CodeGeeX4-9B，参数量9B，原生支持128K上下文，对Python、Java、C++、Go等主流语言效果稳定。FP16精度下权重文件约18GB，显存建议24GB起步；INT4量化后权重约6.6GB，8GB显存的3060、3070也能跑起来。硬盘方面建议留出至少40GB空间放权重和依赖缓存。
然后是部署工具。轻量验证可以直接用transformers加载；如果要做成生产API供IDE插件或内部平台调用，推荐vLLM，它对连续批处理和显存管理做得比较好，吞吐明显高于原生transformers。没有NVIDIA独立显卡的环境可以尝试llama.cpp或Ollama走CPU推理，但速度会慢很多。下面用一张表对比常见方案：
| 部署方案 | 显存需求参考 | 适用场景 | 特点 |
|---|---|---|---|
| transformers | FP16约18GB，INT4约8GB | 脚本调用、算法验证 | 灵活，但并发差 |
| vLLM | FP16约18GB，可调显存占满比例 | 生产API、高并发补全 | 吞吐高，支持OpenAI兼容 |
| Ollama/llama.cpp | INT4约7GB起 | 消费级显卡、Mac、无GPU | 部署简单，CPU可跑 |
实际部署前建议先确认NVIDIA驱动、CUDA和PyTorch版本是否匹配。例如使用CUDA 12.1时，PyTorch要装cu121版本，vLLM也要选择对应预编译包，否则会出现库加载失败、算子版本不匹配等奇怪报错。
二、本地部署步骤与OpenAI兼容接口调用
下面以Linux服务器和NVIDIA显卡为例，从零启动一个供局域网调用的补全服务。先创建独立环境并安装依赖：
conda create -n codegeex python=3.10 -y conda activate codegeex pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 pip install transformers accelerate sentencepiece pip install vllm fastapi uvicorn
依赖安装完成后，用vLLM启动OpenAI兼容服务。这里把模型名设为codegeex4-9b，限制最大序列长度和显存占用比例，避免启动时直接把整卡占满：
python -m vllm.entrypoints.openai.api_server \ --model THUDM/codegeex4-9b \ --served-model-name codegeex4-9b \ --max-model-len 8192 \ --gpu-memory-utilization 0.85 \ --port 8000
服务启动后，终端会输出Uvicorn running on http://127.0.0.1:8000 类似日志。可以用curl快速测试补全接口：
curl -X POST http://127.0.0.1:8000/v1/completions \
-H "Content-Type: application/json" \
-d '{"model": "codegeex4-9b", "prompt": "def quick_sort(arr):", "max_tokens": 256, "temperature": 0.2}'
返回的JSON里choices[0].text就是补全结果。为了方便外部程序接入，也可以使用Python的OpenAI客户端。只需要把base_url指向本地服务，api_key随便填一个非空字符串，vLLM不会做鉴权：
from openai import OpenAI
client = OpenAI(
base_url="http://127.0.0.1:8000/v1",
api_key="EMPTY"
)
resp = client.completions.create(
model="codegeex4-9b",
prompt="# 读取CSV文件并统计每列缺失值\n",
max_tokens=512,
temperature=0.1
)
print(resp.choices[0].text)
如果暂时不需要服务化，也可以直接用transformers加载模型做单次推理。本地权重路径在Windows下要特别注意反斜杠转义，例如 D:\models\codegeex4-9b 传入Python时建议写成原始字符串 r"D:\models\codegeex4-9b" 或者 D:\\models\\codegeex4-9b，避免被当成转义字符。
三、性能评测与功能验证
为了给后续选型做参考，我在两块常见显卡上做了简单测试：RTX 3090 24GB和A100 40GB。FP16模型在3090上加载后会占用约17.5GB显存，单次补全请求平均耗时约0.9秒到1.4秒；A100上同样请求约0.4秒到0.6秒。启用vLLM连续批处理后，并发从1提到4时，吞吐提升约2.3倍到3倍。INT4量化版在3090上显存占用降到约7.8GB，单请求延迟略有增加，大约1.1秒到1.7秒，但可以让8GB到12GB显存的机器跑起来。
从补全质量看，CodeGeeX4-9B在函数级补全、注释生成和简单代码翻译任务上表现稳定。实测让它补全快速排序、读取CSV并统计缺失值、用Go写一个HTTP服务等任务，第一遍生成的可运行率较高。特别是在给定函数签名和明确中文注释的场景下，生成结果更贴近预期。下表汇总了测试结果：
| 测试项 | FP16延迟 | INT4延迟 | 显存占用 | 通过情况 |
|---|---|---|---|---|
| 快速排序函数补全 | 约1.0秒 | 约1.2秒 | 7.8GB到18GB | 一次通过 |
| CSV缺失值统计 | 约1.3秒 | 约1.6秒 | 同上 | 一次通过 |
| Go HTTP服务生成 | 约1.5秒 | 约1.9秒 | 同上 | 小幅修改后通过 |
新功能方面，CodeGeeX4-9B支持跨文件上下文补全和function calling。跨文件补全适合把当前仓库中多个相关文件作为背景，让模型理解现有函数和类型定义后再生成代码，能明显减少重复造轮子。function calling则可以把补全服务接入内部工具链，比如在IDE插件里让模型返回结构化调用参数，实现自动查询数据库Schema、自动生成测试用例等操作。
四、常见错误与解决方法
部署过程中最常遇到的是显存溢出。启动vLLM或加载模型时如果看到CUDA out of memory，不要直接加卡。先把 --max-model-len 从8192降到4096，或者把 --gpu-memory-utilization 从0.85调低到0.6。如果仍不够，就改用INT4量化模型，必要时设置 --dtype half 或 --quantization awq。单次推理的transformers脚本也可以通过 model.half().to(device) 降低显存占用。
另一个高频问题是模型权重下载失败或加载报错。很多内网服务器无法访问Hugging Face，这时候可以用ModelScope镜像或者提前把权重下载后离线加载。离线加载时要保证目录下包含config.json、tokenizer.json和权重分片文件，缺任何一个都会导致加载中断。vLLM加载自定义目录时常遇到tokenizer class not found，可以加上 --trust-remote-code，并确认已安装sentencepiece。
- 报错关键词：CUDA out of memory → 降低 seq length 或显存占用比例，切换INT4。
- 报错关键词：model is not a directory / connection error → 检查网络代理和模型路径，必要时离线下载。
- 报错关键词：tokenizer class not found → 安装sentencepiece，启动时添加 --trust-remote-code。
- 报错关键词：port 8000 is already in use → 换端口或执行 lsof -i:8000 找到占用进程。
- Windows环境：权重路径使用反斜杠时必须正确转义，不能直接写 D:\models 而不处理，否则 \m 等会被当成转义字符。
最后提醒一个容易忽略的细节：本地模型服务和外部API不同，vLLM默认没有鉴权，如果部署在局域网以外的机器上，必须用反向代理加认证，避免服务被公网扫描后滥用。生产环境还建议固定vLLM和transformers版本，最好把依赖写进requirements.txt，避免某次升级后出现接口或模型加载行为变化。