MATLAB 통합

MATLAB 데이터 사이언스, 데이터 엔지니어링, 머신러닝 워크플로에서 lakeFS를 MATLAB과 통합하면 데이터 버전 관리를 할 수 있어요. lakeFS 네이티브 MATLAB 함수로 저장소·브랜치·커밋·태그를 다루고, lakeFS Mount로 경로를 로컬처럼 마운트할 수도 있어요.

출처: 문서

본문

MATLAB의 데이터 사이언스, 데이터 엔지니어링, 머신러닝 워크플로에서 데이터 버전 관리를 위해 lakeFS를 MATLAB과 통합할 수 있어요.

개요

lakeFS MATLAB 통합은 lakeFS 저장소와 상호작용하는 네이티브 MATLAB 함수를 제공해요. 할 수 있는 일은:

• 데이터 버전 관리: 실험마다 데이터셋, 모델, 결과를 추적

• 재현 가능한 연구: 커밋 ID로 코드를 특정 데이터 버전에 연결

• 격리된 실험: 데이터 복제 없이 병렬 실험용 브랜치 생성

• 직접 데이터 접근: lakeFS Mount로 lakeFS 저장소를 로컬 디렉터처럼 마운트

이 통합은 두 개의 MATLAB 헬퍼 클래스를 사용해요:

• lakefs.m: lakeFS 핵심 작업(브랜치, 커밋, 태그, 메타데이터)
• everest.m: 직접 데이터 접근을 위한 파일시스템 마운트

필수 조건

MATLAB에서 lakeFS를 사용하기 전에 다음이 준비되어 있어야 해요:

• lakeFS 서버: 동작 중인 인스턴스(로컬 또는 클라우드)

• 퀵스타트 가이드

• 클라우드 설정

• lakectl CLI: 설치 및 구성 완료

• lakectl 설치

• ~/.lakectl.yaml 설정 파일

• lakeFS Mount (선택, 마운트용): 파일시스템 인터페이스

• lakeFS Mount 문서

• 설치: brew install treeverse/brew/everest (macOS)

• MATLAB: R2023a 이상 권장

설치

lakeFS 연결 설정

템플릿을 복사하고 편집해 lakeFS 설정을 만드세요:

lakefs_template.m:

classdef lakefs_template
    % LAKEFS_TEMPLATE - Configuration template for lakeFS connection
    %
    % SETUP:
    % 1. Copy this file to lakefs.m in your project directory
    % 2. Fill in your credentials below
    % 3. Keep lakefs.m out of version control (.gitignore)

    properties(Constant)
        % === LOCAL CONFIGURATION ===
        LOCAL_ENDPOINT = 'http://localhost:8000'
        LOCAL_ACCESS_KEY = 'YOUR_ACCESS_KEY_HERE'
        LOCAL_SECRET_KEY = 'YOUR_SECRET_KEY_HERE'

        % === CLOUD CONFIGURATION ===
        CLOUD_ENDPOINT = 'https://your-org.us-east-1.lakefscloud.io'
        CLOUD_ACCESS_KEY = 'YOUR_CLOUD_ACCESS_KEY_HERE'
        CLOUD_SECRET_KEY = 'YOUR_CLOUD_SECRET_KEY_HERE'

        % === CURRENT CONFIGURATION (will be set by configure()) ===
        % These will be populated when you call lakefs.configure()
    end

    properties(Access=private)
        current_endpoint
        current_access_key
        current_secret_key
    end

    methods(Static)
        function configure(environment)
            % CONFIGURE - Set active lakeFS environment
            %
            % Syntax:
            %   lakefs.configure('local')   % Use local lakeFS
            %   lakefs.configure('cloud')   % Use cloud lakeFS
        end
    end
end

설정 단계:

• lakefs_template.m을 lakefs.m으로 복사하세요

• lakefs.m의 자격 증명을 편집하세요

• 자격 증명이 노출되지 않도록 lakefs.m을 .gitignore에 추가하세요

