1. 先搞清楚 Codex 到底是什么别被名字带偏很多人第一次听到“Codex”这个词脑子里蹦出来的就是那个曾经在代码补全领域刷屏的模型名字。于是下意识觉得本地部署 Codex 就是下载一个模型权重、跑起来、然后对着它敲代码。我一开始也这么想直到真正动手搭了一套之后才发现这个理解从根上就偏了。Codex 在当下这个语境里更多指的是一整套代码生成服务的工程形态而不是某一个具体的模型文件。它可以是前端编辑器插件、可以是命令行工具、也可以是一个 HTTP 服务但它的核心能力——把自然语言或者上下文转换成可用的代码——背后依赖的往往是一个可替换的推理后端。也就是说Codex 是“壳”模型是“芯”。你可以用 DeepSeek可以用别的开源代码模型甚至可以用一个本地跑的小参数模型只要接口对得上Codex 这一层就能工作。这就引出了一个很现实的问题为什么要在本地部署这样一套东西我总结了几个真实动因。第一是数据不出内网很多团队的代码资产敏感不可能把整段业务逻辑发到外部接口去第二是可控性和可调试性线上服务挂了只能等本地部署出了问题可以自己看日志、改配置、换模型第三是成本结构高频调用场景下本地一张消费级显卡跑量化模型长期算下来比按 token 计费划算得多第四是定制空间你可以针对自己团队的代码规范、目录结构、命名习惯去调 prompt 和中间层逻辑这是通用服务给不了的。那这套东西适合谁来折腾我的判断是有一定 Linux 基础、能看懂 Python、愿意花一个周末把环境跑通的后端或者全栈开发者。纯小白也不是不能做但至少要能接受命令行操作遇到报错愿意去翻日志而不是直接放弃。如果你连pip install都没用过建议先补一下 Python 环境管理的基础不然会在依赖冲突上卡很久。这篇文章我会按照三层架构的思路来拆接入层负责对外提供接口和协议适配编排层负责请求处理、上下文管理和模型调度推理层负责真正跑模型出结果。这三层分开之后每一层都可以独立替换和调试这也是我在实际项目里觉得最稳的一种组织方式。下面我会把每一层的设计考量、关键参数、实操步骤和踩过的坑都摊开讲。2. 三层架构的整体设计与选型逻辑2.1 为什么是三层而不是一坨脚本我见过太多人本地部署 AI 服务的做法是写一个app.py里面既处理 HTTP 请求又拼 prompt又加载模型又做后处理全部塞在一起。跑是能跑但一旦要换模型、要加缓存、要接第二个前端整个文件就得大改。这种“一坨脚本”模式在 demo 阶段没问题但稍微正经一点就会失控。三层架构的价值在于关注点分离。接入层只关心“请求怎么进来、响应怎么出去”编排层只关心“这个请求该怎么处理、该调哪个模型、上下文怎么拼”推理层只关心“给定输入产出输出”。层与层之间通过明确的接口通信任何一层内部怎么实现其他层不需要知道。打个生活化的比方这就像一家餐厅。接入层是前台和服务员负责接待客人、记录点单、把菜端上桌编排层是后厨的调度决定这道菜该哪个灶台做、需要哪些备料、先做哪道推理层就是真正掌勺的厨师只管把给定的食材做成菜。前台换一套点单系统不影响厨师做菜厨师换人前台也不用改流程。2.2 各层的技术选型与理由接入层我选的是 FastAPI。理由很直接原生支持异步、自动生成 OpenAPI 文档、Pydantic 做请求校验非常省心、性能在 Python 框架里属于第一梯队。对于代码生成这种可能涉及流式输出的场景FastAPI 的StreamingResponse和 SSE 支持都很成熟。相比之下 Flask 更简单但异步支持弱Django 太重不适合这种轻量服务。编排层我倾向于用一个独立的 Python 模块不引入额外框架。核心职责包括请求预处理比如把编辑器传来的上下文整理成模型能吃的格式、prompt 模板管理、模型路由根据请求类型选不同的模型或参数、结果后处理比如提取代码块、去掉多余解释、以及日志和指标采集。这一层是整个系统的“大脑”也是最需要根据自己业务定制的地方。推理层的选择就多了。如果你追求开箱即用Ollama 是最省事的路子它把模型下载、量化、服务化都封装好了一条命令就能起一个兼容 OpenAI 接口的服务。如果你要更细的控制比如自定义量化、batch 推理、多卡调度那就得上 vLLM 或者直接用手动加载的方式。我实测下来对于个人和小团队Ollama 的性价比最高启动快、显存占用可控、接口标准。三层之间的通信协议我统一用 HTTP JSON。接入层到编排层是内部函数调用同进程编排层到推理层是 HTTP 请求因为推理服务可能独立部署甚至独立机器。这样设计的好处是推理层可以随时换成远程服务编排层代码不用动。2.3 目录结构规划一个清晰的目录结构能省掉后面无数麻烦。我用的结构大概是这样codex-local/ ├── app/ │ ├── main.py # FastAPI 入口接入层 │ ├── api/ │ │ ├── routes.py # 路由定义 │ │ └── schemas.py # Pydantic 请求/响应模型 │ ├── orchestrator/ │ │ ├── engine.py # 编排核心逻辑 │ │ ├── prompts.py # prompt 模板 │ │ └── postprocess.py # 结果后处理 │ ├── inference/ │ │ ├── client.py # 推理服务客户端 │ │ └── config.py # 模型配置 │ └── core/ │ ├── config.py # 全局配置 │ └── logging.py # 日志配置 ├── tests/ ├── requirements.txt └── .env这个结构的关键点是api、orchestrator、inference三个目录对应三层职责边界清晰。core放跨层共用的配置和日志。新人接手时看目录就知道系统怎么组织的。注意不要为了“看起来专业”而过度拆分目录。我见过有人把每个函数拆成一个文件结果找代码比写代码还累。目录结构的唯一目的是让人快速定位不是炫技。3. 接入层FastAPI 服务的搭建与接口设计3.1 环境准备与依赖安装先把基础环境弄干净。我强烈建议用虚拟环境不要污染系统 Python。用 conda 或者 venv 都行我个人习惯 conda因为管理多版本 Python 方便。conda create -n codex-local python3.11 -y conda activate codex-localPython 版本选 3.11 是我实测下来兼容性最好的3.12 有些库还没跟上3.10 又偏旧。装依赖pip install fastapi uvicorn[standard] httpx pydantic pydantic-settings python-dotenv这里解释一下每个包的作用。fastapi是框架本体uvicorn是 ASGI 服务器带[standard]会装上 uvloop 和 httptools性能更好。httpx用来在编排层调用推理服务它支持异步比 requests 更适合。pydantic做数据校验pydantic-settings用来从环境变量读配置python-dotenv读.env文件。实操心得装依赖时如果遇到编译错误八成是缺少系统级的开发库。Ubuntu 上先apt install build-essential python3-devCentOS 上装gcc python3-devel。这个坑我踩过不止一次。3.2 请求与响应模型设计接入层的核心是定义清楚“请求长什么样、响应长什么样”。用 Pydantic 定义模型既能做校验又能自动生成文档。from pydantic import BaseModel, Field from typing import Optional, List class CodeGenRequest(BaseModel): prompt: str Field(..., description自然语言描述或代码上下文) language: Optional[str] Field(python, description目标语言) context: Optional[str] Field(None, description额外的代码上下文) max_tokens: Optional[int] Field(1024, ge64, le8192) temperature: Optional[float] Field(0.2, ge0.0, le2.0) stream: Optional[bool] Field(False) class CodeGenResponse(BaseModel): code: str language: str model: str tokens_used: int finish_reason: str几个设计细节值得说。temperature默认给 0.2因为代码生成场景需要确定性太高会胡编。max_tokens设了上下限防止有人传个 100 万把服务打挂。stream字段预留给流式输出编辑器场景下流式体验好很多。3.3 路由与流式输出实现路由部分保持简洁一个生成接口加一个健康检查就够了。from fastapi import APIRouter, HTTPException from fastapi.responses import StreamingResponse from .schemas import CodeGenRequest, CodeGenResponse from ..orchestrator.engine import OrchestratorEngine router APIRouter() engine OrchestratorEngine() router.post(/v1/codegen, response_modelCodeGenResponse) async def generate_code(req: CodeGenRequest): try: result await engine.process(req) return result except Exception as e: raise HTTPException(status_code500, detailstr(e)) router.post(/v1/codegen/stream) async def generate_code_stream(req: CodeGenRequest): async def event_generator(): async for chunk in engine.process_stream(req): yield fdata: {chunk}\n\n return StreamingResponse(event_generator(), media_typetext/event-stream) router.get(/health) async def health(): return {status: ok}流式输出用的是 SSEServer-Sent Events格式是data: xxx\n\n。这里有个容易踩的坑SSE 的每条消息必须以两个换行结尾少一个前端就收不到。我第一次写的时候只写了一个\n调试了半小时才发现。注意流式接口的异常处理要特别小心。如果生成过程中抛异常不能直接 raise因为响应头已经发出去了。正确做法是在生成器内部捕获异常yield 一个错误事件出去。3.4 接入层的配置管理配置统一走环境变量用pydantic-settings管理。from pydantic_settings import BaseSettings class Settings(BaseSettings): inference_base_url: str http://localhost:11434 inference_model: str deepseek-coder request_timeout: int 120 max_context_length: int 8192 log_level: str INFO class Config: env_file .env settings Settings()这样部署时只要改.env或者环境变量不用动代码。inference_base_url默认指向 Ollama 的默认端口 11434后面推理层会用到。4. 编排层请求处理与模型调度的核心逻辑4.1 编排层到底在编排什么很多人对编排层的理解停留在“转发请求”这是低估了它的价值。编排层真正要做的事情包括把用户输入的碎片化信息组装成模型能理解的完整 prompt、根据请求特征选择合适的模型和参数、处理多轮对话的上下文裁剪、对模型输出做结构化和清洗、以及记录整个链路的可观测数据。我举个具体例子。用户在编辑器里选中一段函数然后输入“帮我加个错误处理”。接入层收到的可能只有prompt帮我加个错误处理和context选中的代码。编排层要做的是识别出这是代码修改任务、把选中的代码和指令拼成一个清晰的 prompt、告诉模型输出格式要求、然后在结果里把代码块提取出来。这一整套逻辑就是编排层的价值。4.2 Prompt 模板的设计与版本管理Prompt 是编排层的核心资产。我建议把 prompt 模板单独放一个文件用常量或者模板引擎管理不要硬编码在逻辑里。CODE_GEN_TEMPLATE 你是一个专业的代码助手。请根据以下要求生成代码。 目标语言{language} 任务描述 {prompt} {context_section} 要求 1. 只输出代码不要输出解释性文字 2. 代码要符合该语言的主流规范 3. 如果需要导入库把导入语句放在最前面 4. 代码块用 包裹 代码 CONTEXT_SECTION 相关上下文{context}模板设计有几个原则。第一明确输出格式告诉模型只输出代码、用代码块包裹这样后处理时好提取。第二把可变部分和固定部分分开方便做 A/B 测试。第三留出版本号我习惯在模板常量名后面加版本比如CODE_GEN_TEMPLATE_V2改模板时新建而不是直接改方便回滚。实操心得prompt 调优是个体力活。我的做法是准备一组固定的测试用例比如 20 个典型的代码生成任务每次改 prompt 就跑一遍对比输出质量。凭感觉调 prompt 很容易越调越差。4.3 上下文管理与长度控制代码生成场景的上下文往往很长用户可能贴进来几百行代码。但模型的上下文窗口是有限的超了要么报错要么被截断。编排层必须做长度控制。我的策略是按优先级裁剪。优先级从高到低当前指令 用户显式选中的代码 光标附近的代码 文件其他部分 项目级上下文。裁剪时从低优先级开始丢保证高优先级内容完整。def build_context(req, max_tokens): sections [] if req.context: sections.append((selected, req.context)) # 按优先级组装超长时从尾部裁剪 total estimate_tokens(req.prompt) kept [] for name, content in sections: tokens estimate_tokens(content) if total tokens max_tokens: kept.append(content) total tokens else: # 部分保留 allowed max_tokens - total kept.append(truncate_to_tokens(content, allowed)) break return \n.join(kept)estimate_tokens是个粗略估算一般按 1 token 约等于 4 个英文字符或 1.5 个中文字符来算。精确计算要用对应模型的 tokenizer但估算够用了留点余量就行。4.4 模型路由与参数动态调整不同任务适合不同模型和参数。补全单行代码用小模型快生成整个模块用大模型质量好解释代码temperature 可以高一点生成测试用例要强调覆盖边界。def select_model_and_params(req): if req.max_tokens 128: return small-coder, {temperature: 0.1} if test in req.prompt.lower(): return large-coder, {temperature: 0.3, top_p: 0.95} return settings.inference_model, {temperature: req.temperature}这种路由逻辑一开始可以很简单随着使用慢慢加规则。关键是把决策逻辑集中在一处不要散落在各个地方。4.5 结果后处理与代码提取模型输出经常带一堆废话比如“好的这是你要的代码”然后才是代码块。后处理要把这些噪音去掉。import re def extract_code(text): # 优先提取 包裹的代码块 pattern r(?:\w)?\n(.*?) matches re.findall(pattern, text, re.DOTALL) if matches: return \n.join(matches).strip() # 没有代码块就返回原文 return text.strip()正则里的(?:\w)?用来匹配语言标识比如python。re.DOTALL让.能匹配换行。这个正则我调了好几版早期版本遇到嵌套代码块会出错后来改成非贪婪匹配才稳。注意后处理不要过度清洗。有些模型输出的注释是有价值的全删了反而不好。我的原则是只删明显的对话性文字代码和注释保留。5. 推理层本地模型服务的部署与对接5.1 推理层方案对比与选型推理层是整个系统的算力底座选型直接决定成本和体验。我把常见的几种方案列个表对比。方案部署难度显存占用接口兼容适合场景Ollama低中OpenAI 兼容个人、小团队快速起步vLLM中高OpenAI 兼容高并发、多卡llama.cpp中低自有CPU 推理、边缘设备手动 Transformers高高需自己封装研究、深度定制我推荐从 Ollama 起步。它的核心优势是把模型量化、下载、服务化全包了你不需要懂 GGUF 格式、不需要手动配显存一条ollama run就能跑起来。等业务量上来了再考虑迁移到 vLLM。5.2 Ollama 的安装与模型拉取Linux 上安装 Ollama 很简单curl -fsSL https://ollama.com/install.sh | sh装完确认服务在跑systemctl status ollama然后拉模型。代码生成场景我推荐 DeepSeek 系列的 coder 模型中文理解好、代码质量高。根据显存选参数量# 显存 8G 左右 ollama pull deepseek-coder:6.7b # 显存 16G 以上 ollama pull deepseek-coder:33b拉完之后测试一下ollama run deepseek-coder:6.7b 写一个 Python 快速排序能出结果就说明推理层通了。实操心得模型下载很吃磁盘和带宽6.7b 的量化版大概 4G33b 的要 20G 左右。建议提前确认磁盘空间我第一次没注意下到一半磁盘满了白等半天。5.3 推理服务的接口对接Ollama 默认在 11434 端口提供 HTTP 接口而且兼容 OpenAI 的/v1/chat/completions格式。编排层用 httpx 调用import httpx from ..core.config import settings class InferenceClient: def __init__(self): self.base_url settings.inference_base_url self.model settings.inference_model self.timeout settings.request_timeout async def generate(self, prompt: str, **params): payload { model: self.model, messages: [{role: user, content: prompt}], temperature: params.get(temperature, 0.2), max_tokens: params.get(max_tokens, 1024), stream: False, } async with httpx.AsyncClient(timeoutself.timeout) as client: resp await client.post( f{self.base_url}/v1/chat/completions, jsonpayload, ) resp.raise_for_status() data resp.json() return { text: data[choices][0][message][content], tokens: data.get(usage, {}).get(total_tokens, 0), finish_reason: data[choices][0].get(finish_reason, stop), }这里用messages格式而不是prompt格式因为 chat 格式对指令遵循更好。timeout设 120 秒因为大模型生成长代码可能很慢设太短会频繁超时。5.4 流式推理的实现流式输出对编辑器体验提升很大用户不用干等。Ollama 的流式接口返回的是 NDJSON每行一个 JSON需要逐行解析。async def generate_stream(self, prompt: str, **params): payload { model: self.model, messages: [{role: user, content: prompt}], stream: True, temperature: params.get(temperature, 0.2), } async with httpx.AsyncClient(timeoutself.timeout) as client: async with client.stream( POST, f{self.base_url}/v1/chat/completions, jsonpayload, ) as resp: async for line in resp.aiter_lines(): if not line.strip(): continue if line.startswith(data: ): line line[6:] if line [DONE]: break import json chunk json.loads(line) delta chunk[choices][0].get(delta, {}) if content in delta: yield delta[content]流式解析的坑在于不同服务的格式略有差异有的带data:前缀有的不带有的用[DONE]结束有的直接断流。写的时候要兼容这几种情况。5.5 显存与性能调优推理层的性能瓶颈几乎都在显存。几个关键参数num_ctx上下文窗口大小默认 2048代码场景建议调到 8192但会吃更多显存num_gpuGPU 层数显存不够时减少这个值部分层跑 CPUnum_threadCPU 线程数纯 CPU 推理时调优用在 Ollama 里可以通过 Modelfile 或者 API 参数设置。我的经验是先保证能跑再追求快。显存不够就降量化等级q4 换 q3或者换小模型不要硬撑。注意显存溢出不会优雅报错通常是进程直接被系统杀掉日志里只有一行 Killed。遇到这种情况先dmesg | tail看是不是 OOM再调参数。6. 三层联调与端到端验证6.1 启动顺序与依赖关系三层有依赖关系启动顺序不能乱。正确顺序是先起推理层Ollama再起接入层FastAPI因为接入层启动时会初始化编排层编排层会去连推理层。# 1. 确认 Ollama 在跑 systemctl start ollama curl http://localhost:11434/api/tags # 2. 启动 FastAPI uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload--reload只在开发时用生产环境去掉否则文件变动会重启服务。6.2 端到端测试用例服务起来后用 curl 测一遍完整链路curl -X POST http://localhost:8000/v1/codegen \ -H Content-Type: application/json \ -d { prompt: 写一个函数判断字符串是否是回文, language: python, max_tokens: 256 }预期返回一个包含代码的 JSON。如果返回 500先看 FastAPI 日志再看 Ollama 日志逐层排查。流式接口测试curl -N -X POST http://localhost:8000/v1/codegen/stream \ -H Content-Type: application/json \ -d {prompt: 写一个冒泡排序, stream: true}-N参数关闭 curl 的缓冲能实时看到输出。6.3 性能基准测试搭好之后要有个基准知道系统什么水平。我一般测三个指标首 token 延迟、生成速度tokens/秒、端到端延迟。import time import httpx def benchmark(prompt, n5): times [] for _ in range(n): start time.time() resp httpx.post( http://localhost:8000/v1/codegen, json{prompt: prompt, max_tokens: 256}, timeout120, ) times.append(time.time() - start) print(f平均延迟: {sum(times)/len(times):.2f}s) print(f最快: {min(times):.2f}s, 最慢: {max(times):.2f}s)我实测下来6.7b 量化模型在消费级显卡上256 token 的生成大概 3-8 秒首 token 延迟 1-2 秒。这个水平做编辑器辅助够用了。7. 常见问题与排查技巧实录7.1 连接类问题速查现象可能原因排查方法接入层启动报连接拒绝推理层没起curl推理层端口请求超时模型太大或显存不足看推理层日志降模型流式输出卡住SSE 格式错误检查换行符和前缀端口被占用重复启动lsof -i:8000查进程7.2 生成质量问题模型输出质量差先别急着换模型按这个顺序排查prompt 是否清晰、上下文是否超长被截断、temperature 是否过高、模型是否适合该语言。我遇到过生成 Java 代码质量差换成专门的 Java 微调模型就好了不是 prompt 的问题。7.3 显存与性能问题显存不足的表现是进程被杀或者推理极慢。解决路径降量化等级、减num_ctx、换小模型、加显卡。我个人的经验是宁可跑小模型跑得顺不要跑大模型跑不动体验差距很大。7.4 我踩过的几个典型坑第一个坑是中文编码问题。早期没在响应头里指定charsetutf-8中文注释返回给前端变成乱码。FastAPI 默认是 utf-8但 SSE 流式响应要手动确认。第二个坑是并发下的显存竞争。多个请求同时进来Ollama 会排队但如果并发太高显存会爆。解决办法是在编排层加信号量限流import asyncio semaphore asyncio.Semaphore(2) # 最多同时 2 个推理请求 async def process(self, req): async with semaphore: return await self._do_process(req)第三个坑是模型加载慢。Ollama 默认模型闲置一段时间会卸载下次请求要重新加载首 token 延迟飙升。可以在配置里设置keep_alive参数保持模型常驻。实操心得排查问题时日志要打全。我在编排层每个关键节点都加了日志记录请求 ID、耗时、模型名、token 数。出问题时顺着请求 ID 一路查下去比瞎猜快得多。8. 后续可扩展的方向这套三层架构搭好之后扩展空间很大。接入层可以加鉴权、加限流、加多租户编排层可以加缓存相同 prompt 直接返回、加 RAG检索项目代码作为上下文、加多模型投票推理层可以加模型热切换、加 batch 推理提升吞吐。我自己下一步打算做的是项目级上下文注入。现在的上下文是用户手动贴的如果能自动索引整个项目的代码生成时自动检索相关文件作为上下文代码质量和一致性会好很多。这个用向量数据库加检索就能实现编排层加一个检索模块即可三层架构的好处在这里体现得很明显——加功能不用动其他层。另外一个小技巧分享给做编辑器的朋友流式输出时前端可以按 token 增量渲染但代码高亮要等完整代码块出来再做否则高亮会闪烁。我试过几种方案最后是攒够一个完整代码块再触发高亮体验最稳。