企业级代码类 RAG 实战：当 AST 遇上了业务语义
今天在公司做 SDK 知识库，遇到了一个很真实的工程问题。

我们公司有一套自己开发的 SDK，还有 50 多个示例代码。

我的目标是让 AI 能够准确理解这些 SDK，在生成业务脚本时，找到正确的函数、参数和调用示例。

本来以为做个 RAG 就能解决，结果折腾了一天。

记录一下今天的踩坑和优化过程。

### ① 第一次尝试：直接把文档交给 AI

最开始的想法很简单：

既然 AI 不知道我们公司的 SDK，那就把文档给它看。

结果第一篇文档就接近 4 万字。

而当时实际能够放进上下文的内容大概只有 8000～9000 字，根本装不下。

于是开始做 RAG，把文档切片，建立向量知识库。

### ② 第二次尝试：常规文档切片 + AST 代码切片

我开始按照比较常见的方式处理：

- Markdown 文档按照章节和段落切分
- 示例代码使用 AST 按语法结构切分


结果发现效果并不好。

**第一个问题：API 文档被切得太零碎。**

我们的 SDK 中，一个 API 可能支持多种 `type`，而且每种类型对应的参数可能不同。

简单按照 Markdown 章节切分，参数说明和示例代码容易分散。

导致 AI 虽然检索到了相关内容，却找不到完整的调用示例，有时只能自己猜。

**第二个问题：AST 按函数切分也有局限。**

我们的 SDK 示例有一个特点：

大量业务逻辑都集中在一个巨大的 `main` 函数里。

里面包含：

导入 SDK → 初始化 → 各种业务操作 → 执行仿真 → 查看结果。

如果直接按照函数节点切分：

一个切片可能只有 `import`，另一个切片却包含几乎整个 `main` 函数。

虽然符合代码的语法结构，但并不适合实际检索。

这时我意识到：

**代码的语法边界，不一定等于业务语义边界。**

### ③ 第三次尝试：AST + 业务语义重新组织代码

这次我没有放弃 AST。

而是重新思考：

既然我们的业务流程相对固定，为什么不利用这些业务知识指导代码切片？

我先人工分析了实际业务流程，把一份完整的仿真脚本归纳为七八个相对固定的业务步骤。

然后继续使用 AST 解析代码。

不同的是，这一次不再局限于函数边界，而是进一步分析 `main` 函数内部的语句节点。

**根据人工归纳的业务步骤，将相应的代码语句重新分组，形成更有业务意义的切片。**

之后，我把 50 多个 SDK 示例都按照这套思路整理。

这样 AI 在需要某个具体操作时，就有机会直接检索到对应步骤的代码，而不是拿到一个巨大的 `main` 函数。

对我来说，这次优化的核心是：

**AST 负责识别代码结构，业务知识负责指导切片边界。**

### ④ 第四次尝试：重新整理 API 文档

代码的问题解决了一部分，Markdown 文档也需要优化。

我们的 API 文档有一个特点：

同一个函数可能有多种 `type`，不同类型需要的参数不同，但其中大约 50% 的参数又是重复的。

如果过度追求去重，就可能导致一个切片缺少必要的参数信息。

所以这次我选择允许合理冗余。

对于不同类型的 API 调用，尽量保留完整的信息：

- API 名称及用途
- 参数名称
- 参数类型
- 参数取值范围
- 不同 `type` 对应的参数要求
- 具体的代码调用示例


即使不同切片之间有重复字段，我也会把参数保留完整。

因为对于代码类知识库来说，**完整、连贯的调用说明，比单纯减少重复内容更重要。**

我希望 AI 检索到某个 API 时，能够同时看到需要哪些参数、参数怎么填写，以及具体应该怎么调用。

### ⑤ 最后的检索效果

这次采用的是 Embedding + Rerank 的两阶段检索方案。

最开始，知识库有 1000 多个切片。

重新整理之后，变成了 700 多个。

虽然切片数量减少了，但实际测试时，检索效果明显改善。

例如，当 AI 需要使用某个具体的结构创建函数时：

之前可能找不到对应的 SDK 示例。

现在能够检索到相关函数的接口说明和调用代码。

当然，目前主要验证的是检索效果，还不能直接代表最终代码生成成功率。

后续还需要继续验证生成脚本的正确性。

### ⑥ 今天最大的收获

经过这几轮尝试，我发现：

**RAG 切片不是越细越好，也不是冗余越少越好。**

尤其是对于 SDK、API、代码示例这一类知识库。

真正需要考虑的是：

1. 切片是否符合实际业务的语义边界？
2. 代码片段是否保留了足够完整的上下文？
3. API 参数和调用示例是否对应？
4. 检索出来的知识能否帮助 AI 完成实际任务？


当然，我今天的方法有个重要前提：

我们的业务流程相对固定，而且我对 SDK 比较熟悉。

所以能够通过人工梳理业务流程，再结合 AST 对代码进行结构化处理。

如果换成一个业务逻辑高度动态的通用代码库，可能就需要其他策略。

**今天最大的感受是：RAG 不只是一个向量检索问题，也是一个知识组织问题。**

有时候，与其反复调整 Chunk Size，不如先想清楚：

AI 完成一个任务，究竟需要什么样的知识？

这只是今天的一次小实践，后续还会继续优化。

你们做代码类 RAG 时，是直接按照 AST 切片，还是会结合业务语义进行处理？

#AIGC创作大赛·夏日