Contexta 시작하기
이 가이드는 Contexta를 설치하고, 로컬 .contexta/ 워크스페이스에서 첫 실행 결과를 수집한 뒤, 실행 중 계산된 메트릭이 어떤 기록으로 저장되는지 확인하는 과정을 안내합니다.
배울 내용
이 문서를 따라가면 다음 내용을 확인할 수 있습니다.
- Contexta를 설치하는 방법
- 로컬
.contexta/워크스페이스를 생성하는 방법 - 워크플로 실행이 메트릭 기록을 남기는 방식
- 실행 후 확인해야 할 파일과 주요 필드
전제 조건
- Python
>=3.14 uv가 설치된 Python 환경.contexta/디렉터리를 만들 수 있는 작업 디렉터리
설치
uv add "contexta[sklearn]"
이 예제는 scikit-learn 연동을 사용하므로 sklearn extra를 함께 설치합니다.
첫 실행 캡처하기
아래의 예제는 작은 학습 워크플로를 실행하고, 평가 단계에서 계산된 r2 메트릭을 Contexta에 기록합니다.
from sklearn.datasets import load_diabetes
from sklearn.linear_model import LinearRegression
from sklearn.metrics import r2_score
from sklearn.model_selection import train_test_split
from contexta import Contexta
features, targets = load_diabetes(return_X_y=True)
train_x, test_x, train_y, test_y = train_test_split(
features, targets, test_size=0.2, random_state=42
)
model = LinearRegression()
ctx = Contexta(workspace=".contexta", config={"project_name": "getting-started"})
with ctx.run("training") as run:
with run.stage("train"):
model.fit(train_x, train_y)
with run.stage("evaluate") as stage:
score = r2_score(test_y, model.predict(test_x))
stage.metric("r2", score, unit="ratio")
print(f"Captured run: {run.ref}")
print(f"Measured r2: {score:.3f}")
코드를 contexta_example.py로 저장한 뒤, Contexta가 설치된 환경에서 실행하세요.
uv run contexta_example.py
실행 결과 확인하기
실행이 끝나면 터미널에 다음과 같은 출력이 표시됩니다.
Captured run: run:getting-started.training
Measured r2: 0.453
이 출력은 getting-started 프로젝트의 training 실행이 수집되었고, 평가 단계에서 r2 메트릭이 계산되었다는 뜻입니다.
Contexta는 이 실행에서 생성된 기록을 로컬 워크스페이스 아래에 저장합니다.
.contexta/
cache/capture/record.jsonl
record.jsonl은 JSON Lines 형식의 파일입니다. 한 줄이 하나의 기록이며, 이 예제에서 생성된 메트릭 기록은 다음과 같은 정보를 포함합니다.
{
"captured_at": "2026-05-25T10:26:03.502991Z",
"payload": {
"envelope": {
"record_type": "metric",
"run_ref": "run:getting-started.training",
"stage_execution_ref": "stage:getting-started.training.evaluate",
"completeness_marker": "complete",
"degradation_marker": "none"
},
"payload": {
"metric_key": "r2",
"value": 0.4526027629719198,
"unit": "ratio"
}
},
"payload_type": "MetricRecord",
"sink_name": "local-jsonl"
}
이 기록은 다음처럼 읽을 수 있습니다.
| 필드 | 의미 |
|---|---|
payload_type: "MetricRecord" | 이 항목이 로그 메시지나 파일이 아니라 측정된 메트릭 기록임을 나타냅니다. |
metric_key: "r2" | 기록된 메트릭의 이름입니다. |
value: 0.4526... | 이번 실행에서 실제로 측정된 값입니다. |
run_ref | 이 메트릭이 getting-started 프로젝트의 training 실행에 속한다는 뜻입니다. |
stage_execution_ref | 이 메트릭이 학습 단계가 아니라 evaluate 단계에서 생성되었다는 뜻입니다. |
captured_at | Contexta가 이 기록을 저장한 시각입니다. |
completeness_marker | 기록이 완전한 상태로 저장되었는지 나타냅니다. |
degradation_marker | 기록에 기능 저하 상태가 표시되었는지 나타냅니다. |
sink_name: "local-jsonl" | 이 기록이 로컬 JSON Lines 파일에 저장되었음을 나타냅니다. |
즉, Contexta는 단순히 0.453이라는 숫자만 저장하지 않습니다.
그 값이 어떤 메트릭인지, 어떤 실행과 단계에서 만들어졌는지, 언제 저장되었는지, 그리고 기록이 완전한 상태인지까지 함께 남깁니다.
핵심 개념
Contexta가 저장하는 정보는 크게 세 가지로 나눌 수 있습니다.
| 구분 | 저장되는 내용 |
|---|---|
| Metadata | 프로젝트, 실행, 단계, 환경, 배포, 배치, 샘플 |
| Records | 메트릭, 구조화된 이벤트, 스팬, 불완전한 상태 |
| Artifacts | 모델, 체크포인트, 프롬프트, 평가 파일, 리포트 |
Metadata는 실행의 맥락을 설명합니다.
Records는 실행 중 발생한 Observability 데이터를 저장합니다.
Artifacts는 실행 결과로 생성되거나 나중에 검토해야 하는 파일을 가리킵니다.