1. 为什么我选择把 Codex 搬到本地跑第一次接触 Codex 是在一个赶项目的深夜当时用云端版本补全一段 Python 数据清洗逻辑网络延迟加上请求排队敲三行代码要等两秒才出提示那种感觉就像跟一个反应迟钝的搭档配合思路全被打断了。后来我下定决心把它弄到本地来折腾了大概一个周末从 Docker 环境配置到模型权重加载中间踩了不少坑但跑通之后那种“代码刚敲一半补全已经整段铺好”的流畅感确实值得花这个时间。Codex 本质上是一个面向代码生成与补全的大语言模型应用它可以根据你写的注释、函数签名或者半截代码自动推断你接下来想写什么并且给出符合上下文语境的建议。把它部署在本地最大的好处有三个数据不出本机公司内部代码不用担心外传响应速度快省去了网络往返的时间可定制性强你可以针对自己的代码库做微调让它更懂你的项目风格。这篇文章适合两类人看一类是手头有闲置显卡、想自己搭一套 AI 编程助手的开发者另一类是单纯对本地部署大语言模型感兴趣、想拿 Codex 当练手项目的技术爱好者。不管你之前有没有用过 Docker只要跟着步骤走基本都能跑起来。我会把每个环节的“为什么这么做”讲清楚而不是只丢一堆命令让你复制粘贴。2. 部署前的整体思路与环境选型2.1 为什么用 Docker 而不是裸机安装很多人第一反应是直接在系统上装 Python 环境、拉模型权重、配依赖但这种方式有个致命问题环境冲突。Codex 依赖的 Python 版本、CUDA 版本、各种底层库跟你系统里已有的环境很容易打架。我之前在一台开发机上裸装过一次结果把原本跑得好好的一个数据分析项目搞崩了排查了半天才发现是 numpy 版本被覆盖了。Docker 的好处在于容器资源隔离。每个容器有自己独立的文件系统、网络栈和进程空间Codex 需要什么依赖就在容器里装什么跟宿主机完全隔开。就算你把容器里的环境搞乱了删掉重建就行不会影响外面的任何东西。这也是为什么现在本地部署大语言模型、部署各种 AI 应用Docker 几乎是标配方案。另一个实际考量是迁移方便。你在开发机上调好的容器配置可以原封不动搬到另一台机器上跑只要那台机器装了 Docker 和显卡驱动基本不会出问题。我后来把整套环境从台式机搬到一台带显卡的迷你主机上前后不到二十分钟就搞定了。2.2 硬件门槛与显卡选择Codex 这类代码模型对硬件的要求主要看你想跑多大的参数量。我整理了一个简单的对照表方便你判断自己的机器能不能扛得住模型规模最低显存推荐显存量化后显存实际体验1B-3B4GB8GB2GB补全速度极快复杂逻辑偏弱7B8GB12GB4GB日常补全够用性价比最高13B12GB16GB8GB代码理解明显更好34B24GB32GB16GB接近云端体验硬件成本高如果你手头只有一张 8GB 显存的卡我建议从 7B 量化版本开始跑实际用下来补全日常业务代码完全没问题。量化简单说就是把模型参数的精度从 16 位压缩到 4 位或 8 位模型体积和显存占用大幅下降代价是精度有一点点损失但在代码补全这个场景里几乎感觉不出来。注意如果你用的是 AMD 显卡或者 Apple Silicon 芯片Docker 对 GPU 直通的支持不如 NVIDIA 成熟建议先确认你的平台有没有对应的容器运行时方案否则可能只能跑 CPU 推理速度会慢很多。2.3 系统环境与依赖清单我这次演示用的是 Ubuntu 22.04这是目前兼容性最好的选择。Windows 用户可以用 Docker Desktop但要注意开启 WSL2 后端否则容器性能会打折扣。macOS 用户如果用的是 M 系列芯片Docker Desktop 也能跑但 GPU 加速需要额外配置。开始之前你需要确认这几样东西已经就位Docker Engine 24.0 以上或者 Docker Desktop 最新版NVIDIA 显卡驱动 525 以上如果用 NVIDIA 卡NVIDIA Container Toolkit这是让容器能访问显卡的关键组件至少 50GB 空闲磁盘模型权重和镜像加起来占空间不小Python 3.10 以上如果你打算在容器外写调用脚本检查 Docker 是否装好终端里敲一行docker --version看到版本号输出就说明没问题。如果提示命令找不到先去 Docker 官网下载对应系统的安装包安装教程网上很多这里不展开。3. 核心环节拆解从拉取镜像到跑通第一个请求3.1 镜像选择与拉取策略Codex 本身是一个模型但要在本地跑起来你需要一个推理服务框架来加载它。目前主流的选择有几种我对比一下各自的特点框架优势劣势适合场景Ollama开箱即用命令简单定制性一般快速体验vLLM吞吐量高支持并发配置稍复杂多人共用Text Generation Inference官方维护稳定镜像体积大生产环境llama.cppCPU 也能跑轻量GPU 加速有限无显卡环境我这次选的是Ollama作为推理后端原因是它对新手最友好一条命令就能拉模型跑起来而且社区活跃遇到问题容易找到答案。等你能跑通之后再考虑换成 vLLM 提升并发性能也不迟。拉取 Ollama 镜像docker pull ollama/ollama:latest这个镜像大概 1GB 左右取决于你的网络情况几分钟到十几分钟不等。拉完之后可以用docker images确认一下。3.2 启动容器与显卡直通配置这是整个部署过程中最容易出问题的一步。很多人卡在“容器启动了但用不了显卡”这个环节原因通常是 NVIDIA Container Toolkit 没装好或者启动命令里没加--gpus参数。先确认 Toolkit 是否安装nvidia-ctk --version有版本输出就说明装好了。如果没有Ubuntu 下可以这样装sudo apt-get install -y nvidia-container-toolkit sudo systemctl restart docker然后启动 Ollama 容器关键参数我逐个解释docker run -d \ --gpus all \ -v ollama_data:/root/.ollama \ -p 11434:11434 \ --name codex-ollama \ ollama/ollama:latest--gpus all把宿主机所有显卡暴露给容器这是 GPU 加速的前提-v ollama_data:/root/.ollama把模型数据挂载到命名卷容器删了模型还在不用重新下载-p 11434:11434把容器内的服务端口映射到宿主机后面调用 API 要用--name codex-ollama给容器起个名字方便管理启动之后用docker ps看看容器是不是在运行状态。如果状态是Exited用docker logs codex-ollama看日志大概率是显卡驱动或者 Toolkit 的问题。实操心得如果你在 Windows 上用 Docker Desktop--gpus all这个参数可能不生效需要在 Docker Desktop 设置里开启 GPU 支持并且确保 WSL2 内核版本足够新。我在这上面浪费过两个小时最后发现是 WSL 内核太旧。3.3 拉取模型权重与量化版本选择容器跑起来之后进入容器内部拉模型docker exec -it codex-ollama bash然后在容器里执行ollama pull codellama:7b这里我选的是 CodeLlama 的 7B 版本它是 Meta 开源的代码模型跟 Codex 的能力定位接近而且社区支持好。如果你显存比较紧张可以拉量化版本ollama pull codellama:7b-instruct-q4_0q4_0表示 4 位量化模型体积从 13GB 左右降到 4GB 上下显存占用也大幅下降。实测下来量化后的补全质量在日常业务代码场景里跟全精度版本差距很小但速度提升明显。模型下载时间取决于你的网络7B 全精度大概 13GB量化版 4GB 左右。下载过程中可以用ollama list查看进度。3.4 验证服务是否正常模型拉完之后在容器里直接测试一下ollama run codellama:7b进入交互模式后输入一段代码注释看看它能不能补全。比如# 写一个 Python 函数读取 CSV 文件并返回每列的平均值如果模型开始输出代码说明推理服务正常。输入/bye退出交互模式。接下来测试 API 是否可以从宿主机访问curl http://localhost:11434/api/generate -d { model: codellama:7b, prompt: def calculate_average(numbers):, stream: false }如果返回 JSON 格式的结果说明整个链路已经通了。这一步很关键因为后面你要把它接入编辑器插件靠的就是这个 API。4. 接入编辑器与日常使用配置4.1 VS Code 插件配置模型跑起来只是第一步真正提升效率的是把它接入你的代码编辑器。VS Code 上有一个叫Continue的插件支持自定义 API 端点正好可以对接我们本地跑的 Ollama 服务。安装完插件后打开配置文件config.json填入以下内容{ models: [ { title: Local Codex, provider: ollama, model: codellama:7b, apiBase: http://localhost:11434 } ], tabAutocompleteModel: { title: Local Autocomplete, provider: ollama, model: codellama:7b } }保存之后重启 VS Code你应该能在插件面板里看到本地模型已经加载。打开一个代码文件开始敲代码如果补全提示正常弹出说明配置成功。注意apiBase填的是http://localhost:11434不是容器内部的地址。因为端口已经映射到宿主机了编辑器直接访问宿主机端口就行。4.2 补全触发方式与延迟调优默认情况下Continue 会在你打字停顿的时候触发补全请求。但本地模型的推理速度跟云端没法比如果触发太频繁反而会拖慢编辑体验。我建议调整几个参数防抖延迟设置成 300-500 毫秒避免每敲一个字符就发请求最大 token 数限制在 128 以内补全不需要太长上下文行数控制在 20 行左右太多会拖慢推理这些参数在 Continue 的设置界面里都能找到。我实测下来7B 量化模型在 8GB 显存的机器上一次补全请求大概 0.5 到 1 秒返回基本不影响编码节奏。4.3 多模型切换与场景适配不同场景对模型的要求不一样。写业务逻辑的时候7B 模型够用但如果你在重构复杂算法或者写正则表达式可能需要更大的模型。Ollama 支持同时拉多个模型你可以根据场景切换。比如再拉一个 13B 的模型ollama pull codellama:13b然后在 Continue 配置里加一个模型条目需要的时候手动切换。不过要注意13B 模型对显存要求更高8GB 卡跑量化版勉强可以全精度就吃力了。我自己的习惯是日常补全用 7B 量化版遇到复杂逻辑手动切到 13B写完再切回来。虽然多了一步操作但整体效率比一直用大模型高因为小模型的响应速度确实快很多。5. 常见问题与排查技巧实录5.1 容器启动失败类问题问题一docker: Error response from daemon: could not select device driver with capabilities: [[gpu]]这个报错说明 NVIDIA Container Toolkit 没装好或者 Docker 服务没有重启。解决步骤sudo apt-get install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtimedocker sudo systemctl restart docker重启之后再跑一次启动命令基本就能解决。问题二容器启动后立刻退出日志显示no CUDA-capable device detected这说明容器里看不到显卡。先确认宿主机上nvidia-smi能正常输出然后检查 Docker 启动参数里有没有加--gpus all。如果都正常可能是驱动版本跟 CUDA 版本不匹配需要升级显卡驱动。问题三Windows 上 Docker Desktop 启动报virtualization support not detected这是 BIOS 里虚拟化技术没开启。重启进 BIOS找到 Intel VT-x 或 AMD-V 选项设为 Enabled。保存重启后再开 Docker Desktop 就行了。5.2 模型加载与推理类问题问题四模型拉取到一半卡住不动通常是网络问题。Ollama 的模型仓库在国内访问有时候不稳定可以尝试换一个时间段或者配置镜像加速。如果实在拉不下来可以手动下载模型文件然后导入。问题五推理速度极慢一次补全要等十几秒先确认容器是不是真的在用 GPU。进入容器执行nvidia-smi如果能看到进程列表里有 Ollama说明 GPU 在工作。如果看不到说明跑在 CPU 上速度慢是正常的。检查启动参数和 Toolkit 安装情况。另一个可能的原因是模型太大显存不够系统自动降级到 CPU 推理。用docker stats看一下容器的资源占用如果显存接近满载换小一号的量化版本。问题六补全结果质量差经常给出无关代码检查一下你用的模型是不是 instruct 版本。基础版本只做续写不理解指令instruct 版本经过指令微调更懂你的意图。拉模型的时候注意标签codellama:7b-instruct才是对话和补全都支持的版本。5.3 日常使用中的避坑清单现象可能原因解决方向容器重启后模型丢失没挂载数据卷启动时加-v参数端口被占用11434 已被其他程序使用换映射端口如-p 11435:11434补全提示不弹出插件配置的 API 地址不对确认apiBase指向宿主机端口显存溢出报错模型太大或并发请求过多换量化版限制并发数中文注释补全乱码模型对中文支持弱用英文写注释或换中文优化模型实操心得我建议在容器启动命令里加上--restart unless-stopped这样机器重启后容器会自动拉起来不用每次手动启动。另外定期用docker system prune清理无用镜像和缓存不然磁盘很快就会被占满。6. 性能调优与进阶玩法6.1 显存优化与并发控制如果你只有一张显卡同时跑多个请求的时候显存很容易爆。Ollama 默认的并发数比较保守但你可以通过环境变量调整docker run -d \ --gpus all \ -e OLLAMA_NUM_PARALLEL2 \ -e OLLAMA_MAX_LOADED_MODELS1 \ -v ollama_data:/root/.ollama \ -p 11434:11434 \ --name codex-ollama \ ollama/ollama:latestOLLAMA_NUM_PARALLEL2表示同时处理两个请求OLLAMA_MAX_LOADED_MODELS1表示只保留一个模型在显存里。这两个参数要根据你的显存大小来调显存小就设成 1显存充裕可以适当提高。6.2 针对自己代码库做微调通用模型对你项目里的私有库、内部框架了解有限补全的时候经常给出不存在的函数名。解决办法是用你自己的代码库做一次轻量微调。这个过程叫LoRA 微调只需要少量数据就能让模型学会你的代码风格。大致流程是从项目里导出几百个高质量代码文件整理成问答对格式然后用微调工具跑几个小时。微调后的模型在补全你项目代码时准确率会明显提升。这块内容展开讲篇幅太长后面可以单独写一篇。6.3 多容器编排与资源隔离如果你除了 Codex 还想跑其他 AI 服务比如本地知识库、语音识别建议用 Docker Compose 做统一编排。每个服务一个容器通过内部网络通信资源互不干扰。一个简单的 Compose 文件示例version: 3.8 services: codex: image: ollama/ollama:latest deploy: resources: reservations: devices: - driver: nvidia count: all capabilities: [gpu] volumes: - ollama_data:/root/.ollama ports: - 11434:11434 restart: unless-stopped volumes: ollama_data:这样管理起来比手敲docker run清晰得多而且版本控制方便配置文件往仓库里一放换机器直接拉下来就能跑。7. 我在这套方案上踩过的坑与最终建议回过头看整个部署过程最耗时间的不是技术难点而是那些“看起来没问题但就是不工作”的细节。比如有一次容器启动成功、模型也加载了但编辑器里死活不出补全提示排查了半天发现是插件配置里apiBase多写了一个斜杠。还有一次是显卡驱动自动更新后Container Toolkit 版本没跟上导致 GPU 直通失效重新配置一遍才恢复。如果你打算长期用这套本地环境我的建议是把容器配置写成文件管理起来别依赖手敲命令。Docker Compose 也好自己写个启动脚本也好总之要能一键重建。因为本地部署的环境迟早会因为驱动更新、系统升级、磁盘清理之类的原因出问题能快速重建比什么都重要。另外模型版本要固定。Ollama 的latest标签会随着上游更新变化今天跑得好好的版本明天拉下来可能行为就不一样了。生产环境里建议用具体的版本号标签比如codellama:7b-instruct-q4_0避免意外。最后说一个实际体验本地 Codex 在补全重复性代码、生成单元测试、写文档字符串这几个场景下表现最好能省掉大量机械劳动。但涉及复杂业务逻辑推理的时候还是得靠自己别指望模型能替你思考架构问题。把它当成一个手速极快、记忆力极好但缺乏全局视野的助手这个定位最准确。