我前段时间搭了一套基于 Ollama 本地大模型 RAG 的代码知识库问答系统把某个内部项目的代码仓库做成可检索的知识库。刚开始用起来确实爽问“这个配置函数在哪定义”“这段废弃逻辑在哪个模块”回答得又快又准。但两周之后我发现一个致命问题代码提交改了不下三十次知识库却还停在最开始的版本。问题出在“静态索引”上——RAG 这种方案索引不做更新回答就永远用旧代码。这篇文章就围绕“让代码知识库活起来”这个目标把 Ollama RAG 代码仓库的增量更新与自动同步完整拆解一遍。适合已经跑通基础 RAG、但被“知识库过期”坑过的开发者也适合准备上手评估增量方案的同学。我会把架构思路、实现细节、参数调整和踩坑实录一并分享。1. 需求拆解静态代码知识库的三个致命伤1.1 过时答案比没有答案更危险如果知识库没有答案最多就是“不知道”用户会自己去查代码。但如果知识库返回的是旧版本代码的答案问题就大了。模型往往会基于检索到的片段给出非常肯定的回答检索片段是旧的、结论是新旧代码拼接的甚至会把已删除的函数当成存在的东西介绍给开发者。我见过最典型的一次某个 API 内部逻辑已经在最新版本里改成异步调用但知识库检索到的还是同步调用的旧实现。使用知识库的同事直接照着旧答案去改代码结果上线前联调才发现完全对不上。这种事故的根子不是大模型的智商问题而是“检索到的内容本身不可信”。如果没有增量更新RAG 系统的时间价值是快速衰减的。知识库刚建好答案准确率看着不错一周后开始出现偏差一个月后基本只剩参考价值。这个衰减速度比很多人预期的快得多因为代码改动是持续发生的而知识库索引却是一次性的。1.2 全量重建的成本与致命问题有的团队会觉得知识库过期就过期呗过一段时间全量重新索引一遍不就行了。这个思路在代码量小的时候确实可行但代码仓库是会膨胀的。一个中等规模的仓库动辄几万个文件全量 embedding 的花费不只是时间还有机器资源的持续占用。按照我自己实测的经验embedding 全量建索引的耗时与代码文件数量和 chunk 数量成正比。假设一个仓库有 2 万个 chunk用本地小模型批量 embedding大概需要十几分钟到半小时如果用云端模型 API除了超时风险还有按 token 计费的成本问题。更别说每次全量重建时旧的索引要不要先清空、清空期间问答服务是停还是不停、新索引没建完过程中系统处于“半可用”状态怎么处理。全量重建还有隐性风险embedding 模型版本如果升级过旧向量与新向量所在的向量空间不一致可能出现新旧向量混用导致检索质量下降。这个问题在全量重建时往往被忽略增量更新反而容易暴露出这种不一致。1.3 代码库的特殊性块级变更与级联影响代码知识库和文档知识库不一样。文档是章节、段落级别的自然语言改一个词的语义影响通常局限在局部代码不一样一个函数签名变了所有引用它的地方都受影响。所以“增量更新”这件事放到代码场景里不能简单理解为“哪个文件变了就重新索引哪个文件”。它至少包含三层文件层哪个文件内容变了。块层文件内部哪个函数、哪个类变了。影响层变了之后依赖关系图中哪些其他模块的检索语义需要连带更新。如果只做文件级更新一个文件被改动后就把整个文件的 chunk 全部重灌到向量库那有些结构复杂的大文件几千行的模块会产生大量冗余向量还容易把没变的部分也洗一遍。真正合理的粒度是“块级别”。2. 架构设计增量同步的整体方案2.1 模块划分与数据流整个增量同步系统我拆成四个模块采集器负责从代码仓库拿到变更信息可以是 git diff 的解析结果也可以是文件监听器发现的变化。检测器负责判断哪些变更真正影响知识库排除注释改动、空行变化、格式化变化这类“伪变更”。索引器负责把变更后的代码块转换为向量并同步到向量数据库。调度器负责编排整个流程的执行时机、重试策略和失败恢复。这四块配合起来数据流大致是这样仓库产生变更 → 采集器感知到变更 → 检测器对比旧索引状态筛选出需要处理的 chunk → 索引器完成新增、修改、删除三类操作 → 向量库完成提交后问答端开始访问新版本知识。这个设计里查询链路和更新链路尽量解耦。问答服务是实时读向量库的更新流程在后台异步跑不应该阻塞正常的检索请求。2.2 技术选型逻辑先说向量数据库。早期我用的方案是 Chroma因为它的 API 简单、get/upsert/delete 都有适合快速验证。但跑了一段时间后发现如果要做“按文档源删除全部向量”这种操作Chroma 有一点别扭因为 delete 需要知道主键 ID而 ID 如果不提前规划好后面就找不到了。所以对于这个项目我最终选择的是 PostgreSQL pgvector 的路线。原因有三一是便于按 metadata 过滤SQL 层面的条件筛选很灵活二是事务性好知识库维护起来不容易出现半更新状态三是同一套数据库里管理版本快照和向量数据更方便。表结构上核心就一张表字段类型说明idvarchar向量唯一 ID用“文件路径:块序号”构造contenttext代码块原始文本file_pathvarchar所属文件git_revvarchar提交版本号 / 提交哈希vectorvectorembedding 结果updated_attimestamp索引更新时间embedding 模型我用的是 Ollama 本地跑的 nomic-embed-text。选它的原因是原生支持 768 维、上下文 8192在本地跑速度不错而且在代码混合文档场景下表现均衡。更有野心的路子是接 bge-m3 或者单独训练代码专用 embedding但在没有强需求之前nomic-embed-text 是性价比最高的起点。2.3 触发链路三种方案各有取舍增量更新必须有一个触发机制。代码仓库在本地环境下我见过三种常见选型第一种是定时轮询。代码里面跑一个定时任务每隔几分钟对仓库做一次 git fetch 和 git diff。优点是对仓库无侵入、实现简单缺点是实时性有延迟、每次轮询都要做一次仓库状态对比。第二种是 Git 钩子。在仓库的 post-commit 或者 post-merge 钩子里调用同步脚本。优点是实时性极好、变更信息直接可得缺点是要侵入仓库配置——团队成员本地各自建库的话钩子部署就变得很麻烦。第三种是文件监听。用 watchdog 之类的库监听仓库目录变化一旦发现 .py/.js/.go 等源码文件变化就触发同步。优点是文件级实时缺点是与编辑器保存行为强相关每次 CtrlS 都可能触发一次同步容易把更新链路搞得很吵。我实际用的是“定时轮询为主、Git 钩子为辅”的混合方案仓库侧不强制大家装钩子同步服务端每 10 分钟轮询一次 git log发现新提交就走增量流程。需要实时反馈的目录再单独部署一个钩子快速触发。2.4 为什么“增量”必须落到代码块粒度增量更新的本质是“尽量少做、但别漏做”。如果一个文件被改动要把被改动的函数、类重新 embedding而不是把整个文件的所有 chunk 都删了重灌。落到代码块粒度还有一个重要理由embedding 向量库里的内容可能是“文件片段”检索的时候只需要该函数相关的上下文就够了。比如一个 2000 行的模块整个文件切成一个长 chunk 去 embedding检索向量很可能被无关内容干扰但如果按函数/类切成 20 个短 chunk命中目标函数的概率就高得多。所以同步系统做增量的时候永远不要“改一个文件 → 重新索引整个文件”而是“改一个文件 → 解析文件 → 比较每个函数块的哈希 → 只对变化块执行 upsert/delete”。这样才能把一次同步的耗时控制在一秒左右而不是几十秒。3. 核心细节与实操实现3.1 代码分块方案结构感知切块代码和自然语言的分块逻辑差别很大。按字符数硬切文档的方式切代码会把一个函数劈成两半导致语义残缺。我之前犯过这个错误用固定 512 字符的滑动窗口切一个 Python 文件结果一个 400 行的类被切得七零八落检索到的片段连 def 开头都没有问答效果非常差。踩坑之后换成了结构感知切块用 tree-sitter 解析文件得到 AST。遍历语法树把每一个函数定义、类定义、方法定义作为独立的 chunk。如果某个函数体超过预设上限再按顶层语句把函数体内的逻辑块切分。保留文件头部的 import 区块作为全文件的公共上下文。用 tree-sitter 的好处是能区分不同语言的语法结构同一个方案适配多语言代码库。而且通过树节点拿到函数的起始行和结束行分块边界是和代码语义严格对齐的。切出来的每个 chunk 都附带结构化元信息类名、函数名、文件路径、起始行号。这样的好处很明显检索时返回的 top-k 片段都是“完整可读”的代码段放到上下文里大模型能直接理解而不需要猜。3.2 变更检测实现从 Git 提交到影响集合增量检测不能只靠文件大小或者修改时间因为代码文件经常出现“内容没变但 mtime 变了”的情况比如 git checkout、批量 CRLF 转换、格式化工具全仓跑一遍。所以我把变更检测做了两层第一层是文件级检测做法是记录每个文件的 SHA-256 哈希。轮询脚本每次执行时对源码文件重新计算哈希与存储的旧哈希比对筛出内容真正变化的文件。这一层很轻几万个文件的哈希扫描也就在秒级。第二层是块级检测对筛出来的文件用 tree-sitter 重新解析出函数块列表对每个块计算块内哈希。如果某一块的哈希值与上一版本不一致就把这块标记为候选更新块。要删除的块旧版本里有但新版本里没有也要识别出来。还要处理“引用影响”的问题。严格做法是维护全量符号表检测某个函数签名变更后把所有 import 过它的文件都标记为“待重新解析”。在纯增量第一版里可以不做这一步但至少要把“变更文件内关联引用”考虑进去否则容易出现检索返回旧拼接信息。3.3 同步实现向量库的 Upsert 与 Delete同步的最终操作分三类新增块向向量库插入新向量。修改块更新现有向量用新 embedding 覆盖旧的。删除块把物理上已不存在的代码块的向量移除。在 PostgreSQL pgvector 的 SQL 实现里删除操作比较直接DELETE FROM code_vectors WHERE file_path src/parser.py AND chunk_hash NOT IN ( SELECT chunk_hash FROM staged_code_chunks );这个思路是先算出当前文件所有新的 chunk 哈希把“库里存在、但新版本里已经没有”的哈希删掉。它比“按 ID 逐个删”要可靠得多。新增和修改统一走 upsertINSERT INTO code_vectors (id, content, file_path, chunk_hash, embedding, updated_at) VALUES (%s, %s, %s, %s, %s, NOW()) ON CONFLICT (id) DO UPDATE SET content EXCLUDED.content, chunk_hash EXCLUDED.chunk_hash, embedding EXCLUDED.embedding, updated_at NOW();id 是唯一键这样新块插入旧块更新天然是幂等的。同步删除的时候最怕误删“这个块在新版本里没出现”可能不是因为删除了而是因为解析器没识别出它。比如动态拼函数名的装饰器、eval 构造的代码块都是解析器容易漏的情况。所以删除操作要有保护机制——只有明确拿到 git diff 中带减号行的删除块才真正向向量库发 delete否则最多先标记待确认。3.4 调度器与失败恢复增量更新如果只跑一次成功那也不需要什么调度器。但跑到实际环境就会发现同步任务偶尔会因为网络抽风、模型推理超时、数据库连接断开而中断。失败之后如果直接重跑整包又可能把之前已经同步成功的块重复 embedding。我这边把同步任务设计成了“批处理 状态指针”的方式每次任务处理的是从上次成功位置到当前提交之间的增量。任务开始时生成一条 task batch 记录记录开始 commit 和结束 commit。每个 chunk 处理完就把 chunk_hash 写入 batch 的 completed 集合。任务失败后重试时查询 completed 集合跳过已处理过的块只处理未完成的块。这样重试是幂等的速度也快。调度器本身我用 APScheduler 的 BackgroundScheduler轮询间隔 10 分钟超过 15 分钟还没完成的任务自动报警并进入重试队列。刚开始实现时犯了“失败就全量重来”的毛病后来改成上面这套 batch 续传逻辑稳定性高了很多。4. 实录一套可运行的完整流程4.1 环境与依赖准备写一个可落地的参考实现环境假设如下本地 Linux 服务器已有 Ollama 服务模型 nomic-embed-text 已拉取。代码仓库在本地路径git 工作区干净。PostgreSQL 14 已安装 pgvector 扩展。Python 依赖方面我实际跑的最低组合是库名用途tree-sitter解析代码生成 AST 分块gitpython读取 git log / diffpsycopg2-binary连接 PostgreSQLpgvectorPostgreSQL 向量扩展apscheduler任务调度requests调用 Ollama API核心逻辑就三步检测变更、解析分块、同步向量。4.2 把增量检测做成一个小脚本检测脚本先算出当前 HEAD 和上次记录的 HEAD 之间的提交列表import git repo git.Repo(/path/to/code/repo) last_rev load_last_rev() # 从本地 state 文件读取 head_rev str(repo.head.commit) changed_files [] if last_rev ! head_rev: diff repo.git.diff(last_rev, head_rev, name_onlyTrue) changed_files [f for f in diff.splitlines() if f.endswith((.py, .js, .go))]这里不要直接逐个文件去看 git log因为如果两次增量周期之间提交很多每次提交都取 diff 会爆炸。正确做法是只对比 last_rev 和 head_rev 之间的整体 diff。这一步就能筛掉一大半不涉及代码变更的文件。4.3 tree-sitter 分块与哈希比较对每个变化文件解析并切成块然后和上一版本的块哈希做差import tree_sitter_python as tspython from tree_sitter import Language, Parser LANGUAGE Language(tspython.language()) parser Parser(LANGUAGE) tree parser.parse(source_bytes) blocks extract_function_blocks(tree, source_text) for block in blocks: h sha256(block[text].encode()).hexdigest() if h ! block_store.get(block[id]): queue_upsert(block)这段代码省略了 AST 遍历过程核心是把每个函数块提取为一条记录。比较差异的时候注意一个经验不要用修改时间而要用内容哈希因为 git pull 之后整个目录的 mtime 会全部刷新只看时间等于全量重建。4.4 向量写入调用 Ollama 生成 embeddingOllama 的 embed 接口一次调用输入一条文本返回一个向量。实测下来 nomic-embed-text 对 1024 token 以内的 chunk 延迟大概 80-150ms一个中大型仓库的增量同步也就涉及几十上百个块总耗时控制在半分钟以内。import requests resp requests.post( http://localhost:11434/api/embed, json{model: nomic-embed-text, input: block[text]} ) vector resp.json()[embeddings][0]批量写入时要注意 Ollama 同时处理多个请求的并发能力我在实际测试时把并发数压到 4发现比并发 16 还要稳定。并发太高时 Ollama 会排队反而拖慢整体完成时间还不如固定小并发配合批处理。4.5 完整同步主流程整个同步方法串起来大概是这样读取上次增量位置。对仓库执行 git fetch 与 git diff得到变更文件列表。对每个变更文件解析出块级差异集合。过滤掉注释、纯格式化变更对真正的块计算 embedding。对旧库中已不存在的块执行 delete对新增和修改块执行 upsert。更新 last_rev 到当前 HEAD。执行失败则保留部分进度下次从断点续跑。这个流程跑通之后知识库的“新鲜度”就是可控的。我观察过一个跑了两周的系统最后一条问答检索到的代码片段和仓库最新 HEAD 之间相差不超过一个同步周期。4.6 参数调整的实操心得运行效果好不好不看模型选得多强关键在几个参数chunk 长度我这边设置函数块上限 256 行超过的行数按语句再切开。再大的块即使 embedding 模型装得下检索注意力也会被无关逻辑稀释。top_k默认检索 8 个块。代码场景下 top_k 设太大会把无关文件搅进来设太小又容易漏关键信息。实测代码库 top_k 6 比 10 效果好很多。相似度阈值pgvector 里我用余弦距离阈值设在 0.2 以下距离越小越相似。阈值太高会把语义相近但内容不一致的块也送进上下文。5. 常见问题与排查技巧实录5.1 幽灵片段库里残留旧版本代码最常遇到的问题是“知识库明明同步了但回答里还有旧代码”。查下来十有八九是向量库的 delete 没生效。原因要么是 ID 设计碰撞导致覆盖位置不对要么是删除条件判断得太保守旧块一直留在库里没被标记为删除。排查思路清晰先看回答里给出的片段路径和行号去数据库直接查这条向量确认它存在然后用更新脚本打印它最后一次 updated_at。如果 updated_at 是很早的时间说明它根本没进入更新队列要在“变更检测”环节补上对旧块的比对逻辑。5.2 重复索引与脏数据嵌入向量库的数据偶尔会出现重复。比如同一个函数因为跨文件 import 被两个文件各自的解析器各索引了一次检索出来两条一模一样的片段。解决的思路是给向量表加上联合唯一索引唯一键用file_path, chunk_hash而不是file_path, chunk_id。插入前做一次存在性检查能过滤掉八成重复。还有一种是同步任务重复执行时没有幂等保护把同一块 upsert 了两遍。这要靠 3.4 里说的 batch completed 集合来兜底。5.3 embedding 模型版本更换后的全栈重灌增量更新最大的坑是Ollama 里 embedding 模型一旦从 nomic-embed-text 换成了另一个模型整个向量库所有向量全部失效。因为不同模型生成的向量分布不同新旧向量混在一个库里检索距离比较完全没有意义。遇到这种情况没有捷径只能全量重灌。为了避免后期的全量重灌我建议在向量表里加一列 model_name每次写入时记录模型名。检索时强制只查 model_name 等于当前模型的数据。这样即使模型升级也只是旧模型的数据变“不可用”不会污染新模型的结果。5.4 定时任务失联与人工补救某次生产环境的同步在凌晨断掉日志还没接好第二天一查知识库已经落后了十几个提交。这种情况靠定时任务自身很难感知我的补救方案是同步状态额外记录一个“最后成功时间”用一个独立健康检查任务每天检查如果超过 2 小时没有成功更新就发告警。人工补救也很简单把 last_rev 手动回拨到目标 commit。运行一轮完整同步后知识库就追平了。需要注意回拨前把 batch 状态清理干净不要带着旧的断点续跑记录。6. 写在最后的经验心得最后分享一点我当时最深的体会增量更新和自动同步不是“锦上添花”的功能而是代码知识库能否长期可用的地基。第一次搭 RAG 的时候我花了很多精力调模型提示词、调检索参数但知识库索引却一直被当成一个一次性构建的静态产物。等到业务里真正用起来才发现做好增量链路让整个系统的有效性至少上了一个台阶。如果让我重新做一遍我一定会先把“变更检测 幂等同步 失败恢复”这三件事设计清楚再回头看检索优化。知识库“活”起来才能真正成为团队的长期资产。