内容
# 🚀 **WebNexus: 高级网页爬虫与 RAG 系统**
*一个强大、独立的网页爬虫和文档搜索系统，具备最先进的 AI 能力*
[](https://www.python.org/downloads/)
[](https://fastapi.tiangolo.com/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io/)
## 🎯 **什么是 WebNexus？**
WebNexus 是一个**强大、开源的网页爬虫和 RAG 系统**，设计用于**智能文档发现和语义搜索**。它将最先进的 AI 模型与本地存储相结合，创建一个复杂的检索增强生成系统，该系统完全在您的机器上运行。
### **🏆 为什么选择 WebNexus？**
✅ **100% 开源** - 无需 API 密钥或云依赖
✅ **最先进的搜索** - 高级混合搜索，具备关键词提取和重新排序
✅ **本地和私有** - 所有数据都存储在您的机器上
✅ **AI 代理就绪** - 完全支持 MCP（模型上下文协议）
✅ **生产就绪** - FastAPI 服务器，具备全面的文档
✅ **技术内容优化** - 适用于文档、代码仓库和教程
---
## 🧠 **核心技术及原因**
### **🔍 高级搜索管道**
- **Stella EN 400M v5 嵌入式模型** - 最先进的 1024 维向量，用于语义搜索
- **FAISS 向量数据库** - 闪电般快速的相似性搜索（比 pgvector 更快）
- **增强的 BM25 关键词搜索** - 复杂的分词，包含 400 多个技术术语
- **混合搜索融合** - 结合向量相似性 + 关键词匹配 + 高级重新排序
- **智能查询扩展** - 自动添加复数、变体和相关术语
### **🕷️ 多策略网页爬虫**
- **Crawl4AI 集成** - 现代异步网页爬虫，支持 JavaScript
- **4 种爬虫策略**：单页、批量、递归和 XML 站点地图
- **智能内容提取** - 保留代码块，维护结构
- **速率限制和尊重** - 遵循 robots.txt，可配置延迟
### **🗄️ 本地优先架构**
- **SQLite 数据库** - 轻量级、可靠，无需服务器
- **FAISS 向量存储** - 优化搜索性能
- **原始 Archon 分块** - 5000 字符块，智能边界
- **零云依赖** - 所有内容都在本地运行
### **🤖 AI 代理集成**
- **MCP 服务器** - 完整的模型上下文协议支持
- **3 种生产就绪工具** - 爬虫、搜索和源管理
- **JSON 格式响应** - 适用于 AI 代理和自动化
---
## 📦 **快速入门安装**
### **前提条件**
- **Python 3.12+** （推荐）或 Python 3.10+
- **8GB+ RAM** （用于嵌入式模型）
- **2GB+ 磁盘空间** （用于模型和数据）
### **1. 克隆和设置**
```bash
git clone <仓库 URL>
cd WebNexus
# 使用 uv 安装（推荐）
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync
# 或使用 pip
pip install -e .
```
### **2. 初始化数据库和下载模型**
```bash
# 一次性设置（下载约 800MB Stella 模型）
uv run python scripts/setup_db.py
```
### **3. 启动服务**
#### **选项 A：使用启动脚本（推荐）**
```bash
uv run python scripts/run_servers.py
```
#### **选项 B：手动启动**
```bash
# 终端 1：FastAPI 服务器
uv run uvicorn src.api.main:app --reload --port 8000
# 终端 2：MCP 服务器（用于 AI 代理）
uv run python src.mcp.server.py --stdio
```
### **4. 验证安装**
```bash
# 检查 FastAPI 服务器
curl http://localhost:8000/health
# 查看交互式 API 文档
open http://localhost:8000/docs
```
---
## 🌐 **FastAPI REST API 端点**
WebNexus 提供用于所有操作的综合 REST API：
### **🕷️ 爬虫端点**
#### **单页爬虫**
```http
POST /api/crawl/single
Content-Type: application/json
{
"url": "https://python.langchain.com/docs/introduction/",
"store_documents": true
}
```
**响应：**
```json
{
"success": true,
"session_id": "single_crawl_20250131_143052",
"message": "成功爬取并存储 1 个文档",
"documents_stored": 1,
"metadata": {
"url": "https://python.langchain.com/docs/introduction/",
"title": "LangChain 介绍",
"content_length": 15420,
"chunks_created": 4
}
}
```
#### **批量爬虫**
```http
POST /api/crawl/batch
Content-Type: application/json
{
"urls": [
"https://python.langchain.com/docs/introduction/",
"https://python.langchain.com/docs/concepts/",
"https://python.langchain.com/docs/tutorials/"
],
"max_concurrent": 3,
"store_documents": true
}
```
#### **进度监控**
```http
# 获取爬虫状态
GET /api/crawl/status/{session_id}
# 列出活动爬虫
GET /api/crawl/active
# 取消正在运行的爬虫
POST /api/crawl/cancel/{session_id}
```
### **🔍 搜索端点**
#### **高级混合搜索**
```http
POST /api/search/query
Content-Type: application/json
{
"query": "LangChain 向量存储和嵌入",
"top_k": 10,
"search_type": "hybrid",
"vector_weight": 0.7,
"keyword_weight": 0.3,
"use_reranking": true,
"rerank_strategy": "hybrid"
}
```
**响应：**
```json
{
"success": true,
"results": [
{
"document_id": "doc_123",
"chunk_id": "chunk_456",
"title": "LangChain 向量存储指南",
"content": "LangChain 提供向量存储以进行嵌入存储和检索...",
"url": "https://python.langchain.com/docs/modules/data_connection/vectorstores/",
"similarity_score": 0.92,
"keyword_score": 0.85,
"combined_score": 0.89,
"metadata": {"source_type": "网页"},
"source_type": "网页"
}
],
"total_results": 8,
"query": "LangChain 向量存储和嵌入",
"search_time_ms": 245.7,
"search_strategy": "hybrid+hybrid_rerank"
}
```
#### **简单搜索**
```http
GET /api/search/simple?q=machine+learning&limit=5&type=vector
```
#### **文档特定搜索**
```http
POST /api/search/document
Content-Type: application/json
{
"document_id": "doc_123",
"query": "向量数据库实现",
"max_chunks": 5
}
```
### **📚 文档管理**
#### **列出文档**
```http
GET /api/search/documents?limit=50&url_pattern=langchain.com
```
#### **搜索统计**
```http
GET /api/search/stats
```
**响应：**
```json
{
"total_documents": 156,
"total_chunks": 847,
"total_embeddings": 847,
"vector_index_size": 847,
"embedding_dimension": 1024,
"available_source_types": ["网页", "PDF", "Markdown"],
"recent_crawls": 23,
"search_performance": {
"avg_search_time_ms": 180.5,
"total_searches": 1247
}
}
```
### **⚡ 系统端点**
```http
GET /health # 健康检查与服务状态
GET /api/stats # 综合系统统计
GET /docs # 交互式 API 文档（Swagger UI）
GET /redoc # 替代 API 文档（ReDoc）
```
---
## 🤖 **与 Claude Desktop 的 MCP 集成**
WebNexus 包括完整的**模型上下文协议（MCP）**支持，允许像 Claude 这样的 AI 代理直接爬取网站和搜索文档。
### **🔧 使用 Claude Desktop 设置 MCP**
#### **1. 安装 Claude Desktop**
从以下网址下载：https://claude.ai/download
#### **2. 配置 MCP 服务器**
**适用于 macOS/Linux：**
```bash
# 编辑 Claude Desktop 配置
code ~/.claude-desktop/claude_desktop_config.json
```
**适用于 Windows：**
```bash
# 编辑 Claude Desktop 配置
notepad "%APPDATA%\Claude\claude_desktop_config.json"
```
#### **3. 添加 WebNexus MCP 配置**
```json
{
"mcpServers": {
"WebNexus": {
"command": "uv",
"args": [
"run",
"python",
"/path/to/WebNexus/webnexus/mcp/server.py"
],
"cwd": "/path/to/WebNexus"
}
}
}
```
**替换 `/path/to/WebNexus` 为您的实际项目路径。**
#### **4. 重新启动 Claude Desktop**
关闭并重新打开 Claude Desktop 以加载 MCP 服务器。
### **🛠️ 可用的 MCP 工具**
配置完成后，Claude Desktop 将可以访问这些工具：
#### **1. `crawl_website` - 多策略网页爬虫**
```python
# Claude 可以使用此工具爬取网站
crawl_website(
url="https://python.langchain.com/docs/",
strategy="recursive", # single_page, batch, recursive, sitemap
max_depth=2,
max_pages=20,
store_documents=True
)
```
#### **2. `search_documents` - 高级 RAG 搜索**
```python
# Claude 可以搜索爬取的文档
search_documents(
query="LangChain 向量存储实现",
max_results=10,
search_type="hybrid", # vector, keyword, or hybrid
use_reranking=True, # 应用高级重新排序
similarity_threshold=0.1 # 最小相关性分数
)
```
#### **3. `get_sources` - 文档源管理**
```python
# Claude 可以浏览可用的文档源
get_sources(
limit=25,
url_pattern="langchain.com", # 按 URL 模式过滤
source_type="网页" # 按内容类型过滤
)
```
### **🎯 Claude 交互示例**
一旦配置了 MCP，您可以问 Claude：
> **"请爬取 LangChain 文档，然后搜索有关向量存储的信息"**
Claude 将：
1. 使用 `crawl_website` 爬取 LangChain 文档
2. 使用 `search_documents` 查找有关向量存储的相关信息
3. 提供基于爬取内容的综合答案
> **"我们有哪些可用的编程教程？搜索 Python 示例。"
Claude 将：
1. 使用 `get_sources` 列出可用文档
2. 使用 `search_documents` 查找 Python 相关内容
3. 总结可用资源
---
## 🔍 **高级搜索功能**
### **🧠 增强的关键词提取**
WebNexus 使用复杂的关键词提取，比简单的分词效果更好：
**之前（简单分词）：**
```
查询： "machine learning model deployment best practices"
Tokens: ["machine", "learning", "model", "deployment", "best", "practices"]
```
**之后（增强提取）：```
查询： "machine learning model deployment best practices"
Keywords: ["deployment", "machine", "learning", "production", "best", "model", "best_practices"]
Search Terms: ["deployment", "deployments", "machine", "machines", "learning", "learnings", "production", "productions", "best", "model", "models", "best_practices"]
```
**性能改进：2-3 倍更好的 BM25 分数，93.8% 技术术语保留率**
### 🔗 **混合搜索策略**
#### **向量搜索** - 语义理解
- 使用 Stella EN 400M v5 嵌入式模型（1024 维度）
- 理解上下文和含义
- 适用于概念查询
#### **关键词搜索** - 精确术语匹配
- 增强的 BM25 技术术语保留
- 处理特定术语和代码
- 适用于精确查找
#### **混合融合** - 两全其美
- 结合向量相似性 + 关键词相关性
- 可配置的权重（默认：70% 向量，30% 关键词）
- 高级重新排序以改善结果
### 🎯 **重新排序策略**
1. **BM25 重新排序** - 纯关键词相关性优化
2. **混合重新排序** - 结合分数 + 查询覆盖 + 内容质量
3. **质量重新排序** - 关注内容完整性和结构
---
## 🏗️ **架构概述```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ MCP 服务器 │◄──►│ FastAPI 服务器 │◄──►│ SQLite + FAISS │
│ （端口 8051） │ │ （端口 8000） │ │ 数据库 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
AI 工具 REST API 端点 本地数据存储
- `crawl_website - /api/crawl/* - 文档元数据
- `search_documents - /api/search/* - 向量嵌入
- `get_sources - /health, /docs - FAISS 索引
```
### **📊 数据库架构**
**SQLite 表：
- **documents** - 文档元数据和内容
- **document_chunks** - 分块内容用于 RAG
- **embeddings** - 向量嵌入元数据
- **code_examples** - 提取的代码块
- **crawl_sessions** - 爬取进度跟踪
**FAISS 索引：
- **文档向量** - 语义搜索索引
- **代码向量** - 专门的代码搜索
- **持久存储** - 自动索引保存/加载
---
## ⚙️ **配置和自定义### **环境变量
```bash
# 核心配置
EMBEDDING_MODEL="dunzhang/stella_en_400M_v5"
CHUNKING_STRATEGY="original" # original, advanced, specialized
ORIGINAL_CHUNK_SIZE=5000
ADVANCED_CHUNK_SIZE=1000
# 数据库配置
DATABASE_URL="sqlite:///./data/WebNexus.db"
VECTOR_INDEX_PATH="./data/vectors/faiss_index.bin"
# 性能设置
MAX_CONCURRENT_CRAWLS=10
CRAWL_TIMEOUT=30
EMBEDDING_BATCH_SIZE=32
```
### **分块策略**
#### **原始 Archon（默认）**
- 5000 字符块，无重叠
- 智能边界检测（代码块、段落、句子）
- 优化与原始 Archon 兼容
#### **高级自定义**
- 1000 字符块，100 字符重叠
- 增强的语义边界检测
- 适用于密集技术内容的最佳效果
#### **专业化**
- 针对不同文件类型的基于内容的分块
- 语言特定的代码块边界
- 适用于混合文档和代码的最佳效果
---
## 📈 **性能和基准**
### **搜索性能**
- **向量搜索**：10k 文档约 200ms
- **混合搜索**：带有重新排序功能约 400ms
- **内存使用量**：嵌入式模型峰值约 4GB
- **存储**：每 1000 个爬取页面约 75MB
### **爬取性能**
- **单页**：每页约 2-5 秒
- **批量爬取**：每秒 5-10 页，延迟适当
- **递归**：尊重速率限制，可配置深度
- **成功率**：标准网站 >95%
### **嵌入性能**
- **Stella EN 400M v5**：13.7 文档/秒（CPU），50+ 文档/秒（GPU）
- **FAISS 索引**：1000 个向量约 50ms
- **索引加载**：<2 秒 10k 文档
---
## 🎨 **使用案例和示例**
### **📚 文档爬取和搜索**
适用于创建可搜索的知识库：
- API 文档（OpenAPI，REST 文档）
- 框架文档（React，Vue，Django）
- 技术教程和指南
- GitHub 仓库文档
### **🔬 研究和分析**
- 学术论文仓库
- 技术博客聚合
- 行业报告集合
- 竞争分析数据集
### **🤖 AI 代理增强**
- 为 Claude 提供特定领域的知识
- 创建上下文感知编码助手
- 构建专业问答系统
- 启用自主研究能力
### **💼 企业应用**
- 内部文档搜索
- 合规文档管理
- 培训材料组织
- 知识库创建
---
## 🔒 **隐私和安全**
### **本地优先设计**
- **无云依赖** - 所有内容都在本地运行
- **无需 API 密钥** - 使用开源模型
- **完全数据控制** - 您拥有所有爬取的内容
- **离线能力** - 无需互联网（模型下载后）
- **数据安全** - 加密存储
### **安全功能**
- **Robots.txt 合规** - 尊重网站爬取政策
- **速率限制** - 防止服务器超载
- **URL 验证** - 防止恶意请求
- **安全存储** - SQLite 具有适当权限
---
## 🛠️ **开发和贡献**
### **开发设置**
```bash
# 克隆仓库
git clone <仓库 URL>
cd WebNexus
# 安装开发依赖
uv sync --dev
# 运行测试
uv run python tests/test_langchain_pipeline.py
# 代码格式化
uv run black webnexus/
uv run isort webnexus/
# 类型检查
uv run mypy webnexus/
```
### **项目结构**
```
WebNexus/
├── webnexus/
│ ├── api/ # FastAPI 应用程序
│ ├── mcp/ # MCP 服务器实现
│ ├── models/ # 数据库模型
│ ├── services/ # 核心业务逻辑
│ ├── utils/ # 实用函数
│ └── config/ # 配置管理
├── tests/ # 测试套件
├── scripts/ # 设置和管理脚本
├── data/ # 数据库和向量存储
└── docs/ # 文档
```
### **添加新功能**
1. **新的爬虫策略** - 扩展 `CrawlingService`
2. **搜索改进** - 增强 `SearchService` 或 `RerankingService`
3. **MCP 工具** - 在 `mcp/server.py` 中添加新工具
4. **API 端点** - 在 `api/` 中创建新路由器
---
## 📞 **支持和社区**
### **获取帮助**
- **文档**：查看 `/docs` 端点获取 API 参考
- **问题**：在 GitHub 上报告错误和功能请求
- **讨论**：加入社区讨论获取帮助和想法
### **常见问题和解决方案**
#### **模型下载失败**
```bash
# 清除缓存并重试
rm -rf ~/.cache/huggingface/
uv run python scripts/setup_db.py
```
#### **内存问题**
```bash
# 使用 CPU 模式
export FORCE_CPU=true
uv run python scripts/setup_db.py
```
#### **端口冲突**
```bash
# 使用不同端口
uv run uvicorn src.api.main:app --port 8001
```
---
## 📄 **许可证和致谢**
### **许可证**
本项目根据 **MIT 许可证**授权 - 参见 [LICENSE](LICENSE) 文件获取详细信息。
### **致谢和认可**
- **Crawl4AI** - 现代网页爬虫功能
- **Stella EN 400M v5** - 由 dunzhang 提供的高级嵌入式模型
- **FAISS** - Facebook AI 的高效向量相似性搜索
- **FastAPI** - 现代、快速的 Web 框架
- **模型上下文协议** - AI 代理集成标准
### **第三方模型**
- **Stella EN 400M v5**：MIT 许可证（dunzhang/stella_en_400M_v5）
- **Sentence Transformers**：Apache 2.0 许可证
- **FAISS**：MIT 许可证
---
## 🎯 **接下来是什么？**
WebNexus 正在积极开发中，计划中的功能包括：
### 🚀 **即将推出的功能**
- **递归爬虫改进** - 更好的深度控制和过滤
- **支持更多文件格式** - PDF、DOCX、TXT 处理
- **高级分析** - 搜索分析和文档洞察
- **性能优化** - GPU 加速、缓存改进
- **UI 仪表盘** - 基于 Web 的管理界面
### 🤝 **贡献**
我们欢迎贡献！需要帮助的领域：
- 性能优化
- 额外的爬虫策略
- UI/UX 改进
- 文档增强
- 测试覆盖率扩展
**🎉 准备开始了吗？运行 `uv run python scripts/setup_db.py`，使用最先进的 AI 搜索功能开始爬取网络！**
---
*由 WebNexus 社区构建 ❤️。将您的网页内容转化为智能、可搜索的知识库。*
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器