• 스크립트에서 활성 환경을 지정하세요:

% Use local lakeFS instance
lakefs.configure('local');

% Or use cloud lakeFS instance
lakefs.configure('cloud');

기본 사용법

저장소 작업

브랜치 목록:

% List all branches in a repository
branches = lakefs.list_branches('my-repo');
disp(branches.branch);

태그 목록:

% List all tags
tags = lakefs.list_tags('my-repo');
disp(tags.tag);

커밋 히스토리 보기:

% Get commit log for a branch
commits = lakefs.log('my-repo', 'main', 'amount', 5);
for i = 1:height(commits)
    fprintf('%s: %s\n', commits.id{i}(1:12), commits.message{i});
end

브랜치 관리

브랜치 만들기:

% Create experiment branch from main
lakefs.create_branch('my-repo', 'experiment-1', 'main');

브랜치 비교:

% Show differences between branches
diff = lakefs.diff('my-repo', 'main', 'experiment-1');
fprintf('Changed objects: %d\n', height(diff));

데이터 작업

데이터 업로드:

% Upload local file to lakeFS branch
lakefs.upload('my-repo', 'experiment-1', ...
    'data/results.mat', ...      % Destination in lakeFS
    'local/output/results.mat');  % Local source file

데이터 다운로드:

% Download file from lakeFS
lakefs.download('my-repo', 'main', ...
    'models/trained_model.mat', ...  % Source in lakeFS
    'local/models/model.mat');        % Local destination

변경 사항 커밋:

% Commit with metadata
metadata = struct();
metadata.accuracy = '0.945';
metadata.training_time = '120.5';
metadata.dataset = 'v1.2';

lakefs.commit('my-repo', 'experiment-1', ...
    'Trained model with improved accuracy', ...
    'metadata', metadata);

마운트(lakeFS Mount)

파일시스템에 직접 접근하려면 lakeFS Mount로 lakeFS 경로를 마운트하세요:

% Mount a branch
everest.mount('lakefs://my-repo/main/', 'local_data/');

% Read files directly
data = load('local_data/results.mat');

% Unmount when done
everest.umount('local_data/');

참고: 마운트를 사용하면 명시적인 업로드/다운로드 없이 표준 MATLAB 파일 입출력 함수로 lakeFS 데이터를 다룰 수 있어요.

핵심 API 레퍼런스

lakefs.m - 저장소 작업

설정

lakefs.configure(environment)

설명: 활성 lakeFS 환경 설정

파라미터:

• environment (string): 'local' 또는 'cloud'

브랜치 작업

branches = lakefs.list_branches(repo)

설명: 저장소의 모든 브랜치 목록

파라미터:

• repo (string): 저장소 이름

반환: 브랜치 이름과 커밋 ID가 담긴 테이블

lakefs.create_branch(repo, branch_name, source_ref)

설명: 소스 참조에서 새 브랜치 생성

파라미터:

• repo (string): 저장소 이름
• branch_name (string): 새 브랜치 이름
• source_ref (string): 소스 브랜치 또는 커밋 ID

커밋 작업

commits = lakefs.log(repo, ref, varargin)

설명: 커밋 히스토리 조회

파라미터:

• repo (string): 저장소 이름
• ref (string): 브랜치 또는 커밋 참조
• 선택: 'amount', N - 반환할 커밋 수 제한

반환: 커밋 ID, 메시지, 타임스탬프, 메타데이터가 담긴 테이블

lakefs.commit(repo, branch, message, varargin)

설명: 브랜치에 변경 사항 커밋

파라미터:

• repo (string): 저장소 이름
• branch (string): 브랜치 이름
• message (string): 커밋 메시지
• 선택: 'metadata', struct - 커밋에 메타데이터 첨부

데이터 전송

lakefs.upload(repo, branch, lakefs_path, local_path)

설명: 로컬 파일을 lakeFS로 업로드

파라미터:

