🧠 SuiAgentic

SuiAgentic — это приложение на основе FastAPI для встраивания документов и семантического поиска, работающее на базе векторной базы данных Qdrant. Оно позволяет преобразовывать документы (из URL-адресов или локальных файлов) в встраивания, эффективно хранить их и извлекать релевантный контент с помощью запросов на естественном языке. Оно разработано для поддержки инструментов с улучшенным ИИ, таких как Cursor, Copilot, Claude и других клиентов, совместимых с MCP.

💡 Почему SuiAgentic? Многим организациям необходимо интегрировать контекст из внутренних документов (например, PRD, спецификации дизайна, вики) в инструменты, используемые разработчиками и работниками знаний. Однако консолидация документов из различных источников в централизованную, доступную для поиска базу знаний сложна и фрагментирована.

SuiAgentic решает эту проблему, предоставляя централизованный контекстный сервер, который принимает, разделяет, встраивает и индексирует ваш контент, делая его доступным через простой REST API и веб-интерфейс. Он также поддерживает использование в качестве сервера MCP для агентов ИИ.

🚀 Основные функции Встраивание документов: извлекает содержимое из URL-адресов (с аутентификацией или без нее), разбивает его на части, генерирует встраивания и сохраняет их в Qdrant.

Семантический поиск: выполняйте запросы к своей базе знаний на естественном языке и извлекайте соответствующие фрагменты или документы.

Веб-интерфейс: простой в использовании веб-интерфейс для встраивания и поиска.

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 (Векторная БД)

Использование Докера:

docker run -p 6333:6333 qdrant/qdrant

Или с помощью вспомогательного скрипта:

./runqdrant.sh

Запустите приложение Agentic

uvicorn app.main:app --reload
# or:
python run.py

Посетите http://localhost:8000

🌐 Веб-интерфейс и API

Веб-интерфейс:

/ - Дом
/embed — Встраивание документов через пользовательский интерфейс
/retrieve — Интерфейс семантического поиска

🔍 Опубликовать /извлечь

{
  "query": "What is the architecture of Sui?",
  "top_k": 5,
  "group_by_doc": true
}

🌍 Встраивание из URL-адресов

Публичные URL-адреса:

Просто укажите URL-адрес через API или пользовательский интерфейс — аутентификация не требуется.

🤖 Использование в качестве 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

Предпосылки

Питон 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
Отслеживайте метаданные для каждого документа

Аргументы командной строки

upload_folder.py

folder - Путь к папке, содержащей PDF-файлы.
--prefix — Префикс для добавления к именам документов

upload_documents.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