01 项目背景  

近两年 AI 技术渗透到各行各业，随之诞生了 AI 编程助手，AI 编程助手生成的代码速度非常快，但生成质量并不一定很好，因此日常我们在使用 AI 编程助手生成代码的过程中会遇到很多问题。  

开发者面临的文档挑战 

1. 编造根本不存在的 API 接口

由于大语言模型存在代码幻觉，有时候会编造一些不存在 API 接口，导致使用 AI 编程助手生成的代码可能很大问题。 

2. 大语言模型的训练数据往往滞后于技术的更新，导致生成的代码常常基于已经废弃的旧版 API

大语言模型语料库仅包含了训练时导入的代码文档，通过大语言模型生成代码时，技术已经迭代更新，且文档也已经更新，然而大语言模型在生成代码时可能还是会基于语料库废弃的旧版 API，从而降低了代码生成的准确性。 

3. AI 可以快速生成代码，但往往不是官方的最佳实践

大语言模型虽然能够快速生成代码，但是通常并不是官方的最佳实践，对开发的效率也会有影响。

现有解决方案的局限性  

1. 传统文档查询方式的效率低下

在代码文档生成的模拟代码质量不高的情况下，我们需要去自行搜索代码文档，将代码文档链接或直接复制文档内容导入大语言模型，作为参考生成代码，效率比较低下。 

2. AI 编程助手与文档系统的割裂

AI 编程助手有时会调用谷歌或获取 API 进行搜索，但由于代码文档可能在官方文档内部并不易查找，或者文档中没有提供导览功能，因此 AI 编程助手无法找到合适的参考文档，不能很好地基于官方文档进行集成。 

3. 缺乏语义理解的关键词搜索

调用模型在调用搜索引擎类 API 时，一般通过关键字方式进行搜索，由于关键字搜索缺乏语义理解，可能搜索结果准确度并不高，此时将搜索结果作为参考文档，会导致生成代码的质量并不理想。

AI 代码幻觉问题举例 

由于 AI 不熟悉文档可能会导致传入参数不正确，例如向 AI 编程助手发出如下命令：使用 elasticsearch- rs 编写代码和 elasticsearch 进行交互，创建一个索引，并写入几条文档。但可能由于 elasticsearch-rs 的已有使用经验较少，我们在训练 AI 的过程中可参考资料有限，可能导致生成结果存在幻觉。从下图可以看到生成的代码参数并不准确，直接爆红，代码无法满足运行要求。

02 Doc2Dev 介绍  

核心功能

那么我们看一下 Doc2Dev 项目是如何解决上述问题和挑战的。 

• 最 新、最准确的 代码：通过提供 Git 仓库 URL 地址，可以让搜索引擎获取最新库版本和最佳实践的建议。 

• 减少调试时间 ：减少因过时的 AI 知识导致的错误修复时间。 

• 拒绝代码幻觉 ：依赖于已记录的、存在的函数和 API。 

• 无缝工作流程 ：直接集成到现有的 AI 编程助手中，无需频繁切换到文档网站。 

• 语义理解 ：基于向量嵌入的搜索超越了传统的关键词匹配，能够理解查询的语义内容。 

  项目 Github 地址

  https://github.com/cr7258/doc2dev 

  在线体验：https://doc2dev.top

整体架构

项目的整体架构主要包括前端、后端、 #OceanBase  数据存储、AI 编程助手集成四部分。其中设计最为复杂的是后端 API 服务层，如下图所示，最右侧是索引服务，当用户提供了一个 Github 或 Gitlab 仓库地址时，Doc2Dev 会获取 Git 仓库中的文档内容，并进行解析和预处理，然后调用 Emebedding 服务将文档转化为向量，最后将数据存储到 OceanBase 中。中间的查询服务，用户提出的问题同样会被进行 Embedding，然后和 OceanBase 的内容进行匹配，匹配内容会同步给大语言模型生成摘要后返回，便于  #Agent  参考代码结构。最左侧是  #MCP  服务器，提供 MCP 服务器便于和 Cursor、Windsurf 进行集成。

技术栈

上文提到的各部分的技术栈如下： 

• 前端：Next.js, React, TypeScript, Tailwind CSS, shadcn/ui 

• 后端：Python, FastAPI, WebSockets 

• AI 模型： 

• 嵌入模型：用于生成文档的向量表示 

• LLM ：用于生成搜索结果摘要 

• 数据库：使用 OceanBase 处理向量存储、元数据管理和相似度检索

• MCP： 通过 MCP Server 的方式向 AI 编程助手提供查询文档的接口

数据处理流程

数据处理流程是整个项目最为关键的一部分，共分为如下5个步骤： 

1. 文档获取：通过 GitHub/Gitlab API 下载指定公有/私有仓库的 Markdown 文件 

2. 文档分割：将文档分割成适合嵌入的片段， 使用

  #LangChain 的 MarkdownHeaderTextSplitter   

3. 向量嵌入：使用嵌入模型将文本片段转换为高维向量 

4. 向量存储：将向量和原始文本存储到 OceanBase 向量数据库中

5. 查询处理： 

    a. 将用户查询转换为向量 

    b. 在 OceanBase 中进行相似度搜索 

    c. 使用 LLM 生成搜索结果的摘要

03 用户界面设计  

首页

Doc2Dev 的首页展示了索引的仓库总数、列表、占用的 Tokens 数量、代码片段数量等全局信息。点击 + 添加 Git 仓库，即进入索引 Git 仓库页面。

索引 Git 仓库

用户可以在索引 Git 仓库页面提供 Git 仓库 URL，并指定具体的 Git 平台，然后点击下载并索引，系统会开始索引，首先下载对应 Markdown 文件，然后进行 Embedding 存入 OceanBase。操作可以异步完成，即提交任务后可以直接在后台进行处理，然后直接更新进度状态。

查询 

用户可以在查询页面基于已经索引的代码仓库进行查询，例如提问：如何创建索引？系统会进行 一个语义化搜索，然后让代理模型进行总结输出，查询结果展示了代码片段描述，以及如何使用 elasticsearch-rs 库来编写这段代码。

04 MCP 集成  

通过 MCP 方式集成也相对比较简单，Doc2Dev 为每位用户提供了唯一的 MCP URL，用户可通过 MCP Streamable HTTP 方式完成配置。

例如，在  #Cursor  中可以通过以下配置文件进行设置：

例如提问：先用 Doc2Dev 查询文档，使用elasticsearch-rs 编写代码和 elasticsearch 进行交互，创建一个索引。可以看到系统首先会查询相关代码库，由于存在多个代码库，需要先根据具体关键字查找相关内容，然后选择某个相关内容询问对应问题，最后得到相应代码片段提示。 演示：