• repo (string): 저장소 이름
• branch (string): 브랜치 이름
• lakefs_path (string): lakeFS 안의 대상 경로
• local_path (string): 로컬 시스템의 소스 파일

lakefs.download(repo, ref, lakefs_path, local_path)

설명: lakeFS에서 파일 다운로드

파라미터:

• repo (string): 저장소 이름
• ref (string): 브랜치, 태그 또는 커밋 ID
• lakefs_path (string): lakeFS 안의 소스 경로
• local_path (string): 로컬 시스템의 대상 경로

비교

diff = lakefs.diff(repo, left_ref, right_ref)

설명: 두 참조 비교

파라미터:

• repo (string): 저장소 이름
• left_ref (string): 첫 번째 참조(브랜치/태그/커밋)
• right_ref (string): 두 번째 참조

반환: 변경·추가·삭제된 오브젝트를 보여주는 테이블

태그

tags = lakefs.list_tags(repo)

설명: 모든 태그 목록

파라미터:

• repo (string): 저장소 이름

반환: 태그 이름과 커밋 ID가 담긴 테이블

everest.m - 파일시스템 작업

마운트

everest.mount(lakefs_uri, mount_dir, varargin)

설명: lakeFS 경로를 로컬 디렉터로 마운트

파라미터:

• lakefs_uri (string): 전체 lakeFS URI (예: 'lakefs://repo/branch/path/')
• mount_dir (string): 로컬 마운트 지점
• 선택: 'presign', true - presigned URL 사용(기본값: true)

everest.umount(mount_dir)

설명: 디렉터 언마운트

파라미터:

• mount_dir (string): 언마운트할 로컬 마운트 지점

mounts = everest.list_mounts()

설명: 활성 마운트 보기

반환: 현재 마운트된 디렉터의 셀 배열

everest.verify()

설명: lakeFS Mount 설치와 접근 가능 여부 확인

예제 워크플로

실험 추적

% Configure environment
lakefs.configure('local');

% Create experiment branch
lakefs.create_branch('ml-project', 'experiment-3', 'main');

% Train model (your code here)
model = train_model(data);
save('outputs/model_v3.mat', 'model');

% Upload results
lakefs.upload('ml-project', 'experiment-3', ...
    'models/model_v3.mat', 'outputs/model_v3.mat');

% Commit with metrics
metadata = struct();
metadata.accuracy = num2str(model.accuracy);
metadata.loss = num2str(model.loss);
metadata.epochs = num2str(model.epochs);

lakefs.commit('ml-project', 'experiment-3', ...
    'Experiment 3: Increased learning rate', ...
    'metadata', metadata);

% View experiment history
commits = lakefs.log('ml-project', 'experiment-3', 'amount', 1);
fprintf('Experiment accuracy: %s\n', commits.metadata{1}.accuracy);

데이터 버전 비교

% Compare two data versions
diff = lakefs.diff('research-data', 'v1.0', 'v2.0');

% Show what changed
fprintf('Data changes between versions:\n');
for i = 1:height(diff)
    fprintf('  %s: %s\n', diff.type{i}, diff.path{i});
end

% Download specific version
lakefs.download('research-data', 'v1.0', ...
    'datasets/training_data.mat', 'data/v1_training.mat');

lakefs.download('research-data', 'v2.0', ...
    'datasets/training_data.mat', 'data/v2_training.mat');

% Compare in MATLAB
v1 = load('data/v1_training.mat');
v2 = load('data/v2_training.mat');
fprintf('V1 samples: %d\n', size(v1.data, 1));
fprintf('V2 samples: %d\n', size(v2.data, 1));

재현 가능한 분석

% Record exact data version used
commits = lakefs.log('sensor-data', 'main', 'amount', 1);
data_commit = commits.id{1};

% Mount data
everest.mount('lakefs://sensor-data/main/', 'analysis_data/');

% Run analysis
data = load('analysis_data/sensor_readings.mat');
results = analyze_sensors(data);

