Skip to main content
Glama

🧠 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 等)一起使用。

身份验证支持:支持受保护文档的基本身份验证和承载令牌。

⚙️ 快速入门

  1. 克隆存储库

git clone https://github.com/AnhQuan2004/mcp_agent.git
cd mcp_agent
  1. 设置 Python 环境

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
  1. 安装依赖项

pip install -r requirements.txt
  1. 创建 .env 文件(或使用提供的 .env.example)

QDRANT_URL=localhost
QDRANT_PORT=6333
QDRANT_COLLECTION_NAME=documents
  1. 启动 Qdrant(向量 DB)

使用 Docker:

docker run -p 6333:6333 qdrant/qdrant

或者使用帮助脚本:

./runqdrant.sh
  1. 运行 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 数据库的工具。

可用工具

  1. upload_folder.py - 一个从文件夹上传 PDF 文件的简单脚本

  2. upload_documents.py - 一个用于上传 PDF、DOCX 和 TXT 文件的高级脚本,具有更多选项

Related MCP server: Qdrant 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

这些工具的作用

  1. 在指定文件夹中查找支持的文档

  2. 从每个文档中提取文本内容

  3. 将文本拆分成可管理的块

  4. 为每个块生成 3072 维嵌入

  5. 在 Qdrant 中存储块和嵌入

  6. 跟踪每个文档的元数据

命令行参数

上传文件夹.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 授权。

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    C
    maintenance
    Enables semantic search and document management using a local Qdrant vector database with OpenAI embeddings. Supports natural language queries, metadata filtering, and collection management for AI-powered document retrieval.
    70 npm
    37
    MIT