W&B 공개 API를 사용해 데이터를 내보내거나 가져옵니다.
이 기능을 사용하려면 Python>=3.8이 필요합니다.
W&B는 MLFlow의 실험, 실행, 아티팩트, 메트릭 및 기타 메타데이터를 포함한 데이터 가져오기를 지원합니다.
종속성을 설치합니다:
# 참고: py38 이상이 필요합니다
pip install wandb[importers]
W&B에 로그인하세요. 처음 로그인하는 경우 화면 안내에 따라 진행하세요.
기존 MLFlow 서버에서 모든 실행 가져오기:
from wandb.apis.importers.mlflow import MlflowImporter
importer = MlflowImporter(mlflow_tracking_uri="...")
runs = importer.collect_runs()
importer.import_runs(runs)
기본적으로 importer.collect_runs()는 MLflow 서버의 모든 실행을 수집합니다. 특정 부분 집합만 업로드하려면, 직접 실행 이터러블을 만들어 importer에 전달하면 됩니다.
import mlflow
from wandb.apis.importers.mlflow import MlflowRun
client = mlflow.tracking.MlflowClient(mlflow_tracking_uri)
runs: Iterable[MlflowRun] = []
for run in mlflow_client.search_runs(...):
runs.append(MlflowRun(run, client))
importer.import_runs(runs)
Databricks MLflow에서 가져오는 경우, 먼저 Databricks CLI를 설정해야 할 수 있습니다.이전 단계에서 mlflow-tracking-uri="databricks"를 설정하세요.
아티팩트 가져오기를 건너뛰려면 artifacts=False를 인수로 전달하면 됩니다:
importer.import_runs(runs, artifacts=False)
특정 W&B 엔터티와 프로젝트로 가져오려면 Namespace를 전달하세요:
from wandb.apis.importers import Namespace
importer.import_runs(runs, namespace=Namespace(entity, project))
Public API를 사용하여 W&B에 저장한 데이터를 내보내거나 업데이트할 수 있습니다. 이 API를 사용하기 전에 먼저 스크립트에서 데이터를 로깅하세요. 자세한 내용은 Quickstart를 참고하세요.
Public API 활용 사례
- 데이터 내보내기: Jupyter Notebook에서 사용자 정의 분석을 수행하기 위해 데이터프레임을 다운로드합니다. 데이터를 탐색한 후, 새 분석 실행을 생성하고 결과를 로깅하여 분석 결과를 동기화할 수 있습니다. 예:
wandb.init(job_type="analysis")
- 기존 실행 업데이트: W&B 실행과 연관되어 로깅된 데이터를 업데이트할 수 있습니다. 예를 들어, 처음에는 로깅되지 않았던 아키텍처나 하이퍼파라미터와 같은 추가 정보를 포함하도록 여러 실행의 config를 업데이트하고 싶을 수 있습니다.
사용 가능한 함수에 대한 자세한 내용은 Generated Reference Docs를 참고하세요.
API key는 머신을 W&B에 인증하는 데 사용됩니다.
API key를 생성하려면 Personal API key 또는 Service Account API key 탭을 선택해 세부 정보를 확인하세요.
Personal API key
Service account API key
사용자 ID가 소유한 개인 API key를 생성하려면:
- W&B에 로그인한 후, 사용자 프로필 아이콘을 클릭하고 User Settings를 클릭합니다.
- Create new API key를 클릭합니다.
- API key에 대한 설명용 이름을 입력합니다.
- Create를 클릭합니다.
- 표시된 API key를 즉시 복사하여 안전한 위치에 보관합니다.
서비스 계정에 속한 API key를 생성하려면:
- 팀 또는 조직 설정에서 Service Accounts 탭으로 이동합니다.
- 목록에서 해당 서비스 계정을 찾습니다.
- 작업 메뉴(
...)를 클릭한 다음 Create API key를 클릭합니다.
- API key 이름을 입력한 후 Create를 클릭합니다.
- 표시된 API key를 바로 복사해 안전한 위치에 보관합니다.
- Done을 클릭합니다.
서로 다른 환경이나 워크플로를 지원하기 위해 하나의 서비스 계정에 대해 여러 개의 API key를 생성할 수 있습니다.
전체 API key는 생성 시에만 한 번 표시됩니다. 대화상자를 닫으면 전체 API key를 다시 확인할 수 없습니다. 설정에서는 key ID(키의 앞부분)만 표시됩니다. 전체 API key를 분실한 경우 새 API key를 생성해야 합니다.
API key를 안전하게 저장하는 옵션은 API key를 안전하게 저장을 참조하세요.
API key는 W&B 계정에 대한 접근 권한을 제공하므로 비밀번호처럼 보호해야 합니다. 다음 모범 사례를 따르세요.
- Git과 같은 버전 관리 시스템에 API key를 커밋하지 마세요.
- 평문 설정 파일에 API key를 저장하지 마세요.
ps와 같은 운영 체제 명령의 출력에 노출될 수 있으므로, 명령줄 인수로 API key를 전달하지 마세요.
- 이메일, 채팅, 기타 암호화되지 않은 채널을 통해 API key를 공유하는 것을 피하세요.
- 소스 코드에 API key를 하드코딩하지 마세요.
API key가 노출된 경우, 즉시 W&B 계정에서 해당 API key를 삭제하고 support 또는 담당 AISE에 연락하세요.
코드에서 API key를 사용할 때는 환경 변수로 전달하세요:
export WANDB_API_KEY="your-api-key-here"
이 방법을 사용하면 API key를 소스 코드와 분리할 수 있고, 필요할 때 더 쉽게 교체(로테이션)할 수 있습니다.
ps와 같은 OS 명령어 출력에서 환경 변수 값이 그대로 노출될 수 있으므로, 명령어와 같은 줄에서 환경 변수를 설정하는 방식은 피하십시오:# 프로세스 관리자에서 API key가 노출될 수 있으므로 이 패턴은 피하십시오
export WANDB_API_KEY="your-api-key-here" ./my-script.sh
새로 발급되는 API key는 이전 key보다 길이가 더 깁니다. 이전 버전의 wandb 또는 weave SDK로 인증할 때 API key 길이 오류가 발생할 수 있습니다.
해결 방법: SDK를 최신 버전으로 업데이트하세요:
-
wandb SDK v0.22.3+
pip install --upgrade wandb==0.22.3
-
weave SDK v0.52.17+
pip install --upgrade weave==0.52.17
SDK를 즉시 업그레이드할 수 없다면, 임시 방편으로 WANDB_API_KEY 환경 변수를 사용해 API key를 설정하세요.
Public API를 사용하려면 자주 <entity>/<project>/<run_id> 형식의 실행 경로가 필요합니다. 앱 UI에서 실행 페이지를 열고 Overview 탭을 클릭하면 실행 경로를 확인할 수 있습니다.
완료되었거나 현재 진행 중인 실행에서 데이터를 다운로드합니다. 일반적인 사용 예로는 Jupyter 노트북에서 사용자 정의 분석을 위해 데이터프레임을 다운로드하거나, 자동화된 환경에서 사용자 정의 로직과 함께 사용하는 경우가 많습니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
실행 객체에서 가장 자주 사용하는 속성은 다음과 같습니다:
| Attribute | Meaning |
|---|
run.config | 학습 실행의 하이퍼파라미터나 데이터셋 아티팩트를 생성하는 실행을 위한 전처리 방법 등, 실행의 설정 정보를 담은 딕셔너리입니다. 실행의 입력으로 보면 됩니다. |
run.history() | 손실(loss)과 같이 모델 학습 중에 변하는 값을 저장하도록 설계된 딕셔너리들의 리스트입니다. run.log() 명령이 이 객체에 값을 추가합니다. |
run.summary | 실행 결과를 요약하는 정보를 담은 딕셔너리입니다. 정확도와 손실 같은 스칼라 값일 수도 있고, 큰 파일일 수도 있습니다. 기본적으로 run.log()는 기록된 시계열의 최종 값을 summary에 설정합니다. summary의 내용은 직접 설정할 수도 있습니다. summary는 실행의 출력으로 보면 됩니다. |
과거 실행의 데이터도 수정하거나 업데이트할 수 있습니다. 기본적으로 단일 API 객체 인스턴스는 모든 네트워크 요청을 캐시합니다. 실행 중인 스크립트에서 실시간 정보가 필요한 경우 api.flush()를 호출하여 값을 최신 상태로 갱신하십시오.
다음 코드 예제는 실행을 생성하고 일부 데이터를 로깅한 다음, 해당 실행의 속성에 접근하는 방법을 보여줍니다:
import wandb
import random
with wandb.init(project="public-api-example") as run:
n_epochs = 5
config = {"n_epochs": n_epochs}
run.config.update(config)
for n in range(run.config.get("n_epochs")):
run.log(
{"val": random.randint(0, 1000), "loss": (random.randint(0, 1000) / 1000.00)}
)
다음 섹션에서는 위의 실행 객체 속성별로 출력이 어떻게 다른지 설명합니다
run.config
{
"_runtime": 4,
"_step": 4,
"_timestamp": 1644345412,
"_wandb": {"runtime": 3},
"loss": 0.041,
"val": 525,
}
기본 history 메서드는 메트릭을 고정된 개수의 샘플로 샘플링합니다(기본값은 500이며, samples __ 인수를 사용해 변경할 수 있습니다). 대규모 실행의 모든 데이터를 내보내려면 run.scan_history() 메서드를 사용할 수 있습니다. 자세한 내용은 API Reference를 참고하세요.
DataFrame과 CSV
MongoDB 스타일
이 예제 스크립트는 Project를 지정하고, 각 실행의 이름, config, summary 통계를 CSV로 내보냅니다. <entity>와 <project>를 각각 사용자의 W&B 엔터티와 프로젝트 이름으로 바꾸세요.import pandas as pd
import wandb
api = wandb.Api()
entity, project = "<entity>", "<project>"
runs = api.runs(entity + "/" + project)
summary_list, config_list, name_list = [], [], []
for run in runs:
# .summary에는 정확도와 같은
# 메트릭의 출력 키/값이 들어 있습니다.
# 큰 파일을 생략하기 위해 ._json_dict를 호출합니다.
summary_list.append(run.summary._json_dict)
# .config에는 하이퍼파라미터가 들어 있습니다.
# _로 시작하는 특수 값을 제거합니다.
config_list.append({k: v for k, v in run.config.items() if not k.startswith("_")})
# .name은 실행의 사람이 읽을 수 있는 이름입니다.
name_list.append(run.name)
runs_df = pd.DataFrame(
{"summary": summary_list, "config": config_list, "name": name_list}
)
runs_df.to_csv("project.csv")
run.finish()
W&B API는 api.runs()로 프로젝트 내 여러 실행을 쿼리하는 방법도 제공합니다. 가장 일반적인 사용 사례는 사용자 정의 분석을 위해 실행 데이터를 내보내는 것입니다. 쿼리 인터페이스는 MongoDB에서 사용하는 것과 동일합니다.runs = api.runs(
"username/project",
{"$or": [{"config.experiment_name": "foo"}, {"config.experiment_name": "bar"}]},
)
print(f"Found {len(runs)} runs")
api.runs를 호출하면 반복 가능하고 리스트처럼 동작하는 Runs 객체를 반환합니다. 기본적으로 이 객체는 한 번에 50개의 실행을 순차적으로 필요한 만큼 로드하지만, per_page 키워드 인수로 페이지당 로드할 개수를 변경할 수 있습니다.
api.runs는 order 키워드 인수도 받습니다. 기본 정렬 순서는 -created_at입니다. 결과를 오름차순으로 정렬하려면 +created_at을 지정하세요. config나 summary 값으로도 정렬할 수 있습니다. 예를 들어 summary.val_acc 또는 config.experiment_name으로 정렬할 수 있습니다.
W&B 서버와 통신하는 동안 오류가 발생하면 wandb.CommError가 발생합니다. 원래 예외는 exc 속성을 통해 확인할 수 있습니다.
UI에서 실행을 하나 클릭한 다음, 실행 페이지에서 Overview 탭을 클릭하면 최신 git 커밋을 볼 수 있습니다. 최신 git 커밋 정보는 wandb-metadata.json 파일에도 있습니다. 공개 API를 사용하면 run.commit으로 git 해시를 가져올 수 있습니다.
wandb.init()을 호출한 이후에는 스크립트에서 랜덤 실행 ID나 사람이 읽을 수 있는 실행 이름에 다음과 같이 접근할 수 있습니다:
- 고유 실행 ID(8자 해시):
run.id
- 랜덤 실행 이름(사람이 읽을 수 있는 형태):
run.name
실행에 유용한 식별자를 어떻게 설정할지 고민 중이라면, 다음과 같이 설정할 것을 권장합니다:
- Run ID: 생성된 해시 값을 그대로 두세요. 이는 해당 프로젝트 내의 모든 실행에서 고유해야 합니다.
- Run name: 짧고 읽기 쉽고, 가능하면 고유한 이름으로 지정해서 차트에서 서로 다른 선을 쉽게 구분할 수 있게 하세요.
- Run notes: 실행에서 무엇을 하고 있는지에 대한 간단한 설명을 적기에 좋은 곳입니다.
wandb.init(notes="your notes here")와 같이 설정할 수 있습니다.
- Run tags: 실행 태그에 항목을 동적으로 기록하고, UI에서 필터를 사용해 관심 있는 실행만 테이블에 표시되도록 필터링하세요. 스크립트에서 태그를 설정한 뒤, UI의 실행 테이블과 실행 페이지의 개요 탭에서 태그를 편집할 수 있습니다. 자세한 사용 방법은 여기를 참고하세요.
matplotlib 또는 seaborn에서 시각화하기 위한 데이터 내보내기
일반적인 내보내기 패턴은 API 예제를 참고하세요. 사용자 지정 플롯에서 다운로드 버튼을 클릭하거나 확장된 실행 테이블에서 다운로드 버튼을 클릭해 브라우저에서 CSV를 다운로드할 수도 있습니다.
이 예제는 "<entity>/<project>/<run_id>"에 저장된 실행에 대해 run.log({"accuracy": acc})로 기록된 타임스탬프와 정확도를 출력합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
if run.state == "finished":
for i, row in run.history().iterrows():
print(row["_timestamp"], row["accuracy"])
MongoDB Query Language를 사용해 실행을 필터링할 수 있습니다.
runs = api.runs(
"<entity>/<project>",
{"$and": [{"created_at": {"$lt": "YYYY-MM-DDT##", "$gt": "YYYY-MM-DDT##"}}]},
)
실행에서 특정 메트릭만 가져오려면 keys 인자를 사용합니다. run.history()를 사용할 때의 기본 샘플 수는 500입니다. 특정 메트릭을 포함하지 않는 로깅된 step은 출력 데이터프레임에서 NaN으로 표시됩니다. keys 인자를 사용하면 API가 나열된 메트릭 키를 포함하는 step을 더 자주 샘플링합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
if run.state == "finished":
for i, row in run.history(keys=["accuracy"]).iterrows():
print(row["_timestamp"], row["accuracy"])
이는 run1과 run2 사이에서 서로 다른 설정 파라미터를 출력합니다.
import pandas as pd
import wandb
api = wandb.Api()
# <entity>, <project>, <run_id>를 실제 값으로 바꾸세요
run1 = api.run("<entity>/<project>/<run_id>")
run2 = api.run("<entity>/<project>/<run_id>")
df = pd.DataFrame([run1.config, run2.config]).transpose()
df.columns = [run1.name, run2.name]
print(df[df[run1.name] != df[run2.name]])
출력 결과:
c_10_sgd_0.025_0.01_long_switch base_adam_4_conv_2fc
batch_size 32 16
n_conv_layers 5 4
optimizer rmsprop adam
이 예제에서는 이전 실행의 accuracy를 0.9로 설정합니다. 또한 이전 실행의 accuracy 히스토그램을 numpy_array의 히스토그램으로 변경합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
run.summary["accuracy"] = 0.9
run.summary["accuracy_histogram"] = wandb.Histogram(numpy_array)
run.summary.update()
이 예제는 테이블에서 요약 열의 이름을 변경합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
run.summary["new_name"] = run.summary["old_name"]
del run.summary["old_name"]
run.summary.update()
열 이름 변경은 테이블에만 적용됩니다. 차트는 계속해서 메트릭의 원래 이름을 참조합니다.
다음 예제에서는 구성 설정 중 하나를 업데이트합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
run.config["key"] = updated_value
run.update()
시스템 리소스 사용량을 CSV 파일로 내보내기
아래 코드 스니펫은 시스템 리소스 사용량을 조회한 뒤 CSV 파일로 저장합니다.
import wandb
with wandb.Api().run("<entity>/<project>/<run_id>") as run:
system_metrics = run.history(stream="events")
system_metrics.to_csv("sys_metrics.csv")
history에서 데이터를 가져오면 기본적으로 500개의 포인트로 샘플링됩니다. run.scan_history()를 사용해 기록된 모든 데이터 포인트를 가져올 수 있습니다. 아래는 history에 기록된 모든 loss 데이터 포인트를 다운로드하는 예시입니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
history = run.scan_history()
losses = [row["loss"] for row in history]
history에서 페이지네이션된 데이터 가져오기
백엔드에서 메트릭을 가져오는 속도가 느리거나 API 요청이 시간 초과되는 경우, 개별 요청이 시간 초과되지 않도록 scan_history의 페이지 크기를 줄여 볼 수 있습니다. 기본 페이지 크기는 500이므로, 어떤 크기가 가장 잘 동작하는지 확인하기 위해 다양한 값으로 시도해 볼 수 있습니다:
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
run.scan_history(keys=sorted(cols), page_size=100)
프로젝트의 모든 실행 메트릭을 CSV 파일로 내보내기
이 스크립트는 프로젝트의 실행들을 불러와 실행 이름, 설정(config), 요약 통계가 포함된 데이터프레임과 실행 정보 CSV 파일을 생성합니다. <entity>와 <project>를 각각 W&B 엔터티와 프로젝트 이름으로 바꾸세요.
import pandas as pd
import wandb
api = wandb.Api()
entity, project = "<entity>", "<project>"
runs = api.runs(entity + "/" + project)
summary_list, config_list, name_list = [], [], []
for run in runs:
# .summary는 정확도와 같은 메트릭의
# 출력 키/값을 포함합니다.
# 대용량 파일을 생략하기 위해 ._json_dict를 호출합니다.
summary_list.append(run.summary._json_dict)
# .config는 하이퍼파라미터를 포함합니다.
# _로 시작하는 특수 값을 제거합니다.
config_list.append({k: v for k, v in run.config.items() if not k.startswith("_")})
# .name은 실행의 사람이 읽을 수 있는 이름입니다.
name_list.append(run.name)
runs_df = pd.DataFrame(
{"summary": summary_list, "config": config_list, "name": name_list}
)
runs_df.to_csv("project.csv")
이 코드 스니펫은 실행이 생성된 시각을 조회합니다.
import wandb
api = wandb.Api()
run = api.run("entity/project/run_id")
start_time = run.created_at
다음 코드 스니펫은 선택한 파일을 완료된 실행에 업로드합니다.
import wandb
api = wandb.Api()
run = api.run("entity/project/run_id")
run.upload_file("file_name.extension")
다음 예제는 cifar 프로젝트에서 실행 ID uxte44z7와 관련된 “model-best.h5” 파일을 찾아 로컬에 저장합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
run.file("model-best.h5").download()
특정 실행과 연결된 모든 파일을 찾아 로컬에 저장합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
for file in run.files():
file.download()
이 스니펫은 특정 스위프와 연관된 모든 실행을 가져옵니다.
import wandb
api = wandb.Api()
sweep = api.sweep("<entity>/<project>/<sweep_id>")
sweep_runs = sweep.runs
다음 코드 조각은 지정한 스윕에서 최적 실행을 가져옵니다.
import wandb
api = wandb.Api()
sweep = api.sweep("<entity>/<project>/<sweep_id>")
best_run = sweep.best_run()
best_run은 스윕 설정의 metric 매개변수로 정의된 기준에 따라, 가장 우수한 메트릭 값을 가진 실행입니다.
이 스니펫은 모델 파일을 model.h5로 저장한 실행들로 구성된 스위프에서, 검증 정확도가 가장 높은 모델 파일을 다운로드합니다.
import wandb
api = wandb.Api()
sweep = api.sweep("<entity>/<project>/<sweep_id>")
runs = sorted(sweep.runs, key=lambda run: run.summary.get("val_acc", 0), reverse=True)
val_acc = runs[0].summary.get("val_acc", 0)
print(f"Best run {runs[0].name} with {val_acc}% val accuracy")
runs[0].file("model.h5").download(replace=True)
print("Best model saved to model-best.h5")
이 스니펫은 실행에서 지정한 확장자를 가진 파일을 모두 삭제합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
extension = ".png"
files = run.files()
for file in files:
if file.name.endswith(extension):
file.delete()
이 스니펫은 실행에 대한 모든 시스템 리소스 사용량 메트릭이 포함된 데이터프레임을 생성한 다음, 이를 CSV 파일로 저장합니다.
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
system_metrics = run.history(stream="events")
system_metrics.to_csv("sys_metrics.csv")
딕셔너리를 전달하여 요약 메트릭을 업데이트할 수 있습니다.
summary.update({"key": val})
각 실행은 실행 개요 페이지에 해당 실행을 시작한 명령을 기록합니다. 이 명령을 API에서 가져오려면 다음을 실행하세요:
import wandb
api = wandb.Api()
run = api.run("<entity>/<project>/<run_id>")
meta = json.load(run.file("wandb-metadata.json").download())
program = ["python"] + [meta["program"]] + meta["args"]