DeepWiki-Open：为GitHub、GitLab仓库自动生成AI文档

综合介绍

DeepWiki-Open 是一个开源项目，专为 GitHub、GitLab 和 Bitbucket 的代码仓库自动生成结构化文档。它利用 AI 技术分析代码结构、文件内容和逻辑关系，快速生成类似维基百科的知识库页面。用户只需输入仓库 URL，即可获得代码架构、功能模块和实现细节的清晰说明。项目支持本地部署，数据存储在本地，保障隐私安全。它还提供检索增强生成（RAG）功能，允许用户与代码库进行上下文问答，并通过 DeepResearch 功能深入研究复杂问题。DeepWiki-Open 由 AsyncFuncAI 开发，免费开源，适合开发者、团队和开源社区使用，帮助快速理解复杂代码。

功能列表

• 自动生成文档：分析 GitHub、GitLab 或 Bitbucket 仓库，生成结构化的维基式文档。
• 代码智能分析：识别代码结构、关键模块和文件关系，提供清晰说明。
• 上下文问答：通过 RAG 技术，支持用户提出仓库相关问题并获取精准回答。
• DeepResearch 功能：支持多轮研究，深入分析复杂问题，提供详细结论。
• 本地部署支持：数据存储在本地，无需云端服务，保障数据隐私。
• 交互式图表：生成 Mermaid 格式的架构图和流程图，直观展示代码逻辑。
• 多平台支持：兼容 GitHub、GitLab 和 Bitbucket，支持公开和私有仓库。
• 流式 AI 响应：通过 Google Gemini 模型提供实时文档生成和问答。
• 开源免费：完全开源，用户可自由修改和扩展功能。

使用帮助

安装流程

DeepWiki-Open 支持 Docker 和手动安装，适合 Ubuntu、macOS 或 Windows（通过 WSL2）。以下是详细步骤。

1. 克隆仓库

克隆 DeepWiki-Open 的代码库到本地：

git clone https://github.com/AsyncFuncAI/deepwiki-open.git
cd deepwiki-open

2. 配置环境变量

DeepWiki-Open 需要 Google Gemini 和 OpenAI 的 API 密钥，用于文档生成和代码嵌入。在项目根目录创建 .env 文件：

echo "GOOGLE_API_KEY=your_google_api_key" > .env
echo "OPENAI_API_KEY=your_openai_api_key" >> .env

• GOOGLE_API_KEY：从 Google AI Studio 获取，用于 Google Gemini 模型。
• OPENAI_API_KEY：从 OpenAI Platform 获取，用于生成代码嵌入。
• 可选变量：
  • PORT：API 服务器端口，默认 8001。
  • NEXT_PUBLIC_SERVER_BASE_URL：API 服务器地址，默认 http://localhost:8001。

3. 使用 Docker 安装（推荐）

Docker 安装简单，适合快速部署。

• 确保安装 Docker 和 Docker Compose。
• 运行以下命令启动服务：

docker-compose up

• 或者拉取预构建镜像并运行：

docker pull ghcr.io/asyncfuncai/deepwiki-open:latest
docker run -p 8001:8001 -p 3000:3000 \
-e GOOGLE_API_KEY=your_google_api_key \
-e OPENAI_API_KEY=your_openai_api_key \
-v ~/.adalflow:/root/.adalflow \
ghcr.io/asyncfuncai/deepwiki-open:latest

• 服务启动后，API 运行在 http://localhost:8001，前端页面在 http://localhost:3000。
• 也可以挂载 .env 文件：

docker run -p 8001:8001 -p 3000:3000 \
-v $(pwd)/.env:/app/.env \
-v ~/.adalflow:/root/.adalflow \
ghcr.io/asyncfuncai/deepwiki-open:latest

4. 手动安装

如果不使用 Docker，可手动安装。

• 安装 Python 依赖（后端）：

pip install -r api/requirements.txt

• 启动 API 服务：

python -m api.main

• 安装 JavaScript 依赖（前端）：

npm install

• 启动前端开发服务器：

npm run dev

• 前端页面在 http://localhost:3000。

5. 验证安装

• 打开浏览器，访问 http://localhost:3000。
• 输入仓库 URL（如 https://github.com/facebook/react 或 https://bitbucket.org/redradish/atlassian_app_versions）。
• 点击“Generate Wiki”，查看生成的文档。

主要功能操作

自动生成文档

