1. 为什么要在本地跑一个 AI 编程助手先把话说在前头Codex 这类 AI 编程助手本质上是把大模型的代码理解与生成能力包装成一个能读你项目、能改你文件、能跑命令的“结对程序员”。它和你在网页里聊天问代码最大的区别是它能直接接触你的工程目录理解上下文甚至帮你执行构建和测试。这个能力一旦放到本地价值就完全不一样了。我最早是在一个内网项目里被迫走上本地部署这条路的。那个项目代码不能出内网任何云端 API 都碰不得但团队又确实需要 AI 辅助来提速。折腾了一圈之后我发现把 Codex 这类工具落到本地核心要解决三件事模型从哪来、运行环境怎么隔离、工具怎么和模型对接。这三件事想清楚了剩下的都是体力活。这篇文章适合三类人看。第一类是手里有代码隐私顾虑、想把 AI 助手关在自己机器里的开发者第二类是刚接触 Docker、想找个真实项目练手的运维或后端同学第三类是想搞明白“本地部署大模型”到底是怎么回事、不想被各种教程绕晕的技术爱好者。我会从零开始把下载、环境准备、容器编排、模型接入、常见报错排查这一整条链路讲透参数怎么算、为什么这么选我都会说清楚。需要提前说明的是Codex 本身是一个客户端工具它自己不带模型你得给它配一个能说“OpenAI 兼容协议”的后端。这个后端可以是本地跑的开源模型也可以是别的兼容服务。理解了这一点后面所有的配置你都不会觉得突兀。2. 整体方案设计与选型思路2.1 为什么用 Docker 而不是直接装在本机很多人第一反应是“我直接下载安装包双击不就行了”。对于纯客户端工具这样确实可以。但一旦你要在本地跑模型服务直接装本机就是灾难的开始。模型运行依赖特定版本的运行时、特定的 CUDA 或 CPU 指令集、一堆 Python 包装完之后你本机的环境基本就废了换个项目就冲突。Docker 解决的就是这个隔离问题。你可以把它理解成“给每个服务发一个独立的集装箱”箱子里装什么、什么版本和外面互不干扰。模型服务一个箱子数据库一个箱子Codex 客户端一个箱子谁也别污染谁。删掉箱子本机干干净净。提示Docker Desktop 在 Windows 和 macOS 上是带图形界面的发行版Linux 上一般直接装 Docker Engine。本文以 Docker Desktop 为主因为它对新手最友好。2.2 模型后端的三种选择Codex 需要一个兼容 OpenAI 接口的后端。市面上常见的有三条路方案代表工具优点缺点适合谁本地推理框架Ollama、llama.cpp部署极简一条命令拉模型大模型吃内存速度看硬件个人开发者、小团队自建推理服务vLLM、TGI吞吐高支持并发配置复杂显存要求高有 GPU 的团队兼容网关各类 OpenAI 兼容代理可对接多种后端需要额外维护想统一入口的人我个人的建议是如果你只是自己用Ollama 起步最省心如果你要给团队提供共享服务再考虑 vLLM 这类。本文的主线用 Ollama因为它把“下载模型”这件事简化到了极致特别适合第一次做本地部署的人。2.3 整体架构长什么样把链路画清楚后面就不会迷路。整个系统分三层最底层是模型服务跑在容器里对外暴露一个 HTTP 接口路径类似/v1/chat/completions。中间层是 Codex 客户端它读取配置把请求发到上面那个接口拿到回复后决定是显示给你还是直接改文件。最上层是你的项目目录Codex 需要被授权访问这个目录才能读代码、写代码。三层之间靠网络端口和配置文件连接。理解了这一点后面任何一个环节出问题你都能快速定位是哪一层的事。3. 环境准备与 Docker 安装实操3.1 硬件与系统的最低门槛在动手之前先对一下自己的机器别装到一半发现跑不动。内存跑 7B 级别的模型建议至少 16GB 内存跑 14B 以上32GB 起步。模型加载后是常驻内存的不是用完就释放。显存有独立显卡会快很多。N 卡 8GB 显存能跑 7B 量化版12GB 以上能跑 14B 量化版。没有独显也能用 CPU 跑就是慢。磁盘模型文件动辄几个 GB 到几十 GB留出至少 50GB 空闲空间。系统Windows 10/11 64 位、macOS 12 以上、主流 Linux 发行版都可以。注意Windows 上 Docker Desktop 依赖虚拟化功能。如果你在 BIOS 里没开虚拟化启动时会报 “virtualization support not detected” 这类错误先去 BIOS 打开 VT-x 或 AMD-V。3.2 Docker Desktop 安装的完整步骤以 Windows 为例把每一步都说清楚。去 Docker 官网下载 Docker Desktop 安装包。注意选对系统架构绝大多数人是 x86_64。双击安装安装向导里勾选 “Use WSL 2 instead of Hyper-V”如果你的系统支持 WSL 2。WSL 2 的性能和兼容性都比老的 Hyper-V 方案好。安装完成后重启电脑。这一步别省很多“启动失败”都是没重启导致的。首次启动 Docker Desktop它会让你接受服务条款然后等待引擎启动。右下角托盘图标变绿说明引擎跑起来了。打开终端执行docker version能看到 Client 和 Server 两段信息就说明装好了。如果你在 Linux 上用包管理器装更直接# Ubuntu/Debian 系 sudo apt update sudo apt install -y docker.io docker-compose-plugin sudo systemctl enable --now docker # 把当前用户加入 docker 组避免每次都要 sudo sudo usermod -aG docker $USER执行完usermod之后要重新登录一次用户组变更才生效。3.3 验证 Docker 是否真的能用装完别急着往下走先跑个最经典的测试容器docker run --rm hello-world看到 “Hello from Docker!” 就说明整条链路通了。如果这一步就报错后面全是白搭先解决它。常见的启动失败原因我整理成了一张表报错信息原因解决方向virtualization support not detectedBIOS 虚拟化没开进 BIOS 开启 VT-x/AMD-VDocker Desktop failed to startWSL 2 未安装或版本旧安装/更新 WSL 2 内核port is already allocated端口被占用换端口或停掉占用进程no space left on device磁盘满清理镜像或扩容4. 本地模型服务的部署与配置4.1 用容器跑起模型服务Ollama 官方提供了镜像用 Docker 跑起来很干净。下面这条命令是我常用的docker run -d \ --name ollama \ -p 11434:11434 \ -v ollama_data:/root/.ollama \ --restart unless-stopped \ ollama/ollama逐段解释一下为什么这么写-d让容器后台运行不占着你的终端。-p 11434:11434把容器内的 11434 端口映射到本机。这个端口是 Ollama 的默认 API 端口Codex 后面就要连它。-v ollama_data:/root/.ollama是关键。模型文件很大如果不挂载数据卷容器一删模型就没了下次还得重新下。挂载之后模型存在命名卷里容器重建也不丢。--restart unless-stopped让容器在 Docker 启动时自动拉起机器重启后服务还在。提示如果你有 N 卡并且装了驱动可以加上--gpus all让容器用上 GPU。前提是宿主机装了 NVIDIA Container Toolkit否则会报错。4.2 拉取并验证模型容器起来之后进容器拉一个模型。以常见的 7B 模型为例docker exec -it ollama ollama pull qwen2.5-coder:7b拉取时间取决于网速几个 GB 的文件耐心等。拉完之后验证一下docker exec -it ollama ollama list能看到模型名字和大小就对了。再测一下接口能不能通curl http://localhost:11434/v1/models返回一个 JSON里面有模型列表说明服务正常。这个/v1前缀很重要因为 Codex 走的是 OpenAI 兼容协议路径必须对得上。4.3 模型选型的参数账怎么算很多人纠结选多大的模型。我给一个粗略的估算方法帮你心里有数。模型加载占用的内存大致等于“参数量 × 每参数字节数”。以 7B 模型为例FP16 精度7B × 2 字节 ≈ 14GBINT8 量化7B × 1 字节 ≈ 7GBINT4 量化7B × 0.5 字节 ≈ 3.5GB所以一个 7B 的 INT4 量化模型大概 4GB 左右就能装下加上运行时开销8GB 内存能跑。14B 的 INT4 大概 8GB16GB 内存比较稳。这就是为什么我一直强调内存要留够。代码类任务对模型能力要求偏高7B 能应付简单的补全和解释复杂重构建议上 14B 甚至更大。如果硬件实在有限优先保证量化版本牺牲一点精度换可用性。5. Codex 客户端接入与联调5.1 客户端配置文件的写法Codex 客户端需要一个配置文件告诉它“后端在哪、用哪个模型”。不同版本的配置项名称可能略有差异但核心就几项。下面是一个典型的配置结构model qwen2.5-coder:7b model_provider local [model_providers.local] name Local Ollama base_url http://localhost:11434/v1 api_key ollama几个要点base_url一定要带/v1这是 OpenAI 兼容协议的标准前缀漏了会 404。api_key本地服务一般不校验但很多客户端要求这个字段非空随便填一个占位符即可。model的名字必须和ollama list里显示的完全一致大小写、冒号后的标签都不能错。5.2 联调时最容易踩的坑配置写完第一次跑起来大概率不会一次成功。我把最常见的几类问题列出来。第一类连接被拒。报错类似 “connection refused”。先确认容器还在跑docker ps。如果容器没了看日志docker logs ollama。如果容器在跑但连不上检查端口映射对不对以及你是不是在容器网络里用了localhost——容器内的localhost指的是容器自己不是宿主机。第二类模型不存在。报错类似 “model not found”。九成是模型名写错了或者模型根本没拉下来。回去ollama list对一遍。第三类协议不匹配。报错里出现 “not supported” 或者返回结构解析失败。这通常是客户端发的请求格式和后端期望的不一致。确认你用的是/v1路径而不是 Ollama 原生的/api路径。注意有些客户端会默认请求/responses这类端点而本地后端只实现了/chat/completions。遇到 “failed while handling endpoint” 这类报错先看客户端请求的路径再看后端支持哪些路径对不上就改配置。5.3 让 Codex 真正读到你项目的方法客户端连上模型只是第一步让它能操作你的项目还需要授权目录。一般是在启动客户端时指定工作目录或者在配置里写死项目路径。启动后你可以让它先做一个只读操作验证比如“列出当前目录下的所有 Python 文件”确认它能读到文件系统再让它做写操作。我个人的习惯是第一次接入新项目先让它解释一段代码再让它改一个无关紧要的注释最后才让它动真正的逻辑。这样万一配置有问题损失可控。6. 常见故障排查与避坑经验6.1 一张速查表搞定大部分报错现象可能原因排查动作容器起不来端口占用/镜像损坏docker logs看日志换端口接口 404路径少了 /v1检查 base_url接口 401api_key 为空填占位符模型加载慢内存不足在换页换更小量化模型响应超时模型太大 CPU 跑加超时或换 GPU中文乱码编码设置确认 UTF-86.2 我踩过的几个真实坑第一个坑是数据卷没挂载。我第一次跑的时候图省事没加-v结果容器更新一次几十 GB 的模型全没了重新下了一晚上。从那以后我所有带状态的容器都必挂卷。第二个坑是端口冲突。本机之前装过别的服务占了 11434容器起不来但报错很隐晦。后来养成习惯起容器前先netstat看一眼端口。第三个坑是模型名带标签。qwen2.5-coder和qwen2.5-coder:7b是两个不同的引用配置里写错一个字符就连不上。这种错误没有任何提示只能靠仔细。6.3 性能调优的几个实用手段如果跑起来觉得慢可以试这几招。一是换更小的量化模型INT4 比 FP16 快很多代码任务上差距没想象中大。二是给容器分配更多内存Docker Desktop 默认给 WSL 的内存可能偏小在设置里调大。三是如果有 GPU务必确认容器真的用上了进容器跑nvidia-smi看得到显卡才算数。还有一个容易被忽略的点模型首次加载会慢因为要从磁盘读进内存。之后的请求会快很多因为模型常驻了。所以别用第一次请求的耗时来判断性能。7. 后续可以怎么扩展跑通单机版之后这套架构其实很容易扩展。比如把模型服务放到一台带 GPU 的机器上其他同事通过内网连过来就变成了团队共享的 AI 助手。再比如把多个模型都拉下来在配置里切换针对不同任务用不同的模型。还可以把 Codex 和你的 CI 流程结合让它在提交前自动做一轮代码检查。我自己现在的用法是日常补全用小的快模型遇到复杂重构手动切到大的慢模型。这套组合拳打下来效率提升是实打实的。本地部署最大的好处不是省钱而是数据不出门、响应可控、想怎么改就怎么改。等你真正跑起来会发现之前担心的那些配置问题其实都是可以一次性解决的体力活。
