做代码评审这件事很多团队都有一肚子话想说。评审本意是提前拦截问题、传递代码上下文可实际执行起来要么变成“LGTMLooks Good To Me”式的形式主义要么变成耗费大量时间的逐行辩论。我一直在想能不能让本地 AI 先把第一遍粗筛干掉把人从重复劳动里解放出来只去处理那些真正需要人类判断的问题。带着这个想法我折腾了一套叫 open-code-review 的本地代码评审系统搭完之后最大的感受是它不见得能替代人但确实能把评审的起点抬高一大截。这篇文章就把这套系统的设计思路、选型过程、落地细节和踩过的坑完整记录下来。1. 项目概述1.1 项目要解决的核心问题open-code-review 是一套面向本地 AI 的代码评审系统目标很直接在你提交代码之后、合入之前让跑在本地的大模型先对 diff 做一次自动评审输出可能存在的 bug、安全隐患、风格问题、可维护性隐患再交给人类开发者确认。它不追求替代 Code Review而是把“机器能做的粗筛”和“人该做的判断”分开解决三个常见痛点。第一评审节奏容易被琐碎问题拖慢。很多团队不是不想认真评审而是 PRPull Request一多评审者实在看不过来最后只能抓大放小小问题混进主干慢慢变成技术债。第二本地代码仓库和 CI持续集成环境往往有数据隔离要求代码不能随便传到外部 API这就需要一个完全跑在本地的评审方案。第三现在的大模型编码能力已经相当可观但对“某个具体仓库的代码风格、边界条件、历史约定”并不了解直接丢一个完整文件给它它给出来的建议通常很泛缺乏针对性。open-code-review 的定位就是补齐这最后一公里它围绕 git diff 生成评审上下文把变更点、关联文件、仓库约定一起喂给本地模型让模型输出的意见能直接落在一个可执行、可讨论的层面上。1.2 这套系统适合谁用如果你正在维护一个中等规模的代码仓库团队人不多评审人手紧张或者你有强离线要求、代码不能出内网那 open-code-review 这种思路会很合适。它同样适合个人开发者自己写 side project 没人帮着看代码让本地模型跑一遍很多低级错误一眼就能暴露出来。我自己的主力机器是一张 24GB 显存的显卡跑 7B 到 14B 参数的量化模型都很从容。如果显存低于 8GB也不是不能玩但需要选更小的模型比如 3B 到 4B 参数档位并且要把代码分块控制得更小。文章后面会专门讲参数调整和模型选型。2. 整体设计与工作流程2.1 一个最小可用的评审闭环在设计 open-code-review 之前我先把“本地 AI 评审代码”这件事拆成了几个不可跳过的环节获取变更内容、构造评审上下文、调用模型生成意见、汇总输出结果。逐个拆开之后你会发现大部分功能其实不复杂真正的难点在“怎么让模型看到它该看的东西”。先说获取变更内容。最通用的方式是读 git diff因为 diff 本身就浓缩了这个 PR 做了什么。但光有 diff 不够模型经常需要知道修改发生在哪个函数里、这个函数的完整实现长什么样、同文件里有没有类似的既有写法。所以 open-code-review 的做法是解析 diff 中每个变更文件提取变更行所在的函数或类范围再连同相关代码片段一起构造输入。再说评审上下文。我给模型设计的输入结构大体是这样的先给系统指令说明这是一个严格的代码评审任务要求模型按严重程度输出问题接着给仓库约定比如缩进风格、命名规则、禁用的语法然后给这一次的变更内容按文件分块最后给出输出格式模板。整个过程不是把整个仓库灌给模型而是精准抽取“与变更相关的最小集合”。最后是输出。模型输出我要求用结构化的文本格式每条问题带文件路径、行号、问题级别、原因说明和修改建议。这样后续无论是接到终端展示还是转成评论发布到 GitLab/GitHub都有明确的解析目标。2.2 为什么选本地模型而不是云端 API这可能是很多人第一时间会问的问题现在各家云端模型代码能力都这么强为什么不直接调 API我当时的考虑有三个。第一是隐私和合规。企业内部代码往往有严格的保密要求尤其是还没公开的业务逻辑、密钥相关代码往外发一次就多一分风险。本地推理把这些数据全部留在自己的机器上心理负担和合规压力都小很多。第二是成本。代码评审是高频动作每个 commit 都可能触发一次如果每次都按 token 计费长期下来是一笔不小的支出本地推理只有电费和硬件折旧跑得再多也不心疼。第三是定制空间。本地模型你可以随意调 prompt、调整采样参数、甚至微调不用受外部 API 的约束。当然本地方案也有明显的短板对硬件有要求模型能力上限通常低于云端顶尖模型推理速度也慢一些。但对我来说这些短板在接受范围内而且随着开源模型迭代差距正在快速缩小。如果你跑的是最新一代的开源代码模型在绝大多数常规代码评审场景下它的输出质量已经够用了。2.3 工作流设计什么时候触发、什么时候等人工open-code-review 的默认工作流不是“全自动合入”而是“机器先审人工复核”。我通常把它接在 git 的 pre-push hook 或者 CI 的第一个阶段。代码推到远端之前先跑一遍本地评审发现高危问题就直接在终端标红开发者本地改完再推。如果推到远端CI 里也可以再跑一遍把评审意见以评论形式关联到 MR/PR 上。这里有个设计取舍到底是把评审结果当“门禁”强制拦截还是当“建议”仅作参考我的建议是默认不要做强门禁。因为本地模型一定会产生误报把误报变成硬性拦截反而会消耗团队信任。更好的做法是让结果直观、可追溯但由人来决定是否处理。只有当模型在某几类规则上表现足够稳定之后再考虑为那几类问题单独设置检查门槛。3. 技术选型与核心模块3.1 模型选择到底该用哪个开源模型本地代码评审对模型的要求和普通聊天不太一样。它需要模型有较强的代码理解能力、指令遵循能力还要尽量低的幻觉率。我实际对比过几类模型简单说下适用场景。如果你显存在 8GB 到 16GB 之间可以优先考虑 Qwen2.5-Coder-7B-Instruct 或者 DeepSeek-Coder-6.7B-Instruct 的量化版本。这两个模型对中英文指令的理解都不错代码能力在 7B 档位里属于第一梯队跑起来速度也快。我自己最开始就是用 Qwen2.5-Coder-7B 做的验证效果已经比预想好很多。如果显存在 24GB 左右可以上 Qwen2.5-Coder-14B 或者 CodeLlama-34B 的更大量化档。14B 的模型在复杂逻辑判断上明显比 7B 更稳尤其是在分析空指针、并发问题、资源泄漏这类需要多步推理的场景。再往上走的话比如 32B 甚至 70B 的模型推理速度会明显下降除非你有充裕的时间和算力否则对日常评审来说有点奢侈。我在选型时看两个硬性指标一是 HumanEval 之类的代码生成分数虽然不能完全代表评审能力但能反映基础代码理解水平二是上下文长度。评审任务往往需要塞入多段代码上下文太短的话很容易截断关键信息。现在很多新模型的上下文做到了 32K 甚至 128K但实际使用时会发现上下文越长推理越慢所以不是越长越好够用就行。3.2 推理引擎用 llama.cpp 还是 Ollama本地推理这块我先后用过 llama.cpp 和 Ollama最后长期留的是 Ollama但底层思路两者相通。llama.cpp 胜在灵活、资源占用低你可以精确控制量化方式和 GPU 层数适合喜欢折腾的人。Ollama 胜在开箱即用一条命令就能把模型跑起来而且它对模型文件的管理、API 的暴露都做得比较规范适合我这种更关注上层业务的人。实际落地时我建议通过 Ollama 的 HTTP API 来对接而不是直接走命令行交互。原因是评审流程需要程序化地发送 prompt 并解析流式响应命令行交互不利于自动化。Ollama 默认监听 11434 端口用 Python 的 requests 或者 OpenAI SDK 兼容接口就能轻松对接省去很多中间层的开发。如果你的机器上已经装了 Docker也可以用 Ollama 的容器镜像跑这样环境隔离更干净升级也方便。我个人没用容器方案因为本地模型文件比较大直接装原生程序更省心。3.3 上下文构造怎么把代码喂给模型才能让它“看得懂”这部分是整个系统里最影响效果的地方。直接丢一行 git diff 给模型它很难判断这行改动是不是真的有问题因为它不知道这个函数原本的意图、不知道周围变量的类型、也不知道可能被哪些地方调用。所以 open-code-review 做了一个“上下文增强”模块。第一步解析 git diff拿到修改文件的列表和每个文件的 hunk。第二步定位每个 hunk 中变更行所在的函数或方法用简单的语法解析或者正则匹配提取这个函数在最新版本里的完整代码。第三步把原始 diff、完整函数代码、相关文件列表、仓库约定一起按固定格式拼接。第四步如果整体内容超过模型上下文限制就按文件拆成多个子任务而不是暴力截断。这四步听着简单但每一步都有细节。比如定位函数时Python 可以按缩进判断Go 可以按大括号匹配JavaScript 则要小心箭头函数和对象方法的写法。为了省事我第一版只支持 Python 和 JavaScript后面才慢慢扩展。每一类语言加进来的时候都要专门准备一批测试用例确保函数边界抓得准。3.4 Prompt 设计评审意见怎么才能不“泛泛而谈”我见过很多人用 AI 做评审得到的意见永远都是“建议增加空行”“注意命名规范”这种正确但没用的废话。问题往往出在 prompt 上模型确实知道代码有问题但你给它的任务描述太空泛它只能按最安全的套路输出。我给 open-code-review 设计的系统提示词包含几个固定部分。第一角色定位“你是资深代码评审专家擅长发现逻辑缺陷、边界条件、安全问题与可维护性隐患。”第二任务边界“只针对本次变更不要评价未修改的既有代码。”第三输出要求“每条意见必须包含文件路径、行号、严重程度高危/中危/低危/建议、问题描述、修改建议。”第四回答约束“如果变更没有问题请明确回答无需改动不要编造问题。”其中“不要评价未修改的既有代码”和“无需改动时明确回答”这两条非常关键。没有这两条模型很容易把仓库里原有的问题都翻出来让输出变成一堆噪音也容易为了“显得有用”强行报几条意见误报率居高不下。加进去之后整个输出质量肉眼可见地提升。4. 从零到一搭建 open-code-review 的实操过程4.1 环境准备与依赖安装我这套环境的基准配置是Ubuntu 22.04CPU 是 8 核内存 32GB显卡 RTX 3090 24GB。如果你用的是 Windows建议优先考虑 WSL2因为在原生 Windows 上跑 llama.cpp 或者 Ollama 虽然也能跑但 GPU 加速配置更麻烦遇到问题社区资料也没那么多。第一步安装 Ollamacurl -fsSL https://ollama.com/install.sh | sh安装完后先拉取模型ollama pull qwen2.5-coder:14b如果你显存小于 16GB可以换成ollama pull qwen2.5-coder:7b拉取模型的同时我把 open-code-review 的代码从仓库克隆下来创建 Python 虚拟环境git clone https://github.com/yourname/open-code-review.git cd open-code-review python3 -m venv venv source venv/bin/activate pip install -r requirements.txt依赖项不多核心就是 requests、gitpython、pyyaml。这里要提醒一句gitpython 不是必须的如果你不想引入额外依赖直接用 subprocess 调用 git 命令也可以。但 gitpython 在处理 diff 的时候更方便尤其是按文件、按 hunk 解析时能省不少代码。4.2 配置文件让系统认识你的仓库open-code-review 的配置我放在一个 YAML 文件里结构大致如下model: qwen2.5-coder:14b base_url: http://localhost:11434 temperature: 0.2 max_tokens: 2048 repo: path: /path/to/your/project language: python convention: | - 使用 4 空格缩进 - 函数命名使用 snake_case - 禁止使用全局可变状态 rules: enabled: - logic - security - performance - style这里的 temperature 我固定在 0.2。评审任务不是创作任务需要的是稳定输出和低随机性温度调太高会让模型反复横跳同一段代码跑两次意见不一样没法看。max_tokens 设 2048 一般够用如果仓库里一次变更特别大输出可能会被截断可以适当往上调。仓库约定这项看似简单实际上对输出质量影响很大。模型不知道你们团队约定什么命名风格、什么场景禁止做什么你把约定写清楚它就能在评审时主动比对。我就见过一个团队把“禁止在 try 块里写空 except”写进约定之后模型对这种问题的检出率立刻提高。4.3 写一个最小工作流脚本核心逻辑我封装到了一个 Python 脚本里。整体流程可以概括为三步取 diff构造 prompt解析模型输出。先看获取 diff 的部分import subprocess def get_diff(repo_path, commit_rangeHEAD~1..HEAD): result subprocess.run( [git, -C, repo_path, diff, --unified20, commit_range], capture_outputTrue, textTrue, encodingutf-8, ) return result.stdout--unified20这个参数容易被忽略但它很重要。默认 diff 上下文只有 3 行模型很难看清被修改代码的完整逻辑放大到 20 行模型能更好地理解变更所在的函数上下文。当然代价是输入变长、推理变慢具体数值你可以自己权衡。然后是构造 prompt。我会先读配置里的仓库约定再拼接 diff 内容最后在末尾加上输出格式要求def build_prompt(diff_text, convention): prompt f 你是一名资深代码评审专家。请针对以下代码变更进行评审。 仓库约定 {convention} 变更内容{diff_text}要求 1. 只针对变更部分给出意见不要评价未修改代码。 2. 按以下格式输出每条意见单独一行 [级别] 文件路径:行号 问题描述 | 修改建议 级别取值高危/中危/低危/建议 3. 如果变更没有明显问题只输出无需改动 return prompt最后调用 Ollama 的接口import requests def review_diff(prompt, model, base_url, temperature0.2): response requests.post( f{base_url}/api/generate, json{ model: model, prompt: prompt, stream: False, temperature: temperature, }, timeout300, ) return response.json()[response]这里我使用了 requests 库实际生产环境下建议用 OpenAI SDK 的兼容接口因为 Ollama 从某个版本开始已经支持 OpenAI 格式了接口更标准化后续换其他推理引擎也方便。4.4 跑通第一个评审案例我在一个测试仓库里故意制造了几类问题一个未判空的可能空引用、一个重复计算导致的小性能浪费、一个命名不规范的临时变量。然后运行脚本看模型能不能识别出来。第一次跑的时候输出确实有些惊喜。模型不仅找出了空引用还给出了复现路径虽然没有精确到行号但已经能定位到具体函数。同时它也输出了好几条“建议增加注释”这类低价值意见误报率仍然存在。我没有急着调模型而是先调 prompt在要求里加了一句“只有影响代码正确性、安全性或可维护性的问题才需要输出风格类问题仅在明显违反仓库约定时输出”。这一改低价值意见立刻少了很多。这里想强调一个经验不要一上来就怪模型“笨”很多时候是输入和指令不够清晰。先把 prompt 里的约束写明白再考虑换更大的模型这是成本最低的优化路径。5. 实际使用效果与参数调优5.1 用三个指标衡量评审效果在调参之前得先定义什么叫“效果好”。我给自己定了三个指标查全率、查准率、单次评审耗时。查全率指的是“模型找出的真实问题数 / 真实问题总数”这个指标关心的是漏报。查准率指的是“模型找出的问题中真实问题占比”这个指标关心的是误报。评审任务里两个指标都重要但实际使用时容易顾此失彼你为了降低漏报让模型更激进地报问题误报率马上上来你为了减少误报让模型更保守漏报又明显增加。这个平衡点没有标准答案取决于你团队的容忍度。我的设置是中危以上的误报可以接受部分存在但高危误报不能太多因为开发者会逐条看报得太离谱容易失去信任。耗时这个指标容易被忽略但体验影响很大。如果一次评审要等十分钟开发者大概率就不会在本地跑了只有 CI 里强制跑才行。我一般把单次评审控制在 30 秒到 2 分钟以内超过这个范围的变更就分块处理。5.2 温度与上下文窗口temperature 是影响随机性的关键参数。我实际测试过 0.2、0.5、0.8 三档0.8 时模型会写一些花哨的解释但推理结论不稳定同一段代码跑两次可能给出完全不同的意见0.5 仍然有波动0.2 基本稳定偶尔会有微小措辞差异但结论一致。所以最终固定在 0.2。如果你用 low temperature 时发现模型总是给出“安全但无用”的回复可以考虑微调到 0.3 到 0.4但别超过 0.5。上下文窗口不是调越大越好。模型支持 32K 上下文但实际塞太多内容进去注意力会被稀释模型可能忽略真正关键的问题。我一般把单次评审的输入控制在 6K 到 8K token 以内。如果一次变更包含十几个文件我会先按文件分组成多个子任务每个子任务独立评审最后合并结果。这样虽然总的耗时变长了但每个子任务的质量有保障。5.3 一次真实 Pull Request 的评审记录我拿一个真实的 Python Web 项目 PR 做过测试。这个 PR 改动了一个订单查询接口涉及 3 个文件一个新增的查询函数、一个修改的数据库访问层、一个修改的路由注册。模型输出的意见里比较有价值的有三条一是指出新增查询函数里缺少对输入参数空字符串的校验可能导致后续数据库查询条件失效二是指出数据库访问层新增的排序逻辑没有加索引提示数据量大时会有性能问题三是路由注册里异常处理只捕获了通用 Exception建议细分异常。这三条虽然称不上“惊艳”但都指向了真实存在的问题而且基本符合评审者会提出的方向。作为第一遍粗筛这个质量已经能帮助评审者把注意力集中到更核心的业务逻辑上。当然它也漏掉了一个问题并发场景下订单状态的原子更新没有考虑这个需要模型理解更复杂的业务约束确实超出了它当前能力。所以结论很明确它能做助理别让它当终审。6. 常见问题与排查技巧6.1 模型输出不稳定怎么办症状相同代码、相同 prompt跑两次意见完全不同。原因通常是 temperature 太高或者 prompt 里的约束不够强。先检查 temperature评审任务应当尽量低建议 0.2 以下。如果温度正常再检查 prompt 开头是不是给了足够清晰的角色和任务边界。还有一种情况是量化模型本身的不确定性低比特量化会让输出稍微波动可以换更高比特的量化文件或者更稳定的模型。另一种“不稳定”不是随机性问题而是输出格式不统一。模型有时候不按你要求的格式输出直接生成一段对话式意见。解决办法是在 prompt 里给出一个输出示例再做一层轻量的后处理解析。解析失败的时候我宁愿丢弃这条输出也不要把它原样贴给开发者。6.2 推理速度慢、内存不足如果你跑 14B 模型时出现内存不足或生成速度很慢第一件事是确认显存是否足够。Ollama 默认会优先加载到 GPU 上但显存不够时会把部分层放到 CPU速度断崖式下降。查看是否 GPU 加载的命令ollama ps看输出里 GPU 和 CPU 的列如果很多层都在 CPU 上说明显存不够考虑换小模型或者加量化。另外可以限制进程使用的 CPU 线程数避免推理时整机卡死。还有一个小技巧把并发请求数限制为 1避免多个评审任务同时挤占资源。6.3 误报太多开发者开始不信任结果这是团队落地时最容易出的问题。我的经验是分两步走先从 prompt 端压制误报例如明确说“只有影响正确性、安全性的问题才报告高危”再做规则白名单把模型容易误报的场景写到仓库约定里。比如我们约定“所有临时调试打印必须移除”模型就会更认真地查这个点而不是漫无目的地挑刺。如果仍然误报太多可以给输出加一个置信度字段让模型自己对每条意见标记“确认/需要人工确认”。虽然这个置信度不完全可靠但能给开发者一个优先级参考减少“逐条判断是否值得看”的负担。6.4 换了新语言后效果下降模型训练语料对热门语言覆盖更好冷门语言自然效果差一些。遇到这种情况我会先调整 prompt 中仓库约定部分把语言的常见陷阱写进去。比如 C 里我会强调注意指针所有权和异常安全Rust 里强调生命周期和所有权约束。这一招能让模型更聚焦在语言特有的风险上效果比换更大的模型更明显。如果你的仓库里同时存在多种语言建议按语言拆成不同的评审配置为不同语言设定不同的约定文本。不要试图用一个通用 prompt 覆盖所有语言那只会让模型每样都懂一点每样都不够精准。7. 后续扩展方向和我的个人体会open-code-review 目前对我来说已经是一个稳定可用的工具了。平时开发时我先跑一遍本地评审再自己过一遍提交质量明显比裸写好很多。让我比较意外的是它不光帮我发现了 bug还会逼着我把“为什么这么写”想得更清楚当模型对一个改动提出质疑时我需要能解释清楚为什么它是合理的这个解释过程本身就是一种提升。后续我打算做两个扩展。第一是支持把评审结果直接发布到 GitLab/GitHub 的 MR/PR 评论上而不是只输出在终端里。这个在技术上不复杂主要是要处理评论文本过长和重复评论的去重问题。第二是想做一个“误报反馈”机制如果开发者标记某条意见是误报可以记录下来后续通过微调或者参考示例的方式改进模型表现。这等于把团队评审沉淀成模型经验价值会越来越大。还有一个扩展方向是接入更细粒度的静态分析结果。大模型和传统静态分析工具各有侧重静态分析在数据流、控制流分析上很精准但规则有限大模型灵活但有时会漏。把两者结合让模型基于静态分析告警做深入判断误报和漏报都能再压一压。如果你也想在本地搭一套我的建议是从最小闭环开始先跑通单次提交的评审别急着做 CI 集成和评论回写。等 prompt 和模型选型都稳定了再把自动化一步步加上。毕竟工具再强大最终还是要让开发者用起来觉得省事、可信。机器先把粗活干了人就能把注意力留给真正有价值的讨论这可能才是代码评审这个环节最该有的走向。