🧠 SuiAgentic
SuiAgentic 是一款基于 FastAPI 的文档嵌入和语义检索应用程序，由 Qdrant 矢量数据库提供支持。它支持您将文档（来自 URL 或本地文件）转换为嵌入，高效存储，并使用自然语言查询检索相关内容。它旨在支持 AI 增强型工具，例如 Cursor、Copilot、Claude 以及其他兼容 MCP 的客户端。
💡 为什么选择 SuiAgentic？许多组织需要将内部文档（例如产品需求文档 (PRD)、设计规范、Wiki）中的上下文集成到开发人员和知识工作者使用的工具中。然而，将来自不同来源的文档整合到一个集中式、可搜索的知识库中既复杂又分散。
SuiAgentic 通过提供一个集中式上下文服务器来解决这个问题，该服务器可以提取、分块、嵌入和索引您的内容，并通过简单的 REST API 和 Web 界面访问。它还支持用作 AI 代理的 MCP 服务器。
🚀 主要功能文档嵌入：从 URL 中提取内容（无论是否经过身份验证），将其拆分成块，生成嵌入，然后将其存储在 Qdrant 中。
语义搜索：使用自然语言查询您的知识库并检索相关的块或文档。
Web UI：易于使用的嵌入和搜索 Web 界面。
REST API：可通过 HTTP 端点完全访问，以实现自动化或集成。
MCP 服务器就绪：与 MCP 兼容的客户端（如 Cursor、Copilot、Claude 等）一起使用。
身份验证支持：支持受保护文档的基本身份验证和承载令牌。
⚙️ 快速入门
- 克隆存储库
git clone https://github.com/AnhQuan2004/mcp_agent.git
cd mcp_agent
- 设置 Python 环境
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
- 安装依赖项
pip install -r requirements.txt
- 创建 .env 文件（或使用提供的 .env.example）
QDRANT_URL=localhost
QDRANT_PORT=6333
QDRANT_COLLECTION_NAME=documents
- 启动 Qdrant（向量 DB）
使用 Docker：
docker run -p 6333:6333 qdrant/qdrant
或者使用帮助脚本：
- 运行 Agentic 应用程序
uvicorn app.main:app --reload
# or:
python run.py
访问http://localhost:8000
🌐 Web 界面和 API
Web 用户界面：
- / - 家
- /embed — 通过 UI 嵌入文档
- /retrieve——语义搜索UI
🔍 POST /检索
{
"query": "What is the architecture of Sui?",
"top_k": 5,
"group_by_doc": true
}
🌍 从 URL 嵌入
公共 URL：
- 只需通过 API 或 UI 提供 URL — 无需身份验证。
🤖 用作 MCP 服务器
要使用 sui 作为 MCP 服务器：
{
"mcpServers": {
"suiAgentic": {
"url": "http://localhost:8000/mcp"
}
}
}
文档上传工具
该目录包含将文档批量上传到您的 SuiAgentic Qdrant 数据库的工具。
可用工具
upload_folder.py - 一个从文件夹上传 PDF 文件的简单脚本upload_documents.py - 一个用于上传 PDF、DOCX 和 TXT 文件的高级脚本，具有更多选项
先决条件
- Python 3.8+
- SuiAgentic 应用程序已安装并配置
- Qdrant 服务器在本地运行或可通过网络访问
- 安装所需的依赖项（PyPDF2、python-docx）
基本用法
从文件夹上传 PDF 文件
# Upload all PDFs from a folder
python upload_folder.py /path/to/pdf/folder
# Upload with a prefix (useful for categorizing documents)
python upload_folder.py /path/to/pdf/folder --prefix "Research Papers"
高级文档上传
# Upload all supported documents from a folder and subfolders
python upload_documents.py /path/to/documents --recursive
# Add metadata tags to all documents
python upload_documents.py /path/to/documents --tag category=research --tag project=alpha
# Specify collection name (if not using default)
python upload_documents.py /path/to/documents --collection my_collection
# Complete example with all options
python upload_documents.py /path/to/documents --recursive --prefix "Project X" --tag department=marketing --tag status=final
这些工具的作用
- 在指定文件夹中查找支持的文档
- 从每个文档中提取文本内容
- 将文本拆分成可管理的块
- 为每个块生成 3072 维嵌入
- 在 Qdrant 中存储块和嵌入
- 跟踪每个文档的元数据
命令行参数
上传文件夹.py
folder - 包含 PDF 文件的文件夹路径--prefix - 添加到文档名称的前缀
上传文档.py
folder - 包含文档的文件夹路径--prefix - 添加到文档名称的前缀--recursive - 在子文件夹中递归搜索文件--collection - 要使用的 Qdrant 集合的名称--tag - 向文档添加元数据标签（可多次使用： --tag key=value ）
示例
按项目组织文档
python upload_documents.py /path/to/projects/project1 --recursive --prefix "Project 1" --tag project=alpha
python upload_documents.py /path/to/projects/project2 --recursive --prefix "Project 2" --tag project=beta
对文档进行分类
python upload_documents.py /path/to/contracts --prefix "Legal" --tag department=legal --tag confidential=true
python upload_documents.py /path/to/manuals --prefix "Technical" --tag department=engineering
故障排除
- 如果遇到大型文档的内存错误，请尝试将其拆分为较小的文件
- 对于大量文档，请考虑以较小的批次进行处理
- 检查日志输出以查找处理过程中的任何错误
🪪 许可证
根据 Apache License 2.0 授权。