🔭 Сервер поиска EOSC Data Commons

Сервер для сервиса MatchMaker проекта EOSC Data Commons, обеспечивающий поиск по открытым наборам данных на естественном языке. Он предоставляет HTTP-эндпоинт и поддерживает Model Context Protocol (MCP), помогая пользователям находить наборы данных и инструменты с помощью поиска на основе больших языковых моделей.

🧩 Эндпоинты

HTTP API включает 2 основных эндпоинта:

• /mcp: MCP-сервер, который ищет релевантные данные для ответа на вопрос пользователя с помощью сервиса OpenSearch проекта EOSC Data Commons

  • Использует транспорт Streamable HTTP

  • Доступные инструменты:

    • Поиск наборов данных

    • Получение метаданных файлов в наборе данных (имя, описание, тип файлов)

    • Поиск инструментов

    • Поиск цитирований, связанных с наборами данных или инструментами

• /chat: HTTP POST эндпоинт (JSON) для общения с инструментами MCP-сервера через LLM-провайдера (ключ API передаётся через переменную окружения при развёртывании)

  • Потоковая передача ответов в формате Server-Sent Events в соответствии с протоколом AG-UI.

[!TIP]

Его также можно использовать просто как MCP-сервер через пакет pip.

Related MCP server: Datos.gob.es-MCP

🔌 Подключение к MCP-серверу

Систему можно использовать напрямую как MCP-сервер, используя либо STDIO, либо транспорт Streamable HTTP.

[!WARNING]

Для работы MCP-сервера потребуется доступ к предварительно проиндексированному экземпляру OpenSearch.

Следуйте инструкциям вашего клиента и используйте URL /mcp публичного сервера: https://matchmaker.eosc-data-commons.eu/api/search/mcp

Чтобы добавить новый MCP-сервер в VSCode GitHub Copilot:

• Откройте палитру команд (ctrl+shift+p или cmd+shift+p)

• Найдите MCP: Add Server...

• Выберите HTTP и укажите URL MCP-сервера: https://matchmaker.eosc-data-commons.eu/api/search/mcp

Ваш файл mcp.json в VSCode должен выглядеть так:

{
    "servers": {
        "data-commons-search-http": {
            "url": "https://matchmaker.eosc-data-commons.eu/api/search/mcp",
            "type": "http"
        }
    },
    "inputs": []
}

🛠️ Разработка

[!IMPORTANT]

Требования:

• uv — для удобной работы со скриптами и виртуальными окружениями

• docker — для развёртывания базы данных и сервиса OpenSearch

• Ключ API для LLM-провайдера: e-infra CZ, Mistral.ai или OpenRouter

📥 Установка зависимостей для разработки

uv sync --all-extras

Установите pre-commit хуки:

uv run --all-extras pre-commit install

Создайте файл keys.env с ключом(ами) API вашего LLM-провайдера и, при необходимости, другими настройками:

CESNET_API_KEY=YOUR_API_KEY
MISTRAL_API_KEY=YOUR_API_KEY

OIDC_CLIENT_ID=
OIDC_CLIENT_SECRET=
LANGFUSE_PUBLIC_KEY=
LANGFUSE_SECRET_KEY=
POSTGRES_HOST=localhost
POSTGRES_USER=app
POSTGRES_PASSWORD=app_password

RATE_LIMITING_ENABLED=False
LOG_LEVEL=DEBUG
LOG_JSON=false

OPENSEARCH_URL=http://localhost:9200

💾 База данных

Для хранения разговоров аутентифицированных пользователей системе требуется подключение к базе данных PostgreSQL.

Разверните и инициализируйте metadata-warehouse; в этих инструкциях предполагается, что папка metadata-warehouse находится рядом с папкой data-commons-search в одном каталоге.

cd ../metadata-warehouse
docker compose up postgres

Чтобы инициализировать базу данных, выполните из репозитория metadata-warehouse:

uv run --directory scripts/postgres_data create_db.py --db appdb --reset

[!IMPORTANT]

Для публично доступных сред рекомендуется обновить пароль пользователя app:

ALTER USER app WITH PASSWORD 'newpassword';

Сброс базы данных:

docker compose down --volumes --remove-orphans

Экспортируйте схему из db.py в metadata-warehouse (команда выполняется в корне репозитория data-commons-search):

uv run scripts/export_db_schema.py ../metadata-warehouse/scripts/postgres_data/create_sql/appdb/tables.sql

⚡️ Запуск dev-сервера

Запустите сервер в режиме разработки на http://localhost:8000, с MCP-эндпоинтом на http://localhost:8000/mcp, указывающим на запущенный экземпляр OpenSearch:

uv run --all-extras uvicorn src.data_commons_search.main:app --reload

По умолчанию OPENSEARCH_URL=http://localhost:9200

Настройка порта сервера через переменную окружения:

OPENSEARCH_URL=http://localhost:9200 SERVER_PORT=8001 uv run --all-extras uvicorn src.data_commons_search.main:app --host 0.0.0.0 --port 8001 --reload

[!NOTE]

Вы можете развернуть фронтенд matchmaker в режиме разработки, указав его на этот dev-сервер:

cd ../matchmaker
npm run dev

[!TIP]

