上个月接到一个任务把一套多年没维护的老系统全部源码整理成AI能读懂的语料库。打开仓库一看近万个源文件铺了满满一层。旧的业务模块、测试脚本、自动生成的临时文件、还有十几份“最终版”“最终版2”的副本什么都有。我花了大半天做了一件事——没有急着调模型也没有把文件直接喂给AI而是先把整个源码库做了一次彻底的语料预处理。做完之后AI的回答质量有了质的提升。这篇文章就把这件事的完整思路、操作细节和踩过的坑全部记录下来供同样要管理大规模源码语料的开发者参考。1. 为什么不能直接把源文件丢给AI1.1 原始仓库的真实状态乱、重、杂我最初打开仓库时以为只要把文件全部读出来扔给大模型就行。结果先写了个统计脚本扫描了一遍发现情况远没有这么简单。先说“乱”。这个仓库的目录结构里既有src/main/java这样的正式目录也有old_work/2020_backup这种时间备份目录甚至还有tmp_test/这种随手建的学习场地。不同目录下的代码命名规则完全不同同一个功能模块在三个目录里各有一份实现谁新谁旧光看文件名根本分不清。再说“重”。仓库里大量文件都是重复的。有的是手工复制后改名有的是构建工具自动生成的副本。我统计了一下模拟项目X里光带copy、bak、backup后缀的文件就有两百多个。还有将近一万个文件里有接近四分之一的内容是完全重复的——用哈希值一比对就现出原形。这些重复文件不清理喂给AI后模型会来回学习同一段内容既浪费token又打乱上下文。最后是“杂”。除了真正的源文件仓库里混着大量二进制包、日志文件、图片、模型权重文件甚至还有几个几百兆的压缩包。这些文件如果被AI当作源码去读轻则解析失败重则把二进制内容强行按文本解码产生一堆乱码噪点污染整个语料库。1.2 AI对输入语料有隐性要求很多人以为大模型能处理海量文本所以把文件一次性全部塞进去就行。但实际操作中模型对语料是有隐性要求的。第一点是“语义单元清晰”。一段语料应当尽可能围绕一个主题、一种语言、一个模块来组织。如果直接读某个源文件前面的代码是Java后面的片段又拼了一段SQL和正则表达式模型很难判断当前应该按什么语法来理解。把近万个文件直接拼成一个大文本AI彻底糊涂上下文被各种无关代码反复打断。第二点是“去噪优先”。语料里的注释、生成代码、无用代码块对模型来说都是噪声。尤其是自动生成的代码例如编译产物和“// generated by xxx”的模板代码占据了大量token却几乎没有语义信息反而会引导模型烤进错误的模式。第三点是对“结构信息”的敏感。模型读代码时如果不知道文件的路径、模块归属、依赖关系它只能靠猜测。而预处理时保留这些元数据AI就能按图索骥地理解文件在整个项目中的位置。我常打一个比方给AI喂原始仓库相当于把一筐没洗的菜、冷冻肉、调味料连着包装袋一起倒进锅里而预处理要做的是把菜洗净切好、把肉类分类、把食材按菜谱摆盘。AI不需要自己去分辨“这根葱是不是能吃的”它只需要专心做菜。2. 我做的那件事给近万个源文件建立预处理管线2.1 先定义处理范围和目标动手写脚本之前我先把处理目标写成了三段话只保留真正的源代码文本排除构建产物、二进制文件和压缩包。对源码文件做去重、格式统一并补充必要的元数据。生成一个总索引文件让AI能够仅在大局信息下按需读取具体文件。这三段话看着简单但落地的时候没有边界容易失控。比如有些配置文件是.json里面也含逻辑但更多时候只是参数表是否保留我的策略是保留可读文本格式但把配置类文件归入“配置语料”与源码分开存放避免模型将配置误认成逻辑代码。接着确定文件类型白名单。以模拟项目X为例我保留了.py、.java、.js、.ts、.sql、.xml、.yml、.md等文本类扩展名其余全部排除。二进制文件不看内容直接按扩展名过滤效率最高。2.2 文件扫描与统计先摸清家底处理近万个文件一上来就做清洗是盲人摸象。我先写了一个扫描脚本用os.walk遍历仓库统计三类信息扩展名分布、文件大小分布、重复率情况。扫描脚本的核心逻辑很直接import os from collections import Counter ext_counter Counter() size_list [] for root, dirs, files in os.walk(., followlinksFalse): for name in files: path os.path.join(root, name) try: size os.path.getsize(path) except OSError: continue ext os.path.splitext(name)[1].lower() ext_counter[ext] 1 size_list.append((size, path)) for ext, count in ext_counter.most_common(20): print(f{ext}: {count})跑完一遍后我拿到了这个仓库的真实数据总文件数9567总大小2.3GB扩展名种类有47种。其中仅.class文件就有三千多个这些是编译产物真正需要的.java源文件只有一千四百多个。整体来看实际有效源码只占总文件量的两成左右。这个数据把问题摸清了不能直接喂原因是有效内容太少、噪声太多。同时这个统计结果也能帮助我和团队成员对齐认知知道最终输出的语料规模大约是多少。2.3 去除重复和“伪源码”扫描之后我做了一次去重。去重不能只用文件名因为复制出来的文件常常改名。我用内容级别的MD5哈希去重所有文件的哈希值一致就认为内容完全一致只保留一份。import hashlib def file_md5(path): h hashlib.md5() with open(path, rb) as f: for chunk in iter(lambda: f.read(8192), b): h.update(chunk) return h.hexdigest()hash相同的文件很多我保留路径最浅、路径信息最完整的那一份其余记录到“重复文件清单”里而不是直接删除。记录清单的好处是一旦后续发现某个文件其实是不同用途还可以追溯恢复。去重之后我做了“伪源码”过滤。自动生成的代码一般具有明显的标记比如文件头注释里写着auto-generated、code generated by等。我建了一个关键词列表只要文件前两行命中关键词就标记为“生成文件”并排除。另外我还按目录名字黑名单过滤build/、dist/、node_modules/、target/等目录一律跳过因为这些目录里绝大多数不是手写源码。2.4 结构化输出文件头加元数据再生成总索引清洗完的源码文件仍然是一团散沙。如果直接把它们按原始路径存放AI在读取单个文件时会缺失项目层面的上下文。所以我做了两件事。第一件事为每个保留的源文件添加一个标准化的文件头。文件头使用YAML格式记录路径、语言、模块名、最后修改时间、依赖模块列表。比如一个订单模块的Java文件处理后文件开头会是这样--- path: src/main/java/com/example/order/OrderService.java language: java module: order dependencies: [payment, inventory] ---这个文件头相当于给每个文件贴了标签。AI读文件时第一眼就能知道“我在看哪个模块、用什么语言写的、跟其他模块有什么关联”从而以正确的姿势解析后续代码。第二件事生成一份总索引。索引文件我可以理解成整个仓库的地图里面列出所有保留文件的路径、所属模块、一句话摘要和文件行数。AI使用时先读索引再根据索引按需读取具体文件而不是一次吞下全部语料。这样既节省上下文空间又能提高检索的精准度。3. 关键参数与工具选型3.1 脚本语言与并发策略预处理脚本我选了Python原因很简单文本处理生态成熟写起来快os、hashlib、pathlib、concurrent.futures都是标准库不需要额外依赖。真正要注意的是并发策略。近万个文件不算多但如果每个文件都做哈希、编码检测、内容清洗单线程跑也要几分钟到十几分钟。我采用了进程池并发处理而不是线程池因为CPU密集型计算哈希、解码受Python GIL限制较大多线程提升有限多进程则能利用多核。进程数不需要拉满。我建议使用max_workersos.cpu_count() - 1留一个核心给操作系统和监控工具避免整个机器卡死。处理逻辑也很简单把所有文件路径列表切分后交给进程池每个worker独立完成“定义白名单 - 读取内容 - 计算哈希 - 清洗格式”这一整条链然后再把结果汇总。3.2 阈值的取舍多少行算有效什么是重复清洗过程中需要定几个阈值这些参数直接影响最终语料的规模。第一个是文件大小下限。很多小于1KB的文本文件只是空壳或一行模板比如只包含一段import的.java文件。这类文件本身信息量极低但保留它们问题也不大。为了避免误杀我把“完全无效文件”的阈值定得太保守低于10字节的文件直接剔除大于等于10字节的保留。10字节大约是一行空注释的长度再短的真没什么可读了。第二个是重复的定义。我使用“内容哈希完全相同”才算重复没有用相似度算法。理由很务实项目里真正的“近似重复代码”往往发生在同一个功能的多个版本之间这类文件用相似度判断很容易误判。近万个文件用simhash或token粒度对比成本高、收益不稳定。先过滤掉完全重复文件已经能省掉大约20%到30%的冗余。如果需要进一步压缩可以后续再做细粒度相似度分析但这属于优化项不是必需项。3.3 格式统一换行符、编码和BOM老仓库最大的隐藏问题在编码上。很多文件不是UTF-8老Windows时期常用GBK还有少量文件带UTF-8 BOM头。如果不处理AI读取时会出现莫名字符有时连文件解析都会中断。我的处理策略是统一转成UTF-8并且去掉BOM。在Python中打开文件时使用encodingutf-8并指定errorsreplace但这样会把非法字节替换成内容被破坏。更稳妥的办法是先用二进制模式读取尝试decode(utf-8)失败后再尝试decode(gbk)再不行才使用latin-1硬解码——这样至少能保留原始字节的映射关系不至于完全丢失信息。换行符方面也必须统一。Windows的\r\n和Linux的\n混用时AI模型虽然也能处理但在后续划分段落和代码块时容易出问题统一转成\n最省心。3.4 输出格式为什么用Markdown而不是JSON预处理完的文件输出成什么格式直接决定了AI怎么读取。我一开始考虑过把所有文件的内容写成一个巨大的JSON串每个文件作为一个字段。但在实际测试中发现JSON会把代码里的换行和缩进全部转义一下子膨胀30%以上。而且AI读取JSON时还需要额外解析“哪个key对应哪段代码”的逻辑增加了理解负担。最后我选择的是Markdown风格的文本文件每个文件输出为一个.md片段用代码块包裹原始代码文件头放在文档开头。这样模型一眼就能看明白结构哪怕不做额外解析也能正确读取。# File: OrderService.java Author: unknown Language: java Module: order Path: src/main/java/com/example/order/OrderService.java java public class OrderService { // ... }这种格式的好处是结构清晰、可读性好、Token占用低、后续喂给AI时无需额外处理。如果后续要做嵌入向量也可以从这个Markdown版本里很方便地抽取内容。 ## 4. 实操流程一份可复制的源码语料预处理管线 ### 4.1 完整脚本框架 下面是我实际使用过的核心脚本骨架为了通用性去掉了具体业务路径保留了关键处理流程。完整脚本可以分为扫描、去重、过滤、输出四步。 python import os import hashlib import shutil from pathlib import Path from concurrent.futures import ProcessPoolExecutor SOURCE_DIR /path/to/legacy-repo OUTPUT_DIR /path/to/ai-corpus WHITE_EXT {.py, .java, .js, .ts, .sql, .xml, .yml, .md, .properties} BLACK_DIRS {build, dist, node_modules, target, .git, .idea, output, tmp} MAX_WORKERS os.cpu_count() - 1 def hash_file(path: Path) - str: h hashlib.md5() with open(path, rb) as f: for chunk in iter(lambda: f.read(8192), b): h.update(chunk) return h.hexdigest() def normalize_text(raw: bytes) - str: for enc in (utf-8, gbk, latin-1): try: text raw.decode(enc) break except UnicodeDecodeError: continue else: return text text.replace(\r\n, \n).replace(\r, \n) if text.startswith(\ufeff): text text[1:] return text def process_file(args): src_path, out_dir args try: raw src_path.read_bytes() text normalize_text(raw) if not text.strip(): return None file_hash hashlib.md5(raw).hexdigest() rel src_path.relative_to(SOURCE_DIR) out_file out_dir / (file_hash[:8] .md) header ( f---\npath: {rel}\nlanguage: {src_path.suffix.lstrip(.)}\nsize: {len(raw)}\n---\n\n src_path.suffix.lstrip(.) \n text \n\n ) # 只写入第一次出现的内容重复内容不再覆盖 if not out_file.exists(): out_file.write_text(header, encodingutf-8) return {hash: file_hash, path: str(rel)} except Exception as e: print(fERROR {src_path}: {e}) return None def scan_files(): candidates [] for root, dirs, files in os.walk(SOURCE_DIR): dirs[:] [d for d in dirs if d not in BLACK_DIRS] for name in files: p Path(root) / name ext p.suffix.lower() if ext in WHITE_EXT: candidates.append(p) return candidates def main(): files scan_files() print(fscan files: {len(files)}) tasks [(f, Path(OUTPUT_DIR)) for f in files] with ProcessPoolExecutor(max_workersMAX_WORKERS) as ex: results list(ex.map(process_file, tasks)) results [r for r in results if r] # 基于哈希去重实际保留的是第一个写入的文件 print(foutput files: {len(results)}) if __name__ __main__: main()这个脚本只包含了核心流程还有一些细节没写进去比如索引文件生成、原路径与哈希的映射记录、错误文件清单等。实际使用时我建议至少额外保留一份“处理日志”记录哪些文件因为什么原因被剔除以便回溯。4.2 运行结果示例近万文件被压缩到多少在模拟项目X上跑完整个预处理管线后统计结果是这样的阶段文件数说明初始扫描9567含所有格式扩展名过滤后2143只保留代码和配置文件内容去重后1685砍掉458个完全重复文件排除自动生成文件后1532又去掉153个生成文件最终生成语料文档1532每个文件对应一个Markdown片段总索引1包含所有文件的路径和摘要这个结果意味着AI实际需要处理的内容从近万个文件降到了一千五百多个文件。占用token大幅下降同时因为过滤掉了重复和自动生成代码下游问答的准确率明显上升。4.3 预处理前后喂给AI的对比我用同样的模型、同样的“帮我找出订单模块里支付状态判断所有位置”这个问题做测试。预处理前AI搜索时把大量重复副本、编译产物、甚至旧备份也当作有效代码回答里混杂了多个版本的逻辑一会儿说在OrderService.java里一会儿说在OrderBackup.java里根本无法定位到实际生效版本。它自己也承认没有把握。预处理后AI根据索引文件很快定位到与payment相关的模块再读取实际的OrderService.java和依赖文件给出了一份清晰的清单甚至列出了状态字段的取值范围和对应的分支逻辑。这个体验差距是决定性的。我个人体会是预处理省掉的不是AI的推理能力而是把AI从垃圾堆里捞答案的负担。只要喂进去的内容干净、有结构、有元数据模型的能力就会被真正释放出来。5. 问题排查与避坑指南5.1 文件编码最隐蔽的坑老仓库里最常见的坑就是文件内容不是UTF-8。一开始我直接使用open(path, encodingutf-8)读取结果读不到一半就抛出UnicodeDecodeError程序当场崩掉。后来改成用二进制读取再多重编码解码问题才解决。另一个容易踩的是某些文件开头带着UTF-8 BOM也就是\ufeff字符。这个字符在文本里显示不出来但你把它喂给AI后模型会把它当成一个特殊标记偶尔引起莫名的输出异常。处理方式很简单在归一化文本时把开头的\ufeff剥离掉。如果你也想处理更古老的编码我建议工具链里加上chardet或charset-normalizer做编码检测。但注意检测库并非100%准确检测错误比强制指定还可怕。我的做法是“优先尝试已知编码序列”如果都尝试失败再用latin-1保底。5.2 路径过长、特殊字符和软链循环在Windows环境里老项目常常踩到路径超长问题。某个模块的目录层级很深完整路径已经超过260字符。Python的pathlib.Path在Windows上默认也会受到这个限制。解决办法是在代码中加入路径规范化或者尽量在Linux环境下运行预处理。如果必须在Windows跑可以启用长路径支持或者在顶层脚本里用\\?\前缀。特殊字符也是坑。我在原始仓库中发现了含有两个换行符的文件名仔细一看是历史上某个脚本生成的错误文件。这种文件名在os.walk遍历时不会报错但写入日志或输出索引时会导致格式错乱。解决办法处理文件名时先做一次安全替换把换行、制表符、控制字符替换成下划线。软链循环问题发生在目录中存在符号链接指回祖先目录的情况。比如仓库里有个link - ../如果不加限制os.walk会一直递归下去直到卡死。我增加了followlinksFalse参数并在遍历时跳过所有is_symlink()的目录彻底规避。5.3 二进制文件被误读扩展名过滤虽然能排除大多数二进制文件但有少数文件扩展名是.py或.txt内容却是二进制。原因可能是某些版本管理工具冲突时生成的副本也可能是反序列化时被写坏的文件。这些文件一旦被当作文本解码通常会抛出异常但也可能“成功”解码出一堆无意义字符。我的做法是在解码之前先对原始字节做一个“文本比例”检测。统计可打印字符的占比如果比例低于90%直接把文件标记为疑似二进制并剔除。这个检测成本很低但能防止模型吃进一堆乱码。5.4 处理速度与资源观察预处理脚本跑起来后CPU占用往往直接打满。如果机器内存有限一次性把上万个文件路径全部放进内存再分发给进程池内存占用也会上升。对于近万文件来说通常没问题但如果你面对的是百万级别的大仓库建议分批读取、流式处理。我遇到过的一个实际问题是某个进程池worker因为读取一个特别大的文件比如几百MB的日志误报为源文件而长时间卡住。后来我在读取文件前先检查文件大小超过50MB的直接跳过并记录到异常列表。这个上限要根据你的场景调整但一定要有。另外脚本运行期间可以实时观察输出目录的文件数变化。如果发现大量文件都被跳过多半是白名单配置有问题如果输出文件数量极少则可能是目录黑名单误伤了源码。根据统计日志调整策略比跑完才发现问题高效得多。6. 做完预处理之后的效果与个人体会6.1 实际使用的几种场景预处理完成后这个语料库马上派上用场。第一个场景是代码问答。团队成员直接向AI提问“订单模块的超时时间在哪里配置”AI先读索引再命中对应配置文件几秒钟就能给出准确路径。第二个场景是新人培训。新同事接手老系统时要理解近万个文件确实压力很大。现在可以先让AI基于预处理过的语料生成一份“系统模块地图”把核心模块的职责、依赖关系、关键入口梳理清楚新人顺着地图去读代码效率高了很多。第三个场景是代码审计辅助。在审计某个功能时AI能够很快地说出某段逻辑散落在哪几个文件里还能指出哪些文件是重复副本、哪些是自动生成的、哪些已经废弃。这些判断完全依赖于预处理阶段保留的元数据和索引信息。6.2 经验层面的几点体会我最大的体会是搞清楚“要喂什么给AI”比“怎么调Prompt”更重要。好的语料就是AI的土壤土壤不行施肥再多也长不出好庄稼。预处理确实是脏活累活但它解决的是内容质量的根本问题。第二点体会是任何时候都不要直接删除原始文件。我的所有清洗逻辑都保留“删除清单”和“重复映射”这样哪怕后续发现某个文件被误删也能轻松找回。处理语料不是一锤子买卖迭代是常态。第三点体会是这个预处理脚本别丢保存成通用工具。后来我又接手了另一个更杂乱的仓库直接把脚本改一下目录和扩展名白名单十几分钟就跑完整套流程效果一样稳定。如果你也准备把一个庞杂的源码库喂给AI我建议你动手前先做一次预处理哪怕只做去重和格式统一效果都立竿见影。把这一步做扎实后续的模型选择、Prompt调优才有意义。