目录
- [1. 前言:为什么要本地部署 Codex](#1. 前言:为什么要本地部署 Codex)
- [5.1 创建隔离环境并安装依赖](#5.1 创建隔离环境并安装依赖)
- [5.2 模型权重放置与配置](#5.2 模型权重放置与配置)
- [5.3 启动本地服务](#5.3 启动本地服务)
- [5.4 跑通第一个任务](#5.4 跑通第一个任务)
- [6. 关键配置与性能调优](#6. 关键配置与性能调优)
- [7. 常见问题排查(FAQ)](#7. 常见问题排查(FAQ))
- [8. 安全与合规注意事项](#8. 安全与合规注意事项)
- [9. 总结与下一步](#9. 总结与下一步)
- [10. 附录](#10. 附录)
1. 前言:为什么要本地部署 Codex
- 云端调用与本地部署的差异对比
- 本地部署的典型收益:数据不出内网、可离线运行、可深度定制、成本可控

- 适用人群与典型场景(个人开发者 / 团队内网 / 教学演示)
- 本文目标:读完后能独立完成一次可运行的本地部署
下图对比了云端调用与本地部署两条链路的数据流向,可以直观看出本地部署在数据边界上的优势:
#mermaid-svg-9zi9AAtDhxoSqFlJ{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-9zi9AAtDhxoSqFlJ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-9zi9AAtDhxoSqFlJ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-9zi9AAtDhxoSqFlJ .error-icon{fill:#552222;}#mermaid-svg-9zi9AAtDhxoSqFlJ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-9zi9AAtDhxoSqFlJ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-9zi9AAtDhxoSqFlJ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-9zi9AAtDhxoSqFlJ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-9zi9AAtDhxoSqFlJ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-9zi9AAtDhxoSqFlJ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-9zi9AAtDhxoSqFlJ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-9zi9AAtDhxoSqFlJ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-9zi9AAtDhxoSqFlJ .marker.cross{stroke:#333333;}#mermaid-svg-9zi9AAtDhxoSqFlJ svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-9zi9AAtDhxoSqFlJ p{margin:0;}#mermaid-svg-9zi9AAtDhxoSqFlJ .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-9zi9AAtDhxoSqFlJ .cluster-label text{fill:#333;}#mermaid-svg-9zi9AAtDhxoSqFlJ .cluster-label span{color:#333;}#mermaid-svg-9zi9AAtDhxoSqFlJ .cluster-label span p{background-color:transparent;}#mermaid-svg-9zi9AAtDhxoSqFlJ .label text,#mermaid-svg-9zi9AAtDhxoSqFlJ span{fill:#333;color:#333;}#mermaid-svg-9zi9AAtDhxoSqFlJ .node rect,#mermaid-svg-9zi9AAtDhxoSqFlJ .node circle,#mermaid-svg-9zi9AAtDhxoSqFlJ .node ellipse,#mermaid-svg-9zi9AAtDhxoSqFlJ .node polygon,#mermaid-svg-9zi9AAtDhxoSqFlJ .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-9zi9AAtDhxoSqFlJ .rough-node .label text,#mermaid-svg-9zi9AAtDhxoSqFlJ .node .label text,#mermaid-svg-9zi9AAtDhxoSqFlJ .image-shape .label,#mermaid-svg-9zi9AAtDhxoSqFlJ .icon-shape .label{text-anchor:middle;}#mermaid-svg-9zi9AAtDhxoSqFlJ .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-9zi9AAtDhxoSqFlJ .rough-node .label,#mermaid-svg-9zi9AAtDhxoSqFlJ .node .label,#mermaid-svg-9zi9AAtDhxoSqFlJ .image-shape .label,#mermaid-svg-9zi9AAtDhxoSqFlJ .icon-shape .label{text-align:center;}#mermaid-svg-9zi9AAtDhxoSqFlJ .node.clickable{cursor:pointer;}#mermaid-svg-9zi9AAtDhxoSqFlJ .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-9zi9AAtDhxoSqFlJ .arrowheadPath{fill:#333333;}#mermaid-svg-9zi9AAtDhxoSqFlJ .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-9zi9AAtDhxoSqFlJ .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-9zi9AAtDhxoSqFlJ .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-9zi9AAtDhxoSqFlJ .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-9zi9AAtDhxoSqFlJ .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-9zi9AAtDhxoSqFlJ .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-9zi9AAtDhxoSqFlJ .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-9zi9AAtDhxoSqFlJ .cluster text{fill:#333;}#mermaid-svg-9zi9AAtDhxoSqFlJ .cluster span{color:#333;}#mermaid-svg-9zi9AAtDhxoSqFlJ div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-9zi9AAtDhxoSqFlJ .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-9zi9AAtDhxoSqFlJ rect.text{fill:none;stroke-width:0;}#mermaid-svg-9zi9AAtDhxoSqFlJ .icon-shape,#mermaid-svg-9zi9AAtDhxoSqFlJ .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-9zi9AAtDhxoSqFlJ .icon-shape p,#mermaid-svg-9zi9AAtDhxoSqFlJ .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-9zi9AAtDhxoSqFlJ .icon-shape .label rect,#mermaid-svg-9zi9AAtDhxoSqFlJ .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-9zi9AAtDhxoSqFlJ .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-9zi9AAtDhxoSqFlJ .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-9zi9AAtDhxoSqFlJ :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 本地部署
本地代码
本机/内网服务
本地模型权重
返回结果
云端调用
本地代码
公网传输
厂商托管模型
返回结果
5.1 创建隔离环境并安装依赖
5.2 模型权重放置与配置
- 硬件要求:CPU / 内存 / 显存的最低配置与推荐配置
- 不同量化精度下的显存占用估算表
- 操作系统与驱动:Linux / macOS / Windows(WSL2)
- Python 版本与 CUDA / ROCm 版本匹配
- 依赖管理:conda 与 venv 的取舍
- 网络与镜像源配置(pip / Hugging Face 加速)
不同量化精度下的显存占用大致关系如下(以 7B 级模型为例,实际数值随模型规模线性增长):
| 量化精度 | 单参数位宽 | 7B 模型权重显存 | 适用场景 |
|---|---|---|---|
| FP16 | 16 bit | 约 14 GB | 精度优先,显存充足 |
| INT8 | 8 bit | 约 7 GB | 精度与显存平衡 |
| INT4 | 4 bit | 约 4 GB | 消费级显卡、显存受限 |
5.3 启动本地服务
- 方式一:官方仓库克隆(git clone + 选择版本 tag)
- 方式二:包管理器安装(pip / npm / brew)
- 方式三:模型权重下载(Hugging Face / ModelScope)
- 下载完整性校验:文件大小、哈希值、目录结构确认
- 常见下载失败原因与排查清单
三种获取方式的决策路径如下:
#mermaid-svg-hXRSmP55JC838Qqp{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-hXRSmP55JC838Qqp .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-hXRSmP55JC838Qqp .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-hXRSmP55JC838Qqp .error-icon{fill:#552222;}#mermaid-svg-hXRSmP55JC838Qqp .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-hXRSmP55JC838Qqp .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-hXRSmP55JC838Qqp .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-hXRSmP55JC838Qqp .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-hXRSmP55JC838Qqp .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-hXRSmP55JC838Qqp .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-hXRSmP55JC838Qqp .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-hXRSmP55JC838Qqp .marker{fill:#333333;stroke:#333333;}#mermaid-svg-hXRSmP55JC838Qqp .marker.cross{stroke:#333333;}#mermaid-svg-hXRSmP55JC838Qqp svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-hXRSmP55JC838Qqp p{margin:0;}#mermaid-svg-hXRSmP55JC838Qqp .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-hXRSmP55JC838Qqp .cluster-label text{fill:#333;}#mermaid-svg-hXRSmP55JC838Qqp .cluster-label span{color:#333;}#mermaid-svg-hXRSmP55JC838Qqp .cluster-label span p{background-color:transparent;}#mermaid-svg-hXRSmP55JC838Qqp .label text,#mermaid-svg-hXRSmP55JC838Qqp span{fill:#333;color:#333;}#mermaid-svg-hXRSmP55JC838Qqp .node rect,#mermaid-svg-hXRSmP55JC838Qqp .node circle,#mermaid-svg-hXRSmP55JC838Qqp .node ellipse,#mermaid-svg-hXRSmP55JC838Qqp .node polygon,#mermaid-svg-hXRSmP55JC838Qqp .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-hXRSmP55JC838Qqp .rough-node .label text,#mermaid-svg-hXRSmP55JC838Qqp .node .label text,#mermaid-svg-hXRSmP55JC838Qqp .image-shape .label,#mermaid-svg-hXRSmP55JC838Qqp .icon-shape .label{text-anchor:middle;}#mermaid-svg-hXRSmP55JC838Qqp .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-hXRSmP55JC838Qqp .rough-node .label,#mermaid-svg-hXRSmP55JC838Qqp .node .label,#mermaid-svg-hXRSmP55JC838Qqp .image-shape .label,#mermaid-svg-hXRSmP55JC838Qqp .icon-shape .label{text-align:center;}#mermaid-svg-hXRSmP55JC838Qqp .node.clickable{cursor:pointer;}#mermaid-svg-hXRSmP55JC838Qqp .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-hXRSmP55JC838Qqp .arrowheadPath{fill:#333333;}#mermaid-svg-hXRSmP55JC838Qqp .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-hXRSmP55JC838Qqp .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-hXRSmP55JC838Qqp .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-hXRSmP55JC838Qqp .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-hXRSmP55JC838Qqp .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-hXRSmP55JC838Qqp .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-hXRSmP55JC838Qqp .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-hXRSmP55JC838Qqp .cluster text{fill:#333;}#mermaid-svg-hXRSmP55JC838Qqp .cluster span{color:#333;}#mermaid-svg-hXRSmP55JC838Qqp div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-hXRSmP55JC838Qqp .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-hXRSmP55JC838Qqp rect.text{fill:none;stroke-width:0;}#mermaid-svg-hXRSmP55JC838Qqp .icon-shape,#mermaid-svg-hXRSmP55JC838Qqp .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-hXRSmP55JC838Qqp .icon-shape p,#mermaid-svg-hXRSmP55JC838Qqp .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-hXRSmP55JC838Qqp .icon-shape .label rect,#mermaid-svg-hXRSmP55JC838Qqp .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-hXRSmP55JC838Qqp .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-hXRSmP55JC838Qqp .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-hXRSmP55JC838Qqp :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 是
否
是
否
需要获取 Codex
是否需要改源码
方式一:git clone 官方仓库
是否只需命令行工具
方式二:pip / npm / brew 安装
方式三:下载模型权重
校验文件大小与哈希值
5.4 跑通第一个任务
- 用 curl 调用本地接口的最小示例
- 用 Python SDK 调用的完整示例
- 在 IDE 插件中接入本地服务地址
- 验证输出质量与响应耗时
一次完整的调用链路如下:
"模型权重" "本地 Codex 服务" "curl / Python SDK / IDE 插件" "开发者" "模型权重" "本地 Codex 服务" "curl / Python SDK / IDE 插件" "开发者" #mermaid-svg-mhFLK7jqy4HMiXV2{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-mhFLK7jqy4HMiXV2 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-mhFLK7jqy4HMiXV2 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-mhFLK7jqy4HMiXV2 .error-icon{fill:#552222;}#mermaid-svg-mhFLK7jqy4HMiXV2 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-mhFLK7jqy4HMiXV2 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-mhFLK7jqy4HMiXV2 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-mhFLK7jqy4HMiXV2 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-mhFLK7jqy4HMiXV2 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-mhFLK7jqy4HMiXV2 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-mhFLK7jqy4HMiXV2 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-mhFLK7jqy4HMiXV2 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-mhFLK7jqy4HMiXV2 .marker.cross{stroke:#333333;}#mermaid-svg-mhFLK7jqy4HMiXV2 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-mhFLK7jqy4HMiXV2 p{margin:0;}#mermaid-svg-mhFLK7jqy4HMiXV2 .actor{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-mhFLK7jqy4HMiXV2 text.actor>tspan{fill:black;stroke:none;}#mermaid-svg-mhFLK7jqy4HMiXV2 .actor-line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-mhFLK7jqy4HMiXV2 .innerArc{stroke-width:1.5;stroke-dasharray:none;}#mermaid-svg-mhFLK7jqy4HMiXV2 .messageLine0{stroke-width:1.5;stroke-dasharray:none;stroke:#333;}#mermaid-svg-mhFLK7jqy4HMiXV2 .messageLine1{stroke-width:1.5;stroke-dasharray:2,2;stroke:#333;}#mermaid-svg-mhFLK7jqy4HMiXV2 #arrowhead path{fill:#333;stroke:#333;}#mermaid-svg-mhFLK7jqy4HMiXV2 .sequenceNumber{fill:white;}#mermaid-svg-mhFLK7jqy4HMiXV2 #sequencenumber{fill:#333;}#mermaid-svg-mhFLK7jqy4HMiXV2 #crosshead path{fill:#333;stroke:#333;}#mermaid-svg-mhFLK7jqy4HMiXV2 .messageText{fill:#333;stroke:none;}#mermaid-svg-mhFLK7jqy4HMiXV2 .labelBox{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-mhFLK7jqy4HMiXV2 .labelText,#mermaid-svg-mhFLK7jqy4HMiXV2 .labelText>tspan{fill:black;stroke:none;}#mermaid-svg-mhFLK7jqy4HMiXV2 .loopText,#mermaid-svg-mhFLK7jqy4HMiXV2 .loopText>tspan{fill:black;stroke:none;}#mermaid-svg-mhFLK7jqy4HMiXV2 .loopLine{stroke-width:2px;stroke-dasharray:2,2;stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);}#mermaid-svg-mhFLK7jqy4HMiXV2 .note{stroke:#aaaa33;fill:#fff5ad;}#mermaid-svg-mhFLK7jqy4HMiXV2 .noteText,#mermaid-svg-mhFLK7jqy4HMiXV2 .noteText>tspan{fill:black;stroke:none;}#mermaid-svg-mhFLK7jqy4HMiXV2 .activation0{fill:#f4f4f4;stroke:#666;}#mermaid-svg-mhFLK7jqy4HMiXV2 .activation1{fill:#f4f4f4;stroke:#666;}#mermaid-svg-mhFLK7jqy4HMiXV2 .activation2{fill:#f4f4f4;stroke:#666;}#mermaid-svg-mhFLK7jqy4HMiXV2 .actorPopupMenu{position:absolute;}#mermaid-svg-mhFLK7jqy4HMiXV2 .actorPopupMenuPanel{position:absolute;fill:#ECECFF;box-shadow:0px 8px 16px 0px rgba(0,0,0,0.2);filter:drop-shadow(3px 5px 2px rgb(0 0 0 / 0.4));}#mermaid-svg-mhFLK7jqy4HMiXV2 .actor-man line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;}#mermaid-svg-mhFLK7jqy4HMiXV2 .actor-man circle,#mermaid-svg-mhFLK7jqy4HMiXV2 line{stroke:hsl(259.6261682243, 59.7765363128%, 87.9019607843%);fill:#ECECFF;stroke-width:2px;}#mermaid-svg-mhFLK7jqy4HMiXV2 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 发起代码补全请求 POST /v1/completions 推理 生成结果 返回 JSON 响应 展示补全内容与耗时
6. 关键配置与性能调优
-
量化方案选择:精度、速度、显存三者的权衡
-
上下文长度与显存占用的关系
-
批处理与并发设置
-
GPU 显存不足时的降级策略(offload / 更小模型 / CPU 推理)
-
推理加速:vLLM、llama.cpp 等后端对比## 7. 常见问题排查(FAQ)
-
启动报错:CUDA 版本不匹配
-
加载失败:权重文件缺失或路径错误
-
推理极慢:是否走了 CPU、是否未启用量化
-
显存 OOM:如何定位与缓解
-
接口调用 401/404:鉴权与路由配置问题
-
中文输出乱码或截断:编码与 max_tokens 设置
8. 安全与合规注意事项
- 本地服务不要直接暴露公网
- 简单的访问控制与鉴权方案
- 日志与代码数据的留存策略
- 模型许可证与商用限制确认
9. 总结与下一步
- 部署流程回顾:环境 → 下载 → 配置 → 启动 → 验证
- 从「跑通」到「用好」的进阶方向
- 推荐的学习资源与社区
10. 附录
- 完整命令速查表
- 推荐硬件配置清单
- 参考链接汇总