如何通过构建 RAG 知识库有效降低 LLM 在生成代码时的逻辑幻觉

给 Cursor 或 Claude Code 喂一个庞大的官方文档 PDF 往往没用，因为 LLM 在处理长上下文时依然会有“中间丢失”现象，导致生成的代码虽然语法正确，但调用接口的方式完全是凭空捏造的。要真正解决代码幻觉，必须把 RAG 的颗粒度从「文档级」拆到「函数/类定义级」。

我最近在给一个冷门 SDK 写封装，通过构建私有 .cursorrules 和本地向量索引，把幻觉率降低了大概 60%。核心逻辑是：不要让 AI 去“阅读”文档，而要让它在生成前先“检索”到精确的 API 签名。

具体实操步骤：

1. 结构化知识切片（Chunking）
不要直接上传 PDF。我用 Python 写了个简单的脚本，把文档里的每个 API 定义、参数类型、返回值以及一个 Minimal Example 强行绑定在一起，存成一个个独立的 .md 文件。
例如：api_getUserInfo.md 包含：

• 函数名：getUserInfo
• 参数：userId (string)
• 行为：获取用户信息，注意该接口在 v2.1 后弃用了 token 参数。
• 示例：client.getUserInfo('123')

2. 强制约束 Prompt 指令
在 .cursorrules 或者项目的 .claudecode.config 中加入强约束，强制 AI 在写代码前必须执行检索动作。

# Code Generation Rule
Before implementing any function involving [SDK名称], you MUST:
1. Search the local docs folder for the specific API signature.
2. Verify the parameter types against the retrieved .md file.
3. If the retrieved documentation conflicts with your internal knowledge, the local .md file takes absolute priority.

3. 解决“版本打架”的坑
最容易踩的坑是 LLM 的预训练权重里有旧版本代码，它会倾向于用旧语法。我发现最有效的办法是在 RAG 检索出的片段顶部加上 Current Version: v3.0 (Deprecated: v2.x) 这样的显式标记，并在提示词里要求它：Compare the retrieved version with your training data and use the latest one。

效率提升点：
以前我得在浏览器和编辑器之间反复横跳，复制 API 文档到对话框。现在直接在 Cursor 里 @Docs 指向我的结构化文件夹，AI 生成的代码几乎不需要修改接口名和参数顺序，直接编译通过。

推荐的目录组织方式：
docs/api/ (存放单个 API 的 md 文件)
docs/patterns/ (存放最佳实践代码片段)
docs/gotchas/ (记录已知的 Bug 和避坑指南)

这种把知识库“原子化”的做法，比直接给一个 50 页的 PDF 要高效得多。