🔭 EOSC Data Commons 검색 서버

EOSC Data Commons 프로젝트 MatchMaker 서비스를 위한 서버로, 오픈 액세스 데이터셋에 대한 자연어 검색을 제공합니다. HTTP POST 엔드포인트를 노출하며, Model Context Protocol (MCP)을 지원하여 사용자가 대규모 언어 모델 기반 검색을 통해 데이터셋과 도구를 발견할 수 있도록 돕습니다.

🧩 엔드포인트

HTTP API는 2개의 주요 엔드포인트로 구성됩니다:

• /mcp: MCP 서버로, EOSC Data Commons OpenSearch 서비스를 사용하여 사용자 질문에 답변하기 위한 관련 데이터를 검색합니다.

  • Streamable HTTP 전송 사용

  • 사용 가능한 도구:

    • 데이터셋 검색

    • 데이터셋 내 파일의 메타데이터 가져오기 (이름, 설명, 파일 유형)

    • 도구 검색

    • 데이터셋 또는 도구와 관련된 인용 검색

• /chat: HTTP POST 엔드포인트 (JSON)로, LLM 제공자를 통해 MCP 서버 도구와 채팅합니다 (API 키는 배포 시 환경 변수로 제공됨).

  • AG-UI 프로토콜을 준수하는 Server-Sent Events (SSE) 응답 스트리밍.

[!TIP]

pip 패키지를 통해 MCP 서버로만 사용할 수도 있습니다.

Related MCP server: Datos.gob.es-MCP

🔌 MCP 서버에 연결

이 시스템은 STDIO 또는 Streamable HTTP 전송을 사용하여 MCP 서버로 직접 사용할 수 있습니다.

[!WARNING]

MCP 서버가 작동하려면 사전 인덱싱된 OpenSearch 인스턴스에 대한 액세스 권한이 필요합니다.

클라이언트의 지침을 따르고 공개 서버의 /mcp URL을 사용하세요: https://matchmaker.eosc-data-commons.eu/api/search/mcp

VSCode GitHub Copilot에 새 MCP 서버를 추가하려면:

• 명령 팔레트 열기 (ctrl+shift+p 또는 cmd+shift+p)

• MCP: Add Server... 검색

• HTTP 선택 후 MCP 서버 URL 제공: https://matchmaker.eosc-data-commons.eu/api/search/mcp

VSCode mcp.json은 다음과 같아야 합니다:

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

🛠️ 개발

[!IMPORTANT]

요구 사항:

• uv, 스크립트 및 가상 환경을 쉽게 관리하기 위함

• docker, 데이터베이스 및 OpenSearch 서비스 배포를 위함

• LLM 제공자용 API 키: e-infra CZ, Mistral.ai, 또는 OpenRouter

📥 개발 종속성 설치

uv sync --all-extras

pre-commit 훅 설치:

uv run --all-extras pre-commit install

LLM 제공자 API 키와 선택적으로 기타 구성을 포함한 keys.env 파일 생성:

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

db를 초기화하려면 metadata-warehouse 저장소에서 실행:

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

[!IMPORTANT]

공개적으로 사용 가능한 환경에서는 app 사용자 비밀번호를 업데이트해야 합니다:

ALTER USER app WITH PASSWORD 'newpassword';

db 재설정:

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

⚡️ 개발 서버 시작

실행 중인 OpenSearch 인스턴스를 가리키는 MCP 엔드포인트 http://localhost:8000/mcp와 함께 http://localhost:8000에서 개발 서버를 시작합니다:

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 프론트엔드를 별도로 개발 모드로 배포할 수 있습니다:

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로 배포

API 키가 포함된 keys.env 파일 생성 (전체 예시는 위 참조):

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를 쿼리하는 데 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에서 서버를 시작하고 (개발 서버 시작 섹션 참조) PostgreSQL을 시작해야 합니다.

uv run pytest

벤치마크 실행 (일련의 검색 쿼리 성공 확인):

uv run tests/benchmark.py

LLM 탈옥 테스트를 garak로 실행:

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

스트레스 테스트 실행 (API의 20개 동시 사용):

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

🔧 유지 관리

db의 데이터셋에 대한 통계를 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 Masaryk University가 운영하는 서비스입니다.

컴퓨팅 리소스는 체코 교육부, 청소년 및 체육부가 지원하는 e-INFRA CZ 프로젝트(ID:90254)에서 제공되었습니다.

인증 제공자는 EGI Check-in입니다.