시작하기¶

VSS Feature Store를 처음부터 설정하고 실행하기

사전 요구사항¶

Python 3.10 이상
uv 설치 (공식 문서)
MinIO 접근 권한

1. 프로젝트 클론¶

git clone <repository-url> mantis-ml-platform
cd mantis-ml-platform

2. 가상환경 설정¶

가상환경 생성¶

uv venv

출력:

Using Python 3.10.12
Creating virtualenv at: .venv

가상환경 활성화¶

source .venv/bin/activate

활성화 확인:

(.venv) ail@server:~/pyler/mantis-ml-platform$

3. 라이브러리 설치¶

uv pip install -e "packages/mantis_common" -e "services/svc-vss/data/feast"

출력:

Resolved 87 packages in 2.3s
Installed 87 packages in 1.8s
 + feast==0.40.1
 + milvus-lite==2.4.9
 + pandas==2.2.3
 + pyyaml==6.0.2
 ...

설치 완료

모든 필수 패키지가 정상적으로 설치되었습니다.

4. 환경 변수 설정¶

MinIO Feature Store 연결¶

export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
export AWS_ENDPOINT_URL_S3=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000
export FEAST_S3_ENDPOINT_URL=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000

환경 변수 유지

환경 변수는 현재 터미널 세션에만 유효합니다.
새 터미널을 열 때마다 다시 설정해야 합니다.

영구 설정 (선택 사항)¶

매번 설정하기 번거롭다면 ~/.bashrc 또는 ~/.zshrc에 추가:

# VSS Feature Store 환경 변수
export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
export AWS_ENDPOINT_URL_S3=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000
export FEAST_S3_ENDPOINT_URL=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000

적용:

source ~/.bashrc  # 또는 source ~/.zshrc

5. MCP 서버 실행 확인¶

MCP 서버 실행¶

python services/svc-vss/data/feast/mcp_server.py

성공 출력¶

2026-01-19 09:09:31,373 - __main__ - INFO - Starting VSS Feature Store MCP Server...
2026-01-19 09:09:31,378 - __main__ - INFO - Server initialized, waiting for requests...

MCP 서버 실행 성공

서버가 정상적으로 시작되었습니다!
Ctrl+C로 종료할 수 있습니다.

실행 실패 시 확인 사항¶

오류: ModuleNotFoundError

해결: 가상환경 활성화 확인
source .venv/bin/activate

오류: MinIO 연결 실패

해결: 환경 변수 확인
echo $AWS_ENDPOINT_URL_S3

오류: No such file or directory

해결: 경로 확인
pwd  # /home/ail/pyler/mantis-ml-platform인지 확인

6. 기능 테스트¶

테스트 실행¶

python services/svc-vss/data/feast/test_feast.py

7. 빠른 시작: Python 스크립트¶

가상환경과 환경 변수 설정 후 다음 코드를 실행해보세요:

import api
from constants import FEATURE_VIEW_VIDEO_DESCRIPTION

# 0) Target Feature View
fv = FEATURE_VIEW_VIDEO_DESCRIPTION

# 1) Register New Captions (required step)
result = api.register_captions(
    feature_view=fv,
    uuid='yt-video-001',
    mp4_source='https://www.youtube.com/watch?v=wjZofJX0v4M',
    model='gpt-4o',
    segments=[
        {'index': 0, 'start': 0.0,  'end': 10.0, 'text': 'Intro segment...'},
        {'index': 1, 'start': 10.0, 'end': 20.0, 'text': 'Content segment...'},
    ],
)

# 2) Retrieve Captions (verify registration result)
captions = api.get_captions(
    feature_view=fv,
    uuid='yt-video-001',
    model='gpt-4o',
)

# 3) Search Metadata (optional)
metadata = api.search_metadata(
    feature_view=fv,
    models=['gpt-4o'],
)

print(f"Registered {len(captions)} segments")
print(f"Metadata count: {len(metadata)}")

Feature View 종류¶

from constants import (
    FEATURE_VIEW_VIDEO,               # 비디오 정보
    FEATURE_VIEW_VIDEO_DESCRIPTION,    # 비디오 설명
    FEATURE_VIEW_AUDIO_TRANSCRIPT,     # 오디오 전사
    FEATURE_VIEW_CAPTION_SUMMARY,      # 캡션 요약 
)

문제 해결¶

가상환경이 활성화되지 않음¶

# 현재 디렉토리 확인
pwd  # /home/ail/pyler/mantis-ml-platform

# 가상환경 재생성
rm -rf .venv
uv venv
source .venv/bin/activate

환경 변수가 설정되지 않음¶

# 환경 변수 확인
env | grep -E "AWS|FEAST"

# 출력이 없으면 다시 설정
export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
export AWS_ENDPOINT_URL_S3=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000
export FEAST_S3_ENDPOINT_URL=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000

MinIO 연결 실패¶

# MinIO 엔드포인트 접근 확인
curl http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000

# 또는 ping 테스트
ping andrew-minio-2025-12-03-svc.dev.idc.k8s

패키지 설치 오류¶

# pip 업그레이드
uv pip install --upgrade pip

# 개별 재설치
uv pip install -e "packages/mantis_common" --force-reinstall
uv pip install -e "services/svc-vss/data/feast" --force-reinstall

설치 체크리스트¶

완료한 항목을 체크하세요:

[ ] Python 3.10 이상 설치
[ ] uv 설치
[ ] 프로젝트 클론
[ ] 가상환경 생성 및 활성화
[ ] 라이브러리 설치
[ ] 환경 변수 설정
[ ] MCP 서버 실행 확인
[ ] 기능 테스트 통과

다음 단계¶

MCP 연동¶

Claude Code 또는 Cursor에서 MCP 서버를 사용하려면:

👉 MCP 활용 가이드

API 사용법¶

Python 코드에서 VSS Feature Store를 사용하려면:

👉 API 레퍼런스

Config 설정¶

캡션 생성 설정을 커스터마이징하려면:

👉 Configuration

아키텍처 이해¶

시스템 구조를 자세히 알아보려면:

👉 Architecture

요약¶

# 1. 가상환경 설정
uv venv
source .venv/bin/activate

# 2. 라이브러리 설치
uv pip install -e "packages/mantis_common" -e "services/svc-vss/data/feast"

# 3. 환경 변수 설정
export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
export AWS_ENDPOINT_URL_S3=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000
export FEAST_S3_ENDPOINT_URL=http://andrew-minio-2025-12-03-svc.dev.idc.k8s:9000

# 4. MCP 서버 실행 (확인)
python services/svc-vss/data/feast/mcp_server.py

# 5. 기능 테스트
python services/svc-vss/data/feast/test_feast.py

설치 완료! 🎉