上个月接到一个任务：把一套多年没维护的老系统全部源码整理成AI能读懂的语料库。打开仓库一看，近万个源文件铺了满满一层。旧的业务模块、测试脚本、自动生成的临时文件、还有十几份“最终版”“最终版2”的副本，什么都有。我花了大半天做了一件事——没有急着调模型，也没有把文件直接喂给AI，而是先把整个源码库做了一次彻底的语料预处理。做完之后，AI的回答质量有了质的提升。这篇文章就把这件事的完整思路、操作细节和踩过的坑全部记录下来，供同样要管理大规模源码语料的开发者参考。
1. 为什么不能直接把源文件丢给AI
1.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(".", followlinks=False): 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_workers=os.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中，打开文件时使用encoding="utf-8"并指定errors="replace"，但这样会把非法字节替换成�，内容被破坏。更稳妥的办法是先用二进制模式读取，尝试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, encoding="utf-8") return {"hash": file_hash, "path": str(rel)} except Exception as e: print(f"ERROR {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(f"scan files: {len(files)}") tasks = [(f, Path(OUTPUT_DIR)) for f in files] with ProcessPoolExecutor(max_workers=MAX_WORKERS) as ex: results = list(ex.map(process_file, tasks)) results = [r for r in results if r] # 基于哈希去重，实际保留的是第一个写入的文件 print(f"output 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, encoding="utf-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会一直递归下去直到卡死。我增加了followlinks=False参数，并在遍历时跳过所有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调优才有意义。
