代码审不完是每个技术团队都要面对的账单。提交一多评审人员既要看业务逻辑又要盯边界条件还要防低级错误最后的响质量往往靠“运气”而纯商业审查工具虽然开箱即用但计费方式按代码量、按调用次数累积长期跑下来开销不明朗更难受的是公司代码片段要出网在强调数据主权和合规的环境里这本身就是一道门槛。我们今天要聊的 open-code-review不是某个官方产品的名字而是一套我们内部打磨过、完全自托管、以开源大模型为核心的代码审查方案。它把“代码走查”这件事拆成了静态规则过滤、大模型语义分析、结果回投 PR 三个环节全部跑在内网 CI 里既不碰外部 API也不让敏感 diff 离开自己的机器。无论是 5 人小团队还是几十个仓库的中型项目都可以用很低的成本搭出一套可解释、可审计、可复用的自动代码审查能力。1. 为什么非要自建审查管线需求分析与方案选型1.1 传统审查的两大边界人力成本与上下文盲区代码评审不是一个纯粹的“看代码”过程。最有效的评审需要理解这次改动在完整功能中的位置、调用链上下游会受什么影响、是否踩到了团队规约里的隐性红线。人脑处理这些信息的带宽很低一次高质量的评审通常要 20~40 分钟经验只要稍有分散就会漏掉经典的“少了一个判空”“并发锁放错了位置”这类只有局部上下文才能发现的问题。很多团队为了效率把评审降级成让 CI 跑一遍测试、再扫一遍 lint但这只能拦住“格式不对”和“用例失败”根本挡不住“逻辑语义与业务预期不符”这类问题。自动化的难点也在这静态分析工具比如 SonarQube、ESLint规则刚性太强认知层面几乎没有如果直接引入商业 AI 审查产品则面临两个现实担忧。一是成本模型通常按 token 和活跃用户收费日活一高账单增速会很可观二是代码是公司的核心资产外发到第三方平台对很多内部项目是无法接受的。基于这两点我们把视线转向了开源可私有化部署的 LLM打算自己承担“提词、上下文组装、结果过滤”这三个关键步骤的控制权。1.2 open-code-review 的四个设计目标省钱、可控、可解释、可定制在项目启动时我给这套系统定了几条硬约束后续所有架构决策都围绕它们展开零外网依赖评审过程必须能完全发生在内网模型推理走本地 GPU 或 CPU。即使没有外网也要能正常完成一个 PR 的评审。结果可追溯每条评论都要能追溯到模型输出和触发规则。不能只丢一句话“这里可能有 bug”我需要知道它是来自规则引擎的“正则匹配”还是来自 LLM 的“语义推断”。低成本复杂化代码提交量有波峰波谷不可能为“偶尔的大 PR”配置一台 8 卡 A100。方案的算力弹性要能平缓适配日常规模必要时允许低优先级任务排队。插件式规则合并团队里已有的 eslint、golangci-lint 结果不应该被抛弃而是作为“规则层”输入继续参与审查让 LLM 的注意力集中在更高级的语义问题上。1.3 整体管线设计一周内跑通的核心链路整个 open-code-review 没有采用复杂的微服务架构而是最朴素的流水线设计。仓库触发事件进入 GitHub Actions 后先用 Git 命令提取 PR 对应的 diff 数据接着一个轻量规则引擎先去处理这个 diff识别敏感的密钥、调试代码和明显的反模式这部分不消耗任何模型调用然后把 diff 和关联的文件片段交给 LLM模型输出后还有一个后置过滤器负责清洗格式、去重、剔除与 diff 无关的幻觉内容最后通过 GitHub API 把评论写到 PR 中对应的代码行上。这条通路的好处是每个环节都可以独立做单元测试。比如规则引擎可以直接喂一个恶意 diff 测试它是否能及时阻断后置过滤器可以单独跑在模型输出上确保不会把乱码贴到 PR 里。从代码仓库到产出第一条线上评论差不多一个工作日就能看到雏形剩下的时间都花在调“模型输出质量”和“减少误报率”上。2. 模型选型细节与提示词工程决定审查效果的上限2.1 开源模型怎么选不只看出名更要看部署约束如果你已经决定用 Ollama 这类工具跑本地模型第一件事就是打消“大模型参数越多越强”的念头。在自托管代码审查场景中模型需要做到的是在 16GB 内存的机器上也能快速推理同时输出足够稳定。我们在实测阶段对比过几款常用模型模型参数量量化后体积审查效果部署备注CodeLlama 13B13B约 7.5GB中规中矩注释风格保守对复杂逻辑敏感度偏低对内存压力大Qwen2.5-Coder 7B7B约 4.7GB代码理解能力强能发现隐藏的边界问题性价比首选单卡即可DeepSeek-Coder 6.7B6.7B约 3.8GB响应快但多选题式思考会消耗 token提示词需要更严格约束GLM-4-9B9B约 5.5GBfp16中文注释理解好对英文代码命名风格适应稍弱我们最终把 Qwen2.5-Coder 7B 作为默认后端原因非常实际它量化后体积可以在普通开发机上运行即使模型推理性能和 70B 差距明显但在代码评审场景里我们并不需要它写出“长篇论文式评论”只需要它针对 diff 中的两个具体代码块给出“是否有风险、风险位置、修复建议”这样的结构化判断。7B 模型只要提示词设计得当在边界条件检测上已经能覆盖大部分常规遗漏。注意不要为了追求“大模型”盲目选择 70B。代码审查对延迟很敏感PR 一多如果模型推理太慢CI 排队时间就会超过开发者的耐心极限再准的审查结论也没用。2.2 提示词设计的三个坑空泛指令、非结构化输出、缺少上下文大模型做代码审查最怕两件事一是回答得太空泛比如“这里逻辑需要优化”“建议增加判空”说了一堆等于没说二是产生幻觉比如指出一个根本不存在的变量名或函数。我们的经验是提示词里一定要包含 ROLE、TASK、CONTEXT、FORMAT 四个模块。以 open-code-review 实际使用的 prompt 模板为例它的核心结构是这样的你是一名资深代码评审工程师。下面给出一段 git diff请基于改动内容进行分析。 分析时请注意 - 只评审实际出现的变更行不要评审未修改的代码。 - 重点关注边界条件、并发安全、资源泄漏、逻辑矛盾。 - 如果发现问题请严格按照以下JSON格式返回 {issues: [{severity: error/warning/info, line: 12, message: 问题描述, suggestion: 修复建议}]} - 如果没有问题只返回 {issues: []}注意这里的几个细节第一“只评审实际出现的变更行”是抑制幻觉的有效手段第二指定 JSON 输出格式让后续后置过滤器可以直接做 JSON 解析而不用依赖模型对自然语言的自由发挥第三字段里带有 severity 分级这样我们可以对 error 级评论进行强提醒对 info 级评论进行汇总。2.3 上下文窗口的组装不是把整个文件塞进去很多人在第一步就踩了坑把单次变更涉及的整个源文件直接拼进 prompt。这有两个问题一是 token 消耗急剧增加7B 模型在小上下文效果才最好二是模型会因为看到了太多“无关代码”而分心反而给已有代码提意见。我们的做法是自动提取“变更函数的完整函数体调用方签名”把它们作为上下文。比如这次改动修改了checkout函数中的一个 return 逻辑那我们就用 grep 提取checkout的完整函数再提取相邻调用它的pay()函数签名形成如下拼接段### modified function: def checkout(user_id, order_id, coupon_code): # 原有逻辑... if coupon_code and not validate_coupon(coupon_code): return {code: 400, msg: coupon invalid} # ... ### caller signature: def pay(user_id, session): result checkout(user_id, session.order_id, session.coupon_code)这样模型看到的是“这个改动在什么上下文里被调用”理解成本大幅降低。再配合一个diff_limit参数控制单次 prompt 不超过 3000 token剩下的交给多个批处理任务而不是一次性让模型分析 5000 行代码。3. 完整实操从环境配置到 CI 机器人上线3.1 本地模型部署五条命令起一个推理服务open-code-review 的模型服务采用了 Ollama 作为运行时它可以自动完成模型下载、量化切分、API 暴露等工作。部署过程不用碰 Python 环境和 CUDA 编译作为内网工具非常合适。安装方式如下# 安装 OllamaLinux / macOS 均可 curl -fsSL https://ollama.com/install.sh | sh # 拉取 Qwen2.5-Coder 7B 模型的量化版本 ollama pull qwen2.5-coder:7b # 启动 Ollama 服务监听在 11434 端口 ollama serve如果 CI 机器和模型服务不在同一台机器需要在启动时暴露接口# 允许局域网访问请确认内网防火墙策略 OLLAMA_HOST0.0.0.0 ollama serve需要说明的是Ollama 默认监听的是 127.0.0.1如果 CI 节点要远程调用必须设置OLLAMA_HOST。此时建议在 CI 节点和模型节点之间做好网络层白名单不要在公网裸奔。如果团队已经在用 Kubernetes也可以把 Ollama 容器化成 deployment并挂载 PVC 缓存模型文件这样可以避免每次重启重新下载模型。3.2 获取 diff 数据Git 命令的正确姿势在实际 CI 场景中获取 diff 不是简简单单一个git diff就能搞定的。我们基于 GitHub Actions 时通常是 checkout 之后拿到 PR 合并目标分支和当前分支的差异git fetch --unshallow origin main git diff origin/main...HEAD -- *.py *.js *.go *.java *.ts *.tsx这里有几个细节经验可以分享origin/main...HEAD的三点语法表示“取 main 分支的最新公共祖先到 HEAD 之间的差异”这样可以避免把 main 分支上别人新提交的内容算进当前 PR 的改动防止模型误评“他人代码”。另外--后面的指定扩展名清单可以过滤掉 lock 文件、编译产物和自动生成文件不仅减少 token 消耗也避免模型对锁文件变化大惊小怪。3.3 核心评审脚本示例基于 Ollama API 的最小实现我们脚本的核心逻辑分五步读取 diff → 规则引擎预检 → 组装上下文 → 调用 Ollama → 解析输出。这里给出一个可以直接跑通的精简版本为了突出关键点做了部分简化import json import subprocess import requests OLLAMA_URL http://model-server:11434/api/chat MODEL_NAME qwen2.5-coder:7b def get_diff(): result subprocess.run( [git, diff, origin/main...HEAD, --, *.py, *.js, *.go], capture_outputTrue, textTrue, checkTrue, ) return result.stdout[:20000] # 防止 diff 过大 def rule_precheck(diff): 静态检查跳过明显的噪音把疑似密钥行直接拦截. blocked [] for line in diff.splitlines(): if line.startswith() and api_key in line.lower() and in line: blocked.append(line) return blocked def build_prompt(diff, rule_warnings): system_prompt ( 你是资深代码评审专家。只评审变更行禁止评论文档或注释。 如发现问题返回JSON格式为 {\issues\: [{\severity\: \error\, \line\: 1, \message\: \问题\, \suggestion\: \修复建议\}]} ) user_content f以下是 diff\n{diff}\n if rule_warnings: user_content f\n规则引擎发现以下额外可疑内容{json.dumps(rule_warnings)}\n user_content \n请给出JSON格式评审意见。 return system_prompt, user_content def call_model(system_prompt, user_content): payload { model: MODEL_NAME, messages: [ {role: system, content: system_prompt}, {role: user, content: user_content}, ], stream: False, format: json, # 强制 JSON 输出 } resp requests.post(OLLAMA_URL, jsonpayload, timeout300) resp.raise_for_status() return resp.json()[message][content] def parse_review_result(model_output): try: data json.loads(model_output) issues data.get(issues, []) except json.JSONDecodeError: # 如果模型输出不符合 JSON直接丢弃避免异常评论 issues [] return [i for i in issues if i.get(severity) in (error, warning)] if __name__ __main__: diff_text get_diff() rule_warn rule_precheck(diff_text) if not diff_text.strip(): print(No diff found.) exit(0) sys_prompt, user_msg build_prompt(diff_text, rule_warn) raw_output call_model(sys_prompt, user_msg) final_issues parse_review_result(raw_output) print(json.dumps(final_issues, ensure_asciiFalse, indent2))几个关键点format设置为json是 Ollama 2.x 以后支持的 JSON 输出模式会显著降低模型输出额外自然语言解释的概率。同时parse_review_result里对解析失败做了兜底宁可放弃这条输出也不要在 PR 里挂着“无法解析的模型废话”。3.4 接入 GitHub Actions自动评论 PR为了让评论直接定位到代码行我们通过 GitHub API 的create review comment接口把问题挂到对应的 diff 行上。下面是一个简化版的工作流文件name: open-code-review on: pull_request: types: [opened, synchronize] jobs: review: runs-on: ubuntu-latest permissions: pull-requests: write contents: read concurrency: group: review-${{ github.event.pull_request.number }} cancel-in-progress: true steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - name: Run code review script id: review run: | python review.py result.json cat result.json - name: Post comments to PR run: | jq -r .[] | \(.line)\t\(.message)\t\(.severity) result.json | while IFS$\t read -r line message severity; do gh api \ --method POST \ repos/{owner}/{repo}/pulls/{pull_number}/comments \ -f path${{ env.REVIEWED_FILE }} \ -f line$line \ -f body$severity: $message done env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}这个流程里我预留了REVIEWED_FILE环境变量实际项目中你可能需要从 diff 中提取出文件路径注释挂载的行号必须是 diff 上下文中的新增行行号否则接口会报错。评论全部是通过 GitHub Token 完成的权限控制在pull-requests: write不需要额外创建机器人账号。4. 常见踩坑实录与排查技巧稳定运行的关键4.1 问题速查表我们踩过最深的那几个坑问题现象根本原因解决方式模型反复评论同一段 Code模型对已有代码和新增代码分不清在 prompt 里强调“只审变更行”并增加 diff 行号前缀JSON 输出偶尔夹带 Markdown 文本模型训练时有指令遵循的偏差强制format: json解析失败直接丢弃PR 一多 CI 就排队并发模型服务能力不足给 workflow 加concurrency限制超过 5 个任务排队等待模型对驼峰命名不规范提出大量 warning模型把“风格建议”当成了“问题”后置过滤器按severityinfo过滤不再推送内网机器拉取模型失败无法连接 Ollama 官方源提前 docker save 模型镜像或配置代理镜像4.2 误报治理从“看什么都像问题”到“准确率高得多了”使用初期模型对“可疑”很敏感尤其是对 null 判断、异常吞掉这类模式经常给出 warning。这本身没问题但 warning 太多会淹没真正的 error。我们的治理办法是在后置过滤阶段叠加一个历史误报库我们把每次人工标记为“无效评论”的内容保存下来后续遇到文本相似度超过 90% 的新评论时直接降级不再作为 error 推送。这个去重机制表面上看起来简陋但对减少团队对工具的“狼来了”疲劳非常有效。另一个心得是按仓库调整 prompt 示例。每个团队的代码习惯不同如果团队里习惯用ResultT这样的单子模式而模型默认认为函数返回 null 是问题就会造成大量误报。我们支持在仓库根目录放一个.open-code-review.yaml里面配置“忽略规则”“额外审查点”“提示词补充”。配置文件版本跟着仓库走仓库演进规则也演进。4.3 长 PR 拆分策略一次只审一坨在实际运行中我们能明显看到模型性能随着 diff 长度增加而恶化。当 diff 超过 300 行时7B 模型开始“健忘”经常遗漏中间部分的错误。对此我们做了“文件级分片”每个任务只审查一个文件文件过大时再按函数切分。这个改动让模型的效果几乎线性提升。代价是消息数量会变多但配合并发限制整体耗时反而比一次性处理长 diff 要短。4.4 智能排队与优先级控制如果你的团队使用共享的 GPU 推理服务肯定会遇到这种情况好几个 PR 同时触发评审一次性把 OLLAMA 服务打满后面的请求全部超时。我们的解决方案是在 CI 与 Ollama 之间加一个简单的任务队列用 Redis 的列表结构存储请求worker 从列表左侧取任务、逐条推理同时设置OLLAMA_NUM_PARALLEL控制模型并发数。优先级方面把含 release 分支的 PR 标记为 high其它为 normal。模型服务再忙核心分支的审查也能优先得到执行。5. 阶段性优化记录用数据说话的一周项目上线第一周我们做了一次量化测量目的是确认这套工具到底值不值得继续投入维护。指标人工评审基线接入 open-code-review 后平均每个 PR 排队时间6.2 小时25 分钟含模型推理评审报告发现的问题数2.3 个/千行4.1 个/千行人为 Miss 的并发问题复现率较高下降约 60%无效评论误报0没有自动化评论早期 40%优化后 12%从数据可以看出AI 最大的价值不是替代人而是把“非常啰嗦、重复性高、需要稳定注意力”的那部分检查交给机器把人的时间解放出来专注于架构合理性、接口兼容性和业务语义校验。误报率从 40% 降到 12%主要是提示词从“宽松模式”改成了“严格模式JSON 输出”再加上重复评论合并策略。后期我们还在考虑通过反馈功能把开发者的“踩下”动作自动回传形成一个持续学习的闭环。最后分享一个实际操作中的细节为了让 PR 评论不至于显得冷冰冰我们在每条评论前面加上了对应的问题置信度标记。开发者在看到[error]时会多看一眼看到[info]时则会直接跳过。这种分层处理比让模型去强制识别“严重程度”要可靠得多。核心经验是不要把大模型当成全能的审查者它的定位应该是“读代码很快的初级评审员”真正的掌控权始终留在团队手里。这也是我们把项目命名为 open-code-review 的原因代码开放规则也开放。后续你可以基于这条主线继续加规则、换模型、调 prompt毕竟代码审查这件事越细颗粒度、越贴合团队上下文效果才会越好。