Пример curl запроса:

curl -X POST http://localhost:8000/chat -H "Content-Type: application/json" \
	-d '{"items": [{"type": "message", "role": "user", "content": [{"text": "Educational datasets from Switzerland covering student assessments, language competencies, and learning outcomes, including experimental or longitudinal studies on pupils or students."}]}], "model": "cesnet/agentic"}'

С токеном доступа аутентифицированного пользователя из http://127.0.0.1:8000/auth/login:

curl -X POST http://localhost:8000/chat -H "Content-Type: application/json" \
-H "Cookie: access_token=$ACCESS_TOKEN" \
-d '{"items": [{"type": "message", "role": "user", "content": [{"text": "Educational datasets from Switzerland covering student assessments, language competencies, and learning outcomes, including experimental or longitudinal studies on pupils or students."}]}], "model": "cesnet/agentic"}'

Получить последний разговор:

curl -X GET "http://localhost:8000/conversation/$(curl -s http://localhost:8000/conversations -H "Content-Type: application/json" -H "Cookie: access_token=$ACCESS_TOKEN" | jq -r '.[-1].thread_id')" -H "Content-Type: application/json" -H "Cookie: access_token=$ACCESS_TOKEN"

Найти доступную модель у провайдера Cesnet:

curl -H "Authorization: Bearer $CESNET_API_KEY" https://llm.ai.e-infra.cz/v1/models | jq ".data[].id"

Рекомендуемая модель: cesnet/agentic

🔐 Хранилище секретов

EGI Secret Store, получите токен на aai.egi.eu/token (декодируйте JWT, чтобы получить фактический токен доступа)

export BASE="https://matchmaker.eosc-data-commons.eu"
curl -s "$BASE/auth/user" --cookie "access_token=$TOKEN"

curl -s -X PUT "$BASE/auth/keys/vip" --cookie "access_token=$TOKEN" \
  -H "Content-Type: application/json" -d '{"key_value":"sk-123"}'

curl -s "$BASE/auth/keys" --cookie "access_token=$TOKEN"
curl -s "$BASE/auth/keys/all" --cookie "access_token=$TOKEN"
curl -s "$BASE/auth/keys/vip" --cookie "access_token=$TOKEN"
curl -s -X DELETE "$BASE/auth/keys/vip" --cookie "access_token=$TOKEN"

🐳 Развёртывание с помощью Docker

Создайте файл keys.env с ключами API (см. полный пример выше):

CESNET_API_KEY=YOUR_API_KEY
MISTRAL_API_KEY=YOUR_API_KEY
SEARCH_API_KEY=SECRET_KEY_YOU_CAN_USE_IN_FRONTEND_TO_AVOID_SPAM

[!TIP]

SEARCH_API_KEY можно использовать для дополнительной защиты от ботов, которые могут отправлять запросы к LLM; если ключ не задан, для запросов к API ключ не потребуется.

Вы можете использовать готовый docker-образ ghcr.io/eosc-data-commons/data-commons-search:main

Пример файла compose.yml:

services:
  mcp:
    image: ghcr.io/eosc-data-commons/data-commons-search:main
    ports:
      - "127.0.0.1:8000:8000"
    environment:
      OPENSEARCH_URL: "http://opensearch:9200"
      CESNET_API_KEY: "${CESNET_API_KEY}"

Сборка и развёртывание сервиса:

docker compose up

📦 Сборка для продакшена

Сборка пакета в каталог dist/:

uv build

✅ Запуск тестов

[!CAUTION]

Перед запуском тестов необходимо сначала запустить сервер на порту 8000 (см. раздел «Запуск dev-сервера») и PostgreSQL.

uv run pytest

Запуск бенчмарка (проверка успешности выполнения набора поисковых запросов):

uv run tests/benchmark.py

Запуск тестов на устойчивость LLM к джейлбрейку с помощью garak:

PYTHONPATH=tests/security uv run garak --config tests/security/garak.yaml

Запуск стресс-тестов (20 одновременных обращений к API):

uv run tests/stress_api.py -c 20

🧹 Форматирование кода и проверка типов

uvx ruff format && uvx ruff check --fix && uvx ty check

♻️ Сброс окружения

Обновление uv:

uv self update

Очистка кэша uv:

uv cache clean

🔧 Обслуживание

Предварительный расчёт статистики для наборов данных в базе данных в файл src/data_commons_search/stats.json:

POSTGRES_DB=datasetdb uv run scripts/compute_stats.py

Обновление зависимостей в pyproject.toml:

uvx uv-bump

🏷️ Процесс релиза

Запустите скрипт релиза, указав тип изменения версии: fix, minor или major

.github/release.sh fix

Или укажите явную версию, например, для согласования с версией фронтенда:

.github/release.sh 0.10.0

Это создаст git-тег, релиз на GitHub и опубликует docker-образ

🤝 Благодарности

LLM-провайдер cesnet — это сервис, предоставляемый e-INFRA CZ и управляемый CERIT-SC Масарикова университета.

Вычислительные ресурсы были предоставлены проектом e-INFRA CZ (ID:90254), поддержанным Министерством образования, молодёжи и спорта Чешской Республики.

Провайдер аутентификации — EGI Check-in.