如何将多子目录下千余个.py文件索引至pgvector，让RAG复用目录结构

一、锚定目录结构的元数据设计 #

每个代码块必须嵌入完整路径上下文的元数据，存入pgvector时除向量字段外，需添加以下结构化字段（建表时为这些字段创建普通B树索引）：

• namespace: 所属模块（如common libraries1、project1）
• file_path: 文件相对根目录的完整路径（如common libraries1/utils.py）
• module_type: 模块类型标记（common或project）
• code_unit: 代码单元类型（file_header、class、function、logic_block）
• parent_unit: 父单元名称（如函数所属的类名、块所属的函数名）

二、代码分块策略（平衡语义完整性与结构关联） #

1. 按Python语法单元拆分
   • 用AST解析所有.py文件，提取每个类、函数的完整定义（含注释、装饰器、内部逻辑）作为独立块，确保每个块是语义自洽的单元。
   • 文件顶部的全局导入、全局常量、模块级注释单独作为file_header块，和该文件的其他块通过file_path关联。
2. 超大单元拆分规则
   • 若单个函数/类超过500行，按逻辑段落拆分（以独立业务逻辑、条件分支为边界），同时在元数据中标记block_index（块序号）和total_blocks（总块数），通过parent_unit关联原函数/类。
3. 禁用无结构拆分
   • 绝对不能按固定行数（如每100行一刀切）拆分，避免破坏代码的语法和语义完整性。

三、索引优化与结构利用 #

1. 分层检索逻辑
   • 用户提问后，先通过元数据过滤缩小范围：比如问通用工具逻辑，优先过滤module_type=common的块；问项目业务问题，优先匹配对应namespace的项目块。
   • 再对过滤后的块做向量相似度匹配，提升检索效率和精准度。
2. 向量嵌入的结构增强
   • 生成向量前，将元数据关键信息拼在代码块内容开头，示例格式：[namespace: common libraries1, file: utils.py, type: function] def data_clean(...): ...，让模型学习到代码的结构关联。
3. 跨模块关联检索
   • 当检索到某项目块包含公共库的导入语句时，自动触发对应公共库模块的关联检索，将相关公共库代码块纳入结果，解决跨模块调用的问题。

内容的提问来源于stack exchange，提问作者GeorgeOfTheRF