1. 在前端页面输入仓库 URL（如 https://gitlab.com/gitlab-org/gitlab）。
2. 对于私有仓库，点击“+ Add access tokens”，输入 GitHub、GitLab 或 Bitbucket 的个人访问令牌。
3. 点击“Generate Wiki”，系统克隆仓库并分析代码，生成文档。
4. 生成的文档包括：
   • 代码架构概述。
   • 关键模块的功能说明。
   • 文件和目录的详细描述。
   • 交互式 Mermaid 架构图和流程图。

上下文问答（Ask 功能）

1. 在文档页面找到“Ask”区域。
2. 输入问题，如“这个仓库的数据库连接如何实现？”。
3. 系统通过 RAG 技术检索代码片段，生成上下文相关的回答。
4. 回答以流式方式显示，支持实时交互。

DeepResearch 功能

1. 在“Ask”界面启用“Deep Research”开关。
2. 输入复杂问题，如“这个仓库的认证流程如何优化？”。
3. 系统执行多轮研究：
   • 研究计划 ：生成初始分析框架。
   • 研究更新 ：迭代分析，补充细节。
   • 最终结论 ：综合所有信息，提供详细答案。
4. 研究过程最多迭代 5 次，回答以流式方式显示。

特色功能操作

流式 AI 响应

• 使用 Google Gemini 模型，文档生成和问答响应实时显示。
• 示例：输入问题后，回答逐段加载，减少等待时间。

交互式 Mermaid 图表

• 系统生成仓库的架构图和流程图，基于 Mermaid 技术。
• 图表支持放大、拖动和点击交互。
• 示例：生成 TensorFlow 仓库文档后，可查看模型训练流程图。

支持私有仓库

• 需提供 GitHub、GitLab 或 Bitbucket 的个人访问令牌。
• 令牌仅用于克隆仓库，不存储在服务器。
• 示例：输入私有仓库 URL 和令牌后，可生成文档。

本地数据存储

• 文档和分析数据存储在 ~/.adalflow 目录（Docker 可自定义挂载）。
• 无云端依赖，适合隐私敏感场景。

项目结构

DeepWiki-Open 的代码结构如下：

deepwiki/
├── api/                  # 后端 API 服务器
│   ├── main.py           # API 入口
│   ├── api.py            # FastAPI 实现
│   ├── rag.py            # RAG 功能实现
│   ├── data_pipeline.py  # 数据处理工具
│   └── requirements.txt  # Python 依赖
├── src/                  # 前端 Next.js 应用
│   ├── app/              # Next.js 页面
│   │   └── page.tsx      # 主页面
│   └── components/       # React 组件
│       └── Mermaid.tsx   # Mermaid 图表渲染
├── public/               # 静态资源
├── package.json          # JavaScript 依赖
└── .env                  # 环境变量

注意事项

• 确保 API 密钥有效，无效密钥会导致生成失败。
• Docker 部署建议分配 4GB 以上内存。
• 手动安装需 Python 3.8+ 和 Node.js 16+。
• 大型仓库可能需要更长时间生成文档，建议从小仓库开始测试。
• 如果遇到 CORS 错误，确保前后端在同一机器运行，或调整 NEXT_PUBLIC_SERVER_BASE_URL。

应用场景

1. 新开发者快速上手
   新开发者可生成项目文档，快速了解代码结构和模块功能，缩短学习曲线。
2. 开源项目贡献
   贡献者通过文档和问答功能，快速掌握仓库逻辑，提高代码提交效率。
3. 企业内部文档维护
   企业部署 DeepWiki-Open 为私有仓库生成文档，减少手动维护成本。
4. 技术面试准备
   求职者分析目标公司的开源仓库，生成文档后通过 DeepResearch 深入研究技术细节。
5. 教育和学习
   学生使用 DeepWiki-Open 分析知名项目（如 React、Django），通过图表和问答学习代码设计。

QA

1. DeepWiki-Open 是否免费？
   DeepWiki-Open 完全免费开源，但需用户提供 Google 和 OpenAI 的 API 密钥，API 使用可能产生费用。
2. 支持哪些代码托管平台？
   支持 GitHub、GitLab 和 Bitbucket，覆盖公开和私有仓库。
3. 如何导出生成的文档？
   文档存储在本地 ~/.adalflow，可手动复制为 Markdown 或其他格式。
4. DeepResearch 和 Ask 功能有何不同？
   Ask 提供单次上下文问答，DeepResearch 通过多轮迭代深入研究复杂问题。
5. 如果生成文档失败怎么办？
   检查 API 密钥、仓库 URL 格式，或尝试小型仓库；查看终端日志获取错误详情。