% Unmount
everest.umount('analysis_data/');

% Store results with data lineage
lakefs.upload('sensor-data', 'analysis-results', ...
    'results/analysis_output.mat', 'results/output.mat');

metadata = struct();
metadata.data_commit = data_commit;  % Track source data version
metadata.analysis_date = datestr(now);
metadata.mean_value = num2str(mean(results.values));

lakefs.commit('sensor-data', 'analysis-results', ...
    'Sensor analysis results', 'metadata', metadata);

% Later: Reproduce exact analysis
fprintf('Analysis used data from commit: %s\n', data_commit);

고급 주제

환경 전환

같은 세션에서 로컬과 클라우드 환경을 전환할 수 있어요:

% Work with local instance
lakefs.configure('local');
local_branches = lakefs.list_branches('dev-repo');

% Switch to cloud
lakefs.configure('cloud');
cloud_branches = lakefs.list_branches('prod-repo');

메타데이터 모범 사례

최대한 가치가 있도록 메타데이터를 구성하세요:

metadata = struct();

% Experiment details
metadata.experiment_id = 'exp-2024-001';
metadata.hypothesis = 'increased_batch_size';

% Quantitative results
metadata.accuracy = sprintf('%.4f', results.accuracy);
metadata.training_time_sec = num2str(results.time);

% Computational environment
metadata.matlab_version = version;
metadata.gpu_used = 'NVIDIA RTX 4090';

% Data lineage
metadata.training_data_commit = training_commit_id;
metadata.validation_data_commit = val_commit_id;

lakefs.commit(repo, branch, message, 'metadata', metadata);

대용량 데이터셋 다루기

대용량 데이터셋은 업로드/다운로드보다 마운트를 권장해요:

% Mount for direct access (no copying)
everest.mount('lakefs://large-data/main/datasets/', 'data/');

% Process data in chunks
datastore = imageDatastore('data/images', ...
    IncludeSubfolders=true, ...
    LabelSource="foldernames");

% Process without loading all into memory
while hasdata(datastore)
    img = read(datastore);
    process_image(img);
end

% Unmount when done
everest.umount('data/');

문제 해결

연결 문제

오류: lakeFS에 연결할 수 없음

설정을 확인하세요:

% Check lakectl is configured
!lakectl repo list

% Test lakefs.m configuration
lakefs.configure('local');  % or 'cloud'

마운트 문제

오류: 마운트 실패

lakeFS Mount 설치를 확인하세요:

everest.verify();

% Check if lakeFS Mount is in PATH
!which everest

마운트에 파일이 안 보임

마운트가 완료되길 기다리세요:

everest.mount('lakefs://repo/branch/', 'data/');
pause(2);  % Give mount time to initialize
dir('data/')  % Should now show files

경로 문제

오류: lakeFS에서 파일을 찾을 수 없음

경로 형식을 확인하세요:

% Correct: Relative path from branch root
lakefs.upload('repo', 'branch', 'data/file.mat', 'local.mat');

% Incorrect: Leading slash
lakefs.upload('repo', 'branch', '/data/file.mat', 'local.mat');

추가 자료

• lakeFS 문서

• lakectl CLI 레퍼런스

• lakeFS Mount 레퍼런스

• lakeFS Samples 저장소

• lakeFS 커뮤니티 Slack

버전 호환성

구성 요소	최소 버전	권장
MATLAB	R2020a	R2023a+
lakeFS	0.100.0	최신
lakectl	0.100.0	최신
lakeFS Mount	0.1.0	최신

참고: MATLAB R2023a에서 함수 인자에 name=value 문법이 도입됐어요. 이전 버전은 'name', value 쌍을 사용해요. 헬퍼 파일은 두 문법 모두와 호환돼요.

더 알아보기 (Learn more)

공식 문서의 자세한 내용은 https://docs.lakefs.io/reference/matlab/에서 확인하실 수 있어요.