🧠 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

或者使用帮助脚本：

./runqdrant.sh

运行 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 文件的高级脚本，具有更多选项

Related MCP server: RagDocs MCP Server

先决条件

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 授权。

SuiAgentic